Code Browser Documentation

Marc Kerbiquet

<mkerbiquet@users.sourceforge.net>

Copyright © 2004-7 Marc Kerbiquet

Abstract

Code Browser is a folding and outlining editor for Linux and Windows.

Table of Contents

Introduction
Principle
Relative indentation
1. Concepts
Files and Windows
Folders and Links
Folders
Links
Special Links
Layouts
Undo - Redo
Find and Replace
2. Customization
Files
General Syntax
Edit Configurations
User Tools
Add or Modify a Language Definition
3. Command Line Reference
Usage
A. Miscellaneous
Tips

List of Tables

1.1. Special character in search pattern
1.2. Special character in replace pattern
2.1. Special sequences in property values
2.2. Builtin properties in preferences.cbc
2.3. Variables in Arguments
2.4. Attributes for a Language Definition


Introduction

Table of Contents

Principle
Relative indentation

Code Browser is a text editor that allows you to structure your source code like an hyper-text document: the source code can be cut into pages independently of the file structure. A page can be referenced using links or can be nested into another page. It gives a better visibilty on large projects and makes navigation easier.

For a quick start, open samples/tutorial.c with the application.


Principle

Special directives are inserted in the source code as comments. The file saved on disk is completely compatible with any programming language having comments (single or multi-lines). It does not require any transformation before processing.


Relative indentation

Code Browser can fold a text file in two ways: with absolute indentation or with relative indentation. The mode can be defined independently for each configuration. Here is two examples:

  • Absolute indentation
    line1
    line2
//[of]:    This is a folder
    line3
    line4
//[cf]
  • Relative indentation
    line1
    line2
    //[of]:This is a folder
    line3
    line4
    //[cf]

In both cases the header is indented, but when you edit the content of the first folder, the text is also indented, whereas in the second one the text will start at column 1.

By default, absolute indentation is used.

The relative indentation is useful for indentation sensitive syntaxes such as Python: when editing the content of a sub-folder, you don't have to care about indentation, just indent or unindent its header to update its real indentation.

The relative indentation is auto-detected when loading a file (the tags are indented), so anybody can open it and read it with the same indentation wihtout having to change their settings.


Chapter 1. Concepts

Table of Contents

Files and Windows
Folders and Links
Folders
Links
Special Links
Layouts
Undo - Redo
Find and Replace


Files and Windows

The application supports two independent features:

  • multiple files
  • multiple windows

A loaded file can be displayed in zero, one or more windows.

Usually, a text editor has only one window per file. When you want to open a file that is already opened, it just brings its window to front. With Code Browser, a file is loaded only once but several windows can be opened on it.

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 does not unload any file. That's why it never asks for save confirmation. Confirmations occur only 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 folders 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

Sometimes some windows could unexpectedly disapear while reloading. But don't worry, the file has been reloaded and you can re-open a window on it with the Files... command from the File menu. It happens only with windows displaying sub-folders and where changes occured on a parent folder.


Folders and Links

Folders

A folder is a group of lines collapsed into one single line. A folder can include sub-folders. By default, folder lines are displayed in blue. Folders can be used only with a language having a comment directive.

Inserting a New Folder

The Folder command from the Insert menu opens the folder creation dialog. Enter a name and an identifier. Use \t to put tabs in the name. The identifier is needed only if you want to reference this folder (i.e. creating a link to it).

Any text selected before is moved into the newly created folder. This feature helps to structure an existing flat file.

Editing Folder Properties

When the caret is on a folder, you can use the Properties command from the Edit menu to modify its name and identifier.

The command is also available from the contextual menu.

Entering into a Folder

When the caret is on a folder, you can use the Enter command (ALT-Right) from the Go menu to edit its content.

This command is also available by double-clicking on the line.

Leaving a Folder

To go back to the previous folder, use the Back command (ALT-Left) from the Go menu.

Links

A link is a reference to a folder either in the same file or in an other file. This concept is similar to links in HTML documents. It can be useful to add links to related items (related functions, definitions of classes, ...).

A link is similar to a folder: the Enter command follows the link instead of opening a folder. Properties are edited in the same way.

By default, link lines are displayed in green.

The syntax for the path is:

<filename>[#<folder-path>]

Where <filename> is the filename with path relative to the current file. The path separators are '/' even on Windows platform, not '\' in order to have platform independent files. <folder-path> is optional, it is the path in the file to reach the target folder. The path separators are also '/' between folders.

Special Links

It is possible to create special links pointing to a line identified by a line number or a regular expression.

Link to a line in a folder:

<filename>[#<folder-path>]?ln=<line-number>

Link to a line in a file:

<filename>?aln=<line-number>

Link to the first line matching a regular expression:

<filename>[#<folder-path>]?s=<regular-expression>

or case insensitive:

<filename>[#<folder-path>]?is=<regular-expression>

Reminder

  • A folder (blue) owns its content
  • A link (green) is a reference to a remote folder
In short: deleting a blue line deletes the content, deleting the green line has no effect on the source code.


Layouts

Each window can show one or more panes: each one displays the content of the folder or link selected by its predecessor. The layout of the active window can be changed using the View menu.

There is 3 classes of layouts.

One Pane

Display only one folder. This is the default mode.

Two Panes

Can be arranged horizontally or vertically. The second pane displays a preview of the line selected by the first pane.

More than Two Panes

This is more complex layouts, there is several 'list' panes arranged in a row or a column and a 'text' pane at the bottom or the right.

A folder is displayed in a list pane if it contains only links, sub-folders and comments but no text, otherwise it is displayed in the text pane.

Tree View

Display one folder and a tree view of the file. Sub-folders can be reached directly with this tree. Links are also expanded in the tree.

Customizing the default layout

The layout can be customized for each configuration. So it is possible to open a file in a new window with a layout depending on the file type. There is two attributes in the general section of preferences: 'layout' and 'tree.view'. These attributes can be overridden for each configuration. See the preferences file for more information.


Undo - Redo

There is an unlimited undo stack for each loaded file.

You must be careful since a window can display several files and several windows can display the same file: undo may cancel a change made in another window if the focus is in the wrong pane. Anyway an undo operation can always be undone with the redo command.


Find and Replace

Code Browser has two types of search and replace: iterative and global. The global one searches all occurrences of a string and displays a list of links to matching lines. The two modes does not support same features:

Iterative Search/Replace (CTRL-F, CTRL-R)

  • Cannot find text in headlines
  • Cannot follow links
  • Cannot search in sub-folders if scope is current folder

Global Search/Replace (CTRL-H, CTRL-SHIFT-R)

  • Can find text in headlines
  • Can follow links
  • Can search in sub-folders
  • Can search in current selection
  • Can search in multiple files

Note

For convenience, there is a 'Replace All' accessible from the iterative replace dialog. But consider using the global replace instead because it reports modified lines.

Note

In this application, the term 'folder' means folded sections inside text files, so to avoid confusions with folders on disks, the 'directory' term will be used to refer to disk folders

Regular Expressions

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

Table 1.1. Special character 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 \.

Table 1.2. Special character in replace pattern

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


Chapter 2. Customization

Table of Contents

Files
General Syntax
Edit Configurations
User Tools
Add or Modify a Language Definition

Use the Options command from the Tools menu to edit the user preferences.


Files

The editor loads first all configuration files in the config global directory, then it loads all configuration files in the config user directory, and finally it will load an optional configuration file specified using the -c command line option.

On Unix platform

  • the global directory is (by default): /usr/local/share/code-browser
  • the user directory is: $(HOME)/.code-browser

On Windows platform

  • the global directory is the directory of the executable
  • the user directory is: "\Documents and Settings\CurrentUser\Application Data\code-browser"

The configuration files are merged into one document before being processed. They all have the same syntax.

The files in the global directory contain original settings that will be overriden when upgrading, so you should not modify them.

The config-default directory contains the default user configuration file. This file will be automatically copied into the user directory on the first access to the options from the Tools/Options... menu. All properties are commented out, this prevent overriding the settings defined in the global preference file. Just uncomment properties you want to modify and and change their values.

The config-optional directory contains optional configuration files that are not activated by default. To use them, just copy them into the user or global config directory.

The file specified in command line (-c) is typically used for project specific customizations. such as user tools to compile and run a specific 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.

Table 2.1. Special sequences in property values

Expression | Description
%_ | Whitespace
%% | %
%(path.prop) | Replaced by the value of the property found at the absolute path
%(.path.prop) | Replaced by the value of the property found at the relative path
%(prop) | Replaced by the value of the property found at the root level
%(.prop) | Replaced by the value of the property found at the current level

The parenthesis are not required and can be omitted when there is no ambiguity.

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.

A property can overwrite directly an existing value in a sub-element:

sub-elem-1.sub-elem-2.property = value

A configuration file is not restricted to properties recognized by the editor, you can define your own and reuse them at different places.

The preferences have access to the following builtin properties: There is builtin properties accessible in preferences.cbc. These properties are used to define the system color themes but you can use them.

Table 2.2. Builtin properties in preferences.cbc

Name | Description
p | The current platform (win32 or x11)
system.back-color | The system background color of text
system.medium-color | An intermediary color between the background color and window color
system.fore-color | The system foreground color of text
system.inactive-back-color | The background color for selected objects when inactive
system.highlight-back-color | The background color for selected objects
system.highlight-fore-color | The foreground color for selected objects


Edit Configurations

A configuration determines how to display and edit a file given its extension or its first line.

Each configuration is defined as follow:

def name
  patterns = pattern1 [; pattern2 ...]
  first-line-patterns = pattern1 [; pattern2 ...]
  language = language
  display = display-scheme
  layout = 0..9
  tree-view = (true|false)
  relative-indentation = (true|false)
  auto-indentation = (true|false)
  expand-tabulation = (true|false)
  tabulation-size = size
  word-wrap = (true|false)
end
patterns
The list of extension separated by a ';'. If this attribute is missing, and there is no 'first.line.patterns' attribute, this configuration is used as the default one.
first-line-patterns
The list of matching first lines separated by a ';'. Wildcards '*' are accepted.
language
The language used to structure and colorize the text.
display
The display scheme (defines colors and fonts).
layout
If specified, it overrides the property defined in the general section.
tree-view
If specified, override the property define in the general section.
relative-indentation
If true, each folder will be indented with the indentation of its headline.

Remark: this option has no effect on a file already opened, you must exit and restart.

Warning: use this option carefully, once a file is saved with relative indentation, it cannot be undone easily.

auto-indentation
Turns on auto-indentation.
expand-tabulation
A tabulation is replaced by whitespaces.
tabulation-size
Size of tabulations.
word-wrap
Turns on the word wrapping.


User Tools

Customized tools can be launched from the 'Tools' menu. To add new tools, edit the 'tools' section from the options. Each tool is defined as follow:

def name
  caption = caption
  command = command name
  arguments = list of arguments
  directory = initial directory
  save-all = (true|false)
  show-window = (true|false)
  language = language definition
  layout = 0-8
  tree-view = (true|false)
  hot-key = key
  auto-close = (true|false)
  edit-arguments = (true|false)
end

The name identifies the tool but it is not used yet.

caption
This text will be displayed in the Tools menu and in the title of the output window.
command
The full name of the command to execute. Blanks are accepted, no need to use quotes.
arguments
The arguments to pass to the command. This attribute accepts special variables that will be substitute when launching the command. The syntax is $(variablename) where 'variablename' must be one of:

Table 2.3. Variables in Arguments

Name | Description
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 folder.
CurCol | The current column of the caret. This value is an offset, tab characters are not expanded.
directory
The directory where you want the command to execute. This attribute accepts the same variables as the arguments attribute.
save-all
If true, all file are saved before launching the command.
show-window
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 Linux platform.
language
If this value is set, the output is parsed using the specified language definition. So it is possible to have tools that generate structured output (including sub-folders and links). In such a case, the entire output is buffered until the process terminates.

The output does not have a filename, so links must have a full name to locate target files.

layout
The layout to use with the output window when launching this tool. By default, two panes tiled vertically are opened.
tree-view
Switch to show or hide the tree view with the output window.
hot-key
An optional key to launch quickly the tool. The syntax is:

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

auto-close
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
If true, the you will be prompted for arguments.

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. The editor recognizes two syntaxes:

filename:line:message
filename(line):message

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.


Add or Modify a Language Definition

Table 2.4. Attributes for a Language Definition

Name | Description
colorizer The name of the colorizer function.

It can be one of:

  • batch
  • css
  • generic
  • html
  • makefile
  • monochrome
  • python
  • ruby
  • sh
  • tex

Only the generic colorize function uses all of the following attributes.

line-comment | The beginning of a comment line. This attribute is used for folding as well as for colorization.
line-comment-2 | The beginning of an alternative comment line. This attribute is used for colorization only.
open-comment | The beginning of a comment block. This attribute is used for folding as well as for colorization.
close-comment | The end of a comment block
open-comment-2 | The beginning of an alternative comment block
close-comment-2 | The end of an alternative comment block
preprocessor | The preprocessor characters (e.g. '#')
hexa-prefix | The hexadecimal prefix (e.g. '0x')
string-delimiter | The delimiter character for strings
string-escape-char | The escape character inside strings
multiline-string-delimiter | The delimiter character for multiline strings
regex-delimiter | The delimiter character for regex (e.g. '/' in Ruby)
regex-escape-char | The escape character inside a regex (e.g. '\' in Ruby)
char-delimiter | The delimiter character for characters (or alternative strings)
char-escape-char | The escape character inside characters
multiline-char-delimiter | The delimiter character for multiline characters (or alternative strings)
char-prefix | The prefix character for chars (e.g. '$' in Smalltalk)
variable-prefix | The 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-char | The escape character
ignore-case | 'true' if keywords are not case sensitive
words-1 | First class of words
words-2 | Second class of words
words-3 | Third class of words
words-4 | Fourth class of words
chars-1 | First class of chars
chars-2 | Second class of chars
chars-3 | Third class of chars
chars-4 | Fourth class of chars


Chapter 3. Command Line Reference

Table of Contents

Usage


Usage

code-browser [-i] [-c config] file1 file2 ...

Starts the editor and opens a window for each file specified in command line.

-i

This switch forces to create a new instance of the editor, overridding the allow-multiple-instances option in the configuration file.

-c config

This option specifies a configuration file that will be merged to preferences.cbc. It allows for instance to specify project specific tools.

Example of custom preferences:

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

These tools will be added to the user tools defined in preferences.cbc.

With this option, the -i switch is implicit.


Appendix A. Miscellaneous

Table of Contents

Tips


Tips

This is a various collection of tips to better use the potential of the program.

Using a Project File

Code Browser does not handle projects, but it is easy to create a file to access all files of a project: just create a file project.cbi and then add links to the source files.

Transforming Text to Comment and Vice Versa

The Text Line and Comment Line commands in the Insert menu can be used to transform the current selection into comment or text. It can be useful to comment/uncomment source code, but also to transform source comments into Code Browser comments.