8.3.1 Overview
The rich type system of the Haxe Compiler makes it difficult for IDEs and editors to provide accurate completion information. Between type inference and macros, it would require a substantial amount of work to replicate the required processing. This is why the Haxe Compiler comes with a built-in completion mode for third-party software to use.
All completion is triggered using the --display file@position[@mode] compiler argument. The required arguments are:
- file: The file to check for completion. This must be an absolute or relative path to a .hx file. It does not respect any classpaths or libraries.
- position: The byte position (not character position) of where to check for completion in the given file.
- mode: The completion mode to use (see below).
We will look into the following completion modes in detail:
- Field access: Provides a list of fields that can be accessed on a given type.
- Call argument: Reports the type of the function which is currently being called.
- Type path: Lists sub-packages, sub-types and static fields.
- Usage: Lists all occurrences of a given type, field or variable in all compiled files. (mode:
"usage") - Position: Reports the position of where a given type, field or variable is defined. (mode:
"position") - Top-level: Lists all identifiers which are available at a given position. (mode:
"toplevel")
Due to Haxe being a very fast compiler, it is often sufficient to rely on the normal compiler invocation for completion. For bigger projects, Haxe provides a server mode which ensures that only those files are re-compiled that actually changed or had any of their dependencies changes.
- The position-argument can be set to 0 if the file in question contains a pipeline
| character at the position of interest. This is very useful for demonstration and testing as it allows us to ignore the byte-counting process a real IDE would have to do. The examples in this section are making use of this feature. Note that this only works in places where | is not valid syntax otherwise, e.g. after dots (.|) and opening parentheses ((|). - The output is HTML-escaped so that
&, < and > become &, < and > respectively. - Otherwise any documentation output is preserved which means longer documentation might include new-line and tab-characters as it does in the source files.
- When running in completion mode, the compiler does not display errors but instead tries to ignore them or recover from them. If a critical error occurs while getting completion, the Haxe Compiler prints the error message instead of the completion output. Any non-XML output can be treated as a critical error message.