com.h3c.of.sw

## Class AbstractDefReader

- java.lang.Object
- - com.h3c.of.sw.AbstractDefReader

-     public abstract class AbstractDefReader
      extends Object

  Abstract base class for parsing text-based definition files.

  A definition file is a free format text file where lines beginning with the `#` symbol are treated as comments and ignored, as are blank lines. All other lines are treated as input and converted to "logical" lines. There will be one logical line per real (non-comment) line, except in the case where the backslash character is used to indicate line continuation. For example:

       1   # a comment
       2
       3   some input line
       4   another input line \
       5      continued on the next line
       6
       7   # another comment
       8   last line

  In this example, the parsed definition will consist of 3 logical lines:

       [3] some input line
       [4-5] another input line continued on the next line
       [8] last line

  The line numbers from the source file are indicated in square brackets.

  As the file is processed, subclasses have the opportunity to further validate each logical line by overriding the `parseLogicalLine(com.h3c.of.sw.AbstractDefReader.LogicalLine)` method. The implementation should return `null` if the line is acceptable, or a short string describing why it is not. These "errors" are collected and reported to the user in a single `ValidationException`, indicating the line numbers at which the errors occurred.

  The following example accepts only lines of the form `"key: some value"`:

       private static final Pattern RE_KV = Pattern.compile("(\\w+):\\s+(.*)");

       @Override
       protected String parseLogicalLine(LogicalLine line) {
          return RE_KV.matcher(line.getText()).matches()
                  ? null : "invalid format: \"" + line.getText() + "\"";
       }

  If we used this implementation to try and parse the example file above, the following exception would be thrown:

       com.h3c.util.ValidationException: Failed to parse sample.def
         Line 3: invalid format: "some input line"
         Line 4-5: invalid format: "another input line continued on the next line"
         Line 8: invalid format: "last line"

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AbstractDefReader.Line` Represents a single line of text from the definition file.
    `static class` | `AbstractDefReader.LogicalLine` Represents a logical (non-comment) line from the definition file; possibly an aggregate of several lines.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractDefReader(String path)` Constructs the definition file reader by reading in the specified text file, and parsing it into logical lines.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `List<String>` | `debugLines()` Returns a list of strings representing each of the logical lines, used by `AbstractDefn.toDebugString()`.
    `List<AbstractDefReader.LogicalLine>` | `getLines()` Returns an unmodifiable view of the logical lines.
    `String` | `getPath()` Returns the definition file path.
    `protected void` | `initStorage()` Subclasses may override this method to initialize their data model before the parsing actually starts.
    `protected void` | `parseDefinition(String[] lines)` Parses the definition file, creating a model of the logical lines.
    `protected abstract String` | `parseLogicalLine(AbstractDefReader.LogicalLine line)` This method is invoked once for every logical line in the definition file.
    `String` | `toDebugString()` Returns a multi-line string representation of the definition file.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### AbstractDefReader

          protected AbstractDefReader(String path)

      Constructs the definition file reader by reading in the specified text file, and parsing it into logical lines.
      Parameters:
        `path` - the path of the file

  - ### Method Detail

    - #### parseDefinition

          protected void parseDefinition(String[] lines)

      Parses the definition file, creating a model of the logical lines.
      Parameters:
        `lines` - the lines of the file

    - #### initStorage

          protected void initStorage()

      Subclasses may override this method to initialize their data model before the parsing actually starts. For example, if each logical line is going to be converted into a "Command", the `List<Command>` field in which to store the commands should be initialized from this method.

      This default implementation does nothing.

    - #### parseLogicalLine

          protected abstract String parseLogicalLine(AbstractDefReader.LogicalLine line)

      This method is invoked once for every logical line in the definition file. Note that comments and blank lines are ignored, and continuation lines are joined into a single logical line. If all is well, the method should return null; if there is a parse error, a short string describing the error should be returned.
      Parameters:
        `line` - the line to parse
      Returns:
        null if all is well, a short error description if not

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toDebugString

          public String toDebugString()

      Returns a multi-line string representation of the definition file.
      Returns:
        a multi-line string representation

    - #### getLines

          public List<AbstractDefReader.LogicalLine> getLines()

      Returns an unmodifiable view of the logical lines.
      Returns:
        the logical lines

    - #### debugLines

          public List<String> debugLines()

      Returns a list of strings representing each of the logical lines, used by `AbstractDefn.toDebugString()`.
      Returns:
        a list of strings, one per logical line

    - #### getPath

          public String getPath()

      Returns the definition file path.
      Returns:
        the path

Copyright © 2014. All Rights Reserved.