To build the example program, you must have a copy of the Shore server running. The document Shore Software Installation Manual, particularly the section Testing Your Installation, gives simple instructions on how to start a server. You probably want to do this in a separate window. The server will accept interactive commands from the keyboard. The only one you will need for this demonstration is "bye", which causes the server to shut down cleanly and exit. The server may also occasionally produce debugging output.
The file Makefile.template is a sample Makefile for building the example program. Copy it to Makefile and edit it to set INSTALL_DIR to the root of the Shore installation directory ($SHROOT). Then type "make stree". You should see something like this.
rm -f stree.h
/usr/local/shore/bin/sdl_all -s stree.sdl -b stree -o stree.h
g++ -g -Wall -I/usr/local/shore/include -c main.C
g++ -g -Wall -I/usr/local/shore/include -c tree.C
g++ -g -Wall -I/usr/local/shore/include -c word.C
g++ -g -Wall -I/usr/local/shore/include -c cite.C
g++ -g -Wall -I/usr/local/shore/include -c document.C
g++ -g -Wall -I/usr/local/shore/include -c stree_defs.C
g++ -g main.o stree_defs.o tree.o word.o cite.o document.o
/usr/local/shore/lib/libshore.a -o stree
The second line invokes the SDL compiler. The command-line options ask it to perform several functions. The option -s stree.sdl asks it to parse the specification and install the resulting compiled versions of the module stree in the Shore database (you must have a Shore server running when you do this). The module is a registered object named /type/stree. Other options can be used to put it elsewhere in the Shore database. See the sdl(sdl) manual page for more details. The -b stree option asks SDL to generate a C++ language binding from the module just generated, and the -o stree.h option directs it to place the results into the file file stree.h in the current directory. This file is included by all of our source files. We then compile all of the source files and link them together, along with the Shore runtime support library. Any C++ compiler should be usable, but the current release is only tested to work with the GNU compiler (g++) version 2.6.3.
We have already explained the source files main.C, tree.C, word.C, cite.C, and document.C. The first of these is the main program, while the rest define the member functions for each of the classes corresponding to interfaces defined in stree.sdl. The file stree_defs.C is a small file containing just two lines:
#define MODULE_CODE
#include "stree.h"
The generated file stree.h contains some function definitions and initializations of global variables. Compiling it with MODULE_CODE defined generates these functions and initializations for linking with the rest of the program.
First use stree to add the files test1, test2, and test3 to the repository.
% stree -aV test?The output should look like this
Indexing file test1
Indexing file test2
Indexing file test3
about to commit
committed
Next, use the -lV (list verbose) option to look up some words.
% stree -lV six
========== six
test2: two six
test2: three six
test2: six two
test2: six three
test2: six six
test2: six seven
test2: seven six
test3: four six
test3: five six
test3: six four
test3: six five
test3: six six
test3: six seven
test3: seven six
% stree -lV eight
========== eight
**** Not found
Use the -d option to remove some of the documents.
% stree -d test2
% stree -lV six
========== six
test3: four six
test3: five six
test3: six four
test3: six five
test3: six six
test3: six seven
test3: seven six
% stree -d test1
% stree -lV seven
========== seven
test3: four seven
test3: five seven
test3: six seven
test3: seven four
test3: seven five
test3: seven six
test3: seven seven
Use the -p option to see what anonymous objects remain in the pool.
% stree -p
Word 'one' occurs on 0 lines
Word 'three' occurs on 0 lines
Word 'five' occurs on 7 lines
Word 'seven' occurs on 7 lines
Word 'two' occurs on 0 lines
Word 'six' occurs on 7 lines
Cite, offset 0 in file test3 cites four
Word 'four' occurs on 7 lines
Cite, offset 10 in file test3 cites four five
Cite, offset 20 in file test3 cites four six
Cite, offset 29 in file test3 cites four seven
Cite, offset 40 in file test3 cites five four
Cite, offset 50 in file test3 cites five
Cite, offset 60 in file test3 cites five six
Cite, offset 69 in file test3 cites five seven
Cite, offset 80 in file test3 cites six four
Cite, offset 89 in file test3 cites six five
Cite, offset 98 in file test3 cites six
Cite, offset 106 in file test3 cites six seven
Cite, offset 116 in file test3 cites seven four
Cite, offset 127 in file test3 cites seven five
Cite, offset 138 in file test3 cites seven six
Cite, offset 148 in file test3 cites seven
Remove the remaining document from the repository and verify that the pool
contains only Word objects.
% stree -d test3
% stree -p
Word 'one' occurs on 0 lines
Word 'three' occurs on 0 lines
Word 'five' occurs on 0 lines
Word 'seven' occurs on 0 lines
Word 'two' occurs on 0 lines
Word 'six' occurs on 0 lines
Word 'four' occurs on 0 lines
The stree directory has a sub-directory called sonnets which contains all 154 of Shakespeare's sonnets, one per file. For this test, add sonnets 10 through 19 to the repository.
% stree -aV sonnets/sonnet01?
Indexing file sonnets/sonnet010
Indexing file sonnets/sonnet011
Indexing file sonnets/sonnet012
Indexing file sonnets/sonnet013
Indexing file sonnets/sonnet014
Indexing file sonnets/sonnet015
Indexing file sonnets/sonnet016
Indexing file sonnets/sonnet017
Indexing file sonnets/sonnet018
Indexing file sonnets/sonnet019
about to commit
committed
% stree -lV summers
========== summers
sonnet012: And summer's green all girded up in sheaves
sonnet018: Shall I compare thee to a summer's day?
sonnet018: And summer's lease hath all too short a date:
% stree -l summers
sonnet012
sonnet018
sonnet018
Note that sonnet 18 is listed twice, since "summers" appears
on two different lines in that sonnet.
To illustrate access to the Shore database from existing Unix utilities, mount the Shore database as a Unix file system, as explained in the Shore Software Installation Manual, in the section NFS-Mounting the Shore File System. If you follow the instructions there, you will have the Shore database mounted as /shoremnt.
% ls -l /shoremnt
total 2
drwxrwxr-x 1 solomon 68 Oct 28 06:39 sample
drwxr-xr-x 1 solomon 376 Oct 28 06:45 stree
drwxr-xr-x 1 solomon 128 Oct 28 06:44 types
% ls -l /shoremnt/stree
total 6
prw-r--r-- 1 solomon 0 Oct 28 06:47 pool
-rw-r--r-- 1 solomon 0 Oct 28 06:47 repository
-rw-r--r-- 1 solomon 650 Oct 28 06:47 sonnet010
-rw-r--r-- 1 solomon 709 Oct 28 06:47 sonnet011
-rw-r--r-- 1 solomon 657 Oct 28 06:47 sonnet012
-rw-r--r-- 1 solomon 637 Oct 28 06:47 sonnet013
-rw-r--r-- 1 solomon 623 Oct 28 06:47 sonnet014
-rw-r--r-- 1 solomon 647 Oct 28 06:47 sonnet015
-rw-r--r-- 1 solomon 630 Oct 28 06:47 sonnet016
-rw-r--r-- 1 solomon 677 Oct 28 06:47 sonnet017
-rw-r--r-- 1 solomon 656 Oct 28 06:47 sonnet018
-rw-r--r-- 1 solomon 662 Oct 28 06:47 sonnet019
Note that there are 12 registered objects in the directory stree: 10 sonnets (objects of class Document), the object repository (of class SearchTree), and the pool object. The pool and repository show up under Unix as having zero size, since neither has a text member, but each of the sonnets shows up as a file whose contents are the same as its text member body.
% cat /shoremnt/stree/sonnet018
Shall I compare thee to a summer's day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer's lease hath all too short a date:
Sometime too hot the eye of heaven shines,
And often is his gold complexion dimmed,
And every fair from fair sometime declines,
By chance, or nature's changing course untrimmed:
But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow'st,
Nor shall death brag thou wand'rest in his shade,
When in eternal lines to time thou grow'st,
So long as men can breathe or eyes can see,
So long lives this, and this gives life to thee.
The shell script swc illustrates how Shore applications can be combined with "legacy" Unix programs.
% swc summers
14 118 657 sonnet012
14 114 656 sonnet018
28 232 1313 total
This script uses the output of stree -l (piped through sort -u
to remove duplicates) as the list of arguments to a standard Unix utility
(in this case wc) which accesses the objects as if they were
ordinary Unix files.
Note that there is no need to use a special version of wc or even
to re-link wc with a special library.
A slightly more sophisticated example is afforded by sedit, which invokes an editor on the set of sonnets containing a given word. If your editor (as indicated by the EDITOR environment variable) is emacs, you will see this:
% sedit summers
MR Buffer Size Mode File
-- ------ ---- ---- ----
. sonnet018 656 Text /shoremnt/stree/sonnet018
sonnet012 657 Text /shoremnt/stree/sonnet012
*scratch* 0 Lisp Interaction
* *Buffer List* 274 Text
--%%-Emacs: *Buffer List* 6:54am 0.23 (Buffer Menu)--All--------------------
Shall I compare thee to a summer's day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer's lease hath all too short a date:
Sometime too hot the eye of heaven shines,
And often is his gold complexion dimmed,
And every fair from fair sometime declines,
By chance, or nature's changing course untrimmed:
But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow'st,
Nor shall death brag thou wand'rest in his shade,
-----Emacs: sonnet018 6:54am 0.23 (Text Fill)--Top-----------------------
Commands: d, s, x, u; f, o, 1, 2, m, v; ~, %; q to quit; ? for help.
To clean up after this test, you can remove all the documents from the repository and then remove the repository itself with the -c option
% stree -d sonnet010 sonnet011 sonnet012 sonnet013 sonnet014
% stree -d sonnet015 sonnet016 sonnet017 sonnet018 sonnet019
% stree -c
or you can simply remove the repository through the Unix compatibility
interface
% rm -rf /shoremnt/stree