FLoWS Basics
FLoWS is another syntax to use all the functions you already know from WarpLib. For easier migration, FLoWS can be executed from within WarpScript, and WarpScript can be executed from FLoWS.
Please read the basic concepts of FLoWS first.
To understand some error messages, you must know that FLoWS uses the same execution environment as WarpScript.
What is the language closest to FLoWS?
Similarity learning also works with human brain. So, we can try to compare to well known syntaxes...
Strings
JavaScript, Python... lots of well known language allow double or single quotes. Multiline is straightforward. You don't need triple quotes or so.
- The key difference in FLoWS is that there is no backslash escape, only URL percent encoding (using UTF-8).
\n
becomes%0A
in FLoWS.- You won't need double escaping to write regular expressions.
Collections
Using double quotes for strings, this is exactly JSON syntax!
Operators and assignement
Comparable to all well known languages... With the same pitfalls. Use parentheses to explicit your operations.
Specific to FLoWS: Some functions of WarpLib can return several results. In this case, you must use multiple assignment:
User defined functions
These are called macros in FLoWS.
Declaration is like Java lambdas, with the same arrow type, and with an explicit return. The call of the macro with a @
prefix is WarpScript legacy.
Dear JavaScript developpers, beware of the arrow syntax,
->
is not the same as=>
in FLoWS. Both are available, see below.
Variable scoping
As most programming languages, scope of variables is limited to the macro, as long as your macro is declared with ->
.
If you use
->
, the macro has its own namespace.
If you do want the macro to be able to change variables in the calling namespace, you can use a leaking macro, with =>
arrow (double arrow because variables will flow back to the caller), as in the example below:
Control structures
FLoWS is a functional language, control structures are functions that take user defined functions as parameters. There is no IF, THEN or ELSE keyword, just an IFTE function:
Looking at the signature of IFTE, you can also write a macro as first argument, which should return a boolean.
The example above is typical functional programming. But "if then" cannot return any arguments, because nothing will be returned if the condition is not met. The following example illustrates what cannot be done:
If you want to be able to do "if then" (IFT function), then you can choose to break the strictly functional programming and use leaking macros:
Conclusion: control structures cannot be compared to well known languages except maybe Lisp, but its wellknownness is opinionated!
Semicolon, indentation, formatter
If you really want, you can add semicolons at the end of statements. Just like TypeScript. They have no effect on the grammar, and could contribute to a clearer code. Though there MUST be a statement before the semicolon, the construct a = 1;;
is invalid since there is no statement before the second semicolon.
FLoWS formatter is not yet developped.
Understanding Error messages
This code has a bug. Click on the execute button below:
Error example:
line #13: Exception at '=>FLOWS<=' in section [TOP] (FLOWS encountered an error. (Error at FLoWS L2:4-2:28 (Empty stack.)))
- If present, ignore the first line number.
line #13
refers to the internally generated WarpScript behind FLoWS. Most tools may hide this in the future. - Focus on the error message:
L2:4-2:28
You know the error is at line 2, character 2. Empty stack
: This is the kind of error message we are trying to remove from WarpLib, but some remain. Keep in mind this is linked to the number of arguments of the function you called.
Remember to check your macro or function signature (number of arguments) each time you see "stack" in an error message.
Looking at the RENAME
FLoWS signature in the doc, RENAME first argument must be the GTS you want to rename. Correct code is:
FLoWS syntax errors
FLoWS is parsed as execution proceeds. Parsing errors are raised as soon as they are encountered. For example, the code below has two errors:
RENAME
has less than two arguments: this is a runtime error, it will raise during execution of the function call, and can therefore be caught with TRY.gf = 32 + g * 9/5
is a syntax error:9/5
can not be parsed as a function{'unit','°Fahrenheit'}
is a syntax error: maps key value pairs should be separated with a colon, not a comma.
The syntax error will be raised before the RENAME error. Fix the syntax errors in the upper code, and try again: The RENAME runtime error should be caught, and the script returns empty GTS.
FLoWS precedence errors
Does 42°C equals to 133°F? No... It should be 107.6.
FLoWS implements a simple left to right precedence, there is no operator priority.
As you may have done in the C language in the past, the best practice is to explicit the priority with parentheses (remember MISRA C R.12.1). Moreover, the GTS type is LONG. The operations will be integer, not floating point ones: 9 divided by 8 equals 1 instead of 1.8. You must write 9.0 to force type conversion. The correct code is:
Objects
In FLoWS, there are a few primitives (number, strings, boolean) and lots of object: object types are the same as in WarpScript.
Type | Use Case |
---|---|
BITSET | Used for binary operation (decode a CAN bus frame for example) |
BOOLEAN | |
BYTES | Bytes array, raw binary data storage |
COUNTER | Atomic long. |
DOUBLE | |
GEOSHAPE | Polygon drawing on earth |
GTS | |
LIST | |
LONG | |
MACRO | |
MAP | |
MAPPER | Piece of custom Warpscript |
MATRIX | Math matrix |
NULL | |
PFONT | Font object. Linked to Pgraphics. |
PGRAPHICS | Pgraphics Image object. Could be rendered to png. |
PIMAGE | Pgraphics layer object. |
PSHAPE | Pgraphics shape object |
REDUCER | Piece of custom Warpscript |
SET | A collection of unique values |
STRING | |
VECTOR | Math vector |
VLIST | Vector, used for example to produce data bags in Pig |
The bold ones can be represented in the JSON stack output.
The other objects types cannot be serialized in JSON: it means if you try to return them at the end of your FLoWS script, you will get null
in the JSON object.
For example, run this code, and check the JSON tab output:
The PGRAPHICS objects cannot be serialized. They need to be converted into a PNG image, like in the code below. You can see the image in the image tab.
The conversion table is the same.
FLoWS make function arguments and results far more explicit than WarpScript. But as WarpLib is the same behind, some objects are mutable. For example, renaming a GTS does not change the GTS object:
In this example, g and h refer to the same object. Lots of functions in WarpLib return the input object reference. FLoWS won't bother if you ignore the return value:
Next Step
FLoWS is a WarpScript extension, so you now need to undestand the link between FLoWS and WarpScript with the next tutorial.
Explore FLoWS tutorials and blog posts on the blog