To be a subject for sourceexporer, a source file requires markup as described in succeeding topics. Source lines must end with selectors beginning "//=". The code may be sectioned with marker lines beginning "//@". And definition lines describe the explorable features;

TAGS

A tag is a sequence of lowercase letters Each tag denotes a feature of the code, one without which the code can still work, but will be less useful (perhaps imperceptibly) Tags are defined on lines of the form

//TAG name required description

The second field names a tag for a feature which must be present if the named tag is to be part of an executable program.

SELECTORS

A code line ends with a selector denoting which tag(s) that line implements. A selector is

slash slash equal tag [space sign tag]

or

slash slash  equal tag space plus tag space plus tag

In all, a line tag ends in one of

//=abc
//=abc +def
//=abc -def
//=tag |tag
//=tag +tag +tag
//=tag +tag -tag

Nominally, the only spaces are before the signs. However, all spaces are ignored.

Lines are counted and ignored if they are blank, untagged, or end in //0.

Tagged lines are extracted or ignored depending on the correspondence between the line tags and the selector tags specified on the command line.

If the line is chosen for extraction, everything from the // to the end of line is removed.

//=abc

A line tagged with form //=abc is extracted whenever abc is in the list of selector tags.

//=abc+def

In this tagging abc is the context of surrounding affectedLines. The line is to be extracted along with that context to implement the def feature. The abc context should be able to operate without the line, except it will not have the def feature. Accordingly, when extracting an excerpt of the file, the line will be extracted whenever def is selected. However, when extracting an EXECUTABLE file, the line will be extracted only if both abc and def are selected. See example below.

//=abc +def +ghi

A line tagged this will be extracted only if all three tags are requested.

//=abc +def -ghi

A line thus tagged will be extracted if both abc and def are being extracted wile ghi is not.

//=abc|def

A line thus tagged will be extracted when either of its two tags is selected. If only one of the two is selected, the context of the line is that tag. If both are selected, the context is arbitrarily set to the first of the tags.

//=abc -def

A line tagged like this is selected if the context tag abc is selected and the feature tag def is not. The line must begin with two slashes. They are removed when the line is selected (and the line is ignored if not selected).

When a section of code has two alternative versions the appropriate tagging is

// code used if aaa is selected and ppp is not   //=aaa -ppp
code used if aaa and ppp are both selected   //=aaa +ppp

The raw code, when not run through extract, will compile and will have both the aaa and ppp features.

EXAMPLE for //abc +def

Suppose method qwertList() produces a list and tag qwerty extracts this method. Most affectedLines end with //=qwerty. Sorting may be an added feature for qwertList(). The line that calls the sort method would be tagged with //=qwerty +qwertysort This line is extracted whenever the qwertysort tag is in the selected list; even if qwerty is not. If extracting instead an EXECUTABLE, the line is extracted only if both qwerty and qwertysort are selected. If extracted when only qwertysort is selected, the line would be extracted without its context and the program would not compile.

TAGGING SUMMARY

LINE

A line beginning //LINE and have an integer gives the line number for the next line. Numbering is then sequential. If no //LINE appears, the first line is numbered 1.

TREE - REQUIRES

The set of possible tags is organized in a hierarchy. To build an executable including some tag, all the parents of that tag must also be selected for extraction. Thus we may find a sequence of affectedLines for feature //=dxyk and among them a line for the //=dzgm feature. The program will be compilable as long as the dzym feature is a descendant in the tree of dxyk.

Within this program, the tree is expressed in the directReq array, giving the directReq for each tag. The program expands this information so the allReq array gives the full list of ancestors for each tag.

Additional constraints may be given in REQUIRES lines:

//REQUIRES tag needed-tag

The allReq list for tag is augmented with needed-tag. The program propagates the requirements so that any client tag that requires the first named tag will also be made to require needed-tag.

SUBSETS

In addition to the fine grained structure imposed by tags, a program may be perceived as a sequence of versions each with a superset of the functionality of the formmer. For SourceExplorer these subsets must be defined in terms of the list of tags selected for each. They are described to SourceExplorer with SUBSET lines:

//SUBSET name list-of-tags

The name of a subset is in all-caps. The list-of-tag may include a subset name.

TEST

Same syntax as a subset, but the line begins //TEST The named tests are added to the SourceExplorer pull-down menu for tests. only the allMembers field is used, not the ownMembers.

SECTIONS

A source file may be segmented in sections: features, methods, classes. Each section begins and ends with a section line:

//@[ ~section description
    . . .
//@] ~section description

Sections may be nested. There is one copy of " ~" for each level of nesting. The description should be identical in the opening and closing lines.

Example section lines

//@[FontViewer.java - Display system fonts, with a sample in each
//@[ ~FontViewer preface - comment, package, imports
//@] ~FontViewer preface - comment, package, imports
//@[ ~FontViewer class
//@[ ~ ~FontViewer.main() : the main program
//@[ ~ ~FontViewer.main().invokeLater() : launch the application
//@] ~ ~FontViewer.main().invokeLater() : launch the application
//@] ~ ~FontViewer.main() : the main program
//@] ~FontViewer class
//@]FontViewer.java - Display system fonts, with a sample in each