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. Thekey
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 thatobj
isn’t a string. Even ifobj
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 unlesspass_obj
is set toFalse
upon registering the function with theRouter
instance.- If
pass_obj
isTrue
andobj
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.