Package com.salesforce.omakase.writer

Interface CustomWriter<T extends Writable>

  • Type Parameters:
    T - The Type of unit being overridden.
    public interface CustomWriter<T extends Writable>
    Customizes the writing of a particular Syntax unit.

    This allows you to override (or augment) the writing of any Syntax unit.

    Important: Some syntax units will not have their overrides kick in unless the parent unit is refined. For example, a ClassSelector override will not be utilized unless the parent Selector is refined. See the main readme file for more information about refinement.

    Also Important: The write method will only be called if the unit is writable (see Writable.isWritable()). This may be false if the unit was destroyed/removed.

    Note that custom writers may need to handle the writing (or not writing) of CSS comments on their own. For assistance with this see StyleWriter.appendComments(Iterable, StyleAppendable). Also see Syntax#writesOwnComments() and Syntax#writesOwnOrphanedComments().

    • Method Detail

      • write

        boolean write​(T unit,
              StyleWriter writer,
              StyleAppendable appendable)
       throws IOException
        Writes the given unit to the given StyleAppendable.

        Notes for implementation:

        You can completely bypass the default writing behavior of the unit by simply writing out arbitrary content to the StyleAppendable.

        If you are augmenting the write process instead, you can output the default representation of the unit by calling StyleWriter.writeInner(Writable, StyleAppendable, boolean) before or after your augmentations, as appropriate. You must pass false to this method to prevent looping back into this method.

        Do not use the StyleWriter in an attempt to write direct content (Strings, chars, etc...). Use the StyleAppendable.

        The StyleWriter should be used to make decisions based on writer settings (e.g., compressed vs. verbose output mode), as well as for writing inner or child Writables.

        This method will only be called if the unit is writable. It may not be writable if the unit was destroyed, for example, or is empty.

        Parameters:
        unit - The unit to write.
        writer - Writer to use for output settings and for writing inner Writables.
        appendable - Append direct content to this StyleAppendable.
        Returns:
        Return true if this writer handled the unit and no other writers should process it. Return false if you decide not to handle it.
        Throws:
        IOException - If an I/O error occurs.