diff --git a/README.md b/README.md index e755d8aa..70526667 100644 --- a/README.md +++ b/README.md @@ -7,60 +7,53 @@ ## Background -Trees are everywhere in computing, representing more complex data structures than a list or sequence. +Trees are everywhere in computing, representing more complex data structures than a list or sequence with examples being -Before expanding on their utility consider the following +- JSON +- XML documents +- Computer languages -- [Expression](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression) along - with numerous helpers may be used to represent a runtime or execute numerous different language systems, which will be - discussed below. -- [ExpressionNumber](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/expression/ExpressionNumber.java) - . Within `Expression` evaluation support for either `BigDecimal` (slower but more precision) or `double` (faster but - limited precision), and is hot-switchable. -- [Node](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/Node.java) A node - represents a building block for a tree system, such as JSON, XML and more. -- [Select](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/select) A general - purpose XPATH like execution system that works over many tree systems, unlike XPATH which only works with XML. +Before expanding on their utility consider the following key classes/interfaces. -## [Expression](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression) +## [Expression](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression/Expression.java) -Expression and its sub-classes may be used to represent a parsed AST, with a built-in execution with sensible / useful -semantics. +An agnostic AST that supports complex expressions, including computation, logical operands and user defined functions. -A brief summary of supported features include: +- Immutable +- Functional +- Fully traversable +- May be evaluated - see below -- Delegating type coercion and checks to a user provided `EvaluationExpressionContext` to convert or fail. -- Support for named and lambda functions, where named functions are located by - the `EvaluationExpressionContext#namedFunction`. -- Prior to execution a function, the input parameters may be validated and possibly converted/coerced to the required - type. -- The grammar of the language in text form is not known, and irrelevant to the execution phase of the AST. -- If the default `Expression#toValue(ExpressionEvaluationContext)` is not right, create a sub-class - of `ExpressionVisitor` - and override all the visit methods to provide an alternative execution behaviour for each `Expression` sub-class type. +## [ExpressionNumber](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/expression/ExpressionNumber.java) -Two interesting examples of the Expression system include: +An abstraction that supports two number types -- The mini expression language used - by [select](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/select). The Node - selector parser includes a visitor which converts its parser tokens into equivalent Expression. -- The [spreadsheet](https://github.com/mP1/walkingkooka-spreadsheet) also uses Expressions to represent and execute a - spreadsheet formula. +- `BigDecimal` slower but more precision and various `Rounding` options. +- `double` faster but limited 64-bit precision +- `float` fastest but limited 32-bit precision [TODO](https://github.com/mP1/walkingkooka-tree/issues/722) -It should be possible (but I havent tried) to parse Javascript into an `Expression` and execute it with javascript -runtime semantics. +Either may be used within an expression and during computations with the answer matching the form provided by the +accompanying `ExpressionEvaluationContext`. -### [ExpressionEvaluationContext](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/expression/ExpressionEvaluationContext.java) +## [ExpressionEvaluationContext](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression/ExpressionEvaluationContext.java) -One considerable advantage of using this approach is that an `Expression` or `ExpressionFunction` can be assembled once -without finalizing the desired locale or other similar user parameters. Re-using the same expressions/functions in a -multi-user system with different parameters, simply means creating an appropriately -customised `ExpressionEvaluationContext`. +A context accompanies the evaluation of an `Expression` and provides context aware values and behaviours. -### [ExpressionFunction](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/expression/function/ExpressionFunction.java) +- 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](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression/FunctionExpressionName.java) + to + a [function](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression/function/ExpressionFunction.java) +- 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](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/expression/function/ExpressionFunction.java) This interface makes it easy to insert a function located by name into an `Expression` AST. Numerous methods are -provided with parallels to `java.lang.ref` including: +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 @@ -90,66 +83,45 @@ requirements, like locating cell/label references, parsing spreadsheet formula e ## [Node](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/Node.java) -This helps define a node within a tree or graph with emphasis for navigation in any direction, including branches, -children and leaves. +- 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](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/select) -Currently the following implementations are available which means selecting nodes using xpath like queries is possible. +- 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](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression) - Abstraction over an expression AST -- [File](https://github.com/mP1/walkingkooka-tree-file/tree/master/src/main/java/walkingkooka/tree/file) Abstraction - over a file system -- [Json](https://github.com/mP1/walkingkooka-tree-json/tree/master/src/main/java/walkingkooka/tree/json) Json objects -- [Patch](https://github.com/mP1/walkingkooka-tree-patch/tree/master/src/main/java/walkingkooka/tree/patch) JSON Patch - for all Node(s) -- [Pojo](https://github.com/mP1/walkingkooka-tree-pojo/tree/master/src/main/java/walkingkooka/tree/pojo) Java POJOs -- [Search](https://github.com/mP1/walkingkooka-tree-search/tree/master/src/main/java/walkingkooka/tree/search) Text with - highlight support -- [Xml](https://github.com/mP1/walkingkooka-tree-xml/tree/master/src/main/java/walkingkooka/tree/xml) Xml documents + - [Expression](https://github.com/mP1/walkingkooka-tree/tree/master/src/main/java/walkingkooka/tree/expression) + Described above + - [File](https://github.com/mP1/walkingkooka-tree-file/tree/master/src/main/java/walkingkooka/tree/file) A file system + abstraction, execute xpath over directories and files. + - [Json](https://github.com/mP1/walkingkooka-tree-json/tree/master/src/main/java/walkingkooka/tree/json) Json objects. + - [Patch](https://github.com/mP1/walkingkooka-tree-patch/tree/master/src/main/java/walkingkooka/tree/patch) JSON Patch + - [Pojo](https://github.com/mP1/walkingkooka-tree-pojo/tree/master/src/main/java/walkingkooka/tree/pojo) Java POJOs + - [Search](https://github.com/mP1/walkingkooka-tree-search/tree/master/src/main/java/walkingkooka/tree/search) Text + with highlight support + - [Xml](https://github.com/mP1/walkingkooka-tree-xml/tree/master/src/main/java/walkingkooka/tree/xml) Xml documents -If this interface is implement any new tree or graph can then be also be searched by the query systems more below. +### Additional Tree Navigation Technologies. -Some interesting and different navigation systems can be found in java, javascript and the internet, and implementations -that work with `Node` are available, and other +Additional standard tree navigation approaches are also implemented supporting `Node` are also provided in other repos. - [JSON POINTER](https://datatracker.ietf.org/doc/html/rfc6901) Another navigation system that may be used to identify a value within a JSON document. - [json-patch](http://jsonpatch.com) only works with JSON and not XML. - [XPATH](https://en.wikipedia.org/wiki/XPath) only works with XML and not JSON. -## [NodePointer](https://github.com/mP1/walkingkooka/blob/master/src/main/java/walkingkooka/tree/pointer/NodePointer.java) - -`NodePointer` provides an equivalent functionality for `Nodes` mentioned above, as what `Json pointer` provides for a -Json object graph, namely a path mechanism to locate a single `Node` with a tree. The `Node.pointer()` may be used to -fetch the pointer for an individual node relative to its root and may be used to locate another Node upon another graph. - -[JsonPointer RFC6901](https://tools.ietf.org/html/rfc6901) - -### [NodeSelector](https://github.com/mP1/walkingkooka-tree/blob/master/src/main/java/walkingkooka/tree/select/NodeSelector.java) - -A `NodeSelector` provides all xpath selectors to all `Nodes`. Predicate expressions and many xpath like functions are -implemented using `Expression` from above, with support for custom functions, which can easily be registered. Many xpath -like functions (eg: `starts-with()`) are already implemented with tickets for others outstanding. - -The `Selector` AST may be built by parsing a String holding the expression or by using the available assemblers/builders -present. See the many unit tests for examples. - -Some interesting examples of a `select query` can include: - -- Executing a query against a Node, like XPATH over XML. -- Executing the same query against a file system to find files, where files and directories are nodes, file attributes - such as file size are node attributes. -- Queries can also be executed over JSON. - - - -### Visitors +## 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](https://github.com/mP1/walkingkooka-spreadsheet) uses visitors in many use cases, including - rewrite formulas when a column/row is moved. +- The [spreadsheet project](https://github.com/mP1/walkingkooka-spreadsheet) 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.