Asimov 0.1.1 API documentation

A higher order function to help with compiler steps
that annotate each message with a new transformation result.

Expects:
 msgs:map The entire message map to be compiled.
 k:keyword The key the new intermediary result is to be associated with.
 f:fn The transformation function to be applied to each message definition.
 
Returns the message map where each message definition map has been passed to
the provided function. The result is then associated to it under the given key.

Compiling messages just means applying all compiler annotation steps to a raw message map.

Expects:
 msgs:map The entire message map to be compiled.

Returns the given message map with all properties needed and generated
by compilation annotated to each message.
Throws an exception if the a message or the dependency graph is malformed somehow.

A compiler step to calculate md5 sums for single messages.

Expects:
 msg:map A single message definition map.
 msgs:map The entire message map to be compiled.

Returns the message definition with the md5 sum annotated to it.

A compiler step to calculate md5 sums for all messages.
Messages are automatically ordered so that the dependency
graph is annotated bottom up.

Expects:
 msgs:map The entire message map to be compiled.

Returns the provided message map where each message definition is annotated with its md5 sum.

A compiler step to calculate  `gendeps --cat` texts for single messages.
In addition to the md5 sum, ros uses a message definition where all the
dependencies are concatenated into a single text during handshakes.
To be used with `annotate`.

Expects:
 msg:map A single message definition map.
 msgs:map The entire message map to be compiled.

Returns the cat text of the provided message definition.

Compiler step that checks for parsing errors.

Expects:
 msg:string The raw unparsed message used for error reporting.
 p:instaparse-parse The parsed version of the message,
   potentially containing errors.

Returns the parsed message when parsing was successful.

Thows an exception when the message definitions parse contains any errors.

Each declaration in a message definition has to be turned into a serializer and deserializer
in order to send and receive messages.

Expects:
 d:map A single declaration of a message definition.
 msgs:map The entire message map to be compiled.

Returns a gloss frame to encode and decode the given declaration.

A compiler step for turning the raw message definition into separate declarations.
To be used with `annotate`.

Expects:
 msg:map The message definition map consisting of a package name (:package)
         and the raw message declaration (:raw).
 msgs:map The entire message map to be compiled.

Returns a vector of the message definitions declarations.

Calculates a message definition maps dependency graph.

Expects:
 msgs:map The message definitions for which the graph is to be calculated.

Returns a map where each key represents a node in the graph and each value is a set
of child nodes.

A compiler step for extracting a messages dependencies from its declarations.
To be used with `annotate`.

Expects:
 msg:map The message definition map consisting of a collection of declarations (:declarations).
 msgs:map The entire message map to be compiled.

Returns a vector of the messages depencencies in the order they appeared.

A compiler step to ensure that the provided message definition map
is closed in regards to each messages dependencies.

Expects:
 msgs:map The message definitions to check.

Returns the given message definitions as is when all dependencies are satisfied.

Throw an exception if any message definitions depencency can't be satisfied.

A compiler step to ensure that the provided message definition map does not
contain cyclic dependencies.

Expects:
 msgs:map The message definitions to check.

Returns the given message definitions as is when no dependencies are cyclic.

Throw an exception if cycles are found in the dependency tree.

Toplevel message definitions require a special header,
in comparison with embedded messages.

Expects:
 msg:map A single message definition.
 msgs:map The entire message map to be compiled.

Returns a gloss frame to encode and decode the messages described by the given definition.
To be used for toplevel messages.

Generates an instaparse leaf transformer for literal value tokens.

Expects:
 f:fn A parsing function to be applied to the literals.

Returns a function that takes a literal and returns a map
containing it in its raw form (:raw) as well as the value
created by parsing it with the provided function (:read).

Compiler step that makes implicit package references in a
ros message definition explicit.
For "Header" messages the package is "std_msgs".
For all other message references without an explicit package
the package the message was declared in will be choosen.

Expects:
 package:string The name of the package the message was declared in.
 declarations:vector The declarations of the message definition.

Returns the given declarations where every message reference is explicit.

In order to create a md5 checksum for a message definition ros first
tries to bring it into a canonical text representation which is then hashed.
This process is buggy as it cannot distinguish between non-primitive arrays
tuples and variables, but we have to live with it (See the `:pedantic?` flag.).

Expects:
 msg:map The message definition map consisting of declarations (:declarations).
 msgs:map The entire message map to be compiled.

Returns the "canonical" text form of the message to be used for md5 generation.

Each message definition has to be turned into a serializer and deserializer
in order to send and receive messages.

Expects:
 msg:map A single message definition.
 msgs:map The entire message map to be compiled.

Returns a gloss frame to encode and decode the messages described by the given definition.
To be used as subframes embedded in other messages.

Loads all messages in the given directory.

Expects:
 root:file The directory to load the messages from.

Returns a message definition map where each key is a map with the messages package (:package) and name (:name)
and every value is a map with the messages package (:package),
name (:name) and its raw string data (:raw).

Ros employs package/message ids to identify message definitions.
Handling these as clojure maps is a bit nicer.
Inverse of `serialize-id`.

Expects:
 id:string A message definition id string of the form `package_name/message_name`.

Returns a map containing its components (:package and :name).

Message name and package are extracted from the
directory structure the message is stored at.

Expects:
 path:string The path to the message file.

Returns a map with the packacke name (:package) and the message name (:name).

Instaparse leaf transformer for primitive type token.

Expects:
 name:string the name of the type.

Returns a map with the keyworized version of the type (:name) as well as a tag
that marks it as a primitive (:tag).

Serializes a single declaration back to a string to be used in the md5 calculations.

Expects:
 d:map A single declaration.
 msgs:map The entire message map to be compiled.

Returns the declaration as a string formatted like
a line generated by the ros tool `gendeps`.

Ros employs package/message ids to identify message definitions.
Handling these as clojure maps is a bit nicer.
Inverse of `parse-id`.

Expects:
 id:string A message definition id map with the keys [:package :name].

Returns a message definition id string of the form `package_name/message_name`.

Instaparse tree transformer to be used on message declaration parsing results.

Expects:
 parse-tree: instaparse-tree The parse three to be transformed.

Returns a workable list of declarations.