Permalink
Fetching contributors…
Cannot retrieve contributors at this time
735 lines (573 sloc) 39.2 KB
\chapter{Compiler Features}
\label{cr-features}
\state{NoContent}
\section{Built-in Compiler Metadata}
\label{cr-metadata}
Starting from Haxe 3.0, you can get the list of defined compiler metadata by running \expr{haxe --help-metas}
\begin{center}
\begin{tabular}{| l | l | l |}
\hline
\multicolumn{3}{|c|}{Global metadata} \\ \hline
Metadata & Description & Platform \\ \hline
@:abi & Function ABI/calling convention & cpp \\
@:abstract & Sets the underlying class implementation as 'abstract' & cs java \\
@:access \_(Target path)\_ & Forces private access to package type or field, see \tref{Access Control}{lf-access-control} & all \\
@:allow \_(Target path)\_ & Allows private access from package type or field, see \tref{Access Control}{lf-access-control} & all \\
@:analyzer & Used to configure the static analyzer & all \\
@:annotation & Annotation (\expr{@interface}) definitions on \expr{-java-lib} imports will be annotated with this metadata. Has no effect on types compiled by Haxe & java \\
@:arrayAccess & Allows \tref{Array access}{types-abstract-array-access} on an abstract & all \\
@:autoBuild \_(Build macro call)\_ & Extends \expr{@:build} metadata to all extending and implementing classes. See \tref{Macro autobuild}{macro-auto-build} & all \\
@:bind & Override Swf class declaration & flash \\
@:bitmap \_(Bitmap file path)\_ & \_Embeds given bitmap data into the class (must extend \expr{flash.display.BitmapData}) & flash \\
@:bridgeProperties & Creates native property bridges for all Haxe properties in this class & cs \\
@:build \_(Build macro call)\_ & Builds a class or enum from a macro. See \tref{Type Building}{macro-type-building} & all \\
@:buildXml & Specify xml data to be injected into Build.xml & cpp \\
@:callable & Abstract forwards call to its underlying type & all \\
@:classCode & Used to inject platform-native code into a class & cs java \\
@:commutative & Declares an abstract operator as commutative & all \\
@:compilerGenerated & Marks a field as generated by the compiler. Shouldn't be used by the end user & cs java \\
@:coreApi & Identifies this class as a core api class (forces Api check) & all \\
@:coreType & Identifies an abstract as \tref{core type}{types-abstract-core-type} so that it requires no implementation & all \\
@:cppFileCode & Code to be injected into generated cpp file & cpp \\
@:cppInclude & File to be included in generated cpp file & cpp \\
@:cppNamespaceCode & & cpp \\
@:dce & Forces \tref{Dead Code Elimination}{cr-dce} even when not \expr{-dce full} is specified & all \\
@:debug & Forces debug information to be generated into the Swf even without \expr{-debug} & flash \\
@:decl & & cpp \\
@:delegate & Automatically added by \expr{-net-lib} on delegates & cs \\
@:depend & & cpp \\
@:deprecated & Automatically added by \expr{-java-lib} on class fields annotated with \expr{@Deprecated} annotation. Has no effect on types compiled by Haxe & java \\
@:event & Automatically added by \expr{-net-lib} on events. Has no effect on types compiled by Haxe & cs \\
@:enum & Defines finite value sets to abstract definitions. See \tref{enum abstracts}{types-abstract-enum} & all \\
@:expose \_(?Name=Class path)\_ & Makes the class available on the \expr{window} object or \expr{exports} for node.js. See \tref{exposing Haxe classes for JavaScript}{target-javascript-expose} & js \\
@:extern & Marks the field as extern so it is not generated & all \\
@:fakeEnum \_(Type name)\_ & Treat enum as collection of values of the specified type & all \\
@:file(File path) & Includes a given binary file into the target Swf and associates it with the class (must extend \expr{flash.utils.ByteArray}) & flash \\
@:final & Prevents a class from being extended & all \\
@:font \_(TTF path Range String)\_ & Embeds the given TrueType font into the class (must extend \expr{flash.text.Font}) & flash \\
@:forward \_(List of field names)\_ & \tref{Forwards field access}{types-abstract-forward} to underlying type & all \\
@:from & Specifies that the field of the abstract is a cast operation from the type identified in the function. See \tref{Implicit Casts}{types-abstract-implicit-casts} & all \\
@:functionCode & Injects native code into the beginning of the function & cs cpp \\
@:functionTailCode & Injects native code into the end of the function & cpp \\
@:generic & Marks a class or class field as \tref{generic}{type-system-generic} so each type parameter combination generates its own type/field & all \\
@:genericBuild & Builds instances of a type using the specified macro & all \\
@:getter \_(Class field name)\_ & Generates a native getter function on the given field & flash \\
@:hack & Allows extending classes marked as \expr{@:final} & all \\
@:headerClassCode & Code to be injected into the generated class, in the header & cpp \\
@:headerCode & Code to be injected into the generated header file & cpp \\
@:headerNamespaceCode & & cpp \\
@:hxGen & Annotates that an extern class was generated by Haxe & cs java \\
@:ifFeature \_(Feature name)\_ & Causes a field to be kept by \tref{DCE}{cr-dce} if the given feature is part of the compilation & all \\
@:include & & cpp \\
@:internal & Generates the annotated field/class with \expr{internal} access & cs java \\
@:isVar & Forces a physical field to be generated for properties that otherwise would not require one & all \\
@:javaCanonical \_(Output type package,Output type name)\_ & Used by the Java target to annotate the canonical path of the type & java \\
@:jsRequire & Generate javascript module require expression for given extern & js \\
@:keep & Causes a field or type to be kept by \tref{DCE}{cr-dce} & all \\
@:keepInit & Causes a class to be kept by \tref{DCE}{cr-dce} even if all its field are removed & all \\
@:keepSub & Extends \expr{@:keep} metadata to all implementing and extending classes & all \\
@:macro & \_(deprecated)\_ & all \\
@:mergeBlock & Merge the annotated block into the current scope & all \\
@:meta & Internally used to mark a class field as being the metadata field & all \\
@:multiType \_(Relevant type parameters)\_ & Specifies that an abstract chooses its this-type from its \expr{@:to} functions & all \\
@:native \_(Output type path)\_ & Rewrites the path of a class or enum during generation & all \\
@:native & Add the \expr{native} keyword to the generated field (JNI) & java \\
@:nativeChildren & Annotates that all children from a type should be treated as if it were an extern definition - platform native & cs java \\
@:nativeGen & Annotates that a type should be treated as if it were an extern definition - platform native & cs java \\
@:nativeProperty & Use native properties which will execute even with dynamic usage & cpp \\
@:noCompletion & Prevents the compiler from suggesting \tref{completion}{cr-completion} on this field & all \\
@:noDebug & Does not generate debug information into the Swf even if \expr{-debug} is set & flash \\
@:noDoc & Prevents a type from being included in documentation generation & all \\
@:noImportGlobal & Prevents a static field from being imported with \expr{import Class.*} & all \\
@:noPrivateAccess & Disallow private access to anything for the annotated expression & all \\
@:noStack & & cpp \\
@:noUsing & Prevents a field from being used with \expr{using} & all \\
@:nonVirtual & Declares function to be non-virtual & cpp \\
@:notNull & Declares an abstract type as not accepting \tref{\expr{null} values}{types-nullability} & all \\
@:ns & Internally used by the Swf generator to handle namespaces & flash \\
@:op \_(The operation)\_ & Declares an abstract field as being an \tref{operator overload}{types-abstract-operator-overloading} & all \\
@:optional & Marks the field of a structure as optional. See \tref{Optional Arguments}{types-nullability-optional-arguments} & all \\
@:overload \_(Function specification)\_ & Allows the field to be called with different argument types. Function specification cannot be an expression & all \\
@:privateAccess & Allow private access to anything for the annotated expression & all \\
@:property & Marks a property field to be compiled as a native C\# property & cs \\
@:protected & Marks a class field as being protected & all \\
@:public & Marks a class field as being public & all \\
@:publicFields & Forces all class fields of inheriting classes to be public & all \\
@:pythonImport & Generates python import statement for extern classes & python \\
@:readOnly & Generates a field with the \expr{readonly} native keyword & cs \\
@:remove & Causes an interface to be removed from all implementing classes before generation & all \\
@:require \_(Compiler flag to check)\_ & Allows access to a field only if the specified \tref{compiler flag}{lf-condition-compilation} is set & all \\
@:rtti & Adds runtime type informations. See \tref{RTTI}{cr-rtti} & all \\
@:runtime & & all \\
@:runtimeValue & Marks an abstract as being a runtime value & all \\
@:selfCall & Translates method calls into calling object directly & js \\
@:setter \_(Class field name)\_ & Generates a native setter function on the given field & flash \\
@:sound \_(File path)\_ & Includes a given \_.wav\_ or \_.mp3\_ file into the target Swf and associates it with the class (must extend \expr{flash.media.Sound}) & flash \\
@:sourceFile & Source code filename for external class & cpp \\
@:strict & Used to declare a native C\# attribute or a native Java metadata. Is type checked & cs java \\
@:struct & Marks a class definition as a struct & cs \\
@:structAccess & Marks an extern class as using struct access('.') not pointer('->') & cpp \\
@:suppressWarnings & Adds a SuppressWarnings annotation for the generated Java class & java \\
@:throws \_(Type as String)\_ & Adds a \expr{throws} declaration to the generated function & java \\
@:to & Specifies that the field of the abstract is a cast operation to the type identified in the function. See \tref{Implicit Casts}{types-abstract-implicit-casts} & all \\
@:transient & Adds the \expr{transient} flag to the class field & java \\
@:unbound & Compiler internal to denote unbounded global variable & all \\
@:unifyMinDynamic & Allows a collection of types to unify to Dynamic & all \\
@:unreflective & & cpp \\
@:unsafe & Declares a class or a method with the C\#'s \expr{unsafe} flag & cs \\
@:value & Used to store default values for fields and function arguments & all \\
@:void & Use Cpp native 'void' return type & cpp \\
@:volatile & & cs java \\
\end{tabular}
\end{center}
\section{Dead Code Elimination}
\label{cr-dce}
Dead Code Elimination or \emph{DCE} is a compiler feature which removes unused code from the output. After typing, the compiler evaluates the DCE entry-points (usually the main-method) and recursively determines which fields and types are used. Used fields are marked accordingly and unmarked fields are then removed from their classes.
DCE has three modes which are set when invoking the command line:
\begin{description}
\item[-dce std:] Only classes in the Haxe Standard Library are affected by DCE. This is the default setting on all targets.
\item[-dce no:] No DCE is performed.
\item[-dce full:] All classes are affected by DCE.
\end{description}
The DCE-algorithm works well with typed code, but may fail when \tref{dynamic}{types-dynamic} or \tref{reflection}{std-reflection} is involved. This may require explicit marking of fields or classes as being used by attributing the following metadata:
\begin{description}
\item[\expr{@:keep}:] If used on a class, the class along with all fields is unaffected by DCE. If used on a field, that field is unaffected by DCE.
\item[\expr{@:keepSub}:] If used on a class, it works like \expr{@:keep} on the annotated class as well as all subclasses.
\item[\expr{@:keepInit}:] Usually, a class which had all fields removed by DCE (or is empty to begin with) is removed from the output. By using this metadata, empty classes are kept.
\end{description}
If a class needs to be marked with \expr{@:keep} from the command line instead of editing its source code, there is a compiler macro available for doing so: \expr{--macro keep('type dot path')} See the \href{http://api.haxe.org/haxe/macro/Compiler.html#keep}{haxe.macro.Compiler.keep API} for details of this macro. It will mark package, module or sub-type to be kept by DCE and includes them for compilation.
The compiler automatically defines the flag \expr{dce} with a value of either \expr{"std"}, \expr{"no"} or \expr{"full"} depending on the active mode. This can be used in \tref{conditional compilation}{lf-condition-compilation}.
\trivia{DCE-rewrite}{DCE was originally implemented in Haxe 2.07. This implementation considered a function to be used when it was explicitly typed. The problem with that was that several features, most importantly interfaces, would cause all class fields to be typed in order to verify type-safety. This effectively subverted DCE completely, prompting the rewrite for Haxe 2.10.}
\trivia{DCE and try.haxe.org}{DCE for the \type{JavaScript} target saw vast improvements when the website \url{http://try.haxe.org} was published. Initial reception of the generated \target{JavaScript} code was mixed, leading to a more fine-grained selection of which code to eliminate.}
\section{Compiler Services}
\label{cr-completion}
\state{NoContent}
\subsection{Overview}
\label{cr-completion-overview}
The rich \tref{type system}{type-system} of the Haxe Compiler makes it difficult for IDEs and editors to provide accurate completion information. Between \tref{type inference}{type-system-type-inference} and \tref{macros}{macro}, 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 \ic{--display file@position[@mode]} compiler argument. The required arguments are:
\begin{description}
\item[file:] The file to check for completion. This must be an absolute or relative path to a .hx file. It does not respect any class paths or libraries.
\item[position:] The byte position (not character position) of where to check for completion in the given file.
\item[mode:] The completion mode to use (see below).
\end{description}
We will look into the following completion modes in detail:
\begin{description}
\item[\tref{Field access}{cr-completion-field-access}:] Provides a list of fields that can be accessed on a given type.
\item[\tref{Call argument}{cr-completion-call-argument}:] Reports the type of the function which is currently being called.
\item[\tref{Type path}{cr-completion-type-path}:] Lists sub-packages, sub-types and static fields.
\item[\tref{Usage}{cr-completion-usage}:] Lists all occurrences of a given type, field or variable in all compiled files. (mode: \ic{"usage"})
\item[\tref{Position}{cr-completion-position}:] Reports the position of where a given type, field or variable is defined. (mode: \ic{"position"})
\item[\tref{Top-level}{cr-completion-top-level}:] Lists all identifiers which are available at a given position. (mode: \ic{"toplevel"})
\end{description}
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 \tref{server mode}{cr-completion-server} which ensures that only those files are re-compiled that actually changed or had any of their dependencies changes.
\paragraph{General notes on the interface}
\label{cr-completion-interface-notes}
\begin{itemize}
\item The position-argument can be set to 0 if the file in question contains a pipeline \ic{|} 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 \ic{|} is not valid syntax otherwise, e.g. after dots (\ic{.|}) and opening parentheses (\ic{(|}).
\item The output is HTML-escaped so that \ic{\&}, \ic{<} and \ic{>} become \ic{\&amp;}, \ic{\&lt;} and \ic{\&gt;} respectively.
\item Otherwise any documentation output is preserved which means longer documentation might include new-line and tab-characters as it does in the source files.
\item When run 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.
\end{itemize}
\subsection{Field access completion}
\label{cr-completion-field-access}
Field completion is triggered after a dot \ic{.} character to list the fields that are available on the given type. The compiler parses and types everything up to the point of completion and then outputs the relevant information to stderr:
\begin{lstlisting}
class Main {
public static function main() {
trace("Hello".|
}
}
\end{lstlisting}
If this file is saved to Main.hx, the completion can be invoked using the command \ic{haxe --display Main.hx@0}. The output looks similar to this (we omit several fields for brevity and improve the formatting for readability):
\lang{xml}\begin{lstlisting}
<list>
<i n="length">
<t>Int</t>
<d>
The number of characters in `this` String.
</d>
</i>
<i n="charAt">
<t>index : Int -&gt; String</t>
<d>
Returns the character at position `index` of `this` String.
If `index` is negative or exceeds `this.length`, the empty String
"" is returned.
</d>
</i>
<i n="charCodeAt">
<t>index : Int -&gt; Null&lt;Int&gt;</t>
<d>
Returns the character code at position `index` of `this` String.
If `index` is negative or exceeds `this.length`, null is returned.
To obtain the character code of a single character, "x".code can
be used instead to inline the character code at compile time.
Note that this only works on String literals of length 1.
</d>
</i>
</list>
\end{lstlisting}
The XML structure follows:
\begin{itemize}
\item The document node \ic{list} encloses several nodes \ic{i}, each representing a field.
\item The \ic{n} attribute contains the name of the field.
\item The \ic{t} node contains the type of the field.
\item the \ic{d} node contains the documentation of the field.
\end{itemize}
\since{3.2.0}
When compiling with \ic{-D display-details}, each field additionally has a \ic{k} attribute which can either be \ic{var} or \ic{method}. This allows distinguishing method fields from variable fields that have a function type.
\subsection{Call argument completion}
\label{cr-completion-call-argument}
Call argument completion is triggered after an opening parenthesis character \ic{(} to show the type of the function that is currently being called. It works for any function call as well as constructor calls:
\begin{lstlisting}
class Main {
public static function main() {
trace("Hello".split(|
}
}
\end{lstlisting}
If this file is saved to Main.hx, the completion can be invoked using the command \ic{haxe --display Main.hx@0}. The output looks like this:
\lang{xml}\begin{lstlisting}
<type>
delimiter : String -&gt; Array&lt;String&gt;
</type>
\end{lstlisting}
IDEs can parse this to recognize that the called function requires one argument named \ic{delimiter} of type \type{String} and returns an \type{Array<String>}.
\trivia{Problems with the output structure}{We acknowledge that the current format requires a bit of manual parsing which can be annoying. In the future we might look into providing a more structured output, especially for functions.}
\subsection{Type path completion}
\label{cr-completion-type-path}
Type path completion can occur in \tref{import declarations}{type-system-import}, \tref{using declarations}{lf-static-extension} or any place a type is referenced. We can identify three different cases:
\paragraph{package completion}
This lists all sub-packages of the haxe package as well as all modules in that package:
\begin{lstlisting}
import haxe.|
\end{lstlisting}
\lang{xml}\begin{lstlisting}
<list>
<i n="CallStack"><t></t><d></d></i>
<i n="Constraints"><t></t><d></d></i>
<i n="DynamicAccess"><t></t><d></d></i>
<i n="EnumFlags"><t></t><d></d></i>
<i n="EnumTools"><t></t><d></d></i>
<i n="Http"><t></t><d></d></i>
<i n="Int32"><t></t><d></d></i>
<i n="Int64"><t></t><d></d></i>
<i n="Json"><t></t><d></d></i>
<i n="Log"><t></t><d></d></i>
<i n="PosInfos"><t></t><d></d></i>
<i n="Resource"><t></t><d></d></i>
<i n="Serializer"><t></t><d></d></i>
<i n="Template"><t></t><d></d></i>
<i n="Timer"><t></t><d></d></i>
<i n="Ucs2"><t></t><d></d></i>
<i n="Unserializer"><t></t><d></d></i>
<i n="Utf8"><t></t><d></d></i>
<i n="crypto"><t></t><d></d></i>
<i n="ds"><t></t><d></d></i>
<i n="extern"><t></t><d></d></i>
<i n="format"><t></t><d></d></i>
<i n="io"><t></t><d></d></i>
<i n="macro"><t></t><d></d></i>
<i n="remoting"><t></t><d></d></i>
<i n="rtti"><t></t><d></d></i>
<i n="unit"><t></t><d></d></i>
<i n="web"><t></t><d></d></i>
<i n="xml"><t></t><d></d></i>
<i n="zip"><t></t><d></d></i>
</list>
\end{lstlisting}
\paragraph{import module completion}
This lists all \tref{sub-types}{type-system-module-sub-types} of the module \type{haxe.Unserializer} as well as all its public static fields (because these can be imported too):
\begin{lstlisting}
import haxe.Unserializer.|
\end{lstlisting}
\lang{xml}\begin{lstlisting}
<list>
<i n="DEFAULT_RESOLVER">
<t>haxe.TypeResolver</t>
<d>
This value can be set to use custom type resolvers.
A type resolver finds a Class or Enum instance from a given String.
By default, the haxe Type Api is used.
A type resolver must provide two methods:
1. resolveClass(name:String):Class&lt;Dynamic&gt; is called to
determine a Class from a class name
2. resolveEnum(name:String):Enum&lt;Dynamic&gt; is called to
determine an Enum from an enum name
This value is applied when a new Unserializer instance is created.
Changing it afterwards has no effect on previously created
instances.
</d>
</i>
<i n="run">
<t>v : String -&gt; Dynamic</t>
<d>
Unserializes `v` and returns the according value.
This is a convenience function for creating a new instance of
Unserializer with `v` as buffer and calling its unserialize()
method once.
</d>
</i>
<i n="TypeResolver"><t></t><d></d></i>
<i n="Unserializer"><t></t><d></d></i>
</list>
\end{lstlisting}
\begin{lstlisting}
using haxe.Unserializer.|
\end{lstlisting}
\paragraph{other module completion}
This lists all \tref{sub-types}{type-system-module-sub-types} of the module \type{haxe.Unserializer}:
\begin{lstlisting}
using haxe.Unserializer.|
\end{lstlisting}
\begin{lstlisting}
class Main {
static public function main() {
var x:haxe.Unserializer.|
}
}
\end{lstlisting}
\lang{xml}\begin{lstlisting}
<list>
<i n="TypeResolver"><t></t><d></d></i>
<i n="Unserializer"><t></t><d></d></i>
</list>
\end{lstlisting}
\subsection{Usage completion}
\label{cr-completion-usage}
\since{3.2.0}
Usage completion is enabled by using the \ic{"usage"} mode argument (see \Fullref{cr-completion-overview}). We demonstrate it here using a local variable. Note that it would work with fields and types the same way:
\begin{lstlisting}
class Main {
public static function main() {
var a = 1;
var b = a + 1;
trace(a);
a.|
}
}
\end{lstlisting}
If this file is saved to Main.hx, the completion can be invoked using the command \ic{haxe --display Main.hx@0@usage}. The output looks like this:
\lang{xml}\begin{lstlisting}
<list>
<pos>main.hx:4: characters 9-10</pos>
<pos>main.hx:5: characters 7-8</pos>
<pos>main.hx:6: characters 1-2</pos>
</list>
\end{lstlisting}
\subsection{Position completion}
\label{cr-completion-position}
\since{3.2.0}
Position completion is enabled by using the \ic{"position"} mode argument (see \Fullref{cr-completion-overview}). We demonstrate it using a field. Note that it would work with local variables and types the same way:
\begin{lstlisting}
class Main {
static public function main() {
"foo".split.|
}
\end{lstlisting}
If this file is saved to Main.hx, the completion can be invoked using the command \ic{haxe --display Main.hx@0@position}. The output looks like this:
\lang{xml}\begin{lstlisting}
<list>
<pos>std/string.hx:124: characters 1-54</pos>
</list>
\end{lstlisting}
\trivia{Effects of omitting a target specifier}{In this example the compiler reports the standard String.hx definition which does not actually have an implementation. This happens because we did not specify any target, which is allowed in completion-mode. If the command line arguments included, say, \ic{-neko neko.n}, the reported position would instead be \ic{std/neko/_std/string.hx:84: lines 84-98}.}
\subsection{Top-level completion}
\label{cr-completion-top-level}
\since{3.2.0}
Top-level completion displays all identifiers which the Haxe Compiler knows about at a given compilation position. This is the only completion method for which we need a real position argument in order to demonstrate its effect:
\begin{lstlisting}
class Main {
static public function main() {
var a = 1;
}
}
enum MyEnum {
MyConstructor1;
MyConstructor2(s:String);
}
\end{lstlisting}
If this file is saved to Main.hx, the completion can be invoked using the command \ic{haxe --display Main.hx@63@toplevel}. The output looks similar to this (we omit several entries for brevity):
\lang{xml}\begin{lstlisting}
<il>
<i k="local" t="Int">a</i>
<i k="static" t="Void -&gt; Unknown&lt;0&gt;">main</i>
<i k="enum" t="MyEnum">MyConstructor1</i>
<i k="enum" t="s : String -&gt; MyEnum">MyConstructor2</i>
<i k="package">sys</i>
<i k="package">haxe</i>
<i k="type" p="Int">Int</i>
<i k="type" p="Float">Float</i>
<i k="type" p="MyEnum">MyEnum</i>
<i k="type" p="Main">Main</i>
</il>
\end{lstlisting}
The structure of the XML depends on the \ic{k} attribute of each entry. In all cases the node value of the \ic{i} nodes contains the relevant name.
\begin{description}
\item[\ic{local}, \ic{member}, \ic{static}, \ic{enum}, \ic{global}:] The \ic{t} attribute holds the type of the variable or field.
\item[\ic{global}, \ic{type}:] The \ic{p} attribute holds the path of the module which contains the type or field.
\end{description}
\subsection{Completion server}
\label{cr-completion-server}
To get the best speed for both compilation and completion, you can use the \ic{--wait} command-line parameter to start a Haxe compilation server. You can also use \ic{-v} to have the server print the log. Here's an example:
\lang{hxml}\begin{lstlisting}
haxe -v --wait 6000
\end{lstlisting}
You can then connect to the Haxe server, send command-line parameters followed by a 0 byte and, then, read the response (either completion result or errors).
Use the \ic{--connect} command-line parameter to have Haxe send its compilation commands to the server instead of executing them directly :
\lang{hxml}\begin{lstlisting}
haxe --connect 6000 myproject.hxml
\end{lstlisting}
Please note that you can use the parameter \ic{--cwd} at the first sent command line to change the Haxe server's current working directory. Usually class paths and other files are relative to your project.
\paragraph{How it works}
The compilation server will cache the following things:
\begin{description}
\item[parsed files] the files will only get parsed again if they are modified or if there was a parse error
\item[haxelib calls] the previous results of haxelib calls will be reused (only for completion : they are ignored when doing a compilation)
\item[typed modules] compilation modules will be cached after a successful compilation and can be reused in later compilation/completions if none of their dependencies have been modified
\end{description}
You can get precise reading of the times spent by the compiler and how using the compilation server affects them by adding \ic{--times} to the command line.
\paragraph{Protocol}
As the following Haxe/Neko example shows, you can simply connect on the server port and send all commands (one per line) ending with a 0 binary char. You can, then, read the results.
Macros and other commands can log events which are not errors. From the command line, we can see the difference between what is printed on \ic{stdout} and what is print on \ic{stderr}. This is not the case in socket mode. In order to differentiate between the two, log messages (not errors) are prefixed with a \ic{\\x01} character and all newline-characters in the message are replaced by the same \ic{\\x01} character.
Warnings and other messages can also be considered errors, but are not fatal ones. If a fatal error occurred, it will send a single \ic{\\x02} message-line.
Here's some code that will treat connection to the server and handle the protocol details:
\haxe{assets/CompletionServer.hx}
\paragraph{Effect on macros}
The compilation server can have some side effects on \tref{macro execution}{macro}.
\section{Resources}
\label{cr-resources}
\flag{fold}{true}
Haxe provides a simple resource embedding system that can be used for embedding files directly into the compiled application.
While it may be not optimal to embed large assets such as images or music in the application file, it comes in very handy for embedding smaller resources like configuration or XML data.
\subsection{Embedding resources}
\label{cr-resources-embed}
External files are embedded using the \emph{-resource} compiler argument:
\lang{hxml}\begin{lstlisting}
-resource hello_message.txt@welcome
\end{lstlisting}
The string after the \emph{@} symbol is the \emph{resource identifier} which is used in the code for retrieving the resource. If it is omitted (together with the \emph{@} symbol) then the file name will become the resource identifier.
\subsection{Retrieving text resources}
\label{cr-resources-getString}
To retrieve the content of an embedded resource we use the static method \emph{getString} of \type{haxe.Resource}, passing a \emph{resource identifier} to it:
\haxe{assets/ResourceGetString.hx}
The code above will display the content of the \emph{hello_message.txt} file that we included earlier using \emph{welcome} as the identifier.
\subsection{Retrieving binary resources}
\label{cr-resources-getBytes}
While it's not recommended to embed large binary files in the application, it still may be useful to embed binary data. The binary representation of an embedded resource can be accessed using the static method \emph{getBytes} of \type{haxe.Resource}:
\haxe{assets/ResourceGetBytes.hx}
The return type of \emph{getBytes} method is \type{haxe.io.Bytes}, which is an object providing access to individual bytes of the data.
\subsection{Implementation details}
\label{cr-resources-impl}
Haxe uses the target platform's native resource embedding if there is one, otherwise it provides its own implementation.
\begin{itemize}
\item \emph{Flash} resources are embedded as ByteArray definitions
\item \emph{C\#} resources are included in the compiled assembly
\item \emph{Java} resources are packed in the resulting JAR file
\item \emph{C++} resources are stored in global byte array constants.
\item \emph{JavaScript} resources are serialized in Haxe serialization format and stored in a static field of \type{haxe.Resource} class.
\item \emph{Neko} resources are stored as strings in a static field of \type{haxe.Resource} class.
\end{itemize}
\section{Runtime Type Information}
\label{cr-rtti}
The Haxe compiler generates runtime type information (RTTI) for classes that are annotated or extend classes that are annotated with the \expr{:rtti} metadata. This information is stored as a XML string in a static field \expr{__rtti} and can be processed through \type{haxe.rtti.XmlParser}. The resulting structure is described in \Fullref{cr-rtti-structure}.
\since{3.2.0}
The type \type{haxe.rtti.Rtti} has been introduced in order to simplify working with RTTI. Retrieving this information is now very easy:
\haxe{assets/RttiUsage.hx}
\subsection{RTTI structure}
\label{cr-rtti-structure}
\paragraph{General type information}
\begin{description}
\item[path:] The \tref{type path}{define-type-path} of the type.
\item[module:] The type path of the \tref{module}{define-module} containing the type.
\item[file:] The full slash path of the .hx file containing the type. This might be \expr{null} in case there is no such file, e.g. if the type is defined through a \tref{macro}{macro}.
\item[params:] An array of strings representing the names of the \tref{type parameters}{type-system-type-parameters} the type has. As of Haxe 3.2.0, this does not include the \tref{constraints}{type-system-type-parameter-constraints}.
\item[doc:] The documentation of the type. This information is only available if the \tref{compiler flag}{define-compiler-flag} \expr{-D use_rtti_doc} was in place. Otherwise, or if the type has no documentation, the value is \expr{null}.
\item[isPrivate:] Whether or not the type is \tref{private}{define-private-type}.
\item[platforms:] A list of strings representing the targets where the type is available.
\item[meta:] The meta data the type was annotated with.
\end{description}
\paragraph{Class type information}
\label{cr-rtti-class-type-information}
\begin{description}
\item[isExtern:] Whether or not the class is \tref{extern}{lf-externs}.
\item[isInterface:] Whether or not the class is actually an \tref{interface}{types-interfaces}.
\item[superClass:] The class' parent class defined by its type path and list of type parameters.
\item[interfaces:] The list of interfaces defined by their type path and list of type parameters.
\item[fields:] The list of member \tref{class fields}{class-field}, described in \Fullref{cr-rtti-class-field-information}.
\item[statics:] The list of static class fields, described in \Fullref{cr-rtti-class-field-information}.
\item[tdynamic:] The type which is \tref{dynamically implemented}{types-dynamic-implemented} by the class or \expr{null} if no such type exists.
\end{description}
\paragraph{Enum type information}
\begin{description}
\item[isExtern:] Whether or not the enum is \tref{extern}{lf-externs}.
\item[constructors:] The list of enum constructors.
\end{description}
\paragraph{Abstract type information}
\begin{description}
\item[to:] An array containing the defined \tref{implicit to casts}{types-abstract-implicit-casts}.
\item[from:] An array containing the defined \tref{implicit from casts}{types-abstract-implicit-casts}.
\item[impl:] The \tref{class type information}{cr-rtti-class-type-information} of the implementing class.
\item[athis:] The \tref{underlying type}{define-underlying-type} of the abstract.
\end{description}
\paragraph{Class field information}
\label{cr-rtti-class-field-information}
\begin{description}
\item[name:] The name of the field.
\item[type:] The type of the field.
\item[isPublic:] Whether or not the field is \tref{public}{class-field-visibility}.
\item[isOverride:] Whether or not the field \tref{overrides}{class-field-override} another field.
\item[doc:] The documentation of the field. This information is only available if the \tref{compiler flag}{define-compiler-flag} \expr{-D use_rtti_doc} was in place. Otherwise, or if the field has no documentation, the value is \expr{null}.
\item[get:] The \tref{read access behavior}{define-read-access} of the field.
\item[set:] The \tref{write access behavior}{define-write-access} of the field.
\item[params:] An array of strings representing the names of the \tref{type parameters}{type-system-type-parameters} the field has. As of Haxe 3.2.0, this does not include the \tref{constraints}{type-system-type-parameter-constraints}.
\item[platforms:] A list of strings representing the targets where the field is available.
\item[meta:] The meta data the field was annotated with.
\item[line:] The line number where the field is defined. This information is only available if the field has an expression. Otherwise the value is \expr{null}.
\item[overloads:] The list of available overloads for the fields or \expr{null} if no overloads exists.
\end{description}
\paragraph{Enum constructor information}
\label{cr-rtti-enum-constructor-information}
\begin{description}
\item[name:] The name of the constructor.
\item[args:] The list of arguments the constructor has or \expr{null} if no arguments are available.
\item[doc:] The documentation of the constructor. This information is only available if the \tref{compiler flag}{define-compiler-flag} \expr{-D use_rtti_doc} was in place. Otherwise, or if the constructor has no documentation, the value is \expr{null}.
\item[platforms:] A list of strings representing the targets where the constructor is available.
\item[meta:] The meta data the constructor was annotated with.
\end{description}
\section{Static Analyzer}
\label{cr-static-analyzer}
\since{3.3.0}
Haxe 3.3.0 introduces a new static analyzer for code optimizations. It is enabled by using the \ic{-D analyzer-optimize} \tref{compiler flag}{compiler-usage-flags} and consists of multiple \tref{modules}{cr-static-analyzer-modules} which can be configured globally with a \tref{compiler flag}{compiler-usage-flags} as well as at type-level and field-level with a \tref{compiler metadata}{cr-metadata}:
\paragraph{Global configuration}
\label{cr-static-analyzer-global-configuration}
To globally enable an analyzer module \ic{-D analyzer-module} is used. To globally disable a module \ic{-D analyzer-no-module} is used. In both cases ``module'' represents the name of the module to be disabled or enabled:
\lang{hxml}\begin{lstlisting}
# Global enable from command line
haxe -D analyzer-module
# Global disable from command line
haxe -D analyzer-no-module
\end{lstlisting}
\paragraph{Local configuration}
\label{cr-static-analyzer-local-configuration}
To enable an analyzer module for a given type or field \ic{@:analyzer(module)} is used. To disable a module \ic{@:analyzer(no_module)} is used. In both cases ``module'' represents the name of the module to be disabled or enabled:
\begin{lstlisting}
@:analyzer(module)
class C {
@:analyzer(module) function f() { } // Field-level enable
@:analyzer(no_module) function f() { } // Field-level disable
}
@:analyzer(no_module)
class D { } // Type-level disable
\end{lstlisting}
\paragraph{Modules}
\label{cr-static-analyzer-modules}
The static analyzer currently comes with the following modules. Unless noted otherwise they are enabled if \ic{-D analyzer} is used.
\begin{description}
\item[\ic{const_propagation}]: Implements sparse conditional constant propagation to promote values that are known at compile-time to usage places. Also detects dead branches.
\item[\ic{copy_propagation}]: Detects local variables that alias other local variables and replaces them accordingly.
\item[\ic{local_dce}]: Detects and removes unused local variables.
\item[\ic{fusion}]: Moves variable expressions to its usage in case of single-occurrence. By default, only compiler-generated variables are handled. This can be changed by using the compiler flag `\ic{-D analyzer-user-var-fusion} or the metadata \ic{@:analyzer(user_var_fusion)}.
\item[\ic{purity_inference}]: Infers if fields are ``pure'', i.e. do not have any side-effects. This can improve the effect of the fusion module.
\end{description}