next up previous contents
Next: 11.2 Adding other classes Up: 11. Extending the tool Previous: 11. Extending the tool   Contents


11.1 Adding simple shell-command tools

If the tool is implemented as a ``typical'' shell command, then all that needs to be done is a single call of:


  Tools.registerStdShellCmdTool

For example, suppose you have made a new, improved version of ML-Yacc (``New-ML-Yacc'') and want to register it under a class called nmlyacc. Here is what you write:


  val _ = Tools.registerStdShellCmdTool
    { tool = "New-ML-Yacc",
      class = "nmlyacc",
      suffixes = ["ngrm", "ny"],
      cmdStdPath = "new-ml-yacc",
      template = NONE,
      extensionStyle =
          Tools.EXTEND [("sig", SOME "sml", fn _ => NONE),
                        ("sml", SOME "sml", fn x => x)],
      dflopts = [] }

This code can be packaged as a CM library and loaded via CM.make or CM.load_plugin. ( CM.autoload is not enough because of its lazy nature which prevents the required side-effects to occur.) Alternatively, the code could also be entered at the interactive top level after loading library $smlnj/cm/tools.cm.

In our example, the shell command name for our tool is new-ml-yacc. When looking for this command in the filesystem, CM first tries to treat it as a path anchor (see section 3.3). For example, suppose new-ml-yacc is mapped to /bin. In this case the command to be invoked would be /bin/new-ml-yacc. If path anchor resolution fails, then the command name will be used as-is. Normally this causes the shell's path search mechanism to be used as a fallback.

Tools.registerStdShellCmdTool creates the class and installs the tool for it. The arguments must be specified as follows:

tool
a descriptive name of the tool (used in error messages); type: string
class
the name of the class; the string must not contain upper-case letters; type: string
suffixes
a list of file name suffixes that let CM automatically recognize files of the class; type: string list
cmdStdPath
the command string from above; type: string
template
an optional string that describes how the command line is to be constructed from pieces;
The string is taken verbatim except for embedded % format specifiers:
%c
the command name (i.e., the elaboration of cmdStdPath)
%s
the source file name in native pathname syntax
%$n$t
the $n$-th target file in native pathname syntax;
($n$ is specified as a decimal number, counting starts at $1$, and each target file name is constructed from the corresponding extensionStyle entry; if $n$ is $0$ (or missing), then all targets--separated by single spaces--are inserted; if $n$ is not in the range between $0$ and the number of available targets, then %$n$t expands into itself)
%$n$o
the $n$-th tool parameter;
(named sub-option parameters are ignored; $n$ is specified as a decimal number, counting starts at $1$; if $n$ is $0$ (or missing), then all options--separated by single spaces--are inserted; if $n$ is not in the range between $0$ and the number of available options, then %$n$o expands into itself)
%$x$
the character $x$ (where $x$ is neither c, nor s, t, or o)
If no template string is given, then it defaults to "%c %s".
extensionStyle
a specification of how the names of files generated by the tool relate to the name of the tool input file; type: Tools.extensionStyle.
Currently, there are two possible cases:
  1. `` Tools.EXTEND $l$'' says that if the tool source file is file then for each suffix sfx in (map #1 $l$) there will be one tool output file named file . sfx. The list $l$ consists of triplets where the first component specifies the suffix string, the second component optionally specifies the member class name of the corresponding derived file, and the third component is a function to calculate tool options for the target from those of the source. (Argument and result type of these functions is Tools.toolopts option.)
  2. `` Tools.REPLACE $(l_1, l_2)$'' says that given the base name base there will be one tool output file base . sfx for each suffix sfx in (map #1 $l_2$). Here, base is determined by the following rule: If the name of the tool input file has a suffix that occurs in $l_1$, then base is the name without that suffix. Otherwise the whole file name is taken as base (just like in the case of Tools.EXTEND). As with Tools.EXTEND, the second components of the elements of $l_2$ can optionally specify the member class name of the corresponding derived file, and the third component maps source options to target options.
dflopts
a list of tool options which is used for substituting %$n$o fields in template (see above) if no options were specified. (Note that the value of dflopts is never passed to the option mappers in Tools.EXTEND or Tools. REPLACE.) Type: Tools.toolopts.

Examples for the EXTEND expansion style are tools such as ML-Yacc and ML-Lex, while others, e.g., ML-Burg, use the REPLACE style (see section 6.2).


next up previous contents
Next: 11.2 Adding other classes Up: 11. Extending the tool Previous: 11. Extending the tool   Contents
Matthias Blume
2001-07-19