Anatomy of a unit

units are the building blocks of caixanegra.
Every unit will be materialized into one flow step, which you can use multiple times to model processes.

Input

units can accept (or not) input. If your unit, let's say, transform strings, it will need to receive at least one input, which will be the target string to work the transformation.

Data Types

Current caixanegra version understands the formats string, number, boolean, regex and dataset.

• string, boolean and number are self-explanatory.
• regex will enable the built-in regex editor and tester
• dataset will limit the values to a user-defined list

Value Provenance

caixanegra can look up values for a specified input on three different provenances:

• storage, which is a hash shared by all units
• carryover, which is a hash available on the current unit, carrying over whatever the previous unit outputted
• user, which will enable the designer user to set a value, directly from the interface

Dynamic Hot Swapping

Input values can refer to storage and carryover provenances dynamically, exactly one pass deep.

• @somekey@, will be replaced with the value held by storage key somekey
• %somekey%, will be replaced with the value held by carryover key somekey

So, if the carryover has a name: John, surname: Doe and the full_name input has the value: %name% %surname%, getting the value for full_name will return John Doe.

Configuration Keys

Key	What does it do?
type	Input datatype. It can be string, number, boolean, regex or dataset
editable	Determines if the designer user can decide the input provenance and/or value
default	Sets the default value, when no value is found via regular mechanics
display	The input display text, that will show on the designer
description	The input text description, that will show on the designer, explaining what's that specific input for
set	Only applicable if type is dataset. This will be an array of pairs value and display which will, respectively, set the value for the selected option and determine what will the display text be for that option, on the designer

Output

units will output whatever is configured to be mapped from the current carryover, as soon as an exit is pointed out.
The only exception is the type passthrough, where all carryover will be effectively carried over to the next unit.
Either way, the exit mapping can be used to modulate the output.

Exit Mapping

Exit mappings will tell caixanegra what to pick from the carryover to build the input for the next unit.
Value set on Use should point to a key on the current carryover. Nested values are supported, with a dot notation.
If a value for the specified key (or chained key) is found, it will be set on the final output with the key specified on As.

So, if the carryover has a name: { first: John, last: Doe }, age: 34, the following mapping:

• Use: name.first As: first_name
• Use: age As: age_now

Will create the following input for the next unit:

first_name: John, age_now: 34

Unit Types

caixanegra treats every unit as block that has input, carryover and a specific execution order.
However, in some cases there's the need to specify differences in order to make exceptions:

• blackbox, the default type, will execute normally and only carryover what's on the exit mapping
• passthrough functions as a blackbox, but it will transparently carryover everything
• starter and terminator are used to mark the beginning of the flow, and the end
• fork functions as a blackbox, but it will display in a different color
• feeder functions as a blackbox, but it will not be executed in the context of a previous unit. Feeders are executed whenever the unit they're flowing into executes.

Unit DSL

By inheriting Caixanegra::Unit, your class will receive some defs and accessors in order to be recognized as a caixanegra unit.

Configuration

Class defined Defs	Argument type	What does it do?
configure_scope	[symbol]	Defines the unit scope
configure_name	string	Defines the unit name to display on the designer
configure_description	string	Defines the unit description to display on the designer
configure_type	symbol	Specifies the unit type. See above
configure_exits	[symbol]	Each array item will configure a possible exit from that unit, with the specified name (which cannot be repeated
configure_inputs	hash	Describes each unit input. See above
configure_assignments	[symbol]	Each array item will configure a possible assignment on that unit. This will hint other units's exit mappings on the necessary keys to output

Flow def

Your class must implement a def flow. This is the def that will be called on the context of the unit execution.
Inside this def, you can use a couple of predefined tools:

Instance defined Defs	Argument type	What does it do?
input	symbol	Tries to get the value for the specified input, according to it's configuration
carry_over	hash	Merges any given hash into the current unit carryover
persist	hash	Merges any given hash into the storage
exit_through	symbol	Mark the specified exit as the exit to flow through
exit_and_return	-	Prepare the result so it can be safely terminated. Should be used in a terminator unit