Wilma uses a simple command language where each command is of the form:

Target Action Parameters

where the target is the Wilma object to which to apply the action. In Wilma's case, there are very few objects which can be targets. The base object is the index itself and it only contains two child objects, the search criteria and search referrals. The search referrals in turn has each referral as a child. Thus the entire object network for Wilma looks something like:

Index (named / )

These objects are addressed by giving a path of ancestors separated by dots. Thus the full name for the search criteria would be:


and one of the referrals might be:


Strictly speaking the dot is not necessary immediately following the slash designating the root object, but including it may make the relationships clearer.

The default object is the object to which commands which omit the target term are directed. Normally in Wilma, the root object is also the default object, but it is possible to change the default object with the cd command (see below). Target addresses that start with a dot rather than a slash are also considered relative to the default object. Since Wilma has few objects there will rarely be a need to change the default.

Some actions are understood by all objects, while others only make sense to parent objects that contain other objects (/ and /.referrals in Wilma's case) and of course some actions are only recognized by specific objects.

Actions All Objects Understand

cd Change the default object to the one described by the path passed as the parameter. For example:

cd /.referrals

getvalue Retrieve the value of the object property named as the parameter. For example:

/.referrals getvalue name

Note that all objects have a name and classname property.

read Open the file whose path name is given by the parameter and execute the commands in the file. For example

read /Users/craig/test.txt

If test.txt contained the single line:

/.criteria setvalue maxsize 10000

then the effect would be to set the maximum file size in the search criteria to 10000 characters.

rbscript Run the RealBasic script whose path name is given by the parameter. A basic example is available, but this stuff is probably not for the faint of heart.

renameto Change the name of the target to the value of the parameter. For example:

/.referrals.mymail renameto mainmail

Wilma has some basic undo and redo capability, which is not currently reflected in the graphical user interface. For instance, if you set the criteria maximum file size with:

/.criteria setvalue maxsize 100000

and then give the command:


Wilma will restore the original value. Then typing:


would repeat the command and set the value to 100000 once again. You cannot undo everything and in particular cannot undo builds and updates or other commands specific to Wilma objects.

setvalue Set the value of the target's property as named in the first parameter to the value of the second parameter. For example the now familiar:

/.criteria setvalue maxsize 100000

Arbitrary values can be created by using a name starting with an underscore character. Wilma reserves value names starting with two underscores for its own use and currently sets __selected to a tab delimited list of the file ids of the files currently selected in the results list. It also sets __selectedcontents to any text selected in the contents pane.

system Arguments are executed as a operating system command and the results, if any, are displayed. This is a syncrhonous command, which means Wilma will wait for the command to finish before continuing.

tee Directs a copy of the console output to the file whose path is given as the parameter. If no parameter is given, any copying is ended. Wilma will complain if the file already exists, but prepending the path with the '>' character will cause Wilma to overwrite the destination. Prepending two '>" characters will result in Wilma appending to an existing file.

xml This just returns an XML representation of the object, which can be useful for determining property values etc.

Actions Parent Objects Understand

Parent objects are objects which can contain other objects. In Wilma only the root object (the index) and its child referrals are parent objects.

create Create a new child with of the class type given in the first parameter and with the name given in the second parameter. For example:

/.referrals create RTLocalReferral fred

will create a new local referral named fred. You can check this by calling up the search dialog, but note that at this point the referral is incomplete as it does not have an index name. Entering:

/.referrals.fred setvalue index freds

would set the index to refer to. Of course it must be a valid index on that machine.

ls List the child objects this parent has.

rename Rename a child from the name given in the first parameter to the second parameter. Thus another way of accomplishing what was done in the example for renameto in the previous section would be:

/.referrals rename mymail mainmail

rm Delete the child named in the parameter. For example:

/.referrals rm mainmail

Actions / (the index object) Understands

addinclude Add the pattern given in the first parameter to the list of include patterns. The second parameter must contain the name of the analyzer to use for files matching the pattern. For example:

/ addinclude *.xyz generic

addroot Add the path given in the parameter to the list of root paths to be searched for files to index. For example:

/ addinclude /Users/craig/Documents

addexclude Add the pattern given in the parameter to the list of exclude patterns. For example:

/ addexclude /home/craig/Maildir/.rejected

build Save the index properties and do a full scan and index. Note that this does not spawn a separate task as happens when build is selected from the GUI toolbar or menu, but rather runs directly in the current program.

clearexcludes Removes all entries in the exclude list.

clearincludes Removes all entries in the include list.

clearroots Removes all entries in the root path list.

deleteindex Completely deletes the index named in the parameter. This cannot be undone. You cannot delete the index that is currently loaded.

find Perform a search using the parameters as the search phrase. The number of found files and occurrences will be reported.

listresults Produce a list of files found in the previous search. The parameter must be a number indicating the maximum number of results to list. Each line will contain the file name, folder path, the number of occurrences minus one, the modified date in seconds, the file size and an ID number for the file.

filecontents This will return the text contents of the file whose ID number is given as the parameter. The output for a very small file following a search for the word "hobo" might look like:
{SPLIT}}0:4	10:4	{{SPLIT}}hobo fred
hobo tommy
The n:m number pairs between the first two {{SPLIT}} tags, represent the position and length of each matched word in the contents text, which is included between the second and third {{SPLIT}} tags. The contents text is what appears in the contents pane of WilmaDesktop and will be either collapsed or expanded as per the current setting if the index outline property.

new Create and load a new index with the name as given as the parameter. Note that any unsaved changes to the current index are discarded.

open Load a the index whose name is given as the parameter. Note that any unsaved changes to the current index are discarded.

save Save any changes that have been made to the index. Note that the index is automatically saved when built or updated.

saveas Save a copy of the index using the name as given as the parameter as the copy name.

setsearchphrase Set the last search phrase. This is used internally when retrieving file contents from referred indexes.

showexcludes Lists the exclude patterns.

showincludes Lists the include patterns and associate analyzers.

showroots Lists the root paths.

wordcount Displays word count information about the current index. If used without a parameter, a list will be displayed for all the words in the index, with each line containing the word, the number of files the word occurs in and the total number of occurrences for the word. Each field will be separated by a tab (ascii 9) character.

If an argument "selected" is included as the first argument, then only words contained in files whose file ids are listed in the __selected value (see setvalue above) are listed. The __selected value is automatically set by WilmaDesktop to reflect the files currently selected in the results list.

By default the list is sorted by the word value, but if the last argument is a number, it is taken as the column to sort by.

update Save the index properties and scan for changed or new files. Note that this does not spawn a separate task as happens when build is selected from the GUI toolbar or menu, but rather runs directly in the current program.

Actions /.criteria Understands

clear Set all criteria back to the default values

Actions /.referrals Understands

clear Removes all referrals.

enableall Sets the enabled flag to true for all referrals.