Bundles
From E
Contents |
Bundles
Bundles are packages of functionality that allow the editor to be customized to specific languages and tasks. The format originated in the text editor TextMate on the mac, and there is a thriving community creating and improving the bundles. There are already several hundred bundles available for just about any programming language and editing related task you can imagine.
The bundles contains all the info to adapt the editor to a given task: syntax highlighting rules, snippets that allow smart expansion of text, any kind of executable commands, completion lists, indentation rules and much more.
When you open a new document the editor will set the current syntax according to the filename's extension or the contents of the first line in the document. Most of the time this will be enough, but if you are creating new files or multiple bundles using the same extension, you can set the current syntax by clicking on the syntax field in the statusbar and selecting from the popup menu.
Why do we need cygwin?
The bundle format originated in the rich unix environment of MacOS X, and it gives you a lot of freedom to create your commands and extensions in any language you like. To support this on windows we have to setup a similar unix environment. Thankfully the cygwin project has done an amazing job in porting the unix environment to windows.
The installer that comes with e will install cygwin and the packages used by the bundles for you. Cygwin takes up a bit of space, but it is a very low impact installation that confines itself to a single directory, and does not cause any slowdown on your machine.
Snippets
Snippets are smart mini templates that expands text and automates a lot of what could otherwise be repetitive typing. The usual way to insert a snippet is to write the 'trigger' word and pressing tab, but you can also select it from the bundle menu where it will be sided by a gray box with the trigger word followed by a tab character.
The most simple snippet just replaces the trigger with some text, but you can dynamically insert the output of shell commands by wrapping the commands in backtics and environment variables by prepending them with the dollar sign:
``(c) Copyright `date +%Y` $USER. All Rights Reserved.``
You can embed tabstops in the snippet, so that pressing the tab button jumps you to the next tabstop. The tabstops can also contain default text that will be selected:
if ${1:condition}
$2
else
$3
end
$0 is a special tabstop that indicates where the caret/selection should be at the end of the snippet:
<style type="text/css" media="screen">
$0
</style>
The contents of the tabstops can also be reflected to other places in the text to save you typing (updates dynamically as you type):
for( ${1:unsigned int} ${2:i} = ${3:0}; ${2:i} < ${4:count}; ${2:i} += ${5:1} )
{
$0
}
You can also transform the reflections using regular expressions and conditionals. An example would be this snippet for an html header, which transforms all non-alpha chars in the header text to underlines and lowercases it before inserting it as the id:
<h1 id="${1/[[:alpha:]]+|( )/(?1:_:\L$0)/g}">${1:$TM_SELECTED_TEXT}</h1>
Making your own snippets is really easy, and just learning a few basic snippets for you favorite languages can save you lots of time and effort.
Commands
Commands allow you to extend the editor in pretty much any programming language. By default the commands are run as bash scripts, but by following the unix convention of defining an interpreter with as shebang (#!) on the first line, you can change it to any language you like. There are also a lot of options to which kinds of input that should be sent to the commands stdin, and to what the editor should do with the output.
If you need your command to show dialogs or other gui elements to get input from the user, the recommended way is to use CocoaDialog which is bundled with the editor.
Environment variables
When running commands you have a lot of environment variables set that reflect the current state. Note that they only will be set when it makes sense (eg. TM_SELECTED_TEXT will not be set if there is no selection):
| TM_FILENAME | Name of current file. |
| TM_FILEPATH | Full path of current file. |
| TM_DIRECTORY | Directory of current file. |
| TM_SELECTED_TEXT | The current selected text. |
| TM_CURRENT_WORD | The current word under the caret. |
| TM_CURRENT_LINE | The line the caret is in. |
| TM_LINE_NUMBER | Index of current line |
| TM_LINE_INDEX | Position in line (0 based) |
| TM_COLUMN_NUMBER | Current column |
| TM_TAB_SIZE | Width of tabs (in spaces) |
| TM_SOFT_TABS | Is soft tabs activated (YES/NO) |
| TM_SCOPE | Current scope |
| TM_MODE | Current active syntax |
| TM_CARET_XPOS | xpos of caret (in screen pixels) |
| TM_CARET_YPOS | ypos of caret (in screen pixels) |
| TM_PROJECT_DIRECTORY | Path of the current project |
| TM_SELECTED_FILE | First selected file in project |
| TM_SELECTED_FILES | List of selected files in project |
| TM_BUNDLE_PATH | Path to bundle of current command |
| TM_BUNDLE_SUPPORT | Path to the support directory of current bundle |
| TM_SUPPORT_PATH | Path to the base support directory |
The run environment
When creating commands (and snippets) you have three choices of run environments:
- Cygwin generic
- This is the basic environment that runs your commands under cygwin. It is used for all commands comming from the mac, and when you create new commands that should work on all platforms.
- Cygwin windows
- The environment is the same as Cygwin generic, but it is saved in a separate section of the bundle file so that it can co-exist with the generic version. Use this if you make windows specific changes to a command.
- Windows native
- This runs the command as a native windows command (no cygwin environment). If you do not define an interpreter with a shebang on the first line it will be run as a bat script. All paths and environments variables are in native format.
Contributing your bundle fixes and updates
If you find a bug in a bundle and fix it yourself, or add some new functionality you feel might be useful to others, please consider submitting the update to the relevant bundle maintainer. If a maintainer doesn't exists for a particular bundle, please do consider becoming a maintainer (if you're interested, post on the forum). Alternatively, submit your change/addition to the forum.
How To Get More Bundles
Only a few of the most popular TextMate bundles are included in the e installation. A large number of bundles, for any language and task you can imagine, are available from the subversion repository:
http://macromates.com/svn/Bundles/trunk/Bundles/
e can read all these bundles as-is. But notice that some of them may use mac specific shell commands (like appletalk or spotlight), which will not work on windows. So be prepared for some manual tweaking.
Getting the bundles
Here are some guides to getting bundles via Subversion:
* TextMate Wiki: Subversion Checkout
Be aware that some bundles contain filenames with characters that are invalid on windows. This can cause problems when doing checkout with svn. The solution for this is to rename the bundle items with invalid names. We will try to work with the bundle maintainers, to gradually transition the bundles to use more cross-platform friendly filenames.
In the mean time, you can use the TMBundles4Win repository which has escaped all NTFS-illegal filenames. It's updated hourly, but does not contain the revision history of the original TextMate repository.
If you don't like to fiddle with svn, you can always download the bundles manually with your web browser or use wget, see: http://www.e-texteditor.com/forum/viewtopic.php?p=1318#1318, this approach will handle the renaming of the illegal characters in filenames.
Installing the bundles
Just copy the bundles to the "Bundles" folder in the user settings application directory, usually something like "C:\Documents and Settings\[username]\Application Data\e"
- Note
- That bundles located under the "user settings application" directory, have precedence over e's default bundles, which are located in e's installation directory, e's installer will overwrite all changes which are done in e's installation directory!
