Inherits from NSObject
Declared in CRRouter.h

Overview

CRRouter provides Criollo’s routing capabilities. It is the base class for CRServer, CRRouteController and CRViewController. It is not meant to be instantiated directly, but rather it’s methods should be called through one of the decendant classes mentioned above. Instances of these classes are called routers.

Routing

In Criollo, a route consists of an ordered list of CRRouteBlock objects, associated with path and an HTTP request method. Blocks are added directly to a route by calling add:block:recursive:method:, one of its overloadds or any of the convenience methods provided, such as get:block:, post:block:recursive:, etc.

Important: blocks are executed in the order in which they are added.

The final parameter of a CRRouteBlock is a dispatch_block_t object that must be called in order to signal the router that the work of the cuurent block has finished its job and execution can proceed to the next block.

Path specification

When adding a route, paths can be specified in three ways:

  • Fixed string (ex. /api). This will match the string exactly.

  • Placeholders (ex. /posts/:pid). The next path component after “/posts”, will be matched and added to request.query under the pid key.

  • Regex patterns (ex. /[0-9]{4}/[0-9]{1,2}/[a-zA-Z0-9-]+). When the three patterns are matched, they are added to request.query, under the keys "0", "1" and "2" respectively.

Important: Regex patterns are parsed per path component.

The string that is used to define a path is called a path specification (pathspec).

Block, Route Controllers and View Controllers

In real-life, the functionality required by a specific route cannot be simply implemented by a single block. Not in a readable way anyway. Come in CRRouteController and CRViewController. These two classes are used to provide a more apropriate wrapper for routes that share a common logic.

CRRouteController and CRViewController instances are added to the router by calling add:controller:recursive:method: and add:viewController:withNibName:bundle:recursive:method: or their overloads.

Both CRRouteController and CRViewController expose a CRRouteBlock as their workhorse.

Serving Static Files

CRRouter also provides methods for serving files stored in a directory on disk (mount:directoryAtPath:options:) or for serving a file directly at a specific path (mount:fileAtPath:options:fileName:contentType:contentDisposition:).

Tasks

Other Methods

Adding a Block

Adding a Controller

Adding a View Controller

Serving Directories

Serving Files

Properties

notFoundBlock

@property (nonatomic, copy) CRRouteBlock notFoundBlock
Discussion

The block called when there are no routes for the requested pathspec

Declared In

CRRouter.h

Class Methods

errorHandlingBlockWithStatus:error:

+ (CRRouteBlock)errorHandlingBlockWithStatus:(NSUInteger)statusCode error:(NSError *_Nullable)error

Instance Methods

add:

- (void)add:(CRRouteBlock)block
Discussion

Adds a block to all pathspecs and all HTTP methods.

Parameters

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

add:block:

- (void)add:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for all HTTP methods, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

add:block:recursive:method:

- (void)add:(NSString *_Nullable)path block:(CRRouteBlock)block recursive:(BOOL)recursive method:(CRHTTPMethod)method
Discussion

Adds a block to a pathspec and HTTP method.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

recursive

Specifies wether the path spec should be matched exactly or if it should be treated aa a prefix.

method

The HTTP request method

Declared In

CRRouter.h

add:controller:

- (void)add:(NSString *)path controller:(__unsafe_unretained Class)controllerClass
Discussion

Adds a controller to a pathspec, for all HTTP methods, recursively.

Parameters

path

The path specification.

controllerClass

The class name of the controller to be used.

Declared In

CRRouter.h

add:controller:recursive:method:

- (void)add:(NSString *)path controller:(__unsafe_unretained Class)controllerClass recursive:(BOOL)recursive method:(CRHTTPMethod)method
Discussion

Adds a controller to a pathspec and HTTP method.

Parameters

path

The path specification.

controllerClass

The class name of the controller to be used.

recursive

Specifies wether the path spec should be matched exactly or if it should be treated aa a prefix.

method

The HTTP request method

Declared In

CRRouter.h

add:viewController:withNibName:bundle:

- (void)add:(NSString *)path viewController:(__unsafe_unretained Class)viewControllerClass withNibName:(NSString *_Nullable)nibNameOrNil bundle:(NSBundle *_Nullable)nibBundleOrNil
Discussion

Adds a view controller to a pathspec, for all HTTP methods, recursively.

Parameters

path

The path specification.

viewControllerClass

The class name of the controller to be used.

nibNameOrNil

The name of the nib file to associate with the view controller.

nibBundleOrNil

he bundle in which to search for the nib file.

Declared In

CRRouter.h

add:viewController:withNibName:bundle:recursive:method:

- (void)add:(NSString *)path viewController:(__unsafe_unretained Class)viewControllerClass withNibName:(NSString *_Nullable)nibNameOrNil bundle:(NSBundle *_Nullable)nibBundleOrNil recursive:(BOOL)recursive method:(CRHTTPMethod)method
Discussion

Adds a view controller to a pathspec and HTTP method.

Parameters

path

The path specification.

viewControllerClass

The class name of the controller to be used.

nibNameOrNil

The name of the nib file to associate with the view controller.

nibBundleOrNil

he bundle in which to search for the nib file.

recursive

Specifies wether the path spec should be matched exactly or if it should be treated aa a prefix.

method

The HTTP request method

Declared In

CRRouter.h

delete:block:

- (void)delete:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for the DELETE method, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

get:block:

- (void)get:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for the GET method, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

head:block:

- (void)head:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for the HEAD method, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

mount:directoryAtPath:

- (void)mount:(NSString *)path directoryAtPath:(NSString *)directoryPath
Discussion

Exposes the contents of a directory at a path specification.

Parameters

path

The path specification.

directoryPath

The filesystem path of the directory.

Declared In

CRRouter.h

mount:directoryAtPath:options:

- (void)mount:(NSString *)path directoryAtPath:(NSString *)directoryPath options:(CRStaticDirectoryServingOptions)options
Discussion

Exposes the contents of a directory at a path specification.

Parameters

path

The path specification.

directoryPath

The filesystem path of the directory.

options

A bitwise-or'ed list of CRStaticDirectoryServingOptions.

Declared In

CRRouter.h

mount:fileAtPath:

- (void)mount:(NSString *)path fileAtPath:(NSString *)filePath
Discussion

Exposes the contents of a file at a path specification.

Parameters

path

The path specification.

filePath

The filesystem path of the file.

Declared In

CRRouter.h

mount:fileAtPath:options:fileName:contentType:contentDisposition:

- (void)mount:(NSString *)path fileAtPath:(NSString *)filePath options:(CRStaticFileServingOptions)options fileName:(NSString *_Nullable)fileName contentType:(NSString *_Nullable)contentType contentDisposition:(CRStaticFileContentDisposition)contentDisposition
Discussion

Exposes the contents of a file at a path specification.

Parameters

path

The path specification.

filePath

The filesystem path of the file.

options

A bitwise-or'ed list of CRStaticFileServingOptions.

fileName

The filename that will be exposed to the client.

contentType

The value of the Content-type HTTP header.

contentDisposition

The CRStaticFileContentDisposition used to build the Content-disposition HTTP header.

Declared In

CRRouter.h

options:block:

- (void)options:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for the OPTIONS method, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

post:block:

- (void)post:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for the POST method, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h

put:block:

- (void)put:(NSString *_Nullable)path block:(CRRouteBlock)block
Discussion

Adds a block to a pathspec, for the PUT method, non-recursively.

Parameters

path

The path specification.

block

The CRRouteBlock to be executed.

Declared In

CRRouter.h