Skip to content

Latest commit

 

History

History
127 lines (94 loc) · 8.02 KB

README.md

File metadata and controls

127 lines (94 loc) · 8.02 KB
Raw

Build Status Coverage Status License Language grade: Java Total alerts J2CL compatible

Background

Trees are everywhere in computing, representing more complex data structures than a list or sequence with examples being

  • JSON
  • XML documents
  • Computer languages

Before expanding on their utility consider the following key classes/interfaces.

Expression

An agnostic AST that supports complex expressions, including computation, logical operands and user defined functions.

  • Immutable
  • Functional
  • Fully traversable
  • May be evaluated - see below

ExpressionNumber

An abstraction that supports two number types

  • BigDecimal slower but more precision and various Rounding options.
  • double faster but limited 64-bit precision
  • float fastest but limited 32-bit precision TODO

Either may be used within an expression and during computations with the answer matching the form provided by the accompanying ExpressionEvaluationContext.

ExpressionEvaluationContext

A context accompanies the evaluation of an Expression and provides context aware values and behaviours.

  • A powerful construct that supports many values and behaviours that modify evaluation of an expression.
  • Provides the preferred ExpressionNumber to use at evaluation time.
  • The context can provide for example locale aware values such as decimal point, current symbol and more.
  • Mapping of function names to a function
  • Switching locales or function mappings and more make it possible to re-evaluate an Expression simply providing a different ExpressionEvaluationContext.
  • XPath expressions and spreadsheet formula expressions both use Expression to compute their results.

ExpressionFunction

This interface makes it easy to insert a function located by name into an Expression AST. Numerous methods are provided to support meta programming and have a familiar feel to java reflection.

  • returnType()
  • parameters() provides a meta view of each individual parameter name, cardinality (including optional support), type and other Expression execution semantics.
  • purity Useful to decide whether an expression or function needs re-evaluation, useful for big spreadsheets with lots of cells to avoid a lot of costly and slow re-evaluation.

Numerous projects are available focusing on grouping functions that perform a similar or related task:

The following function project hold many generic functions.

These project below require a SpreadsheetExpressionEvaluationContext which helps support numerous spreadsheet type requirements, like locating cell/label references, parsing spreadsheet formula expressions and more.

Node

  • A node is the smaller unit within a tree with two basic forms leaves and parent nodes.
  • This provides the base interface for all Tree like representations in all my repos from parsing grammars, expressions and more.

Select

  • An almost identical in representation supporting constructs and functionality found in XPATH.

  • Language is almost identical to XPATH expressions both in syntax and textual representation and execution form.

  • Other represent

  • General purpose XPATH like execution system that works over many tree systems, unlike XPATH which only works with XML.

  • XPath expressions can work unaltered over the following tree abstractions.

    • Expression Described above
    • File A file system abstraction, execute xpath over directories and files.
    • Json Json objects.
    • Patch JSON Patch
    • Pojo Java POJOs
    • Search Text with highlight support
    • Xml Xml documents

Additional Tree Navigation Technologies.

Additional standard tree navigation approaches are also implemented supporting Node are also provided in other repos.

  • JSON POINTER Another navigation system that may be used to identify a value within a JSON document.
  • json-patch only works with JSON and not XML.
  • XPATH only works with XML and not JSON.

Visitors

Lists have powerful APIs such as java.util.stream.Stream and besides the navigation technologies briefly mentioned above it is often necessary to find and change an AST in some way or perhaps convert from/to another AST.

  • Visitors are provided for Expression and all Node implementations used in numerous interesting ways.
  • The spreadsheet project uses visitors in many use cases, to support writing formulas when a column/row is moved.
  • An ExpressionVisitor can be used to transform an Expression back to the ParserToken representation, allowing a roundtrip from parsing text into an expression and back.