User Manual
2. Commands
The syntax of ocamlwizard's command line is the following:
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:
- Completion
- Compile
- Locate
- Refactor
- Completion
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 «M.id» 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.
- -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
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.
Arguments:- files : the list of files to be compiled
- options : options similar to the ones passed to Ocaml compiler
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:
ocamlc -c $(FLAGS) $<
ocamlc -c $(FLAGS) $<
For native code compilation, add the following line:
ocamlopt -c $(FLAGS) $<
- Locate
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
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
Rename
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:
- 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:
Depend
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).Qualif
This command suppresses unnecessary qualifications at the use points of the specified identifier.
