Galax Manual: Command Line Tools

# Chapter 5 Command Line Tools

Galax supports the following stand-alone command-line tools:

galax-run
  The Galax XQuery interpreter.
galax-parse
  XML document parser and validator.
galax-mapschema
  XML Schema validator. Outputs XML Schema in XQuery type system.
galaxd
  The Galax network server. Executes Galax query plans issued from remote client (Under development).

## 5.1 `galax-run` : The Galax XQuery interpreter

The simplest way to use Galax is by calling the ’galax-run’ interpreter from the command line. The interpreter takes an XQuery input file, evaluates it, and yields the result on standard output.

Usage: `galax-run` `options` `query.xq`

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

    %  echo "<two>  1+1  </two>" > test.xq
    %  $(GALAXHOME)/bin/galax-run test.xq
    <two>2</two>

evaluates the simple query `<two> { 1+1 } </two>` and prints the XML value `<two>2</two>`.

The query interpreter has eight processing stages: parsing an XQuery expression; normalizing an XQuery expression into an XQuery core expression; static typing of a core expression; rewriting a core expression; factorizing a core expression; compiling a core expression into a logical plan; selecting a physical plan from a logical plan; and evaluating a physical plan.

Parsing, factorization, and compilation are always enabled. By default, the other phases are:

       -normalize on
       -static off
       -rewriting on
       -optimization on
       -dynamic on

By default, all result values (XML result, 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. Here are the available options. Default values are in `code` font.

-help,–help
  Display this list of options

### 5.1.1 Input options

-base-uri
  Sets the default base URI in the static context
-var
  `x`=literal, Binds the global variable `x` to literal constant
-doc
  `x`=filename, Binds the global variable `x` to document in filename
-context-item
  Binds the context item (“`.`” variable) to the document in filename or ’-’ for stdin
-context
  Load the context query from file or ’-’ for stdin

-xml-whitespace
  Preserves whitespace in XML documents [on/`off`]
-xml-pic
  Preserves PI’s and comments in XML documents [on/`off`]

### 5.1.2 Output options

-serialize
  Set serialization kind [wf, canonical, or `xquery`]

### 5.1.3 Evaluation options

-dynamic
  Evaluation phase [`on`/off]
-execute-normalized-expr
  All files are assumed to be normalized expressions for execution [on/`off`]
-execute-logical-plan
  All files are assumed to be logical plans for execution [on/`off`]
-print-xml
  Print XML result [`on`/off]
-output-xml
  Output XML to result file
-print-expr
  Print input expression [on/`off`]
-output-expr
  Output expr to file.

### 5.1.4 Normalization options

-normalize
  Normalization phase [`on`/off]
-print-normalized-expr
  Print normalized expression [on/`off`]
-output-normalized-expr
  Output normalized expression to file.

### 5.1.5 Static typing options

-static
  Static analysis phase [on/`off`]
-typing
  Static typing behavior [`none`, weak, or strong]
-print-type
  Print type of expression [on/`off`]
-output-type
  Output type to file.
-print-typed-expr
  Print typed expression [on/`off`]
-output-typed-expr
  Output typed expression to file.

### 5.1.6 Rewriting options

-rewriting
  Rewriting phase (use with -static on) [`on`/off]
-sbdo
  Document-order/duplicate-elimination optimization behavior [remove, preserve, sloppy, tidy, `duptidy`]
  remove
    Remove all distinct-docorder (ddo) calls from the query plan. May result in faulty evaluation plans.
  preserve
    Preserve all distinct-doc-order calls (no optimization).
  sloppy
    Delay duplicate removal and sorting until the last step in the path expression. May cause the number of duplicates in intermediate results to increase exponentially since they are not removed. Also, subsequent steps are evaluated multiple times when duplicates are generated in a step.
  tidy
    Removes all distinct-doc-order operations hat can be removed while maintaining duplicate-freeness and doc-order after each step.
  duptidy
    Only sorts and removes duplicates after a step if duplicates are generated. Intermediate results can be out of document order.
-print-rewritten-expr
  Print rewritten expression [on/`off`]
-output-rewritten-expr
  Output rewritten expression to file.

### 5.1.7 Factorization options

-factorization
  Factorization phase [`on`/off]
-print-factorized-expr
  Print factorized expression [on/`off`]
-output-factorized-expr
  Output factorized expression to file.

### 5.1.8 Compilation options

-print-comp-annotations
  Print compilation annotations [on/`off`]
-print-logical-plan
  Print logical plan [on/`off`]
-output-logical-plan
  Output logical plan to file.

### 5.1.9 Optimization options

-optimization
  Optimization phase [`on`/off]
-nested-loop-join
  Turns off sort/hash joins and uses only nested-loop joins [`on`/off]
-print-optimized-plan
  Print optimized plan [on/`off`]
-output-optimized-plan
  Output optimized plan to file
-print-physical-plan
  Print physical plan [on/`off`]
-output-physical-plan
  Output physical algebraic plan to file

### 5.1.10 Miscellaneous printing options

-verbose
  Emit descriptive headers in output [on/`off`]
-print-global
  Prints everything : prologs, exprs, etc.
-output-all
  Output everything to file.
-print-error-code
  Print only the error code instead of the full error message
-output-err
  Redirect error output to file.
-print-context-item
  Serializes the context item at the end of query evaluation
-output-context-item
  Output the context item to the given file
-print-annotations
  Print expression annotations [on/`off`]
-print-prolog
  Print query prolog [on/`off`]
-print-materialize
  Print whenever data materialization occurs [on/`off`]
-force-materialized
  Force materialization of values in variables [on/`off`]

### 5.1.11 Document projection options

-projection
  Document projection behavior [`none`, standard, or optimized]
-print-projection
  Prints the projection paths
-output-projection
  Output the projections paths to a file.
-print-projected-file
  Prints back the input document after projection
-output-projected-file
  Output the input document after projection into file.

### 5.1.12 Miscellaneous options

-version
  Prints the Galax version
-debug
  Emit debugging [on/`off`]
-monitor
  Monitors memory and CPU consumption [on/`off`]
-monitor-mem
  Monitors memory consumption [on/`off`]
-monitor-time
  Monitors CPU consumption [on/`off`]
-output-monitor
  Output monitor actibity to file
-internal-encoding
  Set the input character encoding representation, e.g., `utf8, iso88591`.
-output-encoding
  Set the output character encoding representation

## 5.2 `galax-parse`: XML parser and XML Schema validator

`galax-parse` parses an XML document and optionally validates the document against an XML Schema.

Usage: `galax-parse` `options` `document.xml`

-help,–help
  Display this list of options
-xml-whitespace
  Preserves whitespace in XML documents
-xml-pic
  Preserves PI’s and comments in XML documents
-validate
  Set validation on
-xmlschema
  Schema against which to perform validation
-dm
  Also builds the data model instance
-monitor
  Monitors memory and CPU consumption
-monitor-mem
  Monitors memory consumption
-monitor-time
  Monitors CPU consumption
-output-monitor
  Output monitor to file
-serialize-namespaces
  Set serialization of namespace nodes [strip/`preserve`]
-serialize
  Set serialization kind [canonical, `wf`, or xquery]
-print-error-code
  Print only the error code instead of the full error message
-output-encoding
  Set the output encoding representation

## 5.3 `galax-mapschema` : XML Schema validator

`galax-mapschema` maps XML schemas in xmlschema(s) into XQuery type expressions.

Usage: `galax-mapschema` `options` `schema.xsd`

-prefix
  Namespace prefix
-verbose
  Set printing to verbose
-import-type
  Set XML Schema import
-normalize-type
  Set XQuery type normalization
-print-type
  Set printing ofXQuery type
-print-normalized-type
  Set printing of normalized XQuery type
-output-type
  Output XQuery type in file
-output-normalized-type
  Output normalized XQuery type in file

## 5.4 `galaxd` : The Galax network server

`galaxd` is a server that allows Galax to be invoked over the network.

Usage: `galaxd [``options``] [query.xq]`

-port n
  Listen on port n. If the -port option is not used, the port defaults to 3324.
-s dir
  Simulate the directory dir. The server will act as if it is a part of a virtual network specified by dir. Each file host.xq in dir defines a server host in the virtual network. The virtual network is implemented on the localhost at ports 3324, 3325, …. Ports are assigned to the host.xq files in lexicographic order.

The query file query.xq should define a function named local:main(). An XQuery program can get the result of local:main() on host by calling doc("dxq://host/"). If the server is using a non-default port port, then use doc("dxq://host:port/").

### 5.4.1 Running simulations

It is sometimes useful to simulate a network of Galax servers on a single host. The -s option makes this possible. The way to set this up is to create a directory with a query file for each simulated host. For example, create a directory example with query files a.xq, b.xq, and c.xq. Each .xq file should define a local:main() function. Also, these files can refer to each other’s local:main() functions using doc("dxq://a/"), doc("dxq://b/"), and doc("dxq://c/"). Then start up the three servers as follows:

         galaxd -s example -port 3324
         galaxd -s example -port 3325
         galaxd -s example -port 3326

`galaxd` uses the -s option to find out what the virtual network will look like: it will have hosts a, b, and c, operating on non-virtual ports 3324, 3325, and 3326 on localhost. The first invocation of `galaxd` above uses port 3324, so it uses a.xq to define its local:main() function. Similarly, the second and third invocations use b.xq and c.xq, respectively.