Copyright © 2004-10 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.txt 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 are four different layouts.
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.
With this layout, each sub-folder is displayed at the right of its parent. Three folders are visibles and the view is scrolled with an animation when changing level.
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. |
Copying and pasting text works almost like any other text editors with few differences due to the folding system.
This is a special copy: the location of the current folder is copied instead of the selection. This command works only at the toplevel of a file or in a subfolder if all parent folders have a name.
When the location is pasted in a text file edited in Code Browser, a link to this location is inserted. The link uses a relative path when possible.
Table of Contents
Use the command from the menu to edit the user preferences.
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.
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.
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.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 |
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 = (single|tree|list|page) tree-view = (true|false) relative-indentation = (true|false) auto-indentation = (true|false) expand-tabulation = (true|false) tabulation-size = size word-wrap = (true|false) end
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.
Customized tools can be launched from the 'Tools' menu. To add new tools, edit the 'tools' section from the options.
def name caption = caption command = command name arguments = list of arguments directory = initial directory save-all = (true|false) save-current = (true|false) show-window = (true|false) language = language definition layout = (single|tree|list|page) hot-key = key auto-close = (true|false) edit-arguments = (true|false) error-pattern-1 = regex error-pattern-2 = regex error-pattern-3 = regex error-pattern-4 = regex error-pattern-5 = regex error-pattern-6 = regex error-pattern-7 = regex error-pattern-8 = regex error-pattern-9 = regex 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
The pattern is a regex with the following rules:
Example: an errors such as
c:\myproj\src\main.c(15): Error: 'myvar' undefined
will be reconized with a pattern like this: \F\(\L\): .*
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.
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
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') |
| extra-id-chars | 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-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 |
Table of Contents
code-browser [-i] [-c config] file1 file2 ...
Starts the editor and opens a window for each file specified in command line. Each file name can be followed by a colon and a line number to force the file to be opened at a particular line:
filename: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.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.
Table of Contents
This is a various collection of tips to better use the potential of the program.
To get the full path of the current file, use the menu command (ALT-F F). The path of the current file is displayed at the bottom of the window.
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.