Commands

Commands can be executed by

• Mouse: middle-click the command name
• Keyboard: Place the cursor on the command name and then press CTRL-ENTER

The general form of a commands is

 Command = CommandName [Parameters] ["~"]
 CommandName = ModuleName "." [ ProcedureName ]
 Parameters = {Separator} AnyChar
 Separator = " " | LineFeed | CarriageReturn | Tab
 AnyChar = { 0X..FFX except "~" }

Restrictions:

• LEN(ModuleName) <= LEN(Modules.Name) = 32
• LEN(CommandName) <= WMTextView.MaxCommandLength = 256 bytes
• LEN(Parameters) <= WMTextView.MaxCallParameterBuf = 1024 * 1024 bytes

Notes:

• All names are case-sensitive!!!
• The Separator character is included in the parameter string, the "~" is not
• If the Terminator "~" is omitted, all characters between the CommandName and the end of text (limited by MaxCallParametersBuf size) will be copied into the parameter buffer (even if the command does not accept any parameters). It is therefore recommended to always terminate commands with a tilde.
• Each occurence of the character "^" in the Parameters will be replaced by the most recently selected text (if any)
• If the ModuleName is correct, but the module does not have a valid command with name CommandName, the module will be loaded, but command execution fails
• The command SystemTools.DoCommands is an exception. It requires to subsequent tilde characters to delimit the parameter string. Example: SystemTools.DoCommands SystemTools.Time ~ SystemTools.Time ~ ~.

If you middle click on a CommandName, the system will try to execute the command.

Two kind of command procedures can be executed (must be located in module scope):

 PROCEDURE ProcedureName*;
 PROCEDURE ProcedureName*(context : Commands.Context);

whereas

 Context* = OBJECT
    in-, arg- : Streams.Reader;
    out-, error- : Streams.Writer;
    caller- : OBJECT;
    result*: LONGINT;
 END Context;

Notes:

• arg, out and error are guaranteed to not be NIL
• in and caller may be NIL
• The output streams (out, error) are buffered! Call out.Update respectively error.Update to flush the buffers
• After command execution is completed, the command runner thread will automatically flush the output streams (out, error)

Example of Commands:

• Load module HelloWorld: HelloWorld.
• Execute command Hello in module HelloWorld: HelloWorld.Hello~
• Execute command Show in module SystemTools with parameter Hello World: SystemTools.Show Hello World~

Nice to know:

• The command SystemTools.DoCommands executes a sequence of commands
• The command SystemTools.Repeat executes a command several times

Command Line Options

The module Options.Mod can be used to parse command line options. For a detailed description of its usage, have a look at the header comment found in the source code.

Example:

 PROCEDURE Example*(context : Commands.Context);
 VAR 
    options : Options.Options;
    number : LONGINT; string : ARRAY 16 OF CHAR;
 BEGIN
    NEW(options);
    options.Add("n", "number", Options.Integer);
    options.Add("s", "string", Options.String);
    options.Add("f", "flag1", Options.Flag);
    options.Add("g", "flag2", Options.Flag);
    IF options.Parse(context.arg, context.error) THEN

        IF options.GetInteger("number", number) THEN
            context.out.String("Number = "); 
            context.out.Int(number, 0); 
            context.out.Ln;
	END;

        IF options.GetString("string", string) THEN
	    context.out.String("String = "); 
            context.out.String(string); 
            context.out.Ln;
        END;

        context.out.String("Flag1 = ");
        IF options.GetFlag("flag1") THEN
          context.out.String("set")
         ELSE context.out.String("not set"); 
        END;
        context.out.Ln;

        context.out.String("Flag2 = ");
        IF options.GetFlag("flag2") THEN 
          context.out.String("set"); 
         ELSE context.out.String("not set"); 
        END;
        context.out.Ln;

        (* options.Parse will set the position of the argument 
           stream to the first character after the options 
         *)
        context.arg.GetString(string);
        context.out.String("First argument: "); 
        context.out.String(string); 
        context.out.Ln;
    ELSE
        (* error message will be sent to context.error stream 
           if parsing fails 
         *)
    END;
 END Example;

Example usage:

• ModuleName.Example "This is the first string argument" ~ (no options)
• ModuleName.Example -f -g --string="Optional string" --number=1234 "First argument" ~ (all options set)
• ModuleName.Example -fg -s="Optional string" -n=1234 "First argument" ~ (all options set, compact variant)
• ModuleName.Example -s ~ (error: option s requires string parameter)
• ModuleName.Example -u ~ (error: option u unknown)

System Commands

The following table lists some system commands that are used often.

Path

If there are several fileystems mounted, the search path for file lookup can be modified with FSTools.SetDefault name ~, which moves the filesystem with prefix name to the head of the path. The current setting of the path can be queried with FSTools.Watch~. As stated above, the path will be used when the user does not specified a prefix for a file and the file systems are searched in the same order as returned by FSTools.Watch~. See also last section (FSTools entry in table).

WinAos: Mounting an A2 Partition

Run WinAos with administrative priviligies. The execute WinDisks.Install PhysicalDrive0 RW~ and start Partitions.Tool. Now you can mount the A2 partition.