Package org.incenp.obofoundry.kgcl

Class KGCLReader

java.lang.Object
org.incenp.obofoundry.kgcl.KGCLReader
public class KGCLReader extends Object
A parser to read a KGCL program from a file or a file-like source.

This is the main class to deserialise KGCL objects from their textual representation in the KGCL language. It abstracts most of the details of the underlying parser.

Typical usage: 

 KGCLReader reader = new KGCLReader("file.kgcl");
 if ( reader.read() ) {
     // The file was parsed successfully
     List<Change> changeset = reader.getChangeset();
     // Work with KGCL changes in changeset...
 } else {
     // Some syntax errors were found in the source file
     for ( KGCLSyntaxError error : reader.getErrors() ) {
         System.err.printf("KGCL syntax error: %s\n", error.toString());
     }
 }

  • Constructor Summary

    Constructors
    Constructor
    Description
    KGCLReader()
    Creates a new instance without an input source.
    KGCLReader(File kgclFile)
    Creates a new instance to read from a file.
    KGCLReader(InputStream kgclInput)
    Creates a new instance to read from a stream.
    KGCLReader(Reader kgclInput)
    Creates a new instance to read from a reader object.
    KGCLReader(String kgclFilename)
    Creates a new instance to read from a file.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<Change>
    getChangeSet()
    Gets the KGCL changeset that has been parsed from the underlying source.
    List<KGCLSyntaxError>
    getErrors()
    Gets all syntax errors that were found when parsing, if any.
    boolean
    hasErrors()
    Indicates whether parsing errors occurred.
    boolean
    read()
    Parses the KGCL program from the underlying source.
    boolean
    read(String text)
    Parses the KGCL program from the specified string.
    boolean
    read(String text, boolean reset)
    Parses the KGCL program from the specified string.
    void
    setLabelResolver(ILabelResolver resolver)
    Sets the label resolver.
    void
    setPrefixManager(org.semanticweb.owlapi.model.OWLOntology ontology)
    Deprecated.
    Using an ontology as the prefix manager is no longer recommended.
    void
    setPrefixManager(org.semanticweb.owlapi.model.PrefixManager manager)
    Sets the prefix manager to use to expand short identifiers.
    void
    setPrefixMap(Map<String,String> map)
    Sets the prefix map to use to resolve short identifiers.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • KGCLReader

      public KGCLReader()
      Creates a new instance without an input source. Use this constructor to parse KGCL from something else than a file or file-like source, coupled with the read(String) method. 
       KGCLReader reader = new KGCLReader();
 reader.setPrefixManager(...);
 reader.read("... kgcl commands ...");

    • KGCLReader

      public KGCLReader(Reader kgclInput) throws IOException
      Creates a new instance to read from a reader object.
      Parameters:
      kgclInput - The reader to parse the KGCL program from.
      Throws:
      IOException - If any non-KGCL I/O error occurs when reading from the reader object.

    • KGCLReader

      public KGCLReader(InputStream kgclInput) throws IOException
      Creates a new instance to read from a stream.
      Parameters:
      kgclInput - The stream to parse the KGCL program from.
      Throws:
      IOException - If any non-KGCL I/O error occurs when reading from the stream.

    • KGCLReader

      public KGCLReader(File kgclFile) throws IOException
      Creates a new instance to read from a file.
      Parameters:
      kgclFile - The file to parse the KGCL program from.
      Throws:
      IOException - If any non-KGCL I/O error occurs when reading from the file.

    • KGCLReader

      public KGCLReader(String kgclFilename) throws IOException
      Creates a new instance to read from a file.
      Parameters:
      kgclFilename - The name of the file to read from.
      Throws:
      IOException - If any non-KGCL I/O error occurs when reading from the file.

  • Method Details

    • setPrefixManager

      public void setPrefixManager(org.semanticweb.owlapi.model.PrefixManager manager)
      Sets the prefix manager to use to expand short identifiers. Most KGCL files are expected to use short-form identifiers (commonly known as “CURIEs”) for better readability. The prefix manager will convert such short-form identifiers into the equivalent canonical, full-length identifier.

      The prefix manager must be set before the read() is called, otherwise it will have no effect.

      If no prefix manager is set, the underlying KGCL parser will leave any CURIE it finds unexpanded. It will then be the caller’s responsibility to expand the CURIEs in the resulting KGCL changes.

      Parameters:
      manager - The OWL API prefix manager to use (may be null to leave the CURIEs in their unexpanded form).

    • setPrefixManager

      @Deprecated public void setPrefixManager(org.semanticweb.owlapi.model.OWLOntology ontology)
      Deprecated.
      Using an ontology as the prefix manager is no longer recommended. Provide the reader with an explicit PrefixManager (with setPrefixManager(PrefixManager)) instead.
      Sets the prefix manager from the specified ontology. This is a convenience method that automatically gets the prefix manager from a OWL API OWLOntology object and sets it as the prefix manager for the underlying KGCL parser.
      Parameters:
      ontology - The ontology whose prefix manager shall be used. If the ontology has been read from a OWLDocumentFormat that does not support prefixes, it is ignored and a default prefix manager is used instead.

    • setPrefixMap

      public void setPrefixMap(Map<String,String> map)
      Sets the prefix map to use to resolve short identifiers.

      This is equivalent to calling setPrefixManager(PrefixManager) with a PrefixManager object initialised with the provided map.

      Parameters:
      map - The map of prefix names to prefixes to use to resolve short identifiers.

    • setLabelResolver

      public void setLabelResolver(ILabelResolver resolver)
      Sets the label resolver.

      The label resolver will be used whenever a KGCL instruction refers to an entity by its label rather than by its identifier. It is the resolver’s responsibility to find the entity referenced by the label.

      If not set or null (which is the case by default), the reader will only be able to resolve labels (resulting in a parsing error) unless they have been used in a prior create... instruction, as in: 

       create class EX:0001 "my label"
 create exact synonym "my synonym" for "my label"
      Parameters:
      resolver - The resolver to use.

    • read

      public boolean read()
      Parses the KGCL program from the underlying source. After this method returns true, call the getChangeSet() method to get the result.

      This method may only be used if an input source has been specified to the constructor.

      Returns:
      true if the program was successfully parsed, or false if KGCL syntax errors were found.
      Throws:
      IllegalArgumentException - If the method is called while no input source has been set.

    • read

      public boolean read(String text)
      Parses the KGCL program from the specified string. After this method returns true, call the getChangeSet() method to get the result.

      This method does not require that an input has been set and may be called repeatedly on different inputs in the lifetime of the KGCLReader object.

      When this method is called repeatedly to parse several strings, parsed changes are accumulated across calls and a single subsequent call to getChangeSet() will return all the accumulated changes.

      Parameters:
      text - The KGCL program to parse.
      Returns:
      true if the program was successfully parsed, or false if KGCL syntax errors were found.

    • read

      public boolean read(String text, boolean reset)
      Parses the KGCL program from the specified string. After this method returns true, call the getChangeSet() method to get the result.

      If the reset parameter is set to true, then any changes that have been parsed previously are cleared, so that any subsequent call to getChangeSet() will only return the change(s) parsed by the current call.

      Parameters:
      text - The KGCL program to parse.
      reset - If true, clear any previously parsed changes and errors.
      Returns:
      true if the program was successfully parsed, or false if KGCL syntax errors were found.

    • getChangeSet

      public List<Change> getChangeSet()
      Gets the KGCL changeset that has been parsed from the underlying source. This method should be called after calling read() and checking that it returned true, indicating that parsing was successful.

      As a convenience, this method will call read() automatically if needed, if an input has been set. The caller should then use hasErrors() to check whether syntax errors were found.

      Returns:
      The KGCL changeset. May be an empty list if nothing has been parsed or if syntax errors were found.

    • hasErrors

      public boolean hasErrors()
      Indicates whether parsing errors occurred. Calling this method after read() is another way of checking whether syntax errors were found when parsing.
      Returns:
      true if at least one parsing error occurred, otherwise false.

    • getErrors

      public List<KGCLSyntaxError> getErrors()
      Gets all syntax errors that were found when parsing, if any.

      The parser does not throw any exception upon encountering a KGCL syntax error (it only throws IOException upon I/O errors unrelated to KGCL). Instead, all syntax errors are collected in the form of KGCLSyntaxError objects, which may be retrieved with this method.

      Returns:
      A list of objects representing the syntax errors (empty if no errors occurred).