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 Shore documentation release contains the source code for the examples in this tutorial. Assuming you have fetched and unpacked the documentation release as described in the Shore Software Installation Manual , you will have a directory $SHROOT/examples, where $SHROOT is the root directory of the documentation relase.
mkdir stree cp -R $SHROOT/examples/stree/* stree cd stree make stree
You should see something like this.
rm -f stree.h /usr/local/shore/bin/sdl -f -s stree.sdl -B -L -o stree.h g++ -g -I/usr/local/shore/include -c main.C g++ -g -I/usr/local/shore/include -c tree.C g++ -g -I/usr/local/shore/include -c word.C g++ -g -I/usr/local/shore/include -c cite.C g++ -g -I/usr/local/shore/include -c document.C g++ -g -I/usr/local/shore/include -c stree_defs.C g++ -g -I/usr/local/shore/include -o stree main.o stree_defs.o tree.o word.o cite.o document.o /usr/local/shore/lib/libshore.a -lnsl
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 -L option asks SDL to link all the modules together (in this case, there is only one module), the -B option tells it 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++) listed in the Requirements section of the Shore Release 1.1.1 manual.
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 committedNext, 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 **** 14 citations % stree -lV eight ========== eight **** Not foundUse 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 **** 7 citations % 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 **** 7 citationsUse 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 sevenRemove 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 sonnet018Note 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 drwxr-xr-x 1 solomon solomon 12 Aug 6 16:33 stree/ prwxr-xr-x 1 solomon solomon 0 Aug 6 15:50 testpool| drwxr-xr-x 1 solomon solomon 12 Aug 6 16:23 types/ % ls -l /shoremnt/stree total 6 prw-r--r-- 1 solomon solomon 0 Aug 6 16:33 pool| -rw-r--r-- 1 solomon solomon 0 Aug 6 16:33 repository -rw-r--r-- 1 solomon solomon 650 Aug 6 16:33 sonnet010 -rw-r--r-- 1 solomon solomon 709 Aug 6 16:33 sonnet011 -rw-r--r-- 1 solomon solomon 657 Aug 6 16:33 sonnet012 -rw-r--r-- 1 solomon solomon 637 Aug 6 16:33 sonnet013 -rw-r--r-- 1 solomon solomon 623 Aug 6 16:33 sonnet014 -rw-r--r-- 1 solomon solomon 647 Aug 6 16:33 sonnet015 -rw-r--r-- 1 solomon solomon 630 Aug 6 16:33 sonnet016 -rw-r--r-- 1 solomon solomon 677 Aug 6 16:33 sonnet017 -rw-r--r-- 1 solomon solomon 656 Aug 6 16:33 sonnet018 -rw-r--r-- 1 solomon solomon 662 Aug 6 16:33 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 totalThis 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 -cor you can simply remove the repository through the Unix compatibility interface
% rm -rf /shoremnt/stree