Syntax Definitions

The syntax descriptions on this page are intended as guidelines, not as strict machine-readable definitions. They are to be interpreted loosely as follows:

Event Actions

An event action is performed by passing it as the first argument to INCO.Services.Execute, along with the calling plugin's parent path, name, and main parent as arguments 2 to 4. Its syntax is therefore defined by <command with placeholders> below.

Stream Files

The Cmd.ProcessStream procedure of any plugin (CINIXPlugin::INCOProcessStream()) takes the file name of a stream file in the respective plugin's _Streams_ folder and executes the sequence of commands stored in that file.

Every line of a stream file may be, optionally surrounded by whitespace,

INCO.Services.Execute

A <command with placeholders> is what is processed by INCO.Services.Execute (SINCO::CINIXPluginSINCOCall::INCOExecute()). Before being interpreted according to section Commands, it is transformed into a <command> by performing placeholder expansion.

Placeholder Expansion

Placeholders are the following patterns that upon expansion are replaced by a specific value:

Any occurrence of ${, #{, or %{ in the text can be prevented from being seen as the start of a placeholder by doubling the introducing character. Instead, this additional character will be removed, i.e. $${ is replaced by ${, ##{ by #{, %%{ by %{.

Redirections

<redirection> = "${" <redirection content> "}"

<redirection content> = [<target path>] <extended inco item path>
                      | "{" <redirection content> "}"

Redirections with a single pair of braces expand to the string value of the INCO variable with the given path, which is, for string variables, the string itself, and for numerical variables, the number in decimal notation without any type suffix. With a double pair of braces, redirections expand to the string representation of the value as defined below under <value>. A triple pair of braces yields the string representation of the string representation of the value, and so on – each additional pair of braces applies another conversion to string representation.

Example
If Prop.Greeting is a string variable with the value Hello "World" and Prop.Answer is a double variable with the value 42.0, then redirections expand as follows: 
${Prop.Greeting}     --> Hello "World"
${{Prop.Greeting}}   --> "Hello \"World\""
${{{Prop.Greeting}}} --> "\"Hello \\\"World\\\"\""
${Prop.Answer}       --> 42
${{Prop.Answer}}     --> 42:d
${{{Prop.Answer}}}   --> "42:d"

Choosing the right number of braces requires a bit of care. For example, the command 

.Cmd.SetTitle("Greeting: ${Prop.Greeting}", 42:d)

will sometimes work, but it breaks down easily: if the value of Prop.Greeting is the one from the example above, it expands to 

.Cmd.SetTitle("Greeting: Hello "World"", 42:d)

which is not valid syntax. The proper solution is to use 

.Cmd.SetTitle("Greeting: " ${{Prop.Greeting}}, 42:d)

which will work for any value of Prop.Greeting.

A rule of thumb for placeholders that expand to strings is:

Unless you know that the expanded value cannot contain quotation marks or backslashes, don't use placeholder expansion within string literals. Rather, close the string literal, write the placeholder with an additional pair of braces, then open a new string literal (if necessary).

Constants

Predefined constants that are always available are: 

#{PLUGIN_NAME}
#{PARENT_PATH}
#{PLUGIN_PATH}       -- the respective property of the calling plugin
#{PLUGIN_DIR}
#{MAIN_PARENT_PATH}
#{MAIN_PARENT_DIR}

#{SHIFT_KEY_STATE}   -- 1 if the shift key is pressed, 0 otherwise

At specific places, additional constants may be available, such as (without claim to completeness):

As for redirections, a constant with a single pair of braces expands to the respective string value, double braces make it expand to the string representation, etc. - see Redirections.

INCO item triggers (INCO item triggers documentation) also have some constants defined, see Constants provided by INCO item triggers. In contrast to the constants listed above, triggers are not aware of the "generally available" constants mentioned before (such as #{PLUGIN_NAME}).

Options

Options are: 

%{SYNCH} -- causes a <putvariable command> or <callprocedure command> to be executed synchronously

Options expand to the empty string, but their presence modifies the further processing of the command.

Commands

<command> = "Python> " <shell encoded list>
          | "PythonSync " <shell encoded list>
          | "Stream> " <filename>
          | <putvariable command>
          | <callprocedure command>

A <shell encoded list> is a string that is interpreted as a list of strings by splitting it at spaces (or runs of consecutive spaces), unless those spaces lie within a quoted string. Quoted strings start and end at ". Outside of quoted strings, \ suppresses the special behavior, if any, of the next character and is dropped (characters with special behavior are space, ", and \). Inside quoted strings, \ is only dropped (and suppresses special behavior) if it precedes " or \, all other occurrences of \ are preserved.

To decode a <shell encoded list>, use the ReadNextItemFromShellEncodedList() function. To build a <shell encoded list>, use CINCOValue::StringRep() or its variants to encode the individual items, then join them with spaces. (If you are certain that an item doesn't contain " or \\, you can get away with putting it between ". If you are certain that it doesn't contain space, ", or \, you can even include it as-is.)

Example
Mary\ had "a \"li"ttle\"   lamb "" \\p\i "\pi" "\\pi"
is interpreted as 
Mary had
a "little"
lamb

\pi
\pi
\pi

A Python> or PythonSync> command is transformed into a <callprocedure command> that calls the Python.Services.Execute procedure (CINIXPython::INCOExecuteAction()), passing the first item in the given <shell encoded list> as the first argument (script name), the rest of the list as the second argument (script arguments), the load location [FIXME: what's that?] of the calling plugin as the third, and 0 for Python> or 1 for PythonSync> as the forth argument.

A Stream> command is transformed into a <callprocedure command> that calls the calling plugin's Cmd.ProcessStream procedure with the given file name.

<putvariable command> = [<target path>] <extended inco path> {whitespace} "=" <value>


<callprocedure command> = [<target path>] <extended inco path> {whitespace} "(" [<value> {"," <value>}] ")"


<target path> = [("//" | "\\") <server name or address> ("/" | "\")] {<target name> ("/" | "\")}
              | "."       //current process
              | ".."      //parent of current process
              | "..."     //current INCO server

<extended inco path> = <extended inco item path>
                     | <extended inco item path> "!" <property name>
                     | <extended inco item path> ":" <bit number>
                     | <extended inco item path> "[" <array index> "]"

<extended inco item path> = "."
                          | ["."] <extended inco path component> {"." <extended inco path component>}

Paths starting with . are relative to the caller's plugin, those not starting with . are absolute. Exception: < at the start of a path is an abbreviation for .<, i.e. those paths are relative too.

<extended inco path component> = <inco item name>
                               | "<"       //up one level


<inco item name> = <nonempty sequence of alphanumeric characters, spaces, underscores (_), hyphen-minuses (-), and backslash-escaped periods (\.)>

Periods in INCO item names are only allowed if they are preceded by a backslash. Backslashes are only allowed if they are followed by a period. Unescaped periods are always considered as path separators, and non-period-escaping backslashes as target separators.

<value> = {whitespace} <trimmed value> {whitespace}

<trimmed value> = <number> { {whitespace} ("+"|"-") {whitespace} <number> }
                | <string literal> { {whitespace} <string literal> }

<number> = ("0x"|"0X") <hexadecimal integer> ":" ("l"|"f"|"d"|"L"|"F"|"D")
         | <decimal integer> [":" ("l"|"L")]
         | <decimal real number> [":" ("f"|"d"|"F"|"D")]

<string literal> = """ <string contents with " and \ escaped as \" and \\, optionally LF as \n> """

<value>s are interpreted and written by the CINCOValue class or by the incostringrep Python module.

Decimal numbers without a type suffix are accepted and interpreted as float values for backwards compatibility, but should be avoided in new applications.

Multiple adjacent string literals are concatenated into one string (this is mainly useful if some of the literals are the result of placeholder expansion).

Joining multiple numbers with "+" or "-" computes the respective sum or difference (this too is mainly useful if some of the numbers are the result of placeholder expansion). The type of the result is determined as follows: If any summand is a double, the result is a double. Else, if any summand is a float, the result is a float. Else, if any summand is a signed integer, the result is a signed integer. Else (i.e. if all summands are unsigned integers), the result is an unsigned integer.

IGD Files

IGD files are text files that store the value of a single INCO variable. After removing whitespace from the beginning and end of each line, removing comment lines that start with //, #, or ;, and concatenating all remaining lines, the contents of an IGD file are interpreted as a <value> as defined above.

Libinco_32 CallProcedure

The syntax accepted by the CallProcedure() function in libinco_32 is defined by <callprocedure command> above, with the exception that only absolute INCO paths, and no "<" (up one level) path components, are allowed.

Generated by doxygen 1.8.8