DSCParser
Date: 2016-04-28

org.apache.xmlgraphics.ps.dsc

## Class DSCParser

- java.lang.Object
- - org.apache.xmlgraphics.ps.dsc.DSCParser

- All Implemented Interfaces:
    DSCParserConstants

      public class DSCParser
      extends java.lang.Object
      implements DSCParserConstants

  Parser for DSC-compliant PostScript files (DSC = Document Structuring Conventions). The parser is implemented as a pull parser but has the ability to act as a push parser through the DSCHandler interface.

- - ### Field Summary

    - ### Fields inherited from interface org.apache.xmlgraphics.ps.dsc.DSCParserConstants

      `COMMENT, DSC_COMMENT, EOF, HEADER_COMMENT, LINE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DSCParser(java.io.InputStream in)` Creates a new DSC parser.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(DSCListener listener)` Adds a DSC event listener.
    `DSCEvent` | `getCurrentEvent()` Returns the current event.
    `java.io.InputStream` | `getInputStream()` Returns the InputStream the PostScript code is read from.
    `java.lang.String` | `getLine()` Returns the current PostScript line.
    `boolean` | `hasNext()` Indicates whether there are additional items.
    `boolean` | `isCheckEOF()` Indicates whether the parser is configured to check for content after the EOF comment.
    `boolean` | `isListenersDisabled()` Indicates whether the listeners are currently disabled.
    `int` | `next()` Steps to the next item indicating the type of event.
    `DSCComment` | `nextDSCComment(java.lang.String name)` Advances to the next DSC comment with the given name.
    `DSCComment` | `nextDSCComment(java.lang.String name, PSGenerator gen)` Advances to the next DSC comment with the given name.
    `DSCEvent` | `nextEvent()` Steps to the next item returning the new event.
    `PostScriptComment` | `nextPSComment(java.lang.String prefix, PSGenerator gen)` Advances to the next PostScript comment with the given prefix.
    `void` | `parse(DSCHandler handler)` Starts the parser in push parsing mode sending events to the DSCHandler instance.
    `protected void` | `parseNext()` Parses the next event.
    `DSCEvent` | `peek()` Returns the next event without moving the cursor to the next event.
    `protected java.lang.String` | `readLine()` Reads one line from the input file
    `void` | `removeListener(DSCListener listener)` Removes a DSC event listener.
    `void` | `setCheckEOF(boolean value)` Tells the parser whether to check for content after the EOF comment.
    `void` | `setFilter(DSCFilter filter)` Sets a filter for DSC events.
    `void` | `setListenersDisabled(boolean value)` Allows to disable all listeners.
    `void` | `setNestedDocumentHandler(NestedDocumentHandler handler)` Sets a NestedDocumentHandler which is used to skip nested documents like embedded EPS files.
    `protected void` | `warn(java.lang.String msg)` This method is used to write out warning messages for the parsing process.

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

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

- - ### Constructor Detail

    - #### DSCParser

          public DSCParser(java.io.InputStream in)
                    throws java.io.IOException,
                           DSCException

      Creates a new DSC parser.
      Parameters:
        `in` - InputStream to read the PostScript file from (the stream is not closed by this class, the caller is responsible for that)
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

  - ### Method Detail

    - #### getInputStream

          public java.io.InputStream getInputStream()

      Returns the InputStream the PostScript code is read from.
      Returns:
        the InputStream the PostScript code is read from

    - #### warn

          protected void warn(java.lang.String msg)

      This method is used to write out warning messages for the parsing process. Subclass to override this method. The default implementation writes to logger.
      Parameters:
        `msg` - the warning message

    - #### readLine

          protected java.lang.String readLine()
                                       throws java.io.IOException,
                                              DSCException

      Reads one line from the input file
      Returns:
        the line or null if there are no more lines
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### parse

          public void parse(DSCHandler handler)
                     throws java.io.IOException,
                            DSCException

      Starts the parser in push parsing mode sending events to the DSCHandler instance.
      Parameters:
        `handler` - the DSCHandler instance to send the events to
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### hasNext

          public boolean hasNext()

      Indicates whether there are additional items.
      Returns:
        true if there are additonal items, false if the end of the file has been reached

    - #### next

          public int next()
                   throws java.io.IOException,
                          DSCException

      Steps to the next item indicating the type of event.
      Returns:
        the type of event (See `DSCParserConstants`)
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec
        `java.util.NoSuchElementException` - If an attempt was made to advance beyond the end of the file

    - #### nextEvent

          public DSCEvent nextEvent()
                             throws java.io.IOException,
                                    DSCException

      Steps to the next item returning the new event.
      Returns:
        the new event
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### getCurrentEvent

          public DSCEvent getCurrentEvent()

      Returns the current event.
      Returns:
        the current event

    - #### peek

          public DSCEvent peek()

      Returns the next event without moving the cursor to the next event.
      Returns:
        the next event

    - #### parseNext

          protected void parseNext()
                            throws java.io.IOException,
                                   DSCException

      Parses the next event.
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### getLine

          public java.lang.String getLine()

      Returns the current PostScript line.
      Returns:
        the current PostScript line
      Throws:
        `java.lang.IllegalStateException` - if the current event is not a normal PostScript line

    - #### nextDSCComment

          public DSCComment nextDSCComment(java.lang.String name)
                                    throws java.io.IOException,
                                           DSCException

      Advances to the next DSC comment with the given name.
      Parameters:
        `name` - the name of the DSC comment
      Returns:
        the requested DSC comment or null if the end of the file is reached
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### nextDSCComment

          public DSCComment nextDSCComment(java.lang.String name,
                                  PSGenerator gen)
                                    throws java.io.IOException,
                                           DSCException

      Advances to the next DSC comment with the given name.
      Parameters:
        `name` - the name of the DSC comment
        `gen` - PSGenerator to pass the skipped events though to
      Returns:
        the requested DSC comment or null if the end of the file is reached
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### nextPSComment

          public PostScriptComment nextPSComment(java.lang.String prefix,
                                        PSGenerator gen)
                                          throws java.io.IOException,
                                                 DSCException

      Advances to the next PostScript comment with the given prefix. This is used to find comments following the DSC extension mechanism.

      Example: To find FOP's custom comments, pass in "FOP" as a prefix. This will find comments like "%FOPFontSetup".

      Parameters:
        `prefix` - the prefix of the extension comment
        `gen` - PSGenerator to pass the skipped events though to
      Returns:
        the requested PostScript comment or null if the end of the file is reached
      Throws:
        `java.io.IOException` - In case of an I/O error
        `DSCException` - In case of a violation of the DSC spec

    - #### setFilter

          public void setFilter(DSCFilter filter)

      Sets a filter for DSC events.
      Parameters:
        `filter` - the filter to use or null to disable filtering

    - #### addListener

          public void addListener(DSCListener listener)

      Adds a DSC event listener.
      Parameters:
        `listener` - the listener

    - #### removeListener

          public void removeListener(DSCListener listener)

      Removes a DSC event listener.
      Parameters:
        `listener` - the listener to remove

    - #### setListenersDisabled

          public void setListenersDisabled(boolean value)

      Allows to disable all listeners. This can be used to disable any filtering, for example in nested documents.
      Parameters:
        `value` - true to disable all listeners, false to re-enable them

    - #### isListenersDisabled

          public boolean isListenersDisabled()

      Indicates whether the listeners are currently disabled.
      Returns:
        true if they are disabled

    - #### setNestedDocumentHandler

          public void setNestedDocumentHandler(NestedDocumentHandler handler)

      Sets a NestedDocumentHandler which is used to skip nested documents like embedded EPS files. You can also process those parts in a special way.

      It is suggested to use the more generally usable `addListener(DSCListener)` and `removeListener(DSCListener)` instead. NestedDocumentHandler is internally mapped onto a `DSCListener`.

      Parameters:
        `handler` - the NestedDocumentHandler instance or null to disable the feature

    - #### setCheckEOF

          public void setCheckEOF(boolean value)

      Tells the parser whether to check for content after the EOF comment. This can be disabled to skip nested documents.
      Parameters:
        `value` - true if the check is enabled

    - #### isCheckEOF

          public boolean isCheckEOF()

      Indicates whether the parser is configured to check for content after the EOF comment.
      Returns:
        true if the check is enabled.