Package ghidra.program.model.pcode

# Interface Encoder

All Known Subinterfaces:
  `PatchEncoder`

All Known Implementing Classes:
  `PackedEncode`, `PackedEncodeOverlay`, `XmlEncode`

public interface Encoder
An interface for writing structured data to a stream The resulting encoded data is structured similarly to an XML document. The document contains a nested set of \elements, with labels corresponding to the ElementId class. A single element can hold zero or more attributes and zero or more child elements. An attribute holds a primitive data element (boolean, long, String) and is labeled by an AttributeId. The document is written using a sequence of openElement() and closeElement() calls, intermixed with write*() calls to encode the data primitives. All primitives written using a write*() call are associated with current open element, and all write*() calls for one element must come before opening any child element. The traditional XML element text content can be written using the special ATTRIB_CONTENT AttributeId, which must be the last write*() call associated with the specific element.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Clear any state associated with the encoder The encoder should be ready to write a new document after this call.
  `void`
  `closeElement(ElementId elemId)`
  End the current element in the encoding The current element must match the given annotation or an exception is thrown.
  `boolean`
  `isEmpty()`
  The encoder is considered empty if the writeTo() method would output zero bytes
  `void`
  `openElement(ElementId elemId)`
  Begin a new element in the encoding The element will have the given ElementId annotation and becomes the \e current element.
  `void`
  `writeBool(AttributeId attribId, boolean val)`
  Write an annotated boolean value into the encoding The boolean data is associated with the given AttributeId annotation and the current open element.
  `void`
  `writeSignedInteger(AttributeId attribId, long val)`
  Write an annotated signed integer value into the encoding The integer is associated with the given AttributeId annotation and the current open element.
  `void`
  `writeSpace(AttributeId attribId, AddressSpace spc)`
  Write an address space reference into the encoding The address space is associated with the given AttributeId annotation and the current open element.
  `void`
  `writeString(AttributeId attribId, String val)`
  Write an annotated string into the encoding The string is associated with the given AttributeId annotation and the current open element.
  `void`
  `writeStringIndexed(AttributeId attribId, int index, String val)`
  Write an annotated string, using an indexed attribute, into the encoding.
  `void`
  `writeTo(OutputStream stream)`
  Dump all the accumulated bytes in this encoder to the stream.
  `void`
  `writeUnsignedInteger(AttributeId attribId, long val)`
  Write an annotated unsigned integer value into the encoding The integer is associated with the given AttributeId annotation and the current open element.

- ## Method Details

  - ### clear

    void clear()
    Clear any state associated with the encoder The encoder should be ready to write a new document after this call.

  - ### openElement

    void openElement(ElementId elemId) throws IOException
    Begin a new element in the encoding The element will have the given ElementId annotation and becomes the \e current element.
    Parameters:
      `elemId` - is the given ElementId annotation
    Throws:
      `IOException` - for errors in the underlying stream

  - ### closeElement

    void closeElement(ElementId elemId) throws IOException
    End the current element in the encoding The current element must match the given annotation or an exception is thrown.
    Parameters:
      `elemId` - is the given (expected) annotation for the current element
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeBool

    void writeBool(AttributeId attribId, boolean val) throws IOException
    Write an annotated boolean value into the encoding The boolean data is associated with the given AttributeId annotation and the current open element.
    Parameters:
      `attribId` - is the given AttributeId annotation
      `val` - is boolean value to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeSignedInteger

    void writeSignedInteger(AttributeId attribId, long val) throws IOException
    Write an annotated signed integer value into the encoding The integer is associated with the given AttributeId annotation and the current open element.
    Parameters:
      `attribId` - is the given AttributeId annotation
      `val` - is the signed integer value to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeUnsignedInteger

    void writeUnsignedInteger(AttributeId attribId, long val) throws IOException
    Write an annotated unsigned integer value into the encoding The integer is associated with the given AttributeId annotation and the current open element.
    Parameters:
      `attribId` - is the given AttributeId annotation
      `val` - is the unsigned integer value to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeString

    void writeString(AttributeId attribId, String val) throws IOException
    Write an annotated string into the encoding The string is associated with the given AttributeId annotation and the current open element.
    Parameters:
      `attribId` - is the given AttributeId annotation
      `val` - is the string to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeStringIndexed

    void writeStringIndexed(AttributeId attribId, int index, String val) throws IOException
    Write an annotated string, using an indexed attribute, into the encoding. Multiple attributes with a shared name can be written to the same element by calling this method multiple times with a different index value. The encoding will use attribute ids up to the base id plus the maximum index passed in. Implementors must be careful to not use other attributes with ids bigger than the base id within the element taking the indexed attribute.
    Parameters:
      `attribId` - is the shared AttributeId
      `index` - is the unique index to associated with the string
      `val` - is the string to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeSpace

    void writeSpace(AttributeId attribId, AddressSpace spc) throws IOException
    Write an address space reference into the encoding The address space is associated with the given AttributeId annotation and the current open element.
    Parameters:
      `attribId` - is the given AttributeId annotation
      `spc` - is the address space to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### writeTo

    void writeTo(OutputStream stream) throws IOException
    Dump all the accumulated bytes in this encoder to the stream.
    Parameters:
      `stream` - is the output stream
    Throws:
      `IOException` - for errors during the write operation

  - ### isEmpty

    boolean isEmpty()
    The encoder is considered empty if the writeTo() method would output zero bytes
    Returns:
      true if there are no bytes in the encoder