Syntax for Data Invokes

Pseudo-random data is defined in the List or Values tabs of the main screen.  Once defined, these can be included in text blocks by enclosing in square brackets a reference to that data.  Once referenced, the resulting value can be re-used by storing the result.

Note: ListNames and valueNames cannot overlap.  If a certain name is used for a valueName, there can be no list using the same name.

List element syntax:

A list is a collection of objects which are syntactically equivalent, and which one is chosen is relatively unimportant.  A list might be sorted or not, and may allow duplicates or not.  When called upon for data (and an instance is not explicitly indicated) a list is free to randomly present any instance or line.  Data is returned as a stringlist.  Most of the time, this will contain a single string, but the returned value might also be a very large number of lines. Lists with a single instance can be used to store constant string values, such as drill-wide values or canned paragraphs.  If there is only one instance in the list, that is what will always be returned, so the list performs the functions of a constant string value.

A list may be defined as a "simple list" where each row will be treated as a single string, as if enclosed in quotes.

•

Your car failed to start, and you have to walk.

•

The horror, the horror.

A list may be a "complex list" where each row will be treated as a series of columns and subcolumns.  All complex-list columns are optional and are delimited by spaces.  Each column may contain one or more subColumns delimited by commas.  Single or double quotes may be used to bracket subfields.

•

smith

•

smith  james  brother,father

•

field1,field2,field3  field4,"field5,part2 and more",field6

•

"You can force a complex list to behave simply, like this"

A list may be a "paragraph" list where the first row defines a paragraph delimitor and the remainder of the list contains one or more paragraphs.  Paragraph lists cannot be sorted, and must allow duplicates (the delimitor string).  (The list object protects itself from inconsistent flag settings)

•

--

•

This is the first segment

•

--

•

And the second, which

•

can go on for several lines

•

--

The nature of a list, whether simple, complex or paragraphed, is indicated in flags stored in the list-object and explicitly changed by the user.  They are not changeable during drill generation, and a list cannot be accessed in a different mode than it is flagged. A simple list cannot present a multi-line result.  The drill-designer GUI can always retrieve and store lines individually, as required for the maintenance process.  The contents of a list are constant during the drill generation.

<TextFile Invokes are not yet running>
Text files have the same formats as list objects. The first record of a text file denotes the format using a keyword ("simple", "complex" or "paragraph").  This is case-insensitive and the string is terminated by EOL or a blank followed by undefined values.  If the first record of a file contains none of those, the file is assumed to be a simple list and the first record will be treated as a normal data row.

 ex of a simple flat file:
   simple
   Your car failed to start, and you have to walk.
   The horror, the horror.
 ex of a simple flat file (uses default decision):
   Your car failed to start, and you have to walk.
   The horror, the horror.
 ex of a flat complex file:
   complex
   field1
   field1  field2  field3,field4
   field1,field2,field3  field4,"field5,part2 and more",field6
 ex of a paragraph file:
   paragraph
   ---
   Paul Smith
   2465 Massachusetts Apt G3
   ---
   John Doe
   1234 Elm St
   ---        
<End TextFile Syntax>

  To invoke a simple local variable or list:

•

[simpleName]

example:

•

Windspeed was [windspeed] mph.

•

Mrs. [lastName] was at home when the storm hit.

•

We [narrativeParagraph].

If the simpleName is an integer value, a final value is calced and retrieved as a string, and the calced value is stored in the value-object for future use.  If the name is a listName of a simple list, a random line is returned as a stringList containing one line.  If the name is a listName of a complex list, a random subColumn of a random column of a random row is returned as a stringList containing one line. If the name is a paragraph list, a random instance containing one or more strings is returned as a stringlist.  For all of these, the resulting value is limited in scope to one experience, so each participant's experience can get different values.  If the experience being processed is the common reality-space, then all participants will see the same value.  (For string values, the program does not save a result string but saves the instance number, and retrieves the string(s) at print time.)

<Not working yet>
To generate ephemeral values:

•

[?valueName] -- generates a local value for a defined value, but does not file that result in the value-object.  It does, however, retain the value locally to this text object for immediate re-use.

•

[<x..y>] -- selects random value from the range given. The range can be numeric or alpha or both.  The collating sequence is considered to be numeric, uppercase, lowercase.

•

"0..Z" -> 012...9AB...YZab...yz.

•

"0..F" -> 012...9ABCDEF

•

"A..z" -> ABC...YZab...yz

If the range is expressed wrong, it will return only the first character as the sole occupant of an array with one element.  (An error message is written to the log file.)

•

"1..0" -- returns "1" only

•

"X..H" -- returns "X" only

The start or end numeric can be multi-digit, but in that case there can be no alphas.

•

"10..99" generates 10, 11, 12 ... 98, 99

•

[(x,y,z)] -- selects a random occurrence from this list.

<End of ephemeral values>

  To store returned values:
[valueName=valueName] obtains a value from the integer or string resource, creates a new value in this experience, and stores the returned value there.  The newly stored value can then be referenced like any other value.

•

Mr [thisGuy=lastName] fell down and called out to Mrs [thisGuy].

<Not working>
Complex list specifications:
   [listName, rowSpec, colSpec, subColSpec]
 where rowSpec, colSpec and subColSpec are:
   [simpleName] -- to invoke a defined value, calc its final value
       if needed and retain that result in the value-object for future
       references.  Contrast to ?valueName syntax which uses a defined
       value but does not file the result in the value-object.
   integerValue -- to get that row, col, etc.
     ex:
       John fell on his [bodyParts, 1, 3] and burped.  
     All rows and columns are ONE-based, NOT zero-based.
   "=" -- same as last row, col or subcol used within this list
     ex:
       John broke his [bodyParts,[0..9],3] and his [bodyparts,=] hurt
   [nested reference ...]
   @compute ephemeral offsets ...
     where
       @random -- selects randomized instance
       @each -- returns elements in succession
         ex:
           "Bring your [stuff, [tripType], @each, @each]" returns all
             the columns of the row as a list of strings, where the
             row number is in the value "tripType".
       @count -- gives count of that dimension
       @?valueName -- as in ephemeral values above
       @<x..y> -- as in ephemeral values above
       @(x,y,z) -- as in ephemeral values above
 Fields can be omitted, and return a random element for the
 corresponding dimension.
   ex:
     [listname] -- returns random col & subcol of random line
     [listName, 45] -- returns a random column & subcol on row 45
     [listName,,3,5] -- returns col 3, subCol 5 of a random row
      
File specifications:
   ["fileName", delimStyle, rowSpec, colSpec, subColSpec]
 where
   fileName is adequate for the drill program execution directory.
       That is, fully qualify where needed.  
   ColSpec and subColSpec do not apply when a file is segmented,
       so if the delimStyle is not "flat" or "simple", querying
       the file returns stringlists containing one segment per
       call.
   delimStyle -- how to differentiate "rows" for this file.
     where
       flat -- row-by-row just like an internal local list
       simple -- row-by-row simple strings
       "delimString" -- delim strings show start of second and
         subsequent instances, and perhaps first instance.  
         An "instance" then may be multiple lines in the file.
         The delimString will be tested against each whole row
         of the file but will not scan across the row
         for a match within other data.
       auto -- the entire content of the first row will be taken as
         the delim string.
       integer -- segments are always same number of lines long
   ex:
     ["myFile.txt", flat, [whatRow], 3, 5]
     ["c:\aFile.txt", simple, [whatRow]]
     ["d:\data\narrative", "--", [whatSegNum]]
     ["c:\narrative", auto, [mySegNum]]           
     ["aFile.txt", 6, [whatSeg]]