Haystack Core

A core haystack implementation written in TypeScript.

- Core haystack type implementation.
- Haystack filter compilation and evaluation.
- Core haystack units implementation.
- Hayson encoding/decoding.
- Zinc 3.0 encoding/decoding.
- Haystack v4 defs full normalization, namespace and filter support.

This library is designed to be used in conjunction with these other haystack libraries depending on your use case...

- Haystack units: all haystack units.
- Haystack client: a client network library used for working with a haystack server.
- Haystack react: a set of high level React hooks and utilities for working with haystack data.

Installation

``
npm install @j2inn/haystack-core
`

APIs

$3

The following core Haystacks are implemented...

- HVal: the base class for all haystack values.
- HStr: a string value.
- HBool: a boolean true or false value.
- HNum: a numeric value.
- HCoord: co-ordinates with latitude and longitude.
- HXStr: an xstring implementation. Supports difference types and mime types.
- HDate: a date value.
- HTime: a time value.
- HDateTime: date and time.
- HSymbol: a symbol.
- HDict: dictionary - a map of key/haystack value pairs.
- HGrid: grid - a table of haystack values.
- HList: a list of haystack values.
- HMarker: a marker value.
- HNa: a non-applicable value.
- HRef: a reference value.
- HRemove: a remove value.
- HUri: a universal resource indicator value.

Each haystack value has a kind that can be queried. A haystack value can be encoded to Zinc by calling toZinc().

To convert a Zinc back to a haystack value see ZincReader.

$3

Haystack core has full support for units. The actual unit database implementation is stored in haystack-units. This enables a developer to import the whole unit database or just the units they're interested in working in.

$3

Haystack core has comprehensive support for Haystack v4 defs. Defs add an ontology to the pre-existing haystack taxonomy that is now formalized.

- Normalization: compile a number of libraries (typically held in a trio format) into a normalized def database that can be consumed by a namespace.
- Namespace: the defs database that can be queried.
- Filter: extra haystack filter support for making semantic queries using defs.

$3

The TrioReader and TrioWriter classes are used to read and write Trio files.

$3

Hayson is an alternative JSON encoding format for Haystack that's being promoted.

Hayson has full support in Haystack Core.

$3

An abbreviated namespace of useful methods has been created to make it easier to work with in environments such as a web browser.

$3

A full haystack filter compiler implementation is included.

To work with filters please see HFilter.

- Compile a haystack filter into a node AST (abstract syntax tree).
- Evaluate a Haystack Filter against some haystack values.
- Convert an AST Node tree back into a haystack filter.
- Build a filter using HFilterBuilder`

#### Design

##### Grammar

For the full grammar, please see the class definition for the Parser.

The main class to work with is HFilter. This class contains a number of high level methods that hide the complexity of working with the underlying parser.

##### Nodes

When a haystack filter string is parsed, it's converted into an AST (abstract syntax tree) hierarchy of Nodes.

The Node tree can be used in the following ways...

- Locally evaluated against some data to see if the filter matches or not.
- Converted to back into a haystack filter string.
- Modified via the relevant accessor methods for each different type of Node.
- Revalidated to ensure any changes to the Node tree doesn't contain errors.

##### Visitors

The visitor design pattern has been implemented to make it easy to generate code for different targets (i.e. a haystack filter string).

##### LocalizedError

Any errors caught during parsing are thrown as LocalizedError objects. This error object contains a lexicon key and arguments used for localization as well as a possible index number. If the index number is defined, it will specify the index number of the character that caused the error in the original haystack filter.

Misc links

- Haystack zinc
- Haystack filters
- Java Haystack Filter implemenation