COLIMATE Full Reference

Colimate Full Reference

A Colimate Application description is compound mainly of four sections: the group description, type description, programs' descriptions, and the menu descriptions , plus an optional menu definition for the case that the rightbutton of the mouse is clicked on a file field. They can be interleaved and mixed in any order you like, but at the end all programs, menus and groups must be defined. Symbols need not to be predefined as in other languages, i.e., you can refer to a menu inside a program when the menu hasn't been defined yet. This feature simplifies a lot the language syntax, and hence the language use. At any time you can include any other file with Colimate descriptions or comments. So, in BNF notation we could say

<Application> ::= {<Appl_def>} [<rightbutton_def>]
<Appl_def> ::= <group_def> | <type_def> | <program_def> | <menu_def> | <comment> | <include>

The include and comments structure is like expressed below

<include> ::= "#include" <small_text>
<comment> ::= "//"[^\n]

i.e, an include is like in C when relative paths are given (#include "another_file.mnu") and a comment starts with // and extends until the end of the line. Notice that Colimate only reads the source code between C like comments which start with /*Colimate: and end in */.

In this document, green means optional, blue compulsory, reserved words are bold and non-reserved italic.

GROUP SECTION

A group description basically is the following structure

    GROUP group_name {
        PROGRAM prog1;
        GROUP   another_group;
        ...
    }

You can nest groups as much as you like, and you can use group names in advance, ie, they don't need to be already defined (in the previous example another_group can be defined after group_name).

TYPE SECTION

A type description basically follows the structure below

    TYPE type_name: parent_name, parent_name, ...{
        +: <arg_list>
        $var { ... }
        ...
    }

A Colimate user-defined type can be thought as a record type. This means that variables belonging to this type have several fields under it. The fields are defined as the parameters for the commands (see below) without any restriction. The Colimate types implement some kind of "inheritance", this means that if a type B is inherting from another A, then the variables belonging to type B have all the fields corresponding to type A and B. The access to the variable fields is done by means of a composite name using the variable name, the type from which the field is taken from and the field name, like this

$var_type_field

And they really exist as independent variables, so they can be treated as such.

As for how these variables are written in the comman line, the programmer must supply the corresponding parsing line with all the flags and fields. This comman line must contain only fields defined by this type, ie, the inherited fields must have the corresponding comman line in the type where they were defined.

Click here to see an example using all these features of the user types in Colimate.

PROGRAM SECTION
A program description has got 4 parts (this time the order is important): first, you can provide some help link and a help text (this is optional, and they appear in the menu open as two extra buttons); second, you have to say which is the name of the menu Colimate has to open when this program is called; third, you have to specify which are the valid command lines for it; and finally, unnecessary if the program parameters have been defined somewhere else, you must define all parameters used by the program. So the program description structure is the following

    PROGRAM program_name {
       HELP="...";
        URL="http://...";
        OPEN MENU menu_name;
        COMMAND LINES {
            + line_name : exec_prog <arg_list> <file|$var   >file|$var
            ...
        }

        PARAMETER DEFINITIONS {
      $var {
                label      = "...";
                help       = "..."; // Can occupy several lines
                type       = <type_def>;
                shown      = YES|NO;
                case       = TO LOWER|TO UPPER;
                by default = <value_exp>;
            }
            ...
        }
    }

The help is shown as a small text when the cursor is stopped at the corresponding label. Default values are loaded automatically in variable values at compilation time.

The <arg_list> is compound of identifiers, variables, flags, optional parts delimited by brackets, and references to already defined optional parts with the modifier OPT(...). Here you are an example of command lines using the same option, the example is a very simple model of the Unix command tar where a single file is "tarred".

PROGRAM tar {
   help="Extracts/Archive a set of files";
   OPEN MENU tar;
   COMMAND LINES {
      + Archive: tar [-v]    -cf $TARFILE $FILE_PATTERN
      + Extracts: tar OPT(-v) -xf $TARFILE $FILE_PATTERN
   }
   PARAMETER DEFINITIONS {
      OPT(-v) {label="Verbose";} // Notice that the type is not necessary as
                                 // it is an option
      $TARFILE {
         label="Tarred file";
         help="I/O tarred file depending on action";
         type=FILE;
      }
      $FILE_PATTERN {
         label="Files to extract or archive";
         help="A file pattern can be issued";
         type=FILE PATTERN;
      }
   }
}

Notice that a program should have as many command lines as different functions, but not as different options. It makes no sense to provide command line for extracting verbosely and archiving verbosely, those are options of tar. However, archiving and extracting are different tasks within the same program.

The only two compulsory fields for parameters are the label and the type, except for the following cases :

The type is automatically assigned for optional variables
The label of not shown variables is not necessary (use the "shown=NO" qualifier for this)
If it is shown, then it is not necessary in any of this three cases

It is an exclusion variable
It is an optional variable with only 1 non-list variable depending upon it, ie, it may have more than 1 variable under it, but only one is not of the type LIST. This is thought for options of the kind

"[-mode $MODE $MODE_LIST]"

here

The default value of options must be 1 or 0 indicating if the option is selected or not; for lists and exclusions it is the selected label inside the label list (the first label is number 0).

Type definitions are important if you want colimate to perform some error checking before calling to your program. Thus, you can ask it to check the length of a string, the validity of a numerical field, and the existence or not of a file. In fact nearly all variables could be of type TEXT. User-defined types can be defined, which might be very useful in many cases.

Type's grammar is shown in the following pseudo-BNF expressions, the appropiate explanation is given below.

<type_def>    ::=   TEXT    MAXLENGTH "=" <int>
                  | NATURAL <range>
                  | INTEGER <range>
                  | FLOAT   <range>
                  | FILE    EXISTING | NON EXISTING | PATTERN
                  | LIST "{"
                        <small_text> "{"
                     <var> "=" <value_exp> ";"
                            ...
                        "}"
                        ...
                    "}"
                  | EXCLUSION "{"
                        <small_text> "{"<arg_list> "}"
                        ...
                    "}"
                  | <id>

<range> ::= "[" <number> "..." <number> "]"

Valid Types:

TEXT: This is the simplest data type for all fields. In principle, all variable contents can be regarded as a text. A text field doesn't mean that it is treated with quotes. You can check for a text variable that it hasn't got more characters than a given length. This is done with the MAXLENGTH modifier.
NUMBERS: There are 3 numerical data types: NATURAL (0, 1, ...), INTEGER (..., -1, 0, 1, ...) and FLOAT (any real number). For each of these types you can check that the input variable is inside a given range and ranges are defined from a number to another number (they are closed intervals). If any of the two interval limits is not provided it is supposed to be -infinity or infinity.
FILES: files are treated specially inside the menu, if you click on it the right button of the mouse a popup menu is shown with the structure specified in RightButton definition You can also ask Colimate to check the existence or not of the file selected.
LISTS: this is a very special data type. It is intended to modify other variable values. It, itself, hasn't got any value and does not create text when generating the command line. It might be better to see an example to see how it works. Let's say that there is a variable $A that is a parameter used in a certain process and user can select any value for it. However, there are two very common cases (Case 1 and Case 2) for which the value of $A is fixed (A1 and A2) and we want to provide the possibility of selecting these two values very easily. An extract of the Colimate code to do so might be

PROGRAM Prog {

OPEN MENU Menu;

COMMAND LINES {

+ usual: prog ... -a $A $COMMON_CASES ...

}

PARAMETER DEFINITIONS {

...

$A {

label="Parameter A";

type=TEXT;

}

$COMMON_CASES {

label="Common cases";

type=LIST {

"User Defined"

"Case 1" {$A="A1";}

"Case 2" {$A="A2";}

};

}

MENU Menu {
    ...
    $A
    $COMMON_CASES
    ...
}

Each time a label in the LIST variable is selected by the user, the action list associated to that case is executed and thus, the variables values changed. Of course, we could omit parameter A if we want to allow only a few cases, as in

PROGRAM Prog {
    OPEN MENU Menu;
    COMMAND LINES {
        + usual: prog ... [-a $A $A_FEW_CASES] ...
    }
    PARAMETER DEFINITIONS {
        ...
        $A {
            shown=NO;
            type=TEXT;
        }
        $A_FEW_CASES {
            label="A few cases";
            type=LIST {
                    "Case 1" {$A="A1";}
                    "Case 2" {$A="A2";}
                 };
        }
    }
}

MENU Menu {
    ...
    $Prog_00000
    ...
}

In this second example, $A_FEW_CASES defines the only possible cases for $A. Notice that it is inside an optional variable but as there is only one non-LIST variable under it ($A), then no label definition is needed for the option. The effect on the menu is that the radiobutton of the option is shown together with the label of the only one shown variable.

EXCLUSION: An exclusion is similar to a list, but it defines parts of the parsing line which are mutually exclusive, one and only one must be active at a time (by default, the first one in the list). If there are no variables under the parsing lines then the exclusion is shown horizontally, otherwise it is vertical. An example of use might be

PROGRAM Prog {
    OPEN MENU Menu;
    COMMAND LINES {
        + usual: prog ... [-a $A] ...
    }
    PARAMETER DEFINITIONS {
        ...
        $Prog_00000 {label="Select A";}
        $A {
            type=EXCLUSION {
                    "Case 1" {A1}
                    "Case 2" {A2}
                 };
        }
    }
}

MENU Menu {
    ...
    $Prog_00000
    ...
}

If the option is not selected no command line is generated for this part. If it is then, for instance, if "Case 1" is selected then "-a A1" is generated.

USER DEFINED: When you use user-defined types you supply the name of the defined type as the type for the parameter. From now on, you may change any of the features of the variable fields leaving the rest unchanged. Here you have an example of user-defined types using some inheritance

type base_type {
   +: -f1 $FIELD1
   PARAMETER DEFINITIONS {
      $FIELD1 {
         type=file;
         help="Help for field1";
         label="base field 1";
      }
   }
}
type derived_type: base_type {
   +: -f2 $FIELD2
   PARAMETER DEFINITIONS {
      $FIELD2 {
         type=file;
         help="Help for field2";
         label="derived field 2";
      }
   }
}

PROGRAM Prog {
   OPEN MENU Menu;
   COMMAND LINES {
      + test_inheritance : prog [$DERIVED]
   }
   PARAMETER DEFINITIONS {
      $DERIVED {
         label="Derived variable";
         help="Help for the derived variable";
         type=derived_type;
      }
      $DERIVED_base_type_FIELD1 {
         by default="Change the default value for the FIELD 1";
      }
   }
}

MENU Menu {
"General Parameters"
$Prog_00000
}

VALUE EXPRESSIONS

A value expression corresponds to the intuitive concept of expression in any language. The value expressions inside Colimate have got an inherent type according to the kind of value given as result. Thus, we have numerical expressions and string expressions. There are several operations which cannot be applied to numbers and viceversa. When an operation is applied to a wrong type expression an error is shown in execution time. The set of valid operations follow the syntax below

<value_expression>::=
   <basic_value_expression>
| <basic_value_expression> ".length"           // Length of a string
| <basic_value_expression> ".root"             // Root name of a filename.
                                                // For instance, for "file.txt" is
                                                // "file"
| <basic_value_expression> ".ext"              // Extension of a filename
                                                // In the example, "txt"
| <basic_value_expression> '(' <integer> ')'   // Character at position <integer>
| <value_expression> '*' <value_expression>    // Valid only for numeric expressions
| <value_expression> '/' <value_expression>    // Valid only for numeric expressions
| <value_expression> '+' <value_expression>    // Valid for numeric expressions,
                                                // For string expressions it is a
                                                // concatenation
| <value_expression> '-' <value_expression>    // Vanbsp;             // Options are in fact other variables
| <number>
| <small quoted text>
| '(' <value_expression> ')'

MENU SECTION

Menu definitions are what is really shown to the final user. Here you must define what are the variables you want to show each time a parsing line of a program is selected. Normally, each program has got its own menu, although they can be shared. When a particular parsing line is selected the name of the program and parsing line (if there are more than one for the selected program) chosen are written in the EXEC button of the menu, so it is important that you supply informative enough names. Variables shown in the menu but that are not used by the chosen parsing line are disabled, in this way misleading actions are prevented. A menu conceptually might be regarded as a vertical array of menu items: text or variables (either optionals or not). To define the menu you only need to say which items are inside. So a menu definition has got, finally, the following structure:

    MENU menu_name {
       "text"
        $var
       {$var $var ...}
        ...
    }

The "Exec", "Help", "WWW" and "Default All" buttons are internally defined for each menu. The menu items inside brackets are set in an horizontal array, instead of vertically.

Variables under an OPTION are shown if the OPTION variable is shown in that menu, you don't need to add them (the variables under that option) in the menu, and if an option only has one variable under it, then the label for that variable is used as the option one. Here is an example of use

PROGRAM Prog {

OPEN MENU Menu;

COMMAND LINES {

+ usual: prog $FILE_IN

[-a $A] // Optional arg. 0

[-b $B] // Optional arg. 1

+ less_usual: prog [-c] // Optional arg. 2

$FILE_IN

}

PARAMETER DEFINITIONS {

$FILE_IN {label="Input File"; type=FILE EXISTING;}

$A {label="Label A"; type=TEXT;}

$B {label="Label B"; type=TEXT;}

OPT(-c) {label="Label C";}

}

MENU Menu {
    "I/O parameters"
    $FILE_IN
    "Usual options"
    {OPT(-a) OPT(-b)}
    "Less usual options"
    OPT(-c)
}

RIGHT BUTTON SECTION

When dealing with files you might want to perform other really common operations on the file than the ones defined in the application such as showing it or selecting it from the directory structure. This can be achieved by clicking with the right button over the FILE type variable. By default, on all file variables the select behaviour is defined, i.e., even if you don't define this section user can select the file from the directory structure by right clicking on it. This section must be only provided if you want to do something else (like editing it, show it with an image viewer, show its length, ...). The structure for doing so is like the one for defining command lines with the exception that the only variable which must appear on the command line definitions must be $FILE (pay attention to variable case, usually Colimate is insensitive to reserved words case, except for this one).

The structure for defining the right button options is

    RIGHTBUTTON {
        + line_name : exec_prog<arg_list>
        ...
    }