Class 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.
    • Constructor Summary

      Constructors 
      Constructor Description
      DSCParser​(java.io.InputStream in)
      Creates a new DSC parser.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.