\documentclass[11pt]{article}

\usepackage{epsf,epsfig,subfigure,latexsym,latexsym,amssymb,alltt}
\usepackage{xspace,graphicx,makeidx}
\usepackage{hyperref}

\pagestyle{headings}
\bibliographystyle{plain}

%%\setlength{\topmargin}{-0.25in}
\setlength{\headheight}{10pt}
\setlength{\headsep}{30pt}
\setlength{\oddsidemargin}{0.0in}
\setlength{\evensidemargin}{0.0in}
\setlength{\textheight}{8.5in}
\setlength{\textwidth}{6.5in}
\setlength{\footskip}{50pt}


\setlength{\parskip}{2mm}               % space between paragraphs

\def\cut{\mbox{\tt '!'/0}}

\newtheorem{example}{Example}[section]

\newenvironment{Prog}{\begin{tt}\begin{tabular}[c]{l}}{\end{tabular}\end{tt}}

\newcommand{\comment}[1]{}

\newcommand{\demo}[1]{\hspace*{1.5cm}{\tt #1}}
\newcommand{\desc}[1]{\item[{\tt #1}]\hspace*{1mm}\newline}
\newcommand{\desce}[1]{\item[{\tt #1}]}
\newcommand{\ourrepeatitem}[1]{\item[{\mbox{\tt #1}}]\ \\ \vspace*{-.35in}}
\newcommand{\ouritem}[1]{\item[{\mbox{\tt #1}}]\ \\}
\newcommand{\ournewitem}[2]{\item[{\mbox{\tt #1}}]\hspace*{\fill}{\mbox{\tt #2}}\ \\}

\newcommand{\stuff}[1]{
        \begin{minipage}{4in}
        {\tt \samepage
        \begin{tabbing}
        \hspace{8mm} \= \hspace{6mm} \= \hspace{10mm} \= \hspace{55mm} \= \kill
        #1 \hfill
        \end{tabbing}
        }
        \end{minipage}
}

\newcommand{\longline}{\noindent\rule{\textwidth}{.01in}}


\newenvironment{qrules}{\begin{quote}\tt\begin{tabular}[t]{l}}%
{\end{tabular}\end{quote}}


\newcommand{\obj}{\textit{obj}\xspace}
\newcommand{\thismodule}{{\tt \_@}\xspace}
\newcommand{\db}[1]{\ensuremath{\mathcal{#1}}}

\newcommand{\xany}{\textsf{any}}

\newcommand{\xplus}{\ensuremath{^+}}
\newcommand{\xstar}{\ensuremath{^*}}
\newcommand{\xinv}{\ensuremath{^{-1}}}
\newcommand{\xopt}{\ensuremath{^{?}}}

\newcommand{\xto}[1]{\ensuremath{^{#1}}}
\newcommand{\xcond}[1]{\ensuremath{\textsf{if}(#1)}}
\newcommand{\xif}[1]{\ensuremath{\textsf{if}(#1)}}
\newcommand{\xmu}[1]{\ensuremath{\tcmu(#1)}}
\newcommand{\xmuif}[2]{\ensuremath{\tcmu(#1,#2)}}


\newcommand{\xconc}{\ensuremath{{\cdot}}}
\newcommand{\xor}{\ensuremath{|}}

\newcommand{\nnot}{\mbox{$\neg$}}                           % negation
\newcommand{\query}{\mbox{$\, ?\! - \, $}}                  % query
\newcommand{\impl}                                          % implication
  {\mbox{\Large $\; {\bf \leftarrow} \;$}}  
\newcommand{\isa}{\,{\bf{:}}\,}
\newcommand{\subcl}{\,{\bf{::}}\,}
\newcommand{\eq}{\ensuremath{\doteq}}                           % equation

% f-logic arrows

\newcommand{\fd}{\ensuremath{{\rightarrow}}}                   % scalar
\newcommand{\bfd}{\ensuremath{{\bullet\!\!\!\fd}}}            % " + inheritable
\newcommand{\mvd}{\ensuremath{{\rightarrow\!\!\!\!\rightarrow}}}  % multivalued
\newcommand{\bmvd}{\ensuremath{{\bullet\!\!\!\mvd}}}              % " + inheritable
\newcommand{\Fd}{\ensuremath{{\Rightarrow}}}                      % scalar signature
\newcommand{\Mvd}{\ensuremath{{\Rightarrow\!\!\!\!\Rightarrow}}}  % multiv signature



% curved f-logic arrows

\newcommand{\anyd}{\ensuremath{\leadsto}}                       % noninheritable
\newcommand{\bleadsto}{\ensuremath{\bullet\!\!\!\leadsto}}     % inheritable
\newcommand{\banyd}{\bleadsto}                              % "
\newcommand{\Leadsto}{\ensuremath{\approx}\!\!{>}}            % signature
\newcommand{\Anyd}{\Leadsto}                                % "

\newcommand{\FdConstr}{\ensuremath{\stackrel{constr}{\Fd}}}
\newcommand{\MvdConstr}{\ensuremath{\stackrel{constr}{\Mvd}}}

\newlength{\flogicindent}


\newlength{\flength}
\newlength{\counterlength}


\newcommand{\la}{\ensuremath{\,\leftarrow\,}}

\newcommand{\anon}{\_}

\newcommand{\note}[1]{\textit{[[#1]]}}
\newcommand{\nterm}[1]{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}



\newcommand{\bs}{\ensuremath{\backslash}}
\newcommand{\FLIP}{{\mbox{\sc Flip}}\xspace}
\newcommand{\FLORA}{{\mbox{\sc ${\cal F}${lora}\rm\emph{-2}}}\xspace}
%%\newcommand{\FLORA}{{\mbox{${\cal F}${\small\it LORA}\rm\emph{-2}}}\xspace}
%%\newcommand{\FLORA}{{\mbox{\sc Flora}\rm\emph{-2}}\xspace}
\newcommand{\FLORAone}{{\mbox{${\cal F}${\sc lora}}}\xspace}
\newcommand{\FLORID}{{\mbox{\sc Florid}}\xspace}
\newcommand{\fl}{\mbox{F-logic}\xspace}
\newcommand{\NAF}{{$\tt\backslash +$}\xspace}


\newcommand{\consts}{\ensuremath{\mathcal{C}}}
\newcommand{\funcs}{\ensuremath{\mathcal{F}}}
\newcommand{\preds}{\ensuremath{\mathcal{P}}}
\newcommand{\vars}{\ensuremath{\mathcal{V}}}

\newcommand{\ofile}{xwam}

\newcommand{\HU}{\ensuremath{U}}
\newcommand{\HB}{\ensuremath{\mathcal{HB}}}
\newcommand{\ext}{\ensuremath{^{\star}}}

\newcommand{\bksl}{\symbol{92}}
\newcommand{\dq}{\symbol{34}}


\title{
        \FLORA: User's Manual
           \\
       {\Large Version 0.92}
       }

\author{
  {Guizhen Yang
  \hspace{1cm}
  Michael Kifer
  \hspace{1cm}
  Chang Zhao}
  \\\\
  Department of Computer Science\\
  Stony Brook University\\
  Stony Brook, NY 11794-4400
  }
  
\makeindex
\begin{document}

\maketitle
\thispagestyle{empty}

\newpage
\pagenumbering{roman}
\setcounter{page}{1}

\tableofcontents

\newpage

\pagenumbering{arabic}
\setcounter{page}{1}


\section{Introduction}

\FLORA is a sophisticated object-oriented knowledge base language and
application development platform. It is implemented as a set of run-time
libraries and a compiler that translates a unified language of \fl
\cite{KLW95}, HiLog \cite{hilog-jlp}, and Transaction Logic
\cite{trans-chapter-98,trans-tcs94} into tabled Prolog code.

Applications of \FLORA include intelligent agents, Semantic Web, ontology
management, integration of information, and others. 

\index{FLIP}
\index{FLORID}
%%
The programming language supported by \FLORA is a dialect of \fl with
numerous extensions, which include a natural way to do meta-programming in
the style of HiLog and logical updates in the style of Transaction
Logic. \FLORA was designed with extensibility and flexibility in mind, and
it provides strong support for modular software design through its unique
feature of dynamic modules.
Other extensions, such as the versatile syntax of \FLORID path
expressions, are borrowed from
\FLORID, a C++-based \fl system developed at
Freiburg University.\footnote{
  %%
  See {\tt http://www.informatik.uni-freiburg.de/$\sim$dbis/florid/} for more
  details.
  %%
}
%%
Extensions aside, the syntax of \FLORA differs in many
important ways from \FLORID, from the original version of \fl, as described
in \cite{KLW95}, and from an earlier implementation of \FLORAone. These
syntactic changes were needed in order to bring the syntax of \FLORA closer
to that of Prolog and make it possible to include simple Prolog programs
into \FLORA programs without choking the compiler.  Other syntactic
deviations from the original F-logic syntax are a direct consequence of the
added support for HiLog, which obviates the need for the ``@'' sign in
method invocations (this sign is now used to denote calls to \FLORA
modules).

\FLORA is distributed in two ways. First, it is part of the official
distribution of XSB and thus is installed together with XSB
({\tt http://xsb.sourceforge.net}). Second, a more
up-to-date version of the system is available on \FLORA's
Web site at
%%
\begin{quote}
  {\tt http://flora.sourceforge.net}
\end{quote}
%%
These two versions can be
installed at the same time and used independently ({\it e.g.}, if you want
to keep abreast with the development of \FLORA or if a newer version was
released in-between the releases of XSB). The installation instructions are
somewhat different in these two cases.

\paragraph{Installing \FLORA in UNIX.}
To configure a version of \FLORA that was downloaded as part of the
distribution of XSB, simply configure XSB as usual:
%%
\begin{verbatim}
 cd XSB/build
 ./configure
 ./makexsb
 ./makexsb packages
\end{verbatim}
%%

If you downloaded XSB from its CVS repository earlier and are updating your
copy using the {\tt cvs update} command, then it might be a good idea to
also do the following: 
%%
\begin{verbatim}
 cd packages/flora2
 ./makeflora clean
 ./makeflora
\end{verbatim}
%%

To install the ``bleeding edge'' version of \FLORA from {\tt
http://flora.sourceforge.net}, download it (either as a tarball
or from CVS) into a separate directory \emph{outside} of the XSB
installation tree. After unpacking (or checking out from CVS) the \FLORA
sources will be placed in the subdirectory called {\tt flora2}. To
configure \FLORA, do the following:
%%
\begin{verbatim}
 cd flora2
 ./makeflora clean
 ./makeflora
\end{verbatim}
%%
(assuming that XSB has been already installed and configured separately).
If an XSB executable is not on your program search {\tt PATH}, then in the
third command above you
need to provide the XSB installation directory to {\tt makeflora} as
an argument, {\it e.g.},
%%
\begin{verbatim}
 ./makeflora all ~/XSB  
\end{verbatim}
%%

\paragraph{Installing \FLORA in Windows.}
First, you need Microsoft's {\tt nmake}.
Then use the following commands to configure
\FLORA (assuming that XSB is already installed and configured):
%%
\begin{alltt}
   cd flora2
   ./makeflora clean
   ./makeflora all \emph{path-to-prolog-executable}
\end{alltt}
%%
where \emph{path-to-prolog-executable} is the full path name of the XSB
executable.

In addition, make sure that the {\tt packages} directory contains a
shortcut called {\tt flora2.P} to the file
{\tt packages$\backslash$flora2$\backslash$flora2.P}.

%%\paragraph{Installing \FLORA in Windows under Cygwin.}
%%
%%Configure XSB as in Unix, but make sure that the option {\tt
%%  --with-no-cygwin} is used (yes, the name of the option is odd).
%%%%
%%\begin{verbatim}
%% cd XSB/build
%% ./configure --enable-no-cygwin
%% ./makexsb
%% ./makexsb packages
%%\end{verbatim}
%%%%
%%Then change to the \FLORA directory and configure \FLORA:
%%%%
%%\begin{alltt}
%%   cd flora2
%%   ./makeflora clean
%%   ./makeflora all \emph{path-to-prolog-executable}
%%\end{alltt}
%%%%
%%If XSB can be found through the PATH environment variable then you can
%%simply type {\tt ./makeflora}.


\paragraph{Running \FLORA.}
\FLORA is fully integrated into the underlying Prolog engine, including its
module system. In particular, \FLORA modules can invoke predicates defined in
other Prolog modules, and Prolog modules can query the objects defined in
\FLORA modules. At present, XSB is the only Prolog platform where \FLORA
can run, because it heavily relies on tabling and the well-founded
semantics for negation, both of which are available only in XSB.

\index{local scheduling in XSB}
%%
Due to certain problems with XSB, \FLORA runs best when XSB is configured
with \emph{local} scheduling, which is the default XSB configuration.
However, with this type of scheduling, many Prolog intuitions that relate
to the operational semantics do not work. Thus, the programmer must think
``more declaratively'' and, in particular, to not rely on the 
order in which answers are returned.


\index{runflora script}
\label{runflora-page}
%%
The easiest way to get a feel of the system
is to start \FLORA shell and begin to enter queries interactively.
The simplest way to do this is to use the shell script
%%
\begin{verbatim}
 .../flora2/runflora  
\end{verbatim}
%%
where ``...'' is the directory where \FLORA is downloaded. For instance, to
invoke the version supplied with XSB, you would type something like
%%
\begin{verbatim}
   ~/XSB/packages/flora2/runflora
\end{verbatim}
%%
If \FLORA is installed separately in a directory, say, {\tt bleeding-edge},
then it can be invoked as
%%
\begin{verbatim}
 ~/bleeding-edge/flora2/runflora  
\end{verbatim}
%%
You can take a look at this script and devise your own ways of calling \FLORA.
The version supplied with XSB can also be invoked using the following
commands:
%%
\begin{quote}
  \tt
foo>~~xsb  \\
\tt
... XSB loading messages omitted ...\\
\tt
| ?- [flora2], flora\_shell.\\
\tt
... FLORA messages omitted ... \\
| ?-
\end{quote}
%%
or even
%%
\begin{verbatim}
 foo>  xsb -e "[flora2]. flora_shell."
\end{verbatim}
%%

At this point, \FLORA takes over and \fl syntax becomes the
norm. To get back to the Prolog command loop, type {\tt Control-D} 
(Unix) or Control-Z (Windows), or 
%%
\begin{quote}
  \tt
| ?- flEnd.  
\end{quote}
%%

\noindent
If you are using \FLORA shell frequently, it pays to define an alias, say
(in Bash):
%%
\begin{verbatim}
 alias flora2='xsb -e "[flora2], flora_shell."'
 alias runflora='~/bleeding-edge/flora2/runflora'
\end{verbatim}
%%
\FLORA can then be invoked directly from the shell prompt by typing
{\tt flora2} or {\tt runflora}. 
%%
It is even possible to tell \FLORA to execute commands on start-up.
For instance, 
%%
\begin{verbatim}
 foo>  flora2 -e "flHelp."
 foo>  runflora -e "flHelp."
\end{verbatim}
%%
will cause the system to execute the help command right after after the
initialization. Then the usual \FLORA shell prompt is displayed.

\noindent
\FLORA comes with a number of demo programs that live in
%%
\begin{quote}
 \verb|.../flora2/demos/|  
\end{quote}
%%
The demos can be run issuing the command
``\verb|flDemo(demo-filename).|''
at the \FLORA prompt, {\it e.g.},
%%
\begin{quote}
 \verb|flora2 ?- flDemo(flogic_basics).|
\end{quote}
%%
There is no need to change to the demo directory, as {\tt flDemo} knows
where to find these programs.


\section{\FLORA Shell Commands} \label{sec-shell-commands}

The most common shell command you might need to execute is loading and
compiling a program:
%%
\begin{quote}
  flora2 ?-  {\tt [programfile].}
\end{quote}
%%
or 
%%
\begin{quote}
  flora2 ?- {\tt flLoad programfile.}
\end{quote}
%%
Here {\tt program-file} can contain a \FLORA program or a Prolog program. If
{\tt program-file.flr} exists, it is assumed to be a \FLORA program. The
system will compile the program, if necessary, and then load it. The
compilation process is two-stage: first, the program is compiled into a
Prolog program (one or more files with extensions {\tt .P} and {\tt .fdb})
and then into an executable byte-code, which has the extension {\tt .\ofile}.

If there is no {\tt program-file.flr} file, the file is assumed to contain
a Prolog program and the system will look for the file named {\tt
  program-file.P}. This file then is compiled into {\tt program-file.\ofile} and
loaded. Note that in this case the program is loaded into a {\em Prolog
  module} of \FLORA and, therefore, calls to the predicates defined in that
program must use the appropriate module attribution --- see
Section~\ref{sec:flora-modules} for the details about the module system in
\FLORA.

By default, all \FLORA programs are loaded into the module {\tt main}, but
you can also load them into other modules using the following syntax:
%%
{\tt
\begin{quote}
 flora2 ?-  [file>>modulename].
\end{quote}
}
%%
Understanding \FLORA modules is very important in order to be able to take
full advantage of the system; we will discuss the module system of \FLORA
in Section~\ref{sec:flora-modules}.  Once the program is loaded, you can
pose queries and invoke methods for the objects defined in the program.

There is an important special case of the {\tt flLoad} and {\tt [...]} command
when the file name is {\tt user}. In that case, instead of looking for the
program file {\tt user.flr}, \FLORA starts reading user input. At this
point, the user can start typing in program clauses, which the system saves
in a temporary file. When the user is done and types the end of file
character {\tt Control-D} (Unix) or {\tt Control-Z} (Windows),
the file is compiled and loaded. It is also possible to load such
a program into a designated module, rather than the default one,
using one of the following commands:
%%
{\tt
\begin{quote}
  flora2 ?- [file>>module].\\
  flora2 ?- flLoad file>>module.
\end{quote}
}
%%

\index{don't care variable}
\index{anonymous variable}
\index{variable!don't care}
\index{variable!anonymous}
%%
When the user types in a query to the shell, the query is evaluated and the
results are returned. A result is a tuple of values for each variable
mentioned in the query, except for the \emph{anonymous variables}
represented as ``{\tt \_}'' and named {\em don't care variables}, which are
preceded with the underscore, {\it e.g.}, {\tt \_abc}.

By default, \FLORA prints out all answers. If only one at a time is
desired, type in the following command: {\tt flOne}. You can revert back to
the all-answers mode by typing {\tt flAll}. Note: {\tt flOne} and {\tt flAll}
affect only the \emph{subsequent} queries. That is, in
%%
\begin{verbatim}
 flora2 ?- flOne, goallist1.
 flora2 ?- goallist2.
\end{verbatim}
%%
the {\tt flOne} directive will affect {\tt goallist2},
but \emph{not} {\tt goallist1}. This is because {\tt goallist1} executes in
the same query as {\tt flOne} and thus is not affected by this directive.

\FLORA shell includes many more commands beyond those mentioned above.
These commands are listed below. However, at this point the purpose of some
of these commands might seem a bit cryptic, so it is a good idea to come
back here after you become more familiar with the various concepts
underlying the system.

In the following command list, the suffixes {\tt .flr} {\tt .P}, {\tt
  .\ofile} are optional. If the file suffix is specified explicitly, the
system uses the file with the given name without any modification. The {\tt
  .flr} suffix denotes a \FLORA program, the {\tt .P} suffix indicates that
it is a Prolog program, and {\tt .\ofile} means that it is a bytecode file,
which can be executed by Prolog.  If no suffix is given, the system assumes it
is dealing with a \FLORA program and adds the suffix {\tt .flr}. If the
file with such a name does not exist, it assumes that the file contains a
Prolog program and tries the suffix {\tt .P}. Otherwise, it tries {\tt
  .\ofile} in the hope that an executable Prolog bytecode exists. If none of
these tries are successful, an error is reported.
%
\begin{itemize}
\item {\tt flHelp}:
    Show the help info.
\item {\tt flCompile file}:
    Compile FILE.flr for the default module {\tt main}.
\item {\tt flCompile file>>module}:
    Compile FILE.flr for the module {\tt module}.
  \item {\tt flLoad file>>module}: Load {\tt file.flr} into the module {\tt
      module}. If you specify {\tt file.P} or {\tt file.\ofile} then will load
    these files.
  \item {\tt flLoad file}: Load {\tt file.flr} into the default module {\tt
      main}. If you specify {\tt file.P} or {\tt file.\ofile} then will load
    these files.
\item {\tt [file.\{P$|$\ofile$|$flr\} $>>$ module,...]}:
    Load the files in the specified list into the module {\tt module}.
\item {\tt flDemo(demofilename)}:
    Consult a demo from \FLORA demos directory.
\item {\tt equality \{none$|$basic$|$flogic\}}:
    Set the level of support for the equality predicate {\tt :=:} in the
    shell module {\tt main}.
    {\tt none}  means that {\tt :=:} is treated as a regular
    predicate; {\tt basic} means that only standard first-order equality is
    supported ({\it i.e.}, the usual congruence rules); {\tt flogic} means
    that F-logic style equality is supported ({\it i.e.}, congruence plus
    the axiom for scalar methods).
\item {\tt abolish\_all\_tables}:
    Flush all tabled data. This is sometimes needed when Prolog's tabling 
    gets in the way. We describe tabling (as it pertains to \FLORA) in
    Section~\ref{sec-tabling-flora}.
\item {\tt op(Precedence,Associativity,Operator)}:
    Define an operator in shell mode.
\item
  \index{{\tt flReset}}
  %%
  {\tt flReset(\{op\})}:
    Clear all operator definitions in the \FLORA shell.
\item {\tt flAll}:
    Show all solutions (default). Affects subsequent queries only.
\item {\tt flOne}:
    Show solutions to subsequent queries one by one.
\item {\tt flMaxerr(all$|$N)}:
    Set/show the maximum number of errors \FLORA reports.
\item {\tt flTrace/flNoTrace}:
    Turn on/off \FLORA trace.
\item {\tt flChatter/flNoChatter}:
    Turn on/off the display of the number of solutions at the end of query
    evaluation.
\item {\tt flEnd}:
    Say Ciao to \FLORA, stay in Prolog.
\item {\tt flHalt}:
    Quit both \FLORA and Prolog.
\end{itemize}
%%

In general, \FLORA built-in predicates whose name is of the form {\tt
  fl[A-Z]...} are either the \FLORA shell commands or predicates that can
be used in Prolog to control the execution of \FLORA modules. We will
discuss the latter in Section~\ref{sec-flora-from-prolog}. Some of these
commands --- mostly dealing with loading and compilation of \FLORA modules
  --- can also be useful within \FLORA applications.

All commands with a FILE argument passed to them use the Prolog
{\tt library\_directory} predicate to search for the file, except that the
command {\tt flDemo(FILE)} first looks for {\tt FILE} in the \FLORA demo
directory. The search path typically includes the standard system's
directories used by Prolog followed by the current directory. 

All Prolog commands can be executed from \FLORA shell, if the corresponding
Prolog library has already been loaded.

After a parsing or compilation error, \FLORA shell will
discard tokens read from the current input stream until the end of file or a
rule delimiter (``.'') is encountered. If \FLORA shell seems to be hanging
after the message
\begin{quote}
\begin{verbatim}
++FLORA Warning: discarding tokens (rule delimiter `.' or EOF expected)
\end{verbatim}
\end{quote}
%%
hit the {\tt Enter} key once, type ``.'', and then {\tt Enter} again.  This
should reset the current input buffer and you should see the \FLORA command
prompt:
\begin{quote}
\begin{verbatim}
flora2 ?-
\end{verbatim}
\end{quote}

 
\section{\fl and \FLORA by Example}


In the future, this section will contain a number of small
introductory examples illustrating the use of \fl and \FLORA. Meanwhile, the
reader is referred to the excellent tutorial written by the members of the
\FLORID project.\footnote{
  %%
  See {\tt http://www.informatik.uni-freiburg.de/$\sim$dbis/florid/} for more
  details.
  %%
  }
%%
Since \FLORA and \FLORID share much of the same syntax, most examples in that
tutorial can be made into valid \FLORA programs by changing the separator
``;'' used in F-molecules into ``,'' and by eliminating the ``@''
sign in method invocations.



\section{Basic \FLORA Syntax}

In this section we describe the basic syntactic structures used to build
\FLORA programs. Subsequent sections describe the various advanced features
that are needed to build practical applications. The complete syntax is
given in Appendix~\ref{app-bnf}. However, it should be noted that BNF
cannot describe the syntax of FLORA precisely, because it is based on
operator grammar (like in Prolog) mixed with context free grammars in
places where operator grammar is inadequate (as, for example, in parsing
if-then-else).


\subsection{\fl Vocabulary}\label{sec-basic-flogic}


\begin{itemize}
\item \emph{Symbols}: The \fl alphabet of \emph{object constructors}
  \index{object constructor}
  consists of the sets \funcs (function symbols), \preds (predicate symbols
  including $=$), and \vars (variables).  Variables begin with a
  capitalized letter or an underscore, followed by zero or more letters
  and/or digits and/or underscores (e.g., $\tt X, Name, \_, \_v\_5$).
  All other symbols, including the constants (which are 0-ary object
  constructors), are symbols that start with a lowercase letter (e.g., {\tt a,
  john}). Constants can also be any string of symbols enclosed in single
  quotes (e.g., {\tt 'AB@*c'}). 
  In addition to the usual first-order connectives and symbols, there is a
  number of special symbols:
  ], [, \}, \{, ``,'', ``;'', \#, \_\#, \fd, \mvd, \Fd,
  \Mvd, \isa, \subcl. Later we will explain other symbols introduced by
  the inheritance mechanism.
  
\item \emph{Variables}: The variable ``\_'' is called \emph{anonymous}
  variable. It is used whenever a \emph{unique} new variable is needed.  In
  particular, two different occurrences of ``\_'' in the same clause are
  treated as \emph{different} variables. Named variables that start with an
  underscore, e.g., {\tt \_foo}, are called \emph{don't care} variables.
  Unlike anonymous variables, two different occurrences of such a variable
  in the same clause refer to the \emph{same} variable. Nevertheless, don't
  variables have special status when it comes to error checking
  and returning answers.  The practice of logic programming shows that a
  singleton occurrence of a variable in a clause is often a mistake due to
  misspelling. Therefore, \FLORA issues a warning when it finds that some
  variable is mentioned only once in a clause. If such an occurrence is
  truly intended, it must be replaced by an anonymous variable or a don't
  care variable to avoid the warning message from \FLORA. Also, bindings
  for anonymous and don't care variables are not returned as answers.

  %%
  \index{Id-term}
  \index{oid}
  \index{object identifier}
\item \emph{Id-Terms/Oids}:
    First-order terms over \funcs\ and \vars\ are called \emph{Id-terms},
    and are used to name objects, methods, and classes.  Ground Id-terms
    (i.e., terms with no variables) correspond to \emph{logical
      object identifiers} (\emph{oid}s), also called object \emph{names}.
    Numbers (including integers and floats) can also be used as Id-terms,
    but such use might be confusing and is not recommended.
  \index{atomic formula!in \fl}
\item \emph{Atomic formulas}: Let $\tt O,M,R_{i},X_{i},C,D,T$ be Id-terms.  In
  addition to the usual first-order atomic formulas, like
  $p(X_1,\dots,X_n)$, there are the following basic types of formulas:
  \medskip

  \begin{enumerate}
    \item \label{eq-scalar-atom} $\tt O[M\fd V]$
    \item $\tt O[M\mvd \{V_1,\dots,V_n\}]$
    \item $\tt C[M\Fd T]$
    \item $\tt C[M\Mvd \{T_1,\dots,T_m\}]$
  \end{enumerate}
  
  \index{data atom}
  \index{atom!data}
  \index{method}
  \index{method!single-valued}
  \index{method!scalar}
  \index{method!multi-valued}
  \index{method!set-valued}
  %
  In all of the above cases, {\tt O}, {\tt C}, {\tt M}, ${\tt V_i}$, and
  ${\tt T_i}$ are HiLog terms, {\it i.e.}, expressions of the form, $\tt a$,
  $\tt f(X)$, $\tt X(s,Y)$, $\tt X(f,Y)(X,g(k))$, etc., where $\tt X$
  and $\tt Y$ are variables and lowercase letters $\tt f$, $\tt s$, etc., are
  constants.
  
  Expressions (1) and (2) above are \emph{data atoms}, which specify that a
  \emph{method expression} $\tt M$ applied to an object $\tt O$ yields the
  result object $\tt V$ in case (1), or a set of objects, $\tt V_1$, ...,
  $\tt V_n$, in case (2). Thus, in (1), $\tt M$ is said to be a
  \emph{single-valued} (or \emph{scalar}) method expression, i.e., there is
  at most one $\tt V$ such that $\tt O[M\fd V]$ holds.  In contrast, in
  (2), $\tt M$ is \emph{multi-valued} (also known as \emph{set-valued}), so
  the result contains several objects, which \emph{includes} $\tt V_1$,
  $\tt V_2$, ..., $\tt V_n$. Note that we emphasized ``includes'' rather
  than ``equals'', because other facts and rules in the program can specify
  additional objects that must be considered part of the method result.
  
  When $n=1$ in set-valued data atoms, the curly braces can be omitted. For
  instance, $\tt O[M\mvd V_1]$. In fact, the single expression (2) is
  equivalent to a the following set of expressions, where the result set is
  split into singletons:
  %%
  \begin{quote}
  $\tt O[M\mvd V_1]$    \\
  $\tt O[M\mvd V_2]$    \\
  $~~~\dots$\\
  $\tt O[M\mvd V_n]$
  \end{quote}
  %%
  
  When $\tt M$ is a constant, {\it e.g.}, {\tt abc}, then we say that it is
  an \emph{attribute}; for example, {\tt john[name\fd 'John']}. When $\tt
  M$ has the form {\tt f(X,Y,Z)} then we refer to it as a method, {\tt f},
  with arguments {\tt X}, {\tt Y}, and {\tt Z}; for example, {\tt
  john[salary(1998)\fd 50000]}.  However, as we saw
  earlier, method expressions can be much more general than these two
  possibilities, as they can be arbitrary HiLog terms.


  \medskip

  \index{atom!signature}
  \index{signature!in \fl}
  %%
  Expressions (3) and (4) above denote \emph{signature atoms}. They specify
  that the method expression, $\tt M$, when applied to objects that belong
  to class $\tt C$, must yield objects that belong to class $\tt T$.  In (3),
  $M$ is declared as single-valued, while in (4) it is set-valued. In a
  set-valued signature, the intention is that the method expression $\tt M$
  must return objects that belong \emph{simultaneously} to the classes
  $\tt T_1$, ..., $\tt T_m$. As with data atoms, a single set-valued
  signature expression of the form (4) is equivalent to the set of
  signature expressions
  %%
  \begin{quote}
      $\tt O[M\Mvd T_1]$    \\
      $\tt O[M\Mvd T_2]$    \\
      $~~~\dots$\\
      $\tt O[M\Mvd T_m]$
  \end{quote}
  %%
  and the curly braces \{ and \} can be omitted when only one class appears
  on the right of $\Mvd$.

  Note that it is allowed for the same method to have both a single-valued
  signature and a set-valued one. The single-valued signature controls the
  data atoms that use $\fd$, and the set-valued signatures control data
  atoms that use $\mvd$.
  
  \medskip

  \index{atom!isa}
  %%
  Objects are grouped into classes using \emph{ISA-atoms}:
  \medskip

  \begin{enumerate}
  \item[5.] $\tt O\isa C$
  \item[6.] \label{eq-subclass} $\tt C\subcl D$
  \end{enumerate}

  \index{class}
  \index{subclass}
  \index{class!subclass}
  \index{class!instance}
  %%
  The expression (5) states that $\tt O$ is an \emph{instance} of class $\tt C$,
  while (6) states that $\tt C$ is a \emph{subclass} of $D$.
\item
  \index{F-molecule}
  \emph{F-molecules} provide a convenient way to shortcut specifications
  related to the same object. For instance, the conjunction of the atoms
  {\tt john{\isa}person}, {\tt john[age{\fd}31]}, {\tt
  john[children\mvd\{bob,mary\}]}, and {\tt john[children\mvd john]}
  is equivalent to the following single F-molecule:
  %%
  \begin{quote}
    {\tt john{\isa}person[age{\fd}31, children\mvd\{bob,mary,john\}]} 
  \end{quote}
  %%
  Note the use of the ``,'' that separates the expression for the {\tt age}
  attribute from the expression for the {\tt children} attribute. This is a
  departure from the original \fl syntax in \cite{KLW95}, which uses ``;'' 
  to separate such expressions.
  
\item \emph{Rules} are, as usual, the constructs of the form $head :-
  body$, where $head$ is an F-molecule and \emph{body} is a conjunction of
  F-molecules or negated F-molecules. (Negation is specified using {\NAF}
    or {\tt tnot} --- the difference will be explained later.)
  Each rule must be terminated with a ``.''.
  
  Conjunction is specified as in Prolog, using the ``,'' symbol. Like in
  Prolog, \FLORA also allows disjunction in the rule body, which is denoted
  using ``;''. As usual in logic languages, a single rule of the form
  %%
  \begin{equation}\label{eq-disjunction}
  {\tt
    {\it head}~:-~john[age{\fd}31],~(john[children\mvd\{bob,mary\}]~;~
    john[children\mvd john]).
    }
  \end{equation}
  %%
  is equivalent to the following pair of rules:
  %%
  \begin{quote}
  {\tt
    {\it head}~:-~john[age{\fd}31],~john[children\mvd\{bob,mary\}].
    }
  \\
  {\tt
    {\it head}~:-~john[age{\fd}31],~john[children\mvd john].
    }
  \end{quote}
  %%
  Disjunction is also allowed inside F-molecules. For instance, the rule
  (\ref{eq-disjunction}) can be equivalently rewritten as:
  %%
  \begin{quote}
 {\tt
   {\it head}~:-~john[age{\fd}31,~(children\mvd\{bob,mary\}~;~children\mvd john)].
   }
  \end{quote}
  %%
  Note that conjunction ``,'' binds stronger than disjunction ``;'', so the
  parentheses in the above example are essential.
  
\item \emph{Programs and queries}: A \emph{program} is a set of rules. A
  \emph{query} is a rule without the head. In \FLORA, such headless rules
  use {\tt ?-} instead of {\tt :-}, {\it e.g.}, 
  %%
  \begin{quote}
    {\tt 
    ?-~john[age->X].    
    }
  \end{quote}
  %%
  The symbol {\tt :-} in headless \FLORA expressions is used for various
  directives, which are plenty and will be introduced in due course.
\end{itemize}



\begin{example}
  {\bf (Publications Database)} \rm Figure~\ref{fig-flogic-model} depicts
  a fragment of a \FLORA program that represents a database of scientific
  publications.
\end{example}


\begin{figure}[htb]
\begin{tabular}{c}
  \begin{tabular}{l}
    {\bf Schema:}\\
    conf\_p\subcl paper. \\
    journal\_p\subcl paper.\\
    paper[authors\Mvd  person, title\Fd string].\\
    journal\_p[in\_vol\Fd volume]. \\
    conf\_p[at\_conf\Fd conf\_proc].\\
    journal\_vol[of \Fd journal, volume\Fd integer, 
               number\Fd integer, year\Fd integer].\\  
    journal[name\Fd string, publisher\Fd string,
            editors\Mvd person]. \\
    conf\_proc[of\_conf\Fd conf\_series, year\Fd integer,
               editors\Mvd person]. \\
    conf\_series[name\Fd string]. \\
    publisher[name\Fd string].\\
    person[name\Fd string, affil(integer)\Fd institution]. \\
    institution[name\Fd string, address\Fd string].\smallskip\\

    {\bf Objects:}\\
    $o_{j1}$\isa journal\_p[%
      title\fd 'Records, Relations, Sets, Entities, and Things',
      authors\mvd$\{o_{mes}\}$, in\_vol\fd $o_{i11}$]. \\
    $o_{di}$\isa conf\_p[
      title\fd 'DIAM II and Levels of Abstraction',
      authors\mvd$\{o_{mes},o_{eba}\}$, at\_conf\fd $o_{v76}$]. \\
    $o_{i11}$\isa journal\_vol[of\fd $o_{is}$, number\fd 1, volume\fd 1, year\fd1975]. \\
    $o_{is}$\isa journal[name\fd'Information Systems', editors\mvd $\{o_{mj}\}$]. \\
    $o_{v76}$\isa conf\_proc[of\fd vldb, year\fd 1976, editors\mvd $\{o_{pcl},o_{ejn}\}$].\\
    $o_{vldb}$\isa conf\_series[name\fd'Very Large Databases']. \\
    $o_{mes}$\isa person[name\fd'Michael E. Senko']. \\
    $o_{mj}$\isa person[name\fd'Matthias Jarke', affil(1976)\fd $o_{rwt}$]. \\
    $o_{rwt}$\isa institution[name\fd'RWTH\_Aachen'].
\end{tabular}
\end{tabular}
\caption{A Publications Object Base and its Schema in \FLORA}
  \label{fig-flogic-model}
\end{figure}



\subsection{Symbols, Strings, and Comments}


\index{symbol}
%%
\paragraph{Symbols.}
\FLORA symbols (that are used for the names of constants, predicates, and
object constructors) begin with a lowercase letter followed by zero or more
letters ($\tt A \ldots Z, a \ldots z$), digits ($\tt 0 \ldots 9$), or underscores
(\_), e.g., \texttt{student}, \texttt{apple\_pie}. Symbols can also be
\emph{any} sequence of characters enclosed in a pair of single quotes,
e.g., \texttt{'JOHN SMITH'},\texttt{'default.flr'}.  Internally, \FLORA
symbols are represented as \emph{Prolog symbols},\footnote{
  %%
  Symbols are called ``atoms'' in Prolog, which contravenes the use of this
  term for atomic formulas in classical logic and \fl.
  We avoid the use of the term ``atom'' in reference to symbols.
  %%
  }
%%
which are used there as names of predicates and function symbols.

\begin{table}[htb]
\center
\texttt{ \small
\begin{tabular}{|c|r@{\hspace{1.5cm}}|@{\hspace{5mm}}l@{\hspace{5mm}}|}
\hline
Escaped String &
  \multicolumn{1}{c|@{\hspace{5mm}}}{ASCII (decimal)} &
  \multicolumn{1}{c|}{Symbol} \\ \hline
{\bksl}{\bksl} &  92 & {\bksl} \\ \hline
{\bksl}n &  10 &		 NewLine \\ \hline
{\bksl}N &  10 &		 NewLine \\ \hline
{\bksl}t &   9 &		 Tab \\ \hline
{\bksl}T &   9 &		 Tab \\ \hline
{\bksl}r &  13 &		 Return \\ \hline
{\bksl}R &  13 &		 Return \\ \hline
{\bksl}v &  11 &		 Vertical Tab \\ \hline
{\bksl}V &  11 &		 Vertical Tab \\ \hline
{\bksl}b &   8 &		 Backspace \\ \hline
{\bksl}B &   8 &		 Backspace \\ \hline
{\bksl}f &  12 &		 Form Feed \\ \hline
{\bksl}F &  12 &		 Form Feed \\ \hline
{\bksl}e &  27 &		 Escape \\ \hline
{\bksl}E &  27 &		 Escape \\ \hline
{\bksl}d & 127 &		 Delete \\ \hline
{\bksl}D & 127 &		 Delete \\ \hline
{\bksl}s &  32 &		 Whitespace \\ \hline
{\bksl}S &  32 &		 Whitespace \\
\hline
\end{tabular}
}
\caption{Escaped Character Strings and Their Corresponding Symbols}
\label{tab:tab-esc-str}
\end{table}

\index{escaped character}
%%
\FLORA also recognizes escaped characters inside single quotes
(\texttt{'}).  An escaped character normally begins with a backslash
(\texttt{\bksl}).  Table~\ref{tab:tab-esc-str} lists the special escaped
character strings and their corresponding special symbols. An escaped
character may also be any ASCII character. Such a character is preceded
with a backslash together with a lowercase \texttt{x} (or an uppercase
\texttt{X}) followed by one or two hexadecimal symbols representing its
ASCII value. For example, \texttt{{\bksl}xd} is the ASCII character
Carriage Return, whereas \texttt{{\bksl}x3A} represents the semicolon. In
other cases, a backslash is recognized as itself.

One exception is that inside a quoted symbol, a single quote character is
escaped by another single quote, e.g., \texttt{'isn''t'}.

\paragraph{Strings (character lists).}

\index{string}
\index{character list}
%
Like Prolog strings, \FLORA strings are enclosed in a pair of double quotes
(\texttt{\dq}).  These strings are represented internally as lists of
ASCII characters. For instance, \mbox{\texttt{[102,111,111]}} is the same
as \texttt{{\dq}foo{\dq}}.

Escape characters are recognized inside \FLORA strings similarly to
\FLORA symbols.  However, inside a string, a single quote character does
not need to be escaped. A double quote character, however, needs to be
escaped by another double quote, e.g.,
\texttt{{\dq}{\dq}{\dq}foo{\dq}{\dq}{\dq}}.

\paragraph{Numbers.}

\index{number}
%%
\index{integer}
%%
\index{floating number}
%%
Normal \FLORA integers are decimals represented by a sequence of digits,
e.g., \texttt{892, 12}.  \FLORA also recognizes integers in other bases (2 through
36). The base is specified by a decimal integer followed by a single quote
(\texttt{'}). The digit string immediately follows the single quote. The
letters $\tt A \ldots Z$ or $\tt a \ldots z$ are used to represent digits greater
than 9.  Table~\ref{tab:tab-int-rep} lists a few example integers.
%%
\begin{table}[htb]
\center
\texttt{ \small
\begin{tabular}{|r@{'}l|r@{\hspace{1.5cm}}|c|}
\hline
  \multicolumn{2}{|c|}{Integer} &
  \multicolumn{1}{c|}{Base (decimal)} &
  \multicolumn{1}{c|}{Value (decimal)} \\ \hline
\multicolumn{1}{|r}{} & \multicolumn{1}{@{}l|}{1023} &  10 & 1023 \\ \hline
2 & 1111111111 & 2 & 1023 \\ \hline
8 & 1777 & 8 & 1023 \\ \hline
16 & 3FF &  16 & 1023 \\ \hline
32 & vv & 32 & 1023 \\
\hline
\end{tabular}
}
\caption{Representation of Integers}
\label{tab:tab-int-rep}
\end{table}

Underscore (\texttt{\_}) can be put inside any sequence of digits as
delimiters. It is used to partition some long numbers. For instance,
$\texttt{2'11\_1111\_1111}$ is the same as $\texttt{2'1111111111}$.
However, ``\texttt{\_}'' cannot be the first symbol of an integer, since
variables can start with an underscore. For example, $1\_2\_3$ represents
the number $123$ whereas $\_12\_3$ represents a variable named $\_12\_3$.

Floating numbers normally look like {\tt 24.38}. The decimal point
must be preceded by an integral part, even if it is 0, e.g., {\tt 0.3}
must be entered as {\tt 0.3}, but not as {\tt .3}. Each floating
number may also have an optional exponent. It begins with a lowercase
{\tt e} or an uppercase {\tt E} followed by an optional minus sign
({\tt -}) or plus sign ({\tt +}) and an integer. This exponent is
recognized as in base 10. For example,
\mbox{\tt 2.43E2 is 243} whereas
\mbox{\tt 2.43e-2 is 0.0243}.

\paragraph{Comments.}

\index{comment}
%
\FLORA supports three kinds of comments: (1) all characters following
{\tt \%} until the end of the line; (2) all characters following
{\tt //} until the end of the line; (3) all characters inside a pair of
{\tt /*} and {\tt */}. Note that only (3) can span multiple lines.

Comments are recognized like whitespaces by the compiler.  Therefore,
tokens can also be delimited by comments.


\subsection{Operators}


\index{operators}
%%
As in Prolog, \FLORA allows the user to define operators, to liven up the
otherwise boring syntax.  There are three kinds of operators: infix,
prefix, and postfix. An infix operator appears between its two arguments,
while a prefix operator before its single argument and a postfix operator
after its single argument. For instance, if {\tt foo} is defined as an
infix operator, then {\tt X foo a} will be parsed as {\tt foo(X,a)} and if
{\tt bar} is a postfix operator then {\tt X bar} is parsed as {\tt bar(X)}. 

\index{operators!precedence level}
\index{operators!type}
%
Each operator has a \emph{precedence level}, which is a positive integer.
Each operator also has a \emph{type}. The possible types for infix operators
are: {\tt xfx}, {\tt xfy}, {\tt yfx}; the possible types for prefix
operators are: {\tt fx}, {\tt fy}; and the possible types for postfix
operators are: {\tt xf}, {\tt yf}. In each of these type expressions, {\tt
  f} stands for the operator, and {\tt x} and {\tt y} stand for the
arguments.  The symbol {\tt x} in a type expression means that the
precedence level of the corresponding argument should be \emph{strictly
  less} than that of the operator, while {\tt y} means that the precedence
level of the corresponding argument should be \emph{less or equal} than
that of the operator.

The precedence level and the type together determine the way the operators
are parsed. The general rule is that precedence of a constant or a functor
symbol that has not been defined as an operator is zero. Precedence of a
Prolog term is the same as the precedence of its main functor. 
An expression that contains several operators is parsed in such a way that
the operator with the highest precedence level becomes the main functor of
the parsed term, the operator with the next-highest precedence
level becomes the main functor of one of the arguments, and so on.
If an expression cannot be parsed according to this rule, a parse error is
reported.

It is not our goal to cover the use of operators in any detail, since this
information can be found in any book on Prolog. Here we just give an
example that illustrates the main points.  For example, in \FLORA, {\tt -}
has precedence level {\tt 800} and type {\tt yfx}, {\tt *} has precedence
level {\tt 700} and type {\tt yfx}, {\tt ->} has precedence level 1100 and
type {\tt xfx}.  Therefore, {\tt 8-2-3*4} is the same as {\tt
  -(-(8,2),*(3,4))} in prefix notation, and {\tt a -> b -> c} will generate
a parsing error.


\index{compiler directive!{\tt op}}
%
Any symbol can be defined as an operator. The general syntax is
\begin{qrules}
{\tt :- op(\emph{Precedence},\emph{Type},\emph{Name}).}
\end{qrules}
%%
For instance, 
%%
\begin{quote}
 {\tt
   :- op(800, xfx, foo)
   }
\end{quote}
%%
As a notational convenience, the argument {\tt Name} can also be a list of
operator names of the same type and precedence level, for instance,
\begin{qrules}
{\tt :- op(800,yfx,[+,-]).}
\end{qrules}
%%
It is possible to have more than one operator with the same name provided
they have different use ({\it e.g.}, one infix and the other postfix).
However, the \FLORA built-in operators are not allowed to be redefined.
In particular, any symbol that is part of \fl syntax, such as ``,', ``.'',
``[``, ``:'', etc., as well as any name that begins with {\tt flora} or
{\tt fl} followed by a capital letter should be considered as reserved for
internal use.

Although this simple rule is sufficient, in most cases, to keep you out of
trouble, you should be aware of the fact that symbols such as ``{\tt ,}'',
``{\tt ;}'', ``{\tt +}'', ``{\tt .}'', ``{\tt ->}'', ``{\tt ::}'', ``{\tt
  :-}'', ``{\tt ?-}'' and many
other parts of \FLORA syntax are operators. Therefore, there is a chance
that precedence levels chosen for the user-defined operators conflict with
those of \FLORA and, as a result, your program might not parse. If in
doubt, check the declarations in the file {\tt flroperator.P} in the \FLORA
source code.

The fact that some symbols are operators can sometimes lead to
surprises. For instance,
%%
\begin{verbatim}
 ?- (a,b,c).
 :- (a,b).
\end{verbatim}
%%
will be interpreted as terms {\tt '?-'(a,b,c)} and {\tt ':-'(a,b)} rather
than a query and a directive, respectively. The reason for this is that,
first, such terms are allowed in Prolog and there is no good reason to ban
them in \FLORA; and, second, the above syntax is ambiguous and the parser
makes the choice that is consistent with the choice made in
Prolog. Typically users do not put parentheses around subgoals in such
cases, and would instead write
%%
\begin{verbatim}
 ?- a,b,c.
 :- a,b.  
\end{verbatim}
%%
Note that things like
%%
\begin{verbatim}
?- (a,b),c.  
?- ((a,b,c)).
\end{verbatim}
%%
will be interpreted as queries, so there are plenty of ways to satisfy
one's fondness for redundant parentheses.


\subsection{Logical Expressions}


\index{logical expressions}
%
In a \FLORA program, any combination of conjunction, disjunction, and
negation of literals can appear wherever a logical formula is allowed,
e.g., in a rule body.

Conjunction is represented through the infix operator ``{\tt ,}'' and
disjunction is made using the infix operator ``{\tt ;}''.  Negation is made
through the prefix operators ``\NAF'' and ``{\tt
  tnot}''.\footnote{
  %%
  In brief, ``{\tt $\backslash$+}'' represents negation as
  failure and can be applied only to non-tabled Prolog, \FLORA, or HiLog
  predicates. ``{\tt tnot}'', on the other hand, is negation that
  implements the well-founded semantics.  Refer to
  Section~\ref{sec:negation} for more information on the difference between
  negation operators. 
  %%
  }
%%
When parentheses are omitted, conjunction binds stronger than disjunction
and the negation operators bind their arguments stronger than the other
logical operators.  For example, in \FLORA the following expression:
\verb|a, b; c, not d|, is equivalent to the the logical formula: $\tt (a
\wedge b) \vee (c \wedge (\neg d))$.

\index{molecule!logic expressions}
%
Logical formulas can also appear inside the specification of an object. For
instance, the following F-molecule:
\begin{qrules}
o[tnot att1{\fd}val1, att2{\mvd}val2; meth{\fd}res]
\end{qrules}
is equivalent to the following formula:
\begin{qrules}
(tnot o[att1{\fd}val1], o[att2{\mvd}val2]) ; o[meth{\fd}res]
\end{qrules}


\subsection{Arithmetic Expressions}


\index{arithmetic expression}
%%
In \FLORA arithmetic expressions are \emph{not} always evaluated. As in
Prolog, the arithmetic operators such as {\tt +}, {\tt -}, {\tt /}, and
{\tt *}, are defined as normal binary functors. To evaluate an arithmetic
expression, \FLORA provides another operator, {\tt is}.  For example, {\tt
  X is 3+4} will bind {\tt X} to the value {\tt 7}.

When dealing with arithmetic expressions, the order of literals is
important.  In particular, all variables appearing in an arithmetic
expression must be instantiated at the time of evaluation. Otherwise, a
runtime error will occur. For instance, 
%%
\begin{qrules}
  \tt
?- X > 1, X is 1+1.
\end{qrules}
%%
will produce an error, while
%%
\begin{qrules}
  \tt
?- X is 1+1, X > 1.
\end{qrules}
%%
will evaluate to true.

As in Prolog, the operands of an arithmetic expression can be any variable
or a constant. However, in \FLORA, an operand can also be a \emph{path
  expression}. For the purpose of this discussion, a path expression of the
form $\tt p.q$ should be understood as a shortcut for {\tt p[q$\fd$X]}, where
$\tt X$ is a new variable, and $\tt p.q.r$ is a shortcut for {\tt p[q$\fd$X],
  X[r$\fd$Y]}. For set-valued formulas, the notation ``..'' is used. For
instance, {\tt p..q} stands for {\tt p[q$\mvd$X]}. More detailed discussion
of path expressions appears in Section~\ref{sec-pathexpr}.

Both single-valued and multi-valued path expressions are allowed in
arithmetic expressions, and all variables are considered to be
existentially quantified. For example, the following query
%%
\begin{qrules}
?- john..bonus $+$ mary..bonus $>$ 1000.
\end{qrules}
%%
should be understood as
%%
\begin{qrules}
?- john[bonus{\mvd}{\tt \_V1}], mary[bonus{\mvd}{\tt \_V2}], ${\tt \_V1}+{\tt \_V2} > 1000$.
\end{qrules}
%%
Note that in first query does not have any variables, so after the
evaluation the system would print either yes or no. To achieve the same
behavior, we use \emph{don't care variables}, {\tt \_V1} and {\tt
  \_V2}. If we used {\tt V1} and {\tt V2} instead, the values of these
variables would have been printed out.

\FLORA recognizes numbers as oids and, thus, it is perfectly normal to have
allows arithmetic expressions inside path expressions such as this:
{\tt 1.2.(3+4*2).7}. When parentheses are omitted, this might lead to
ambiguity.
For instance, is the meaning of
%%
\begin{qrules}
1.m+2.n.k
\end{qrules}
%%
represented by
the arithmetic expression {\tt (1.m)+(2.n.k)}, or by
the path expressions {\tt (1.m+2.n).k}, by {\tt (1.m + 2).n.k}, or by {\tt
  1.(m+2).n.k}? To disambiguate such expressions, we must remember that the
operators ``.'' and ``..'' used in path expressions bind stronger than the
arithmetic operators $+$, $-$, etc.

Even more interesting is the following example: {\tt 2.3.4}. Does it
represent the path expression {\tt (2).(3).(4)}, or {\tt (2.3).4}, or {\tt
  2.(3.4)} (where in the latter two cases 2.3 and 3.4 are interpreted as
decimal numbers)? The answer to this puzzle (according to \FLORA conventions)
is {\tt (2.3).4}: when
tokenizing, \FLORA first tries to classify tokens into meaningful
categories. Thus, when 2.3 is first found, it is identified as a
decimal. Thus, the parser receives the expression (2.3).4, which it
identifies as a path expression that consists of two components, the oids
2.3 and 4.

Another ambiguous situation arises when the symbols {\tt -} and {\tt +} are
used as minus and plus
signs, respectively. \FLORA follows the common arithmetic interpretation of
such expressions, where the {\tt +/-} signs bind stronger than the infix
operators and thus
{\tt 4--7} and {\tt 4-+7} are interpreted as {\tt 4-(-7)} and {\tt 4-(+7)},
respectively.

%%
\begin{table}[tb]
\center
\texttt{ \small
\begin{tabular}{|c|c|c|c|c|}
\hline
%%
Precedence  & Operator & Use & Associativity & Arity \\ \hline
not applicable & () & parentheses & not applicable & not applicable\\ \hline
not applicable & . & decimal point & not applicable & not applicable \\ \hline
            & .   & single-valued object reference & left & binary \\ \cline{2-5}
300         & ..   & multi-valued object reference & left & binary \\ \cline{2-5}
            & :    & ISA specification & left & binary \\ \cline{2-5}
            & ::   & subclass specification & left & binary \\ \hline
600         & - & minus sign & right & unary \\ \cline{2-5}
            & + & plus sign & right & unary \\ \hline
700         & * & multiplication & left & binary \\ \cline{2-5}
            & / & division & left & binary \\ \hline
800         & - & subtraction & left & binary \\ \cline{2-5}
            & + & addition & left & binary \\ \hline
            & =< & less than or equals to & not applicable & binary \\ \cline{2-5}
            & >= & greater than or equals to & not applicable & binary \\ \cline{2-5}
1000        & =:= & equals to & not applicable & binary \\ \cline{2-5}
            & ={\bksl}= & unequal to & not applicable & binary \\ \cline{2-5}
            & is & assignment & not applicable & binary \\
\hline
\end{tabular}
}
\caption{Operators in Non-Increasing Precedence Order and Their Associativity and Arity}
\label{tab:tab-op-pre}
\end{table}

Table~\ref{tab:tab-op-pre} lists various operators in decreasing precedence
order, their associativity, and arity.  When in doubt, use parentheses.
Here are some more examples of valid arithmetic expressions:
{\tt
\begin{quote}
o1.m1+o2.m2.m3~~~~~~~~~{\rm same as} (o1.m1)+(o2.m2)\\
2.(3.4)~~~~~~~~~~~~~~~~{\rm the value of the attribute} 3.4 {\rm on object} 2\\
3 + - - 2~~~~~~~~~~~~~~{\rm same as} 3+(-(-2))\\
5 * - 6~~~~~~~~~~~~~~~~{\rm same as} 5*(-6)\\
5.(-6)~~~~~~~~~~~~~~~~~{\rm the value of the attribute} -6 {\rm on object} 5
\end{quote}
}
%%
Note that the parentheses in {\tt 5.(-6)} are needed,
because otherwise ``{\tt .-}'' would be recognized as a single token.
Similarly, the whitespace around ``{\tt +}'', ``{\tt -}'', and ``{\tt *}''
are also needed in these examples to avoid {\tt *-} and {\tt +--} being
interpreted as distinct token.


\section{Multifile Programs}

\FLORA supports many ways in which a program can be modularized.  First, an
\fl program can be split into many files with separate namespaces. Each
such file can be considered an independent library, and the different
libraries can call each other. In particular, the same method name (or a
predicate) can be used in different files and the definitions will not
clash.  Second, a program file can be split of several files, and these
files can be included by the preprocessor prior to the compilation. In this
case, all files share the same namespace in the sense that the different
rules that define the same method name (or a predicate) in different files
are assumed to be part of one definition. Third, \FLORA programs can call
Prolog modules and vice versa. In this way, a large system can be built partly
in Prolog and partly in \FLORA.

We discuss each of the aforesaid modularization methods in turn.


\subsection{\FLORA Modules} \label{sec:flora-modules}

\index{module}
\index{module!name}
\index{module!contents}
%%
A \emph{\FLORA module} is a programming abstraction that allows a large
program to be split into separate libraries that can be reused in multiple
ways in the same program. Formally, a module is a pair that consists of a
\emph{name} and a \emph{contents}. The name is just an alphanumeric symbol
(the underscore, {\tt \_}, is also allowed), and the contents consists of
the program code that is typically loaded from some file (but it can also
be constructed dynamically by inserting facts
into another module).

The basic idea behind \FLORA modularization is that reusable code libraries
are to be placed in separate files.  To use a library, it must be
\emph{loaded into a module}. Other parts of the program can then invoke
this library's methods by providing the name of the module (and the
method/predicate names, of course).  There is no need to export anything
from a library --- any public method or predicate can be called by other
parts of the program.\footnote{
  %%
  {\bf Unimplemented}: At present, all methods are public, but
  encapsulation will be implemented in the future.
  %%
  }
%%
In this way, the library loaded into a module becomes that module's content.

Note that there is no a priori association between files and modules.  Any
file can be loaded into any module and one program file can even be loaded
into two different modules at the same time. The same module can be reused
during the same program run by loading another file into that module. In
this case, the old contents is erased and the module gets new contents from
the second file.

In \FLORA, modules are completely decoupled from file names. A \FLORA
program knows only the module names it needs to call, but not the file
names. Specific files can be loaded into modules by another, unrelated
bootstrapping program. Moreover, a program can be written in such a way
that it calls a method of some module without knowing that module's name.
The name of the module can be passed as a parameter or in some other way
and the concrete binding of the method to the module will be done at
runtime.

This dynamic nature of \FLORA modules stands in sharp contrast to the module
system of Prolog, which is static and associates modules with files at compile
time. Moreover, to call a predicate from another module, that predicate
must be imported explicitly and referred to by the same name.

\index{module!user}
\index{module!Prolog}
\index{module!system}
\index{user module}
\index{Prolog module}
\index{system module}
%%
As a pragmatic measure, \FLORA defines \emph{three kinds of modules} rather
than just one. The kind described above is actually just one of the three:
the \emph{user module}. As explained, these modules are decoupled from the
actual code, and so they can contain different code at different times.
The next kind is a \emph{Prolog module}. This is an abstraction in \FLORA,
which is used to call Prolog predicates. Prolog modules are static and are
assumed to be closely associated with their code. We describe these modules
in Section~\ref{sec-prolog-modules}. (Do not confuse \FLORA Prolog modules
--- an abstraction used in the language of \FLORA --- with Prolog modules,
which is an abstraction used in Prolog.)  The third type of modules are the
{\tt \FLORA system modules}. These modules are preloaded with \FLORA
programs that provide useful methods and predicates ({\it e.g.}, I/O) and,
thus, are also static. These modules are described in
Section~\ref{sec-flora-system-modules} and~\ref{sec-service-libs}. The
abstraction of system modules is a convenience provided by \FLORA, which
enables user programs to perform common actions using standard names of
predicates and methods implemented in those modules. The syntactic
conventions for calling each of these types of modules are similar, but
distinct.


\subsection{Calling Methods and Predicates Defined in User Modules}


\index{module!user!reference to}
%
If \emph{literal} is an F-molecule or a predicate defined in another
user module, it can be called using the following syntax:
%%
\begin{quote}
\emph{literal} @ \emph{module} 
\end{quote}
%%
The name of the module can be any alphanumeric symbol.\footnote{
  %%
  In fact, any symbol is allowed. However, it cannot contain the quote
  symbol, ``{\tt '}''.
  %%
  }
%%
For instance, \verb|foo(a) @ foomod| tests whether {\tt foo(a)} is true in
the user module named {\tt foomod}, and {\tt mary[children\mvd X]@genealogy}
queries the information on {\tt mary}'s children available in the module
{\tt genealogy}. More interestingly, the module specifier can be a variable
that gets bound to a module name at run time. For instance, 
%%
\begin{quote}
 {\tt
   ..., Agent=zagat, ..., newyork[dinner(italian) \mvd X]@Agent.
   }
\end{quote}
%%
A call to a literal with an unbound module specification or one that is not
bound to a symbol will result in a runtime error.

When calling the literals defined in the same module, the {\tt @{\it
    module}} notation is not needed, of course. (In fact, since a program
does not know where it will be loaded, using the @-notation to call a
literal in the same module is hard. However, it is possible with the help
of the special token \thismodule, which is described later, and is left
as an exercise.)

\index{module!rules for}
%%
The following rules apply when calling a literal defined in another module:
%%
\begin{enumerate}
\item Literal reference cannot appear in a rule head or be specified as
  a fact. For example, the following program will generate
  a parsing error
  %%
  \begin{quote}
    \verb|john[father->smith] @ foomod.| \\
    \verb|foo(X) @ foomod :- goo(X).|
  \end{quote}
  %%
  because defining a literal that belongs to another module does not make
  sense.
  
\item Module specification is distributive over logical connectives,
  including the conjunction operator, ``\verb|,|'', the disjunction,
  ``\verb|;|'', and the negation operators, ``\NAF'' and
  ``\verb|tnot|''. For example, the formula below:
  %%
  \begin{quote}
    \verb|(john[father->smith], tnot smith[spouse->mary]) @ foomod|
  \end{quote}
  is equivalent to the following formula:
  \begin{quote}
    \verb|john[father->smith] @ foomod, tnot (smith[spouse->mary] @ foomod)|
  \end{quote}

\item Module specifications can be nested. The one closest to a literal
  takes effect. For example,
  \begin{quote}
    \verb|(foo(a), goo(b) @ goomod, hoo(c)) @ foomod|
  \end{quote}
  is equivalent to
  \begin{quote}
    \verb|foo(a) @ foomod, goo(b) @ goomod, hoo(c) @ foomod|
  \end{quote}
  
\item The module specification propagates to any F-molecule appearing
  in the argument of a predicate for which the module is
  specified. For example,
  \begin{quote}
    \verb|foo(a.b[c->d]) @ foomod|
  \end{quote}
  %%
  is equivalent to
  %%
  \begin{quote}
    \verb|a[b->X] @ foomod, X[c->d] @ foomod, foo(X) @ foomod|
  \end{quote}
  
\item Module specifications do not affect function terms that are not
  predicates or method names, unless such a specification is explicitly
  attached to such a term. For instance, in
  %%
  \begin{quote}
    \verb|?- foo(goo(a)) @ foomod.|
  \end{quote}
  %%
  {\tt goo/1} refers to the same functor both in module {\tt foomod} and in
  the calling module. However, if the module is attached explicitly
  (see Section~\ref{sec-meta-reification}), as in
  \begin{quote}
    \verb|?- foo(${goo(a) @ goomod}) @ foomod.|
  \end{quote}
  %%$
  then {\tt foo/1} is assumed to be a meta-predicate that receives the
  predicate {\tt goo/1}  as a parameter.
\end{enumerate}


\subsection{Finding the Current Module Name}

\index{module!\thismodule}
\index{\thismodule}
%
Since a \FLORA program can be loaded into any module, the program does not
have a priori knowledge of the module it will be executing in. However, the
program can determine its module at runtime using the special token
\thismodule, which is replaced with the current module name when the module
is loaded. More precisely, if \thismodule occurs anywhere as an oid, method
name, value, etc., in file {\tt foo.flr} then when {\tt foo.flr} is loaded
into a module, say, {\tt bar}, then all such occurrences of \thismodule are
replaced with {\tt bar}. For instance,
%%
\begin{verbatim}
   a[b->_@].
   ?- a[b->X].

   X=main

   Yes
\end{verbatim}
%%



\subsection{Loading Files into User Modules}\label{sec-loading-mods}


\index{module!user!compilation of}
%%
\FLORA provides commands for compiling and loading program files into
specified user modules.
The
command 
%%
\begin{quote}
  {\tt ?- flCompile({\it file}>>{\it module}).}
\end{quote}
%%
generates the byte code for the program to be loaded into the user module
named {\tt module}. The name of the byte code for the program in
\emph{file}.flr, which can later be loaded into the specified module. In
practice this means that the compiler generates files named
\emph{file\_module.P} and \emph{file\_module.\ofile} with symbols appropriately
renamed to avoid clashes.

If no module is specified, the command
%%
\begin{quote}
 \tt
 ?- flCompile({\it file}).
\end{quote}
%%
compiles {\it file}.flr for the default module {\tt main}.


\index{loading files}
%
To load a file, the following command can be used:
%%
\begin{quote}
 \tt [myprog].  
\end{quote}
%%
This loads the program in the file {\tt myprog.flr} into the default user
module {\tt main}. If {\tt myprog.flr} is newer than the compiled code, the
source file is recompiled.

An optional module name can be used to load the program into a specified
module:
\begin{quote}
  \tt
[myprog >> foomod]
\end{quote}
%%
This loads the \FLORA program {\tt myprog.flr} into the user module named {\tt
  foomod}, compiling it if necessary.

Like Prolog, \FLORA lets the user to compile and load several program
files at the same time: If the file was not compiled before (or if the
program file is newer), the program is compiled before being loaded.  For
instance, the following command:
%%
\begin{quote}
\verb|[myprog1, myprog2]|
\end{quote}
%%
will loads both {\tt myprog1} and {\tt myprog2} into the default module
{\tt main}. However, loading several programs into the same module is not
very useful: the code of the last program will wipe out the code of the
previous ones. This is a general rule in \FLORA (and Prolog). Thus, loading
multiple files is always used in conjunction with the module targets:
%%
\begin{quote}
\verb|['myprog1.flr', myprog2 >> foomod].|
\end{quote}
which loads {\tt myprog1.flr} into the module {\tt main} and {\tt
  myprog2.flr} into the module {\tt foomod}.

Note that the {\tt [...]} command can also load and compile Prolog programs.
The overall algorithm is as follows. If the file suffix is specified
explicitly, the corresponding file is assumed to be a \FLORA file, a Prolog
file, or a byte code depending on the suffix: {\tt .flr}, {\tt .P}, or {\tt
  .\ofile}. If the suffix is not given explicitly, the compiler first checks if
{\it file}.{\tt flr} exists. If so, the file assumed to be a \FLORA program
and is compiled as such. If {\it file}.{\tt flr} is not found, but {\it
  file}.{\tt P} or {\it file}.{\tt O} is, the file is passed to Prolog for
compilation.


\index{module!{\tt flLoadedModule/1}}
\index{{\tt flLoadedModule/1}}
%%
Sometimes it is useful to know which user modules are loaded or if a
particular user module is loaded (say, because your might want to load it,
if not).  To find out which modules are loaded at the present time, use the
predicate {\tt flLoadedModule/1}. For instance, the first query,
below, succeeds if the module {\tt foo} is loaded. The second query
succeeds and binds {\tt L} to the list of all user modules that are loaded
at the present time.
%%
{\tt
\begin{quote}
  ?- flLoadedModule(foo).\\
  ?- findall(X,flLoadedModule(X),L).
\end{quote}
}
%%


\subsection{Calling Prolog from \FLORA}\label{sec-prolog-modules}

\index{Prolog module}
\index{module!Prolog}
%%
Prolog predicates can be called from \FLORA through the \FLORA module system
\FLORA models Prolog programs as collections of static {\em Prolog modules},
{\it i.e.}, from \FLORA's point of view, Prolog modules are always available
and do not need to be loaded explicitly because the association between Prolog
programs and modules is fixed.

\index{module!{\tt prolog()}}
\index{module!{\tt prolog(modulename)}}
%%\index{module!{\tt prolog modulename}}
\paragraph{@prolog().}
The syntax to call Prolog predicates is either one of the following:
%%
\begin{quote}
  \tt
  ?- {\it predicate}@prolog({\it module})  \\
  \tt
  ?- {\it predicate}@prolog {\it module}
\end{quote}
%%
For instance, since the predicate {\tt member/2} is defined in the Prolog
module {\tt basics}, we can call it as follows:
%%
\begin{quote}
 \tt
 ?- member(abc,[cde,abc,pqr])@prolog basics.
\end{quote}
%%
To use this mechanism, you must know which Prolog module the particular
predicate is defined in. Some predicates are defined by programs that do
not belong to any module. When such an Prolog program is loaded, the
corresponding predicates become available in the default Prolog module.  In
XSB, the default module is called {\tt usermod} and \FLORA can call such
predicates as follows:
%%
\begin{quote}
 \tt
 ?- foo(X)@prolog usermod.
\end{quote}
%%
Note that variables are not allowed in the module specifications of Prolog
predicates, {\it i.e.},
%%
\begin{quote}
 \tt
 ?- M=usermod, foo(X)@prolog(M).
\end{quote}
%%
will cause a compilation error.

Some Prolog predicates are considered ``well-known'' and, even though they
are defined in various obscure Prolog modules, the user can just use those
predicates without remembering the corresponding Prolog module names. These
predicates (that are listed in the XSB manual) can be called from \FLORA
with particular ease:
%%
\begin{quote}
 \tt
 ?- writeln('Hello')@prolog()
\end{quote}
%%
{\it i.e.}, we can simply omit the Prolog module name (but parentheses must be
preserved). 

\index{module!{\tt prologall()}}
\index{module!{\tt prologall(modulename)}}
\index{module!{\tt prologall modulename}}
\paragraph{@prologall().}
The Prolog module specification {\tt @prolog()} has one subtlety: it does
not affect the arguments of a call. For instance, 
%%
\begin{verbatim}
 ?- foo(f(X,b))@prolog().  
\end{verbatim}
%%
will call the Prolog predicate foo/1, but its argument, {\tt f(X,b)}, will
be considered as a HiLog term. If the fact {\tt foo(f(a,b))} 
was defined somewhere in the Prolog program then the above query will fail,
since a Prolog term {\tt f(X,b)} and a HiLog term {\tt f(X,b)} are
\emph{different} even though their textual representation in \FLORA is the
same.

A correct call to {\tt foo/1} in this case would be as follows:
%%
\begin{verbatim}
 ?- foo(f(X,b)@prolog())@prolog().
\end{verbatim}
%%
Clearly, this might be too much writing and is error prone. Moreover, as
explained in Section~\ref{sec-passing-args}, there also is a subtle issue of
passing arguments between Prolog and \FLORA.

To simplify calls to Prolog, \FLORA provides another, more powerful
primitive: {\tt @prologall()}. Thus, one can call
%%
\begin{verbatim}
 ?- foo(f(X,b))@prologall().  
\end{verbatim}
%%
without having to worry about the differences between the HiLog
representation of terms in \FLORA and the representation used in Prolog.

One might wonder why is there the {\tt @prolog()} module call in the first
place. The reason is efficiency. The {\tt @prologall()} call does automatic
conversion between Prolog and HiLog, which is not always necessary. For
instance, to check whether a term, {\tt f(a)}, is a member of a list,
{\tt [f(b),f(a)]}, one does not need to do any conversion, because the
answer is the same whether these terms are HiLog terms or Prolog
ones. Thus,
%%
\begin{verbatim}
 ?-  member(f(a), [f(b),f(a)])@prolog basics.
\end{verbatim}
%%
is perfectly acceptable and is more efficient than
%%
\begin{verbatim}
 ?-  member(f(a), [f(b),f(a)])@prologall basics.
\end{verbatim}
%%
\index{p2h\{...\}}
%%
\FLORA provides a special primitive, {\tt p2h\{...,...\}}, which converts terms to
and from the HiLog representation, and the programmer can use it in
conjunction with {\tt @prolog()} to achieve a greater degree of control
over argument conversion. This issue is further discussed in
Section~\ref{sec-passing-args}.



\subsection{Calling \FLORA from Prolog}\label{sec-flora-from-prolog}

Since Prolog does not understand \FLORA syntax, it can call only
predicates defined in \FLORA programs. To call predicates
defined in \FLORA programs, they must be imported by the Prolog program.

\paragraph{Importing \FLORA predicates into Prolog shell.}
To import a \FLORA predicate into Prolog shell, the following must be done:
%%
%%
\begin{itemize}
\item The query
%%
\begin{quote}
 ?- [flora2], bootstrap\_flora.  
\end{quote}
%%
must be executed first.
\item 
  One of the following {\tt flImport} queries must be executed in the shell:
  \begin{quote}
    \tt
    ?- flImport {\it flora-predicate/arity} as {\it
      xsb-name}(\_,\_,...,\_)\\
    \hspace*{5cm}from {\it filename} >> {\it flora-module-name}
    \\
    ?- flImport {\it flora-predicate/arity} as {\it 
      xsb-name}(\_,\_,...,\_)\\
    \hspace*{5cm}from {\it flora-module-name}
  \end{quote}
  %%
\end{itemize}
%%
We will explain shortly which {\tt flImport} query should be used in what
situation.

{\bf Note:} If \FLORA is installed outside of the XSB directory structure,
then you must let Prolog know the location of your distribution of \FLORA.
This is done by executing {\tt asserta(library\_directory(path-to-flora))}
{\it e.g.},
%%
\begin{verbatim}
 ?- asserta(library_directory('/home/me/flora2')).  
\end{verbatim}
%%
before calling any of the \FLORA modules. Observe that {\tt asserta} and
\emph{not} {\tt assert} must be used.

\paragraph{Calling \FLORA from Prolog module.}
To call \FLORA from within a Prolog program, say {\tt test.P}, the
  following must be done:
  %%
  \begin{enumerate}
  \item  The query 
    %%
    \begin{quote}
      {\tt ?- [flora2], bootstrap\_flora} 
    \end{quote}
    %%
    must be executed \emph{before compiling or loading} {\tt test.P} ---
    otherwise, the program will not compile or load.
  \item The directive
    %%
    \begin{quote}
      {\tt :- import (flImport)/1 from flora2.}    
    \end{quote}
    %%
    must appear near the top of {\tt test.P}, \emph{prior to any call} to
    \FLORA predicates.
  \end{enumerate}
  %%
  
  The first form for {\tt flImport} above is used to both import the
  predicate and also load the program file defining it into a given \FLORA
  user module. The second syntax is used when the flora program is already
  loaded into a module and we only need to import the corresponding
  predicate.
  
  The imported predicate must be given a name by which the imported
  predicate will be known in Prolog.  (This name can be the same as the
  name used in \FLORA.)  It is important, however, that the Prolog name be
  specified as shown, {\it i.e.}, as a predicate skeleton with the same
  number of arguments as in the \FLORA predicate. For instance, {\tt
    foo(\_,\_,\_)} will do, but {\tt foo/3} will not.

Once the predicate is imported, it can be used under its Prolog name as a
regular predicate.

Prolog programs can also load and compile \FLORA programs using the following
queries (again, bootstrap\_ {\tt flora} must be executed in advance): 
%%
\begin{quote}
 \tt
 :- import (flLoad)/1, (flCompile)/1 from flora2.\\
 ?- flLoad  {\it flora-file} >> {\it flora-module}.\\
 ?- flLoad  {\it flora-file}\\
 ?- flCompile {\it flora-file} >> {\it flora-module}.\\
 ?- flCompile  {\it flora-file}
\end{quote}
%%
The first query loads the file {\it flora-file\/} into the given user
module and compiles it, if necessary. The second query loads the program
into the default module {\tt main}. The last two queries compile the file
for loading into the module {\it flora-module} and {\tt main},
respectively, but do not load it.

Finally, a Prolog program can check if a certain \FLORA user module has been
loaded using the following call:
%%
\begin{quote}
 \tt
 :- import flLoadedModule/1 from flora2.\\
 ?- flLoadedModule({\it flora-module-name}).
\end{quote}
%%

{\bf Note:} If you use a release of \FLORA that is installed
outside of the XSB directory tree, you must make sure that Prolog will find
this installation and use it in preference to the \FLORA package that is
located in your XSB distribution. One way of doing this was described
earlier (by executing an appropriate {\tt asserta/1}). This method works
best if your application consists of both \FLORA and Prolog modules, but
the initial module of your application ({\it i.e.}, the one that bootstraps
everything) is a Prolog program.  If the initial module is a \FLORA
program, then the best way is to start XSB and \FLORA using the {\tt
  runflora} script (page~\pageref{runflora-page}) located inside your
interim distribution of \FLORA.

\paragraph{Passing parameters between Prolog and \FLORA modules.}
In an application that has both Prolog and \FLORA modules, parameter
passing between modules plays an important role. We already discussed this
issue in the context of calls from \FLORA to Prolog. The same applies to
calls in the opposite direction. When calling a \FLORA module, it might be
necessary to convert arguments represented as Prolog terms into HiLog and
vice versa. For instance, if {\tt p/2} is a predicate imported from \FLORA,
which uses the first argument as input and returns the result in the second
argument, then one might need to use the following calling sequence:
%%
\begin{verbatim}
 ... :- ..., p2h{In,InHilog}, p(InHilog,OutHilog), p2h{Out,OutHilog}, ...
\end{verbatim}
%%
Here we assume that the Prolog module that calls the \FLORA predicate {\tt
  p/1} passes the input through the variable {\tt In}and gets the result in
the variable {\tt Out}.


\subsection{\FLORA System Modules}\label{sec-flora-system-modules}

\index{system module}
\index{module!system}
\index{module!{\tt flora(modulename)}}
%%
\FLORA provides a special set of modules that are \emph{preloaded} with
useful utilities, such as prettyprinting or I/O. These modules have special
syntax, {\tt @flora(modname)}, and cannot be loaded by the user. For this
reason, these modules are called \emph{\FLORA system modules}.  For
instance, to prettyprint all the attributes and methods of an object, the
following method, defined in the system module {\tt pp}, can be used:
%%
\begin{quote}
 \tt   ?- obj[\#pp\_self(foo)]@flora(pp).
\end{quote}
%%
Here, the method {\tt \#pp\_self} is applied to the object {\tt obj}.
Since {\tt obj} can have completely different methods in different user
modules, we have to tell the prettyprinting method in which module to look.
For more details on the existing \FLORA system modules, see
Section~\ref{sec-service-libs}.


\subsection{Including Files into \FLORA Programs}

The last and the simplest way to construct multi-file \FLORA 
programs is by using the {\tt \#include} preprocessing directive.
For instance if file {\tt foo.flr} contains the following instructions:
%%
\begin{quote}
  \#include file1 \\
  \#include file2\\
  \#include file3
\end{quote}
%%
the effect is the same as if the above three files were concatenated
together and stored in {\tt foo.flr}.
Note, however, that when compiling {\tt foo.flr}, the compiler has no way
of knowing if any of the included files have changed, because file
inclusion is done by the preprocessor. So, it is recommended to compile
such multi-file programs using a Makefile, like in C and C++.

\subsection{More on Variables as Module Specifications}

Earlier we mentioned that a user module specification can be a variable,
{\it e.g.}, {\tt a[m->b]@X}, which ranges over module names. This variable
does not need to be bound to a concrete module name before the call is
made.  If it is a variable, then {\tt X} will get successively bound to the
user modules where {\tt a[m->b]} is true.  However, these bindings will not
include {\tt prolog()}, {\tt prolog(module)}, or {\tt flora(module)}.

Dynamic module bindings can be used to implement \emph{adaptive methods},
which are used in  many types of applications, {\it e.g.}, agent
programming. Consider the following example:
%%
  \begin{center}
    {\tt
    \begin{tabular}{l l}
      Module {\tt foo}  & Module {\tt moo} \\
      \hline
      something :- ... & ......\\
      something\_else :- & ......\\
      \hspace*{1.5cm}a[someservice(\thismodule,Arg)->Res]@moo ~~& ......\\
      ...... & a[someservice(Module,Arg)-> Res] :- \\
      ...... & \hspace*{2.2cm} something@Module, ...\\
      ...... & ......
      
    \end{tabular}
    }
  \end{center}
  %%
  
  Here the method {\tt someservice} in user module {\tt moo} performs
  different operation depending on who is calling it, because {\tt
    something} can be defined differently for different callers.  When {\tt
    something\_else} is called, it invokes the method {\tt someservice} on
  object {\tt a} in module {\tt moo}. The current module name ({\tt foo})
  is passes as a parameter. When {\tt someservice} is executed in module
  {\tt moo} it calls the predicate {\tt something} in module {\tt foo}.
  
  This schema is, for instance, how the pretty printing system module of
  \FLORA works. A pretty-printing method is called on an object in some
  user module, and to do its job the pretty-printing method needs to query
  the object \emph{in the context of the calling module} to find the
  methods the object has.

It is also possible to view adaptive methods as a declarative counterpart
of the callback functions in C/C++, which allows the callee to behave
differently for different clients.


\section{Path Expressions}\label{sec-pathexpr}

\subsection{Path Expressions in the Rule Body}


\index{path expression} \index{path expression!in rule body}
%%
In addition to the basic \fl syntax, the \FLORA  system also supports
\emph{path expressions} to simplify object navigation along
single-valued and multi-valued method applications, and to avoid
explicit join conditions \cite{frohn-lausen-uphoff-VLDB-94}.  The
basic idea is to allow the following \emph{path expressions} wherever
Id-terms are allowed:
%%

  \medskip

\begin{enumerate} 
\item[7.]\label{eq-path-fun} ~~ {\tt O.M}
\item[8.]\label{eq-path-set} ~~ {\tt O..M} 
\end{enumerate} \medskip

\noindent
The path expression in (7) is \emph{single-valued}; it refers to the unique
object $\tt R_0$ for which $\tt O[M\fd R_0]$ holds; (8) is a
\emph{multi-valued} path expression; it refers to each $R_i$ for which $\tt
O[M\mvd\{R_i\}]$ holds.  The symbols $\tt O$ and $\tt M$ stand for an
Id-term or path a expression.  Moreover, $\tt M$ can be a method that takes
arguments, in which case $\tt O.M(P_1,\dots,P_k)$ and $\tt
O..M(P_1,\dots,P_k)$ are a valid path expressions.
  
In order to disambiguate the syntax and to specify the desired order of
method applications, parentheses can be used. By default, path expressions
associate to the left, so $\tt a.b.c$ is equivalent to $\tt (a.b).c$, which
specifies the object $\tt o$ such that $\tt a[b\fd x] \land x[c\fd o]$
holds (note that $\tt x=a.b$). In contrast, $\tt a.(b.c)$ is the object
$\tt o1$ such that $b[c\fd x1] \land a[x1\fd o1]$ holds (note that in this
case, $\tt x1=b.c$). In general, $o$ and $o1$ can be different objects.
Note also that in $\tt (a.b).c$, $\tt b$ is a method name, whereas in $\tt
a.(b.c)$ it is used as an object name and {\tt b.c} as a method.  Observe
that function symbols can also be applied to path expressions, since path
expressions, like Id-terms, represent objects. Thus, $\tt f(a.b)$
is a valid expression.

{\bf Note}: A path expression can appear wherever an oid can, but not in
place of a truth-valued expression ({\it e.g.}, a subquery) even though
path expressions can be viewed as formulas. Thus,
%%
\begin{qrules}
\tt ?- P..authors.
\end{qrules}
%%
is illegal and will cause a compiler error. To use a path expression as a
query, square brackets must be attached. For instance, the following are
legal queries:
%%
\begin{qrules}
   \tt ?- P..authors[]. \\
   \tt ?- P..authors[name->N].
\end{qrules}

As path expressions and F-molecules can be arbitrarily nested, this leads
to a concise and flexible specification language for object properties, as
illustrated in the following example.

\begin{example}[Path Expressions]\label{Ex:PathExpr}
  \rm Consider again the schema given in Figure~\ref{fig-flogic-model}.  If
  $n$ is the name of a person, the following path expression is a query
  that returns all editors of conferences in which $n$ had a paper:
  %%
  \begin{qrules}
    ?- P\isa conf\_p[authors\mvd\{\anon [name\fd $n$]\}].at\_conf..editors[].
  \end{qrules}
  %%
  Likewise, the answer to the query
  %%
  \begin{qrules}
    ?- P\isa conf\_p[authors\mvd\{\anon [name\fd
    $n$]\}].at\_conf[editors\mvd\{E\}].
  \end{qrules}
  %%
  is the set of all pairs (\textsf{P},\textsf{E}) such that \textsf{P} is
  (the logical oid of) a paper written by $n$, and \textsf{E} is the
  corresponding proceedings editor.  If we also want to see the
  affiliations of the above editors, we only need to modify our query
  slightly:
  %%
  \begin{qrules}
    ?- P\isa conf\_p[authors\mvd\{\anon [name\fd
    $n$]\}].at\_conf[year\fd Y]..editors[affil(Y)\fd A].
  \end{qrules}
\end{example}
%%
Thus, \FLORA path expressions support navigation 
along the method application dimension using the operators
``.''  and
``..''. In addition, intermediate objects through which such navigation
takes place can be selected by specifying the properties of such objects
inside square brackets.\footnote{
  %%
  A similar feature is used in other languages, e.g., XSQL \cite{xsql-92}.
  %%
  }
%%

\index{method!self}
To access intermediate objects that arise implicitly in the middle
of a path expression, one can define the method \textsf{self} as
%%
\begin{quote}
  {\tt X[self{\fd}X].} 
\end{quote}
%%
and then simply write $\dots${\tt [self{\fd}O]}$\dots$ anywhere in a
complex path expression. This would bind the Id of the current object to
the variable {\tt O}.

\begin{example}[Path Expressions with \textsf{self}]\label{ex-path-self}
  \rm{
    %%
    To illustrate convenience afforded by the use of the {\tt self}
    attribute in path expressions, consider the second query in
    Example~\ref{Ex:PathExpr}. If, in addition, we want to obtain the names
    of the conferences where the respective papers were published, that
    query can be reformulated as follows:
    %%
    }
  \begin{qrules}
    X[self\fd X].\\
    ?- P\isa conf\_p[authors\mvd\anon [name\fd
    $n$]].at\_conf[self\fd C, year\fd Y]..editors[affil(Y)\fd A]. 
  \end{qrules}
\end{example}


\subsection{Path Expressions in the Rule Head}\label{sec-pathexp-head}


Only single-valued path expressions are allowed in a rule head. Set-valued
path expressions are not allowed because the semantics is not always clear
in such cases.

\index{path expression!in rule head}
The following is an example of a path expression in rule head. For any
person X, this rule defines the grandchildren for X's mother.
\begin{qrules}
X.mother[grandson{\mvd}Y] :- X{\isa}person[son{\mvd}Y].
\end{qrules}
%%
Here X's mother is treated as an unknown object. Should this object become
known in the future, complications may arise. For instance, suppose that
later on the following facts were added or derived:
%%
\begin{qrules}
  john[mother{\fd}mary]. \\
  john[son{\mvd}david].
\end{qrules}

Because John's mother is now identified as {\tt mary}, it follows that
${\tt mary}$ and ${\tt john.mother}$ represent the same things, since the
attribute {\tt mother} is scalar. To deal with single-valued path
expressions in rule heads, \FLORA \emph{skolemizes} ${\tt john.mother}$ and
adds the requisite equalities to record that the Skolem term that
corresponds to {\tt john.mother} equals {\tt mary}.  All this is done by
the \FLORA compiler transparently to the user: if a path expression in rule
head is detected, \FLORA replaces this expression with a Skolem function.
The problem here is that maintenance of such equalities is costly
(sometimes causing a slowdown by the factor of 2--10 times). Since the user
often knows that equations of the above kind will never be derived, \FLORA
leaves it to the user to tell the compiler whether equality maintenance is
needed.  Equality maintenance is discussed in Section~\ref{sec-eqmaintain}.


\section{Truth Values and Object Values}
\label{sec-references}


Id-terms, \fl atoms, and path expressions can all be used as objects. This
is obvious for Id-terms and the object interpretation of path expressions
of the form (7) and (8) on page~\pageref{eq-path-fun} was discussed
earlier. The \fl atoms (1) through (6) on pages~\pageref{eq-scalar-atom}
through~\pageref{eq-subclass} are typically viewed as formulas and, thus,
they are assumed to have a truth value only.  However, there also is a
natural way to give them object interpretation.  For example, {\tt
  o{\isa}c[m{\fd}r]} has object value {\tt o} and some truth value.
However, unlike the object value, the truth value depends on the database
(on whether {\tt o} belongs to class {\tt c} in the database and whether
the value of the attribute {\tt m} is, indeed, {\tt r}.

Although previously we discussed only the object interpretation for path
expressions, it is easy to see that they have truth values as well, because
a path expression corresponds to a conjunction of F-logic atoms.
Consequently, all F-molecules of the form (1) through (8) have dual
reading: As logical formulas (\emph{the deductive perspective}), and as
expressions that represent one or more objects (\emph{the object-oriented
  perspective}).  Given an intended model, \db I, of an \fl program an
expression has:
%%
\begin{itemize}
  \index{molecule!object value}
\item An \emph{object value}, which yields the Id(s) of the object(s)
  that are reachable in \db I by the corresponding expression, and 
  \index{molecule!truth value}
\item A \emph{truth value}, like any other literal or molecule of the
  language. 
\end{itemize}
%%
An important property that relates the above interpretations is: a
molecule, $r$, evaluates to \emph{false} if \db I has no object
corresponding to $r$.


Consider the following path expression and an equivalent, decomposed
expression:

\begin{equation}\label{eq-decomp}
\tt
a..b[c\mvd\{d.e\}] \quad\ \Leftrightarrow \quad\  a[b\mvd X_{ab}]
\land d[e\fd X_{de}] \land X_{ab}[c\mvd X_{de}]. 
\end{equation}

\noindent
Such decomposition is used to determine the truth value of arbitrarily complex
path expressions in the \emph{body} of a rule.  Let $\tt \obj(path)$ denote
the Ids of all objects represented by the path expression. Then, for
(\ref{eq-decomp}) above, we have:

\begin{displaymath} \tt
\obj(a..b) = \{x_{ab} \mid \db I \models a[b\mvd x_{ab} ]\}
\qquad\textrm{ and }\qquad \obj(d.e) = \{x_{de} \mid \db I \models d[e\fd 
x_{de}]\} 
\end{displaymath}
%
where $\db I \models \varphi$ means that $\varphi$ holds in \db I.  Observe
two formulas can be equivalent, but their object values might be different.
For instance, $\tt d[e\fd f]$ is equivalent to {\tt d.e} as a formula.
However, $\tt \obj(d.e)$ is $f$, while $\tt \obj(d[e\fd f])$ is {\tt d}.

In general, for an \fl\ database \db I, the object values of ground path
expressions are given by the following mapping, \obj, from ground molecules
to sets of ground oids ($t$, $o$, $c$, $d$, $m$ can be oids or path
expressions):
%
\begin{displaymath}
  \begin{array}{cll@{\hspace{4em}}c}
    \obj(t) & := & \{t \mid  \db I\models t[] \}, 
     \textrm{ for a ground Id-term $t$}  \\   
                                %
    \obj(o[\dots]) & := & \{o1 \mid o1\in\obj(o), \db I \models o1[\dots]
    \} \\  
                                %
    \obj(o\isa c) & := & \{o1 \mid o1\in\obj(o), \db I \models o1\isa c\}
     \\ 
                                %
    \obj(c\subcl d) & := & \{c1 \mid c1\in\obj(c), \db I \models c1\subcl
    d\} \\ 
                                %
    \obj(o.m) & :=  & \{r1 \mid r1\in\obj(r), \db I \models o[m\fd
    r]\} \\ 
                                %
    \obj(o..m) & := &  \{r1 \mid  r1\in\obj(r), \db I \models
    o[m{\mvd}\{r\}] \}
  \end{array}
\end{displaymath}

Observe that if $\tt t[]$ does not occur in \db{I}, then $\obj(t)$ is
$\emptyset$.  Conversely, a ground molecule $r$ is called \emph{active} if
$\obj(r)$ is not empty. A molecule, $r$, can be 
single-valued or multi-valued:
%%
\begin{itemize}
\item $r$ is called \emph{multi-valued} if
 \begin{itemize}
  \item it has the form $o..m$, or 
  \item it has one of the forms $\underline{o}[\dots]$,
    $\underline{o}\isa c$, $\underline{c}\subcl d$, or
    $\underline{o}.\underline{m}$, and any of the underlined
    subexpressions is multi-valued;
 \end{itemize}
\item in all other cases, $r$ is \emph{single-valued}.
\end{itemize}

\paragraph{Dual representation and meta-predicates.}
Since path expressions can appear wherever Id-terms are allowed, the
question arises whether a path expression is intended to indicate a truth
value or an object value. For instance, we may want to call the Prolog
aggregate predicate {\tt findall/3} to retrieve the oids of the managers
who like to play tennis:
%%
\begin{qrules}
findall(P,P{\isa}manager[hobbies{\mvd}tennis],L)
\end{qrules}
%%
If all arguments are treated as objects, then this expression would mean
%%
\begin{quote}
 \tt
 P{\isa}manager[hobbies{\mvd}tennis], findall(P,P,L)
\end{quote}
%%
and a meaningless result --- the list of all instances of {\tt P} that
evaluate to true --- will be returned. Since, due to the first F-molecule,
these instances of {\tt P} must be the oids of the tennis-playing managers,
such as {\tt john}, the list {\tt L} would contain those oids that happen
to be true as 0-ary facts. (For example, {\tt john} would end up on such a
list if the fact {\tt john} is true as a 0-ary predicate).

The upshot of this problem is that the interpretation of \fl expressions as
objects is not always suitable. In our example, we need to indicate to the
compiler that the middle argument of {\tt findall/3} ought to be translated
into Prolog as follows:
%%
\begin{quote}
 \tt
 findall(P,F(P),L)
\end{quote}
%%
where {\tt F(P)} is an formula into which {\tt
  P{\isa}manager[hobbies{\mvd}tennis]} is compiled by the \FLORA
compiler.\footnote{
  %%
  Something like {\tt isa(P,manager),mvd(P,hobbies,tennis)}.
  %%
  }
%%
\index{reification}
Under this translation, findall/3 will find all instances of {\tt
  P} that make {\tt F(P)} true and return a list of such instances in the
list {\tt L}. This is accomplished using the \emph{reification} feature of
\FLORA: a formula is compiled into an object that represents \emph{it} if
the formula is wrapped with the \$\{...\} construct as, {\it e.g.}, in
%%
\begin{alltt}
 findall(P,\$\{P{\isa}manager[hobbies{\mvd}tennis]\},L)
\end{alltt}
%%
Reification is further discussed in Section~\ref{sec-meta-reification}.


\section{HiLog and Related Issues} \label{sec:hilog}


\index{HiLog}
%
HiLog \cite{hilog-jlp} is the default syntax that \FLORA uses to represent
functor terms (including object Ids) and predicates.  In HiLog, complex
terms can appear wherever a function symbol is allowed. For example, {\tt
  group(X)(Y,Z)} is a HiLog term where the functor is no longer a symbol
but rather a complex term {\tt group(X)}. Variables in HiLog can range over
terms, predicate and function symbols, and even over atomic formulas. For
instance,
%%
{\tt
\begin{qrules}
 ?- p(X), X(p).
\end{qrules}
}
%%
\noindent
and
%%
{\tt
\begin{qrules}\label{eq-hilog-notallowed}
 ?- p(X), X(p), X.  
\end{qrules}
}
%%
\noindent
are perfectly legal queries. If {\tt p(a(b))}, {\tt a(b)(p)},
and {\tt a(b)} are all true in the database, then $X=a$ is one of the
answers to the query.

\index{HiLog!translation}
%
Although HiLog has a higher order syntax, its semantics is first order
\cite{hilog-jlp}. Any HiLog term can be consistently translated into a
Prolog term. For instance, {\tt group(X)(Y,Z)} can be represented by the
Prolog term {\tt apply(apply(group,X),Y,Z)}. The translation scheme is
pretty straightforward and is described in \cite{hilog-jlp}.

Any Id-term in \FLORA, including function symbols and predicate symbols,
are considered to be HiLog terms and therefore are subject to translation.
That is, even a normal Prolog term will by default be represented using the
HiLog translation, e.g., {\tt foo(a)} will be represented as {\tt
  apply(foo,a)}. This guarantees that HiLog unification will work correctly
at runtime. For instance, {\tt foo(a)} will unify with {\tt F(a)} and bind
the variable {\tt F} to {\tt foo}.

There is one important difference between HiLog, as described in
\cite{hilog-jlp}, and its implementation in \FLORA. In HiLog, functor terms
that appear as arguments to predicates and the atomic formulas ({\it i.e.},
predicates that are applied to some arguments) belong to the same domain. 
In contrast, in \FLORA they are in different domains.\footnote{
  %%
  This is allowed in \emph{sorted HiLog} \cite{hilog-icdt-95}. 
  %%
  }
%%
For instance, (\ref{eq-hilog-notallowed}) will cause an error because {\tt
  X} is bound to the \emph{term} {\tt a(b)}, which is different from the
atomic formula {\tt a(b)}, and thus has no truth value. In fact, since
terms are not associated with any \FLORA module, it is not clear what $\tt
X(p)$ should mean when $\tt X$ is bound to a \emph{term} $\tt a(b)$ ({\it
  e.g.}, in what module should $\tt a(b)(p)$ be called).  However,
the following query would work correctly:
%%
\begin{verbatim}
  ?- p(X),X(p),X@foo.
\end{verbatim}
%%
if we need to call {\tt X} in module {\tt foo}. If we need to call it in
the current module, then we could use the following:
%%
\begin{verbatim}
  ?- p(X),X(p),X@ _@.  
\end{verbatim}
%%



\index{HiLog!unification}
%
Like in classical logic, {\tt foo} and {\tt foo()} are different terms.
However, in programming, it is convenient to identify these terms when they
are treated as predicates. Prologs often disallow the use of the {\tt
  foo()} syntax altogether.  The same distinction holds in HiLog: {\tt
  foo}, {\tt foo()} and {\tt foo()()} are all different. In terms of the
HiLog to Prolog translation, this means that {\tt foo} is different from
{\tt apply(foo)} is different from {\tt apply(apply(foo))}.  However, just
like in Prolog, we treat {\tt p} as syntactic sugar for {\tt p()} when both
occur as predicates. Thus, the following queries are the same:
%%
{\tt
\begin{quote}
   ?- p.\\
   ?- p().
\end{quote}
}
%%
\noindent
In the following program,
%%
{\tt
\begin{quote}
 p. \\
 q().\\
 ?- p(), X().\\
 ?- q, X().\\
 ?- r = r().
\end{quote}
}
%%
\noindent
the first two queries will succeed (with {\tt X} bound to {\tt p} or {\tt
  q}), but the last one will fail.  Identification of {\tt p} with {\tt
  p()} does not extend to {\tt p()()}, which is distinct from both {\tt p}
and {\tt p()} not only as a term but also as a formula. Thus, in the following
program, all queries fail:
%%
{\tt
\begin{quote}
 p.\\
 q().\\
 ?- p()().\\
 ?- q()().\\
 ?- p = p()().\\
 ?- q() = q()().
\end{quote}
}
%%


\subsection{Meta-programming, Meta-unification, and Reification}
\label{sec-meta-reification}


\index{meta-programming}
%
\fl together with HiLog is powerful stuff. In particular, it lends itself
naturally to meta-programming. For instance, it is easy to examine the
methods and types defined for the various classes.  Here are some simple
examples:
%%
\begin{quote}
\begin{verbatim}
// all unary scalar methods defined for John
?- john[M(_) -> _].

// all unary scalar methods that apply to John,
// for which a signature was declared
?- john[M(_) => _].

// all method signatures that apply to John,
// which are either declared explicitly or inherited
?- john[M => _].

// all method invocations defined for John
?- john[M -> _].
\end{verbatim}
\end{quote}
%%

However, a number of meta-programming primitives are still needed
since they cannot be directly expressed in \fl. Many such features are
provided by the underlying Prolog system and \FLORA simply takes advantage of
them: 
%%
\begin{quote}
\begin{verbatim}
?- functor(X,f,3).
X = f(_h455,_h456,_h457)
Yes

?- compound(f(X)).
X = _h472
Yes

?- X =.. [f,a,b].
X = f(a,b)
Yes
\end{verbatim}
\end{quote}
%%
Note that these primitives are used for Prolog terms only and
are described in the XSB manual.

\paragraph{Meta-unification.}
\index{meta-unification operator $\sim$}
\index{$\sim$!meta-unification operator}
%%
In \FLORA, variables can be bound to both formulas and terms. For instance,
in {\tt X = p(a)}, {\tt p(a)} is viewed as a term and {\tt X} is bound to
it. Likewise, in {\tt X = a[m->v]}, the F-molecule is evaluated to its
object value and then unified with {\tt X}. To bind variables to formulas
instead, \FLORA provides a {\tt meta-unification} operator, $\sim$.  This
operator treats its arguments as formulas and unifies them as such. For
instance, {\tt X $\sim$ a[m->v,k->V]} binds {\tt X} to the F-molecule {\tt
  a[m->v,k->V]} and {\tt a[m->v,k->V] $\sim$ X[M->v,k->p]} unifies the two
molecules by binding {\tt X} to {\tt a}, {\tt M} to {\tt m}, and {\tt V} to
{\tt p}.

Meta-unification is very useful when it is necessary to find out the module
in which a particular formula lives. For instance,
%%
\begin{verbatim}
 ?- X ~ a[b->c]@foo, X ~ Y@M.  
\end{verbatim}
%%
would bind {\tt Y} to {\tt X} and {\tt M} to the module of {\tt X}. Note that
in meta-unification the variable {\tt Y} in the idiom \verb|Y@M| or
\verb|Y@foo| is viewed as a meta-variable that is bound to a
formula. Thus, in the above, {\tt Y} is bound to {\tt X}. More subtle
examples are
%%
\begin{verbatim}
  ?- X ~ f(a)@foo, X ~ Y@M.  
  ?- f(a)@foo ~ Y@M.
\end{verbatim}
%%
In both cases {\tt M} is bound to {\tt foo} and {\tt Y} is bound to the
(internal representation of the) HiLog formula {\tt f(a)@foo} ---
\emph{not} to the HiLog term {\tt f(a)}!

Another subtlety has to do with the scope of the module specification.
In \FLORA, module specifications have scope and inner specifications
override the outer ones. For instance, in
%%
\begin{verbatim}
  ..., (abc@foo, cde)@bar, ...
\end{verbatim}
%%
the term {\tt abc} is in module {\tt foo}, while {\tt cde} in module {\tt
bar}. This is because the inner module specification, {\tt @foo}, overrides
the outer specification {\tt @bar} for the literal in which it occurs ({\it
i.e.}, {\tt abc}). These scoping rules have subtle impact on literals that
are computed dynamically at run time. For instance, consider
%%
\begin{verbatim}
  ?- X ~ a[b->c]@foo, X@bar.  
\end{verbatim}
%%
Because {\tt X} gets bound to {\tt a[b->c]@foo}, the literal {\tt X@bar}
becomes the same as  {\tt (a[b->c]@foo)@bar}, {\it i.e.}, {\tt a[b->c]@foo}.
Thus, both of the following queries succeed:
%%
\begin{verbatim}
  ?- X ~ a[b->c]@foo, X@bar ~ a[b->c]@foo.
  ?- X ~ a[b->c]@foo, X@M ~ a[b->c]@foo.
\end{verbatim}
%%
Moreover, in the second query, the variable {\tt M} is \emph{not} bound to
anything because, as noted before, the literal {\tt X@M} becomes
{\tt (a[b->c]@foo)@M)} at run time and, due to the scoping rules, is the
same as {\tt a[b->c]@foo}.

\paragraph{Reification.}
\index{reification operator \$\{...\}}
\index{\$\{...\}!reification operator}
%%
It is sometimes useful to be able to treat \FLORA molecules and predicates
as objects. For instance, consider the following statement:
%%
\begin{verbatim}
 tom[believes->> alice[thinks->>floraProgramming:coolThing]].
\end{verbatim}
%%
The intended meaning here is that one of Tom's beliefs is that Alice
thinks that programming in \FLORA is a cool thing. Unfortunately, this is
incorrect, because, as stated, the above formula has a different meaning:
%%
\begin{verbatim}
 tom[believes->> alice].
 alice[thinks->>floraProgramming:coolThing].  
\end{verbatim}
%%
That is, Tom believes in Alice and Alice thinks that FLORA programming is
cool. This is different from what we originally intended. For instance, we
did not want to say that Alice likes FLORA (she probably does, but she did
not tell us). All we said was what Tom believes about what Alice thinks. In
other words, to achieve the desired effect we must turn the formula {\tt
  alice[thinks->>floraProgramming:coolThing]} into an object, {\it i.e.},
\emph{reify} it.

Reification is done using the operator ``\$\{...\}''. For instance, to
say that Tom believes that Alice thinks that programming in \FLORA is a
cool thing one should write:
%%
\begin{verbatim}
 tom[believes->> ${alice[thinks->>floraProgramming:coolThing]}].
\end{verbatim}
%%$

The semantics of reification in \FLORA is described in
\cite{reification-odbase-02}.

\paragraph{Reification and meta-unification.}
Reification should not be confused with meta-unification, although they are
close concepts. A reified formula reflects the exact structure that is used
to encode it, so structurally similar, but syntactically different formulas
might meta-unify, but their internal representations could be very different.
For instance, 
%%
\begin{verbatim}
 ?- M=foo, a[b->X]@M ~ Y[b->d]@foo.
\end{verbatim}
%%
will return \emph{true}, because the two molecules are structurally similar
and thus meta-unify. On the other hand,
%%
\begin{verbatim}
 ?- M=foo, ${a[b->X]@M} = ${Y[b->d]@foo}.
\end{verbatim}
%%
will be false, because {\tt a[b->Y]@X} and {\tt Z[b->d]@foo} have different
internal representations (even though their conceptual structures are
similar), so they do not unify (using ``='', {\it i.e.}, in the usual
first-order sense). Note, however, that
%%
\begin{verbatim}
 ?- ${a[b->Y]@foo} = ${Z[b->d]@foo}.
 ?- M=foo, ${a[b->Y]@M} = ${Z[b->d]@M}.
 ?- a[b->Y]@foo ~ Z[b->d]@foo.
 ?- M=foo, a[b->Y]@M ~ Z[b->d]@M.
\end{verbatim}
%%
will all return \emph{true}, because {\tt a[b->Y]@foo} and {\tt
  Z[b->d]@foo} are structurally similar --- both conceptually and as far as
  their
internal encoding is concerned (and likewise are {\tt a[b->Y]@foo} and {\tt
  Z[b->d]@foo}).


{\bf Unimplemented}: Meta-programming support for HiLog terms and
F-molecules is incomplete. For instance, there is no operator similar to
{\tt =..}, like in Prolog (or, rather, it does not do the right thing in
\FLORA). Additional meta-programming support will be provided through
future enhancements.


\subsection{Passing Arguments between \FLORA and Prolog}\label{sec-passing-args}

The native HiLog support in \FLORA causes some tension when crossing the
border from one system to another. The reason is that \FLORA terms and Prolog
terms have different internal representation. Even though XSB supports
HiLog (according to the manual, anyway), this support is incomplete and is
not integrated well into the system --- most notably into the XSB module
system. As a result, XSB does not recognize terms passed to it from \FLORA
as HiLog terms and, thus, many useful primitives will not work correctly.
(Try {\tt ?- writeln(foo(abc))@prolog()} and see what happens.)

\index{p2h\{...\}}
\index{Prolog to HiLog conversion}
\index{HiLog to Prolog conversion}
%%
To cope with the problem, \FLORA provides a primitive, {\tt
  p2h\{Plg,Hlg\}}, which does the translation. If the first argument, {\tt
  Plg}, is bound, the primitive binds the second argument to the Hilog
representation of the term. If {\tt Plg} is already bound to a Hilog term,
then {\tt Hlg} is bound to the same term without conversion.  Similarly, if
{\tt Hlg} is bound to a HiLog term, then {\tt Plg} gets bound to the Prolog
representation of that term. If {\tt Hlg} is bound to a non-HiLog term,
then {\tt Plg} gets bound to the same term without conversion. In all these
cases, the call to {\tt p2h\{...\}} succeeds. If {\tt both} arguments are
bound, then the call succeeds if and only if
%%
\begin{itemize}
\item {\tt Plg} is a Prolog term and {\tt Hlg} is its HiLog
  representation.
\item Both {\tt Plg} and {\tt Hlg} are identical Prolog terms.
\end{itemize}
%%
Note that if both {\tt Plg} and {\tt Hlg} are bound to the same
\emph{HiLog term} then the predicate \emph{fails}. Thus, if you type the
following queries into the \FLORA shell, they both succeed:
%%
\begin{verbatim}
  ?- p2h{X,f(a)}, p2h{X,X}.
\end{verbatim}
%%
but the following will fail:
%%
\begin{verbatim}
  ?- p2h{f(a),X}, p2h{X,X}.
  ?- p2h{f(a),f(a)}.
\end{verbatim}
%%
The first query succeeds because {\tt X}  is bound to a prolog term, and by the
above rules {\tt p2h\{X,X\}} is supposed to succeed. The second query fails
because {\tt X} is bound to a HiLog term and, again by the above rules,
{\tt p2h\{X,X\}} is supposed to fail.
The reason why the last query fails is less obvious.
In that query, both occurrences of {\tt f(a)} are HiLog terms, as are all
terms that appear in a \FLORA program (unless they are marked with {\tt
  @prolog} or {\tt @prologall()} module designations). Therefore, again by
the rules above the query should fail.

One should not try to convert certain Prolog terms to
HiLog and expect them to be the same as similarly looking \FLORA terms. In
particular, this applies to reified statements. For instance, if {\tt X =
\${a[b->c]}} then {\tt ?- p2h\{X,Y\}, Y = \${a[b->c]}} is not expected to
succeed. This is because {\tt p2h\{...\}} does not attempt to mimic the \FLORA
compiler in cases where conversion to HiLog (such as in case of reified
statements) makes no sense. Doing so would have substantially increased the
run-time overhead.


Not all arguments passed back and forth to Prolog need conversion. For
instance, {\tt sort/2}, {\tt ground/1}, {\tt compound/1}, and many others
do not need conversion because they work the same for Prolog and HiLog
representations. On the other hand, most I/O predicates require conversion.
\FLORA provides the {\tt io} library, described in
Section~\ref{sec-service-libs}, which provides the needed conversions for
the I/O predicates.


\index{@prologall()}
%%
Another mechanism, described in Section~\ref{sec-prolog-modules}, is the
use of the {\tt @prologall()} and {\tt @prologall(module)} specifier to
call Prolog modules. This specifier cause the compiler to include code for
automatic conversion of arguments to and from Prolog
representation. However, as mentioned above, such conversion is sometimes
not necessary and the use of {\tt @prologall()} might incur unnecessary
overhead.


\section{Equality Maintenance}\label{sec-eqmaintain}


\paragraph{Implicitly derived equality.}
Unlike in regular Prolog, \FLORA terms can become {\tt equal}, which is a side
effect of the \fl semantics for scalar methods.  For instance, consider the
following \fl facts:
%%
\begin{quote}
mary[spouse{\fd}john]. \\
mary[spouse{\fd}joe]. \\
john[son{\mvd}frank].
\end{quote}
%%
Since {\tt spouse} is a scalar attribute, it can have at most one value for
any given object. This implies that the oids {\tt john} and {\tt joe} must
refer to the same object. Therefore, whatever is true about {\tt john}
should be also true about {\tt joe}, and vice versa.  Thus we should be
able to derive that {\tt joe[son{\mvd}frank]}.

What is illustrated above is just a very simple scenario of equality
maintenance. Another scenario when terms may become equal arises due to the
path expressions in the rule heads (Section~\ref{sec-pathexp-head}).
For instance, if our program has
%%
\begin{verbatim}
 john.mother[father->bob].
\end{verbatim}
%%
then \FLORA will create an internal oid to represent the value of
{\tt john.mother}. However, if later on we insert the face
\verb|john[mother->sally]| then this internal oid must be equated with
{\tt sally}.

\paragraph{User-defined equality.}
In addition, \FLORA users can define equality \emph{explicitly} in the source
program using the predicate {\tt :=:}, e.g.,
%%
\begin{quote}
{\tt john:=:batman.} \\
{\tt X:=:Y :- X[similar->Y].} \\
\end{quote}

\index{equality maintenance level}
\paragraph{Equality maintenance levels.}
Once an equality between terms is derived, this information may need to be
propagated to all \fl 
structures, including the subclass hierarchy, the ISA hierarchy, etc.
For instance, if {\tt x} and {\tt y} are equal, then so must be {\tt f(x)}
and {\tt f(y)}. If {\tt x:a} has been previously derived then we should now
be able to derive {\tt y:a}, etc. Although equality is a powerful
feature, its maintenance can slow the program down quite significantly.
In order to be able to eat the cake and have it at the same time, \FLORA
allows the user to control how equality is handled.
by providing the following three compiler directives:
%%
\index{equality}
\index{compiler directive!equality}
%%
{\tt
\begin{quote}
:- equality none.  (default)\\
:- equality basic.\\
:- equality flogic.
\end{quote}
}

\noindent
The first directive, \mbox{\tt equality none}, does not maintain equality
and {\tt :=:} is considered just like any other user-defined predicate
without any special semantics.  The directive \mbox{\tt equality basic}
guarantees that {\tt :=:} obeys the usual congruence rules for equality,
i.e., transitivity, reflexivity, symmetry, and substitution, but not the
special \fl equality rule for scalar methods. Finally, \mbox{\tt equality
  flogic} means that the full equality theory for \fl is in force.  In
particular, programs with path expressions in the rule heads might require
this level of equality to work correctly (if there is a possibility that
the Skolem terms introduced to represent the path expressions might be
equal to some real objects).

If a \FLORA module does not define facts of the form {\tt a:=:b}, which
involve the equality predicate {\tt :=:}, then the default equality
maintenance level is {\tt none}. If the program does define such facts,
then the default equality maintenance level is {\tt basic}, because it is
assumed that the use of {\tt :=:} in the program is not accidental.
In any case, the {\tt equality} directive overrides the default.

Note that even if the module might have path expression in the head, the
default equality level is still {\tt none} (unless {\tt :=:} is used).  The
reason for this is that such path expressions do not always require
equality maintenance, so the user has to request it explicitly.  For
instance, if in the above example we never insert
\verb|john[mother->sally]| then no equality maintenance will be required
even if the program defines the fact {\tt john.mother[father->bob]}, as
above.  However, if this fact is inserted, then the equality maintenance
level appropriate for this case is {\tt flogic} ({\tt basic} will not be
sufficient).

\paragraph{Locality of equality.}
Equality in \FLORA is always local to the module in which it is derived.
For example, if {\tt a:=:b} is derived by the rules in module {\tt foo}
then the query
%%
\begin{verbatim}
 ?- (a:=:b)@foo.  
\end{verbatim}
%%
will succeed, but the query
%%
\begin{verbatim}
 ?- (a:=:b)@bar.  
\end{verbatim}
%%
will fail (unless, of course, {\tt a:=:b} is also derived by the rules in
module {\tt bar}).

Since equality information is local to each module, the directives for
setting the equality level affect only the particular user modules in which
they are included.  Thus, equality can be treated differently in different
modules, which allows the programmer to compartmentalize the performance
problem associated with equality and, if used judiciously, can lead to
significant gains in performance.

\paragraph{Run-time changes to the equality maintenance level.}
In \FLORA, the desired level of equality maintenance can also be changed at
run time by executing a goal such as
%%
\begin{quote}
 {\tt ?- (equality basic).}
\end{quote}
%%
Furthermore, \FLORA allows one user module to set, at run time, the level
of equality maintenance in another user module:
%%
\begin{quote}
\verb!?- (equality flogic)@modulename.!
\end{quote}
%%
\index{dynamic module}
%%
This might be useful for \emph{dynamic} modules, {\it i.e.}, modules that
are not associated with any files and whose content is generated completely
dynamically. (See Section~\ref{sec-updates}.)

\paragraph{Using the preprocessor to avoid the need for equality maintenance.}
One final advice regarding equality. In many cases, programmers tend to use
equality as an aliasing technique for long messages, numbers, etc. In this
case, we recommend to use the preprocessor commands, which achieve the same
result without loss of performance. For instance,

%%
\begin{verbatim}
  #define YAHOO  'http://yahoo.com'  

  ?- YAHOO[fetch \fd X].
\end{verbatim}
%%
\noindent
Assuming that {\tt fetch} is a method that applies to strings that
represent WWW sites and that fetches the corresponding Web pages, the above
program will fetch the page at the Yahoo site, because \FLORA compiler will
replace YAHOO with the corresponding string that represents a URL.


\section{Inheritance}\label{sec-inheritance}


\index{inheritance!structural}
\index{inheritance!behavioral}
%%
\fl supports two types of inheritance: \emph{structural} and
\emph{behavioral}.  Structural inheritance applies to signatures only. For
instance, if {\tt student::person} and a program defines the signature
{\tt person[name{\Fd}string]} then the query {\tt ?- student[name{\Fd}X]}
succeeds with {\tt X=string}.

\index{inheritance!non-monotonic}
%%
Behavioral inheritance is much more
complicated. It is \emph{non-monotonic} in the sense that
addition of new facts might falsify previously true facts.

\index{attribute!inheritable}
\index{attribute!non-inheritable}
%%
\fl (and \FLORA) distinguishes between attributes and methods that can
inherit values from superclasses and those that do not. The syntax that we
have seen so far applies to \emph{non-inheritable} attributes only.
\emph{Inheritable attributes} are declared using the {\tt *=>} and {\tt *=>>}
style arrows and defined using the {\tt *->} and {\tt *->>} style arrows.
Note that while {\tt ->} and {\tt ->>} typically occur in facts and rules
that define the properties of individual objects, {\tt *->} and {\tt *->>}
normally occur in the definitions of classes.

The following is a \FLORA program for the classical {\tt Royal Elephant}
example:
%%
\begin{quote}
\begin{verbatim}
elephant[color*=>color].
royal_elephant::elephant.
clyde:royal_elephant.
elephant[color*->gray].
\end{verbatim}
\end{quote}
%%
The question is what is the color of {\tt clyde}?
{\tt clyde}'s color has not been defined in the above program. However, since
{\tt clyde} is an elephant and the default color for elephants is gray,
{\tt clyde}
must be gray. Thus, we can derive:
%%
\begin{quote}
\begin{verbatim}
clyde[color->gray].  
\end{verbatim}
\end{quote}
%%
Observe that when inheritable methods are inherited from a class by its
members, the attribute becomes non-inheritable. On the other hand, when
such a method is inherited by a subclass from its superclass, then the
method is still inheritable, so it can be further inherited by the members
of that subclass or by its subclasses. For instance, if we have
%%
\begin{quote}
\begin{verbatim}
circus_elephant::elephant.
\end{verbatim}
\end{quote}
%%
then we can derive 
%%
\begin{quote}
\begin{verbatim}
circus_elephant[color*->gray].  
\end{verbatim}
\end{quote}
%%

Non-monotonicity of behavioral inheritance becomes apparent when certain new
information gets added to the knowledge base. For instance, suppose we
learn that
%%
\begin{quote}
\begin{verbatim}
royal_elephant[color*->white].  
\end{verbatim}
\end{quote}
%%
Although we have previously established that {\tt clyde} is gray, this
new information renders our earlier conclusion invalid. Indeed, Since
{\tt clyde} is a royal elephant, it must be white, while being an
elephant it must be gray.  The conventional wisdom in object-oriented
languages, however, is that inheritance from more specific classes
must take precedence. Thus, we must withdraw our earlier conclusion
that {\tt clyde} is gray and infer that he is white:
%%
\begin{quote}
\begin{verbatim}
clyde[color->white].    
\end{verbatim}
\end{quote}
%%

Behavioral inheritance in \fl is discussed at length in
\cite{inheritance-odbase-02}.  The above problem of non-monotonicity is
just the tip of an iceberg. Much more difficult problems arise when
inheritance interacts with regular deduction. To illustrate, consider
the following program:
%%
\begin{quote}
\begin{verbatim}
b[m*->>c].
a:b.
a[m->>d] :- a[m->>c].
\end{verbatim}
\end{quote}
%%
In the beginning, it seems that \verb|a[m->>c]| should be derived by
inheritance, and so we can derive \verb|a[m->>d]|. Now, however, we can
reason in two different ways:
%%
\begin{enumerate}
\item \verb|a[m->>c]| was derived based on the belief that attribute {\tt
    m} is not defined for the object {\tt a}. However, once inherited,
  necessarily we must have \verb|a[m->>{c,d}]|. So, the value of
  attribute {\tt m} is not really the one produced by inheritance. In other
  words, inheritance of \verb|a[m->>c]| negates the very premise on which
  the original inheritance was based, so we must undo the operation and the
  ensuing rule application.
\item We did derive \verb|a[m->>d]| as a result of inheritance, but
  that's OK --- we should not really be looking back and undo previously
  made inheritance inferences. Thus, the result must be \verb|a[m->>{c,d}]|.
\end{enumerate}
%%
A similar situation (with similarly conflicting conclusions) arises when
the class hierarchy is not static. For instance, 
%%
\begin{verbatim}
 d[m*->e]
 d::b.
 b[m*->c].
 a:b.
 a:d :- a[m->c].  
\end{verbatim}
%%
If we inherit {\tt a[m \fd c]}  from {\tt b} (which seems to be OK in the
beginning, because nothing overrides this inheritance), then we derive {\tt
  a:d}, {\it i.e.}, we get the following: {\tt a:d::b}. This means that
\emph{now} {\tt d} seems to be negating the reason why {\tt a[m \fd c]} was
inherited in the first place. Again, we can either undo the inheritance or
adopt the principle that inheritance is never undone.

A semantics that favors the second interpretation was proposed in
\cite{KLW95}. This approach is based on a fixpoint computation of
non-monotonic behavioral inheritance.  However, this semantics is very hard
to implement efficiently, especially using a top-down deductive engine
provided by the underlying Prolog engine. It is also unsatisfactory in many
respects because it is not based on a model-theory. \FLORA uses a
different, more cautious semantics for inheritance, which favors the first
interpretation above.

The details of this semantics are described in
\cite{inheritance-odbase-02}.  Under this semantics, {\tt clyde} will still
inherit color white, but in the other two examples {\tt a[m->c]} is
\emph{not} inherited.  The basic intuition can be summarized as follows:
%%
\begin{enumerate}
\item  Methods definitions in subclasses override the definitions that
  appear in the superclasses.
\item In case of a multiple inheritance conflict, the result of inheritance
  is undefined. More precisely, \FLORA is based on a three-valued logic and
  in this case the truth value is ``unknown.''
\item  Inheritance from the same source through different paths is
  \emph{not} considered a multiple inheritance conflict. For instance, in
  %%
  \begin{verbatim}
      a:c.    c::e.      e[m->f].    
      a:d.    d::e.
  \end{verbatim}
  %%
  Even though we derive {\tt c[m->f]} and {\tt d[m->f]} by inheritance,
  these two facts can be further inherited to {\tt a} since they came from
  a single source {\tt e}.

  On the other hand, in a similar program
  %%
  \begin{verbatim}
       a:c[m->f].    
       a:d[m->f].     
  \end{verbatim}
  %%
  inheritance does not take place (the truth value of {\tt a[m->f]} is
  ``undefined''), because the two inheritance candidates, {\tt c[m->f]} and
  {\tt d[m->f]}, are considered to be in conflict.

  Note that in the last example one might argue that even if we did inherit
  both facts to {\tt a} there would be no discrepancy, because in both
  cases the values of the attribute {\tt m} agree with each other.
  However, \FLORA views this agreement accidental, as it depends on the
  data currently stored in the database. Had one of the values changed to, say,
  {\tt d[m->g]}, there would be a conflict.
  
\item At the level of methods of arity $>1$, a conflict is considered to have
  taken place if there are two non-overwritten definitions of the same method
  attached to two different superclasses. When deciding whether a conflict
  has taken place we disregard the arguments of the method. For instance, in
  %%
  \begin{verbatim}
       a:c[m(k)->f].    
       a:d[m(u)->f].     
  \end{verbatim}
  %%
  a multiple inheritance conflict has taken place even though in one case
  the method {\tt m} is applied to object {\tt k}, while in the other it is
  applied to object {\tt u}. On the other hand,
  %%
  \begin{verbatim}
       a:c[m(k)->f].    
       a:d[m(k,k)->f].     
  \end{verbatim}
  %%
  do not conflict, because {\tt m/1} in the first case is a different
  method than {\tt m/2} in the second.
\end{enumerate}
%%
%%
\index{well-founded semantics}
%%

In the examples that we have seen so far, path expressions used only
non-inheritable attributes. Clearly, there is no reason to disallow
inheritable attributes in such expressions. To distinguish inheritable
attributes from non-inheritable ones, \FLORA uses the symbols
{\tt !} and {\tt !!} in its path expressions. For instance,
%%
\begin{quote}
\begin{verbatim}
clyde!color           means: some X, such that clyde[color*->X]}.
obj!!attr             means: some Y, such that obj[attr*->>Y].
\end{verbatim}
\end{quote}
%%



\section{Aggregates}


The syntax for aggregates is similar to that in \FLORID. An
aggregate has the following form:
%%
\begin{qrules}
agg\{X[Gs] $|$ {\it query}\}
\end{qrules}
%%
\index{aggregation!aggregate operator}
\index{aggregation!grouping}
%
where {\tt agg} represents the aggregate operator, {\tt X} is called the
aggregation variable, {\tt Gs} is a list of comma-separated grouping
variables, and {\it query} is a logical formula that specifies the
query conditions. The grouping variables, {\tt Gs}, are optional. {\it query}
can be any combination of conjunction, disjunction, and negation of literals.

All the variables appearing in {\it query} but not in {\tt X} or {\tt Gs} are
considered to be existentially quantified. Furthermore, the syntax of an
aggregate must satisfy the following conditions:
%%
\begin{enumerate}
\item All names of variables in both {\tt X} and {\tt Gs} must
appear in {\it query};
\item {\tt Gs} should not contain {\tt X}.
\end{enumerate}

Aggregates are evaluated as follows: First, the query
condition specified in {\it query} is evaluated to obtain all the bindings
for the template of the form {\tt \texttt{<}X, Gs\texttt{>}}. Then, these
tuples are grouped according to each distinct binding for
{\tt \texttt{<}Gs\texttt{>}}. Finally, for each group, the aggregate operator
is applied to the list of bindings for the aggregate variable $\tt X$.


\index{aggregates!min}
\index{aggregates!max}
\index{aggregates!count}
\index{aggregates!sum}
\index{aggregates!avg}
\index{aggregates!collectset}
\index{aggregates!collectbag}
%
The following aggregate operators are supported in \FLORA: {\tt min}, {\tt
  max}, {\tt count}, {\tt sum}, {\tt avg}, {\tt collectset} and {\tt
  collectbag}.

The operators {\tt min} and {\tt max} can apply to any list of
terms. The order among terms is defined by the Prolog operator {\tt @=<}.  In
contrast, the operators {\tt sum} and {\tt avg} can take numbers only. If
the aggregate variable is instantiated to something other than a
number, {\tt sum} and {\tt avg} will discard it and generate a runtime
warning message.

For each group, the operator {\tt collectbag} collects all the bindings of
the aggregation variable into a list. The operator {\tt collectset} works
similarly to {\tt collectbag}, except that all the duplicates are removed
from the result list.


The aggregates {\tt min}, {\tt max}, {\tt sum}, {\tt count}, and {\tt avg}
fail if {\tt query} fails.
In contrast, {\tt collectbag} and {\tt collectset} succeed even if {\tt
  query} returns no binding. In this case, these aggregates return the
empty list.

In general, aggregates can appear wherever a number or a list is
allowed. Therefore, aggregates can be nested. The following examples
illustrate the use of aggregates (some borrowed from the \FLORID manual):
%%
\begin{quote}
\begin{verbatim}
?- Z = min{S|john[salary(Year)->S]}.
?- Z = count{Year|john.salary(Year) < max{S|john[salary(Y)->S], Y < Year}}.
?- avg{S[Who]|Who:employee[salary(Year)->S]} > 20000. 
\end{verbatim}
\end{quote}
%%
If an aggregate contains grouping variables that are \emph{not} bound
by a preceding subgoal, then this aggregate would backtrack over such
grouping variables (In other words, grouping variables are considered to be
existentially quantified). For instance, in the last query above, the
aggregate will backtrack over the variable {\tt Who}. Thus, if
{\tt john}'s and {\tt mary}'s average salary is greater than {\tt 20000},
this query will backtrack and return both {\tt john} and {\tt mary}.

The following query returns, for each employee, a list of years when this
employee had salary less than 60. This illustrates the use of the {\tt
  collectset} aggregate.
%%
\begin{quote}
\begin{verbatim}
?- Z = collectset{Year[Who]|Who[salary(Year)->X], X < 60}.
Z = [1990,1991]
Who = mary

Z = [1990,1991,1997]
Who = john
\end{verbatim}
\end{quote}
%%

\subsection {Aggregation and Set-Valued Methods}

\index{aggregates!multi-valued methods}
\index{multi-valued methods!aggregation}
\index{{\tt ->->}}
\index{{\tt *->->}}
%%
Aggregation is often used in conjunction with set-valued methods, and
\FLORA provides several shortcuts to facilitate this use.
In particular, the operators
{\tt ->->} and {\tt *->->}, for non-inheritable and
inheritable multivalued methods, collects all the values of the given
method for a given object in a set. The semantics of these operators is
as follows:

\begin{quote}
\begin{verbatim}
O[M->->L] :- L=collectset{V|O[M->>V]}

O[M*->->L] :- L=collectset{V|O[M*->>V]}
\end{verbatim}
\end{quote}

\noindent
Note that in {\tt O[M->->L]}  and {\tt O[M*->->L]}  {\tt L} is a list of oids.

Having special meaning for {\tt ->->} and {\tt *->->} means that these
constructs \emph{cannot} appear in the head of a rule.
One other caveat: recursion through aggregation is not supported and can
produce incorrect results.



\index{\tt +>>}
\index{\tt *+>>}
  %%
Sets collected in the above manner often  need to be compared to other
sets. For this, \FLORA provides another pair of primitives: {\tt +>>} and
{\tt *+>>} for non-inheritable and inheritable methods, respectively.
The atom of the form {\tt o[m+>>s]} is true if the set of all values of the
non-inheritable attribute {\tt m} for object {\tt o} \emph{contains} every
element in the list {\tt s}. 

For instance, the following query tests whether all Mary's children are
also John's children:
%%
\begin{quote}
\begin{verbatim}
?- mary[children->->L], john[children+>>L].
\end{verbatim}
\end{quote}

As with {\tt ->->} and {\tt *->->},
the use of {\tt +>>} and {\tt *+>>} is limited to rule bodies.



\section{Boolean Methods}


\index{method!boolean}
%
As a syntactic sugar, \FLORA introduces boolean methods, which can be
considered as scalar methods that return some fixed value, e.g.,
{\tt void}. For example, the following facts:
\begin{quote}
\verb|john[is_tall -> void].| \\
\verb|john[loves(tennis) -> void].|
\end{quote}
can be simplified as boolean methods as follows:
\begin{quote}
\verb|john[is_tall].| \\
\verb|john[loves(tennis)].|
\end{quote}

Conceptually, boolean methods are statements about objects whose truth
value is the only concern. Boolean methods do not return any value (not
even the value {\tt void}). Therefore, boolean methods {\tt cannot} appear
in path expressions. For instance, \mbox{\tt john.is\_vegetarian}, where
{\tt is\_vegetarian} is a binary method, is illegal.

\index{method!boolean!inheritable}
\index{boolean method!inheritable}
%%
Like scalar methods, boolean methods can be inheritable. To make a
boolean method inheritable, the \verb|*| sign is prepended to
the method name:
%%
\begin{quote}
\begin{verbatim}
buddhist[*is_vegetarian].
john:buddhist.
\end{verbatim}
\end{quote}
%%
The above says that all Buddhists are vegetarian and John (the object with
oid {\tt john}) is a Buddhist. Since \verb|is_vegetarian| is inheritable,
it follows that John is also a vegetarian, i.e.,
\verb|john[is_vegetarian]|.


\section{Anonymous Oids}


\index{anonymous oid}
\index{oid!anonymous}
%
For applications where oids are not important, \FLORA provides the
compiler directive \verb|_#| to automatically generate a new
oid. \verb|_#| can be used wherever an Id-term is allowed, \emph{except in the
rule body}, where such oids make no sense. Like the
anonymous variable \verb|_|, each occurrence of \verb|_#| represents
an \emph{anonymous oid}. The difference is that such an oid is not only
unique in each rule, but in the source program as well.

Of course, uniqueness is achieved through the use of special ``weird'' naming
schema for such oids. However, as long as the user does not use a similar
naming convention (who, on earth, would give names that begin with lots of
{\tt ``\_\$''}s?), uniqueness is guaranteed.


For example, in the following program:
%%
\begin{quote}
\begin{verbatim}
_#[ssn->123, father->_#[name->john, spouse->_#[name->mary]]].
foo[_#(X)->Y] :- foo(X,Y).
\end{verbatim}
\end{quote}
%%
the compiler will generate unique oids for each occurrence of {\tt \_\#}.
Note that, in the second clause, only one oid is generated and it serves as
a method name.

\index{numbered anonymous oid}
\index{oid!anonymous!numbered}
%%
In some situations, it is needed to be able to create a new oid and use it
within the same rule head or a fact. Since such an oid 
needs to be referenced inside the same program clause, it is no longer
possible to use \verb|_#|, because each occurrence of \verb|_#| causes the
compiler to generate a new oid. To solve this problem, \FLORA allows 
\emph{numbered anonymous oids}, which are of the form \verb|_#132|, {\it
  i.e.}, \verb|_#| with a number attached to it. For instance, 
%%
\begin{quote}
\begin{verbatim}
_#1[ssn->123, father->f(_#1)[name->john, spouse->_#[name->mary]]].
_#1[self->_#1].
\end{verbatim}
\end{quote}
%%
The first time the compiler finds \verb|_#1| in the first clause above,
it will generate a new oid. However, the second occurrence of \verb|_#1|
in the \emph{same} clause ({\it i.e.}, \verb|f(_#1)|)  will use the oid
previously generated for the first occurrence. On the other hand,
occurrences of \verb|_#1| in \emph{different} clauses are substituted with
different oids. Thus, the occurrences of \verb|_#1| in the first and second
clauses above refer to different objects.



\section{\FLORA and Tabling}\label{sec-tabling-flora}


\subsection{Tabling in a Nutshell}


\index{tabling}
%
Tabling is a technique that enhances top-down query evaluation with a
mechanism that remembers the calls made previously in the process.  This
technique is known to be essentially equivalent to the Magic Sets method
for bottom-up evaluation. However, tabling combined with top-down
evaluation has the advantage of being able to utilize highly optimized
compilation techniques developed for Prolog. The result is a very efficient
deductive engine.

XSB lets the user specify which predicates must be tabled.  The \FLORA
compiler automatically tables F-molecules.
However, if the user wants to table a predicate, she must tell this to
\FLORA using a tabling directive.

\index{table}
\index{compiler directive!{\tt table}}
%
To table a predicate, the following can be used:
\begin{quote}
\begin{verbatim}
:- table tc/2.

tc(X,Y) :- edge(X,Y).
tc(X,Y) :- edge(X,Y), tc(Y,Z).
\end{verbatim}
\end{quote}
%%
which renders {\tt tc/2}  as a tabled predicate.

Note that \FLORA supports HiLog predicates, which can have the form {\tt
  p(a,b)(c)(X)}. Therefore, tabling in \FLORA is more elaborate than in XSB.
In particular, it allows tabling structured predicates, such as {\tt p(\_,\_)(\_)}.
This can be specified as
%%
\begin{verbatim}
 :- table p/2/1.
\end{verbatim}
%%
meaning that the structured predicates of the form {\tt p(a,b)/1} (for all
{\tt a} and {\tt b}) are tabled. Note that the above directive does \emph{not}
table predicates of the form {\tt p/1} or {\tt p(a)/1}. In other words, the
two-level tabling schema supported in \FLORA provides for a more selective
tabling of HiLog predicates.

\FLORA \emph{does not} support 3-level (or higher) tabling.  That is,
%%
\begin{verbatim}
 :- table p/2/1/3.  
\end{verbatim}
%%
will cause a parsing error.  However, note that {\tt :- table X/1/3.} will
also table all 3-level predicates of the form {\tt p(\_,\_)(\_)/3}. The
difference is that it will also table {\tt q(a,b,c)(d)/3}, {\tt r(w)(f)/3},
etc.  In contrast, if {\tt :- table p/2/1/3.} were allowed, then the last
two forms would not have been tabled.\footnote{
  %%
  The reason for not supporting this more elaborate tabling schema is
  because it is believed to be an overkill.
  %%
}
%%
The allowed depth of HiLog tabling can be changed by changing the constant
{\tt FLSK\_DEPTH} in {\tt flrparser.P} and recompiling \FLORA. However,
this might negatively affect the performance and we  believe that it is
generally not necessary.


%% Unimplemented -- Flora and subsumptive tabling
It is important to keep in mind that Prolog does not do reordering of \fl
molecules and predicates during joins. Instead, all joins are performed
left-to-right.  Thus, program clauses must be written in such a way as to
ensure that smaller predicates and classes appear early on in the join.
Also, even though XSB tables the results obtained from previous queries,
the current tabling engine has several limitations. In particular, when a
new query comes in, XSB tries to determine if this query is ``similar'' to
one that already has been answered (or is in the process of being
evaluated).  Unfortunately, the default notion of similarity used by XSB is
fairly weak, and many unnecessary recomputations might result. Recently, a
new technique, called \emph{subsumptive tabling}, has been implemented in
XSB. It is known that subsumptive tabling can speed up certain queries by
an order of magnitude. A future version of \FLORA might take advantage of
this technique.

\subsection{Discarding Information Stored in Prolog Tables}

When Prolog (and \FLORA) evaluate a program, all tabled predicates are
partially materialized and all the computed tuples are stored in Prolog
tables. Thus, if you change the underlying set of facts (via insert and
delete operations), the existing tables must be discarded in order to allow
Prolog to recompute the results.  We discuss updates and the problems
caused by tabling Section~\ref{sec-updates}.

\index{refresh\{...\}}
%%
There are two ways to discard tabled information in \FLORA. One, and the
safest way is to use the operator {\tt refresh\{...\}}. Inside the braces
you list the calls for which you want to discard table information.  For
instance,
%%
\begin{verbatim}
 flora2 ?- refresh{p(a,X), X[meth(_)->b]}.
\end{verbatim}
%%
will discard any tabling information that is related to   {\tt p(a,X)}
and {\tt X[meth(\_)->b]}.
To affect the tables in another module, attach the module name to the
corresponding literals. For instance,
%%
\begin{verbatim}
 flora2 ?- refresh{(p(a,X), X[meth(_)->b])@foo}.
\end{verbatim}
%%

\index{abolish\_all\_tables}
%%
Sometimes it may be desirable to discard \emph{all} table information in the
current run of the program.
This can be done by issuing the
query {\tt ?- abolish\_all\_tables/0} described in the XSB manual.
However, this should be done with great caution, because
{\tt abolish\_all\_tables/0} is not a safe query (it can crush XSB!).

If you really need to use {\tt abolish\_all\_tables/0}, it \emph{cannot} be
used in the following cases:
%%
\begin{enumerate}
  \item  in the body of a rule that defines an object attribute or method
  \item  in the body of a rule that defines a tabled HiLog predicate
\end{enumerate}
%%
This is because internally the above entities are represented using tabled
predicates. Execution of {\tt abolish\_all\_tables/0} in the body of such a
rule would destroy the table for the predicate being computed by that rule.

More generally, no tabled predicate or object molecule of the above sort
can depend via rules --- directly or indirectly --- on {\tt
  abolish\_all\_tables/0}.  However, it is safe to use this predicate in
the body of a rule that defines a procedural method (defined next).

\paragraph{Note:} Neither {\tt refresh\{...\}} nor {\tt
  abolish\_all\_tables} can occur under the scope of the {\tt tnot}
negation operator (directly or indirectly).


\subsection{Procedural Methods}\label{sec-proc-methods}

\index{method!procedural}
%
Because tabling is not integrated with the update mechanism in Prolog, it can
have undesirable effect on predicates with non-logical ``side effects''
(e.g., writing or reading a file) and predicates that change the state of
the database.  If a tabled predicate has a side effect, the first time the
predicate is called the side effect is performed, but the second time the
call simply returns with success or failure (depending on the outcome of
the first call), because Prolog will simply look it up in a table.  Thus, if
the predicate is intended to perform the side effect each time it is
called, it will not operate correctly.

Object-oriented programs often rely on methods that produce side effects
or make updates.  In \FLORA we call such methods \emph{procedural}.
Because by default \FLORA tables everything that looks like an F-molecule,
these procedural methods are potentially subject to the aforesaid problem.

To sidestep this program, \FLORA introduces a new syntax to identify
procedural methods --- by allowing the ``\verb|#|'' sign in front of a
procedural method. For instance, the following rule defines an output
method that, for every object, writes out its oid:
%%
\begin{quote}
\verb|O[#output] :- write(O)@prolog().|
\end{quote}
%%
Like boolean methods, procedural methods can take arguments, but do not
return any values.  The only difference is that procedural methods are
\emph{not} tabled, while boolean methods are.

\subsection{Operational Semantics of \FLORA}\label{sec-flora-procedural}

Although \FLORA is a declarative language, it provides primitives, such as
input/output, certain types of updates, cuts, etc., which have no logical
meaning. In such cases, it is important to have an idea of the
\emph{procedural semantics} of \FLORA. This procedural semantics is
essentially the same as in XSB and when no tabled predicates or \fl molecules
are involved, the behavior is the same as in Prolog. However, when tabled
HiLog predicates or \fl molecules (other than procedural methods) are used
the programmer must have some understanding of the way XSB evaluates tabled
predicates.

XSB has two configuration modes that affect tabled predicates:
\emph{batched} and \emph{local} (the default). These modes affect
\emph{scheduling}, {\it i.e.}, the order in which answers to the literals
in a rule body are computed.
(The current release does not work under batched scheduling, so reading on
is even more important to understand the flow of control under local
evaluation.)

Under the batched scheduling, the behavior is similar to that of Prolog.
Under the local scheduling, answers to the entire clique of inter-dependent
predicates is computed before the computation proceeds to the next literal
in a rule body. The following little program illustrates the difference:
%%
\begin{verbatim}
a:b.
d:b.
c:b.

X[foo->Y] :- X:Y, writeln(X)@prolog().
q(X,Y) :- X:Y, writeln(X)@prolog().

?- X[foo->Y], writeln(done)@prolog().
?- q(X,Y), writeln(done)@prolog().
\end{verbatim}
%%
The two queries are essentially the same, the first is an \fl molecule
and so it is implemented internally as a tabled XSB predicate. The second
query is implemented as a non-tabled predicates.  Thus, despite the fact
that the two queries are \emph{logically equivalent}, they are not
\emph{operationally equivalent} under local scheduling.  Indeed, a simple
experiment shows that the answers to the above two queries are produced in
different orders (as seen by the order of execution of the print statement.
In the first query, \verb|X[foo->Y]| is evaluated completely before
proceeding to {\tt writeln(done)@prolog()} and thus the executions of {\tt
  writeln(X)@prolog()} are grouped together. In the second case, executions
of {\tt writeln(X)@prolog()} and {\tt writeln(done)@prolog()} alternate,
because {\tt q/2}is not tabled by  default and thus its evaluation follows
the usual Prolog semantics.

On the other hand, if we add the directive
%%
\begin{verbatim}
 :- table q/2.  
\end{verbatim}
%%
then the two queries will behave the same, as both {\tt q/2} and
\verb|X[foo->Y]| would then be implemented internally as tabled predicates.
Likewise, if we replace {\tt foo} with {\tt \#foo} then the corresponding
molecule would be represented internally as a non-tabled predicate.
Thus, the two queries in the program
%%
\begin{verbatim}
X[#foo(Y)] :- X:Y, writeln(X)@prolog().
q(X,Y) :- X:Y, writeln(X)@prolog().

?- X[#foo(Y)], writeln(done)@prolog().
?- q(X,Y), writeln(done)@prolog().
\end{verbatim}
%%
will produce the same result where {\tt a, b, c} and {\tt done}
alternate in the output.



\subsection{Cuts}


\index{cut!in \FLORA}
\index{cut!across tables}
%%
No discussion of a logic programming language is complete without a few
words about the infamous Prolog cut (!). Although Prolog cut has been
(mostly rightfully) excommunicated as far as Database Query Languages are
concerned, it is sometimes indispensable when doing ``real work'', like
pretty-printing \FLORA programs or implementing a pattern matching
algorithm.  To facilitate this kind of tasks, \FLORA lets the programmer
use cuts.  However, the current implementation of XSB has a limitation that
Prolog cuts cannot ``cut across tabled predicates.''  If you get an error
message telling something about cutting across the tables --- you know that
you have cut too much!

The basic rule that can keep you out of trouble is: do not put a cut in the
body of a rule \emph{after} any F-molecule or tabled 
predicate. However, it is OK to put a cut before any F-molecule. It is
even OK to have a cut in the body of a rule that \emph{defines} an
F-molecule (again, provided that the body has no F-molecule to the left of
that cut). If you need to use cuts, plan on using procedural methods or
non-tabled predicates.

\index{cut!and local scheduling}
Also, when XSB is configured for \emph{local} scheduling, cuts across
tables are much less likely, because under this strategy XSB tries to
compute the entire clique of interrelated predicates \emph{before} it
proceeds to the next body literal (which could be the dreadful cut).
Thus, something like
%%
\begin{verbatim}
 X[#foo(Y)] :- Z[moo->W], W:X, !, rest.  
\end{verbatim}
%%
will not cause problems under the local scheduling, but
%%
\begin{verbatim}
 X[foo->Y] :- Z[moo->W], W:X, !, rest.  
\end{verbatim}
%%
will likely result in a runtime error. The reason is that in the first case
the molecule \verb|X[#foo(Y)]| is implemented as a non-tabled predicate, so
by the time the evaluation reaches the cut, both \verb|Z[moo->W]| and 
{\tt W:X} will be evaluated completely and their tables will be marked as
``complete.'' In contrast, in the second example, \verb|X[foo->Y]| is
implemented as a tabled predicate, which is interrelated with the
predicates that are used to implement \verb|Z[moo->W]| and 
{\tt W:X}. Thus, the cut would occur in the middle of the computation of
the table for \verb|X[foo->Y]| and an error will result.

%% Unimplemented -- demand tabling
In a future release, XSB will implement a different tabling schema. While
cutting across tables will still be prohibited, it will provide an
alternative mechanism that achieves many of the goals a cut is used for.


\section{Updates}\label{sec-updates}


\index{update}
\index{predicate!derived part of}
\index{predicate!base part of}
\index{object!base part of}
\index{object!derived part of}
\index{derived part of predicate}
\index{base part of predicate}
%
\FLORA provides primitives to update the runtime database. Unlike Prolog,
\FLORA does not require the user to define a predicate as dynamic in order
to update it. Instead, every predicate and object
has a \emph{base part} and a \emph{derived part}.  Updates directly change
only the base parts and only indirectly the derived parts.

Note that the base part of a predicate or an object contains \emph{both}
the facts that were \emph{inserted explicitly} into the database and the
facts that you specified in the program. For instance, in
%%
{\tt
\begin{quote}
 p(a).\\
 a[m->b].
\end{quote}
}
%%
\noindent
the fact {\tt p(a)} will be placed in the base part of the predicate p/1 tt
and it can be deleted by the {\tt delete} primitive. Likewise,
the fact {\tt a[m->b]} is updatable. If you do not want
some facts to be updatable, use the following syntax:
%%
{\tt
\begin{quote}
 p(a) :- true.\\
 a[m->b] :- true.
\end{quote}
}
%%


\FLORA updates can be \emph{non-backtrackable,} as in Prolog,
or backtrackable, as in Transaction Logic \cite{trans-chapter-98,trans-tcs94}.
We first describe non-backtrackable updates.


\subsection{Non-backtrackable (Non-logical) Updates}
\label{sec:non-backtrackable-updates}

\index{non-backtrackable update}
\index{update!non-backtrackable}
%
The effects of non-backtrackable updates persist even if a subsequent failure
causes the system to backtrack.

\FLORA supports the following non-backtrackable update primitives:
{\tt insert}, {\tt insertall}, {\tt delete}, {\tt deleteall},
{\tt erase}, {\tt eraseall}. These primitives use special syntax (the curly
braces) and are \emph{not} predicates. Thus, it is allowed to have a
user-defined predicate such as {\tt insert}.

\index{non-backtrackable update!insert}
\index{non-backtrackable update!insertall}
%
\paragraph{Insertion.} The syntax of an insertion is as follows (note the
\{,\}s!):
{\tt
\begin{quote}
\emph{insop}\{\emph{literals} [| \emph{query}]\}
\end{quote}
}
\noindent
where {\it insop} stands for either {\tt insert} or {\tt insertall}.
The
{\it literals} part represents a comma separated list of literals,
which can include
predicates and \mbox{F-molecules}. The optional part, {\tt |}{\it query},
is an additional condition that must be satisfied in order for
\emph{literals} to be inserted or deleted (depending on what \emph{insop}
is).
The semantics is that \emph{query} is posed first and, if it is
satisfied, \emph{literals} is inserted (note that the query may affect the
variable binding and thus the particular instance of \emph{literals} that
will be inserted). For instance, in
\begin{quote}
\begin{verbatim}
flora2 ?- insert{p(a),mary[spouse->smith,children->>frank]}
flora2 ?- insert{P[spouse->S] | S[spouse->P]}
\end{verbatim}
\end{quote}
%%
the first statement inserts a particular molecule. In the second case, the
query {\tt S[spouse->P]} is posed and one answer (a binding for {\tt P} and
{\tt S}) is obtained. If there is no such binding, nothing is inserted and
the statement fails. Otherwise, the instance of {\tt P[spouse->S]} is
inserted for that binding and the statement succeeds.

The insert statement has two forms: {\tt insert} and {\tt insertall}
The difference between {\tt insert} and {\tt insertall} is that {\tt
  insert} inserts only one instance of \emph{literals} that satisfies the
formula, while {\tt insertall} inserts \emph{all} instances of the literals
that satisfy the formula. In other words, \emph{query} is posed first and
\emph{all} answers are obtained. Each answer is a tuple of bindings for
some (or all) of the variables that occur in \emph{literals}.  To
illustrate the difference between {\tt insert} and {\tt insertall},
consider the following statements:
%%
{\tt
\begin{quote}
  flora2  ?- p(X,Y), insert\{q(X,Y,Z)|r(Y,Z)\}.\\
  flora2  ?- p(X,Y), insertall\{q(X,Y,Z)|r(Y,Z)\}.
\end{quote}
}
%%
In the first case, if {\tt p(x,y)} and {\tt r(y,z)} are true, then the fact
{\tt q(x,y,z)} is inserted. In the second case, if {\tt p(x,y)} is true,
then the update means the following:
%%
\begin{quote}
  For each {\tt z}  such that {\tt r(y,z)}  holds, {\tt insert(x,y,z)}.
\end{quote}
%%
\index{bulk insert}
\index{insert!bulk}
%%
The primitive {\tt insertall} is also known as a bulk-insert operator.

Unlike {\tt insert}, the operator {\tt insertall} always succeeds and it
always leaves its free variables unbound.

The difference between {\tt insert} and {\tt insertall} is more subtle than
it may appear from the above discussion. In the all-answers mode, the above
two queries will actually behave the same, because \FLORA will try to find
all answers to the query {\tt p(X,Y), r(Y,Z)} and will do the 
insertion for each answer. The difference becomes apparent if \FLORA is in
one answer at a time mode (because {\tt flOne} was executed in a preceding
query) or when the all-answers mode is suppressed by a cut as in
{\tt
\begin{quote}
  flora2  ?- p(X,Y), insert\{q(X,Y,Z)|r(Y,Z)\}, !.\\
  flora2  ?- p(X,Y), insertall\{q(X,Y,Z)|r(Y,Z)\}, !.
\end{quote}
}
%%
\noindent
In such cases, the first query will indeed insert only one fact, while the
second will insert all.

Note that literals appearing inside an insert primitive (to the left of the
\verb'|' symbol, if it is present) are treated as
facts and should follow the syntactic rules for facts and literals in the
rule head. In particular, multi-valued path expressions are not allowed.
Similarly, module specifications inside update operators are illegal.
However, it is allowed to insert facts into a different module so module
specifications are permitted in the literals that appear in the 
{\tt insert\{...\}} primitive:
%%
\begin{quote}
\begin{verbatim}
flora2 ?- insert{(mary[children->>frank], john[father->smith]) @ foomod}
\end{verbatim}
\end{quote}
The above statement will insert {\tt mary[children->>frank]} and
{\tt john[father->smith]} into module {\tt foomod}.

Note that module specifications are also allowed in the
\emph{condition} part of an update operator (to the right of the \verb'|'
mark):
%%
\begin{quote}
\begin{verbatim}
flora2 ?- insert{mary[children->>X]@foobar | adult(X)@infomod}
\end{verbatim}
\end{quote}

Updates to Prolog modules is accomplished using the usual
Prolog's {\tt assert/retract}:
%%
\begin{quote}
 {\tt flora2 ?- assert(foo(a,b,c))@prolog().  }
\end{quote}
%%
The following subtleties related to updates of Prolog modules are worth
noting. Recall Section~\ref{sec-passing-args} on the issues concerning the
difference between the HiLog representation of terms in \FLORA and the one
used in Prolog. The problem is that {\tt foo(a,b,c)} is a HiLog term that
Prolog does not understand and will not associate it with the predicate
{\tt foo/3} that it might have. To do it right, use explicit conversion:
%%
\begin{quote}
 {\tt ?- p2h\{PrologRepr,foo(a,b,c)\}, assert(PrologRepr)@prolog().  }
\end{quote}
%%
This will insert {\tt foo(a,b,c)} into the default XSB module called {\tt
  usermod}.

\index{@prologall()}
%%
If all this looks too complicated, \FLORA provides a higher-level
primitive, {\tt @prologall()}, as described in
Section~\ref{sec-prolog-modules}. This module specifier does automatic
conversion of terms to and from Prolog representation, so the above example
can be written much more simply:
%%
\begin{quote}
 {\tt flora2 ?- assert(foo(a,b,c))@prologall().  }  
\end{quote}
%%

Another possible complication might be that
If {\tt foo/3} is defined in another Prolog module, {\tt bar}, and
is imported by {\tt usermod}, then the above statement will not do anything
useful due to certain idiosyncrasies in the XSB module system. In this
case, we have to tell the system that {\tt foo/3} was defined in Prolog
module {\tt bar}.  Thus,
{\tt foo/3} was defined as a dynamic predicate in the module
  {\tt bar}, we have to write:
%%
\begin{quote}
 {\tt flora2 ?- assert(foo(a,b,c)@prolog(bar))@prolog().  }  
\end{quote}
%%
Note that if we want to assert a more complex fact, such as {\tt
  foo(f(a),b,c)}, we would have to use either
%%
\begin{quote}
 {\tt flora2 ?- assert(foo(f(a)@prolog(bar),b,c)@prolog(bar))@prolog().  }  
\end{quote}
%%
or {\tt @prologall()}:
%%
\begin{quote}
 {\tt flora2 ?- assert(foo(f(a),b,c)@prologall(bar))@prolog().  }  
\end{quote}
%%

We should also mention one important difference between insertion of facts
in \FLORA and Prolog. Prolog treats facts as members of a \emph{list}, so
duplicates are allowed and the order matters. In contrast, \FLORA treats
the database as a \emph{set} of facts with no duplicates. Thus, insertion
of a fact that is already in the database has no effect.


\index{non-backtrackable update!delete}
\index{non-backtrackable update!deleteall}
\index{non-backtrackable update!erase}
\index{non-backtrackable update!eraseall}
%
\paragraph{Deletion.} The syntax of a deletion primitive is as follows:
\begin{quote}
{\tt \emph{delop}\{\emph{literals} [| \emph{query}]\}}
\end{quote}
%%
where {\it delop} can be {\tt delete}, {\tt deleteall}, {\tt erase}, and
{\tt eraseall}. The {\it literals} part is a comma separated list of
F-molecules and predicates. The optional part, {\tt |}\emph{query},
represents an additional constraint or a restricted quantifier, similarly
to the one used in the insertion primitive.

For instance, the following predicate:
\begin{quote}
\begin{verbatim}
flora2 ?- deleteall{john[Year(Semester)->>Course] | Year < 2000}
\end{verbatim}
\end{quote}
will delete John's course selection history before the year 2000.

Note that the semantics of a {\tt delete}\{\emph{literal}{\tt |}{\it query}\}
statement is that first the query \emph{literal} $\wedge$ \emph{query} should
be asked. If it succeeds, then deletion is performed. For instance, if the
database is
%%
\begin{quote}
\begin{verbatim}
p(a). p(b). p(c). q(a). q(c).
\end{verbatim}
\end{quote}
then the statement below:
\begin{quote}
\begin{verbatim}
flora2 ?- deleteall{p(X)|q(X)}
\end{verbatim}
\end{quote}
will succeed with the variable {\tt X} bound to {\tt a} and {\tt c}, and
{\tt p(a)}, {\tt p(c)} will be deleted.  However, if the database contains
only the facts {\tt p(b)} and {\tt q(c)}, then the above predicate will
succeed ({\tt deleteall}always succeeds) and the database will stay
unchanged.

\index{bulk delete}
\index{delete!bulk}
%%
\FLORA provides four deletion primitives: {\tt delete}, {\tt deleteall},
{\tt erase}, and {\tt eraseall}. The primitive {\tt delete} removes at most
one fact at a time from the database. The primitives {\tt deleteall} and
{\tt eraseall} are {\bf bulk delete} operations; {\tt erase} is kind of a
hybrid: it starts slowly, by deleting one fact, but may go on a joy ride
and end up deleting much of your data. These primitives are described
below.
%%
\begin{enumerate}
\item If there are several bindings or matches for the literals to be
  deleted, then {\tt delete} will choose only one of them
  nondeterministically, and delete it.  For instance, suppose the database
  contains the following facts:
  \begin{quote}
    \verb|p(a). p(b). q(a). q(b).|
  \end{quote}
  then
  \begin{quote}
    \verb|flora2 ?- delete{p(X),q(X)}|
  \end{quote}
  will succeed with {\tt X} bound to either {\tt a} or {\tt b},
  depending on the ordering of facts in the database at runtime.

  However, as with insertion, in the all-answers mode the above deletion
  will take place for each binding that makes the query true. To avoid
  this, use one answer at a time mode or the cut.
      
\item In contrast to the plain {\tt delete} primitive, {\tt deleteall} will
  try to delete all bindings or matches.  Namely, for each binding of
  variables produced by \emph{query} it deletes the corresponding instance
  of \emph{literal}. If \emph{query} $\wedge$ \emph{literal} is false, the
  {\tt deleteall} primitive fails.  To illustrate, consider the following:
  %%
  \begin{quote}
    {\tt flora2 ?- p(X,Y), deleteall\{q(X,Y,Z)|r(Y,Z)\}.}
  \end{quote}
  %%
  and suppose {\tt p(x,y)} is true. Then the above statement will, for
  each {\tt z} such that {\tt r(y,z)} is true,
  delete {\tt q(x,y,z)}.
  
  For another example, suppose the database contains the following facts:
  %%
  \begin{quote}
    \verb|p(a). q(b). q(c).|
  \end{quote}
  %%
  and the query is {\tt ?- deleteall\{p(a),q(X)\}.} The effect will be 
  the deletion of {\tt p(a)} and of all the facts in {\tt q}. (If you
  wanted to delete just one fact in {\tt q}, {\tt delete} should
  have been used.)
  
  \smallskip
  
  Unlike the {\tt delete} predicate, {\tt deleteall} \emph{always}
  succeeds. Also, {\tt deleteall} leaves all variables unbound.
  
\item {\tt erase} works like {\tt delete}, but with an object-oriented
  twist: For each \fl fact, $f$, that it deletes, {\tt erase} will
  traverse the object tree by following $f$'s methods and delete all
  objects reachable in this way. It is a power-tool that can cause
  maiming and injury. Safety glasses and protective gear are
  recommended.
  
  Note that only the base part of the objects can be erased. If the
  object has a part that is derived from the facts that still exist, this
  part will not be erased.
  
\item {\tt eraseall} is the take-no-prisoners version of {\tt erase}.
  Just like {\tt deleteall}, it first computes \emph{query} and for each
  binding of variables it deletes the corresponding instance of
  \emph{literal}. For each deleted object, it then finds all objects it
  references through its methods and deletes those. This continues
  recursively until nothing reachable is left.  This primitive always
  succeeds and leaves its free variables unbound.
\end{enumerate}


\subsection{Backtrackable (Logical) Updates}


\index{backtrackable update}
\index{update!backtrackable}
%
The effects of backtrackable updates are undone upon backtracking, i.e., if
some post-condition fails and the system backtracks, a previously inserted
item will be removed from the database, and a previously deleted item will be
put back.

\index{backtrackable update!btinsert}
\index{backtrackable update!btinsertall}
\index{backtrackable update!btdelete}
\index{backtrackable update!btdeleteall}
\index{backtrackable update!bterase}
\index{backtrackable update!bteraseall}
%
The syntax of backtrackable update primitives is similar to that of
non-backtrackable ones and the names are similar, too.  The syntax for
backtrackable insertion is:
%%
\begin{quote}
\emph{btinsop}\{\emph{literals} [$\mid$ \emph{formula}]\}
\end{quote}
%%
while the syntax of a backtrackable deletion is:
%%
\begin{quote}
\emph{btdelop}\{\emph{literals} [$\mid$ \emph{query}]\}
\end{quote}
%%
where {\tt btinsop} stands for either {\tt btinsert} or {\tt btinsertall},
and {\tt btdelop} stands for either of the following four deletion
operations: {\tt btdelete}, {\tt btdeleteall}, {\tt bterase}, and {\tt
  bteraseall}. The meanings of {\it literals} and {\it query} is
the same as in Section~\ref{sec:non-backtrackable-updates}.

{\tt btinsert}, {\tt btinsertall}, {\tt btdelete}, {\tt btdeleteall}, {\tt
  bterase}, and {\tt bteraseall} work similarly to {\tt insert}, {\tt
  delete}, {\tt deleteall}, {\tt erase}, and {\tt eraseall}, respectively,
except that the new operations are backtrackable.  Refer to
Section~\ref{sec:non-backtrackable-updates} for details of these
operations.

To illustrate the difference between backtrackable and
non-backtrackable updates, consider the following execution trace
immediately after the \FLORA system starts:
\begin{quote}
\begin{verbatim}
flora2 ?- insert{p(a)}, fail.

No

flora2 ?- p(a).

Yes

flora2 ?- btinsert{q(a)}, fail.

No

flora2 ?- q(a).

No
\end{verbatim}
\end{quote}
In the above example, when the first \verb|fail| executes, the system
backtracks to {\tt insert\{p(a)\}} and does nothing. Thus the insertion
of {\tt p(a)} persists and the following query \verb|p(a)| returns
with {\tt Yes}. However, when the second \verb|fail| executes, the
system backtracks to {\tt btinsert\{q(a)\}} and removes {\tt q(a)} that
was previously inserted into the database. Thus the next query
\verb|q(a)| returns with {\tt No}.

Keep in mind that some things that Prolog programmers routinely do with
{\tt assert} and {\tt retract} goes against the grain of the use of
backtrackable updates. In particular, {\tt fail}-loops are not going to
work (will leave the database unchanged) for obvious reasons. The {\tt
  while} and {\tt until} loops should be used in such situations.

As before, {\tt btinsertall}, {\tt btdeleteall}, and {\tt bteraseall}
primitives always succeed and leave the free variables unbound.  Likewise,
in the all-answers mode, the primitives {\tt btinsert}, {\tt btdelete}, and
{\tt bterase} behave similarly to the {\tt bt*all} versions in other
respects, {\it i.e.}, they will insert or delete facts for every answer to
the associated query. This can be prevented with the use of the cut or the
{\tt flOne} directive.

{\bf Unimplemented}: In the current release, arithmetic expressions in the
query part of an update must have their variables be bound by the subgoals
that precede the update primitive, except that the literal part does not
currently bind. For instance, 
%%
\begin{quote}
 \verb!?- delete{X[salary->Y] | Y<20000}.!
\end{quote}
%%
is going to cause a run-time error. This limitation will be removed in a
future release.


\subsection{Updates and Tabling}

\index{updates!and tabling}
%%
\paragraph{Changing tabled predicates or predicates on which tabled
  predicates depend.}
%%
We have earlier remarked in Section~\ref{sec-proc-methods} that tabling and
database updates do not mix well.  One problem is that the results from
previous queries are stored in Prolog tables, and database updates do not
modify those tables.  Thus, in Prolog the user might get the following
counterintuitive result, if the predicate {\tt p/1} is tabled:
%%
\begin{quote}
\begin{verbatim}
| ?- assert(p(a)).

yes
| ?- p(a)

yes
| ?- retract(p(a)), p(a).

yes
\end{verbatim}
\end{quote}
What is going on here?  The last positive answer is a consequence of the
fact that Prolog tables remember that the fact {\tt p(a)} is true from the
evaluation of the second query. So, when the same query is asked after {\tt
  retract}, a ``stale'' answer is returned from the tables.  Similarly,
tabling might interact poorly with {\tt assert} in the following case:
\begin{quote}
\begin{verbatim}
| ?- p(b).

no
| ?- assert(p(b)), p(b).

no
\end{verbatim}
\end{quote}
The reason for the bad answer is, again, that Prolog remembers that {\tt p(b)}
was false the last time it looked up this fact, even though this answer
has become stale after the insertion.

Fortunately, \FLORA is much more update-friendly than plain Prolog, and in
situations similar to the above it will behave correctly:
%%
\begin{quote}
\begin{verbatim}
flora2 ?- insert{o[m->v]}.

Yes

flora2 ?- o[m->v].

Yes

flora2 ?- delete{o[m->v]}, o[m->v].

No

flora2 ?- insert{o[m->v]}, o[m->v].

Yes
\end{verbatim}
\end{quote}
%%
Nevertheless, there still are problems with facts that
depend through rules on facts that were inserted or deleted.  This
problem is illustrated by the following program.
%%
\begin{quote}
\begin{verbatim}
a[b->c] :- d[e->f].  
d[e->f].
\end{verbatim}
\end{quote}
%%
Consider the following a query
%%
\begin{quote}
\begin{verbatim}
flora2 ?- a[b->c].

Yes
\end{verbatim}
\end{quote}
%%
Suppose that next we delete the fact {\tt d[e->f]}. Then we will get the
following counterintuitive results:
%%
\begin{quote}
\begin{verbatim}
flora2 ?- delete{d[e->f]}.

Yes

flora2 ?- a[b->c].

Yes
\end{verbatim}
\end{quote}
%%
The reason for this behavior is, as before, that the stale positive
answer to the query {\tt a[b->c]} has been recorded in Prolog tables.
In order to invalidate this answer it would be necessary to keep 
track of the dependencies among different facts, which Prolog currently
does not do (and it would be very hard and inefficient to keep this
information at the \FLORA level).

\index{refresh\{...\}}
%%
Nevertheless, \FLORA provides partial solution to this problem in the form
of the {\tt refresh\{...\}} operator, which lets the programmer to explicitly
remove stale answers from tables. For instance, in the above case we could
do the following:
%%
\begin{quote}
\begin{verbatim}
flora2 ?- refresh{a[b->c]}, a[b->c].

No
\end{verbatim}
\end{quote}
%%
In general, {\tt refresh\{...\}} can take a comma-separated list of facts to
be purged from the tables, and the facts can even contain unbound variables.
In the latter case, any stale call that unifies with the given facts will
be refreshed. For instance,
%%
\begin{quote}
\begin{verbatim}
flora2 ?- refresh{a[b->X], c:Y, p(z,V)@foo}.

Yes
\end{verbatim}
\end{quote}
%%
will refresh the tables for {\tt a[b->X]} and {\tt c:Y} in module {\tt
  main}, and for {\tt p(z,V)} in module {\tt foo}.

\index{abolish\_all\_tables}
%%
Sometimes it is desirable to completely get rid of all the information
stored in tables (for instance, when it is hard to track down all the facts
that might depend on the changed base facts. In such a case, the command
%%
\begin{quote}
\begin{verbatim}
flora2 ?- abolish_all_tables.
\end{verbatim}
\end{quote}
%%
can be used. However, this command is unsafe: If it is executed during the
computation of a subquery that involves an \fl molecule or a tabled
predicate, then the system might crash. (This is an unsafe, low level XSB
builtin.)  The only safe way to execute {\tt abolish\_all\_tables} is as a
\emph{separate} query.

\paragraph{Note:} The update operators {\tt {\tt insert}/delete}, etc., the {\tt
  refresh\{...\}} operator, or {\tt abolish\_all\_tables} cannot occur
under the scope of the {\tt tnot} negation operator (directly or
indirectly). If they do, XSB will likely crash. Typically it will first
issue an error message telling you that an update has been issued under the
scope of the negation operator.



\paragraph{Tabled predicates that depend on update operations.}
A related issue is that a tabled predicate (or an F-logic molecule)
might occur in the head of a rule that has an update operation in its body,
or it may be transitively dependent on such an update. Note that this is
different from the previous issue, where tabled predicates did not
necessarily depend on update operations but rather on other predicates that
were modified by these update operations.

In this case, the update operation will be executed the first time the
tabled predicate is evaluated. Subsequent calls will return the predicate truth
value from the tables, without invoking the predicate definition.
Moreover, if the update statement is non-logical ({\it i.e.},
non-backtrackable), then it is hard to predict how many times it will be
executed (due to backtracking) before it will start being ignored due to
tabling.

If \FLORA compiler detects that a tabled literal depends on an update
statement, a warning is issued, because such a dependency is most likely a
mistake. This warning is issued also for procedural methods ({\it i.e.},
Boolean methods of the form {\tt \#foo(...)}) when a tabled literal depends
on them.

There are situations, however, when dependency on an update makes perfect
sense. For instance, we might be computing a histogram of some function
by computing its values at every point and then adding it to the
histogram. When a value, $f(a)$, is computed first, the histogram is
updated. However, subsequent calls to $f(a)$ (which might be made during
the computation of other values for $f$) should not update the histogram.
In this case it makes sense to make $f/1$ into a tabled predicate, whose
definition will include an update operator. At present, the compiler will
issue a warning even in such a benign case. A future release will provide
means to exempt certain predicates and methods from such dependency checks.


\subsection{Updates and Meta-programming}

The update operators can take variables in place of literals to be inserted
and queries. For instance, 
%%
\begin{quote}
 {\tt flora2 ?-  X $\sim$ a[b->c], insert\{X\}.}
\end{quote}
%%
One use for this facility is when one module, $\tt foo$, provides methods that
allow other modules to perform update operations on objects in {\tt foo}.
For instance, $\tt foo$ can have a rule
%%
\begin{quote}
 {\tt update(X,Y) :- delete\{X\}, insert\{Y\}.}  
\end{quote}
%%
Other modules can then issue queries like
%%
\begin{verbatim}
 flora2 ?- john[salary->X]@foo, Y is X+1000,
           update(john[salary->X],john[salary->Y]).  
\end{verbatim}
%%

\subsection{Updates and Negation}

Negation applied to methods that have side effects is typically a rich source
of trouble and confusion.

\index{local scheduling in XSB}
\index{batched scheduling in XSB}
%%
First of all, applying negation to \FLORA molecules that involve
non-backtrackable updates does not have logical semantics, and thus the
programmer must have good understanding of the \emph{procedural} semantics of
\FLORA (Section~\ref{sec-flora-procedural}).
In this case, negation applied to methods or predicates that produce
side-effects through updates  or I/O is that of negation as failure
(Section~\ref{sec-negation}).

When only backtrackable updates are used, the semantics is well defined and
is provided by \emph{Transaction Logic}
\cite{trans-chapter-98,trans-tcs94}. In particular, negation is also well
defined. However, simply negating an update, \emph{A} is useless in
programming, since it simply means to jump to a random state that is not
reachable via execution of \emph{A}.  As explained in
\cite{trans-chapter-98,trans-tcs94}, negation is typically useful only in conjunction
with $\wedge$, where it acts as a constraint, or with the hypothetical
operator of possibility $\Diamond$. In most cases, when the programmer
wants to apply negation to a method that performs logical (backtrackable)
updates, he has $\tt \neg \Diamond method$ in mind, {\it i.e.}, a test to
verify that execution of {\tt method} is not possible.

%% Unimplemented -- Transaction Logic NAF
At present this operator is not implemented in \FLORA and \verb|\+ method|
or {\tt tnot method} will not produce correct results.  The difference with
the logical formula $\tt \neg \Diamond method$ is that the latter does not
change the current state of the underlying database, while \verb|\+ method|
will try to execute {\tt method}. If it succeeds, then \verb|\+ method|
will fail, but the changes made by {\tt method} will not be undone.


\subsection{Words of (Extreme) Caution}

\index{backtracking over updates in XSB}
%%
XSB has certain well-known bugs, which are very hard to fix and which can
corrupt its internal state irreparably. One such thing is the issue of
backtracking over updates; especially over deletions.

Here we are not talking about \FLORA's backtrackable updates, which are
implemented properly and are safe. Instead, a problem arises when
backtracking over updates happens in the XSB program into which \FLORA
programs are compiled. If this happens, the program might crash or produce
random, unexplainable results. Unfortunately, it is not easy to spot such
cases by just looking at a source code of your \FLORA program, because much
is done by the runtime system behind the scene. Here we provide high-level
tips that can help avoid the problem.

First, make sure that when you use \emph{non}-backtrackable updates and
your program backtracks over them, deleted facts are never queried again.
This situation is analogous to backtracking over updates in XSB.

Second, \FLORA may backtrack over updates if your top-level query calls an
update directly or indirectly. This may happen when the interpreter is in
the all-answers mode ({\tt flAll}) even if the logic of your program does
not call for backtracking. Indeed, in the venerable Prolog way all answers
can be obtained only by backtracking, and this is what \FLORA does behind
the scene. In this situation, backtrackable updates are as vulnerable as
non-backtrackable ones because after each iteration that returns an answer
to the top level all updates are committed and can no longer be backtracked
over (due to the aforesaid XSB bug).

The only (more or less) sure remedy in this situation is to ensure that
backtracking does not occur at the top level. For instance, if the
top-level query is a procedural method, then semantically it would be
correct to put a cut at the end of the query:
%%
\begin{verbatim}
 ?- X[#some_method(SomeArgs)], something, !.
\end{verbatim}
%%
\index{local scheduling in XSB}
\index{batched scheduling in XSB}
%%
This will work if XSB is configured for the \emph{local} scheduling
strategy (which is currently the default). If it is configured for
the \emph{batched} strategy (see XSB manual for how to do it), then the
above trick will work only is {\tt something} does not have tabled
predicates or those predicates are fully evaluated by the time {\tt
  something} succeeds (as is the case, for example, when those predicates
are under the scope of {\tt findall}).

In some cases cuts can be also inserted in the rules that define procedural
methods if the logic of the program ensures that backtracking over those
methods should not occur. 


\section{Insertion and Deletion of Rules into Modules}

\index{rule insertion}
\index{rule deletion}
\index{rule!static}
\index{rule!dynamic}
\index{dynamic rule}
\index{static rule}
%%
\FLORA supports \emph{non-backtrackable} insertion of rules into modules
as well as deletion of inserted rules.  A \FLORA module gets created
when a program is loaded into it, as described in
Section~\ref{sec-shell-commands}, or it can be created using the
primitive {\tt newmodule}. Subsequently, rules can be added to an
existing module. Rules that are inserted via the {\tt insertrule}
command are called \emph{dynamic} and the rules loaded using the {\tt
flLoad} or {\tt [...]} commands are called \emph{static} or
\emph{compiled}.  Dynamic rules can be deleted via the {\tt deleterule}
command. As mentioned in Section~\ref{sec-updates}, \FLORA predicates
and molecules can have both static and dynamic parts and no special
declaration is required to make a predicate dynamic. The same molecule
or a predicate can be defined by a mixture of static or dynamic rules.

In this section, we will first look at the syntax of creating new
modules.  Then we will describe how to insert rules and delete
rules. Finally, we address other related issues, including tabling,
indexing, and the cut.


\subsection{Creating a New Module at Run-time}


\index{newmodule/1}
%%
The syntax for creating a new module is as follows:
{\tt
\begin{quote}
\emph{newmodule}\{\emph{modulename} [, \emph{equalityMaintenanceLevel}]\}
\end{quote}
}
\index{equality maintenance level}
%%
\noindent
where {\tt equalityMaintenanceLevel} can be {\tt none}, {\tt basic}, or {\tt
  flogic}, with {\tt none} being the default (see
  Section~\ref{sec-eqmaintain} for the details about equality maintenance
  in \FLORA). This creates a
blank module with the given name and the equality maintenance level,
provided that no existing module is using the same name. A module
created using {\tt newmodule} can be used exactly the same way as the
modules that are created by loading user programs.


\subsection{Inserting Rules}
\label{sec-insertingrule}

\index{insertrule\_a}
\index{insertrule\_z}
%%
Dynamic rules can be inserted before all static rules, using the primitive
{\tt insertrule\_a}, or after all static rules, using the primitive {\tt
  insertrule\_z}. Several rules can be inserted in the same command. The
syntax of inserting a list of rules is as follows: {\tt
\begin{quote}
\emph{insruleop}\{\emph{rulelist}\}
\end{quote}
}
\noindent
where \emph{insruleop} is either {\tt insertrule\_a} or {\tt
  insertrule\_z}, rulelist is a comma-separated list of rules.  The rules
  being inserted \emph{should not} terminate with a
period (unlike the static program rules):
%%
\begin{quote}
\begin{verbatim}
flora2 ?- insertrule_a{X:student:-enroll(X,_T)}.
\end{verbatim}
\end{quote}
%%
The above inserts the rule {\tt X:student :- enroll(X,\_T)} in
front of the current module.

If a rule is meant to be inserted into a module other than the current one,
then the rule needs to be parenthesized \emph{and} the module name must be
attached using the usual module operator {\tt @}. If \emph{several} rules
need to be inserted using the same command, each rule must be
parenthesized.  For example, the following statement inserts the same rule
into two different modules: the current one and into module {\tt mod1}.
%%
\begin{quote}
\begin{verbatim}
flora2 ?- insertrule_a{(X:student:-enroll(X,_T)),
                       (X:student:-enroll(X,_T))@mod1}.
\end{verbatim}
\end{quote}
As a result, the rule {\tt X:student:-enroll(X,\_T)} will be inserted in
front of each of these two modules.
For this to be executed successfully, the module {\tt mod1} must already
exist.


\subsection{Deleting Rules}


\index{deleterule\_a}
\index{deleterule\_z}
\index{deleterule}
%%
Rules inserted dynamically using {\tt insertrule\_a} can be deleted using
the primitive {\tt deleterule\_a}, and rules inserted using {\tt
  insertrule\_z} can be deleted using the primitive {\tt deleterule\_z}. If
the user wishes to delete a rule that was previously inserted using either
{\tt insertrule\_a} or {\tt insertrule\_z} then the premitive{\tt
  deleterule} can be used. Similarly to rule insertion, several rules can be
deleted in the same command:
{\tt
\begin{quote}
\emph{delruleop}\{\emph{rulelist}\}
\end{quote}
}
\noindent
where \emph{delruleop} is either {\tt deleterule\_a} or {\tt deleterule\_z}
and \emph{rulelist} is a comma-separated list of rules. Rules in the list
mast be enclosed in parentheses and \emph{should not} terminate with a
period.

To delete the rules inserted in the second example of
Section~\ref{sec-insertingrule}, we can use
%%
\begin{quote}
\begin{verbatim}
flora2 ?- deleterule_a{(X:student:-enroll(X,_T)),
                       (X:student:-enroll(X,_T))@mod1}.
\end{verbatim}
\end{quote}
or
%%
\begin{quote}
\begin{verbatim}
flora2 ?- deleterule{(X:student:-enroll(X,_T)),
                       (X:student:-enroll(X,_T))@mod1}.
\end{verbatim}
\end{quote}

The head of a rule to be deleted cannot be a variable and the module
associated with any rule must be bound. For example, in
%%
\begin{quote}
\begin{verbatim}
flora2 ?- deleterule{(X:-Y@M1)@M2}.
\end{verbatim}
\end{quote}
both X and M2 must be bound. However, Y and M1 can be unbound.

\subsection{Tabling and Indexing of Dynamically Defined Predicates}

If a rule needs to be inserted for a new predicate (which was not seen
before), the system needs to know whether the predicate is to be tabled
and how it should be indexed. By default, new predicates are not tabled and
are indexed on the first argument. To change that,
\FLORA provides instructions to table and index new predicates in
modules. We will describe the syntax of the tabling and
indexing instructions. 

\paragraph{Tabling Dynamically Defined Predicates.} Suppose we have the
following program: 
\begin{quote}
\begin{verbatim}
?- newmodule{mod1}. 
?- insertrule_a{(tc(X,Y):-e(X,Y))@mod1, (tc(X,Y):-tc(X,Z),e(Z,Y))@mod1}.
?- insert{e(a,b)@mod1, e(b,c)@mod1}.
?- tc(X,Y)@mod1.
\end{verbatim}
\end{quote}
\noindent
This program is not going to terminate unless we table {\tt tc/2} in {\tt
  mod1}. To do so, the following executable directive can be used:
%%
\begin{quote}
\begin{verbatim}
?- table(mod1,tc/2).
\end{verbatim}
\end{quote}
%%
The module name is optional in the tabling directive. For instance,
%%
\begin{quote}
\begin{verbatim}
?- table(tc/2).
\end{verbatim}
\end{quote}
%%
tables {\tt tc/2} in the current module.  If we want to table more than one
predicates for the same module in one tabling instruction, the predicates
should be enclosed in parentheses. For example,
\begin{quote}
\begin{verbatim}
?- table(mod2,(p/1/2,tc/2)). 
\end{verbatim}
\end{quote}
\noindent
tables {\tt p/1/2} and {\tt tc/2} in module {\tt mod2}.
Please refer to Section~\ref{sec-tabling-flora} for more details on tabling
in \FLORA.

Note that when a tabling instruction is executed, there should be no rules
(either static or inserted) that define the same predicate. Otherwise,
the tabling directive will have no effect.
The module must also exist prior to the execution of the tabling
instruction. For instance,
\begin{quote}
\begin{verbatim}
?- newmodule{mod1}. 
?- table(mod1,tc/2).
?- insertrule_a{(tc(X,Y):-e(X,Y))@mod1, (tc(X,Y):-tc(X,Z),e(Z,Y))@mod1}.
\end{verbatim}
\end{quote}
will work, but if the newmodule/2 instruction were not executed prior then
a runtime error will result.

\paragraph{Indexing Dynamically Defined Predicates} Sometimes we need to
index inserted rules in some module and \FLORA provides an indexing instruction
for this purpose. For instance,
\index{{\tt index} compiler directive}
\index{compiler directive!{\tt index}}
\begin{quote}
\begin{verbatim}
?- newmodule{mod1}. 
?- (index 3-2)@mod1.
\end{verbatim}
\end{quote}
\noindent
says that all HiLog predicates of arity 3 should be indexed on
argument 2 provided that currently there are no such predicates defined.

The module specification can be omitted, if {\tt mod1} is the default
module {\tt main}, and there can be more than one arity-argument pair in
one indexing instruction.

\paragraph{A Problem with Cuts} What is behind rule insertion is pretty
simple. As we know from Section~\ref{sec-updates}, every predicate and
object has a base part and a derived part. Now we further divide the
derived part into three sub-parts: the \emph{dyna sub-part} (the part that
precedes all other facts in the predicate), the static sub-part, and the
\emph{dynz sub-part}. All rules inserted using {\tt insertrule\_a} go into
the dyna sub-part; all the rules in the program file go into the static
sub-part; and all the rules inserted using {\tt insertrule\_z} go into the
dynz sub-part.

This works well when there are no cuts in rules inserted by {\tt
  insertrule\_a}. With the cuts, the program might not
behave as expected. For example, if we have the following program:
\begin{quote}
\begin{verbatim}
p(X) :- r(X).
r(a).
q(b).
?- insertrule_a{p(X) :- q(X),!}.
?- p(X).
\end{verbatim}
\end{quote}
\noindent
we normally expect the answer to be {\tt b} only. However, \FLORA will
return two answers, {\tt a} and {\tt b}. This is because the cut affects
only the dynamic part of p(X), instead of all the rules for {\tt p/1}.



\section{Control Flow Statements}\label{sec:control}

\FLORA supports a number of control statements that are commonly used in
procedural languages. These include {\tt if - then - else} and 
a number of looping constructs.

\paragraph{if-then-else.}
%%
\index{if-then-else}
%%
This is the usual conditional control flow
construct supported by most programming languages.  For instance,
%%
\begin{quote}
 \tt
 ?- if (foo(a),foo2(b)) then (abc(X),cde(Y)) else (qpr(X),rts(Y)).
\end{quote}
%%
Here the system first evaluates {\tt foo(a),foo2(b)} and, if true,
evaluates {\tt abc(X),cde(Y)}. Otherwise, it evaluates {\tt qpr(X),rts(Y)}.
Note that {\tt if}, {\tt then}, and {\tt else}
bind stronger than the conjunction ``,'', the
disjunction ``;'', etc. This is why the parentheses are needed in the above
example.


The abbreviated {\tt if-then} construct is also supported.  However, it
should be mentioned that \FLORA gives a different semantics to {\tt
  if-then} than Prolog does. In Prolog,
%%
\begin{verbatim}
    ..., (Cond -> Action), Statement, ...  
\end{verbatim}
%%
fails if {\tt Cond} fails and {\tt Statement} is not executed. If the
programmer wants such a conditional succeed even if {\tt Cond} fails, then
{\tt (Cond->Action; true)} must be used. Our experience shows, however,
that it is the latter form that is used in most cases in Prolog
programming, so in \FLORA the conditional
%%
\begin{verbatim}
    ..., if Cond then Action, Statement, ...  
\end{verbatim}
%%
succeeds even if {\tt Cond} fails and {\tt Statement} is executed next. To
fail when {\tt Cond} fails, one should explicitly use {\tt else}:
{\tt if Cond then Action else fail}. More precisely:
%%
\begin{itemize}
  \item  {\tt if Cond then Action} fails if and only if {\tt Cond} succeeds
    but {\tt Action} fails.
  \item {\tt if Cond then Action else Alternative} succeeds if and only if 
    {\tt Cond} and {\tt Action} both succeed or {\tt Cond} fails while
    {\tt Alternative} succeeds.
\end{itemize}
%%

Note that the {\tt if}-statement is friendly to backtrackable updates in
the sense that backtrackable updates executed as part of an {\tt
  if}-statement would be undone on backtracking, unless the changes done by
such updates are explicitly committed using the {\tt commit} method of the
system module {\tt flora(db)} (see Section~\ref{sec:storage-ctl}).

\paragraph{unless-do.}
%%
\index{unless-do}
%%
This construct is an abbreviation of {\tt if Cond then true else Action}.
If {\tt Cond} is true, it succeeds without executing the action.
Otherwise, it executes {\tt Action} and succeeds or fails depending on
whether {\tt Action} succeeds or fails.

\paragraph{while-do and do-until.}
%%
\index{while-do}
\index{until}
\index{do-until}
%%
These loops are similar to those in C, Java, and the like.
In {\tt while Condition do Action}, {\tt Condition} is evaluated before each
iteration. If it is true, {\tt Action} is executed. This statement succeeds
even if {\tt Condition} fails at the very beginning. The only case when this
loop fails is when {\tt Condition} succeeds, but {\tt Action} fails (for all
possible instantiations).

The loop {\tt do Action until Condition} is similar, except that {\tt
  Condition} is evaluated after each iteration. Thus, {\tt Action} is
guaranteed to execute at least once.

These loops work by backtracking through {\tt Condition} and terminate when
all ways to satisfy it have been exhausted (or when {\tt Action} fails).
The loop condition should \emph{not} be modified inside the loop body.  If
it is modified ({\it e.g.}, new facts are inserted in a predicate that {\tt
  Condition} uses), XSB does not guarantee that the changes will be seen
during backtracking and thus the result of such a loop is indeterminate.
If you need to modify {\tt Condition}, use the statements {\tt while-loop}
and {\tt loop-until} described below.

The above loop statements have special semantics for backtrackable updates.
Namely, changes done by these types of updates are \emph{committed} at the
end of each iteration. Thus, if {\tt Condition} fails, the changes done by
backtrackable updates that occur in {\tt Cond} are undone. Likewise, if
{\tt Action} fails, backtracking occurs and the corresponding updates are
undone. However, changes made by backtrackable update statements during the
previous iteration remain committed. If the current iteration finishes then
its changes will also remain committed regardless of what happens during
the next iteration.


\index{while-loop}
\index{until}
\index{loop-until}
%%
\paragraph{while-loop and loop-until.}
This pair of loop statements is similar to {\tt while-do} and {\tt
  do-until}, except that backtrackable updates are \emph{not} committed
after each iteration. Thus, failure of a statement following such a loop
can cause all changes made by the execution of the loop to be undone.  In
addition, {\tt while-loop} and {\tt loop-until} do not work through
backtracking. Instead, they execute as long as {\tt Condition} stays true.
Therefore, the intended use of these loop statements is that {\tt Action}
in the loop body must modify {\tt Condition} and, eventually, make it false
(for instance, by deleting objects or tuples from some predicates mentioned
in {\tt Condition}).
  
As in the case of the previous two loops, {\tt while-loop} and
{\tt loop-until} succeed even if {\tt Condition} fails right from the
outset. The only case when these loops fail is when {\tt Action} fails ---
see Section~\ref{sec-updates-pitfalls} for ways to avoid this ({\it i.e.},
to continue executing the loop even when {\tt Action} fails) and the
possible pitfalls.


The statements {\tt while-loop} and {\tt loop-until} are more
expensive (both time- and space-wise) than {\tt while-do} and {\tt
  do-until}. Therefore, they should be used only when full backtrackability
of updates is required. In particular, such loops are rarely used with
non-backtrackable updates.


\subsection{Some Subtleties of the Semantics of the Loop Statements}
\label{sec-updates-pitfalls}

Observe that {\tt while-loop} and {\tt loop-until} assume that the
condition in the loop is being updated inside the loop body.  Therefore,
the condition must \emph{not} contain tabled predicates.  If such
predicates are involved in the loop condition, the loop is likely to
execute infinitely many times.

Also, keep in mind that in any of the four loop statements, if {\tt Action}
fails before {\tt Condition} does, the loops terminate and fail. Therefore,
if the intention is that the loop should continue even if {\tt Action}
fails, use the
%%
\begin{verbatim}
    (Action ; true)  
\end{verbatim}
%%
idiom in the loop body. In case of {\tt while-do} and {\tt do-until},
continuing execution of the loop is not a problem, because these loops work
by backtracking through {\tt Condition} and the loop will terminate when
there is no more ways to backtrack. However, in case of {\tt while-loop}
and {\tt loop-until}, there is a potential pitfall. The problem is that
these loops will continue as long as there is a way to satisfy {\tt
  Condition}.  If condition stays true, the loop continues forever.
Therefore, the way to use these loops is to make sure that {\tt Condition}
is modified by {\tt Action}. If {\tt Action} has non-backtrackable updates,
the user must ensure that if {\tt Action} fails then {\tt Condition} is
modified appropriately anyway (for otherwise the loop will never end).
If {\tt Action} is fully backtrackable and it fails, then using the
{\tt (Action ; true)} idiom in the loop body will definitely make the loop
infinite, so the use of this idiom in the body of {\tt while-loop} and {\tt
  loop-until} is dangerous if there is a possibility that {\tt Action} will
fail, and it is useless if the action is expected to always succeed.



\section{Negation} \label{sec:negation}


\FLORA supports two kinds of negation: the usual Prolog's \emph{negation as
  failure} \cite{Cla78} and negation based on \emph{well-founded semantics}  
\cite{gelder-alternating-89,gelder-ross-schlipf-91}. Both types of negation
are compiled into clauses that invoke the corresponding operators in
Prolog.

\subsection{Two Operators for Negation}\label{sec-negation}
\index{tnot}
\index{\NAF}
%%
Negation as failure is specified using the operator
\NAF.  Negation based on well-founded semantics is specified using the
operator {\tt tnot}.  The well-founded negation, {\tt tnot}, is applied to
predicates that are tabled or to F-molecules that do not contain procedural
methods (which are the only methods that are not tabled).

For non-tabled predicates and procedural methods, \NAF is usually
recommended (we assume that the user is familiar with the use of negation
as failure in Prolog programs).  It is also possible to apply {\tt tnot} to
these types of queries.  The effect is that the system will first generate
a new tabled predicate to hold the results of the query and then apply {\tt
  tnot} to this new predicate. This may lead to incorrect results,
if the negated formula is defined in terms of an update
primitive (see Section~\ref{sec-updates} for a discussion of this issue).

For more information on the implementation of the negation operators in XSB
we refer the reader to the XSB manual.

Both \NAF and {\tt tnot} can be used as operators inside and outside \FLORA
molecules. For instance,
%%
\begin{alltt}
   ?- tnot p(a).
   ?- \NAF p(a).
   ?- tnot X[foo->bar, bar->>foo].
   ?- X[tnot foo->bar, bar->>foo, \NAF #p(Y)].
\end{alltt}
%%
are all legal. Note that \NAF applies only to non-tables constructs, such
as non-tabled \FLORA predicates and procedural methods.

We should warn against one pitfall however. Sometimes it is necessary to
apply negation to several separate literals and write something like
%%
\begin{alltt}
   ?- \NAF(p(a),q(X)).
   ?- tnot(p(a),q(X)).
   ?- tnot(X[foo->bar], X[bar->>foo]).
\end{alltt}
%%
This is incorrect however, since in this context \FLORA (and Prolog as
well) will interpret {\tt tnot} and \NAF as predicates with two arguments,
which are undefined. The correct syntax is:
%%
\begin{alltt}
   ?- \NAF((p(a),q(X))).
   ?- tnot((p(a),q(X))).
   ?- tnot((X[foo->bar], X[bar->>foo])).
\end{alltt}
%%
{\it i.e.}, an additional pair of parentheses is needed to indicate that
the sequence of literals form a single argument.

\subsection{True vs. Undefined Literals}

The fact that the well-founded semantics for negation is three-valued
brings up the question of what exactly does the success or failure of a
call means. Is undefinedness covered by a success? failure?  none?  The way
this is implemented in XSB is such that a call to a literal, $P$, succeeds
if and only if $P$ is true \emph{or} undefined.  Therefore, it is sometimes
necessary to be able to separate true and undefined facts. In XSB, this
separation is accomplished by a call to the {\tt get\_residual/2}
predicate, which is not easy to use directly in \FLORA.  To simplify this
use, \FLORA provides a wrapper called {\tt table\_state/2}, which is a
predicate provided by the \FLORA system module {\tt sys}.  A call to
%%
\index{table\_state/2}
%%
\begin{verbatim}
   table_state(Call,List)@flora(sys)  
\end{verbatim}
%%
succeeds if and only if {\tt Call} is either true or undefined according to
the well-founded semantics. Moreover, {\tt Call} is true iff {\tt List} is
nil ({\it i.e.}, {\tt []}). Thus, {\tt table\_state(Call,[])@flora(sys)}
succeeds if and only if {\tt Call} is true.



\section{Constraint Solving}\label{sec-clp}
\index{Constraint solving}

\FLORA provides an interface to constraint solving capabilities of the
underlying Prolog engine. Currently XSB supports linear constraint solving
over the domain of real numbers (CLPR). However, we must warn that the XSB
implementation of CLPR has many rough spots -- do not say that we did not
warn! To pass a constraint to a constraint solver in the body of a \FLORA
rule (or query), simply include it inside curly braces.

Here is a 2-minute introduction to CLPR. Try the following program:
%%
\begin{verbatim}
  ?- insert{p(1.0),p(2.0),p(3.0)}.
  ?- X>0, X<5, p(X).
\end{verbatim}
%%
Intuitively, one would expect 2.0 and 3.0 as answers. However, if you
actually try to run this
program, you will be disappointed --- an error message will be
reported:
%%
\begin{quote}
 ++Error[XSB]: [Runtime/P] Type Error: Uninstantiated Arithmetic Expression \\
 Aborting...
\end{quote}
%%
This happens because ordinarily Prolog views {\tt >/2} and {\tt </2} as
predicates with infinite number of facts. Since there are infinite number
of values for {\tt X} that make {\tt X > 0} true, it reasons, the query
does not make sense.

Constraint logic programming takes a different view: it considers {\tt X>0,
  X<5} to be a \emph{constraint} on the set of solutions of the query {\tt
  p(X)}. This approach allows Prolog to return meaningful solutions to the
above query. However, the user must explicitly tell the system which view
  to take --- the ``dumb'' view that treats arithmetic built-ins are
  infinite predicates or a ``smart'' view, which treats them as constraints.
  The smart view is indicated by enclosing constraints in curly
  braces. Thus, the above program becomes:
%%
\begin{verbatim}
  ?- [clpr].          % must be loaded prior to the use of constraint solver
  ?- insert{p(1.0),p(2.0),p(3.0)}.
  ?- {X>0, X<5}, p(X).
  
  X = 2.000000e+00

  X = 3.000000e+00

  2 solution(s) in 0.0000 seconds
\end{verbatim}
%%
Note that the package {\tt clpr} must be loaded in advance.

It should be kept in mind that the constraint solver is very picky about
the type of values it is willing to work with. It insists on floats and
will refuse to convert integers to floats. For instance, if the insert
statement were as follows:
%%
\begin{verbatim}
   ?- insert{p(1),p(2),p(3)}.  
\end{verbatim}
%%
then the user would have been rewarded with the following obscure message:
%%
\begin{quote}
  type\_error(\_h5356 = 3,2,a real number,3)
\end{quote}
%%
It is trying to tell the user that a floating number is expected and the
integer 3 will not do.

\section{Exception Handling}\label{sec-errors}

\index{catch\{...\}}
\index{throw\{...\}}
%%
\FLORA supports the common catch/throw paradigm through the primitives {\tt
  catch\{Goal,Error,Handler\}} and {\tt throw\{Error\}}.  Here {\tt Goal}
can be any \FLORA query, {\tt Error} is a HiLog (or Prolog) term, and {\tt
  Handler} is a \FLORA query that will be called if an exception that
unifies with {\tt Error} is thrown during the execution of {\tt Goal}. For
instance,

%%
\begin{verbatim}
someQuery(Y) :- Y[value->X], X > 0, doSomethingUseful(X).  
someQuery(Y) :- Y[value->X], X =< 0, throw{myError('X non-positive', X)}.

?- p(Y), catch{someQuery(Y), myError(Reason,X), handleException(Reason,X)}.

handleException(Reason,X) :- format('~w: X=~w~n',[Reason,X])@prolog(format), fail.
\end{verbatim}
%%
The {\tt catch} construct first calls the query {\tt someQuery/1}. If {\tt
  X} is positive then nothing special happens, the query executes normally,
and {\tt catch\{...\}} has no effect.  However, if {\tt X} turns out to be
non-positive then the query throws an exception {\tt myError('X {\tt
    non-positive', X)}}, where {\tt X} is bound to the non-positive value
that was deemed by the logic of the program to be an exceptional situation.
The term thrown as an exception is then unified with the term {\tt
  myError(Reason,X)} that was specified in {\tt catch\{...\}}. If the two
terms do not unify ({\it e.g.}, if the error specified in {\tt catch} was
something like {\tt myError(foo,X)}) then the exception is propagated
upwards and if the user program does not catch it, the exception will
eventually be caught by the \FLORA command loop. In out concrete case,
however, the thrown term and the exception specified in {\tt catch} unify
and thus {\tt handleException/2} is called with {\tt Reason} and {\tt X}
bound by this unification.

The queries {\tt Goal} and {\tt Handler} in the {\tt catch\{...\}}
primitive can be \fl molecules, not just predicates. However, {\tt Error}
--- both in {\tt catch} and in {\tt throw} --- must be HiLog or Prolog
terms.  No molecules are allowed inside these terms unless they are
reified. That is, {\tt myError('problem found', a[b->c])} will result in a
parser error, but an exception of the form {\tt myError('problem found',
  \$\{a[b->c]\})} is correct because the molecule is reified.

Some exceptions are thrown by \FLORA itself, and applications might want
to catch them:
%%
\begin{itemize}
\item {\tt '\_\$flora\_undefined'(MethodSpec,ErrMsg)} --- thrown when undefinedness checking is
  in effect (see Section~\ref{sec-undef}) and an attempt is made to execute
  an undefined method or predicate. The first argument in the thrown
  exception is a specification of the undefined predicate or the method 
  that caused the exception. The second argument is the error message.
\item {\tt '\_\$flora\_abort'} or {\tt '\_\$flora\_abort'(Message)} ---
  thrown when \FLORA encounters other kinds of errors. This exception comes
  in two flavors: with an error message and without.

  A user program can also throw this exception when immediate exit to the
  top level is required. The safest way to do so is by calling
  {\tt abort(Message)@flora(sys)}, as explained in
  Section~\ref{sec-flora-syscontrol}.
\end{itemize}
%%
\index{FLORA\_UNDEFINED\_EXCEPTION}
\index{FLORA\_ABORT}
%%
These exceptions are defined by \FLORA under the symbolic names {\tt
  FLORA\_UNDEFINED\_EXCEPTION} and {\tt FLORA\_ABORT}. When a user
application needs to catch these errors we recommend to include the file
{\tt flora\_exceptions.flh} in the program and use the above symbolic
names. For instance,
%%
\begin{verbatim}
#include "flora_exceptions.flh"
?- ..., catch{myQuery(Y),FLORA_UNDEFINED_EXCEPTION(MethSpec,_Msg),myHandler(MethSpec)}.
?- ..., catch{yourQuery(Y),FLORA_ABORT(Message),yourHandler(Message)}.
\end{verbatim}
%%

The {\tt catch\{...\}} primitive can also catch exceptions thrown by the
underlying Prolog system. For this to happen you need to know the format
({\it i.e.}, the exact terms) of the exceptions thrown by Prolog (which can
be found in the manual). One exception that some sophisticated \FLORA
program might need to catch is thrown by Prolog when a \FLORA application
calls an undefined Prolog predicate. The format of the corresponding
exception term is
%%
\begin{verbatim}
error(undefined_predicate(PredName,Arity,Module)  
\end{verbatim}
%%
where {\tt Module} is the name of the Prolog (not \FLORA) module in which
the predicate {\tt PredName/Arity} was called. If you call a Prolog predicate
in a Prolog module that does not exist, then Prolog will throw the exception
%%
\begin{verbatim}
error(existence_error(module,Module)  
\end{verbatim}
%%
Note that the thrown exception will contain a module name but not the predicate.

Although Prolog (obviously) throws Prolog terms as exceptions, there is no
need to worry about making sure that the terms caught by the \FLORA {\tt
  catch\{...\}} primitive are also specified as Prolog terms. he primitive
takes care of the Prolog-to-HiLog conversion automatically.


\section{Debugging User Programs}\label{sec-debugging}
\index{debugging}

\FLORA comes with an interactive, Prolog-style debugger, which is described
in Appendix~\ref{sec-debugger}. The compiler makes many useful checks, such
as the occurrence of singleton variables, which is often an error (see
Section~\ref{sec-basic-flogic}). More checks will be provided in the future.

In addition, it is possible to tell \FLORA to perform various run-time
checks, as described below.

\subsection{Checking for Undefined Methods and Predicates}\label{sec-undef}

\FLORA has support for checking the invocation of undefined methods and
predicates at run time. This feature can be of great help because a trivial
typo can cause a method/predicate call to fail, sending the programmer on a
wild goose chase after a hard-to-find bug. It should be noted, however,
that enabling these checks can slow the runtime by up to 2 times (typically
about 50\% though), so we recommend this to be done during debugging only.

\index{check\_undefined/1}
\index{check\_undefined/2}
\index{debug class}
%%
To enable runtime checks for undefined invocations, \FLORA provides two
methods, which can be called at any time during program execution (and thus
enable and disable the checks dynamically):
%%
\begin{verbatim}
    ?- debug[#check_undefined(Flag)]@flora(sys).
    ?- debug[#check_undefined(Flag,Module)]@flora(sys).
\end{verbatim}
%%
The argument {\tt Flag} can be {\tt on}, {\tt off}, or it can be a variable.
The argument {\tt Module} must be a valid loaded flora module name 
or it can be a variable. When the flag argument is {\tt on}, the first
method turns on the checks for undefinedness in all modules. The second
method does it in a specific module. When the flag argument is off, the
above methods turn the undefinedness checks off globally or in a specific
module, respectively.

When either {\tt Flag} or {\tt Module} (or both) is a variable, the above
methods do not change the way undefined calls are treated. Instead, they
query the state of the system. For instance, in
%%
\begin{verbatim}
    ?- debug[#check_undefined(Flag)]@flora(sys).
    ?- debug[#check_undefined(Flag,foo)]@flora(sys).
    ?- debug[#check_undefined(on,Module)]@flora(sys).
\end{verbatim}
%%
the first query binds {\tt Flag} to {\tt on} or {\tt off} depending on
whether the checks are turned on or off globally. The second query reports
on the state of the undefinedness checks in \FLORA module {\tt foo}, while
the third query tells in which modules these checks are turned on.

\index{catch\{...\}}
%%
The undefinedness exception in \FLORA can be caught using \FLORA's {\tt
  catch\{...\}} builtin. For instance, suppose
$FOO$ is a predicate or an F-molecule whose execution might trigger the
undefinedness exception. Then we can catch this exception as follows:
%%
\begin{verbatim}
#include "flora_exceptions.flh"

  ..., catch{FOO, FLORA_UNDEFINED_EXCEPTION(Call,ErrorMessage), handler(Call)}, ...
\end{verbatim}
%%
Here {\tt FLORA\_UNDEFINED\_EXCEPTION} is the exception name defined in the
\FLORA system file {\tt flora\_exceptions.flh}, which must be included as
shown.
The predicate {\tt handler/1} is user-defined (can be a molecule as well),
which will be called when an undefinedness exception occurs. The variable
{\tt Call} will be bound to an internal representation of the method or
predicate call that caused the exception. For instance, if we define
%%
\begin{verbatim}
  handler(_) :- !.  
\end{verbatim}
%%
then the undefinedness exception that occurs while executing $FOO$ will be
ignored and the call to $FOO$ will succeed.


\paragraph{Undefinedness check and meta-programming.}
We should note one subtle interaction between these checks and
meta-programming. Suppose your program does not have any class membership
facts and the undefinedness checks are turned on. Then the meta-query
%%
\begin{quote}
 {\tt
 ?- a:X.
 }
\end{quote}
%%
would cause the following error:
%%
\begin{quote}
 ++Error[FLORA]: Undefined class \_:\_ in user module main  
\end{quote}
%%
Likewise, if the program does not have any definitions for set-valued
methods, the query {\tt ?- X[Y->>Z].} would cause an error. This might be
not what you expected because the program in question might be
\emph{exploring} the schema or the available data, and the intention in the
above cases might be to fail rather than to get an error.

One way of circumventing this problem is to insert some weird facts into the
database and special-case them in the program. For instance, you could put
the following facts into the program to silence the above errors:
%%
\begin{verbatim}
    ads_asd_fsffdfd : ads_asd_fsffdfd.
    ads_asd_fsffdfd[ads_asd_fsffdfd ->> ads_asd_fsffdfd].
\end{verbatim}
%%
You can then arrange the logic of your program so that anything that contains
{\tt ads\_asd\_fsffdfd} is discarded.

Another way to circumvent  the problem is to turn the undefinedness checks
off temporarily. For instance, suppose the query {\tt ?- X:a} causes
unintended undefinedness error in module {\tt foo}. Then we can avoid the
problem by posing the following query instead:
%%
\begin{verbatim}
 ?- debug[#check_undefined(off,foo)]@flora(sys),
    X:a,
    debug[#check_undefined(on,foo)]@flora(sys).
\end{verbatim}
%%

\index{catch\{...\}}
%%
The third way is to ignore the exception using \FLORA's {\tt catch\{...\}}
builtin (note the curly braces):
%%
\begin{verbatim}
#include "flora_exception.flh"

 ?- catch{X:a, FLORA_UNDEFINED_EXCEPTION(_,_)@prolog(), true}.
\end{verbatim}
%%

\paragraph{Undefinedness check and update operators.}
Although undefinedness checking can be turned on and off at will, it cannot
always capture all cases correctly. Namely, if an insert or delete
statement is executed while undefinedness checking is off, the
corresponding methods will not be properly captured an spurious
undefinedness errors might result.
For instance, 
%%
\begin{verbatim}
?- insert{a[meth->b]}, delete{a[meth->b]}.
?- debug[#check_undefined(on)]@flora(sys).
\end{verbatim}
%%
Then the query {\tt ?- a[meth->b]} will cause the undefinedness error. However,
%%
\begin{verbatim}
?- insert{a[meth->b]}, delete{a[meth->b]}.
?- debug[#check_undefined(on)]@flora(sys).
?- a[meth->b].
\end{verbatim}
%%
will not flag the method {\tt meth} as undefined.


\subsection{Type Checking}\label{sec-typechecking}

\index{type checking}
%%
%% Unimplemented -- type checking
Although \FLORA allows specification of object types through signatures,
type correctness is not checked automatically.
A future versions of \FLORA might support some form of run-time type
checking. Nevertheless, run-time type checking is possible even now,
although you should not expect any speed here and this should be done
during debugging only.

Run-time type checking is possible because \fl naturally supports powerful
meta-programming, although currently the programmer has to do some work to
make type checking happen.  For instance, a programmer can write simple
queries to check the types of methods that might look suspicious.  Here is
one way to construct such a type-checking query:
%%
\begin{verbatim}
scalar_type_incorrect(O,M,R) :- O[X->R], O:C, C[X=>D], tnot R:D.
?- scalar_type_incorrect(obj,meth,Result).
\end{verbatim}
%%
Here, we define what it means to violate type checking using the usual
\fl semantics. The corresponding predicate can then be queried. A
``no'' answer means that the corresponding attribute \emph{does not}
violate the typing rules.

In this way, one can easily construct special purpose type checkers.  This
feature is particularly important when dealing with \emph{semistructured}
data. (Semistructured data has object-like structure but normally does not
need to conform to any type; or if it does, the type would normally cover
only certain portions of the object structure.) In this situation, one
might want to limit type checking only to certain methods and classes,
because other parts of the data might not be expected to have regular
structure.


\section{Optimizations}

\paragraph{Left-to-right processing.}
The first rule in improving the performance of \FLORA programs is to
remember that query evaluation proceeds from left to right. Therefore it is
generally advisable to place subgoals with smaller answer sets as close to
the left of the rule body as possible. And, like in databases, Cartesian
products should be avoided at all costs.

\paragraph{Nested molecules and path expressions.}
\FLORA compiler makes decisions about
where to place the various parts of complex F-logic molecules, and the
programmer can affect this placement by writing molecules in various ways.
For instance,
%%
\begin{verbatim}
    ?- ..., X[attr1 ->> Y, attr2->>Y], ...
\end{verbatim}
%%
is translated as
%%
\begin{verbatim}
    ?- ..., X[attr1 ->> Y], X[attr2->>Y], ...  
\end{verbatim}
%%
so the first attribute will be computed first. If the second attribute has
a smaller answer set, the attributes in the molecule should be written in
the opposite order. The other consideration has to do with literals that
have nested molecules in them. For instance, the following query
%%
\begin{verbatim}
     ?- ..., X[attr1->Y[attr2->Z]], f(P[attr3->Q]), ...
\end{verbatim}
%%
is translated as
%%
\begin{verbatim}
     ?- ..., X[attr1->Y], Y[attr2->Z], f(P), P[attr3->Q], ...
\end{verbatim}
%%
{\it i.e.}, the nested literals follow their hosts in the translation.
Thus, writing terms in this way is considered a hint to the compiler, which
indicates that bindings are propagated from {\tt X[attr1->Y]} to {\tt
  Y[attr2->Z]}, etc. If, on the other hand, {\tt Y[attr2->Z]} has only one
solution then, perhaps, writing {\tt Y[attr2->Z], X[attr1->Y]} might
produce a more efficient code.  The same considerations apply to {\tt
  f(P[attr3->Q])}.

Similarly to nested molecules, the \FLORA compiler assumes that path
expressions represent a hint that bindings are propagated left-to-right.
In other words, in {\tt X.Y.Z}, {\tt X} will be bound first.
Based on this, the oids, of the objects {\tt X.Y} are computed, and
then the attribute {\tt Z} is applied. In other words, the translation will
be {\tt X[Y->Newvar1], Newvar1[Z->Newvar2]}.

Unfortunately, unlike in databases, statistical information is not
available to the \FLORA compiler and only a few heuristics (such as
variable binding analysis, which the compiler does not perform) can be used
to optimize such queries. If the order chosen by the compiler is not right,
the programmer can always unnest the literals and place them in the right
order in the rule body.

\paragraph{Open calls vs. bound calls.}
In Prolog it is much more efficient (space- and
time-wise) to make one unbound call than multiple bound ones. For instance,
suppose we have a class, {\tt cl}, that has hundreds of members, and
consider the following query:
%%
\begin{verbatim}
    ?- X:cl[attr->Y].  
\end{verbatim}
%%
Here, Prolog would first evaluate the open call $X:cl$ and then for each
answer {\tt x} for {\tt X} it will evaluate {\tt x[attr->Y]}.
If the cost of computing {\tt x[attr->Y]} is higher than the cost of $x:cl$
and the number of answers to {\tt X[attr->Y]} is not significantly
higher than the number of answers to {\tt X:cl}, then the following query
might be evaluated much faster:
%%
\begin{verbatim}
   ?- X[attr->Y], X:cl.  
\end{verbatim}
%%
In this query, a single call {\tt X[attr->Y]} is evaluated first and then
{\tt x:cl} is computed for each answer for {\tt X}.  Since, as we remarked,
the cost of this call can be much smaller than the combined cost of
multiple calls to {\tt x[attr->Y]} for different {\tt x}.  If the number of
bindings for {\tt X} in {\tt X[attr->Y]} that are not members of class {\tt
  cl} is small, the second query might take significantly less space and
time.


\section{Compiler Directives}
\label{sec-comp-directives}

\index{directive|see{compiler directive}}
\index{compiler directive}
\index{compiler directive!executable}
\index{compiler directive!compile-time}
%
\paragraph{Executable vs. compile-time directives.}
Like Prolog compiler, \FLORA compiler can take compiler directives.  Like
in Prolog, these directives can be \emph{executable} or
\emph{compile-time}, and this distinction is very important.
Executable directives are treated as queries and they begin with {\tt ?-}.
Compile-time directives begin with {\tt :-}.

Executable directives are mostly used to control how the \FLORA shell
interprets the expressions that the user types in. These directives have no
effect during the compilation of program files. Instead, when they are
executed as queries they affect the shell. In contrast, compile-time
directives affect the compilation of the files they occur in. Also, if a
module is loaded into the main module in the shell, then all compile time
directives in that module are executed in the shell as well, so there is no
need to explicitly execute these directives in the shell.
\FLORA requires
that all compile-time directives appear at the top of the program prior to
the first appearance of a rule or a fact, because such a directive has
effect only after it is found and processed.

To better understand the issue, consider the following simple program
(say, in file {\tt test.flr}):
%%
\begin{verbatim}
  :- op(400,xfx,fff).
  a fff b.
  ?- X fff Y.
\end{verbatim}
%%
If you load this program then it will execute correctly and return the
bindings {\tt a} and {\tt b} for {\tt X} and {\tt Y}, respectively.
If you execute the same query {\tt X fff Y} in the \FLORA shell,
the result will still be correct because \FLORA made sure that the
directive {\tt op(400,xfx,fff)} in
{\tt test.flr} was executed in the shell as well.
On the other hand, if the program were
%%
\begin{verbatim}
  ?- op(400,xfx,fff).
  a fff b.
  ?- X fff Y.
\end{verbatim}
%%
then {\tt fff} would be known to the shell, but, unfortunately, we
will not get that far to find out: The compiler will issue an error, since
{\tt fff} will not be known as an operator during the compilation of the
program.

\paragraph{Summary of directives.}
The following is a summary of all supported compiler directives:
%%
\begin{description}
  \item[{\tt :- equality none|basic|flogic}]
\index{{\tt equality} compiler directive}
\index{compiler directive!{\tt equality}}
%
~~~\\
    Sets the equality maintenance level in the current user module.
    With {\tt none}, equality is not maintained, and the symbol {\tt :=:}
    works like an ordinary predicate.  With {\tt basic}, the predicate {\tt
      :=:} is treated as the equality, but only the usual congruence axioms
    for equality are enforced. With {\tt flogic}, the usual congruence
    axioms are maintained \emph{plus} the additional equality axiom for
    single-valued methods in \fl.
\item[{\tt ?- equality none|basic|flogic}]
  ~~~\\
  This is an executable version of the {\tt equality} directive.
\item[{\tt ?- (equality none|basic|flogic)@\emph{module}}]
  ~~~\\
  Same as above, except that equality maintenance is set for the specified
  user module.
  
\item[{\tt :- index \emph{Arity-Argument} }]
\index{{\tt index} compiler directive}
\index{compiler directive!{\tt index}}
  ~~~\\
  Says that all HiLog predicates of arity {\tt Arity}should be indexed on
  argument number {\tt Argument} (the count starts at 1). This directive
  should appear at the beginning of a module to have any effect.
  Normally predicates in \FLORA are indexed on predicate name only.
  The  above directive changes this so that indexing is done on the given
  argument number instead.

  Note that the {\tt index} directive is not very useful for predicates
  that mostly contain facts, because these are trie-indexed anyway
  (regardless of what you say). Thus, this instruction is useful only for
  predicates with partially instantiated arguments that appear in the rule
  heads.
\item[{\tt :- (index \emph{Arity-Argument})@\emph{module} }]
~~~  \\
  Same as above, except that the indexing of clauses will be done in the
  specified module.

\item[{\tt :-  op({\it precedence},{\it type},{\it operator})}]
\index{{\tt op} compiler directive}
\index{compiler directive!{\tt op}}
 ~~~ \\
  Defines \emph{operator} as a \FLORA operator with the given precedence
  and type. The \emph{type} is the same as in Prolog operators, {\it i.e.},
  {\tt fx}, {\tt xf}, {\tt xfy}, etc.
  Note that the {\tt op} directive is confined to
  the module in which it is executed or defined. For instance, if
  {\tt example.flr} has a call {\tt (a foo b)@bar}, the symbol {\tt foo} is
  declared as an operator in the program loaded to module {\tt bar}, but not in
  {\tt example.flr}, then a syntax error will result, because 
   {\tt example.flr} does not know about the operator declaration for {\tt
  foo}.
\item[{\tt :-  op({\it precedence},{\it type},[{\it operator}, ..., {\it operator}])}]
~~~  \\
  Same as above, except that this directive defines a list of operators
  with the same precedence and type.
\item[{\tt ?-  op({\it precedence},{\it type},{\it operator})@\emph{module}}]
 ~~~ \\
  Same as above, except that a module is also given. However, unless the
  module is {\tt main}, this directive acts as a no-op.
\item[{\tt table {\it functor/arity}, ..., {\it functor/arity}}]
  ~~~\\
  Requests that the specified first order predicates must be tabled.
  
\end{description}


\section{\FLORA System Modules}\label{sec-service-libs}

\index{module!system}
\index{system module}
%%
\FLORA provides a number of useful libraries that other programs can use.
These libraries are statically preloaded into modules that are accessible
through the special {\tt @flora(modname)} syntax, and they are called
\emph{system modules}.  We describe the functionality of these modules
below.

\subsection{Pretty Printing}

This library provides methods for pretty printing the information about an
object or about all objects in a given class. This information can be saved
in a file or printed on the screen. This library is preloaded in the
system module {\tt pp} and is accessible using the {\tt @flora(pp)}
syntax.

To pretty print information about an object, the following calls can be
used.  The first argument is the user module whose object is to be pretty
printed. (Recall that the same object can have completely different sets of
properties in different user modules, so the pretty printing methods need to
know which set of properties to use.)
%%
\begin{itemize}
  \item  {\tt Class[\#pp\_class(Module,Outfile)]} --- pretty print all
  objects in {\tt Class} and put the result in {\tt Outfile}.
\item {\tt Class[\#pp\_class(Module)]} --- same, but the information is
  printed to the screen.
\item {\tt Obj[\#pp\_self(Module,Outfile)]} --- pretty print {\tt Obj}, send
  the result to Outfile.
\item {\tt Obj[\#pp\_self(Module)]} --- same, but print to the screen.
\item {\tt Class[\#pp\_isa(Module,Outfile)]} --- Print the part of the isa
  hierarchy beneath {\tt Class}.
\item {\tt Class[\#pp\_isa(Module)]} --- same, but print to the screen.
\end{itemize}
%%
The following example illustrates the use of this library:
%%
\begin{quote}
 {\tt
   ?- john[\#pp\_self(\thismodule)]@flora(pp).
   }
\end{quote}
%%
When this method is called, the token \thismodule is replaced with the name
of the module in which the call occurs, so it known that it has to pretty
print the object {\tt john} in that module.

\subsection{Input and Output}

This library simplifies access to the most common Prolog I/O facilities.
This library is preloaded into the system module {\tt io} and
can be accessed using the {\tt @flora(io)} syntax.

The purpose of the I/O library is not to replace the standard I/O predicates
with \FLORA methods, but rather to relieve the user from the need to do
explicit conversion of arguments between the HiLog representation of terms
used in \FLORA and the standard Prolog representation of the underlying
engine.\footnote{
  %%
  See Section~\ref{sec:hilog} for a discussion of the problems associated
  with this representation mismatch.
  %%
  }
%%
\index{I/O!stream-based}
\index{I/O!port-based}
%%
However, for uniformity, the {\tt io} library also provides certain methods
that do not suffer from the conversion problem.

The library contains two types of I/O operations: \emph{stream-based I/O}
and \emph{port-based}.  Stream-based I/O is based on the standard Prolog
I/O primitives. It uses symbols as file handles. Port-based I/O is specific
to XSB. Its file handles are internally represented as numbers. Although
stream-based I/O is often easier to use, there are many more port-based
primitives that can accomplish various low-level I/O operations. This
\FLORA library provides just a few common ones. See the XSB manual, volume
2, for a complete list of these primitives.

The methods and predicates accessible through the {\tt io} library are
listed below.  Note that some operations are defined as procedural methods
and others as predicates. This is because we use the object-oriented
representation only where it makes sense --- we avoid introducing
additional classes and objects that require more typing just for the sake
of keeping the syntax object-oriented.

\paragraph{Stream-based I/O.}
%%
\begin{itemize}
\item  {\tt Filename[\#see]} --- open {\tt Filename} and make it into the
  current input stream.
\item {\tt seeing(Stream)} --- binds {\tt Stream} to the current input
  stream.
\item {\tt seen} --- closes the current input stream.
\item {\tt Filename[\#tell]} --- opens {\tt Filename} as the current output
  stream.
\item {\tt telling(Stream)} --- binds {\tt Stream} to the current output
  stream. 
\item {\tt told} --- closes the current output stream.
\item {\tt write(Obj)} --- writes {\tt Obj} to the current output stream.
\item Stream[\#write(Obj)] --- writes {\tt Obj} to the stream {\tt Stream}.
\item {\tt writeln(Obj)}, {\tt Stream[\#writeln(Obj)]} --- same as above,
  except that the newline character is output after {\tt Obj}.
\item {\tt nl} --- writes the newline character to the current output
  stream.
\item {\tt read(Result)} --- binds {\tt Result} to the next term in the
  current input stream.
\item {\tt Stream[\#read(Result)]} --- same as above, but use {\tt Stream}
  as the input stream.
\end{itemize}
%%

\paragraph{Port-based I/O.}
%%
\begin{itemize}
\item  {\tt Filename[\#open(Mode,Port)]} --- opens {\tt Filename} with mode
  {\tt Mode} (which can be {\tt r}, {\tt w}, or {\tt a}) and binds {\tt
  Port} to the file handle.
\item {\tt Port[\#close]} --- closes the file handle to which {\tt Port} is
  bound.
\item {\tt Port[\#read(Result)]} --- bind {\tt Result} to the next term
  in the previously open input {\tt Port}.
\item {\tt stdread(Result)} --- same, but use the standard input as the port.
\item {\tt Port[\#write(Result)]} --- write {\tt Result} out to the
  previously open output {\tt Port}.
\item {\tt stdwrite(Result)} --- same, but use standard output as the port.
\item {\tt fmt\_write(Format,Term)} --- C-style formatted output to the
  standard output. See the XSB manual, volume 2, for the description of all
  the options.
\item {\tt Port[\#fmt\_write(Format,O)]} --- same, but use {\tt Port} for the
  output. 
\item {\tt fmt\_write\_string(String,Format,Obj} --- same as above, but bind
  {\tt String} to the result. See the XSB manual for the details.
\item {\tt fmt\_read(Format,Result,Status)} --- C-style formatted read from
  standard input. See the XSB manual.
\item {\tt Port[\#fmt\_read(Format,Result,Status)]}  ---  same, but use {\tt
    Port} for input.
\item {\tt write\_canonical(Term)} --- write {\tt Term} to standard output
  in canonic Prolog form.
\item {\tt Port[\#write\_canonical(Term)]} --- same, but use {\tt Port} for
  output.
\item {\tt read\_canonical(Term)} --- read standard input and bind {\tt
    Term} to the next term in the input. The term \emph{must} be in
  canonical Prolog form, or else an error will result. This method is much
  faster than the usual {\tt read} operation, but it is not as versatile,
  as it assumes that input is in canonical form.
\item {\tt Port[\#read\_canonical(Term)]} --- same, but use {\tt Port} for
  input.
\item {\tt readline(Type,String)} --- read the standard input and bind
  {\tt String} to the next line. {\tt Type} is either {\tt atom} or
  {\tt charlist}. The former means that {\tt String} is to be bound to a
  Prolog atom and the latter binds it to a list of characters.
\item {\tt Port[\#readline(Type,String)]} --- same, but use {\tt Port} for
  input.
\end{itemize}
%%

\subsection{Storage Control}\label{sec:storage-ctl}

\FLORA keeps the facts that are part of the program or those that are
inserted by the program in special data structures called \emph{storage
  tries}.  The system module {\tt db} accessible through the module
reference {\tt @flora(db)}, provides primitives for controlling this
storage.
%%
\begin{itemize}
  \item  {\tt commit} --- commits all changes made by backtrackable updates.
    If this statement is executed in the middle of an update transaction,
    changes made by backtrackable updates prior to this will be committed
    and will not be undone even if a subsequent subgoal fails.
  \item {\tt commit(Module)} --- commits all changes made by backtrackable
    updates to facts in the user module {\tt Module}. Backtrackable updates
    to other modules are unaffected.
  \item {\tt purgedb(Module)} --- deletes all facts previously inserted
    into the storage associated with module {\tt Module}.
\end{itemize}
%%

\subsection{System Control}\label{sec-flora-syscontrol}

The system module {\tt sys} provides primitives that affect the global
behavior of the system. It is accessible though the system module reference
{\tt @flora(sys)}.
%%
\begin{itemize}
  \item  {\tt libpath[\#add(Path)]} --- adds {\tt Path} to the library
    search path. This works similarly to the {\tt PATH} environment
    variable in that when the compiler or the loader are trying to locate a
    file specified by its name only (without directory, etc.) then they
    examine the files stored in the directories on the library search path.
  \item {\tt libpath[\#remove(Path)]} --- removes {\tt Path} from the
    library search path.
  \item {\tt libpath[\#query(Path)]} --- queries the library search path. If
    {\tt Path} is bound, checks if the specified directory is on the
    library search path. Otherwise, binds (through backtracking) {\tt Path}
    to each directory on the library search path.
  \item {\tt tables[\#abolish]} --- discards all tabled data in Prolog.
\end{itemize}
%%
This module also provides the following amenities:
%%
\begin{itemize}
  \item  {\tt abort(Message)} --- puts {\tt Message} on standard error
  stream and terminates the current execution. Message can also be in the
  form {\tt (M1, M2, ..., Mn)}. In this case, all the component strings are
  concatenated before printing them out.
\item {\tt warning(Message)} --- prints a warning header, then message,
  {\tt Message}, and continues. Output goes to standard error
  stream. {\tt Message} can be of the form {\tt (M1, M2, ..., Mn)}.
\item {\tt message(Message)} --- Like {\tt warning/1}, but does not print
  the warning header. {\tt Message} can be of the form {\tt (M1, M2, ..., Mn)}.
\end{itemize}
%%


\section{A Note on Programming Style}

Programming in \FLORA is similar to programming in Prolog, but is more
declarative. For one thing, F-molecules are always tabled, so the
programmer does not need to worry about tabling the right predicates.
Second, there is no need to worry that a predicate must be declared as
dynamic in order to be updatable. Third --- and most important --- the facts 
specified in the program are considered to be part of the database. In
particular, their order does not matter and duplicates are eliminated
automatically. 

This has a far-reaching implication on the programming style.
In Prolog, it is a common practice to put the catch-all facts at the end of
a program block in order to capture subgoals that do not match the rest of
the program clauses. For instance, 
%%
\begin{verbatim}
  p(f(X)) :- ...
  p(g(X)) :- ...
  %% If all else fails, simply succeed.
  p(_).
\end{verbatim}
%%
This will \emph{not} work in \FLORA, because {\tt p(\_)} will be treated as a
database fact, which is placed in no particular order with respect to the
program. If you want the desired effect, represent the catch-all facts as
rules: 
%%
\begin{verbatim}
  p(f(X)) :- ...
  p(g(X)) :- ...
  %% If all else fails, simply succeed. Use rule notation for p/1.
  p(_) :- true.
\end{verbatim}
%%

\section{Miscellaneous Features}

\subsection{Suppression of Banners}
When \FLORA initializes itself, it produces a lot of chatter: the XSB
banner, a great number of messages about the various XSB and \FLORA modules
that are loaded, and the \FLORA welcome message. However, the user might
not want to see all these, and when the program runs in a batch mode
or interacts with other programs then all these messages are either not
needed or they can complicate this interaction. To suppress these messages,
use the following switches when invoking the system:
%%
\index{{\tt --nobanner}}
\index{{\tt --quietload}}
%%
\begin{quote}
{\tt --nobanner}: suppress the XSB banner and the \FLORA welcome message\\
{\tt --quietload}: when loading a module, do not print feedback to the terminal
\end{quote}
%%
Thus,
%%
\begin{verbatim}
 runflora --nobanner --quietload  
\end{verbatim}
%%
will get you directly to the \FLORA prompt without cluttering the terminal
with chatter.

\index{{\tt --noprompt}}
%%
Sometimes even the prompt stands in the way. For instance, when \FLORA
interacts with other programs ({\it e.g.}, with a GUI) then sending the
prompt to the other program just complicates things, as the receiving
program needs to remember to ignore the prompt. To avoid this complication,
the invocation flag {\tt --noprompt} is provided. Thus,
%%
\begin{verbatim}
 runflora --nobanner --quietload --noprompt
\end{verbatim}
%%
will print nothing on startup and will be just waiting for user input. When
the input occurs, \FLORA will evaluate the query and return the result.
After this, it will return to wait for the input without issuing any
prompts.

\subsection{Passing Compiler Options to XSB}

\index{flora\_compiler\_options directive}
%%
Sometimes it is desirable to pass compiler options to the underlying prolog
compiler. To do this, \FLORA provides the directive
{\tt flora\_compiler\_options/1}. It takes one argument --- a list of
options that is understood by the underlying Prolog compiler. For instance,
the directive
%%
\begin{verbatim}
  :- flora_compiler_options([spec_repr]).  
\end{verbatim}
%%
will cause the module that contains this directive to be compiled with the
XSB specialization optimization.


\section{Bugs in Prolog and \FLORA: How to Report}

The \FLORA system includes a compiler and runtime libraries, but for
execution it relies on Prolog. Thus, some bugs that you might encounter are
the fault of \FLORA, while others are Prolog bugs. For instance, a memory
violation that occurs during the execution is in all likelihood an internal
Prolog bug. (\FLORA is a stress test --- all bugs come to the surface.)

An incorrect result during the execution can be equally blamed on Prolog or
on \FLORA --- it requires a close look at the program. A compiler or
a runtime error for a perfectly valid program is probably a bug in the
\FLORA system.

Bugs that are the fault of the underlying Prolog engine are particularly
hard to fix, because \FLORA programs are translated into mangled,
unreadable to humans Prolog code.  To make things worse, this code might
contain calls to \FLORA system libraries.

\index{flDump/1}
%%
To simplify bug reporting, \FLORA provides a utility that makes the compiled
Prolog program more readable. The flDump/1 predicate can be used to strip the
macros from the code, making it much easier to understand. If you issue the
following command
%%
\begin{verbatim}
  flora2 ?- flDump(foo).  
\end{verbatim}
%%
the program {\tt foo.flr} will be compiled without the macros and dump the
result in the file {\tt foo\_dump.P}. This file is pretty-printed to make
it easier to read. Similarly,
%%
\begin{verbatim}
  flora2 ?- flDump(foo,bar)  
\end{verbatim}
%%
will compile {\tt foo.flr} for module {\tt bar} and will dump the result to
the file {\tt foo\_dump.P}.

Unfortunately, this more readable version of the translated \FLORA program
might still not be executable on its own because it might contain calls to
\FLORA libraries or other modules.  The set of guidelines, below, can help
cope with these problems.

\paragraph{Reporting \FLORA-related Prolog bugs.}
If you find a Prolog bug triggered by a \FLORA program, here is a set of
guidelines that can simplify the job of the XSB developers and increase the
chances that the bug will be fixed promptly:
%%
\begin{enumerate}
  \item  Reduce the size of your \FLORA program as much as possible, while
    still being able to reproduce the bug.
  \item  Eliminate all calls to the system modules that use the
    {\tt @flora(lib)} syntax. (Prolog modules that are accessible
    through the {\tt @prolog(modname)} syntax are OK, but the more you can
    eliminate the better.)
  \item If the program has several user modules, try to put them into one
    file and use just one module. 
  \item  Use {\tt flDump/1} to strip \FLORA macros from the output of the
    \FLORA compiler.
  \item  See if the resulting program runs under plain XSB system (without
    the \FLORA shell). If it does not, it means that the program contains
    calls to \FLORA runtime libraries. Try to eliminate such calls.

    One common library call is used to collect all query answers in a list
    and then print them out. You can get rid of this library call by
    finding the predicate {\tt fllibprogramans/2} in the compiled {\tt .P}
    program and removing it while preserving the subgoal (the first
    argument) and renaming the variables (as indicated by the second argument).
    Make sure the resulting program is still syntactically correct!

    Other calls that are often no longer needed in the dumped code are
    those that load \FLORA runtime libraries (which we are trying to
    eliminate!). These calls have the form
    %%
    \begin{verbatim}
    ?- flora_load_library(...).      
    \end{verbatim}
    %%
    If there are other calls to \FLORA runtime libraries, try to delete
    them, but make sure that the bug is still reproducible.
  \item If the program still does not run because of the hard-to-get-rid-of
    calls to \FLORA runtime libraries, then see if it runs after you
    execute the command
    %%
    \begin{quote}
       {\tt ?- bootstrap\_flora.}      
    \end{quote}
    %%
    in the Prolog shell. If the program runs after this (and reproduces the
    bug) --- it is better than nothing. If it does not, then something went
    wrong during the above process: start anew.
  \item Try to reduce the size of the resulting program as much as possible.
  \item Tell the XSB developers how to reproduce the bug. Make sure you
    include all the steps (including such gory details as whether it is
    necessary to call {\tt bootstrap\_flora/0}).
\end{enumerate}
%%
Finally, remember to include the details of your OS and other relevant
information. Some bugs might be architecture-dependent.

\paragraph{Reporting \FLORA bugs.}
If you believe that the bug is in the \FLORA system rather than in the
underlying Prolog engine, the algorithm is much simpler: 
%%
\begin{enumerate}
  \item Reduce the size of the program as much as possible by deleting 
    unrelated program clauses and squeezing a multi-module program into
    just one file.
  \item Remove all the calls to system modules, unless such a call that is
    the essence of the bug.
  \item Tell \FLORA developers how to reproduce the bug.
\end{enumerate}
%%

The current version contains the following known bugs, which are due to the
fact that certain features are yet to be implemented:
%%
\begin{enumerate}
  \item  Certain programs might cause the following XSB error message:
    %%
    \begin{quote}
     ++Error[XSB]: [Compiler] '!' after table dependent symbol 
    \end{quote}
    %%
    \index{local scheduling in XSB}
    %%
    This is due to certain limitations in the implementation of tabled
    predicates in the XSB system. This problem will be eliminated in a
    future release of XSB. Meanwhile, as explained in the Introduction,
    configuring XSB for SLG-WAM and \emph{local} scheduling will avoid many of
    such errors.
  \item Error messages when \FLORA update predicates contain arithmetic
    expressions in the query part. This problem will be fixed in the
    future.
  \item Multiple types (which represent type intersection in \fl) are not
    allowed in set-valued signature expressions: {\tt a[m=>>{c,d}]} and
    {\tt a[m*=>>{c,d}]}. Use {\tt a[m=>>c],a[m=>>d]} for now.
  \item Inheritance of procedural methods is not supported: {\tt
      a[*\#p(X)]}.
\end{enumerate}
%%

\section{Authors}
\FLORA was designed and implemented by Guizhen Yang. Some architectural
ideas, such as the use of trailer files to implement the F-logic semantics,
were inspired by the \FLIP compiler developed by Bertram Lud\"aescher.

Michael Kifer helped design \FLORA, implemented the debugger, and some
other features.

Chang Zhao made a great many of the crucial enhancements to the
system, such as run-time undefinedness checks, the checker for
dependency among tabled predicates and updates, tabling of HiLog
predicates, and dynamic insertion and deletion of program rules.


\appendix

\newpage

\noindent
{\LARGE\bf Appendices}
\addcontentsline{toc}{section}{Appendices}

\section{A BNF-style Grammar for \FLORA}\label{app-bnf}

%%
\begin{verbatim}
%% To avoid confusion between some language elements and meta-syntax
%% (e.g., parentheses and brackets are part of BNF and also of the language
%% being described), we enclose some symbols in single quotes to make it
%% clear that they are part of the language syntax, not of the grammar.
%% However, in FLORA these symbols can be used with or without the quotes.


Rule := Head (':-' Body)? .

Head := HeadLiteral
Head := Head ',' Head

HeadLiteral := BinaryRelationship | ObjectSpecification | Term

Body := BodyLiteral
Body := BodyConjunt | BodyDisjunct | BodyNegative | ControlFlowStatement
Body := Body '@' ModuleName
Body := BodyConstraint

ModuleName := 'prolog()' | 'prolog(' atom ')' | atom | 'flora(' atom ') '

BodyConjuct  := Body ',' Body
BodyDisjunct := Body ';' Body
BodyNegative := ('tnot' | '\+') Body
BodyConstraint := '{' CLPR-style constraint '}'

ControlFlowStatement  := IfThenElse | UnlessDo
                          | WhileDo | WhileLoop
			  | DoUntil | LoopUntil
IfThenElse := if Body then Body  (else Body)?
UnlessDo   := unless Body do Body
WhileDo    := while Body do Body
WhileLoop  := while Body loop Body
DoUntil    := do Body until Body
LoopUntil  := loop Body until Body

BodyLiteral := BinaryRelationship | ObjectSpecification | Term
                | DBUpdate | Refresh | Builtin | Loading

Builtin := ArithmeticComparison, Unification, MetaUnification, etc.

Loading := '[' LoadingCommand (',' LoadingCommand)* ']'
LoadingCommand := filename ('>>' atom)

BinaryRelationship := PathExpression ':' PathExpression
BinaryRelationship := PathExpression '::' PathExpression

ObjectSpecification := PathExpression '[' SpecBody ']'

SpecBody := 'tnot' MethodSpecification
SpecBody := SpecBody ',' SpecBody
SpecBody := SpecBody ';' SpecBody

MethodSpecification :=  ('#' | '*')? Term
MethodSpecification :=  PathExpression ValueReferenceConnective PathExpression

ValueReferenceConnective :=  '->' | '->>' | '*->' | '*->>' | '=>' | '=>>'

PathExpression := atom | number | string | variable | specialOidToken
PathExpression := Term | List | ReifiedFormula
PathExpression := PathExpression  PathExpressionConnective PathExpression
PathExpression := BinaryRelationship
PathExpression := ObjectSpecification
PathExpression := Aggregate

PathExpressionConnective :=  '.' | '..' | '!' | '!!'

specialOidToken :=  anonymousOid | numberedOid | thisModuleName

ReifiedFormula := ${Body}

%% No quotes are allowed in the following special tokens!
%% No space alowed between _# and integer
%% anonymousOid & numberedOid can occur only in rule head
anonymousOid   := _#
numberedOid    := _#integer
thisModuleName := _@

List := '[' PathExpression (',' PathExpression)* ('|' PathExpression)? ']'

Term := Functor '(' Arguments ')'

Functor := PathExpression

Arguments := PathExpression (',' PathExpression)*

Aggregate := AggregateOperator '{' TargetVariable (GroupingVariables)? '|' Body '}'
AggregateOperator := 'max' | 'min' | 'avg' | 'sum' | 'collectset' | 'collectbag'
%% Note: only one TargetVariable is permitted.
%% It must be a variable, not a term. If you need to aggregate over terms,
%% as for example, in collectset/collectbag, use the following idiom:
%%      S = collectset{ V | ... , V=Term }
TargetVariable := variable
GroupingVariables := '[' variable, (',' variable)* ']'

DBUpdate := DBOp '{' UpdateList ('|' Body)? '}'
DBOp := insert | insertall | delete | deleteall | erase | eraseall
UpdateList := HeadLiteral ('@' atom)?
UpdateList := UpdateList ',' UpdateList  
Refresh := refresh '{' UpdateList '}'
\end{verbatim}
%%


\section{The \FLORA Debugger}\label{sec-debugger}
\index{debugger}


\FLORA debugger is implemented as a presentation layer on top of the Prolog
debugger, so familiarity with the latter is highly recommended (XSB Manual,
Part I). Here we sketch only a few basics.

\index{tracing}
\index{spying}
%%
The debugger has two facilities: \emph{tracing} and \emph{spying.} Tracing
allows the user to watch the program being executed step by step, and
spying allows one to tell \FLORA that it must pose when execution reaches
certain predicates or object methods. The user can trace the execution from
then on. At present, only the tracing facility has been implemented.

\index{flTrace}
\index{flNoTrace}
%%
\paragraph{Tracing.}
To start tracing, you must issue the command {\tt flTrace} at the
\FLORA prompt. It is also possible to put the subgoal {\tt flTrace} in
the middle of the program. In tat case, tracing will start after this
subgoal gets executed. This is useful when you know where exactly you want
to start tracing the program. To stop tracing, type {\tt flNoTrace}.

During tracing, the user is normally prompted at the four ports of subgoal
execution: {\tt Call} (when a subgoal is first called), {\tt Exit} (when
the call exits), {\tt Redo} (when the subgoal is tried with a different
binding on backtracking), and {\tt Fail} (when a subgoal fails).
At each of the prompts, the user can issue a number of commands. The most
common ones are listed below. See the XSB manual for more.
%%
\begin{itemize}
  \item {\tt carriage return (creep)}:  to go to the next step  
  \item {\tt s (skip)}: execute this subgoal non-interactively; prompt
    again when the call exits (or fails)
  \item {\tt S (verbose skip)}: like {\tt s}, but also show the trace
    generated by this execution
  \item {\tt l (leap)}: stop tracing and execute the remainder of the
    program
\end{itemize}
%%
The behavior of the debugger is controlled by the predicate {\tt
  debug\_ctl}. For instance, executing {\tt debug\_ctl(profile, on)} at the
\FLORA prompt tells XSB to measure the CPU time it takes to execute each
call. This is useful for tuning your program for performance. Other useful
controls are: {\tt debug\_ctl(prompt, off)}, which causes the trace to be
generated without user intervention; and {\tt debug\_ctl(redirect,
  foobar)}, which redirects debugger output to the file named {\tt foobar}.
The latter feature is usually useful only in conjunction with the aforesaid
prompt-off mode. See the XSB manual for additional information on debugger
control.

\FLORA provides a convenient shortcut that capture some of the most common
uses of the aforesaid {\tt debug\_ctl} interface. Executing
%%
\begin{quote}
  {\tt ?- flTrace(filename).}
\end{quote}
%%
will switch \FLORA to non-interactive trace mode
and the entire trace will be dumped to file {\tt filename}.
Note that you have to execute {\tt flNoTrace} or exit Prolog in order for the
entire file to be flushed on disk.

\index{flTraceLow}
%%
\paragraph{Low-level tracing.}
\FLORA debugger also supports low-level tracing via the shell command {\tt
  flTraceLow}. With normal tracing, the debugger converts low-level
subgoals to subgoals that are found in the user program and are thus
meaningful to the programmer. With low-level tracing, the debugger displays
the actual Prolog subgoals (of the compiled .P program) that are being
executed. This facility is useful for debugging \FLORA runtime libraries.

As with {\tt flTrace}, \FLORA provides a convenient shortcut that allows
the entire execution trace to be dumped into a file:
%%
\begin{quote}
 \tt ?- flTraceLow(filename).  
\end{quote}
%%

{\bf Note:} \FLORA turns on various Prolog optimizations. Some (like
specialization and unification factoring) can cause certain subgoals to
be omitted from the trace or the trace might show subgoals that
are not in the original program. In the future, it will be possible to turn
these optimizations off for debugging.


\newpage
\section{Emacs Support}

Editing and debugging \FLORA programs can be greatly simplified with the
help of \emph{flora-mode}, a special Emacs editing mode designed
specifically for \FLORA programs. Flora-mode provides support for syntactic
highlighting, automatic indentation, and the ability to run \FLORA programs
right out of the Emacs buffer.


\subsection{Installation}


To install \emph{flora-mode}, you must perform the following steps. Put the
file
%%
\begin{quote}
  {\tt XSB/packages/flora2/emacs/flora.el} 
\end{quote}
%%
found in your XSB distribution on the load path of Emacs or XEmacs
(whichever you are using). The best way to work with Emacs is to make a
separate directory for Emacs libraries (if you do not have one), and put
{\tt flora.el} there. Such a directory can be added to emacs search path by
putting the following command in the file \verb|~/.emacs| (or
\verb|~/.xemacs|, if you are running one of the newer versions of XEmacs):
%%
\begin{quote}
  \tt
   (setq load-path (cons "your-directory" load-path)) 
\end{quote}
%%
It is also a good idea to compile emacs libraries. To compile flora.el,
use this:
%%
\begin{quote}
  \tt
   emacs -batch -f batch-byte-compile flora.el 
\end{quote}
%%
This will produce the file {\tt flora.elc} --- a compiled byte code.
If you are using XEmacs, use {\tt xemacs} instead of {\tt emacs} above ---
the two emacsen use incompatible byte code, and you cannot use {\tt
  flora.elc} compiled under one system for editing files under another.

Finally, you must tell X/Emacs how to recognize \FLORA program files, so
Emacs will be able to invoke the Flora major mode automatically when you
are editing such files:
%%
\begin{verbatim}
(setq auto-mode-alist (cons '("\\.flr$" . flora-mode) auto-mode-alist))
(autoload 'flora-mode "flora" "Major mode for editing Flora programs." t)
\end{verbatim}
%%$

To enable syntactic highlighting of Emacs buffers (not just for \FLORA
programs), you can do the following:
%%
\begin{itemize}
  \item  {\sf In Emacs:} select {\tt Help.Options.Global Font Lock} on
    the menubar.  To enable highlingting permanently, put 
    %%
    \begin{quote}
      \tt
      (global-font-lock-mode t)
    \end{quote}
    %%
    in \verb|~/.emacs|.
  \item {\sf In XEmacs:} select {\tt Options.Syntax
        Highlighting.Automatic} in the menubar. To enable this permanently, put
      %%
      \begin{quote}
        \tt
        (add-hook 'find-file-hooks 'turn-on-font-lock)
      \end{quote}
      %%
      in \verb|~/.emacs| or \verb|~/.xemacs| (whichever is used by your
      XEmacs).
\end{itemize}
%%


\subsection{Functionality}


\paragraph{Menubar menu.}
Once \FLORA editing mode is installed, it provides a number of functions.
First, whenever you edit a \FLORA program, you will see the ``Flora'' menu
in the menubar. This menu provides commands for controlling the Flora
process (i.e., the \FLORA shell). You can start and stop
this process, type queries to it, and you can tell it to consult regions of
the buffer you are editing, the entire buffer, or some other file.

Because Emacs provides automatic file completion and allows you to edit
what you typed, performing these functions right out of the buffer takes
much less effort than typing the corresponding commands to the \FLORA
shell.

\paragraph{Keyboard functions.}
In addition to the menu, \emph{flora-mode} lets you execute most of the
menu commands using the keyboard. Once you get the hang of it, keyboard
commands are much faster to invoke:
%%
\begin{verbatim}
Load file:                 Ctl-c Ctl-f
Load file dynamically:     Ctl-u Ctl-c Ctl-f
Load buffer:               Ctl-c Ctl-b
Load buffer dynamically:   Ctl-u Ctl-c Ctl-b
Load region:               Ctl-c Ctl-r
Load region dynamically:   Ctl-u Ctl-c Ctl-r
\end{verbatim}
%%
When you invoke any of the above commands, a \FLORA process is started,
unless it is already running. However, if you want to invoke this process
explicitly, type
%%
\begin{verbatim}
ESC x run-flora  
\end{verbatim}
%%
You can control the \FLORA process using the following commands:
%%
\begin{verbatim}
Interrupt Flora Process:      Ctl-c Ctl-c
Quit Flora Process:           Ctl-c Ctl-d
Restart Flora Process:        Ctl-c Ctl-s
\end{verbatim}
%%
Interrupting \FLORA is equivalent to typing {\tt Ctl-c} at the \FLORA
prompt. Quitting the process stops the Prolog engine, and restarting the
process shuts down the old Prolog process and starts a new one with \FLORA
shell running. 

\paragraph{Indentation.}
Flora editing mode understands some aspects of the \FLORA syntax, which
enables it to provide correct indentation of program lines (in many cases).
In the future, flora-mode will know more about the syntax, which will let
it provide even better support for indentation.

The most common use of \FLORA indentation facility is by typing the {\tt
  TAB}-key. If \emph{flora-mode} manages to understand where the cursor is,
it will indent the line accordingly. Another way is to put the following in
your emacs startup file (\verb|~/.emacs| or \verb|~/.xemacs|):
%%
\begin{verbatim}
    (setq flora-electric t)  
\end{verbatim}
%%
In this case, whenever you type the return key, the next line will be
indented automatically.




\newpage
\section{Inside \FLORA}

\subsection{How \FLORA Works}


As an \fl-to-Prolog compiler, \FLORA first parses its source file,
compiles it into Prolog syntax and then outputs the resulting code. For
instance the command 
\begin{quote}
\verb|flora ?- flLoad(myprog).|
\end{quote}
compiles the \FLORA program {\tt myprog.flr} and generate the following
files: {\tt myprog.P}, {\tt myprog\_main.\ofile}, and {\tt myprog.fdb} (if {\tt
  myprog.flr} contains \fl facts).  By default, {\tt flLoad(myprog)} loads
the program into the default user module named {\tt main}. If {\tt myprog.flr}
contains \fl facts, all these facts will be compiled separately into the
file {\tt myprog.fdb} that is dynamically loaded at runtime.  Next, the
file {\tt myprog.P} is generated --- take a look at ``{\tt
  myprog\_main.P}'' to see what has become of your \FLORA program! --- and
passed to the Prolog compiler, yielding Prolog byte code {\tt
myprog.\ofile}, which
is then renamed to {\tt myprog\_main.\ofile}. This file is then loaded and
executed.  If {\tt myprog.flr} contains queries, they are immediately
executed by Prolog (provided there are no errors).

In the module system of \FLORA, the same program can be loaded into any
user module. The same program can even be loaded into two different
modules at the same time, in which case there will be two distinct copies
of the same program running at the same time. For each user module, a different
byte code is generated (this is why {\tt myprog.\ofile} was renamed into an
object file that contains the module name as part of the file name).

The main purpose of the \FLORA shell is to allow the evaluation
of ad-hoc \fl queries. For example, after consulting and loading the
the file \texttt{default.flr} from the demo directory by launching
the command \texttt{flora2~?-~flDemo(default).}, pose the following query
and see what happens.
\begin{verbatim}
    flora2 ?-  X..kids[                 % Whose kids
                       self -> K,             % ... (list them by name)
                       hobbies ->>            % ... have hobbies
                         H:dangerous_hobby    % ... that are dangerous?
               ]. 
\end{verbatim}


\paragraph{\FLORA compilation.}
The basic idea behind the implementation of \fl by translating it into
predicate calculus is described in \cite{KLW95}. It consists of two parts:
translation of F-molecules into various kinds of Prolog predicates, and
addition of appropriate ``closure rules'' that implement the
object-oriented semantics of the logic.

Consider, for instance, the following complex F-molecule, which represents
some facts about the object \texttt{mary}:

\begin{quote}
\begin{verbatim}
mary:employee[age->29, kids->>{tim,leo}, salary(1998)->100000].
\end{verbatim}
\end{quote}

As described in \cite{KLW95}, any complex F-molecule can be
decomposed into a conjunction of simpler \fl atomic formulas. These
latter atoms can be directly represented using Prolog syntax.  For
different kinds of \fl atoms we use different Prolog predicates. For
instance, the result of translating the above F-molecule might be:

\begin{quote}
\begin{verbatim}
isa(mary,employee).           % mary:employee.
fd(mary,age,29).              % mary[age->29].
mvd(mary,kids,tim).           % mary[kids->>{tim}].
mvd(mary,kids,leo).           % mary[kids->>{leo}].
fd(mary,salary(1998),100000).  % mary[salary(1998)->a_lot].
\end{verbatim}
\end{quote}
%%

\index{wrapper predicates}
%%
The {\tt fd} predicate is used to encode scalar attributes and methods and
{\tt mvd} is used for set methods. The predicates {\tt isa} ans {\tt sub}
encode the IS-A and subclass relationships, respectively.
We call these predicates \emph{wrapper predicates}. 
Of course, \FLORA has much more: signatures, inheritable and
non-inheritable methods, directives, and all kinds of auxiliary predicates
needed to improve efficiency.

\FLORA facts, such as above, are then stored in a special data structure,
called {\rm trie}, and are retrieved using  ``patch rules'', which have the
form
%%
\begin{verbatim}
 fd(Obj,Meth,Val) :- storage_find_fact(TrieName, fd(Obj,Meth,Val)).  
\end{verbatim}
%%
where {\tt storage\_find\_fact/2}is an XSB predicate that retrieves facts
from tries. {\tt TrieName} is the \emph{storage trie} that is specifically
dedicated to storing facts. There is one such trie per module. Since
programs are loaded into modules dynamically, the name of the storage trie
is determined at program load time. Also, as we shall discuss later, {\tt
  fd}, {\tt mvd}, etc., are not the actual names of the predicates used in
the encoding. The actual names have the module name prepended to them and
thus are different for different modules. Moreover, since module names are
determined at program load time, the names of the wrapper predicates are
also generated at that time from predefined templates.

The way \FLORA rules are encoded is more complex. Consider, the following rule:
%%
\begin{verbatim}
 mary[parent->X] :- mary[father->X].  
\end{verbatim}
%%
This is translated as follows:
%%
\begin{verbatim}
 derived_fd(mary,parent,X) :- d_fd(mary,father,X).  
\end{verbatim}
%%
This is done for a number of reasons. The prefix {\tt derived\_} is used to
separate the head predicates from the body. It is necessary in order to
be able to implement inheritance rules correctly, using the XSB
well-founded semantics for negation ({\tt tnot}, see
Section~\ref{sec:negation}). The prefix used in the body of a rule, {\tt
  d\_}, is introduced in order to be able to capture undefined methods,
{\it i.e.}, methods those definition was not supplied by the user (see
Section~\ref{sec-undef}). All these predicates are connected through an
elaborate set of rules, which appear in {\tt closure/*.flh} files and also
in {\tt genincludes/flrpreddef.flh} (these {\tt flh}-files are generated
from the corresponding {\tt fli}-files at \FLORA configuration time).
The following diagram shows the main
predicates involved in the plumbing system that connects
the {\tt derived\_} and {\tt d\_}; the arrow {\tt ->}indicates the
immediate dependency relationship, {\it i.e.}, that the predicate on the
right appears in the body of a rule that defines the predicate on the left.

\noindent
In program rules:
%%
\begin{verbatim}
derived_fd <- d_fd  
\end{verbatim}
%%
\noindent
In auxiliary runtime libraries:
%%
\begin{verbatim}
d_fd  <-  fd
d_ifd <- ifd
          fd <-      inferred_fd
          fd <- tnot inferred_fd      <- derived_fd
          fd <- tnot conflict_obj_ifd                     <- ifddef <- fd
          fd <-      ifd
          fd <-      immediate_isa

         ifd <-      immediate_sub
         ifd <-      inferred_ifd     <- derived_ifd
         ifd <- tnot inferred_ifd
         ifd <- tnot conflict_ifd                         <- ifddef

      ifddef <-      ifd

  derived_fd <- storage_find_fact(...trie_name..., fd(...))
\end{verbatim}
%%
Here we listed only the predicates that are used to model scalar
inheritable ({\tt ifd}) and non-inheritable ({\tt fd}) methods.  A similar
diagram exists for set methods (which uses {\tt imvd} and {\tt mvd}), and
another one exist for method signatures. There is additional machinery for
IS-A and subclass relationships, and for equality maintenance.

\index{closure axioms}
The closure axioms tie all these predicates together to implement the
semantics of \fl. In particular, they take care of the following features:
%%
\begin{itemize}
\item Computing the transitive closure of ``\subcl'' (the subclass
  relationship).  A runtime check warns about cycles in the subclass
  hierarchy.
\item Computing the closure of ``\isa'' with respect to ``\subcl'', i.e.,
  if $X\isa C, C\subcl D$ then $X\isa D$.
\item Performing monotonic and non-monotonic inheritance. The predicates
  {\tt conflict\_obj\_ifd}, {\tt conflict\_ifd}, {\tt immediate\_sub}, {\tt
    immediate\_isa}, are used for this purpose.
\item Making sure that scalar methods are, indeed, scalar.
\item Making sure that when the equality maintenance mode changes as a
  result of the executable instruction {\tt :- equality
  \{basic|flogic|none\}}, program clauses are not overwiritten by the
  rules specified in \FLORA runtime libraries. This is the reason for
  having the wrappers {\tt derived\_fd} and {\tt inferred\_fd}. The former
  appear only in the rule heads of the clauses generated by the compiler
  from the clauses in the user's program, while the latter appear only in
  the rule heads in runtime libraries.
\item Providing the infrastructure for capturing undefined methods.
  The purpose of the {\tt d\_fd}/{\tt fd} dichotomy is to provide a gap
  into which we inject rules
  (which are enabled only if runtime debugging is turned on using
  {\tt debug[\#check\_undefined(on)]}) that can capture calls to undefined
  methods at run time.
\end{itemize}
%%
Templates for the files that implement these axioms reside in the
subdirectory \texttt{closure/} and have the suffix {\tt .fli}.  These files
are called \emph{trailers} because they are typically included at the end
of the compiled program.  There are three kinds of trailers: the
no-equality trailer (the file {\tt closure/flrtrailer.fli}), which
maintains no equality, the basic trailer ({\tt closure/flreqltrailer.fli}),
which maintains only the standard equality axioms, and the trailer ({\tt
  closure/flrscalareql.fli}), which, in addition, maintains the \fl axioms
for scalar methods.

When a \FLORA program is compiled, the compiler includes the trailers into
the {\tt .P} file. However, there also is a need to be able to load the
trailers dynamically. First, this is needed in the system shell, because
the shell is not represented by any particular user program and so there is
no place where we can include the trailer. Second, the user might enter the
executable instruction 
%%
\begin{quote}
   {\tt ?- equality \{basic|flogic|none\} }
\end{quote}
%%
at the shell prompt and user programs can contain these instructions as
part of their code. Precompiled, loadable trailers for the default module
{\tt main} are stored in the {\tt trailer/} subdirectory. This is done at
the system build time.  When an equality maintenance instruction is
executed for a particular module, the trailer for that module must be
compiled and loaded dynamically.  (The need for this compilation will
become clear after we explain the implementation of the module system.)
These trailers are stored in the user home directory in the subdirectory
{\tt .xsb/flora/} rather than in the {\tt trailer/} subdirectory because
to compile the trailers \FLORA needs write permission into the user file
system.  As mentioned earlier, \FLORA uses different names for 
the wrapper predicates that appear in the rule heads in user programs and
those that appear in the rule heads in trailers. This makes it possible to
load the trailers (by executing the {\tt equality} instruction) at any time
without overriding the user program.

The above is a much simplified picture of the inner-workings of \FLORA. The
actual translation into Prolog and the form of the closure rules is very
complex.  Some of this complexity exists to ensure good performance.  Other
complications come from the need to provide a module system and integrate
it with the underlying Prolog engine.  The module system serves two
purposes.  First, it promotes modular design for \FLORA programs, making it
possible to split the code into separate files and import objects defined
in other modules. Second, it allows \FLORA programs to communicate with
Prolog by using the predicates defined in Prolog programs and letting
Prolog programs use \FLORA objects.  Some of these implementation issues
are described in \cite{guiz-flora-00}.

\paragraph{The module system.} The module system is implemented by
providing separate namespaces for the various predicates used to encode \fl
formulas. First, all predicates have a weird prefix to make clashes with
other Prolog programs unlikely. The prefix is defined in {\tt
  includes/header.flh} and currently is {\tt \_\$\_\$\_flora}. The user, of
course, does not need to worry about it, unless she runs \FLORA programs in
a very unfriendly Prolog environment in which other programs also use this
prefix. In this case, the prefix can be made
even harder to match.\footnote{
  %%
  It is necessary to ensure that the resulting predicate names are symbol
  strings acceptable to the Prolog compiler. Look at the macros
  {\tt FLORA\_THIS\_WORKSPACE} and {\tt FLORA\_THIS\_FDB\_STORAGE} in
  {\tt includes/flrheader.flh} to see what is involved.
  %%
  }
%%

Apart from the general prefix, each predicate name's prefix contains the module
name where this predicate is defined. Since the same \fl program
can be loaded into different modules, the \FLORA compiler does not actually
know the real names of the predicates it is producing. Instead, it dumps
code where each predicate is wrapped with a preprocessor macro. For
instance, the predicate {\tt fd} would be dumped as
%%
\begin{quote}
 \tt FLORA\_THIS\_WORKSPACE(FLORA\_USER\_WORKSPACE,fd)  
\end{quote}
%%
When the program, {\tt myprog.P}, compiled by the \FLORA compiler needs to
be loaded into a user module, say {\tt main}, the preprocessor, {\tt
  gpp}, is called with the macro {\tt FLORA\_USER\_WORKSPACE} set to {\tt
  main}. Gpp replaces all macros with the actual values, includes the
necessary files, and then pipes the result to the Prolog compiler. The latter
produces the object {\tt myprog.\ofile} file where all the predicate names are
wrapped with the user module name, as described above.  This object file is
renamed to {\tt myprog\_main.\ofile}. If later we need to compile {\tt myprog.P}
for another user module, {\tt foo}, {\tt gpp} is called again, but this time it
sets {\tt FLORA\_USER\_WORKSPACE} to {\tt foo}. When Prolog finally compiles
the program into the object file, the file is renames to {\tt
  myprog\_foo.\ofile}.

It is important to keep in mind that only the predicate names are wrapped
with the {\tt FLORA\_PREFIX} macro and a module name. Predicate arguments
are not wrapped and thus, the space of object Ids is shared among modules.
However, this is not a problem and, actually, is very convenient: we can
easily refer to objects defined in other modules and yet the same object
can have completely different sets of properties in each separate module.
This does not preclude the possibility of encapsulating objects, because
only the methods need to be encapsulated --- oids do not carry any meaning
by themselves.

To provide encapsulation for HiLog predicates, they are also prepended with
the module name. In particular, this implies that HiLog atomic formulas
have different representation than HiLog terms: a formula {\tt p(a,f(b))}
would be encoded as
%%
\begin{quote}
 \tt
 FLORA\_THIS\_WORKSPACE(FLORA\_USER\_WORKSPACE,apply)(p,a,FLORA\_PREFIX'apply(f,b))  
\end{quote}
%%
The same term would be encoded differently if it occurs as an argument of a
predicate of another functor:
%%
\begin{quote}
 \tt
 FLORA\_PREFIX'apply(p,a,FLORA\_PREFIX'apply(f,b))    
\end{quote}
%%
Thus, \FLORA implements a 2-sorted version of HiLog \cite{hilog-icdt-95}.

\paragraph{The updatable part of the database.}
All objects and facts that are explicitly inserted by the program are kept
in the special \emph{storage trie} associated with the user module where the
program is loaded. A tries is a special data structure, which is
well-suited for indexing tree-structured objects, like Prolog terms. This
workhorse does much of the grudge work in the Prolog engine. To manipulate the
storage tries, \FLORA uses the XSB package called {\tt storage.P}, which is
described in the XSB manual. This package was originally created to support
\FLORA, but it has independent uses as well.

\index{triehandle}
%%
All primitives in this package take a Prolog symbol, called a
\emph{triehandle}, a Prolog term, and some also return status in the third
argument. Here are some of the most relevant predicates:
%%
{\tt
\begin{quote}
  storage\_insert\_fact(Triehandle,Term,Status)\\
  storage\_delete\_fact(Triehandle,Term,Status)\\
  storage\_insert\_fact\_bt(Triehandle,Term,Status)\\
  storage\_delete\_fact\_bt(Triehandle,Term,Status)
\end{quote}
}
%%
\noindent
The first two methods insert and delete in a non-backtrackable manner,
while the last two are backtrackable.

\FLORA associates a separate triehandle (and, thus, a separate trie) with
each module. The mechanism is similar to that used for predicate names:
%%
\begin{quote}
 \tt FLORA\_THIS\_FDB\_STORAGE(FLORA\_USER\_WORKSPACE)  
\end{quote}
%%
As explained earlier, when Prolog compiles the file generated by the
\FLORA compiler, the macro {\tt FLORA\_USER\_WORKSPACE} gets replaced with
the module name and out comes a unique, hard to replicate triehandle.

Unfortunately, putting something in a trie does not mean that Prolog will find
it there automatically. That is, if you insert {\tt p(a)} in a trie, it
does not mean that the query {\tt ?- p(a)} will evaluate to true, and this
is another major source of complexity that the \FLORA compiler has to deal
with. To find out if a term exists in a trie, we must use the primitive
%%
\begin{quote}
 \tt storage\_find\_fact(Triehandle,Term)  
\end{quote}
%%
If the term exists in the trie identified by its triehandle, then the
predicate succeeds; if the term does not exist, then it fails. The above
primitive can be used to query tries in a more general way, with the second
variable unbound. In this case, we can backtrack through all the terms that
exist in the trie.

Suppose we insert a fact, {\tt a[m->v]}, represented by the formula
{\tt fd(a,m,v)}. Since this formula is inserted in the trie and Prolog knows
nothing about it, we need to connect the trie to Prolog through a rule like
this:
%%
{\tt
\begin{quote}
  fd(O,M,V) :- storage\_find\_fact(triehandle,f(O,M,V)).
\end{quote}
}
%%
\index{patch rules}
%%
Of course, the name of the triehandle and the predicate names must be
generated using the macros, as described above, so that they could be used
for any module. In \FLORA such rules are called \emph{patch rules}. 

Since \fl uses only about the predicates that represent F-molecules, we can
create such rules statically and let {\tt gpp} wrap them with the
appropriate prefixes on the fly.  The problem arises with predicates, since
although they are represented using HiLog encoding using a single
predicate, this predicate can have any arity.  At present we statically
create patch rules for such predicates up to a certain large arity.  The
static patch rules are located in {\tt genincludes/flrpatch.fli} (from
which {\tt flrpatch.flh} is generated by the \FLORA installation script).

For compiled programs, the patch rules are included into the compiled code
by the \FLORA compiler. For the \FLORA shell, however, these rules are
loaded when the corresponding shell module is created (either the default
``main'' module or any module that was created by the {\tt newmodule}
command. This patch file is loaded exactly once per shell module
and is kept in the file
{\tt .xsb/flora/patch.P}, in the user's home directory. It is copied into
the user space from  {\tt trailer/patch.P} because this file must be
compiled for different workspaces and therefore \FLORA needs write
permission.


\subsection{System Architecture}

\index{canonic term}
%%
The overall architecture of \FLORA is depicted in Figure~\ref{fig-arch}.
The program is first tokenized and then the \emph{composer} combines the
disparate tokens into terms. Since, due to the existence of operators, not
everything looks like a term in the source program, the composer consults
the operator definitions in the file {\tt flroperator.P} to get the
directives on how to turn the operator expressions into terms. Next, the
parser checks the syntax of the rules and of the various other primitives
({\it e.g.}, the aggregates, updates, module specifications, etc.). The
output of the parser is a \emph{canonic term} list, which represents the
entire parsed program. The canonic term is taken up by the intermediate
code generator, which generates abstract code. This code is represented in
a form that is convenient for manipulation and is not yet Prolog code.  The
compiler might add additional rules (such as patch rules) and Prolog
instructions. The compiled program is converted into (almost) Prolog syntax
by the coder. As mentioned previously, the code produced by the compiler is
full of preprocessor macros, so before passing it to Prolog it must be
preprocessed by GPP. GPP pipes the result to Prolog, which finally produces
the byte code program that can run under the control of the Prolog
emulator.

%%
\begin{figure}[bt]
  \begin{center}
    \includegraphics[width=5.5in]{architecture}
  \end{center}
  \caption{The architecture of the \FLORA system.}
  \label{fig-arch}
\end{figure}
%%

The following is a list of the key files of the system.
%%
\begin{itemize}
\item \texttt{flrshell.P}: The top level module that implements the
  \FLORA shell --- a subsystem for accepting user commands and queries and
  passing them to the compiler.  See Section~\ref{sec-shell-commands} for a
  full description of shell commands.
\item \texttt{flrlexer.P}: The \FLORA tokenizer.
\item \texttt{flrcomposer.P}: The \FLORA composer, which parses tokens
  according to the operator grammar and does other magic.
\item \texttt{flrparser.P}: The \FLORA parser.
\item \texttt{flrcompiler.P}: The generator of the intermediate code.
\item \texttt{flrcoder.P}: The \FLORA coder, which generates Prolog code.
\item \texttt{flrutils.P}: Miscellaneous utility predicates for loading
  programs, checking if files exist, whether they need to be recompiled,
  etc.
\end{itemize}
%%
Additional system libraries are located in the {\tt syslib/} subdirectory.
These include the various printing utilities, implementation for
aggregates, update primitives, and some others. The compiler determines
which of these libraries are needed while parsing the program. When a
library is needed, the compiler generates an {\tt \#include} statement to
include an appropriate file in the {\tt syslibinc} directory. For instance,
to include support for the {\tt avg} aggregate function, the compiler
copies the file {\tt syslibinc/flraggavg\_inc.flh} to the output {\tt .P}
file.  Since {\tt syslibinc/flraggavg\_inc.flh} contains the code to load
the library {\tt syslib/flraggavg.P}, this library will be loaded together
with that output file. The association between the libraries and the files
that need to be included to provide the appropriate functionality is
implemented in the file {\tt flrlibman.P}, which also implements the
utility used to load the libraries.

While {\tt syslib/} directory contains the libraries implemented in Prolog,
the {\tt lib/} directory contains libraries implemented in \FLORA itself.
Apart from that, the two types of libraries differ in functionality.  The
libraries in {\tt syslib/} implement the primitives that are part of the
syntax of the \FLORA language itself. In contrast, the libraries in {\tt
  lib/} are utilities that are part of the system, but not part of the
syntax. An example is the pretty-printing library.  Methods and predicates
defined in the libraries in {\tt lib/} are accessible through the {\tt
  @flora(lib-name)} system module and (unlike user modules) they are loaded
automatically at startup.

There are several subdirectories that hold the various files that contain
definitions included at compile time. These will be described in a
technical document.

A number of other important directories contain the various included files
(many of which include other files). The directory {\tt flrincludes/}
contains the all-important {\tt flora\_terms.flh} file, which defines all
the names used in the system. These names are defined as preprocessor
macros, so that it would be easy to change them, if necessary.
The directory {\tt genincludes/} currently contains the already mentioned
patch rules. The file {\tt flrpatch.fli} is a template, and {\tt
  flrpatch.flh}, which contains the actual patch rules, is generated from
{\tt flrpatch.fli} during the installation.

The directory {\tt includes/} contains (among others) the header file,
which defines the a number of important macros ({\it e.g.}, {\tt
  FLORA\_THIS\_WORKSPACE}) that wrap all the names with prefixes to
separate the different modules of the user program.  The directory {\tt
  headerinc/} is another place where the template files are located. Each
of these files contains just a few {\tt \#include} statements, mostly for
the files in the {\tt closure/} directory (which, if you recall, contains
pieces of the trailer). When the system is installed certain combinations
of these files are concatenated and dumped into the {\tt trailer/}
directory. Recall that the files in the {\tt trailer/} directory are
trailers that implement the closure axioms (there are three trailers:
without equality, with standard equality, and with \fl equality).  This
double-indirection is needed to simplify the installation procedure and to
eliminate code duplication among the various trailers.

The directory {\tt p2h} contains (the only!) C program in the system. It
implements conversion of Prolog terms to HiLog and back. Finally, the {\tt
  pkgs/} directory is empty. Some day it will contain add-on programs, such
as Internet access, etc.


\newpage

\bibliography{flora2}

\printindex

\end{document}
