Package convex.core.data

Class Syntax

java.lang.Object
convex.core.data.AObject
convex.core.data.ACell
convex.core.data.Syntax
All Implemented Interfaces:
IValidated, IWriteable
public final class Syntax extends ACell
Class representing a Syntax Object. A Syntax Object wraps:
  • A Form (which may contain nested Syntax Objects)
  • Metadata for the Syntax Object, which may be any arbitrary hashmap
Syntax Objects may not wrap another Syntax Object directly, but may contain nested Syntax Objects within data structures. Inspired by Racket.

  • Field Details

    • EMPTY

      public static final Syntax EMPTY

    • EMPTY_META_PREFIX

      public static final AString EMPTY_META_PREFIX

  • Method Details

    • getType

      public AType getType()
      Description copied from class: ACell
      Gets the most specific known runtime Type for this Cell.
      Overrides:
      getType in class ACell
      Returns:
      The Type of this Call

    • createUnchecked

      public static Syntax createUnchecked(ACell value, AHashMap<ACell,ACell> meta)

    • create

      public static Syntax create(ACell value, AHashMap<ACell,ACell> meta)
      Wraps a value as a Syntax Object, adding the given new metadata
      Parameters:
      value - Value to wrap in Syntax Object
      meta - Metadata to merge, may be null
      Returns:
      Syntax instance

    • create

      public static Syntax create(ACell value)
      Wraps a value as a Syntax Object with empty metadata. Does not change existing Syntax objects.
      Parameters:
      value - Any CVM value
      Returns:
      Syntax instance

    • of

      public static Syntax of(ACell value)
      Wraps a value as a Syntax Object with empty metadata. Does not change existing Syntax objects.
      Parameters:
      value - Any value, will be converted to valid CVM type
      Returns:
      Syntax instance

    • of

      public static Syntax of(Object value)
      Create a Syntax Object with the given value. Converts to appropriate CVM type as a convenience
      Parameters:
      value - Value to wrap
      Returns:
      Syntax instance

    • getValue

      public <R> R getValue()
      Gets the value datum from this Syntax Object
      Type Parameters:
      R - Expected datum type from Syntax object
      Returns:
      Value datum

    • getMeta

      public AHashMap<ACell,ACell> getMeta()
      Gets the metadata for this syntax object. May be empty, but never null.
      Returns:
      Metadata for this Syntax Object as a hashmap

    • getStart

      public Long getStart()

    • getEnd

      public Long getEnd()

    • getSource

      public String getSource()

    • isCanonical

      public boolean isCanonical()
      Description copied from class: ACell
      Returns true if this Cell is in a canonical representation for message writing. Non-canonical objects may be used on a temporary internal basis, they must always be converted to canonical representations for external use (e.g. Encoding).
      Specified by:
      isCanonical in class ACell
      Returns:
      true if the object is in canonical format, false otherwise

    • isCVMValue

      public final boolean isCVMValue()
      Description copied from class: ACell
      Returns true if this Cell represents a first class CVM Value. Sub-structural cells that are not themselves first class values should return false, pretty much everything else should return true. Note: CVM values might not be in a canonical format, e.g. temporary data structures
      Specified by:
      isCVMValue in class ACell
      Returns:
      true if the object is a CVM Value, false otherwise

    • read

      public static Syntax read(Blob b, int pos) throws BadFormatException
      Decodes a Syntax object from a Blob encoding
      Parameters:
      b - Blob to read from
      pos - Start position in Blob (location of tag byte)
      Returns:
      New decoded instance
      Throws:
      BadFormatException - In the event of any encoding error

    • encode

      public int encode(byte[] bs, int pos)
      Description copied from class: ACell
      Writes this Cell's encoding to a byte array, including a tag byte which will be written first. Cell must be canonical, or else an error may occur.
      Specified by:
      encode in interface IWriteable
      Specified by:
      encode in class ACell
      Parameters:
      bs - A byte array to which to write the encoding
      pos - The offset into the byte array
      Returns:
      New position after writing

    • encodeRaw

      public int encodeRaw(byte[] bs, int pos)
      Description copied from class: ACell
      Writes this Cell's encoding to a byte array, excluding the tag byte.
      Specified by:
      encodeRaw in class ACell
      Parameters:
      bs - A byte array to which to write the encoding
      pos - The offset into the byte array
      Returns:
      New position after writing

    • print

      public boolean print(BlobBuilder bb, long limit)
      Description copied from class: AObject
      Prints this Object to a readable String Representation. SECURITY: Must halt and return false in O(1) time when limit of printing is exceeded otherwise DoS attacks may be possible.
      Specified by:
      print in class AObject
      Parameters:
      bb - BlobBuilder to append to. May be partially written if print limit exceeded
      limit - Limit of printing in string bytes
      Returns:
      True if fully printed within limit, false otherwise

    • validateCell

      public void validateCell() throws InvalidDataException
      Description copied from class: ACell
      Validates the local structure and invariants of this cell. Called by validate() super implementation. Should validate directly contained data, but should not validate all other structure of this cell. In particular, should not traverse potentially missing child Refs.
      Specified by:
      validateCell in class ACell
      Throws:
      InvalidDataException - If the Cell is invalid

    • validate

      public void validate() throws InvalidDataException
      Description copied from interface: IValidated
      Validates the complete structure of this object. It is necessary to ensure all child Refs are validated, so the general contract for validate is:
      1. Call super.validate() - which will indirectly call validateCell()
      2. Call validate() on any contained cells in this class
      Specified by:
      validate in interface IValidated
      Overrides:
      validate in class ACell
      Throws:
      InvalidDataException - If the data Value is invalid in any way

    • estimatedEncodingSize

      public int estimatedEncodingSize()
      Description copied from interface: IWriteable
      Estimate the encoded data size for this Cell. Used for quickly sizing buffers. Implementations should try to return a size that is highly likely to contain the entire object when encoded, including the tag byte. Should not traverse soft Refs, i.e. must be usable on arbitrary partial data structures
      Returns:
      The estimated size for the binary representation of this object.

    • getRefCount

      public int getRefCount()
      Description copied from class: ACell
      Gets the number of Refs contained within this Cell. This number is final / immutable for any given instance and is defined by the Cell encoding rules. WARNING: may not be valid id Cell is not canonical Contained Refs may be either external or embedded.
      Specified by:
      getRefCount in class ACell
      Returns:
      The number of Refs in this Cell

    • getRef

      public <R extends ACell> Ref<R> getRef(int i)
      Description copied from class: ACell
      Gets a numbered child Ref from within this Cell. WARNING: May be unreliable is cell is not canonical
      Overrides:
      getRef in class ACell
      Type Parameters:
      R - Type of referenced Cell
      Parameters:
      i - Index of ref to get
      Returns:
      The Ref at the specified index

    • updateRefs

      public Syntax updateRefs(IRefFunction func)
      Description copied from class: ACell
      Updates all Refs in this object using the given function. The function *must not* change the hash value of Refs, in order to ensure structural integrity of modified data structures. The implementation *should* re-attach any original encoding in order to prevent re-encoding or surplus hashing This is a building block for a very sneaky trick that enables use to do a lot of efficient operations on large trees of smart references. Must return the same object if no Refs are altered.
      Overrides:
      updateRefs in class ACell
      Parameters:
      func - Ref update function
      Returns:
      Cell with updated Refs

    • mergeMeta

      public Syntax mergeMeta(AHashMap<ACell,ACell> additionalMetadata)
      Merges metadata into this syntax object, overriding existing metadata
      Parameters:
      additionalMetadata - Extra metadata to merge
      Returns:
      Syntax Object with updated metadata

    • mergeMeta

      public static Syntax mergeMeta(ACell original, Syntax additional)
      Merge metadata into a Cell, after wrapping as a Syntax Object
      Parameters:
      original - Cell to enhance with merged metadata
      additional - Syntax Object containing additional metadata. Any value will be ignored.
      Returns:
      Syntax object with merged metadata

    • withMeta

      public Syntax withMeta(AHashMap<ACell,ACell> newMetadata)
      Replaces metadata on this Syntax Object. Old metadata is discarded.
      Parameters:
      newMetadata - New metadata map
      Returns:
      Syntax Object with updated metadata

    • withoutMeta

      public Syntax withoutMeta()
      Removes all metadata from this Syntax Object
      Returns:
      Syntax Object with empty metadata

    • unwrap

      public static <R> R unwrap(ACell x)
      Unwraps a Syntax Object to get the underlying value. If the argument is not a Syntax object, return it unchanged (already unwrapped)
      Type Parameters:
      R - Expected type of value
      Parameters:
      x - Any Object, which may be a Syntax Object
      Returns:
      The unwrapped value

    • unwrapAll

      public static <R extends ACell> R unwrapAll(ACell maybeSyntax)
      Recursively unwraps a Syntax object
      Parameters:
      maybeSyntax - Syntax Object to unwrap
      Returns:
      Unwrapped object

    • getTag

      public byte getTag()
      Description copied from class: ACell
      Gets the tag byte for this cell. The tag byte is always equal to the first byte of the Cell's canonical Encoding, and is sufficient to distinguish how to read the rest of the encoding.
      Specified by:
      getTag in class ACell
      Returns:
      Tag byte for this Cell

    • toCanonical

      public ACell toCanonical()
      Description copied from class: ACell
      Converts this Cell to its canonical version. Must return this Cell if already canonical, may be O(n) in size of value otherwise.
      Specified by:
      toCanonical in class ACell
      Returns:
      Canonical version of Cell