DSL to build a Stopsel router.

A router is declared using the router/2 macro. Within this macro you can declare commands, scopes and Stopsel.

The commands defined in the router will be used to route the messages to the appropriate functions defined in other modules, parallely to the router module.

Note: You can only define one router per module and you cannot use builder functions outside of the router definition.

Scopes

A scope encapsulates commands, stopsel from the parent scope. The router-declaration acts as the root scope.

Aliasing

Every scope can add an alias to the scopes and commands within it. An alias is a module which implements a command that has been declared in the router.

In the following example the router applies the initial alias MyApp and the scope adds the alias Commands, resulting in the alias MyApp.Commands for all commands defined within the scope.

router MyApp do
  scope "command", Commands do
    # Define your commands here
  end
end

Paths

A path is a string with segments that are separated with |. There are 2 types of segments: Static segments and parameters.

Note: Avoid adding spaces in path segments as they can confuse the Stopsel.Invoker module.

Static segments

Text against which the content of a Stopsel.Message is matched against.

Parameter

A parameter segment is defined by prepending : in front of the segment name. These parameters will be available in the :params of the Stopsel.Message.

Commands

A commands is defined with a name and optionally with path and assigns. The name of a command must be the name of a function defined in the current alias.

In this example the command :execute would be used to execute the function MyApp.Commands.execute/2

router MyApp do
  scope "command", Commands do
    command :execute
  end
end

Similar to scopes you can define a path segment against which the message must match against in order to execute the command. By default this will use the name of the command, if no path was given.

Additionally assigns can be added to a command. These will be added to the message before any stopsel are applied.

Stopsel

A stopsel can be defined as a function or a module. A message will pass through each of the stopsel that applies to the current scope. Each stopsel can edit the message or halt the message from being passed down to the command function.

For more information on stopsel see Stopsel