Introduction and API

Roadmap is a routing library powered by regular expressions. Roadmap was created to quickly map large amounts of input to functions. In the particular case that sparked Roadmap’s development, I was writing an IRC bot and I wanted a fast (to code and to execute) way to map input strings to functions. Beyond an IRC bot, I could also picture Roadmap being used to process data from a web API, user input, a socket, or really any stream of data.

Interface

Using Roadmap is hopefully very simple. The complete public interface of Roadmap consists of 3 methods.

Router.destination(reg_str, pass_obj=True)

Decorates functions to be called from a roadmap.Router instance.

Parameters:
  • reg_str – string that a regular expression can be created from
  • pass_obj (boolean) – whether or not to pass object to decorated function

It is generally a good idea to use raw strings to create regular expressions. If the input string matches reg_str, the decorated function will be called.

Router.__init__(processor)

Creates a new roadmap.Router and assigns a processor.

Parameters:processor – single variable function that does something with output

Because of Roadmap’s coroutine based architechture, routing an object returns no value. At first it may seem strange that nothing can be returned, but the mindset of Roadmap is that you don’t return values just for the sake of returning them; you return values to do something with them. In the case of my IRC bot, I wanted my functions to return strings. My processor() function received these strings and sent them over the socket. Other processing functions I can easily imagine are printing, logging, or commiting an object to a database.

This concept might be a little tricky, but the example will show how simple it actually is.

Router.route(obj, key=None)

Maps an object to its appropriate function

Parameters:
  • obj – object to route
  • key – an optional string to route :obj`obj` by
Return type:

None

route() is the method that will receive the input and begin the routing process for an object. The key parameter must be used if the object itself can’t be match by a regular expression, which, to the extent of my knowledge, means that that obj isn’t a string. Even if obj is matchable, key will be used if defined.

Details on Argument Passing

One slightly difficult aspect of using Roadmap is ensuring the desired arguments get passed to the routed functions. Briefly, here is the algorithm:

  • The object routed (the primary input to roadmap.Router.route()) will be passed to the function unless pass_obj is set to False upon registering the function with the Router instance.
  • If pass_obj is True and obj is iterable, each item in the iterable will be passed to the function. This feature may or may not be convenient, but it was useful for my IRC bot so I could nearly transparently route tuples.
  • If unnamed groups are defined in the regular expression for the function, the value of each of these groups will be passed after the arguments from the object itself.
  • If named groups are defined in the regular expression for the function, they will be passed as keyword arguments (name=value) to the function.

The examples should make this admittedly complex behavior a bit clearer.