Documentation

Table of Content

• Introduction
• Folding
  • Example
• User Inteface
  • Files and Windows
  • Documents
  • Navigator
• Editing
  • Undoing a Change
  • Copying and Pasting
  • Inserting a New Section
  • Inserting a Comment Line
• Searching
• Customizing
  • Files
  • General Syntax
  • Languages
  • User Tools

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.

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:

• A window can edit multiple files.
• A file can be edited in multiple windows.

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:

• never: never reload
• ask: ask before reload
• always: reload without asking unless the file is modified

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.

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 single file document
• A folder document
• A project document
• An option document
• A search result document
• An output document

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

• File
• Folder
• Project
• Options
• Search Result
• Output

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:

• global-options.cbc The global options. This one should not be modified
• user-options.cbc The user options, it can override global options.
• project.cbc The project options, available if a project is open.
• Any additional file imported from another option file.

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.

Output Document

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

Navigator

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

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:

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

• Project document: determined by the project-layout option.
• Folder document: determined by the folder-layout option.
• Options: determined by the options-layout option.
• File document: determined by the layout option of the associated language.

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

Special Characters in Replace Pattern

Customizing

Lot of stuff can be customized in Clade:

• Create or modify themes.
• Create or modify languages (syntax highlighting, tab behavior, ... for each file type).
• Create tools to launch external programs.

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

Files

There are 3 main option files:

• global-options.cbc -- The global options
• user-options.cbc -- The user options
• .project.cbc -- The project options

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:

• ~/.config/clade-1/user-config.cbc on Unix systems
• <user>\Application Data\clade-1\user-config.cbc on Windows

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

• Blanks preceding and following the value are ignored.
• % is a special character in values.
• Use %% to get a %.
• Use %_ to get a whitespace (whitespaces at the end of line are removed).

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:

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

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

Variables in Arguments:

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