Folding

1. Overview

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.

Code Browser 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. However the extra effort is worth it.

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.

#include <stdio.h>

fact(n) - Factorial

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

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;
}

Code Browser 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.

2. Links

A link is a reference to a section either in the same file or in another file. This concept is similar to links in HTML documents. Links are useful to reference related pieces of text or to create list of files or sections.

A link is similar to a folded section: the Enter command follows the link instead of entering into a subsection. Properties are edited in the same way.

All standard themes display the link in green.

A link is saved in a comment, prefixed with a [l] marker. The syntax for the path is:

filename[#section-path]

Where filename is the filename with path relative to the current file. The path separators are '/' even on Windows in order to have platform independent files. #section-path is optional, it is the path in the file to reach the target section. The path separators are also '/' between sections.

3. 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 section:

filename[#section-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[#section-path]?s=regular-expression

or case insensitive:

filename[#section-path]?is=regular-expression