User Manual

3. Output formats

ocamlwizard provides several output formats, in order to ease its integration into existing IDEs. Currently, it provides

• an XML output
• a plain text output

The syntax of output depends on the command which is used, and detailed below.

• XML Format for Completion

header:

4 possible kinds of nodes:

• Match :
  <match expr_type=«t option» type = «AllCs»>
  

  <case pattern =«p::r» level =«0» selected=«true»>info</case> (* pattern : | p ::r --> *)
  <case pattern =«p::(a,b)» level =«1» selected=«true»>info </case>
  ...
  

  </match>
  
  expr_type: type of the expression on which we perform pattern-matching
  type: one of AllCs, MissCs or BranchCs
  
  level: depth of the pattern-matching
  selected: boolean which indicates whether the corresponding pattern must be displayed
  info: not available
  
  
• Module :
  <modules>
  

  <module name =«Mod» miss=«od» level =«0» selected=«true»>info</module>
  <module name =«Mod.M2» miss=«od.M2» level =«1» selected=«false»>info</module>
  ...
  

  </modules>
  
  name: completed expression
  miss: the missing part of the completed expression
  
  level: indicates the depth of this proposed expression
  (usually, only completions of minimal depth are proposed in IDEs)
  selected: boolean which indicates whether the corresponding patternexpression must be displayed
  
  info: not available
  
  
• Records :
  <records expr_type=«r»>
  

  <record path=«.M2.M3» name=«r» level =«0»>...</record>
  
  <record path=«.M1» name=«r1» level =«0» >

  <label name=«tempo» type=«int» selected=«true» miss=«po» mut=«false»>info</label>
  <label name=«temp» type=«bool» selected=«false» miss=«o» mut=«true»>info</label>
  <label name=«tempus» type=«float» selected=«false» miss=«us» mut=«true»>info</label>
  ...
  

  </record>
  ...
  

  </records>
  
  For records and record nodes:
  expr_type: type of the expression (optional value)
  path: path of module where the record type is defined
  name: name of the record type
  level: not available
  
  For label nodes:
  name: completed expression
  type: label type
  selected: indicates if the label must be displayed
  miss: missing part of the expression
  mut: indicates whether the label is mutable
  info: not available
  
  
• Value :
  <values>
  

  <value name=«M.x» miss=«.x» affect=«other» pattern_filter=«true» type_filter=«true» is_record=«false» level=«0» type=«int»>info</value>
  <value name=«M.b» miss=«.x» affect=«other» pattern_filter=«true» type_filter=«true» is_record=«false» level=«0» type=«bool»>info</value>
  ...
  

  </values>
  
  name: completed expression
  miss: missing part of the expression
  affect: missing par of the expression
  pattern_filter: indicates if the choice must be displayed
  level: depth of the proposed completion
  type: type of the proposition
  is_record: is this a record expression
  type_filter: relevance indicator (see below)
  
  

Limitations :

Ocamlwizard filters the possible completions according to the expected type of the completed expression (when available). However, there are limitations:
-Functions and tuples
-Incomplete conditional expressions
-Assignments, and more generally side effect expressions


Note that there is no filtering on record types

In practice, it is advised to display all completions in IDEs, and to keep the type filtering feature as an option.

• XML format for locate

Currently not available

• Plain Text Format for locate

This output may contain zero, one or two locations, in the following format:

• XML Format for Refactor

Header:

1. Depend Output: (depend is the opposite of locate)
   
   <locations>
   

   <defn>
   

   <pos value=«12» file=«test.ml»/>
   <pos value=«12» file=«test.ml» />
   

   </defn>
   <use>
   

   <pos value=«85» file=«autre.ml»/>
   <pos value=«90» file=«autre.ml» />
   

   </use>
   <decl>
   

   <pos value=«85» file=«autre.ml»/>
   <pos value=«90» file=«autre.ml» />
   

   </decl>
   ...
   <decl>
   

   <pos value=«12» file=«test_55.ml»/>
   <pos value=«12» file=«test_55.ml» />
   

   </decl>
   

   </locations>
   
   There is one kind of node for each category: declaration (decl), definition (defn) and use (use). All of them contain two locations (pos), one for the start and one for the end.
2. Rename/Qualif Output:

   These two commands have the same output format (since Qualif is a special case of Rename).

   <locations result= «Impossible» file=«toto.ml» loc=«12-15» >
   

   <warnings nb=«10»>
   

   <capture type=«Includ_is_cap » id=«f» cap_id=«g» local="true"/>
   

   <location type="old" loc=\"11-12\" file=\"toto2.ml\">
   <location type=«new_id» loc=«11-12» file=«toto2.ml»>

   </capture> ....
   

   </warnings>
   <errors nb=«3»>
   

   <capture type=«Loose_use» id=«f» cap_id=«g» local=«true» >
   

   <location type="actual" loc=\"11-12\" file=\"toto2.ml\"> (*current position*)
   <location type=«parent_decl» loc=«11-12» file=«toto2.ml»> (*position of the initial declaration or definition *)
   <path_captured id=«N.f»> (*id to be renamed*)
   

   <tested lid=«g» >

   <tested>
   <tested lid=«N.g» >

   <location type="parent_defn" loc=\"...\" file=\"...\">
   

   <tested>
   <tested lid=«K.M.N.g»>

   <location type="parent_defn" loc=\"...\" file=\"...\">
   

   <tested>
   ...
   

   </path_captured>
   <path_captured id=«N.M.f»> (*id to be renamed*)
   ...
   </path_captured>
   
   

   </capture>
   ...
   

   </errors>
   <subs_lis nb=«32» in_cascade=«32»>
   

   <substitution old_id=«M.f» new_id=«g» is_direct=«true»>
   

   <location type="use" loc=\"...\" file=\"...\">
   

   </substitution>
   <substitution old_id=«f» new_id=«M.g» is_direct=«false»>
   

   <location type="use" loc=\"...\" file=\"...\">
   

   </substitution>
   <substitution old_id=«f» new_id=«g» is_direct=«false»>
   

   <location type="defn" loc=\"...\" file=\"...\">
   

   </substitution>
   <substitution old_id=«f» new_id=«g» is_direct=«false»>
   

   <location type="decl" loc=\"...\" file=\"...\">
   

   </substitution>
   ...
   

   </subs_lis>
   

   </locations>
   

   locations

   result: 3 possible values: Impossible | Possible | Possible_with_warning
   (Possible_with_warning is still an experimental feature; it is advised not to perform the substitution when it appears.)
   file: filename where the refactoring was asked for
   loc: position where the refactoring was asked for
   

   errors/warnings

   These are messages to be displayed

   sub_lis

   This is the information to perform the substitution. The format of locations is similar to that of Depend (see above).
   

   capture

   In case of failure of the refactoring, Ocamlwizard tries to provide information about the conflicts, in capture nodes. type: may have the following values:
   • Include_has_cap | Include_is_cap | Defn_has_cap
   • | Defn_is_cap | Decl_conflict | Multiple_defn
   • | Loose_use | Capt_use
   id: local name of the variable to be renamed
   
   cap_id: variable with which there is a conflict
   
   

   location:

   type: may have the following values:
   
   • | include | newid | old | loc |
   • | loc1 |loc2 | actual | decl | defn
   • | use | parent_defn | parent_decl