trails
v2.3.1

View Source trails (trails v2.3.1)

Trails main interface. Use the functions provided in this module to inteact with trails.

Link to this section Summary

Types

metadata/1
method/0
route_match/0
route_path/0
route_rule/0
trail/0
trails/0

Functions

all()
Retrieves all stored trails.
all(HostMatch)
Retrieves all stored trails for the given HostMatch
all(Server, HostMatch)
Retrieves all stored trails for the given Server and HostMatch
api_root()
Get api_root env param value if any, empty otherwise.
api_root(Path)
Set api_root env param to the given Path.
compile(Routes)
Compiles the given list of trails routes, also compatible with cowboy routes.
constraints(Trail)
Gets the constraints from the given trail.
handler(Trail)
Gets the handler from the given trail.
host_matches(ServerRef)
metadata(Trail)
Gets the metadata from the given trail.
options(Trail)
Gets the options from the given trail.
path_match(Trail)
Gets the path_match from the given trail.
retrieve(PathMatch)
Fetch the trail that matches with the given path.
retrieve(HostMatch, PathMatch)
Fetch the trail that matches with the given host and path.
retrieve(Server, HostMatch, PathMatch)
Fetch the trail that matches with the given server and host and path.
servers()
single_host_compile(Trails)

Equivalent to compile([{'_', Trails}]).

store(Trails)
Store the given list of trails.
store(Server, Trails)
trail(PathMatch, ModuleHandler)

Equivalent to trail(PathMatch, ModuleHandler, [], #{}, []).

trail(PathMatch, ModuleHandler, Options)

Equivalent to trail(PathMatch, ModuleHandler, Options, #{}, []).

trail(PathMatch, ModuleHandler, Options, MetaData)

Equivalent to trail(PathMatch, ModuleHandler, Options, MetaData, []).

trail(PathMatch, ModuleHandler, Options, MetaData, Constraints)
This function allows you to add additional information to the cowboy handler, such as: resource path, handler module, options and metadata. Normally used to document handlers.
trails(Handlers)
This function allows you to define the routes on each resource handler, instead of defining them all in one place (as you're required to do with cowboy). Your handler must implement the callback trails_handler:trails/0 and return the specific routes for that handler. That callback is invoked for each given module and then the results are concatenated.

Link to this section Types

Link to this type

metadata/1

View Source 
-type metadata(X) :: #{method() => X}.
Link to this type

method/0

View Source 
-type method() :: get | put | post | delete | patch | head | options.
Link to this type

route_match/0

View Source 
-type route_match() :: '_' | iodata().
Link to this type

route_path/0

View Source 
-type route_path() ::
    {Path :: route_match(), Handler :: module(), Opts :: any()} |
    {Path :: route_match(), cowboy:fields(), Handler :: module(), Opts :: any()}.
Link to this type

route_rule/0

View Source 
-type route_rule() ::
    {Host :: route_match(), Paths :: [route_path()]} |
    {Host :: route_match(), cowboy:fields(), Paths :: [route_path()]}.
Link to this opaque

trail/0

View Source (opaque) 
-opaque trail()
Link to this type

trails/0

View Source 
-type trails() :: [trail() | route_path()].

Link to this section Functions

Link to this function

all()

View Source 
-spec all() -> [trail()].
Retrieves all stored trails.
Link to this function

all(HostMatch)

View Source 
-spec all(HostMatch :: route_match()) -> [trail()].
Retrieves all stored trails for the given HostMatch
Link to this function

all(Server, HostMatch)

View Source 
-spec all(Server :: ranch:ref(), HostMatch :: route_match()) -> [trail()].
Retrieves all stored trails for the given Server and HostMatch
Link to this function

api_root()

View Source 
-spec api_root() -> string().
Get api_root env param value if any, empty otherwise.
Link to this function

api_root(Path)

View Source 
-spec api_root(string()) -> ok.
Set api_root env param to the given Path.
Link to this function

compile(Routes)

View Source 
-spec compile([{Host :: route_match(), Trails :: trails()}]) -> cowboy_router:dispatch_rules().
Compiles the given list of trails routes, also compatible with cowboy routes.
Link to this function

constraints(Trail)

View Source 
-spec constraints(trail()) -> cowboy:fields().
Gets the constraints from the given trail.
Link to this function

handler(Trail)

View Source 
-spec handler(trail()) -> module().
Gets the handler from the given trail.
Link to this function

host_matches(ServerRef)

View Source 
-spec host_matches(ranch:ref()) -> [route_match()].
Link to this function

metadata(Trail)

View Source 
-spec metadata(trail()) -> map().
Gets the metadata from the given trail.
Link to this function

options(Trail)

View Source 
-spec options(trail()) -> any().
Gets the options from the given trail.
Link to this function

path_match(Trail)

View Source 
-spec path_match(trail()) -> route_match().
Gets the path_match from the given trail.
Link to this function

retrieve(PathMatch)

View Source 
-spec retrieve(PathMatch :: string()) -> trail() | notfound.
Fetch the trail that matches with the given path.
Link to this function

retrieve(HostMatch, PathMatch)

View Source 
-spec retrieve(HostMatch :: route_match(), PathMatch :: string()) -> trail() | notfound.
Fetch the trail that matches with the given host and path.
Link to this function

retrieve(Server, HostMatch, PathMatch)

View Source 
-spec retrieve(Server :: ranch:ref(), HostMatch :: route_match(), PathMatch :: string()) ->
            trail() | notfound.
Fetch the trail that matches with the given server and host and path.
Link to this function

servers()

View Source 
-spec servers() -> [ranch:ref()].
Link to this function

single_host_compile(Trails)

View Source 
-spec single_host_compile(trails()) -> cowboy_router:dispatch_rules().

Equivalent to compile([{'_', Trails}]).

Link to this function

store(Trails)

View Source 
-spec store(Trails :: trails() | [{HostMatch :: route_match(), Trails :: trails()}]) -> ok.
Store the given list of trails.
Link to this function

store(Server, Trails)

View Source 
-spec store(Server :: ranch:ref(),
      Trails :: trails() | [{HostMatch :: route_match(), Trails :: trails()}]) ->
         ok.
Link to this function

trail(PathMatch, ModuleHandler)

View Source 
-spec trail(route_match(), module()) -> trail().

Equivalent to trail(PathMatch, ModuleHandler, [], #{}, []).

Link to this function

trail(PathMatch, ModuleHandler, Options)

View Source 
-spec trail(route_match(), module(), any()) -> trail().

Equivalent to trail(PathMatch, ModuleHandler, Options, #{}, []).

Link to this function

trail(PathMatch, ModuleHandler, Options, MetaData)

View Source 
-spec trail(route_match(), module(), any(), map()) -> trail().

Equivalent to trail(PathMatch, ModuleHandler, Options, MetaData, []).

Link to this function

trail(PathMatch, ModuleHandler, Options, MetaData, Constraints)

View Source 
-spec trail(route_match(), module(), any(), map(), cowboy:fields()) -> trail().
This function allows you to add additional information to the cowboy handler, such as: resource path, handler module, options and metadata. Normally used to document handlers.
Link to this function

trails(Handlers)

View Source 
-spec trails(module() | [module()] | {module(), map()} | [{module(), map()}]) -> trails().
This function allows you to define the routes on each resource handler, instead of defining them all in one place (as you're required to do with cowboy). Your handler must implement the callback trails_handler:trails/0 and return the specific routes for that handler. That callback is invoked for each given module and then the results are concatenated.