3.1 Executing a query
The simplest way to use Galax is by calling the galax-run interpreter
from the command line. This chapter describes the most frequently
used command-line options. Chapter 5 enumerates
all the command-line options.
Before you begin, follow instructions in Section 2.3.2
for setting up your environment. Run the following query to make
sure your environment is set-up correctly:
% echo "<two> 1+1 </two>" > test.xq
% galax-run test.xq
<two>2</two>
Galax evaluates the expression <two> { 1+1 } </two> in file
test.xq and prints the XML value <two>2</two>.
By default, Galax parses and evaluates an XQuery main module, which
contains both a prolog and an expression. Sometimes it is useful to
separate the prolog from an expression, for example, if the same
prolog is used by multiple expressions. The -context option
specifies a file that contains a query prolog.
All of the XQuery use cases in $(GALAXHOME)/usecases are
implemented by separating the query prolog from the query
expressions.
Here is how to execute the Parts usecase:
% cd $(GALAXHOME)/usecases
% galax-run -context parts_context.xq parts_usecase.xq
The other use cases are executed similarly, for example:
% galax-run -context rel_context.xq rel_usecase.xq
3.2 Accessing Input
You can access an input document by calling the
fn:doc() function and passing the file name as an argument:
% cd $(GALAXHOME)/usecases
% echo "fn:doc('docs/books.xml')" > doc.xq
% galax-run doc.xq
You can access an input document by referring to the context item (the
``.'' dot variable), whose value is the document's content:
% echo "." >dot.xq
% galax-run -context-item docs/books.xml dot.xq
You can also access an input document by referring to a variable,
whose value is the document's content:
% echo "$doc" > var.xq
% galax-run -var doc=docs/books.xml var.xq
3.3 Controlling Output
By default, Galax serializes, or emits, the result of a query in the
XQuery representation of the XML value. For example, the result of
this query is serialized as the literal 2:
% echo "1+1">sum.xq
% galax-run sum.xq
2
If you want the output of your query to be a well-formed XML value,
then use the -serialize wf option:
% galax-run sum.xq -serialize wf
The result of this query is:
<?xml version="1.0" encoding="UTF-8"?>
<xq:result>2</xq:result>
Note that atomic values do not have a canonical representation in XML,
so Galax ``wraps'' atomic values in xq:result elements.
Try using the -serialize wf option on other examples:
% galax-run -var doc=docs/books.xml var.xq -serialize wf
By default, Galax serializes the result value to standard output. Use
the -print-xml option to serialize the result value to an output
file.
% galax-run -var doc=docs/books.xml var.xq -print-xml output.xml