Copyright © 2004-5 Marc Kerbiquet
Abstract
Code Browser is a folding and outlining editor for Linux and Windows.List of Tables
Table of Contents
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.
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.
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:
line1
line2
//[of]: This is a folder
line3
line4
//[cf]
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.
Table of Contents
The application supports two independent features:
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.
The command from the menu opens a file in a new window. If this file is already loaded, it is not reloaded.
The command from the menu shows all loaded files and allows to open or re-open a file in a new window.
Use the command from the 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.
Use the command from the 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.
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:
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 command from the menu. It happens only with windows displaying sub-folders and where changes occured on a parent folder.
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.
The command from the 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.
When the caret is on a folder, you can use the command from the menu to modify its name and identifier.
The command is also available from the contextual menu.
When the caret is on a folder, you can use the command (ALT-Right) from the menu to edit its content.
This command is also available by double-clicking on the line.
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 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.
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>
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 menu.
There is 3 classes of layouts.
Can be arranged horizontally or vertically. The second pane displays a preview of the line selected by the first pane.
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.
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.
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.
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: may cancel a change made in another window if the focus is in the wrong pane. Anyway an operation can always be undone with the command.
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:
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. |
Table of Contents
The editor uses two configuration files:
For each configuration file, the program first loads the file in the program directory, then merge it with the file in the home directory if any. In addition an extra configuration file can be merge to preferences.cb-config when using the -c option from the command line.
The files from the program directory contain original settings that can be overriden by the settings from the file in home directory. It will be erased and replaced when upgrading (using make install on unix or the installer on windows). So avoid modifying it.
The files from the home directory contain your customizations and won't be lost when upgrading. This file if not exist is a copy of the default preferences.cb-config for easier use, but you can remove everything from this file and just add your changes.
The file specified in command line (-c) is typically used for project specific customizations. e.g. user tools to compile and run a specific project.
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
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.cb-config. These properties are used to define the system color themes but you can use them.
Table 2.2. Builtin properties in preferences.cb-config
| 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 |
Use the command from the menu to edit the preferences.
If there is no preference file in the home directory, the file is loaded from the program directory and is immediately renamed with the home directory, so it will be saved to the right location. If the directory does not exist, it will be created automatically.
An edit scheme allows to customize auto indentation, tabulations and word wrapping.
Each edit scheme is defined as follow:
def name auto-indentation = (true|false) expand-tabulation = (true|false) tabulation-size = size word-wrap = (true|false) end
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.
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. |
The output does not have a filename, so links must have a full name to locate target files.
[CTRL+][ALT+][SHIFT+] keyname
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.
If you want to edit the language file, either copy languages.cb-config in your home directory, or backup it before re-installing a new version.
Table 2.4. Attributes for a Language Definition
| Name | Description |
|---|---|
| colorizer |
The name of the colorizer function.
It can be one of:
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 |
| 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 |
| char-escape-char | The escape character inside characters |
| 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 |
Table of Contents
code-browser [-i] [-c config] file1 file2 ...
Starts the editor and opens a window for each file specified in command line.
This switch forces to create a new instance of the editor, overridding the allow-multiple-instances option in the configuration file.
This option specifies a configuration file that will be merged to preferences.cb-config. 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.cb-config.
With this option, the -i switch is implicit.
Table of Contents
This is a various collection of tips to better use the potential of the program.
There is no bookmark, but you can use an alternate window to remember a position:
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.