# Package com.singularsys.jep.misc.dictionary

package com.singularsys.jep.misc.dictionary
Classes to support associative array like operations.

The package provides a grammar matcher supporting a JSON like syntax for associative arrays, dictionaries or maps.

    dict = {'x':2, 'y':3}

and functions for operating on such dictionaries:

- `GetOr` – `getOr(dict,'x',-1)` – get the value associated with a key or a default value.
- `Get` – `get(dict,'x')` – get the value associated with a key, with configurable behaviour for missing keys.
- `ContainsKey` – `containsKey(dict,'x')` – test if the dict contains a key.
- `Put` – `put(dict,'x',5)` – sets the value associated with a key.
- `Remove` – `remove(dict,'x')` – removes an entry from the table.
- `Clear` – `clear(dict)` – clears the dict.
- `Keys` – `keys(dict)` – returns the set of keys as a list.
- `Values` – `values(dict)` – returns the set of values as a list.
- `Entries` – `entries(dict)` – returns the set of entries as a doubly nested list.
- `MakeMap` – `hashMap()`, `linkedMap()`, `treeMap()`, `hashMap(list)`, `linkedMap(list)`, `treeMap(list)` – creates maps of different types. The functions can either create empty maps, or create a map from an existing list. Each type can be used with the other methods in this package. The hashMap is unordered, linkedMap uses insertion order and treeMap sort the keys.

Three functions are defined but not implemented by default

- `EntriesIterable` – `entriesIter(dict)` – returns an iterator for the entries.
- `KeysIterable` – `keysIter(dict)` – returns an iterator for the keys.
- `ValuesIterable` – `valuesIter(dict)` – returns an iterator for the values.

Some configurations allow values can be omitted in which case the map functions like a set, that can be define using `set = {'x', 'y'}` and added to using `put('set','z')` . A special value `DictionaryComponents.getNullValue()` is used to represent a missing value, this can be set in the constructor.

The package can be configured either to represent maps as a `Map<Object,Object>`. or as doubly nested `Vector<Object>` , when each entry is a Vector with either 2 elements, the key and value; or a single element if the value is missing.

It can be set up using the `DictionaryComponents`

    jep = new Jep(
        new StandardConfigurableParser(),
        new DictionaryComponents(
            DictionaryComponents.Type.MAP_MISSING_VALUES));

Or explicitly

    // Object used to represent null values
    var nullValue = new Object();

    // Add operators for creating maps and map entries
    var ot = new StandardOperatorTable2();
    var listOp = ot.getList();
    Operator mapOp = new Operator(
        "map",
        new MapPfmc(),
        Operator.NARY + Operator.NOT_IN_PARSER);
    Operator entryOp = new Operator(
        "entry",
        new MapPfmc.MapEntryPfmc(
          MapGrammarMatcher.Type.ALLOW_MISSING_VALUES,
          nullValue),
        Operator.NARY + Operator.NOT_IN_PARSER);

    ot.addOperator(mapOp, listOp);
    ot.addOperator(entryOp, listOp);

    // Adds a grammar matcher for the {'x':1,'y':2} syntax
    var cp = new StandardConfigurableParser();
    var stm = cp.getSymbolTokenMatcher();
    var colon = new SymbolToken(":");
    var bopen = new SymbolToken("{");
    var bclose = new SymbolToken("}");
    var comma = stm.getSymbolToken(",");
    stm.add(colon);
    stm.add(bopen);
    stm.add(bclose);
    cp.addGrammarMatcher(new MapGrammarMatcher(
        MapGrammarMatcher.Type.ALLOW_MISSING_VALUES,
        bopen, bclose, colon, comma,
        mapOp, entryOp ));

    // Build the Jep instance.
    jep = new Jep(cp,ot);

    // Add functions
    jep.addFunction("get", new Get(nullValue));
    jep.addFunction("getOr", new GetOr(nullValue));
    jep.addFunction("containsKey", new ContainsKey());
    jep.addFunction("put",
      new Put(Put.Type.ALLOW_MISSING_VALUES, nullValue));
    jep.addFunction("remove",new Remove(nullValue));
    jep.addFunction("clear",new Clear(nullValue));
    jep.addFunction("keys", new Keys());
    jep.addFunction("values", new Values(nullValue));
    jep.addFunction("entries", new Entries(nullValue));
    jep.addFunction("size",new Size());
    jep.addFunction("hashMap", new MakeMap(MakeMap.Type.HashMap));
    jep.addFunction("linkedMap", new MakeMap(MakeMap.Type.LinkedMap));
    jep.addFunction("treeMap",  new MakeMap(MakeMap.Type.TreeMap));

    jep.reinitializeComponents();

Since:
  Jep 4.1
See Also:
  - `com.singularsys.jeptests.unit.misc.dictionary`
  - `CPConsole`

- Related Packages
  Package
  Description
  com.singularsys.jep.misc
  Miscellaneous components.
- Class
  Description
  Clear
  Clears the map.
  ContainsKey
  Tests if the map contains a given key.
  DictionaryComponents
  A set of components for parsing and operating on associative arrays.
  DictionaryComponents.DictionaryKeys
  Keys for the two operators used to build maps.
  DictionaryComponents.Type
  Type of configuration.
  DictionaryGrammarMatcher
  A GrammarMatcher for JSON like map syntax.
  DictionaryGrammarMatcher.Type
  Type of matcher.
  Entries
  Return the entries of a map a nested list of key-value pairs.
  EntriesIterable
  Return an `Iterable<Vector<Object>>` for the entries of a map.
  Get
  Gets the value associated with a key.
  GetOr
  Gets the value associated with a key, or a default value.
  Keys
  Return the keys of a map a nested list of key-value pairs.
  KeysIterable
  Return an `Iterable<Object>` for the keys of a map.
  MakeMap
  Create a map of a given type, either creates an empty map or uses a list or map of data.
  MakeMap.Type
  Configuration type.
  MapPfmc
  PostfixMathCommand for creating a `Map`.
  MapPfmc.Entry
  Value returned for an individual map entry.
  MapPfmc.MapEntryPfmc
  PostfixMathCommand for individual entries
  Put
  Puts a key-value pair into a map.
  Put.Type
  Configuration type
  Remove
  Removes entries with matching key from the map.
  Size
  The number of entries of the map.
  Values
  Return the values of a map a nested list of key-value pairs.
  ValuesIterable
  Return an `Iterable<Object>` for the values of a dictionary.