Clade

Documentation

Table of Content

Introduction

Clade is a text editor with most common features found in programming editors: syntax highlighting, launch external tools, advanced search and replace, brace matching, ...

But Clade implements a unique marker-based folding and navigation system. It allows you to structure your source code like an hyper-text document: the source code can be cut into sections and sub-sections independently of the file structure. It gives a better visibilty on large projects and makes navigation easier.

Folding

Folding allows to hide a group of lines in a text file and to show only a descriptive headline instead. This allows to hide the details and to show the structure of a text file, like the summary of a book.

Clade implements marker-based folding: markers are inserted in the text file to delimit the beginning and the end of the sections of text to hide. These markers are embedded into program comments to prevent a compiler to interpret them, so it does not require any transformation before compilation. Plain text files can be folded as well as source code: the editor uses the '#' character as comment.

This method is the most flexible, you can fold any group of lines and specify any descriptive headline but it requires more work as you have to select manually the regions of text to be folded and provide a headline for each one.

Example

This is a small example in C, the fact function is folded with just a headline displayed. The implementation detail of the function is hidden an there is only a descriptive headline visible.

Simple folding a part of code

There are markers in comments at the beginning and at the end of the function, for the compiler, it is a perfectly valid source code. [of] stands for 'Open Fold' marker: it marks the beginning of the section. [cf] stands for 'Close Fold' marker: it marks the end of the section.

#include <stdio.h>

//[of]:fact(n) - Factorial
int fact(int n)
{
    if( n < 2 )
        return 1;
    else
        return n * fact(n-1);
}
//[cf]

int main()
{
    int n = 5;
    printf("fact(%d) = %d\n", n, fact(n));
    return 0;
}

Clade does not collapse and expand folded sections as in most folding editors. Instead, it always shows a folded section alone.

Sections can be nested, so a text file is no longer flat but becomes a hierarchy of sections. There are several way to navigate through such a hierarchy.

User Inteface

Files and Windows

Files and Windows are independent:

Opening a File

The Open command from the File menu opens a file in a new window. If this file is already loaded, it is not reloaded.

Viewing Loaded Files

The Files command from the File menu shows all loaded files and allows to open or re-open a file in a new window.

Closing a Window

Use the Close command from the Window menu to close the active window. This command unloads a file only if it is not used in another window.

If you close a window with a modified file, you will be asked to save changes but in some case it does not happen. Don't panic. The file is referenced somewhere else (in a search result, from another window...). Just use the File manager to reopen the file. You'll will be asked to save it anyway when exiting.

Cloning a Window

Use the Clone command from the Window menu to create an exact copy of the active window: the new window will have the same layouts that display the same sections in panes.

Reloading a File

A file can be reloaded when it is modified by another application. The reload-mode in options can change the behavior when an external file change is detected:

Splitting the Main Window

By default the application shows tabs in a single notebook, but it is possible to split the main window in two side-by-side notebooks. Use Move Window to Other Notebook from the Window menu.

Side-by-side view of the same file

Documents

A window does not edit a file directly, instead, it edits a Document. A document is basically a hierarchy of folders, file and sections of text. The application distinguishes several kind of documents:

A specific icon in the tab shows the kind of the document:

File Document

When opening or creating a file, a file document is opened: it just contains the file at the root.

Folder Document

When opening a folder from the menu or when dropping a folder into the editor, a folder document is opened: the root is the folder.

Project Document

A project document is similar to a folder document, but it can have additional files and folders attached to it and have custom user tools. The editor can have only one project document opened (but a document can be opened on multiple windows).

Option Document

This document is a special document that give an access to all loaded option files:

Search Result Document

This is a special document that allows navigation through the result of the current search. All folders, files and sections that were part of the search are shown, the ones containing one or more matches are highlighted and show the number of occurrences found at this level.

Search Result

Output Document

This document is generated after running a User Tool: it usually collects errors and warnings that reference a line in a file.

Output document

The navigator is the display of cascading lists at the top of windows.

Navigator

It can be shown or hidden from the View menu, or using the CTRL+Return shortcut.

The navigator provides convenient shortcuts to navigate through a document, this applies when the focus is on the navigator:

Shortcut Command
Up Previous line. If first line, it can go to the last line of the previous parent.
Down Next line. If last line, it can go to the first line of the next parent.
LeftPrevious list
RightNext list
HomeFirst line
EndLast line
Page UpPrevious page
Page DownNext page
CTRL+HomeFirst list
CTRL+EndLast list
Any letter Access to the next line starting with this letter

When opening a new window on a document, the navigator will be visible by default depending on the kind of document and some properties:

For search results and output, the navigator will be always visible by default.

Editing

Undoing a Change

There is an unlimited undo stack for each loaded file. Undo and Redo commands applies to the current file.

Copying and Pasting

Copying text from Clade will preserve the sections.

When pasting into another application, it will become a flat text, sections will just be expanded with a comment as the title of sections.

It is possible to copy a text into Clade without the folded sections as when copying to another application using Paste as Raw Text from the Edit menu.

Inserting a New Section

To insert a new section into a text file, use the Insert Section command from the Edit menu or press F12. If there is some text selected, is will be moved to the content of the section and the first line will be used as a default headline.

Inserting a Comment Line

Comment lines are just comments. They are displayed with an alternate background and without delimiter. It's only to prettify the code or make it a bit more like literate programming.

To insert a new comment, use the Insert Comment Line command from the Edit menu or press CTRL+SHIFT+C. If there is some text selected, is will be transformed into comment. Use the Insert Text Line command to revert the operation.

Searching

Clade has two types of search and replace: iterative and global. The global one searches all occurrences of a string and displays a list of matching lines.

Regular expressions can be used to search and replace complex expressions.

Special Characters in Search Pattern

Expression Description
. Matches any single character except newline
^ Matches the beginning of line if it is the first character of the search pattern
$ Matches the end of line if it is the last character of the search pattern
? Matches the preceding character or group zero or one time
* Matches the preceding character or group zero or more times
+ Matches the preceding character or group one or more times
( ) Group. Used to reuse the matched expression in the replace pattern or to repeat a pattern using ?, * or +
[ ] Matches a set of characters. The expression between bracket is a list of characters and range of character. A range of character is defined using the '-'. Example: [a-zA-Z_] matches any alphabetic character and the underscore. If the first character in the list is a '^', the expression matches all characters except the set of characters.
\t Matches the tab character
\ Matches the character following the backslash: the next character will not be considered as a special character. Useful to match ., ^, $, ?, *, +, [, ], (, ) or \.

Special Characters in Replace Pattern

Expression Description
\\ Inserts a backslash.
\1-9 Inserts the corresponding group.

Customizing

Lot of stuff can be customized in Clade:

To access option files, use the Options command from the View menu.

Options

Files

There are 3 main option files:

There can be additional option files when imported from one of the files above using the use keyword.

Global Options

The global option file is installed with the program and should not be modified. Instead modify properties in user-options.cbc, it can override anything from the global options anyway.

User Options

The user option file is automatically created in the user's directory:

Project Options

The project options exists only if there is a project open. It is found in the folder of the project.

General Syntax

A configuration file is just a sequence of properties and elements.

A property name starts with a letter and can contain letters, digits and dashes (-).

property = value

An element is a named object containing properties and other elements.

def name
    ...
end

The name has the same restrictions as property names.

An element can contain a special property 'prototype' that references another element. If this property is set, this element inherits all properties of the specified target element.

Color properties can use the hexadecimal form #RGB or #RRGGBB or it can use the default keyword to get the appropriate system color.

There is a color editor in the Tool menu that can be used to insert or edit existing colors.

Languages

A language element defines how a text file is highlighted and edited. A language is selected by the extension of the filename or the first line of the content, but it can also be changed from the View > Language menu.

Properties:

Name Format Description
patterns pattern1 [; pattern2 ...] The list of extension separated by a ';'. If this attribute is empty, and there is no 'first-line-patterns' attribute, this configuration is used as the default one.
first-line-patterns pattern1 [; pattern2 ...] The list of matching first lines separated by a ';'. Wildcards '*' are accepted.
encoding default
UTF-8
UTF-16-LE
UTF-16-BE
If specified, the file is loaded with the specified encoding even if the file does not contain a BOM marker. A new file is also saved with this encoding.
layout single
hlist
tree
The layout to use when opening a file of this language.
tabulation-size size Size of tabulations.
fixed true
false
Use fixed font by default.
word-wrap true
false
Turns on the word wrapping.
word-wrap-max-width width The maximum width for word wrapping, in glyph units. The width is computed using the font for normal text, either fixed or proportional depending on the fixed property.
show-line-type true
false
Adds a special symbols in a margin to show sections.
elastic-tabstops true
false
Use elastic tabstops by default.
expand-tabulation true
false
A tabulation is replaced by whitespaces.
auto-indentation true
false
Turns on auto-indentation.
stylizer batch
css
generic
html
makefile
monochrome
python
ruby
sh
tex
The stylizer is the function that colorize and style the text. Only the generic stylizer uses all the attributes described below.
line-comment string The beginning of a comment line. This attribute is used for folding as well as for colorization.
line-comment-2 string The beginning of an alternative comment line. This attribute is used for colorization only.
open-comment string The beginning of a comment block. This attribute is used for folding as well as for colorization.
close-comment string The end of a comment block
open-comment-2stringThe beginning of an alternative comment block
close-comment-2stringThe end of an alternative comment block
preprocessorstringThe preprocessor characters (e.g. '#')
hexa-prefixstringThe hexadecimal prefix (e.g. '0x')
extra-id-chars string Additional identifier chars that can be used in keywords. By default the identifier chars are [_A-Za-z0-9]. These additional chars do not apply to the first character of an identifier.
string-delimitercharThe delimiter character for strings
string-escape-charcharThe escape character inside strings
multiline-string-delimitercharThe delimiter character for multiline strings
regex-escape-charcharThe escape character inside a regex (e.g. '\' in Ruby)
char-delimitercharThe delimiter character for characters (or alternative strings)
char-escape-charcharThe escape character inside characters
multiline-char-delimitercharThe delimiter character for multiline characters (or alternative strings)
char-prefixcharThe prefix character for chars (e.g. '$' in Smalltalk)
variable-prefixcharThe prefix character for a variable (e.g. '$' in php). It will highlight this character and the following word with the same color as for words-4
escape-charcharThe escape character
ignore-casetrue
false
'true' if keywords are not case sensitive
user1stringFirst class of words
user2stringSecond class of words
user3stringThird class of words
user4stringFourth class of words

User Tools

A user tool is a command in the menu that launches an external program and capture the result. A typical usage is to launch an external compiler or interperter. It is possible to pass special values to the command line such as the filename of the current file or the current line number.

Syntax

Properties

Name Format Description
caption string This text will be displayed in the Tools menu and in the title of the output window.
command string The full name of the command to execute. Blanks are accepted, no need to use quotes.
arguments string The arguments to pass to the command. This attribute accepts special variables that will be substituted when launching the command. The syntax is $(variablename) where 'variablename' is described below.
directory string The directory where you want the command to execute. This attribute accepts the same variables as the arguments attribute.
save-all true
false
If true, all files are saved before launching the command. The command will not be launched if at least one save fails.
save-current true
false
If true, the current file is saved before launching the command. The command will not be launched if the save fails.
show-window true
false
Set this attribute to true for graphical tools, set it to false to the other to prevent the opening of a console. This attribute is unused on Unix platform.
language string If this value is set, the tool is available only with files of this language.
hot-key keycode An optional key to launch quickly the tool. The syntax is:

[CTRL+][ALT+][SHIFT+] keyname

auto-close true
false
If true, the output window will be closed if the tool terminates without error (i.e. exit code = 0) and does not report any link.
edit-arguments true
false
If true, the you will be prompted for arguments.
error-pattern-n regex A special regular expression to define a custom error pattern: if a line from the output matches the pattern, it will be recognized as an error message, the output line will be converted into a link and the target line will be marked as an error.

The pattern is a regex with the following rules:

  • \F matches the filename. The filename can be relative to the initial directory (the directory property) or absolute.
  • \L matches the line number.
  • The regular expression must not include any group, remember that parenthesis must be escaped with backslashes: \( \).

Example: an errors such as

c:\myproj\src\main.c(15): Error: 'myvar' undefined

will be recognized with the pattern \F\(\L\): .*

Variables in Arguments:

Name Description
WorkDir The directory of the current project.
FilePath The full name of the current file
FileDir The directory of the current file
FileName The filename without directory and without extension
FileNameExt The filename with extension but without directory
CurText The current selection or the word under the caret. This value will be empty if the selection contains new lines.
CurLine The current line of the caret. This value is an absolute line number i.e. starting from the beginning of the file, not the section.
CurCol The current column of the caret. This value is an offset, tab characters are not expanded.

Handling Output

When a tool is run, its output is parsed. If a line is recognized as an error or warning message, it will appear in the output window as a link. By default, the editor recognizes two patterns:

filename:line:message
filename(line):message

but it can be customized with the error-pattern properties.

If the file is not an absolute path, the directory specified in tool is used. If there is no directory specified, the current working directory of the editor is used instead.

Example

def tools

    def build-cb
        caption = Build Code Browser
        command = cmd.exe
        arguments = /c build.bat
        directory = c:\projects\code-browser
        save-all = true
        hot-key = F7
    end

    def run-cb
        caption = Run Code Browser
        command = cb.exe
        directory = c:\projects\code-browser
        show-window = true
        hot-key = F5
    end

end