File Syntaxes

Author: Jeff Dalton

Available syntaxes

I-X agents can handle a number of different text syntaxes for data stored in files and similar resources.

There is a general-purpose XML syntax that can be used to represent plans, domains and other objects that are meaningful in I-X. There is also an equally general-purpose XML/RDF representation, but it is less often used.

There are some specialised syntaxes for domains. Here are the ones that currently have their own documentation:

There are also some specialised syntaxes for plans:

The available syntaxes for an I-X agents such as and I-P2 or an I-Plan are listed near the end of the response to the "Help" -> "About ..." menu entry. The ones available by default can be found by using the "-help" argument to the file translator

Example:

File syntaxes:
   XML files ("xml")
   RDF and OWL files ("rdf" "owl")
      Not available in this agent
   List-TF files ("lsp" "ltf")
      Input must be a domain
      Output must be a domain
   O-Plan TF files ("tf")
      Output only
      Output must be a domain
   Checklist files as domains ("checklist")
      Input only
      Input must be a domain
   Initial world-state files ("init")
      Input must be a plan
      Output must be a plan
   Plans represented as LTF domains ("lpad")
      Input must be a plan
      Output must be a plan
   Text descriptions of plans ("txt")
      Output only
      Output must be a plan
   OWL-S files ("owls")
      Not available in this agent
      Input only
      Input must be a domain

On the input side, the syntaxes are not only for files. Any "resource" (URL, or entity in the classpath) can be used.

Some syntaxes are restricted to input or to output, and some can handle only certain classes of objects.

That a syntax is listed at all means that the corresponding syntax description object exists. For now, at least, there's always one for every syntax that has any support.

"Not available in this agent" means either that the I-X code that handles that syntax has not been included in the class path or that the the necessary imported code is not there.

The applicable syntax is determined by the file "type" or "extension" (the bit after the "."). The type(s) handled by each syntax are listed in parentheses after the syntax name. So OWL-S files, for example, must be ".owls". If they are named ".owl" or ".rdf", they won't be read correctly.

(We probably shouldn't allow ".owl" at all -- ".owl" should be for ontology definitions, which we can't meaningfully process -- but it's there for historical reasons, because people were saying "owl" for files that were RDF that just happened to have an OWL ontology for their class and property names.)

File synaxes also affect the filters in file-choosers. For example, if you're loading a plan, all syntaxes that might produce a plan will be individually selectable and are available together as "Plan files".

Note that this doesn't mean that the files necessarily contain plans. "xml" and "rdf" files, for example, might contain anything, and the only way for I-X to find out is to read them in and see.

Using file syntaxes in Java

For reasons of history and convenience, file-syntax utilities are in the ix.xml package (even though they can use any available syntax), and many of them are accessible using static methods of the XML class.

This section is incomplete and eventually needs to describe FileSyntaxManager and related classes; for now, it discusses only basic I/O.

Reading from files and URLs; writing to files

The syntax that is used is determined by the file "type" as described above. For example, "rescue.ltf" would be handled by the LTF syntax for domains.

At present, objects can be written only to files, but they can be read from any "resource", where a resource is specified by a file-name, a URL, or the name of a resource that can be obtained from the agent's classpath.

XML.readObject(String resourceName)

Parses the contents of the specified resource and returns a corresponding object.

XML.readObject(Class<T> desiredClass, String resourceName)

Parses the contents of the specified resource and returns a corresponding object if it is an instance of the specified class; otherwise a ClassCastException is thrown.

XML.writeObject(Object object, String fileName)

Writes a textual representation of the object to the specified file.

Examples:

    Plan p = (Plan)XML.readObject("plan1.xml");

    Plan p = XML.readObject(Plan.class, "plan1.xml");

    Domain d = XML.readObject(Domain.class, "rescue.ltf");

    XML.writeObject(p, "best-plan.xml");


Jeff Dalton <J.Dalton@ed.ac.uk>