SoDA allows you to extend the schema of its source domains with a domain extension file. This file is named DOMAIN.EXT and must be located in the SODA_HOME\domains directory. SoDA domain extensions allow you to define new:
§ Attributes for a source class that are:
- Parsed from an existing attribute
- Derived by a batch script that is passed existing attributes as arguments
§ Unary relationships for a class to files and/or directories
§ N-ary relationships for a class to files and/or directories
The syntax for describing the various domain extensions is described in the following sections. These syntax descriptions use pointy brackets (<>) to indicate the description of an item and ellipsis (...) to indicate that an item may be repeated. All other characters are literal.
The domain extension file contains one or more extension specifications for existing classes. The syntax for these extensions is:
EXISTING_CLASS <Domain>.<Class>
<Parsed Attribute>
...
<Script Attribute>
...
<Unary Relationship>
...
<N-ary Relationship>
...
END_CLASS
...
where <Domain> is the name of an information source domain—for example: FileSys, Frame, or Rose—and <Class> is the name of any class defined in that domain—for example: Directory or File in the File System domain.
Parsed attributes, script attributes, Unary relationships, and N-ary relationships are described in the following pages.
Parsed attributes provide a convenient way to define additional structure within an existing attribute. Parsed attributes are evaluated by searching the source attribute for the start delimiter, then searching for the end delimiter, and returning the text in between but not including the two delimiters. The syntax for specifying a set of parsed attributes to be generated from a source attribute is:
EXISTING_CLASS <Domain>.<Class>
SOURCE %<Attribute Name>%
ATTRIBUTE <Name> "<Start Delimiter>" "<End Delimiter>"
...
END_SOURCE
END_CLASS
Note that the ATTRIBUTE keyword, the name, and the start and end delimiters must all appear on the same line in the domain extension file. If you omit the end delimiter, it defaults to the new line character.
The most common use of parsed attributes is to define keywords to be specified in program comments. For example, if you wanted to define ID, author, and purpose keywords for Rose classes, you would add the following lines to your domain extension file:
EXISTING_CLASS Rose.CClass
SOURCE %Documentation%
ATTRIBUTE @Ident "@ID:" "@"
ATTRIBUTE @Author "@AUTHOR:" "@"
ATTRIBUTE @Purpose "@PURPOSE:" "@"
END_SOURCE
END_CLASS
These lines will cause @Ident, @Author, and @Purpose attributes to appear in the SoDA Field dialog for Rose classes. The use of the at-sign (@) character in the attribute name is not required, but rather is a convention followed to distinguish schema extensions from the base attributes of a class.
Script attributes allow you to provide shell scripts that derive new attributes for a class from existing attributes of the class. The syntax for adding script attributes to a class is:
EXISTING_CLASS <Domain>.<Class>
ATTRIBUTE <Name> <Script Name> <Argument List>
...
END_CLASS
Note that the ATTRIBUTE keyword, the script attribute’s name, the script name, and the script’s arguments must all appear on the same line in the domain extension file. The <Script Name> must be a simple command name, and the <Argument List> must be a list of one or more attributes of the class enclosed in percent signs (%).
Beware of blanks or new lines in arguments. The script name and its arguments are simply passed to the shell—which will behave as usual—for interpretation.
For example, if you wanted to add attributes for the number of lines and number of words in a file, you could add the following lines to your domain extension file:
EXISTING_CLASS File.File
ATTRIBUTE @LineCount linecount %FullName%
ATTRIBUTE @WordCount wordcount %FullName%
END_CLASS
These lines will cause @LineCount and @WordCount attributes to appear in the SoDA Field dialog for File System files. You will also need to write two executables, named linecount and wordcount, which given the full pathname to a file, calculate and return the number of lines and words in it, respectively.
It is possible to define additional Unary relationships for a class. These relationships can only be to the following File System domain classes: DirectoryObject, File, or Directory.
The syntax for defining Unary relationships from one class to another is:
EXISTING_CLASS <From Domain.Class>
UNARY_RELATIONSHIP <Name> <FileSys.Class> <Naming Exp>
...
END_CLASS
where <Naming Exp> is any valid file naming expression. You can reference other attributes of the (from) class within the naming expression by enclosing them in percent signs (%).
Note that the UNARY_RELATIONSHIP keyword, the name, the domain, the class, and the naming expression must all appear on the same line in the domain extension file.
For example, adding the following lines to your domain extension file defines a new relationship named @Design from an Apex view to a subdirectory within that view called design:
EXISTING_CLASS Apex.View
UNARY_RELATIONSHIP @Design File.Directory %FullName%"\design"
END_CLASS
It is also possible to define N-ary relationships to File System domain classes in the same manner as Unary relationships. The syntax for defining N-ary relationships from one class to another is:
EXISTING_CLASS <From Domain.Class>
NARY_RELATIONSHIP <Name> <To Domain.Class> <Naming Exp>
...
END_CLASS
<Naming Exp> is the same as for Unary relationships with the exception that wildcard characters can be used.
Note that the NARY_RELATIONSHIP keyword, the name, the domain, the class, and the naming expression must all appear on the same line in the domain extension file.
For example, adding the following lines to your domain extension file defines a new N-ary relationship named @Pics from a directory to all PostScript files within that directory:
EXISTING_CLASS FileSys.Directory
NARY_RELATIONSHIP @Pics FileSys.File %FullName%"\*.ps"
END_CLASS