Sugar hx Textmate

The sugar-hx TextMate bundle is available at github.
Note: This bundle won't work on Textmate 2.

Getting the Bundle


The recommended way to install and keep the bundle updated is to use the bundle manager GetBundles, which you can install with the following commands:
mkdir -p ~/Library/Application\ Support/TextMate/Bundles
cd !$
svn co http://svn.textmate.org/trunk/Review/Bundles/GetBundles.tmbundle/
osascript -e 'tell app "TextMate" to reload bundles'

Once GetBundles is installed, start it from TextMate via Bundles->GetBundles->"Get Bundles". In the search field, search for "sugar-hx" or "haxe", and then install the bundle that includes "Sugar-hx" in the description. You can keep the bundle up to date via GetBundles, as it will automatically update your copy directly from github.

You can also install the Haxe bundle by downloading the zip file at the download page, extracting it, renaming the folder to HaXe.tmbundle, and then double clicking on the resulting bundle file.

Configuring Textmate


By default, Textmate uses a basic search path (see this page). It is usually necessary to alter this, especially if you've built Haxe from source. The simplest way to set up Haxe is to create and set the HAXE_LIBRARY_PATH variable, and update the PATH variable to point to the appropriate binary for Haxe.

The easiest way to do this is: Preferences → Advanced → Shell Variables
Variable: HAXE_LIBRARY_PATH and Value /usr/lib/haxe/std:. (note the final colon and period)

Basic Features

  • Syntax Highlighting Support
  • Project Template
  • Common tab triggers for code blocks

Advanced Features

All of the advanced features require a project, since they typically rely on integrating the compiler output for both the current class file, as well as the current hxml file. The bundle comes with a simple haxe project template which gives an example of an appropriate TextMate Project setup.

HXML Build Specification

If an hxml file is active in the editor, Cmd-B will build according to the active file. If Haxe source code is active in the editor, pressing Cmd-B will build the current project using the project specific build file. The bundle will default to using a build file called "build.hxml" if no build file has been specified, and if "build.hxml" exists.

A different hxml file can be respecified using Cmd-Shift-B. The bundle will search the current project folder for all hxml files, and will present a list for selection. The current alternate build file location is saved in .tmbuild in the project root. This can be altered by hand if necessary to point to a file external to the project, but this is not recommended.

The build command produces an html display of the compiler output. If there are errors, clicking on the error will take you directly to the error indicated by the compiler. Alternatively, pressing a number key will jump immediately to the corresponding error location.

Code Completion


Code completion is triggered using the standard Esc key. However, it only replaces the default TextMate completions when triggered after a potential field, with an additional period or paren: field. or field(.

If a code completion request occurs, then the current build file specified will be built with a --display compiler directive at the current cursor location. If the current build file contains multiple target directives (using the --next compiler command), the build file will be split into several sections based on the --next locations. By default, only the first section is used for autocompletion. However, it is possible to specify an alternate build section by using a special hxml comment switch "# @tm-autocomplete". Using this switch will not affect normal compilation.

For instance, consider the following build file:

# build file
-main Foo
-X foo

--next
-main Bar
-X bar

Completions requested on this build file will be generated according to the first section, producing -X foo. If you use the tm-autocomplete switch:

# build file
-main Foo
-X foo

--next
-main Bar
-X bar
# @tm-autocomplete

Now completions will be performed on the second section.

Code completions triggered with Esc produce a small popup indicating if the field is a package, class, function, or property. If a function is selected, a snippet is automatically produced that allows for easy argument specification.

Import Helper


Imports can automatically be specified after an appropriate class name by pressing Cmd-I. This can be done in the following example:
class Demo
{
    public static function main(): Void
    {
        var h = new Timer|();
    }
}

This code has not imported a Timer class, so by pressing Cmd-I at the caret (|), a list pops up with possible classes, taken from the libraries and code paths indicated in the current project hxml. Selecting one of these classes will automatically insert an appropriate "import" command at the top of the file, without changing the current cursor position:
import haxe.Timer;
class Demo
{
    public static function main(): Void
    {
        var h = new Timer|();
    }
}

The import helper command can also be triggered after an import statement:

import Ti|
class Demo
{
    public static function main(): Void{}
}

This will present a similar list of possible classes, and will complete the import directive appropriately:

import haxe.Timer;
class Demo
{
    public static function main(): Void{}
}

There is also an unused import helper that will try and find imports that aren't used in the current file. This is triggered by Shift-Cmd-I.

AutoDoc Generation for Help


The command Shift-Cmd-H will create haxedoc generated documentation for the current project. This includes all external libraries and paths. The html content will be placed in a folder called ".haxedoc" located in the project directory root.

The command Cmd-H is a help command that will automatically open the corresponding autodoc generated html file for the class indicated under the cursor. This currently only works for classes, so other function names and keywords will fail to produce a result.

It is also possible to open a class referenced in the code directly by the command Ctrl-Cmd-O. Be careful with this command, as it will open the base Haxe class files as well. Those should not be modified in normal circumstances.

Smart JavaDoc comment blocks


The tab trigger "doc" has special behavior. Tab triggering doc before a class declaration will automatically insert a class snippet, with all relevant javadoc style "@" fields populated. Tab triggering doc before a method will automatically insert a method snippet, with all relevant method fields, etc. Tab triggering elsewhere will insert private documentation snippets.

Currently, haxedoc does not support JavaDoc style fields inside comment blocks, so the default behavior for AutoDoc commands will likely change if support is not added.

JS, SWF, and HTML output embedding


Since JS and SWF cannot output to STDOUT, it is commonly necessary to open or embed them with additional commands. The TextMate bundle will embed JS and SWF output into the build results if the hxml comment switch "# @tm-preview" is included somewhere in the hxml.

In addition, it is possible to include arbitrary html in the output with the "# @tm-html" switch. Any additional text added on the same line after this switch will automatically get inserted into the build results. For instance,
this command will add a haxe logo to the build result:

# @tm-html <img src=http://haxe.org/img/haxe/logo_haxe.gif>

This html command can be useful to add additional divs and script locations for javascript specific externs. Such an addition can be done via the "script" tab completion command, which will produce:

# @tm-html <script type="text/javascript" src="|"></script>

Please note that <script> sections created in this fashion cannot contain relative references to javascript files in the project directory. The webkit viewer runs out of its own temporary directory, not in the current project directory. Full file references to local javascript files are required.

likewise, the "div" tab completion command will produce a simple html div:

# @tm-html <div id="|"></div>

Additional Commands


Snippets


Snippets exist for several haxe specific code templates. Check the bundle overview for a full list.

Control-M


Makes a constructor from selected variables. For instance, selecting the following text in TextMate:
    var name:String;
    var x:Float;
    var y:Float;
    var width:Float;
    var height:Float;

...and then pressing "Control-M" will create the following output:

    public function new( name:String, x:Float, y:Float, width:Float, height:Float ){
        this.name = name;
        this.x = x;
        this.y = y;
        this.width = width;
        this.height = height;
    }

HSS Support


The bundle now supports HSS. It includes the 1.2 hss compiler, as well as full syntax highlighting support for hss files. It will automatically generate the css files whenever the corresponding hss file is saved.

Additional Notes


Keep in mind that the webkit browser provided with textmate has its own debugging capabilities. It is possible to view a large amount of details via the built-in debugger, which is accessible by pressing Control-Click on the build result page, and then inspecting an arbitrary element.
version #19835, modified 2013-11-27 21:02:00 by Viltzu