Download the mode here: leg.xml

Note that since the leg syntax uses curly brackets ({}) to delimit actions in the grammar, and those actions are written in C (which also uses curly brackets a lot), the mode has to somehow be able to match a certain number of balanced pairs of these brackets. As far as I know this is not directly supported in the jEdit syntax highlighting mode system but I was able to use the “delegates” mechanism to implement support for two levels of matched brackets, which should be enough for any reasonable use (in any case, it’s easy to add further levels of such support to the mode).

To install this mode, add the following to the modes/catalog file in your jEdit user settings directory (select Utilities → Settings Directory in jEdit to find this):

Then copy the leg.xml file into the same directory with this file. See the Installing Modes section of the jEdit users’ guide for more information.

Since I don’t use the ProjectViewer plugin this macro has to have its own logic for determining where the “project root” is. The way it works is that it tries to find the root folder of the current project by way of searching for version control system folders (i.e. .git, .hg, .bzr, _darcs, .svn or CVS). The assumption is that as the script traverses the file system folder structure from the buffer’s location towards the root the first folder that has a Git, Mercurial, Bazaar or Darcs folder (or the last to have a Subversion or CVS folder) is the root. When the script finds the project root it switches the file browser to display it while keeping the UI focus in the editor field. If no project root can be found in this manner, the script sets the file browser to the directory that contains the currently open file.

Download the macro script itself here: Open_Root_of_Current_Project_in_File_Browser.bsh

You install it by dropping it into your jEdit user settings directory’s /macros folder (select Utilities → Settings Directory from the jEdit menu to find this location) and then running Macros → Rescan Macros. You can set a keyboard shortcut for this via the Shortcuts section of jEdit’s preferences and/or add a toolbar button via the Tool Bar section.

Here is the macro source:

Benefits of Declarative Diagramming

Web Sequence Diagrams is great. It uses a simple, readable syntax you can use to type in descriptions of sequential workflows and based on that it will generate the corresponding UML sequence diagrams for you.

Working with these diagrams in this way has a couple of nice benefits over more intricate/professional methods:

• They’re quick to create and quick to modify
• The syntax is pretty easy to read as-is
• The source is plain text, so all the benefits of using plain text apply (e.g. can put under source control, can use simple diff tools, file sizes are small etc.)

Helper Script and Syntax Highlighting

When I was sure I wanted to use this method again in the future, I hacked up a few quick and simple tools for this:

Script for generating the diagram images from source files

At the time of this writing, there’s a suggestion called “Create a command-line version of this application” on the service’s UserVoice site that’s labeled “started”, so hopefully in the future we’ll have a command-line sequence diagram generator from the author of the online service. In the meantime, though, here’s my solution. This is a Python script that can be used for generating the diagram images (using this service) from “source files” that contain the declarative workflow syntax. You just need to:

1. type up your diagram description in a text editor and save it into a file
2. begin the first line in the file with #wsd (so that the script knows this is a websequencediagrams.com syntax file)
3. (optional:) specify the diagram style you’d like to use on the first line with the syntax #wsd:style=modern-blue
4. call the script with the path to this file as an argument to generate the diagram image

The script uses a temporary SQLite database to save hashes of file contents so that even if you call it repeatedly for the same file, it’ll notice if the file contents haven’t changed and decide not to send a request over to the server. I did this in order to reduce unnecessary load on the server. I tested the script on Mac OS 10.5.7, Windows XP SP3 and Ubuntu 9.04 and it seems to work just fine on all of those (of course, on Windows you’ll first have to install Python manually).

Download the script here: wsd.py

Here’s an example on how to use it (to see the script’s usage info, run it without any arguments):

Save this into a file called ax-diagram:

#wsd

participant "Component A" as A
participant "Component X" as X

X -> A: what up
A -> A: processWhatUp()
note over A: A is confused
A -> X: go away
destroy X

Then run the script:

wsd.py ax-diagram

…and the file ax-diagram.png is created:

jEdit syntax highlighting mode

This is a simple jEdit syntax highlighting mode for the Web Sequence Diagrams syntax. You can download the file here: websequencediagrams.xml. Refer to this other blog post of mine for instructions on how to install modes for jEdit.

Here’s a screenshot of the highlighted syntax on my machine:

The Markdown jEdit mode

Markdown is my favourite markup language. Its primary design principle, that the markup written in it should be as readable as possible even by itself, is something my plain text -loving mind can easily agree with. If I’m writing a document that needs to be represented as HTML later on, Markdown is my first choice (too bad it doesn’t work very well with WordPress).

Here’s my jEdit mode file for Markdown: markdown.xml.

To install this mode, add the following to the modes/catalog file in your jEdit user settings directory (select Utilities → Settings Directory in jEdit to find this):

<MODE   NAME="markdown"

        FILE="markdown.xml"

        FILE_NAME_GLOB="*.markdown"

/>

Then copy the markdown.xml file into the same directory with this file. See the Installing Modes section of the jEdit users’ guide for more information.

This mode is not perfect; I could not figure out how to properly differentiate between code blocks and list item paragraphs (both are indented by 4+ spaces or 1+ tabs). Here’s what I wrote into the mode file related to these:

<!-- PROBLEM: code blocks

     

     Both code blocks and list paragraphs are specified by indenting

     (4+ spaces or 1+ tab) - how to differentiate between them? We

     don't want markdown syntax coloring to apply within code blocks

     but we _do_ want it to apply within list paragraphs. As it stands,

     we can't have both (or at least I don't know how to do that with

     jEdit's current mode syntax implementation.)

     

     The next line applies one syntax color type for all lines that

     begin with at least 4 spaces or 1 tab, which means that all such

     lines are treated as code blocks (this disables markdown syntax

     coloring for indented list paragraphs). Comment or uncomment it

     according to your preferences.

-->

<EOL_SPAN_REGEXP TYPE="LITERAL2" AT_LINE_START="TRUE" HASH_CHARS=" &#09;">(\s{4,}|\t+)</EOL_SPAN_REGEXP>

<!-- The next line applies one syntax color type for all lines that

     are indented "twice" (i.e. begin with at least 8 spaces or 2 tabs).

     This should safely match only code blocks (no list paragraphs can

     be indented twice like this, if I understand the spec correctly.)

-->

<EOL_SPAN_REGEXP TYPE="LITERAL2" AT_LINE_START="TRUE" HASH_CHARS=" &#09;">(\s{4,}|\t+){2,}</EOL_SPAN_REGEXP>

Here’s how you’d generate a HTML file from a Markdown file:

perl Markdown.pl myDocument.markdown > myDocument.html

The POD jEdit mode

When writing documentation for icalBuddy, I had to enter the wonderful world of creating man pages for the first time. The raw syntax for writing these things is, to say the least, awful. Just awful. Unfortunately I can’t use Markdown for writing them, but a pretty nice alternative I found was POD (or “Plain Old Documentation”), which is mainly used to document Perl code. Now, the important thing to note about this mode is that I don’t know any Perl, I don’t code in Perl and I have no idea how POD is used with Perl, so this mode is not suitable for simultaneous use of Perl and POD — I just wrote it for syntax highlighting in the pure POD documents I use to write man pages. Adjusting it to work for the purposes of documenting Perl code might just be trivial for someone who does know Perl and how POD is used with it, but I can’t do it.

Here’s my jEdit mode file for POD: pod.xml. Refer to the installation instructions for the Markdown mode above to see how this should be taken into use — the process is similar.

Here’s how you’d generate a man page from a POD file:

pod2man --section=1 --release=1.0 --center="manpage_title" --date="2009-04-21" myManPage.pod > myManPage.1

Footnotes

1. The Pragmatic Programmer (ISBN 0-201-61622-X): Chapter 3 (“The Basic Tools”), Sections “The Power of Plain Text” (pages 73-77) and “Code Generators” (pages 102-106).

Like I’ve mentioned before in this blog, I develop Flex applications using the Flex SDK and jEdit instead of Adobe’s Flex Builder IDE. This setup has worked very well for me but one annoying issue I’ve had to deal with because of this is the slow compilation speed: every time I make a small change into one of my projects and recompile it, the mxmlc compiler (that my build scripts are calling) has to load the JVM into memory and recompile my whole project from scratch, which obviously takes a while. Compiling things in Flex Builder is a lot faster, and the reason for that is the Flex Compiler Shell, which it uses for compilation instead of mxmlc.

The basic idea behind the Flex Compiler Shell is that it would stay in memory between compilations (thus avoiding the cost of loading up the JVM every time you want to compile something) and use a technique called incremental compilation that, as the name suggests, is based on the idea of only compiling the parts of your project that have changed since the last compilation (thus making the process a lot faster). When you run the Flex Compiler Shell executable (called fcsh), you’re thrown into an interactive shell where you can run commands in order to compile your projects and control the operation of fcsh itself.

The Problem

When I found out about fcsh, tried it out and saw how much faster it was than mxmlc, of course I wanted to immediately start using it instead in my build scripts. The biggest problem with doing this, though, is the fact that the basic operation of these two programs is fundamentally different: when you run mxmlc, it compiles the project, prints some messages to standard output and then exits (with the exit status 0 if the compilation was successful or 1 if it wasn’t), which is perfect for integrating it into build scripts. Fcsh, on the other hand, throws you into a shell of its own and expects you to essentially operate it from within itself (instead of simply calling it with some arguments and then having it return with some standard output and an exit status like mxmlc).

The other issue that makes fcsh more difficult to use in general is that in order to use the incremental compilation feature, you have to first compile your project like you normally would (using the “mxmlc” command), then make note of the “compile target id” number that fcsh then assigns to this project and specifies in its output, and for future compilations use the “compile N” (where N is the compile target id) command.

The Solution

I tried to search for a solution to this problem that somebody else might have come up with but didn’t find an adequate one (a list of the ones that I could find is further down), so I decided to give it a shot myself. My approach, called fcshctl (short for “fcsh controller”), is basically a simple bash script that:

1. starts the fcsh process if it isn’t already running
2. forwards its arguments to fcsh as commands
3. reads the output of that command from the fcsh interactive shell and prints it to the standard output
4. exits with status 0 (success) or >0 (failure)

In addition to this, I also made the script automatically and transparently invoke the incremental compilation feature whenever applicable so that I wouldn’t have to worry about keeping track of the compile target ids and using a different command for the compilation whenever one had already been assigned.

Below is a summarization of the pros and cons of this solution:

Pros:

• It’s quite simple — just one shell script (a few others are included in the .zip that are only for convenience and not required)
• It runs the fcsh instance in a GNU screen session, which means that:
• The running fcsh instance is accessible to all user processes (i.e. not just within a single shell session, for example)
• It is possible for the user to enter the running fcsh interactive shell at any time (by attaching to the screen session via the command screen -r -S fcsh) and manually interact with it
• It automatically checks whether you’ve compiled a specific file before and keeps track of the compile target ids that fcsh assigns so that it can automatically and transparently invoke the incremental compilation feature and let you access the speed gains that are fcsh’s main offering without any additional work. This feature can also be turned off by setting an environment variable.
• A proxy script (called fcshctl-mxmlc) that can be used in place of mxmlc is provided. It simply calls fcshctl with “mxmlc” as the first argument, followed by all the other arguments you specify, so that you can simply use this script as a stand-in for mxmlc in any build scripts that you may be using without having to modify them any further.

Cons:

• It uses the GNU screen logging mechanism and polling for changes in the log file in order to catch the output of commands sent to fcsh, which is not very elegant and causes a slowdown of maybe about a couple hundred milliseconds before the output is printed to stdout.
• The output of the executed fcsh command is not printed to the standard output as it comes, but instead all at once when the command finishes (this is not a problem for me personally, but others might want to fix this).
• It’s implemented as a bash script, which means that it’s not the fastest monster out there (we’re talking about milliseconds here, though, so it doesn’t bother me at all).

Download

You can download fcshctl here:

• fcshctl-v0.5.1.zip (latest)
• fcshctl-v0.5.zip
• fcshctl-v0.4.zip
• fcshctl-v0.3.zip

fcshctl has been tested with fcsh versions 3.0.0 build 477 and 3.1.0 build 2710 on Mac OS 10.5.5. It is licensed under the MIT License.

The script requires the following to be in your $PATH: rm, mv, cat, ps, sleep, tail, head, grep, awk, screen, xargs and basename. You also need to have the FLEX_HOME environment variable set to point to the Flex SDK root path.

Example of use

fcshctl $ export FLEX_HOME=/Users/username/code/SDKs/flex_sdk_3.1
fcshctl $
fcshctl $ ./fcshctl

Usage: fcshctl <commands>

  Substitute <commands> with any commands you
  would like to send fcsh, just like you would
  enter them in the interactive fcsh shell
  session.

  To get a list of the available commands, run:

    fcshctl help

fcshctl $
fcshctl $ ./fcshctl help
List of fcsh commands:
mxmlc arg1 arg2 ...      full compilation and optimization; return a target id
compc arg1 arg2 ...      full SWC compilation
compile id               incremental compilation
clear [id]               clear target(s)
info [id]                display compile target info
quit                     quit
fcshctl $
fcshctl $ ./fcshctl mxmlc ~/code/Flex/projects/testbed/testbed.mxml
Loading configuration file /Users/username/code/SDKs/flex_sdk_3.1/frameworks/flex-config.xml
Recompile: /Users/username/code/Flex/projects/testbed/testbed.mxml
Reason: The source file wasn't fully compiled.
Files changed: 0 Files affected: 1
/Users/username/code/Flex/projects/testbed/testbed.mxml(28):  Error: Incorrect number of arguments.  Expected 2.

    func1("toka");

fcshctl $ echo $?
1
fcshctl $
fcshctl $

Other similar solutions

Below is a list of other approaches to the problem of integrating fcsh to non-standard (i.e. non-Flex Builder) workflows (roughly in order from most promising to least promising), and short lists of reasons why I personally didn’t want to use them. If my solution doesn’t seem good to you, you should maybe check some of these out.

fcsh tools by Mike Rowe

• Runs fcsh in a daemonized process, which means you won’t be able to enter the interactive shell of a running fcsh process and manually interact with it
• You can only specify the filename to compile; has no support for additional mxmlc arguments
• For GNU/Linux (but seems to work just fine on OS X as well)

flex-compiler-shell-daemon by Leonardo Soto Muños (also see his blog post about it)

• I couldn’t get it to work out of the box on OS X
• Runs fcsh in a daemonized process, which means you won’t be able to enter the interactive shell of a running fcsh process and manually interact with it

FCSH Wrapper by Mihai Vasilache

• For Windows
• Designed to be used with Ant
• A bit complicated

http://code.google.com/p/fsch/ by nimrod97

• For Windows

BigSource Zarkov by BigSource GbR

• For Eclipse & Ant

However, after starting to use the SideKick plugin with the modified, AS3-supported version of Ctags while doing my work, I found a few small rough edges in the ActionScript support he had made:

• Package names were not properly catched – only the first level was shown (e.g. “org” instead of “org.hasseg.thingamabob“)
• Todo and note names were not properly catched – it just showed “todo” or “note” instead of what comes after
• My “todo:” notes were not catched – it only supported uppercase (i.e. “TODO:“)
• Some attribute keywords (override, final, internal etc…) were not allowed on classes, functions/methods and properties, so I was missing some of these in my SideKick listings

Not big problems by any means, but for me these meant that SideKick wouldn’t display some of the stuff in my code, and if it did, not properly, so I fixed them.

Get my modified version of the AS3-supported Ctags here:

The ctags binary (zipped) (note: compiled on a rev.B MacBook (Core 2 Duo processor) with Mac OS 10.4.10)

The source code (actionscript.c)

You should refer to VeryVito’s post for more info this issue.

Update (same day as original post): Improved this a bit. Find below a complete list of changes I’ve made (taken from the source code):

Update (Oct 5, 07): Now it can search from any number of AsDoc sources
Update (Oct 8, 07): Also finds documentation for methods, changing the command for opening a file in a web browser is easier
Update (Oct 10, 07): now the script searches through files, not buffers, so you needn’t have all of your project’s files open for it to be able to search through them

The way my version works is that it gets the selection from the current buffer (or if there’s no selection made, it selects the word that the caret is on top of) and searches the Flex SDK language reference for it. The files it goes through and the regular expressions + other logic that is used to do the pattern matching are designed so that it would work for class, package and method names.

Here’s the macro code (with some unnecessary whitespace removed):

As you can see from the settings, the macro can be set to open the documentation html page in either the InfoViewer plugin in jEdit or an external web browser. I prefer to have it open up in the browser, since the formatting and styling of the Flex language reference contribute to the fact that the pages don’t really work very well in the InfoViewer plugin. The OS X open command is used to make the external browser open up the documentation, which means that if someone would want to use this in Windows or Linux, that part would have to be re-implemented. Update: Now you can simply edit the openCommand variable in the “settings” area to change the command that is run in the system shell to open up docs in the browser.

Get the script here:

Display_Flex_documentation.bsh

Update (October 5, 07): Modified the script so that it can search from any number of different AsDoc sources (which the official Flex language reference is one of)

Update (October 8, 07): Modified the script to also find documentation for methods. Made it easier to modify the command that is run in the system shell to open up documentation .html pages in an external browser.

Update (October 10, 07): Modified the script to operate on files instead of buffers so that it can also search files that are not currently open.

For a while, I had the compiler command and the parameters (i.e. the file to compile) hardcoded in my macro, but recently I changed this to a more reusable solution where you have one macro for selecting the file (“buffer” in jEdit lingo) to be compiled and another for actually running the compiler on that file. Then I simply bind keystrokes for both of them. This enables me to easily and quickly run the compiler whenever I want to, and also change the file to be compiled (and, of course, also the compiler used – automatically based on the file extension) if I switch projects.

Select_file_to_compile.bsh

First, let’s take a look at Select_file_to_compile.bsh, which is used to select the file (as you can see, it saves the file path into a jEdit property which the other script will later read):

Compile_previously_selected_file.bsh

Then there’s Compile_previously_selected_file.bsh which invokes the compiling process. Notice the displayDockedConsole parameter in the settings – a false value will make sure that the Console plugin will not open up whenever the compiling starts. I Want to keep it closed because I don’t make this macro call the mxml compiler directly, but instead through a bash shell script (compileMxml.bash – link below) that displays a Growl notification whenever the compiling finishes, telling me whether or not the application was compiled successfully. In case of errors, the notification will be sticky, so that if I leave my computer to compile and then come back later, I’ll still be able to see it.

Download scripts

• Get the jEdit macros here: jEditCompileMacros.zip

Install them by saving them to jEdit’s macros directory. Then you can go to “utilities” -> “global options” -> “shortcuts” -> “macros” to set the keyboard shortcuts. In Mac OS X, the jEdit macros folder can be found here:

~/.jEdit/macros/

Please also note that you need the Console plugin for jEdit for this to work. Go to “plugins” -> “plugin manager” -> “install” to get it.

• Get the mxml compiler shell script (+ the icon images used in the Growl notifications it displays) here: compileMxml.zip