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 the instructions in Section 2.2 and 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 expression <two>{ 1+1 }</two> in file
test.xq and prints the result <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
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 using the -doc argument, which binds an external variable to the content of the given document file:
% echo ’declare variable $x external; $x’ > var.xq % galax-run -doc x=docs/books.xml var.xq
By default, Galax serializes the result of a query in a format that reflects the precise data model instance. For example, the result of this query is serialized as the literal 2:
% echo "document { 1+1 }"> docnode.xq
% galax-run docnode.xq
document { 2 }
If you want the output of your query to be as the standard prescribes, then use the -serialize standard option:
% galax-run docnode.xq -serialize standard 2
By default, Galax serializes the result value to standard output. Use the -output-xml option to serialize the result value to an output file.
% galax-run docnode.xq -serialize standard -output-xml output.xml % cat output.xml 2
By default, Galax compiles the given query an returns the corresponding result. The following options can be set to print the query as it progresses through the compilation pipeline .
-print-expr [on/off] Print input expression -print-normalized-expr [on/off] Print expression after normalization -print-rewritten-expr [on/off] Print expression after rewriting -print-logical-plan [on/off] Print logical plan -print-optimized-plan [on/off] Print logical plan after optimization -print-physical-plan [on/off] Print physical plan
As the output for the compiled query can be quite large, it is often convenient to set the output to verbose using -verbose on, which prints headers for each phase. For instance, the following command prints the original query, and the optimized logical plan for the query.
% galax-run docnode.xq -verbose on -print-expr on -print-optimized-plan on
Galax supports several extensions to XQuery 1.0, notably XML updates and a procedural extensions. To enable one of those extensions, you must use the corresponding language level option on the command line:
galax-run -language ultf (: W3C Update Facility :) galax-run -language xquerybang (: XQuery! Language :) galax-run -language xqueryp (: XQueryP Language :)
Some examples of each of the three languages are provided in the
$GALAXHOME/examples/extensions directory.