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 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

  • 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 object represents a first class CVM Value. Sub-structural cells that are not themselves first class values should return false. 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​(ByteBuffer bb) throws BadFormatException
      Throws:
      BadFormatException

    • 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
      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 void print​(StringBuilder sb)
      Description copied from class: AObject
      Prints this Object to a readable String Representation
      Specified by:
      print in class AObject
      Parameters:
      sb - StringBuilder to append to

    • toString

      public String toString()
      Description copied from class: ACell
      Returns the String representation of this Cell. The String representation is intended to be a easy-to-read textual representation of the Cell's data content.
      Overrides:
      toString in class ACell

    • 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 Valie 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 likely to contain the entire object when represented in binary format, including the tag byte.
      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. 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.
      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. 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 written as the first byte of the Cell's 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. Returns this Cell if already canonical.
      Specified by:
      toCanonical in class ACell
      Returns:
      Canonical version of Cell