FramerD Users Guide Ken Haase |
--- | ---

Quick ref: [Installation] [Listeners] [Customizing FramerD] [Configuration Files] [An Extended Example] [Shell Commands] [Using FramerD from Emacs] [Invoking FDScript]

Installing FramerD | How you install FramerD and FDScript depends on what kind of package you have, but each one eventually runs an installation script written in FDScript, the FramerD scripting language. This script figures out and sets up configuration information regarding your installation. In most cases, it also does the file copying. Normally, it also installs the command `uninstall-framerd` to undo its actions.

The way you install FramerD depends on the kind of installation file you have:

- If you have a FramerD RPM file, simply (as root) do `rpm -Uvh rpm file` to install it; it should take care of everything.
- If you have a FramerD binary tarball (called something like framerd-2.3-linux386.tar.gz) do the following:
  1. uncompress it with `gunzip framerd-2.2....tar.gz`
  2. unpack it with `tar -xf framerd-2.2....tar.gz`
  3. go into the directory (`cd framerd`)
  4. run the installation script (which is written in FDScript) by typing
     `bin/fdscript etc/install.fdx directory`
     where directory is the directory you want to install FramerD. If you do not specify the directory, it stores into `/opt/framer-version`.
  5. if you specified a different installation directly, add a line to your Unix init file setting the variable `FRAMERD_CONFIG` to `directory/share/framerd/framerd.cfg` where directory is the argument you used with `install.fdx`. If you use `bash` modify the file `~/.bashrc` to include the line
     `export FRAMERD_CONFIG=directory`
     if you use `csh` or `tcsh`, modify the file `.cshrc` to include the line
     `setenv FRAMERD_CONFIG directory`
- If you have a FramerD source tarball (called something like framerd-2.2.tar.gz), do the following:
  1. uncompress it with `gunzip framerd-2.2.tar.gz`
  2. unpack it with `tar -xf framerd-2.2.tar`
  3. go into the directory it unpacked with `cd framerd`
  4. configure it by typing `./configure` there
  you can change where it installs itself by giving a `--prefix=directory` argument to `configure`;
  5. build it by typing `make`
  6. (optionally) test it by typing `make test` (this does a lot of stuff and creates a detailed file `test.log`)
  7. install it by typing `make install`, which you might have to do as the `root` user
- If you have the `WIN32` self-extracting `fdDDinstall.exe` (where DD is the major and minor version numbers), just run it. It will ask you some questions and you'll probably be happy with its defaults.

Interacting with Listeners | One can interact directly with FDScript through a `listener' which takes FDScript expressions and evaluates them. If you are programming in FDScript, sooner or later, you will probably want to interact with an FDScript listener.

The FDScript listener is an interactive program which is usually invoked from a system's command line or under GNU Emacs (see Using FDScript under GNU Emacs). It is usually invoked by a command like:

    sh% fdscript

and responds with some information about the executable version, followed by a prompt (typically `fdscript') in square brackets:

    [15:47:39 MIT FramerD library 2.2 (C) 1994-2000, built Mar 16 2001]
    [fdscript]

The square brackets indicate that the text or messages which they contain are not a direct part of the interaction with FDScript. In this case, the string "[fdscript]" prompts you to type an expression. The listener then displays the results of evaluating the expression, followed by another prompt:

    [fdscript] (+ 2 3)
    5
    [fdscript] (* 3+5i 8i)
    -40+24i
    [fdscript] (* (choice 1 2 3 4 5) 10)
    ;; There are 5 values
    {10 20 30 40 50}
    [fdscript] (dtcall "admin@framerd.org" session-id)
    "framerd haase@framerd.media.mit.edu /PID:6836 /OS:i586-unknown-linux /Compiled:Dec 16 1999 /Started:Wed Jan  5 11:52:09 2000"
    [fdscript]

As you interact with the listener, the variable `THAT` is bound to the result of the last expression:

    [fdscript] (/ 22 7)
    22/7
    [fdscript] (* that 5)
    110/7
    [fdscript] (exact->inexact that)
    15.714286
    [fdscript] (set! pi (/ that 5))
    [fdscript] (* pi pi)
    9.877550
    [fdscript]

When an expression non-deterministically returns multiple values, or no values, the listener reports how many values and either lists them or reports the absence of results, e.g.

    [fdscript] (elts "Foo")
    ;; 2 choices were returned
    {#\F #\o}
    [fdscript] (elts "")
    ;; No choices were returned
    [fdscript]

Some expressions, like `SET!`, `DEFINE` or `DISPLAY` are defined to not have return values. When processing one of these expressions, the listener says `Nothing (void) was returned' to indicate the the expression returned no useful value, e.g.

    [fdscript] (display foo)
    Foo
    ;; Nothing (void) was returned
    [fdscript]

The listener also tracks changes in the values of variables, so that a form like `DEFINE` will also elicit a report of change in valuye, e.g.

    [fdscript] (define (fact n) (if (= n 0) 1 (* n (fact (- n 1)))))
    ;; Nothing (void) was returned
    ;; Values changed (1): FACT
    [fdscript]

This works with all top level expressions, providing a useful way to tell (for instance) which global symbols are defined by a particular file:

    [fdscript] (load "fact")
    ;; Nothing (void) was returned
    ;; Global values changed (2): FACT FACT-ITER
    [fdscript]

## Using READLINE

When the listener's prompt starts with an asterisk (e.g. `*[fdscript]`), this indicates that the GNU readline library is being used to read input the console. This library offers simple editing commands much like those in Emacs. In addition, the FDScript listener also defines automatic completion of FDScript symbols and external filenames.

Completion means that hitting the `Tab` key automatically tries to expand whatever you are typing to a known symbol, e.g. hitting tab when you have typed:

    [fdscript] (make-file-p

automatically generates the completion:

    [fdscript] (make-file-pool

Hitting `Tab` twice lists possible completions. For example, hitting tab twice after typing the following:

    [fdscript] (make-file-

would yield:

    [fdscript] (make-file-
    MAKE-FILE-INDEX MAKE-FILE-POOL

When the cursor is inside a string, `Tab` attempts to do filename completion rather than symbol completion. E.G. hitting `Tab` when you have typed:

    [fdscript] (filestring "/usr/local/src/fram

might automatically generate the completion:

    [fdscript] (filestring "/usr/local/src/framerd

Binary releases of FramerD only use the readline library for operating systems which typically include the library. If you are using another platform, you can get and install the readline library separately and recompile FramerD yourself.

Using A Database | FramerD databases can be examined interactively through a listener. This transcript is an annotated tour of the BRICO knowledge base through an FDScript listener. You can also browse this database through the web at http://www.framerd.org/brico/.

We start by telling the system to access the objects in the BRICO knowledge base:

    [15:47:39 MIT FramerD library 2.2 (C) 1994-2000, built Mar 16 2001]
    [fdscript] (use-pool 'brico)

It outputs some identifying information and then reports the pools it has added

    [15:50:04 Session id=fdscript haase@buster.media.mit.edu /PID:2403 /OS:i686-unknown-linux /V:2.2 /Compiled:Mar 16 2001 /Started:Sun Mar 18 15:50:04 2001]
    [#POOL brico@leviathan @1/0+1048576 {}]

Once the pool is added, we can use a numeric OID (Object IDentifier) to retrieve a particular object.

    [fdscript] @1/13800
    @/brico/13800("example" "illustration" "instance" "representative")

We can describe this object by using the `D` function, which gives us a lot of output:

    [fdscript] (d @/brico/13800)
    ---------------------------------------------------------------
    The frame @/brico/13800("example" "illustration" "instance" "representative"):
        SYNSET-CODE:  (NOUN 4483764 0)
        SOURCE:  @/brico/0"WordNet 1.6 Copyright 1997 by Princeton University.  All rights reserved."
        WORD-DATA:  #(("example" . 0) ("illustration" . 2) ("instance" . 0) ("representative" . 0))
        SYNSET-ID:  4483764
        N-WORDS:  4
        LEX-FILENO:  9
        SENSE-KEYS: (4 values)
           "illustration%1:09:02::"
           "representative%1:09:00::"
           "instance%1:09:00::"
           "example%1:09:00::"
        OBJ-NAME:  ("example" "illustration" "instance" "representative")
        HYPERNYM:  @/brico/13754("information")
        HYPONYM: (6 values)
           @/brico/1bd54("precedent" "case_in_point")
           @/brico/1bd56("sample")
           @/brico/1bd57("specimen")
           @/brico/1bd52("apology")
           @/brico/1bd55("quintessence")
           @/brico/1bd53("exception")
        GLOSS:  " a single item of information that is representative of a type; \"this patient provides a typical example of the syndrome\"; \"there is a good example on page 10\"  "
        PART-OF-SPEECH:  NOUN
        WORDS: (4 values)
           "representative"
           "illustration"
           "instance"
           "example"
        ROGET-CLUSTERS: (14 values)
           @/brico/95eb("Nouns32750" "representative" "commissioner" "deputy")
           @/brico/f9c3("Nouns987" "protoplast" "module" "exemplar" "example" "ensample" "paradigm")
           @/brico/40c5("Nouns37449" "postulation" "solicitation" "invitation" "entreaty" "importunity" "supplication" "instance" "impetration" "imploration" "obsecration" "obtestation" "invocation" "interpellation")
           @/brico/1553a("Nouns24846" "illustration" "delineation" "depictment")
           @/brico/8011("Adjectives24699" "diacritical" "representative" "typical" "symbolic" "pantomimic" "pathognomonic" "symptomatic" "characteristic" "demonstrative" "diagnostic" "exponential" "emblematic" "armorial")
           @/brico/1a430("Nouns3707" "exemplification" "illustration" "case in point")
           @/brico/1955("Nouns27738" "influence" "prompting" "dictate" "instance")
           @/brico/40c4("Nouns3706" "example" "instance" "specimen" "sample" "quotation")
           @/brico/2b92("Nouns37175" "deputy" "substitute" "vice" "proxy" "locum tenens" "badli" "delegate" "representative" "next friend" "surrogate" "secondary")
           @/brico/26b9("Adjectives24914" "represent" "representing" "representative")
           @/brico/1a431("Nouns22765" "illustration" "exemplification")
           @/brico/95ec("Nouns37154" "representative" "resident" "consul" "legate" "nuncio" "internuncio" "charge d'affaires" "attache")
           @/brico/13a6d("Nouns25071" "illustration" "illumination")
           @/brico/13a6e("Nouns42133" "illustration" "illumination" "vignette")
        CYC-CONCEPTS: (3 values) ;; Some cross references into CYC
           @1/200939"SalesRepresentative"
           @1/20093b"RepresentativeDemocracy"
           @1/20093a"ArtistOrEntertainerRepresentative"
        PORTUGUESE: (3 values)
           "exemplo"
           ;; Our console is declared to be US-ASCII, so we see unicode escapes
           "ilustra\u00ff\u00ffo"
           "representante"
        TRANSLATIONS: (37 values)
           (DEUTSCH "Illustration")
           (DEUTSCH "Illustration, -en")
           (FRAN\u00c7AIS "exemple")
           (ESPA\u00d1OL "ejemplo")
           (ESPA\u00d1OL "sustituta")
           (ITALIANO "esempio")
           (ESPA\u00d1OL "suplente")
           (ENGLISH "representative")
           (ENGLISH "illustration")
           (ENGLISH "instance")
           (ENGLISH "example")
           (FRAN\u00c7AIS "preuve")
           (FRAN\u00c7AIS "repr\u00e9sentation")
           (FRAN\u00c7AIS "type")
           (FRAN\u00c7AIS "mod\u00e8le")
           (FRAN\u00c7AIS "rempla\u00e7ant")
           (ESPA\u00d1OL "representaci\u00f3n")
           (ESPA\u00d1OL "prueba")
           (ESPA\u00d1OL "figura")
           (ESPA\u00d1OL "ilustraci\u00f3n")
           (ESPA\u00d1OL "modelo")
           (ESPA\u00d1OL "delegado")
           (ESPA\u00d1OL "sustituto")
           (DEUTSCH ("Illustration," "-en"))
           (DEUTSCH "Beleg")
           (DEUTSCH "Beispiel")
           (DEUTSCH "Exempel")
           (ITALIANO "illustrazione")
           (ITALIANO "sostituta")
           (ITALIANO "domanda")
           (ITALIANO "prova")
           (NEDERLANDS "illustratie")
           (NEDERLANDS "verluchting")
           (NEDERLANDS "zaakwaarnemer")
           (DANSK "eksempel")
           (SUOMI "esimerkki")
           (TAGALOG "halimbaw\u00ff")
    @/brico/13800("example" "illustration" "instance" "representative")

We `tell' FramerD to use its index for BRICO as the background for searches and the do a search for concepts related to the word "kludge"

    [fdscript] (set! %background 'BRICO)
    ;; No value (void) was returned
    [fdscript] (?? words "kludge")
    [15:36:30 Using index brico@leviathan]
    ;; No choices were returned

Now we look for concepts that can be described by the word "cluck". We have some more luck.

    [fdscript] (?? words "cluck")
    {;; There are 5 results
     @/brico/1d674("cluck")
     @/brico/7a5("Verbs17023" "cackle" "cluck" "clack "hen" "rooster" "poultry")
     @/brico/7a5("Verbs17023" "cackle" "cluck" "clack "hen" "rooster" "poultry")
     @/brico/356a("cluck" "click" "clack")
     @/brico/356a("cluck" "click" "clack")
    }

Let's look at one of them, again using the `D` function:

    [fdscript] (d @/brico/1d674("cluck"))
    ---------------------------------------------------------------
    The frame @/brico/1d674("cluck"):
        SYNSET-CODE:  (NOUN 5495412 0)
        SOURCE:  @/brico/0"WordNet 1.6 Copyright 1997 by Princeton University.  All rights reserved."
        WORD-DATA:  #(("cluck" . 0))
        SYNSET-ID:  5495412
        N-WORDS:  1
        LEX-FILENO:  17
        SENSE-KEYS:  "cluck%1:17:00::"
        OBJ-NAME:  ("cluck")
        HYPERNYM:  @/brico/1d492("cry")
        GLOSS:  " the sound made by a hen (as in calling her chicks)  "
        PART-OF-SPEECH:  NOUN
        WORDS:  "cluck"
        ROGET-CLUSTERS:  @/brico/7a5("Verbs17023" "cackle" "cluck" "clack "hen" "rooster" "poultry")
    @/brico/1d674("cluck")

We can use the `GET` function to get its generalization (hypernym in WordNet-speak), and to get its generalizations (recursively).

    [fdscript] (get @/brico/1d674("cluck") 'hypernym)
    @/brico/1d492("cry")
    [fdscript] (get that 'hypernym)
    @/brico/13ae1("sound")
    [fdscript] (get that 'hypernym)
    @/brico/13ac3("happening" "occurrence" "natural_event")
    [fdscript] (get that 'hypernym)
    [15:37:22 Growing OID table from 517/1033]
    [15:37:22 OID table grown to 517/2083]
    @/brico/13ac0("event")

This is the top of the generalization hierarchy, but we can also go down, which we do from the node for a meaning of "cry" which we found along the way. This gives us a list of the different kinds of cries which BRICO "knows about":

    [fdscript] (get that 'hypernym)
    ;; No choices were returned
    [fdscript] (get @/brico/1d492("cry") 'hyponym)
    {;; There are 21 results
     @/brico/1d670("cackle")
     @/brico/1d676("crow")
     @/brico/1d67f("yelp" "yelping")
     @/brico/1d674("cluck")
     @/brico/1d66d("bay")
     @/brico/1d67c("moo")
     @/brico/1d677("gobble")
     @/brico/1d671("caterwaul")
     @/brico/1d66b("baa")
     @/brico/1d679("honk")
     @/brico/1d675("coo")
     @/brico/1d66e("bleat")
     @/brico/1d67d("neigh" "whinny")
     @/brico/1d678("growl" "growling")
     @/brico/1d672("caw")
     @/brico/1d67a("howl")
     @/brico/1d66f("bray")
     @/brico/1d67e("roar")
     @/brico/1d673("cheep" "peep")
     @/brico/1d66c("bark")
     @/brico/1d67b("meow" "mew" "miaou" "miaow")
    }

We can get the same list by searching (with the function `??`) for the concepts which have cry as their hypernym.

    [fdscript] (?? hypernym @/brico/1d492("cry"))
    {;; There are 21 results
     @/brico/1d674("cluck")
     @/brico/1d670("cackle")
     @/brico/1d676("crow")
     @/brico/1d67f("yelp" "yelping")
     @/brico/1d66d("bay")
     @/brico/1d67c("moo")
     @/brico/1d677("gobble")
     @/brico/1d671("caterwaul")
     @/brico/1d66b("baa")
     @/brico/1d679("honk")
     @/brico/1d675("coo")
     @/brico/1d66e("bleat")
     @/brico/1d67d("neigh" "whinny")
     @/brico/1d678("growl" "growling")
     @/brico/1d672("caw")
     @/brico/1d67a("howl")
     @/brico/1d66f("bray")
     @/brico/1d67e("roar")
     @/brico/1d673("cheep" "peep")
     @/brico/1d66c("bark")
     @/brico/1d67b("meow" "mew" "miaou" "miaow")
    }

We can use the `DIFFERENCE` primitive to compare these results automatically:

    [fdscript] (difference (get @/brico/1d492("cry") 'hyponym)
                           (?? hypernym @/brico/1d492("cry")))
    ;; No choices were returned

Finally, we exit with `(exit)` and the system tells us what it's been doing...

    [fdscript] (exit)
    ;; 2 pools, 1 indices, 1 net connections
    ;; 591/53 OIDs refd/loaded, 0 new OIDs, 53 OID loads, 1057 symbols
    ;; 4858 conses in use, 4858*20+166490=263650 bytes total

Customizing FramerD | The working environment for FramerD applications can be customized by specifying initial global variable bindings. These intial bindings come from three sources: the configuration file associated with the current installation, an individual user profile associated with a particular user, and the command line with which the program was invoked.

When an interactive FramerD application (like a listener) starts up, it tries to read two initialization files:

1. the configuration file associated with the FramerD installation
2. a user profile associated with the current user

Additional configuration files can be included by either calling the FDScript function `LOAD-CONFIG` or by passing a `--config=file` argument to the FramerD executables (e.g. `fdscript`, `fdserver`, `fdcgi`).

The location of the default configuration file is normally established when FramerD is installed: the FDScript function `(get-config-file)` will return this location if you are interested. The location of the user profile is typically a file named `.fdprofile` in the user's home directory. (You can override these defaults with the shell environment variables `FRAMERD_CONFIG` and `FRAMERD_PROFILE`).

When a series of configuration files are loaded, they can either set variables or add to variables. When a configuration file sets a variable, all values set by previous configuration files (or the user) are lost; when a configuration file adds to a variable, existing and added values coexist.

In addition, the `fdscript` and `fdserver` executables and any scripts which invoke `fdscript` process command line arguments of the form "`VAR=val`" as defining configuration variables. For example, the following turns on debugging (emitting full backtraces for errors) while loading the file `foo.fdx`:

    fdscript %DEBUG=#t foo.fdx

Command line entries of the form "`VAR+=val`" adds an item to the current value of the configuration variable. Suppose that the script `find-dated` were an fdscript script which took a date argument and searched by default in the indices stored in `%BACKGROUND`. The background used for the search could be extended by something like this:

    find-dated %BACKGROUND+=~/oldmail.index "June 1993"

## Dealing with Configuration Files

The command `fdconfig` is used to examine or change the current FramerD configuration. It provides several sub-commands:

fdconfig locate | identifies the file where the configuration is stored
fdconfig list | lists the variable bindings defined by the configuration
fdconfig get var | lists the bindings defined for var in the configuration
fdconfig reset var | removes any bindings defined for var in the configuration
fdconfig set var value | changes the binding of var to value in the configuration
fdconfig add var value | adds a binding of var to value in the configuration; this will combine with any bindings defined before the configuration is loaded
fdconfig use-pool pool | creates a `pooltab' entry for pool in the configuration
fdconfig use-server fcn server | defines the symbol fcn in the current configuration to execute on the remote server server

The shell command `fdprofile` is just like `fdconfig` but modifies the current user's profile rather than the system configuration. And the general command `fdcfg` takes a config file as its first argument and treats the remaining arguments just as `fdconfig` does.

From FDScript, you can use the functions `config-add!`, `config-reset!` and `config-set!` to manipluate the values in configuration files.

## Anatomy of a Configuration File

Configuration files and user profiles are designed to be readable and writable by both humans and machines, though the commands `fdconfig` and `fdprofile` are the preferred way for users and maintainers to change these files. However, you can also read and edit the files by hand.

Each file consists of a sequence of initializations of either the form:

    (symbol value)

(which causes the symbol symbol in the startup environment to be bound to the value value) or

    (symbol value +)

where the second form indicates that value should be added to whatever the current value of symbol may be.

The expression value is read as a Lisp value, but is not evaluated (since not all FramerD applications include an evaluator). For instance, here is a sample configuration file:

    (INSTALL_ROOT "/usr/local")
    (INSTALLATION "1999-06-27T15:26:49-4:00")
    (FRAMERD_DATA "/usr/local/share/framerd/data")
    (FRAMERD_LIB "/usr/local/share/framerd")
    (SUPER_POOL "/usr/local/share/framerd/public/super-pool")
    (BRICO "brico@framerd.org")

which sets up initial variables based on the installation and adds some customizations to identify the sources for particular named resources (the BRICO server).

## FramerD configuration variables

%ENCODING | default text encoding
FRAMERD_PROFILE | where the user profile is loaded from for interactive listeners
HERALD | message string emitted with the FramerD library is initialized
PPWIDTH | how many columns to aim for pretty printing objects
FD_DIE_CONVENTIONALLY | don't signal errors on bad signals
ENCODINGS_PATH | where to find character encoding mapping files
MAILHOST | SMTP mail server
MAILDOMAIN | mail domain
FRAMERD_EMAIL | default from field for generated email
FRAMERD_REPLY_TO | default replyto field for generated email
FDMYPATH | search path for file loading
FDPATH | search path for file loading
FD_LISTENER_INIT | initialization file
FD_LISTENER_LIBS | library modules to load into listener
SUPER_POOL | where pools are taken from
ALWAYS_BUSY | whether prompt always includes resource information
%POOLTAB | lookup table for OIDs
OID_LOCATOR | lookup server for OIDs
%BACKGROUND | default indices for frame searching

Using FramerD From the Shell | One can use FramerD commands from the Unix or DOS shell.

One convenient way to access FramerD is to invoke commands directly from your computer's command line, typically either the Unix shell or the Windows DOS prompt. FramerD comes with a variety of scripts designed to help with this. In addition, it is very simple (if you know a little Scheme or LISP) to define your own shell commands. And the FramerD program `dtcall` allows you to access remote servers from the command line.

Both FramerD scripts and DTCALL interpret command line arguments of dash (-) and dollar sign ($) specially. A "-" argument is converted into a set of lisp objects read from the standard input; a "$" argument is converted into a single string whose content consists of the entire standard input. This allows the output from commands can be piped together to do more complex processing.

In addition, FramerD scripts process and ignore configuration expressions such as `variable=value` from the command line.

The following shell transcript describes one session of interaction with FramerD through the shell; we start by adding the BRICO pool to the variable `%pools`, which is used by the default scripts:

    [haase@localhost /tmp]$ fdprofile add %pools brico

we then look for frames whose `words` slot contains the string `"example"`

    [haase@localhost /tmp]$ fdfind words "example"
    ;;; There are 8 matches
      @1/f9c3("Nouns987" "protoplast" "module" "exemplar" "example" "ensample" "paradigm")
      @1/40c4("Nouns3706" "example" "instance" "specimen" "sample" "quotation")
      @1/13800(NOUN.COGNITION "example" "instance" "illustration" "representative")
      @1/13ad9(NOUN.EVENT "case" "example" "instance")
      @1/1525d(NOUN.ACT "example" "exercise")
      @1/1bbe8(NOUN.COGNITION "model" "example")
      @1/1bdff(NOUN.COGNITION "exemplar" "model" "example" ("good" "example"))
      @1/1cb47(NOUN.COMMUNICATION ("object" "lesson") ("deterrent" "example") "example" "lesson")

and we can now look at one particular frame:

    [haase@localhost /tmp]$ fdd @1/13800
    The frame @1/13800(NOUN.COGNITION "example" "instance" "illustration" "representative"):
        SYNSET-CODE:  (NOUN 4483764 0)
        SOURCE:  @1/0"WordNet 1.6 Copyright 1997 by Princeton University.  All rights reserved."
        WORD-DATA:  #(("example" . 0) ("illustration" . 2) ("instance" . 0) ("representative" . 0))
        SYNSET-ID:  4483764
        N-WORDS:  4
        SENSE-KEYS: (8 values)
           "illustration%1:09:02::"
           "representative%1:09:00::"
           "instance%1:09:00::"
           "example%1:09:00::"
           ("example%1:09:00::" 1 45)
           ("illustration%1:09:02::" 3 1)
           ("instance%1:09:00::" 2 4)
           ("representative%1:09:00::" 4 0)
        HYPERNYM:  @1/13754(NOUN.COGNITION "information")
        HYPONYM: (6 values)
           @1/1bd54(NOUN.COGNITION "precedent" ("case" "in" "point"))
           @1/1bd56(NOUN.COGNITION "sample")
           @1/1bd57(NOUN.COGNITION "specimen")
           @1/1bd52(NOUN.COGNITION "apology")
           @1/1bd55(NOUN.COGNITION "quintessence")
           @1/1bd53(NOUN.COGNITION "exception")
        GLOSS:  " a single item of information that is representative of a type; \"this patient provides a typical example of the syndrome\"; \"there is a good example on page 10\"  "
        PART-OF-SPEECH:  NOUN
        WORDS: (4 values)
           "representative"
           "illustration"
           "instance"
           "example"
        ROGET-CLUSTERS: (14 values)
           @1/95eb("Nouns32750" "representative" "commissioner" "deputy")
           @1/f9c3("Nouns987" "protoplast" "module" "exemplar" "example" "ensample" "paradigm")
           @1/40c5("Nouns37449" "postulation" "solicitation" "invitation" "entreaty" "importunity" "supplication" "instance" "impetration" "imploration" "obsecration" "obtestation" "invocation" "interpellation")
           @1/1553a("Nouns24846" "illustration" "delineation" "depictment")
           @1/8011("Adjectives24699" "diacritical" "representative" "typical" "symbolic" "pantomimic" "pathognomonic" "symptomatic" "characteristic" "demonstrative" "diagnostic" "exponential" "emblematic" "armorial")
           @1/1a430("Nouns3707" "exemplification" "illustration" "case in point")
           @1/1955("Nouns27738" "influence" "prompting" "dictate" "instance")
           @1/40c4("Nouns3706" "example" "instance" "specimen" "sample" "quotation")
           @1/2b92("Nouns37175" "deputy" "substitute" "vice" "proxy" "locum tenens" "badli" "delegate" "representative" "next friend" "surrogate" "secondary")
           @1/26b9("Adjectives24914" "represent" "representing" "representative")
           @1/1a431("Nouns22765" "illustration" "exemplification")
           @1/95ec("Nouns37154" "representative" "resident" "consul" "legate" "nuncio" "internuncio" "charge d'affaires" "attache")
           @1/13a6d("Nouns25071" "illustration" "illumination")
           @1/13a6e("Nouns42133" "illustration" "illumination" "vignette")
        CYC-CONCEPTS: (3 values)
           @1/200939"SalesRepresentative"
           @1/20093b"RepresentativeDemocracy"
           @1/20093a"ArtistOrEntertainerRepresentative"
        PORTUGUESE: (3 values)
           "exemplo"
           "ilustra\u00ff\u00ffo"
           "representante"
        TRANSLATIONS: (37 values)
           (DEUTSCH "Illustration")
           (DEUTSCH "Illustration, -en")
           (FRAN\u00c7AIS "exemple")
           (ESPA\u00d1OL "ejemplo")
           (ESPA\u00d1OL "sustituta")
           (ITALIANO "esempio")
           (ESPA\u00d1OL "suplente")
           (ENGLISH "representative")
           (ENGLISH "illustration")
           (ENGLISH "instance")
           (ENGLISH "example")
           (FRAN\u00c7AIS "preuve")
           (FRAN\u00c7AIS "repr\u00e9sentation")
           (FRAN\u00c7AIS "type")
           (FRAN\u00c7AIS "mod\u00e8le")
           (FRAN\u00c7AIS "rempla\u00e7ant")
           (ESPA\u00d1OL "representaci\u00f3n")
           (ESPA\u00d1OL "prueba")
           (ESPA\u00d1OL "figura")
           (ESPA\u00d1OL "ilustraci\u00f3n")
           (ESPA\u00d1OL "modelo")
           (ESPA\u00d1OL "delegado")
           (ESPA\u00d1OL "sustituto")
           (DEUTSCH ("Illustration," "-en"))
           (DEUTSCH "Beleg")
           (DEUTSCH "Beispiel")
           (DEUTSCH "Exempel")
           (ITALIANO "illustrazione")
           (ITALIANO "sostituta")
           (ITALIANO "domanda")
           (ITALIANO "prova")
           (NEDERLANDS "illustratie")
           (NEDERLANDS "verluchting")
           (NEDERLANDS "zaakwaarnemer")
           (DANSK "eksempel")
           (SUOMI "esimerkki")
           (TAGALOG "halimbaw\u00ff")
        LEX-FILENO:  9
        SENSE-CATEGORY:  NOUN.COGNITION
        OBJ-NAME:  (NOUN.COGNITION "example" "instance" "illustration" "representative")

though we might prefer to get a particular slot:

    [haase@localhost /tmp]$ fdget @1/13800 hypernym
    ;; There are 1 results
      @1/13754(NOUN.COGNITION "information")

and we can pipe one command into another by using the special `-' argument to indicate the inputs on the standard input:

    [haase@localhost /tmp]$ fdget @1/13800 hypernym | fdget - hypernym
    ;; There are 1 results
      @1/6436(NOUN.TOPS "cognition" "knowledge")
    [haase@localhost /tmp]$ fdget @1/13800 hypernym | fdget - hypernym | fdget - hypernym
    ;; There are 1 results
      @1/13747(NOUN.TOPS ("psychological" "feature"))
    [haase@localhost /tmp]$ fdget @1/13800 hypernym | fdget - hypernym | fdget - hypernym |  fdget - hyponym
    ;; There are 3 results
      @1/aac1(NOUN.TOPS "feeling")
      @1/e732(NOUN.TOPS "motive" "motivation" "need")
      @1/6436(NOUN.TOPS "cognition" "knowledge")

the `dtcall` program takes a server specification (service@hostname), an operation, and a set of arguments. The operation is just a symbol whose value will be applied on the remote server. We could use this to invoke the `get-similar` function on `framerd.org`'s brico server:

    [haase@localhost haase]$ fdget @1/13800 hypernym | dtcall brico@localhost get-similar brico -
    @1/13c49
    @1/1c948
    @1/13d75
    @1/cf6a

which has the advantage of not using local memory and taking advantage of the big caches which we will assume are on `brico@framerd.org`. (If this takes a while, it may be that `brico@framerd.org` is overloaded.) However, the OIDs listed as results are not given with names, since `dtcall` doesn't use the `%pools` variable to find the actual objects and their names. However, we can pipe the result to the fd_id script, which just prints its outputs, but it does use `%pools` and so can get the OID's names:

    [haase@localhost haase]$ fdget @1/13800 hypernym | dtcall brico@localhost get-similar brico - | fd_id -
    ;; There are 4 results
      @1/13c49(NOUN.GROUP "data" "information")
      @1/1c948(NOUN.COMMUNICATION "information")
      @1/13d75(NOUN.COMMUNICATION "information" "info")
      @1/cf6a(NOUN.ATTRIBUTE "entropy" "information" ("selective" "information"))

The command line argument "$" takes the entire standard input as a string. Using this, one can (for instance) say

    sh% cat index.html | dtcall demo@framerd.org length $
    11394

to get the length of the text in a file. A more interesting application might be something like:

    sh% cat index.html | dtcall demo@framerd.org refpoints $
    "MIT Media Laboratory"
    "Java"
    "ANSI C"
    "FramerD Root"
    "Scheme"
    "GNU GPL"
    "Machine Understanding Group"
    "Media Laboratory"
    "FramerD"
    "Technology Licensing Office"
    "Unix"

Appendix: Using FramerD from Emacs | It is sometimes useful, for an extended interaction with FDScript, to use it under Emacs. This appendix examples how this works.

FramerD's current development environment is a set of rudimentary but effective tools implemented in GNU Emacs. These are built on top of Emacs' native facilities for dealing with lisp-like languages and for interacting with external processes. They work by maintaining an external `fdscript` interpreter and sending expressions from Emacs to the interpreter.

The interface is implemented by the fdscript.el which tries to be installed in whatever the first directory on your site's "elisp load path". Providing this has been executed successfully, you can arrange for automatically loading this file by adding the following lines to your `.emacs` initialization file:

    (autoload 'fdscript "fdscript" t
      "Starts an FDScript interpreter process")
    (autoload 'fdscript-mode "fdscript" t
      "Sets up a buffer for editing FDScript files.")
    (setq auto-mode-alist
          (append '(("\\.fdx" . fdscript-mode)
    		("\\.fdz" . fdscript-mode)
    		("\\.fdcgi" . fdscript-mode))
    	      auto-mode-alist))

The command `M-x fdscript` starts an external fdscript process and shifts to a buffer interacting with FDScript. In this buffer, you can type expressions much as you would in an FDScript listener. The command `M-x start-fdscript` starts the external process and creates the interaction buffer but does not actually switch to the buffer.

Within the interaction buffer, expressions are sent to fdscript by typing Return within or after a complete expression at the end of the buffer. Typing return elsewhere in the buffer takes a copy of the nearest expression and inserts it at the end of the buffer to be edited.

The commands `Meta-P` and `Meta-N` go forward and backwards in the history of past commands. The command `Meta-S` selects a particular past command (with completion) while the command `Meta-T` gets past commands which contain a particular substring.

A buffer can be changed to fdscript-mode with the command `M-x fdscript-mode`. If your emacs is set up as above, new or existing `.fdx`, `.fdz`, or `.fdcgi` files are automatically in fdscript-mode. This mode implements some special commands for working with fdscript source code.

Typing `Meta-Enter` sends the nearest complete expression to the FDScript process. This is a good way to send definitions to FDScript. The command `C-c C-z` sends the entire current buffer to FDScript. The command `C-c C-l` asks the FDScript process to load a specific file (which defaults to the file the current buffer is visiting).

There are also special commands for examining frames listed in FDScript's output. The command `C-x .` gets the frame/OID reference around the text cursor and sends a "description command" to the FDScript process. This is normally an expression of the form `(XF oid)` which causes a description of oid to be emitted.

Appendix: Invoking FDScript | FDScript also takes some useful command line arguments, which can be used to override user or site configuration setups

The `fdscript` executable takes a number of command line switches which it may be useful to know:

--noherald | supresses the printing of the copyright/warranty herald
--noconfig --nodefaultconfig | supresses loading of the system configuration file
--noprofile | supresses loading of the user's profile
--charset=enc | sets the default charset for program, e.g. latin-1, iso-8859/1, JIS, BIG5, UTF-8, etc
--config=filename -C filename | loads an extra configuration file, searching the current directory, `FDMYPATH`, and `FDPATH`
-ffilename | loads the Scheme (FDScript) file filename
-mmodule | loads the module module and causes the default environment (for subsequent loads or interaction) to `use` that module.
variable=value | Sets variable to value (which is parsed by the lisp parser) in the global environment. This can be used to override or augment configuration variables.
variable=+value | Adds value (which is parsed by the lisp parser) to the value of variable to in the global environment. This can be used to override or augment configuration variables.

The first non-option argument to `fdscript` indicates where it should get its input. If it is a filename, the file is opened and loaded; if it is a single dash `-', the program uses the standard input and declines to print prompts; if it is a single period '.', the program starts up interactively (just as it would with no argument). Finally if there is no such argument, the program enters an interactive listener.

The remaining arguments on the command line are passed to the program. The variable `nargs` contains the number of arguments (including the file being used as input), the variable `args` is bound to this list of arguments, and the variables `arg1`, `arg2`, and `arg3` are bound to the first, second, and third elements of this list.