
                     Galax: An XQuery 1.0 Implementation
                     -----------------------------------
                                 README 

** Galax Release: 0.3.5
December 2003

INDEX
=====
  I. What is XQuery 1.0?
 II. Downloading and installing Galax
III. What is Galax?
 IV. How to use Galax
  V. Credits
 VI. Copyright
VII. Feedback

I. What is XQuery 1.0?
======================

XQuery 1.0 is a query language for XML, defined by the World-Wide Web
Consortium (W3C), under the XML activity.

XQuery is a powerful language, which supports XPath 2.0 as a subset,
operations to construct new documents, SQL-like operations to do
selection, joins, and sorting, operations on namespaces, and
operations on XML Schema types.

XQuery is a functional language, which comes with an extensive library
of built-in functions, and has support for user-defined functions.

More information about XQuery can be found of the XML Query Working
Group Web page at:

    http://www.w3.org/XML/Query


II. Downloading and installing Galax
====================================

The Galax Web site is located at:

    http://db.bell-labs.com/galax/

The latest Galax distribution can be downloaded at:

    http://db.bell-labs.com/galax/distrib.html

Detailed installation instructions are located in the ./INSTALL file.


III. What is Galax?
===================

III.1 Features overview
-----------------------

Main features:

  * Galax is a fully functional implementation of XQuery 1.0. Galax
    supports XPath 2.0, including operations on document order,
    forward and backward axis, support for namespaces, operations on
    types, and user defined functions.
  * Galax is (almost!) up-to-date. It is based on the latest published
    working drafts. [somewhere between November, 2002 and April, 2003]
  * Galax supports UTF-8 and ISO-8859-1 character encodings.
  * Galax is portable, and runs under most modern platforms.
  * Galax supports direct calls from the command line as well as a
    simple Web form-based interface.

Alpha features:

  * Galax supports the two optional conformance features of XQuery:
    XML Schema import and static type checking.

  * Galax supports APIs for O'Caml, C, and, Java.  See
    ***galapi/README or README-API *** for how to use APIs.

  * Galax is designed for scalability. Although only a few
    optimization techniques are available in this release, Galax
    already supports some prototype optimizations and a SAX parser.

Limitations:

  * There is no support for operations on dates and time.
  * There is no support for collations.
  * Galax supports only a simplified type system (no named typing yet).
  * Element construction does not lose type information as specified.
  * XML Schema validation is only available as an external function
    (no support for validate expression).


III.2 Specifications
--------------------

Galax implements the latest XQuery 1.0 and XPath 2.0 Working Drafts
(somewhere between November, 2002 and May, 2003), the XML 1.0
Recommendation, the Namespaces in XML Recommendation, XML Schema
Recommendation (Parts 1 & 2).

    http://www.w3.org/TR/2002/WD-xquery-20030502/
    http://www.w3.org/TR/2002/WD-query-datamodel-20030502/
    http://www.w3.org/TR/2002/WD-xquery-operators-20030502/
    http://www.w3.org/TR/2002/WD-query-semantics-20030502/
    http://www.w3.org/TR/2000/REC-xml-20001006
    http://www.w3.org/TR/1999/REC-xml-names-19990114/
    http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/
    http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/

For more details about how Galax aligns with these various
specifications, please look at the ./STATUS file.  

For changes made in current release, see ./RELEASE_NOTES.

For open & closed bugs, see ./BUGS.

III.3 Support for XML Schema and static typing
----------------------------------------------

Galax provides several XML Schema enabled features. Notably, it
supports

  - (A partial implementation of) XML Schema validation.

  - A complete static type inference system:

    The Galax type system is based on the XQuery Formal Semantics and
    it allows type system allows to infer the type of queries, to
    detect errors in query at compile time, and to check the result of
    a query against a target XML Schema.


IV. How to use Galax
====================

IV.1 Overview
-------------

Galax can be used in various ways:

 * With one of the command-line tools:

    ---------------------------------------------------------------
   | galax     | The main Galax XQuery interpreter.                |
   | validate  | Stand-alone XML Schema validator. (alpha)         |
   | mapschema | Stand-alone XML Schema import to the XQuery type  |
   |           | type system (alpha)                               |
    --------------------------------------------------------------- 

   Command-line tools are documented below.

 * Through a simple form-based Web interface.

 * Through one of the O'Caml, C, or Java API's. 


IV.2 Command-line tools
-----------------------

galax : The main Galax XQuery interpreter 
-----------------------------------------

The simplest way to use Galax is by calling the 'galax' interpreter
from the command line. 'galax' essentially takes an XQuery written in
a file, evaluates it, and then return you an answer.

For instance, the following call from the Galax home directory:

   echo "1+1" > test.xq
   galax test.xq

will evaluate the simple query (1+1) and print the value '2'.

The query interpreter has five processing stages:
   parsing an XQuery expression;
   normalizing an XQuery expression into an XQuery core expression;
   static typing of a core expression;
   optimizing a core expression;
   and evaluating a core expression.

Parsing is always enabled.  By default, the other phases are:

   -normalize on 
   -static off   
   -optim off    
   -dynamic on 

By default, all results (XML answer, inferred type, etc.) are written
to standard output.

The command line options permit various combinations of phases,
printing intermediate expressions, and redirecting output to multiple
output files.
  
    Usage: galax [-version] [-context file] [-pic]  
      [-xml-whitespace]   [-xquery-whitespace]
      [-normalize on/off] [-static on/off] [-optim on/off] [-dynamic on/off] 
      [-print-xml on/off] [-output-xml filename]  
      [-print-type on/off] [-output-type filename]  
      [-print-expr on/off] [-output-expr filename]
      [-print-normalized-expr on/off] [-output-normalized-expr filename]  
      [-print-typed-expr on/off] [-output-typed-expr filename] 
      [-print-optimized-expr on/off] [-output-optimized-expr filename] 
      [-pretty-print filename] [-print-type-annotations on/off] 
      [-output-all filename]  [-serialize-wf] [-debug] [-verbose] 
      [-projection on/off] [-optimized-projection on/off]
      [-print-projection on/off] [-output-projection filename]
      [-print-projected-file on/off] [-output-projected-file filename]
      [-monitor on/off] [-output-monitor filename]
      [-blocking on/off]
      [-base-uri URI]
      query-filename(s)
    
      Evaluate XQuery queries in query-filename(s)
      Default values are in square brackets []:

      -version     Prints Galax version number
      -context     Loads the static context from file. This static
                   context is passed to all queries.

      -xquery-whitespace  Preserves whitespace in XQuery expressions [off]
      -xml-whitespace     Preserves whitespace in XML documents [off]
      -pic                Preserves PI's and comments in input documents [off]
    
      -normalize   Normalization phase [on]
      -static      Static analysis phase (requires -normalize on) [off]
      -optim       Optimization phase (most useful with -static on) [off]
      -dynamic     Evaluation phase (requires -normalize on) [on]
    
      -print-xml   Print XML result [on]
      -output-xml  Output XML to result file [standard output]

      -print-type  Print type of expression [off]
      -output-type Output type to file. [standard output]
    
      -print-expr  Print input expression [off]
      -output-expr Output expr to file. [standard output]
    
      -print-normalized-expr  Print normalized expression [off]
      -output-normalized-expr Output normalized expression to file. [standard output]
    
      -print-typed-expr       Print typed expression [off] 
      -output-typed-expr      Output typed expression to file. [standard output]
    
      -print-optimized-expr   Print optimized expression [off] 
      -output-optimized-expr  Output optimized expression to file. [standard output]
    
      -print-type-annotations  Print type annotations of expressions [off] 

      -pretty-print            Pretty printing the whole query, with
                               all of the results to file 'filename_pretty.xq'
 
      -monitor on              Monitor & print memory and CPU usage
      -output-monitor filename
      -blocking                Stops at the first error
      -base-uri                Sets the default base URI in the static context

      -output-all    Output everything to file. [off] 
      -serialize-wf  Serialize well-formed XML.  By default, result
                     is serialized as XQuery data model value.

      -projection            Projection of documents
      -optimized-projection  Optimized projection of documents
      -print-projection      Prints the projection paths
      -output-projection     Output the projections paths to a file.

      -debug         Emit debugging information
      -verbose       Emit descriptive headers in output [off]

      -help  display this list of options
      --help display this list of options


validate: XML parser and XML Schema validator
---------------------------------------------

  Usage: validate [-schema file -root qname [-prefix prefix]]
  [-typesyntax] [-print] [-whitespace] [-dm] [-wf] file(s)

     Validates XML documents in file(s) using specified schema

    -print       Pretty print the input document
    -whitespace  Preserve white space
    -dm          Also build the data model instance
    -wf          Checks only for well-formedness
    -prefix      Schema namespace prefix
    -typesyntax  Uses XQuery type system syntax instead of XML Schema syntax
    -schema      XML Schema file
    -root        Schema root type
    -help        display this list of options
    --help       display this list of options


mapschema : maps XML Schema document into XQuery type system
------------------------------------------------------------

    Usage: mapschema [-prefix prefix] [-typesyntax] [-output file]
    schemafile(s)

    Maps schemas in schemafile(s) into XQuery type expressions.

    -prefix Namespace prefix
    -output Emit mapped schema in file
    -typesyntax Uses XQuery type system syntax instead of XML Schema syntax
    -help  display this list of options
    --help display this list of options

IV.3 Web interface
------------------

The Web interface is a simple and convenient way to play around with
Galax. It is available on-line at:

    http://db.bell-labs.com/galax/demo/galax_demo.html

You can also re-compile the whole demo from the Galax source and get
it installed on your system. For this you will need an http server
running (Apache recommended), and follow the compilation instruction
in the ./website directory.


VI.4 Language API's
-------------------

Galax support user-level API's in Caml, C, and Java.
 
  *** See galapi/README (or $GALAXHOME/README_API) for how to use the APIs ***

If you have installed Galax from the binary distribution, those API's
should be available directly.

If you have intalled Galax from the source, you will need to select
the language(s) for which you need API support at configuration
time. Please check the ./INSTALL file for details about configuring
Galax for compilation.

Examples of how to use Galax from those API's are in the directories:

  examples/caml_api/     Examples in O'Caml
  examples/c_api/        Examples in C
  examples/java_api/     Examples in C


V. Credits
==========

Main development of Galax is done by:

  Jerome Simeon, Lucent, Bell Labs.
  Mary Fernandez, AT&T Labs.

Contributors:

  Cindy Chen, University of Massachusetts at Lowell.
  Byron Choi, University of Pennsylvania.
  Vladimir Gapeyev, University of Pennsylvania.
  Amélie Marian, Columbia University.
  Nicola Onose, Ecole Polytechnique, France.
  M. Radhakrishnan, AT&T Labs.
  Lori Resnick, AT&T Labs.
  Gargi Sur, University of Florida.
  Avinash Vyas, Bell Laboratories.
  Philip Wadler, University of Edinburgh.

VI. Copyright
=============

Galax is distributed under the terms of the Lucent Public License
Version 1.0 - see the LICENSE file for details.


VII. Feedback
=============

Feedback and bug reports can be sent by mail to:

    galax@lists.bell-labs.com

You can be subscribe to the Galax mailing list at:

    http://lists.bell-labs.com/mailman/listinfo/galax


