Package org.apache.sis.io

Class LineAppender

  • All Implemented Interfaces:
    Flushable, Appendable
    public class LineAppender
extends Object
implements Flushable
    An Appendable which can apply different kinds of reformatting that depend on the End Of Line (EOL) occurrences. Available reformatting include inserting a a margin before each line, wrapping to a maximal line length and replacing tabulations or EOL characters. The actual work to be done can be enabled by invoking one or many of the following methods: In addition this class removes trailing whitespaces before end of lines.
    How line lengths are calculated
    Line length are measured in unit of Unicode code points. This is usually the same than the number of char primitive values, but not always. Combining characters are not yet recognized by this class, but future versions may improve on that.

    For proper line length calculation in presence of tabulation characters ('\t'), this class needs to known the tabulation width. The default value is 8, but this can be changed by a call to set­Tabulation­Width(int). Note that invoking that method affects only line length calculation; it does not replace tabulations by spaces. For tabulation expansion, see set­Tabulation­Expanded(boolean).

    Since:
    0.3

    Defined in the sis-utility module

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Appendable out
      The underlying character output stream or buffer.

    • Constructor Summary

      Constructors 
      Constructor Description
      LineAppender​(Appendable out)
      Constructs a default formatter.
      LineAppender​(Appendable out, int maximalLineLength, boolean isTabulationExpanded)
      Constructs a formatter which will wrap the lines at a given maximal length.
      LineAppender​(Appendable out, String lineSeparator, boolean isTabulationExpanded)
      Constructs a formatter which will replaces line separators by the given string.

    • Field Detail

      • out

        protected final Appendable out
        The underlying character output stream or buffer.

    • Constructor Detail

      • LineAppender

        public LineAppender​(Appendable out,
                    String lineSeparator,
                    boolean isTabulationExpanded)
        Constructs a formatter which will replaces line separators by the given string.
        Parameters:
        out - the underlying stream or buffer to write to.
        line­Separator - the line separator to send to out, or null for forwarding the EOL sequences unchanged.
        is­Tabulation­Expanded - true for expanding tabulations into spaces, or false for sending '\t' characters as-is.

      • LineAppender

        public LineAppender​(Appendable out,
                    int maximalLineLength,
                    boolean isTabulationExpanded)
        Constructs a formatter which will wrap the lines at a given maximal length.
        Parameters:
        out - the underlying stream or buffer to write to.
        maximal­Line­Length - the maximal number of Unicode characters per line, or Integer​.MAX_VALUE if there is no limit.
        is­Tabulation­Expanded - true for expanding tabulations into spaces, or false for forwarding '\t' characters as-is.

    • Method Detail

      • getMaximalLineLength

        public int getMaximalLineLength()
        Returns the maximal line length, in unit of Unicode characters (code point count). The default value is no limit.
        Returns:
        the current maximal number of Unicode characters per line, or Integer​.MAX_VALUE if there is no limit.

      • setMaximalLineLength

        public void setMaximalLineLength​(int length)
        Sets the maximal line length, in units of Unicode characters (code point count).
        Parameters:
        length - the new maximal number of Unicode characters per line, or Integer​.MAX_VALUE if there is no limit.

      • getTabulationWidth

        public int getTabulationWidth()
        Returns the current tabulation width, in unit of Unicode characters (code point count). The default value is 8.
        Returns:
        the current tabulation width in number of Unicode characters.

      • setTabulationWidth

        public void setTabulationWidth​(int width)
        Sets the tabulation width, in unit of Unicode characters (code point count).
        Parameters:
        width - the new tabulation width. Must be greater than 0.
        Throws:
        Illegal­Argument­Exception - if tab­Width is not greater than 0 or is unreasonably high.

      • isTabulationExpanded

        public boolean isTabulationExpanded()
        Returns true if this formatter expands tabulations into spaces. The default value is false, which means that '\t' characters are sent to the underlying appendable as-is.
        Returns:
        true if this formatter expands tabulations into spaces, or false if '\t' characters are forwarded as-is.

      • setTabulationExpanded

        public void setTabulationExpanded​(boolean expanded)
        Sets whether this class formatter expands tabulations into spaces.
        Parameters:
        expanded - true if this class shall expands tabulations into spaces, or false for forwarding '\t' characters as-is.

      • getLineSeparator

        public String getLineSeparator()
        Returns the line separator to be sent to the underlying appendable, or null if EOL sequences are forwarded unchanged.
        Returns:
        the current line separator, or null if EOL are forwarded as-is.

      • setLineSeparator

        public void setLineSeparator​(String lineSeparator)
        Changes the line separator to be sent to the underlying appendable. This is the string to insert in place of every occurrences of "\r", "\n", "\r\n" or other line separators. If null (the default), then the line separators given to the append methods are forwarded unchanged.
        Parameters:
        line­Separator - the new line separator, or null for forwarding EOL as-is.
        See Also:
        Characters​.is­Line­Or­Paragraph­Separator(int)

      • append

        public Appendable append​(char c)
                  throws IOException
        Writes a single character.
        Specified by:
        append in interface Appendable
        Parameters:
        c - the character to append.
        Returns:
        a reference to this Appendable.
        Throws:
        IOException - if an I/O error occurs.

      • append

        public Appendable append​(CharSequence sequence,
                         int start,
                         int end)
                  throws IOException
        Writes a portion of a character sequence.
        Specified by:
        append in interface Appendable
        Parameters:
        sequence - the character sequence to be written.
        start - index from which to start reading characters.
        end - index of the character following the last character to read.
        Returns:
        a reference to this Appendable.
        Throws:
        IOException - if an I/O error occurs.

      • clear

        public void clear()
           throws IOException
        Resets the Line­Appender internal state as if a new line was beginning. Trailing whitespaces not yet sent to the underlying appendable are discarded, and the column position (for tabulation expansion calculation) is reset to 0. This method does not write any line separator.
        Throws:
        IOException - if an error occurred while sending the trailing non-white characters to the underlying stream.

      • flush

        public void flush()
           throws IOException
        Sends all pending characters to the underlying appendable, including trailing whitespaces. Note that this method should preferably be invoked at the end of a word, sentence or line, since invoking this method may prevent Line­Appender to properly wrap the current line if the current position is in the middle of a word.

        Invoking this method also flushes the underlying stream, if flushable. A cheaper way to send pending characters is to make sure that the last character is a line or paragraph terminator, or to invoke clear().

        Specified by:
        flush in interface Flushable
        Throws:
        IOException - if an I/O error occurs.

      • onLineBegin

        protected void onLineBegin​(boolean isContinuation)
                    throws IOException
        Invoked when a new line is beginning. The default implementation does nothing, but subclasses can override this method for example in order to insert a margin on the left side before each line.

        If an implementation wishes to write characters, it shall do so by writing directly to out, not by invoking the append methods of this class.

        Parameters:
        is­Continuation - true if the new line is the continuation of the previous line after a "line wrap", or false if a line or paragraph separator has been explicitly sent to this formatter.
        Throws:
        IOException - if an error occurred while writing to out.

      • toString

        public String toString()
        Returns the content of this Appendable as a string if possible, or the localized "Unavailable content" string otherwise.
        Overrides:
        to­String in class Object
        Returns:
        the content of this Appendable, or a localized message for unavailable content.
        See Also:
        IO​.content(Appendable)