improve examples, illustrate conventions

nb/src/main/resources/examples/bindings-basics.yaml

@@ -0,0 +1,74 @@
+description: examples of basic bindings
+
+scenarios:
+  default:
+    stdout: run driver===stdout format=readout
+
+
+# Each binding is named, so the bindings is a map of names to
+# bindings recipes. Bindings that are defined at the document
+# root level are made available to all statements.
+
+# In these example files, statements are not defined, since
+# we use the stdout driver, which can create a convenient output
+# format for us based on the binding names.
+
+bindings:
+
+  # Identity()
+  #
+  # All binding recipes will get the current cycle number as the
+  # input for the first function in the list.
+  # In this way, each cycle serves as a unique and stable seed
+  # for all the data associated with that cycle.
+  #
+  # You can get the cycle number with the Identity() function,
+  # which is a helpful way to display cycles and their related
+  # values from other named bindings.
+
+  n: Identity();
+
+  # function chaining
+  #
+  # Functions can be stitched together. This is done with Java lambdas
+  # internally. This means you can build up richer binding functions
+  # from basics simply by putting them on a line together, delimited by
+  # semicolons.
+
+  # convert the input long to a String and then prefix it with 'pre-'
+  # and then suffix it with '-post'
+
+  lambda: ToString(); Prefix('pre-'); Suffix('-post');
+
+  # escapes
+  #
+  # When you pass String arguments to a binding function, you can either
+  # use single or double quotes. With single quotes, every character between
+  # the first single quote and the next one is taken literally.
+  #
+  # With double quotes, the backslash character acts escapes the next character,
+  # including double quotes.
+
+  escaped: FixedValue("\"quotes included!\"");
+
+  # NumberNameToString()
+  #
+  # This function produces a name for a number all the way up to
+  # Long.MAX_VALUE, and all negative values except for LONG.MIN_VALUE.
+  # It is quite useful for sketching data and relationships where you
+  # need a text field in your data. For fluffy text, use a higher
+  # cycle range.
+
+  name: NumberNameToString();
+
+  # TypeOf()
+  # If you want to see or confirm the type of object that is produced
+  # by a binding recipe, simply add TypeOf() to the end of it.
+
+  typeof: NumberNameToString(); TypeOf();
+
+# The Show() function provides a snapshot of what is in the thread-local
+# variable map as a String
+
+  show: Show();
+

nb/src/main/resources/examples/bindings-bigdecimal.yaml

@@ -0,0 +1,44 @@
+scenarios:
+  default: run driver===stdout format=readout
+
+# In the binding examples below, ther are some initial conversions to create
+# approriate example data. The most important part ot pay attention to is
+# the actual use of the ToBigDecimal, according to the input type in each
+# example, and the arguments supported.
+
+# ToBigDecimal(...) functions which take whole-numbered inputs may have
+# a scale parameter or a custom MathContext, but not both. The scale parameter
+# is not supported for String or Double input forms.
+
+bindings:
+
+  # convert an example double with some fractional values, then convert it to BigDecimal
+  from_double: ToDouble(); Div(100.0d); ToBigDecimal();
+
+  # convert doubles to BigDecimal, with custom precision and rounding
+  from_double_custom5: ToDouble(); Div(100.0d); ToBigDecimal('precision=5 roundingMode=HALF');
+
+  # convert directly to BigDecimal from long as whole numbers
+  from_long: ToBigDecimal();
+
+  # convert long to BigDecimal with three digits to the right of the decimal point
+  from_long_scale3: ToBigDecimal(3);
+
+  # convert long to BigDecimal with custom precision and rounding
+  from_long_custom2: ToBigDecimal('precision=2 roundingMode=UP');
+
+  # convert int to BigDecimal as whole numbers
+  from_int: ToInt(); ToBigDecimal();
+
+  # convert int to BigDecimal with 2 digits to the right of the decimal point
+  from_int_scale2: ToInt(); ToBigDecimal(2);
+
+  # convert int to BigDecimal with custom precision and rounding
+  from_int_custom3: ToInt(); ToBigDecimal('precision=3 roundingMode=CEILING');
+
+  # convert a string input using default settings
+  from_string: FixedValue("12345.54321"); ToBigDecimal();
+
+  # convert a string input using a custom MathContext
+  from_string_custom: FixedValue("12345.54321"); ToBigDecimal('precision=7 roundingMode=UP');
+

nb/src/main/resources/examples/bindings-double.yaml

@@ -1,8 +1,7 @@
-# You can run this file with this command line to see the values printed to stdout:
-# ./ebdse run driver=stdout yaml=bindings/double.yaml cycles=10
+description: examples of bindings for the double type
 
-# This file demonstrates different types of timestamp recipes
-# that you can use with virtdata. (The bindings used in ebdse)
+scenarios:
+  default: run type===stdout format=readout
 
 # If you want to control the output, uncomment and edit the statement template below
 # and modify the named anchors to suit your output requirements.
@@ -15,14 +14,16 @@ bindings:
 # All uncommented lines under this are indented, so they become named bindings below
 # the entry above
 
-# Normally, the value that you get with a cycle starts at 0.
+# Normally, the value that you get with a cycle starts at 0:
 
   cycleNum: Identity();
 
-# here we convert the cycle number to a double by casting.
+# here we convert the cycle number to a double:
+
   id: Identity(); ToDouble()
 
 ##    Sensor value
+
   sensor_value: Normal(0.0,5.0); Add(100.0) -> double
 
 #  Example output:

nb/src/main/resources/examples/bindings-epochmillis.yaml

@@ -1,8 +1,7 @@
-# You can run this file with this command line to see the values printed to stdout:
-# ./ebdse run driver=stdout yaml=bindings/timestamp.yaml cycles=10
+description: examples of bindings that produce long values as epoch millis
 
-# This file demonstrates different types of timestamp recipes
-# that you can use with virtdata. (The bindings used in ebdse)
+scenarios:
+  default: run type===stdout format=readout
 
 # If you want to control the output, uncomment and edit the statement template below
 # and modify the named anchors to suit your output requirements.
@@ -18,6 +17,7 @@ bindings:
   # Normally, the value that you get with a cycle starts at 0.
 
  cycleNum: Identity();
+
 # All uncommented lines under this are indented, so they become named bindings below
 # the entry above
 

nb/src/main/resources/examples/bindings-utilities.yaml

@@ -0,0 +1,30 @@
+description: examples of bindings that help you design data sets
+
+scenarios:
+  default:
+    stdout: run driver===stdout format=readout
+
+bindings:
+
+# The Identity() function is just a handy place holder to let you get the
+# cycle number unchanged.
+
+  n: Identity();
+
+# NumberNameToString produces a name for a number all the way up to
+# Long.MAX_VALUE, and all negative values except for LONG.MIN_VALUE.
+# It is quite useful for sketching data and relationships where you
+# need a text field in your data. For fluffy text, use a higher
+# cycle range.
+
+  name: NumberNameToString();
+
+# The TypeOf() function tells you the java class of its input
+
+  typeof: TypeOf();
+
+# The Show() function provides a snapshot of what is in the thread-local
+# variable map as a String
+
+  show: Show();
+

nb/src/main/resources/examples/sequences.yaml

@@ -9,6 +9,7 @@ scenarios:
   concat: run driver===stdout seq===concat cycles=20
   bucket: run driver===stdout seq===bucket cycles=20
   interval: run driver===stdout seq===interval cycles=20
+
 statements:
  - A1: "A "
    ratio: 1