Main menu

User Manual

Previous    |    Up    |    Next

2. Commands

The syntax of ocamlwizard's command line is the following:

ocamlwizard [common options] [command] [command's options]

Options common to all commands are the following:

  • -printer : When a command outputs a result, it is written in XML format by default. Passing the value ocaml-pp to this option results in output displayed in plain text format.
  • -debug : Displays debug messages on the error output.

The command may be one of the following:

  1. Completion
  2. Compile
  3. Locate
  4. Refactor

  • Completion
ocamlwizard completion < -pos int> <file> [additional options]

This command provides automatic completion of pattern-matching (match with) cosntructs, paths (qualified identifiers) and record fields. The type of completion is automatically detected from the context.

The supported pattern-matching completions are the following:

  • Proposition of all cases:
    Completion aksed after «match e with» or simply «match e » (with a space after «e» to avoid a possible ambiguity with a path completion).
  • Proposition of missing cases:
    Completion to be asked right after the branch of the last case.
  • Expansion of an existing pattern-matching variable:
    Completion to be asked right after the branch arrow (). (The position of the variable is given using the -expand option; see below.) Only the missing cases are proposed.

In case of existing branches beyond the given position, all corresponding cases are ignored.

The supported path completions are the following:

  • Values
  • Modules

The completion must be asked on a construct such as «» where «M» stands for a (possibly empty) list of module names and where «id» is the (possibly empty) identifier to be completed. (The set of possible completions is filtered to keep only identifiers with prefix «id».)

The supported record field completions are the following:

  • in a record field access e.c (for reading or writing)
  • in a { e with c construct
  • in an explicit record construction { c1 = <val1> ; c2 = v
  • in pattern-matching over a record ({ c1 = <val1> ; c2 = v). In that case, at least one field must be given such that the record type can be determined.
  • -pos int : the position where the completion is asked for, in absolute number of characters from the beginning of the file). (The file will be cut at this point and then completed into a syntactically correct file.)
  • file : the file in which the completion is to be performed.
Specific Options:
  • -I dir : add a directory to the list of directories where files are searched for.
  • -expand from-to : this option is used to specify the position of the pattern-matching variable to be expanded.
  • -printer : selects the output format. Default is XML; use value ocaml-pp to specify a plain text format.
  • -parser : sets the default parser. This option is reserved for a possible later use.
  • -match-depth int : sets the maximal depth of the generated patterns. Default value is 1.
  • -match-annot : use information contained in .annot and .cmi files to compute the result of a pattern-matching completion, instead of ocamlwizard's internal typechecker. This option is to be used only when ocamlwizard compile cannot be used.

  • Compile
ocamlwizard compile <options> <files>

This command behaves exactly as the Ocaml compiler, expect that it produces .owz files instead of .cmi or .cmo files. (.owz files are similar to .cmi files, with additional information used by locate and refactor commands.) This command can only be applied on files which are syntactically and semantically correct.

  • files : the list of files to be compiled
  • options : options similar to the ones passed to Ocaml compiler
Integration into Makefiles:

The simplest way to patch an existing Makefile to make it ocamlwizard-compliant is to add ocamlwizard compile command beside the usual Ocaml compiler commands, as follows:

For bytecode compilation, update the rules as follows:

.mli.cmi :
ocamlwizard compile $(FLAGS) $<
ocamlc -c $(FLAGS) $<
.ml.cmo :
ocamlwizard compile $(FLAGS) $<
ocamlc -c $(FLAGS) $<

For native code compilation, add the following line:

.ml.cmx :
ocamlwizard compile $(FLAGS) $<
ocamlopt -c $(FLAGS) $<

  • Locate
ocamlwizard <options> locate <ident> <from-to> <file>

This command can be used on use points of:

  • values
  • types
  • record fields
  • constructors (including exceptions)
  • modules (including functors)
  • signatures

This command displays the points of definition and/or declaration of the corresponding identifier.

Command line arguments:
  • options : directories where to search for .owz files can be specified here using the -I option
  • ident : the identifier which is searched for
  • from-to : the location of the identifier which is searched for (the location is used together with the identifier to identify the request)
  • file : the file containing the identifier which is searched for

The locate command uses information contained in .owz files produced by the compile command. It is thus a requirement for cross-files navigation that files referred to in the current file have already been processed with ocamlwizard compile. Moreover, the current file must be syntactically correct (the whole file) and it must typecheck up to identifier point.

  • Refactor
ocamlwizard [common options] refactor [sub-command] [sub-command's options]

Up to now, only refactoring of values is possible. The refactor command is currently in beta version and cannot be considered as fully operational. The available sub-commands are the following:

  • -rename
  • -depend
  • -qualif


This option allows the renaming of a value, in any declaration, definition and use of this value through the whole program, when this is possible. It computes the minimal substitution to be performed.

The syntax for this command is the following:

ocamlwizard [common options] refactor -rename int-int ident1 ident2 <target file> [options] <files>
  • int-int : location of the identifier to be renamed
  • ident1 : name of the value to be renamed (with a possible path if this is a use point)
  • ident2 : substitute name
  • target file : file in which the identifier is located
  • options : same options as ocamlc
  • files : the list of all files in which to perform the renaming, given in order compatible with module dependencies

Depend / Qualif

The syntax of these commands is the following:

ocamlwizard [common options] refactor [-depend|-qualif] int-int ident1 <target file> [options] <files>
(Similar to rename, but without ident2)


Localizes the declaration, definition and uses of the specified value (which can be specified through a declaration, definition or use point).

With the -debug option, a dependency graph is displayed (with the meaning of vertices printed on standard output).


This command suppresses unnecessary qualifications at the use points of the specified identifier.

Previous    |    Up    |    Next