next up previous contents
Next: 11.2.3 Reporting errors from Up: 11.2 Adding other classes Previous: 11.2.1 Filename abstractions   Contents

11.2.2 Adding a class and its rule

The interface to add arbitrary classes is the routine Tools.registerClass:


  val registerClass : class * rule -> unit

Here, type class is simply synonymous to string; a class string is the name of the class to be registered. It must not contain upper-case letters:


  type class = string

Type rule is a function type. It describes the rule function that CM will invoke for every member of the new class. The rule function is responsible for invoking the auxiliary mechanism necessary to bring its targets up-to-date. The function result of the rule function describes to CM what the targets are. Thus, the function maps the specification of the given member to its (partial) expansion:


  type rule =
    { spec: spec,
      native2pathmaker: string -> pathmaker,
      context: rulecontext,
      defaultClassOf: fnspec -> class option } ->
    partial_expansion

The specification spec consists of the name of the member together with a function to produce its corresponding abstract path (should that be necessary), the member's optional class (in case it had been given explicitly), its tool options, and a boolean flag that tells whether this member was the result of another tool:


  type spec = { name: string,
                mkpath: pathmaker,
                class: class option,
                opts: toolopts option,
                derived: bool }

name:
The name is the verbatim member string from the description file. Be sure not to use this string directly as a file name (although some tools might use it directly for purposes other than file names). Instead, first convert it to an abstract path (see mkpath below) and then convert back to a native file name string using one of nativeSpec or nativePreSpec.
mkpath
This is a function of type pathmaker that produces an abstract pathname corresponding to name. CM will pass in different functions here depending on whether name was given in CM's standard pathname syntax or in the underlying operating system's native syntax.

  type pathmaker = unit -> presrcpath
class:
This argument carries the class name if such a class name was explicitly specified. If the class was inferred from the member name, then it will be set to NONE.
opts:
Tool options are represented by a data structure resembling Lisp lists:

  type fnspec = { name: string, mkpath: pathmaker }
  datatype toolopt =
      STRING of fnspec
    | SUBOPTS of { name: string, opts: toolopts }
  withtype toolopts = toolopt list
The nesting of SUBOPTS reflects the nesting of sub-option lists in the member's tool option specification. Again, names which are potentially to be interpreted as file names are represented by their original specification string and a function mkpath to get the corresponding abstract path, thereby taking care of interpreting the name according to its respective syntactic rules and its context. (Type fnspec is a slimmed-down version of type spec. It also appears as the argument type of function defaultClassOf. See below.)
derived:
This flag is set to true if the source file represented by the specification is the result of a another, earlier tool invocation.

The other three arguments of a rule function are native2pathmaker, context, and defaultClassOf:

native2pathmaker:
This function takes a string and produces a function of the same type as mkpath above. When the rule constructs the specifications for its result files, it must provide the corresponding mkpath functions for those. Since most tools internally operate on native pathnames, these mkpath functions will have to be constructed using native2pathmaker.
context:
The context argument of a rule represents the directory that contains the CM description file on whose behalf the rule was invoked. It is represented as a higher-order function that invokes its function argument after temporarily setting the working directory to the context directory and returns the result of this invocation after restoring the original working directory. Not all rules require such a temporary change of directories, but those that do should encapsulate all their work into a local function and then pass this function to the context.

  type rulefn = unit -> partial_expansion
  type rulecontext = rulefn -> partial_expansion
defaultClassOf:
This function can be used to directly invoke CM's internal classification mechanism, taking advantage of any registered classifiers. The argument to be passed is of type fnspec, i.e., a record consisting of a name string and a function to convert the string to its corresponding abstract path.

A (full) expansion consists of three lists: a list of ML files, a list of CM files, and a list of sources. A partial expansion is a full expansion together with a list of specifications that still need to be expanded further.


  type expansion =
    { smlfiles: (srcpath * Sharing.request * setup) list,
      cmfiles: (srcpath * Version.t option * rebindings) list,
      sources: (srcpath * { class: class, derived: bool}) list }

  type partial_expansion = expansion * spec list

A rule always returns a partial expansion. CM will derive a full expansion by repeatedly applying rules until the list of pending specification becomes empty.

Most rules (except those for classes sml and cm) leave the lists smlfiles and cmfiles empty. A tool that produces an ML source file or a CM description file as output should put a specification for this file into the specification list of a partial expansion, letting the rules for classes sml and cm take care of the rest. At this point we will therefore not dwell on explanations for the types of these two fields.

The sources field is used to implement CM.sources (see section 4.1.11). Therefore, the rule should include here every file that it consumes if its implementer wishes to have it reported by CM.sources. (Do not include source files that are produced by the rule because those will be reported by subsequent rules.)


next up previous contents
Next: 11.2.3 Reporting errors from Up: 11.2 Adding other classes Previous: 11.2.1 Filename abstractions   Contents
Matthias Blume
2001-07-19