next up previous contents
Next: Using Indexes Up: Getting Started with Shore Previous: The Main Program

 

Building and Running the Example Program

 

Starting the Shore Server

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.

 

Building the Application

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.

 

Running Some Examples

 

A Small Example

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

 

A Larger Example

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



next up previous contents
Next: Using Indexes Up: Getting Started with Shore Previous: The Main Program



Marvin Solomon
Fri Aug 2 13:40:31 CDT 1996