Colimate is thought to manage a set of programs (called application) inside an integrated graphical environment. The nice user interface is defined by describing the command lines that your programs accept, and how different programs form groups. Colimate is divided in two parts. The first one, colimate_cc, is a pure compiler which reads all descriptions and produce a file which is the symbol table associated to that application, this symbol table is a ASCII text file and can be understood by a human being but SHOULD NEVER BE MODIFIED by hand (click here to take flavour of it). The second part of Colimate, colimate, takes this symbol table and opens the desired interface. The reason for splitting the task into two parts is that in this way the Interface opening is faster and safer since the descriptions need not to be recompiled each time.

Line descriptions must be written as C-like comments with a special tag. You can split the Application definition in as many files as you like, however in this quick example we will do everything in the same comment. Let's start with a simple interface to the unix command cp. Let's assume that the cp command line is (see the snapshot for the compulsory and optional colour code)

        cp <source> <destination>

The Colimate description would be something like this (different colors are used to highlight the structure):

/*Colimate:
    GROUP Shell {
        PROGRAM cp;
    }

    PROGRAM cp {
        OPEN MENU cp;
        COMMAND LINES {
            + simple: cp $SOURCE $DEST
        }
        PARAMETER DEFINITIONS {
            $SOURCE {
                label="Source files";
                help="Pattern or single file";
                type=file pattern;
            }
            $DEST {
                label="Destination";
                help="File or directory";
                type=file;
            }
        }
    }

    MENU cp {
        $SOURCE
        $DEST
    }
*/

And the menu is generated by

        colimate_cc -i shell1.mnu -o symbol_shell1
        colimate    -i symbol_shell1 &

Obtaining

Let's allow to make recursive copy. For doing so we would have to change a little the description of the command line (or parsing line) to (now red color highlights the added code)

            + simple: cp [-r] $SOURCE $DEST

And now modify the menu to let selecting the new option. Optional parameters are treated in a special way. For Colimate, everything inside the brackets is considered as a variable of type OPTION whose value simplifies to the bracket contents. Automatically generated variables are introduced Colimate for them, but they can be referred with the modifier OPT(...). In this case [-r] is OPT(-r). So we have to add some label and help (but not the type!!!) for the new automatic variable

            OPT(-r) {
                label="Recursive";
                help="Allow copying in subdirectories";
            }

And add it in the menu

    MENU cp {
        "Compulsory fields"
        $SOURCE
        $DEST
        "Flags"
        OPT(-r)
    }

Notice that the OPT(...) modifier is context-sensible, it means that it searches for the option -r within the menu you are defining and it will not be confused with any other -r option outside this menu.

Finally the result is

The unique command under the shell group is, so far, cp. Let's add a new one sharing the same menu. Of course, you can define a new group without sharing but that's nothing new. Let's add move. Move is really similar to copy but recursion is not allowed. So the final application description would be the following

/*Colimate:
    GROUP Shell {
        PROGRAM cp;
        PROGRAM mv;
    }

    PROGRAM cp {
        OPEN MENU cpmv;
        COMMAND LINES {
            + simple: cp [-r] $SOURCE $DEST
        }
        PARAMETER DEFINITIONS {
            OPT(-r) {
                label="Recursive";
                help="Allow copying in subdirectories";
            }
            $SOURCE {
                label="Source files";
                help="Pattern or single file";
                type=file pattern;
            }
            $DEST {
                label="Destination";
                help="File or directory";
                type=file;
            }
        }
    }

    PROGRAM mv {
        OPEN MENU cpmv;
        COMMAND LINES {
            + simple: mv $SOURCE $DEST
        }
    }

    MENU cpmv {
        "Compulsory fields"
        $SOURCE
        $DEST
        "Flags"
        OPT(-r)
    }
*/

Notice that the menu name has changed to indicate that it is shared between copy and move. Notice as well that different commands may have the same name of command line. Internally Colimate knows to which command each parsing line belongs to. Variables belong to a menu, so in two different menus there can be two variables with the same name, there is no problem at all. But if two programs are sharing a menu, once the variable is defined in one of them then it doesn't need to be redefine in the other, furthermore, it is an error. That is why mv doesn't define its parameters. If it had any new one, the it would have to define it, but this is not the case of $SOURCE and $DEST. Remind that optional variables still belong to a menu, so if OPT(-r) is used by any other program sharing a menu, and OPT(-r) has been already defined then it should be used as any other variable. For instance, although we know that it is nonsense for moving, the parsing line for mv if we wanted to share the option -r with copy should be rewritten as

            + simple: mv OPT(-r) $SOURCE $DEST

But this is not the case. When Colimate opens the menu for mv, it detects that the actual parsing line of mv is not using OPT(-r) so this option is disabled in the move menu. This will occur with all symbols in the menu which are not used by the selected parsing line.

We could have splitted the previous menu in several files, setting each menu in the appropiate source file. A sample structure of how this can be done could be

Application.mnu:
/*Colimate:
    // Groups --------------------------------------
    GROUP Shell {
        PROGRAM cp;
        PROGRAM mv;
    }

    // Programs ------------------------------------
    // Shell group .................................
    #include "cp.c"
    #include "mv.c"
*/

Cp.c:
/*Colimate:
    PROGRAM cp {
        OPEN MENU cpmv;
        COMMAND LINES {
            + simple: cp [-r] $SOURCE $DEST
        }
        PARAMETER DEFINITIONS {
            OPT(-r) {
                label="Recursive";
                help="Allow copying in subdirectories";
            }
            $SOURCE {
                label="Source files";
                help="Pattern or single file";
                type=file pattern;
            }
            $DEST {
                label="Destination";
                help="File or directory";
                type=file;
            }
        }
    }

    // This menu is shared with mv
    MENU cpmv {
        "Compulsory fields"
        $SOURCE
        $DEST
        "Flags"
        OPT(-r)
    }
*/

Mv.c:
/*Colimate:
    PROGRAM mv {
        OPEN MENU cpmv;
        COMMAND LINES {
            + simple: mv $SOURCE $DEST
        }
        // The parameters are defined in "cp.c"
    }
    // The menu is defined in "cp.c"
*/

Several parsing lines can be defined for the same program, they are shown as popup menus depending on the main program name. But remind that you should define a different parsing line only if the two actions performed in each case are completely different. If not you'd better use an option.