

                                                   A . d . i . e

                                         The ADvanced Interactive Editor




Introduction.

Adie is an extremely fast and convenient programming text editor and file viewer written using the FOX Toolkit.

For each visited file, Adie remembers where in that file you were last looking, and which special places in that file have been bookmarked, so you can quickly return to frequently visited places.

Project browsing is made easy by optionally displaying a File/Directory browser side by side with the text so files may be visited by means of a single click.  Files may also be opened simply by highlighting a file name, compiler warning message, or #include directive and hitting a single button; Adie will search for the file in the same directory as an already loaded file, or in a number of predefined directories (like for example include directories).


General Features.

  - Programmable syntax coloring and text styles.
  - Active or current text line highlighting.
  - Optional line number display.
  - Preferences are configurable with convenient dialogs.
  - Text size only limited by available memory.
  - Persistent bookmarks may be set for each file.
  - Persistent scroll position is remembered for each visited file.
  - Wheel mouse scroll support.
  - Online help built in.
  - Parse vim, emacs, and adie modelines.
  - Automatically configure hardtabs when loading files recognized as Makefiles.
  - Searching files matching a wildcard pattern for a regular expression.

File Access Features.

  - File Dialog supporting bookmarked directories.
  - Dropping a file into Adie opens the file.
  - Single-click access to file using File/Directory browser.
  - Visit recently edited files.
  - Jump to file and line number of highlighted compiler warnings or errors.
  - Customizable list of file patterns; show only source files, for example.
  - Open a file by highlighting a #include directive.
  - Customizable list of directories to search for header files.
  - Detect if file changed outside of editor to prevent accidental overwriting.

Editing Features.

  - Unlimited undo/redo capability.
  - Cut and paste to clipboard support.
  - X11 primary selection support using middle-mouse paste.
  - Drag-and-drop support for text move or copy.
  - Brace matching, statement block, and expression block selection.
  - Up to 10 persistent bookmarks may be set in each file.
  - Search and replace history is stored persistently.
  - Auto-indent feature.
  - Strip trailing spaces, strip carriage-returns for DOS files.
  - Indent or unindent selected text; clean indentation.
  - Search for highlighted text.
  - Goto line number, goto highlighted line number, goto matching brace, goto begin/end of block.
  - Fixed word wrap column, or continuous word wrap mode.
  - Mouse wheel or right-mouse scroll support.
  - Customizable word-delimiters to select words by double-clicks.
  - Insert files or extract highlighted text to file.

Syntax Coloring Features.

  - Syntax coloring is programmable, using PERL-like regular expressions.
  - Syntax patterns are keyed to file extension, file contents, modelines, or explicitly set by user.
  - Text styles including foreground, background, selection colors, as well as underlining and strike-throughs.
  - Syntax expressions, text styles, and language modes can be set up from convenient dialogs.
  - Color fallback mechanism to minimize style setup hassles.


Starting a New Document.

To start a new document, invoke the 'New' menu, or press on the New button on the toolbar. A new window, empty, window will be created with a pathname in the same directory as the current file (if any).  The initial name of the file will be 'untitled', 'untitled1', etc.  When trying to save the file, you will be prompted to supply a new filename.


Opening and Saving Files the Old Fashioned Way.

To open a file, you can invoke the 'Open' menu, or press on the 'Open' button on the toolbar.  This will bring up the standard File Dialog, which allows you to select a file.
To save a file, you can either invoke the 'Save', 'Save As', or 'Save To' menu option.  'Save' will save the text to the same filename as it was loaded from.  'Save As' will prompt you to enter a new filename, then save the file to the new name.  This will leave the document under the new name in the text buffer, and a subsequent 'Save' will save the document to the new filename.  When you invoke 'Save To', you will be prompted for a new filename, same as 'Save As', except that the document will not change to the new filename.  A subsequent 'Save' will still save the document to its prior name.

When working with the File Dialog, you can quickly navigate to the desired file by typing the first few letters of the filename and then pressing Enter (Return).  You can use Backspace to move up one directory level.  Control-H moves to your home directory, Control-W moves back to the current working directory. Thus, power-users can open and select a new file with no mouse interactions.

A nice convenience of the File Dialog is the ability to set bookmarks to commonly referenced directories.  Once bookmarked, you can quickly move back and forth between several directories.


Opening Files Using the File and Directory Browser.

An alternative method to open files is the File and Directory Browser. You can display the File and Directory Browser by invoking the 'File Browser' option under the 'View' menu.  To open a file using the File and Directory Browser, simply click on the file. If there are many files, you may want to limit the number of files displayed by specifying a file pattern in the 'Filter' combo box.
The patterns can be any file wildcard expression such as '*.cpp'.  By default, the File and Directory Browser shows all files, i.e. the pattern is '*'. Additional patterns can be added to the list using the 'Preferences' Dialog.


Opening Recently Visited Files.

The recent file menu shows files which have been recently visited.  You can quickly get back to a file you've been editing simply by selecting one of these recent files.


Opening Files by Drag and Drop.

Using a file browser such as PathFinder or other Konqueror or other XDND compatible file browsers, you can simply drop a file into the text pane and have Adie read this file.


Opening a Selected Filename

Selecting any filename, possibly in another application, and invoking the 'Open Selected' option causes Adie to open the selected file. When the selected filename is of the form:

   #include "filname.h"

or:

   #include <filename.h>

Adie will search for this file in the same directory as the currently loaded file, and if not found there, look into a sequence of (possibly relative) search paths.  You can specify the list of search paths to search by entering a list of absolute or relative pathnames into the 'Preferences' dialog, under the 'Miscellaneous' sub panel.
When the selected filename is of the form:

   filename.cpp:177

or:

   filename.cpp:177:9
   
or:

  filename.cpp(177)

or:

  filename.cpp, line 177
  
or:

  File = filename.cpp, Line = 177
  
or:

  filename.cpp:         

Adie will not only load the filename, but also jump to the given line number and column number, if available.  In the case column number is available, it will also place the cursor on the 9-column of line 177.  If this file has already been loaded, Adie will simply jump to the given line (and column-) number in the already open file, and bring the file to the front.
This option is very useful when fixing compiler errors.  Various other popular compiler error or warning formats are supported besides GCC.

Finally, a filename that was escaped according to bash-quotation rules (Linux), or command line escaping rules (Windows), will be unescaped and loaded as well.


Mouse Selection.

You can move the cursor by simply clicking on the desired location with the left mouse button. To highlight some text, press the mouse and drag the mouse while holding the left button. To select text a word at a time, you can double-click and drag; to select text a line at a time, you can triple-click and drag.
Performing a shift-click extends the selection from the last cursor location to the current one.
When selecting words, words are considered to extend from the clicked position up to a blank or word-delimiting character.  The latter may depend on the programming language, and so Adie offers a way to change the set of delimiter characters.


Scrolling Text.

Using the right mouse button, you can grab the text and scroll it. a right mouse drag is a very convenient way to scroll the text buffer by small amount as the scrolling is exactly proportional to the mouse movement.
You can of course also use the scroll bars.  Because scrolling becomes awkward when dealing with large amounts of text, you can do a fine scroll or vernier-scroll by holding the shift or control keys while moving the scroll bars.

Adie can also take advantage of a wheel mouse; simply point the mouse inside the text area and use the wheel to scroll it up and down.  Holding the Control-key while operating the wheel makes the scrolling go faster, by smoothly scrolling one page at a time.  To scroll horizontally, simply point the mouse at the horizontal scroll bar.
In fact, any scrollable control (including the File/Directory Browser), can be scrolled by simply pointing the cursor over it and using the mouse wheel.
You can adjust the number of lines scrolled for each wheel notch by means of the Preferences dialog.


The Clipboard.

After selecting some text, you can cut or copy this text to the clipboard. A subsequent paste operation will then insert the contents of the clipboard at the current cursor location.
If some text has been selected in another application, then you can paste this text by placing the cursor at the right spot in your text and invoking the paste command.


The Primary Selection.

When text is selected anywhere (possibly in another application), Adie can paste this text into the current text buffer by means of the middle mouse button or by pressing the wheel-button if you have a wheel mouse.  Note that while holding the button, the insertion point can be moved by moving the mouse:- Adie will only insert the text when you release the button.


Text Drag and Drop.

After selecting some text, you can drag this text to another location by pressing the middle mouse button; because Adie is fully drag and drop enabled, you can not only drag a selection from one place to another inside the text buffer, but also between different Adie applications, or even from Adie to another drag and drop enabled application or vice-versa.
Within the same text window, the drag defaults to a text-movement.  You can change this to a text copy by holding down the Control key while you're dragging.
Between one text window and another, the drag defaults to a copy operation you can change this to a text movement by holding down the Shift key while dragging.


Undo and Redo.

Adie support unlimited (well, the limit is large...) undo and redo capability.  Each time you insert, remove, or replace some text, Adie remembers what you did.
If you make a mistake, you can undo the last command, and the one before that, and so on. Having invoked undo many times, it is sometimes desirable to invoke the redo command, i.e. to perform the original editing operation again.  Thus, you can move backward or forward in time.
However if, after undoing several commands, you decide edit the buffer in a different way, then you will no longer be able to redo the undone commands:- you have now taken a different path.
When you first load a file, or just after you save it, Adie remembers that this version of the text was special; while subsequent editing commands can be undone individually, you can always quickly return to this special version of the text by means of the revert command.


Modeline Support.

When modelines are present in the loaded text, certain editor features can be automatically switched.  Adie recognizes three flavors of modelines: vim (Vi-Improved), Emacs modelines, and Adie modelines.

Vim modelines are of the form:

	[text]{white}{vi:|vim:|ex:}[white]{options1}

In Vim modelines, programming language, wrap mode, wrap columns, auto-indent, tab-columns, and soft- or hard-tab modes may be configured.  These take precedence over the defaults and values in the syntax file if present.

Emacs modelines are of the form:

	"-*- key1: value1; key2: value2; -*-"

In Emacs modelines, programming language, tab stops, wrap mode, soft- or hard-tab modes, and auto-indent may be configured.

Finally, in Adie modelines, which are of the form:

	"adie: key1=value1 key2=value2 key3=value3 :"

Language mode, tab stops, wrap columns, wrap mode, soft- or hard-tab mode, and auto-indent may be configured.  The variables are simple two-letter names.  The variable "la" configures the programming language to be used for syntax coloring; the variable "ts" sets the tab-stop value. The variable "ww" controls wrap column, and "wr" enables word-wrapping if set to 1.  The variable "et" controls hard-tabs 0 or soft-tabs 1, and the variable "ai" enables auto-indent if set to 1.

These settings may also be set in the syntax file; however, the modeline, if enabled, will override the value in the syntax file or the default setting from the dialog, if present.


Search and Replace.

Adie uses the standard Search Dialog for searching strings. The search dialog offersforward and backward searches (relative to the current cursor location), and three search modes:

Exact. In the Exact mode, a search looks for a verbatim occurrence of the search string in the text.

Ignore Case. In the Ignore Case mode, a search looks for a verbatim occurrence also, but while disregarding the uppercase/lowercase distinctions.

Expression. In the Expression mode, the the search performs a full regular expression match.  The regular expression syntax being used is very similar to PERL and is as follows:

  ^	Match begin of line
  $	Match end of line
  .	Match any character
  |	Alternation
  ( ... )	Grouping sub pattern
  (?i ... )	Match sub pattern case insensitive
  (?I ... )	Match sub pattern case sensitive
  (?n ... )	Match sub pattern with newlines
  (?N ... )	Match sub pattern with no newlines
  (?: ... )	Non-capturing parentheses
  (?= ... )	Zero width positive lookahead
  (?! ... )	Zero width negative lookahead
  (?<= X )	Zero width positive lookbehind
  (?<! X )	Zero width negative lookbehind
  (?> X )	Atomic grouping (possessive match)
  []	Character class

  *	Match 0 or more [greedy]
  +	Match 1 or more [greedy]
  ?	Match 0 or 1 [greedy]
  {}	Match 0 or more [greedy]
  {n}	Match n times [greedy]
  {,m}	Match no more than m times [greedy]
  {n,}	Match n or more [greedy]
  {n,m}	Match at least n but no more than m times [greedy]

  *?	Match 0 or more [lazy]
  +?	Match 1 or more [lazy]
  ??	Match 0 or 1 [lazy]
  {}?	Match 0 or more times [lazy]
  {n}?	Match n times [lazy]
  {,m}?	Match no more than m times [lazy]
  {n,}?	Match n or more [lazy]
  {n,m}?	Match at least n but no more than m times [lazy]

  *+	Match 0 or more [possessive]
  ++	Match 1 or more [possessive]
  ?+	Match 0 or 1 [possessive]
  {}+	Match 0 or more times [possessive]
  {n}+	Match n times [possessive]
  {,m}+	Match no more than m times [possessive]
  {n,}+	Match n or more [possessive]
  {n,m}+	Match at least n but no more than m times [possessive]

  \a	Alarm, bell
  \e	Escape character
  \t	Tab
  \f	Form feed
  \n	Newline
  \r	Return
  \v	Vertical tab
  \cX	Control character (X is '@', 'A'...'Z', '[', '\', ']', '^', '_', or '?' for DEL).
  \033	Octal
  \xFF	Hexadecimal number (should be exactly two hex-digits)
  \w	Word character [a-zA-Z_0-9]
  \W	Non-word character
  \l	Letter [a-zA-Z]
  \L	Non-letter
  \s	Space
  \S	Non-space
  \d	Digit [0-9]
  \D	Non-digit
  \h	Hex digit [0-9a-fA-F]
  \H	Non-hex digit
  \b	Word boundary
  \B	Word interior
  \u	Single uppercase character
  \U	Single lowercase character
  \p	Punctuation (not including '_')
  \P	Non punctuation
  \<	Begin of word
  \>	End of word
  \A	Match only beginning of string
  \Z	Match only and end of string
  \1...\9	Back reference


Greedy match (the default) tries to match as many characters as possible, but backs off one at a time until a match is found.  Lazy match tries to match as few characters as possible, but advances one at a time until a match is found.  The possessive match behaves much like the greedy match, but does not back off; if the rest of the pattern does not succeed, the match fails.  Possessive match can often be a major guard against unnecessary recursion by calling it quits early, because backing off has no possibility of success.



Keyboard Bindings.

The following table lists the keyboard bindings.

Key:	Action:
====	=======

  Up	Move cursor up.
  Shift+Up	Move cursor up and extend selection.
  Ctl+Up	Scroll text downward, keeping current line.
  Down	Move cursor down.
  Shift+Down	Move cursor down and extend selection.
  Ctl+Down	Scroll text upward, keeping current line.
  Left	Move cursor left.
  Shift+Left	Move cursor left and extend selection.
  Ctl+Left	Move cursor left by one word.
  Ctl+Shift+Left	Move cursor left by one word and extend selection.
  Right	Move cursor right.
  Shift+Right	Move cursor right and extend selection.
  Ctl+Right	Move cursor right by one word.
  Ctl+Shift+Right	Move cursor right by one word and extend selection.
  Home	Move cursor to begin of line.
  Shift+Home	Move cursor to begin of line and extend selection.
  Ctl+Home	Move cursor to top of text.
  Ctl+Shift+Home	Move cursor to to top of text and extend selection.
  End	Move cursor to end of line.
  Ctl+End	Move cursor to bottom of text.
  Shift+End	Move cursor to end of line and extend selection.
  Ctl+Shift+End	Move cursor to bottom of text and extend selection.
  Page Up	Move cursor up one page.
  Shift+Page Up	Move cursor up one page and extend selection.
  Page Down	Move cursor down one page.
  Shift+Page Down	Move cursor down one page and extend selection.
  Insert	Toggle between insert mode and overstrike mode.
  Shift+Insert	Paste text from clipboard.
  Ctl+Insert	Copy selected text to clipboard.
  Delete	Delete character after cursor, or text selection.
  Ctl+Delete	Delete word after cursor.
  Shift+Delete	Delete to end of line.
  BackSpace	Delete character before cursor, or text selection.
  Ctl+BackSpace	Delete word before cursor.
  Shift+BackSpace	Delete to begin of line.
  Return	Insert end of line, add indent if auto-indent is on.
  Shift+Return	Insert end of line, and indent even if auto-indent is off.
  Ctl+Return	Insert end of line only.
  Tab	Insert (emulated) tab.
  Ctl-Tab	Insert hard tab.
  Ctl+Shift+<	Move current line up.
  Ctl+Shift+>	Move current line down.
  Ctl-D	Copy current line.
  Ctl+A	Select all text.
  Ctl+K	Delete current line.
  Ctl+X	Cut selected text to clipboard.
  Ctl+C	Copy selected text to clipboard.
  Ctl+V	Paste text from clipboard.


Changing Font.

You can change font by invoking the Font Selection Dialog from the Font menu. The Font Dialog displays four list boxes showing the font Family, Weight, Style, and Size of each font.
You can narrow down the number of fonts displayed by selecting a specific character set, setwidth, pitch, and whether or not scalable fonts are to be listed only.
The All Fonts checkbutton causes all fonts to be listed. Use this feature if you need to select old-style X11 bitmap fonts.
The Preview window shows a sample of text in the selected font.


Changing Preferences.

Since there is no accounting for tastes, Adie can be extensively configured by means of the Preferences dialog. The Preferences dialog is comprised of a number of subpanes which allow you to change colors, editor modes, file patterns, and word delimiters.

Changing Colors.

The colors subpane allows you to change the colors used in the File/Directory browser, and the Text Window.
You can simply drag colors from one color well to another, or you can double-click on a color well and bring up the Color Dialog.
The Color Dialog offers a number of ways to create a new color, either by selecting one of the pre-defined color wells, by mixing a custom color in RGB, HSV, or CMYK color space, or by selecting a named color from a list.


Changing Editor Settings.

The editor subpane is used to change various modes of the editor:

Word Wrapping.  This enables word wrapping mode for the Text Window; when word wrapping is turned on, text flowed to stay within the wrap margins.

Fixed Wrap Margin.  When this feature is enabled, the text is flowed to stay within a fixed wrap column; when disabled, the Text Window is in continuous wrapping mode, and the text is flowed to fit the size of the Text Window.  This option has no effect if the Word Wrapping option is off.

Wrap Margin.  This specifies the column at which paragraphs are to be wrapped; the wrap margin only has effect if the fixed wrap margin option is selected.

Tab Columns.  This specifies the tab spacing, in terms of spaces.

Strip Carriage Returns.  When this option is selected, MS-Windows/MS-DOS text files with lines ending in CRLF are transformed into LF only files upon read; this is mostly of interest when loading DOS files on a UNIX system; when Adie runs under MS-Windows, files are normally automatically translated back and forth.

Strip Trailing Spaces.  When selected, Adie will remove all white-space after the last printable character when reading a file.

Auto Indent.  This causes spaces or tabs to be inserted to match the previous line; this option is meant for programmers.

Brace Match Time.  When entering a brace, parenthesis, or bracket, the cursor temporarily jumps to the matching brace and pauses there for a bit before hopping back to the insert position.  If the brace match time is set to 0, then this feature is disabled.

Insert Tab Characters.  When this option is selected, hard tab characters are inserted when entering the tab key.  If the option is not selected then entering the tab key will insert the corresponding number of spaces into the text buffer.

Mouse Wheel Lines.  This is the number of lines scrolled when the mouse wheel is rotated by one notch.  When holding the control key while using the wheel, the text scrolls by one page at a time; when holding the alt key, it scrolls one pixel at a time.

Save View of File.  When this option is selected, the current view or scroll position is saved so that a subsequent visit to this file can immediately jump back to the same view.
Disabling this option will cause all remembered views to be forgotten.

Save Bookmarks.  When selected, all currently set bookmarks will be saved for this file; a subsequent visit to this file will restore the bookmarks.
Disabling this option will cause all remembered bookmarks to be forgotten.


Changing File Patterns.

This subpane allows you to enter a list of file patterns, one pattern on each line. These patterns are used in the File/Directory browser and the File Dialog.  They are especially useful in the File/Directory browser as it allows you to cause the File/Directory browser to only show those file types you want to see (e.g. only source files).
Each line of a pattern has the format:

   patternname (patternlist)

Where patternname is the name of the pattern (e.g. "C Source") and the patternlist is a comma separated list of patterns (for example "*.h,*.c").
The patternname is optional.
Some examples from my own setup of Adie (you can paste these from this help window if you want) are shown below:

  All Files (*)
  All Source (*.cpp,*.cxx,*.cc,*.C,*.c,*.hpp,*.hxx,*.hh,*.H,*.h,*.y,*.l)
  C++ Source Files (*.cpp,*.cxx,*.cc,*.c,*.C)
  C++ Header Files (*.h,*.hpp,*.hxx,*.hh,*.H)
  C Source Files (*.c)
  C Header Files (*.h)
  Python Files (*.py)
  Perl Files (*.pl)
  Ruby Files (*.rb)
  Lex (*.l)
  Yacc (*.y)
  Object (*.o)
  X Pixmap (*.xpm)
  X Bitmap (*.xbm)

Some details on the allowable wild-card patterns:

  ?	Matches single character.
  *	Matches zero or more characters.
  [abc]	Matches a single character, which must be a, b, or c.
  [^abc]	Matches a single character, which must be anything other than a, b, or c.
  [!abc]	Ditto.
  [a-zA-Z]	Matches single character, which must be one of a-z or A-Z.
  [^a-zA-Z]	Matches single character, which must be anything other than a-z or A-Z.
  [!a-zA-Z]	Ditto.
  pat1|pat2	Matches either pat1 or pat2.
  pat1,pat2	Ditto.
  (pat1|pat2)	Matches either pat1 or pat2; patterns may be nested.
  (pat1,pat2)	Ditto.


Changing Delimiters.

Different programming language have different notions about identifiers.  Adie accomodates for this by allowing you to specify which characters (besides white space, of course) are used to delimit identifiers or tokens in the programming language. The default set of delimiters is "!"#$%&'()*+,-./:;<=>?@[\]^`{|}~".


Syntax Coloring Text.

Syntax highlighting colorizes source code based on recognizing certain patterns in the source files being edited.  For example, in C++ the keywords 'class' and 'while' may be given a different color from normal text. When syntax highlighting is enabled, the Adie editor will evaluate the color of each piece of text as you type it.  Thus, you'll have immediate feedback as misspellings of keywords will be instantly obvious.
Coloring the syntactical elements is only performed if syntax coloring is turned on, and a particular language syntax has been selected for the file.
Colors may be assigned by the user using the 'Preferences' dialog, using the 'Styles' subpanel.  Each particular syntactical element may be given a different foreground color and background color.  Separate colors are available for when a syntactial element is highlighted, selected, or is the currently active cursor line.
Apart from coloring, it is also possible to emphasize a syntactical element with underlines, strikeouts, or bold-face.  These effects may be selected by checking the underline, strikeout, or bold-face checkbuttons in the 'Styles' subpanel next to the style element.
Colors that are set to fully transparent (alpha = 0), will revert to the default text foreground and background colors.  Most users will probably prefer not to set the background colors but only foreground colors, making it easier to keep background colors consistent among the different syntactical elements.

Language Matching.

The set of patterns to be recognized in a piece of text are determined by the programming language syntax currently in effect for the text window.  The editor has several ways to determine which language is to be used for colorizing the text:

The first method is to look at the file's file-extension.  For example, a file extension '.py' will select the Python programming language. Each language syntax definition has a wildcard pattern which is matched against incoming filename, to determine if that langauge should be used for colorizing the file.

The second method is to look at a file's contents.  For example, when the string '#!/bin/bash' is spotted at the top of a file, the 'Shell' language is automatically selected.  This is a very useful method since shell scripts very often don't have a particular file extension.

The third method is to scan the top or bottom of the file for a so-called 'modeline'.  Adie currently supports vi, emacs, and its own modeline syntax.  The modeline is typically embedded in a comment-section of the source text, and may contain other specifications like tab settings and other hints for editing.

The final method is for the user to simply enforce the programming language syntax, by selecting the proper language syntax from the menu. Adie will write this association to the registry, so when the same file will get loaded in the future, the same language will be automatically selected. If this method is used, file extensions, contents, or embedded modelines will not be used to determine the language syntax.


Writing Custom Syntax Files.

The syntax highlighting patterns in Adie are fully extensible, simply by writing you own language specification, or modifying one of the existing language specifications in the 'Adie.stx' file delivered with the software.
In order to get started on writing custom syntax patterns, it will be necessary to develop a basic understanding of how the syntax highlighting in Adie actually works.
Consider the following simple language definition (this is actually the language definition of the language specification file itself!):

  # Adie editor syntax-file syntax coloring
  language "Adie Syntax"
    filesmatch "*.stx"
    contextlines 1
    rule "Comment"
      openpattern     "#"
      closepattern    "$"
      style           "darkgreen"
    end
    rule "Keyword"
      pattern         "\<(language|filesmatch|contentsmatch|delimiters|contextlines|contextchars|rule|group|end|pattern|openpattern|closepattern|stoppattern|style|autoindent|wrapwidth|tabwidth|wordwrap|expandtabs)\>"
      style           "red"
    end
    rule "String"
      openpattern     "\""
      closepattern    "\""
      stoppattern     "$"
      style           "blue"
      rule "Escape"
        pattern       "\\\""
        style         "red"
      end
    end
  end

The first line of this language specification is a comment line.  Comment lines start with '#' and extend to the end of the line.  You can place comments anywhere on a line, but all text after the '#' becomes part of the comment up to the end of the line. The section between 'language' and 'end' is the actual language specification.  Each language specification must have a unique name, to distinguish it from other language specifications.  A language specification contains a number of language-specific parameters, followed by a number of syntax rules.

The first 'filesmatch' statement specifies the wildcard expressions that the filename should be matched against to identify this language as the one to be used for the filename.  In this case, any file ending in '.stx' will use this language syntax.

The statement 'contextlines' specifies how many lines to go backward and forward relative to a change in the text, in order to pick up an incremental recoloring of the text after a modification.  The larger this number is, the more time it takes to recolor. If developing a completely new language specification, its suggested to leave this set as 1 and increase it until there are no more errors recolorizing large documents.

The syntax rules specify what patterns are matched and how to highlight/color them. As can be seen from the language specification above, syntax rules may contain other subrules.  This works as you expect: the nested rules colorize fragments of text found within the outer rules.
Each rule must have a name.  Rule names are used to assign colors, and so its OK to have different rules be given the same name, if they're to have the same color.

There are four types of rules:

 1. Simple rule. Simple rules match only a single regular expression 'pattern'.
 2. Bracket rule. Bracket rules match an 'openpattern' and 'closepattern'.
 3. Safe bracket rule. A bracket rule with an additional 'stoppattern'.
 4. Default rule. A rule that matches all text and has no patterns.

Except for the simple rule, the other rules may have subrules to colorize specific areas within the scope of that rule.  For example, inside the rule "String" above, which colors text blue, rule "Escape" matches escape sequences and colors them red. [An important detail is that the subrule patterns are matched before the closing rule of the outer rule, thus an escape like '\"' will prevent the outer rule from seeing the '"' as the end of the string.

Within each rule, the optional 'style' keyword can be used to specify an initial color to be used for the text highlighted by that rule.

The full list of keywords in the language specification is below:

language "name" ... end

The block between 'language' and 'end' describes one particular progamming language syntax.  Names must be unique.

filesmatch "wildcard"

This describes the wildcard pattern (see file patterns) used to matched against filenames or file extensions.  If there's a match, the language syntax will be used to higlight the file.

contentsmatch "regular-expression"

This sets the regular expression (see regular expressions) used to search the contents of the a small fragment of the file.  If the pattern is found, the language syntax fill be used to highlight the file.

delimiters "string"

Sets the delimiters and punctuation characters considered to be not part of a word in the language.  This affects next word, previous word cursor navigation commands.

contextlines <number>

Sets the number of lines to search around after a change in text to pick up incremental highlighting.  Set to 1 for many programming language but could be set based on largest syntactical element likely to be encountered.

contextchars <number>

Set the number of characters to search around after a change in text. Similar to 'contextlines' above.

autoindent yes | no

Set the auto indent feature for the language.  If set, the next new line after the current line will be indented at the same level as the current line by inserting spaces or tabs.  If no autoindent value is specified in the syntax description, the default value will be in effect.

wrapwidth <number>

Set the number of columns to wrap text at, if text is to be wrapped.  The special value 0 wraps the text at the window-edge.  If no value is specified, the default value will be in effect for this language.

tabwidth <number>

Set the number of columns a tab character indents with.  Typical value is 8.  If no value is specified, the default value will be in effect for this language.

wordwrap yes | no

Enables wrapping of long lines.  Lines will be broken at whitespace, if possible, to keep within the number of columns specified by 'wrapwidth' parameter, or the window edge if 'wrapwidth' was set to 0.  If no value is specified, the default value will be in effect for this language.

expandtabs yes | no

Enables tab expansion into spaces.  The number of spaces tabs expand into is set with 'tabwidth' parameter.  If no value is specified, the default value will be in effect for this language.

group "groupname"

Specifies this language is part of language group "groupname".  If specified, the language color scheme is consolidated on a per-group, rather than a per-language basis.  For example, group "C-Like" comprises various programming languages with similar syntactical elements.  Settings of a color scheme for one language will then be applied to all languages in the group.  For this to work, rule names must match; rule "Comment" in the Java language specification will have the same coloring as rule "Comment" in C or C++ language specification.  This can be a real time-saver as it allows you to set colors for many languages
in a consistent and succinct manner.

rule "name" ... end

Specifies a new language rule.  Within a rule, the following keywords may be used.

style "colorname"

This will give text colored by the rule a color, unless specified from the registry.  It is chiefly to ensure some highlighting is performed prior to customizing the color scheme.
Colors can be specified by name, for example "Aquamarine", or as a number hexadecimal digits, like #FF0000 (which yields a pure red).

pattern "regular-expression"

This sets the pattern this rule is to match against the text.  All text captured by the match will be colored by the colors associated with rule name. If quotes ('"') are to be matched, make sure to escape them as '\"'. Only quotes ('"') need to be escaped for the syntax parser itself.

openpattern "regular-expression"
closepattern "regular-expression"
stoppattern "regular-expression"

This sets regular expression patterns for bracket and safe-bracket rules. A bracket rule matches text against the regular expression specified by 'openpattern' and then colors all text subsequently until the place where the regular expression specified by 'closepattern' is found.  If 'stoppattern' is specified and encountered before the close pattern, the rule breaks out early.  This is handy for rules which may match huge quantities of text while the user hasn't finished typing, for example open-ended strings or multi-line comments.
Note that subrules, if any, are matched first before attempting close pattern or stop pattern.


Finding the Syntax File.

When Adie starts up, it normally looks in the directories listed in the PATH environment variable.  There are installations where this is not convenient.  Therefore, it is possible to set the search directories using the special 'syntaxpaths' registry setting.
For testing purposes, you can also pass the filename of the syntax file directly on the command line using '-S' or '--syntax' flag.


Other Configuration Issues.

Because Adie is an editor written to use the FOX Toolkit, there are various other items, common to all FOX Toolkit programs, which may be configured either by hand or using some other control panel.
A few items of particular interest are list below:

  [SETTINGS]
  typingspeed=800
  clickspeed=400000000
  scrollspeed=80000000
  scrolldelay=600000000
  blinkspeed=500000000
  animspeed=20000000
  menupause=400000000
  tippause=800000000
  tiptime=2000000000
  dragdelta=6
  wheellines=10
  bordercolor=black
  basecolor=AntiqueWhite3
  hilitecolor=AntiqueWhite
  shadowcolor=AntiqueWhite4
  backcolor=AntiqueWhite1
  forecolor=black
  selforecolor=AntiqueWhite
  selbackcolor=#aea395
  tipforecolor=yellow
  tipbackcolor=black
  normalfont="[lucidatypewriter] 90 700 1 1 0 1"
  iconpath = /usr/share/icons:/home/jeroen/icons

These settings can be either placed in $HOME/.foxrc (and thus affect all FOX programs), or in $HOME/.foxrc/FoxTest/Adie (only applying to Adie).
File types may be bound to a command, mime-type, and icons using statements like the one below:

  [FILETYPES]
  cpp = "/usr/local/bin/adie %s &;C++ Source File;c_src.xpm;mini/c_src.xpm"
  /home/jeroen = ";Home Directory;home.xpm;mini/home.xpm;application/x-folder"
  defaultfilebinding = "/usr/local/bin/adie %s &;Document;document.xpm;mini/document.xpm"
  defaultexecbinding = ";Application;exec.xpm;mini/exec.xpm;application/x-executable-file"
  defaultdirbinding = ";Folder;folder.xpm;mini/folder.xpm;application/x-folder"

This example shows how the extension ".cpp" is bound to the program "adie" and is associated with two icons, a big icon "c_src.xpm" and a small icon "mini/c_src.xpm", which are to be found in the directories determined by 'iconpath", in this case, "/usr/share/icons" or "/home/jeroen/icons".

It also binds two icons "home.xpm" and "mini/home.xpm" to the home directory "/home/jeroen".

Finally, it assigns icons, commands, and mime-types to unbound documents, executables, and directories, overriding the built-in icons of the FOX Toolkit.
