Parameter Definition Files
============================================================

Parameters definitions are plain text files in CSV format (Excel dialect is supported).
Values containing spaces or commas should be enclosed within double quotes.
Blank lines and any line beginning with # is treated like a comment and ignored (and encouraged, for readability).

Allowed Fields:
    Level1Category
    Level2Category
    *Name
    *Description
    *Type
    Constraints
    *DefaultValue
    EnabledExpression
    Hidden
    Units
    Tags
    Attributes

  * denotes a mandatory field

A header row must exist, but the columns may be in any order (specified by the header).
Other columns may be added. If they are, they are stored as attributes.


Excel Compatibility Notes
--------------------------------------------------
  * To include a double quote _inside_ a double quoted string, use two double quotes in the place of the one.
  * If you have a field with what could be mistaken for a MM-DD date in it, you'll probably need to quote it in order
    to prevent Excel from "intelligently" changing it to a date (e.g. "5-Mar").
  * Beware of using commas as a separator in parameter values. You'll almost certainly have to quote the default value
    or any help text.
  * Excel will work against you if you give it a file that's incorrect CSV.
    * It will interpret what should have been embedded commas as field separators, and increase the number of
      columns on EVERY row. (You'll see a bunch of needless, trailing commas at the end of every CSV record).
    * These will never go away automatically. You'll have to delete the columns yourself.
      * Excel distinguishes (internally) between empty cells and nonexistent cells when transforming between
        a worksheet and CSV.



Field Information
==============================
  Note: The "config GUI" referred to here is the "Parameters" tab of the MachMotion config window.


  Level1Category
  Level2Category
  ---------------
    These categories (arbitrary strings) are used by the config GUI to group parameters together.
    

  Name
  ---------------
    This is the name of the underlying register that will be created.
    It is not shown to the user in the config GUI.
    It will be used by scripts to access the value of the parameter.
    All parameters will be created under the "MachMotionOEMParameters" device in Mach.


  Description
  ---------------
    This is a description of the parameter.
    It _will_be_ shown to the user in the config GUI.
    

  Type
  Constraints
  ---------------
    The kind of data that the config GUI will expect for the value.
    The constraints field is particular to the type.

    Available Types (not case sensitive):
    ---------------
      text
        arbitrary, single-line text (no validation)
        Constraints: none
      multiline
        arbitrary text that may span multiple lines
        Constraints: none

      integer
        any whole number
        Constraints:
          - min
            the minimum value allowed
          - max
            the maximum value allowed
      float
        any floating-point number
        Constraints:
          - min
          - max
          - precision
            the number of digits (past the decimal point) to display (default: 4)

      choice
        Allow the user to choose from some allowable options.
        Constraints:
          a list of strings to allow as choices (the order in which they are specified
            is the order in which they are presented)
          You may enclose individual choices containing special characters
            with (Excel dialect) pairs of double quotes, e.g. "A, B, ""A; B"""
          You may _not_ embed commas into an option. (Use semicolons as a delimiter.)
          You may include an empty string as a choice if you want an "empty" or select-nothing option.
          Constraints are mandatory for the choice type.

      yesno
        presents the user with the choice between "Yes" and "No"
        Constraints: none
      boolean
        presents the user with the choice between "0" and "1"
        Constraints: none


      IOSignal
        Allows the user to select a Mach 4 signal, I/O, or register.
        Constraints: 
          a list of comma delimited allowable types for the given IOSignal
          valid values are: 
            "All" for All types
            "IO" for IO
            "OutSig" for Output Signals
            "InSig" for Input Signals
            "Reg" for Registers
            "AnlgOut" for Analog Output Signals
            "AnlgIn" for Analog Input Signals
           If no constraints are specified then constraints default to "All"

        Value Encoding: <type>$<device>$name
          Register$MachMotion$UserValue32
          IO$ScriptingMessages$Scripting_In_000
          InputSignal$1
             ISIG_INPUT0
          OutputSignal$1120
             OSIG_MACHINE_ENABLED

          Signals don't have a name. They only include the sigId (taken from the section name in the
            profile, e.g. [Signal1108] corresponds to OSIG_OUTPUT58)


        Lua scripts may use these WrapperModule functions to get the value of
          the object pointed to by the parameter's underlying register
          * WrapperModule.GetOEMParamReg(ParamName)
            Retrieve the value of the register pointed to by the specified parameter name.
          * WrapperModule.SetOEMParamReg(ParamName, Val)
            Set the value of the register pointed to by the specified parameter name to the specified value.
          * WrapperModule.GetOEMParamSig(ParamName)
            Retrieve the state of the signal or I/O point specified by the parameter name.
          * WrapperModule.SetOEMParamSig(ParamName, Val)
            Set the state of the signal or I/O point specified by the parameter name to the specified value.


  DefaultValue
  ---------------
    The value to use when the parameter is first created (or when Mach starts, if the 'save:false' attribute is set).


  Hidden
  ---------------
    The parameter is not shown in the config GUI.
    The underlying register is still created.

  Units
  ---------------
    What to display in the config GUI as "units" (to help the user understand what kind of data to enter).
    E.g. "user units", "in/mm", "degrees", "quantity", ...
  
  Tags
  ---------------
    a list of keywords that, if searched for, will match this parameter
    Substrings of the keywords will match as well, e.g. "spindle", "control" and "leco" will
      all match the tag "spindlecontrol".

    The level categories, parameter name, and type are automatically treated as tags.


  Attributes
  ---------------
    any other attributes (including custom ones not recognized by the software) that you wish to add to an object
    An attribute is a corresponding name and value.
    Any other columns not recognized are added as attributes to every parameter in the file.

    Known Attributes
    ---------------
      save
        - true/false (default: true)
        - Save the value of the parameter in the profile so that the value is preserved between invocations of Mach.
      help
        - a string to display as the help string (in the config GUI)
        - Examples
          "help:""helpful info"""
          "help:""Example: \\""3;5\\"", \\""4;7;9\\"""""


    Currently, the attributes are not exposed to OEM's for their own use. This may change in the future.
    The parameter objects are saved in the profile INI, so if you wanted to look for these attributes,
      they could be found that way. Look for "[PARAMETER__MachMotion_OEMParameters__<parametername>]".


  EnabledExpression
  ---------------
    (Reserved for future use.)
    




Relaxed JSON Syntax
========================================
Most data is read using a relaxed form of JSON, with some of the more verbose or tedious requirements somewhat relaxed.
  - Objects:
    * The object specifiers, "{" and "}" are optional. If left out, the entire piece of data is supposed to have been
      inside them and a single object is created.
  - Lists:
    * The list specifiers, "[" and "]" are optional. If left out, the entire piece of data is supposed to have been
      inside them and a single list is returned.

  - General
    * keys or values do not need to be quoted, unless they contain special characters (spaces, colons, etc.).
    * If no specifier exists, then the context of the data determines whether it will be treated like a list or an object.
      - Attributes looks for an object.
      - Tags looks for a list.
      - Constraints may look for either, depending on the type.
    * Whitespace is allowed (and removed) at the beginning and end of values as well as between items in a list.


Examples
========================================
# These examples include only the essential fields.
#   Actual uses should at least use the categories, units, and tags.
Name,Description,Type,Constraints,DefaultValue

# integers
PosInt,A Positive Integer,integer,min:1,1
NegInt,A Negative Integer,integer,max:-1,-100

# floats
Percent,"A Percent (float between 0 and 100, inclusive)",float,"min:0, max:100",100
ScaleFactor,A Multiplier,float,"min:.0001, max:1000",1.0
Tenths,A Decimal to .1 Precision,float,precision:1,3.3

# simple choices
DebuggingEnabled,Enable Debugging Mode,yesno,,No
IsFeatureEnabled,Is MagicFeature Enabled?,boolean,,1

# other choices
ToolChangerType,Tool Changer Type,choice,"ATC, WineRack",ATC
AllowsBlankChoice,A Choice Allowing 'Nothing',choice,",Option 1,Option 2",
EmbeddedListChoice,An Option With a List,choice,"A, B, C, ""A; B"", ""A; C"", ""B; C"",""A; B; C""","B; C"
