Jtools

There are a lot of new features to be found in version 2.0.0, including keyword arguments, arithmetic in arguments, many new specials, and bug fixes.

* `2.0.0`
* Numerous new language features
* Support for arithmetic in arguments. The supported operators are
`-`, `+`, `*`, `/`, `//` (floor division), `**` (exponentiation), and `%`. The operators can be used any
place a value is valid within an argument, such as `$special(14000 * 2)`, `$special(value // 2)`,
`$special([1, 1+1, 1+2])`. The order of operations follows typical precedence, and arithmetic
can be nested in `()`.
* Support for keyword arguments:`$index("value", fallback=12)`
* Whitespace is allowed in a lot more places in a query now, which is very helpful since both
JavaScript and Python support multi-line strings.
* Performance increase for cases were a `Query` field doesn't have any specials. A faster parsing
method can be used for about a 40x performance increase in creating the `Query` object. Note, this
just speeds up `Query` creation and not the speed of `.single()`, `.many()`, etc.
* Added functionality so that `Filter` values can be queries.
* Using JSON: `{ field: <field>, operator: <op>, value: { query: <value query> } }`
* Using `Key`: `Key(<field>).<op>(Key(<value_query>))`
* For example: `Key("tag.tag1").gt(Key("tag.tag2"))`
* Four new filters: `subset`, `!subset`, `superset`, `!superset`. These should be read
`field value <op> filter value`, so `subset` means all of the values returned from the field query
are in the filter value, which allows better filtering when both the field query and value are iterable.
* Many new specials
* `$key_of_min_value` - Gets the key of the min value in an dict/map/object
* `$key_of_max_value` - Gets the key of the max value in an dict/map/object
* `$time_part(part) -> int` - Get a specific part of a datetime/moment object. Valid values for `part` are as follows:
* 'millisecond'
* 'second'
* 'minute' - Starting from 0
* 'hour' - Starting from 0
* 'day' - Day of month, starting from 1
* 'month' - Month of year, starting from 1
* 'year'
* 'dayOfWeek' - Value in 0-6, corresponding to Monday-Sunday
* 'dayOfYear' - Day of year, starting from 1
* `$min` and `$max`
* `$arith(op, arg_value)` - Perform an arithmetic operation on the current value. `op` can be
any of the support [math operators](math-operators).
* `$lowercase`, `$uppercase`, and `$titlecase`
* `$filter(field, op, value, single=true)` OR `$filter({<filter>}, single=true)` OR
`$filter([<filters>], single=true)` - Allow a single value or list of values to be filtered.
The filters should be formatted that same way they are for `Filter`.
* `$pipeline(pipeline)` - Apply multiple specials to value in a given order. Can be very useful
when used in conjunction with `$map` to apply multiple specials at once. `pipeline` must be of format:

[
<special>

OR

[<special>, arg1, arg2, ..., (optional) map/object/dict of keyword arguments],
...
]

for example

$pipeline([
['index', 'balance'],
['range', 1],
['replace', {'old': ',', 'new': ''}],
['float']
])

is the same as
$index("balance").$range(1).$replace(old=",", new="").$float

* Updates to old specials
* `$index(i, fallback=null, extended=false)` - added `extended` argument to allow
`$index` to support any valid JQL query for `i` if `extended=true`
* Bug fixes
* Fixed issue with filters not shortcutting properly
* Fixed Python issue with `$print`
* Fixed issues with `$fallback` with `Filter` and `Formatter`
* Fixed issue causing an error when trying to use an integer value in
`$sort` and `$group_by`

* `1.1.5`
* Unify `README` between Python and JavaScript versions
* Expand documentation

* `1.1.4`
* Added `$value_map`, which allows the values on an map/dict/object to be modified with a special, either in-place
or on a duplicate
* Exposed `context` so additional fields can manually be put into the current query space. This was already
being used by `$store_as`. `context` can be passed to any `.single()` or `.many()` call.
* Additionally, `Filter.many()` is now placing `INDEX` into the query space to allow
items to be filtered by their 0-based index

* `1.1.3`
* Changed the behavior of `Query("")`, from returning the fallback value, to returning the source data element itself.
For example, `Query("").single(data) == data`.
* Added `SpecialNotFoundError`, which is raised when an invalid special is queried. Can be imported as
`from jtools import SpecialNotFoundError`
* Added new specials
* `$store_as(name)` Store the current query value in the current context for later use in the query. This does not
change the underlying data being queried.
* `$group_by(key="", count=false)` Take an incoming list and group the values by the specified key.
Any valid JQL query can be used for the key, so `""` means the value itself. The result by default will be
keys to a list of values. However, if `count=true`, then the result will be keys to the number of elements with each
key.
* `$sort(key="", reverse=false)` Sort an incoming list of values by a given key which can be any valid JQL query.
By default, `key=""` means the top-level value will be sorted on.
* `$dict` Take an incoming list of `(key, value)` pairs and make a dict out of them.
* `$join_arg(arg, sep=', ')` Similar to `$join` except this operates on an argument instead of the query value.
Essentially a shortened form of `$inject(arg).$join(sep)`.
* Changed the underlying special function definition to now include the keyword argument `context`. This argument is
implemented to only be accessed by name to avoid collision if the user provides too many arguments in their query.
The purpose of the context is to support specials adding values temporarily to the data
namespace of the query, like `$store_as` does.

* `1.1.2`
* Minor changes to documentation
* Mostly just to get version back on track with repository

* `1.1.1`
* Add `antlr4-python3` requirement to `setup.py` so that installation will get the needed dependencies
* Change `JQL` so that field and special names must only contain `[-a-zA-Z0-9_]`. `$index` can be used to get fields
with prohibited characters. The change was to support more formatting use-cases, like `Age: age, DOB: dob`, which
previously would have failed because the `,` would have been considered part of the field name.
* Change `Formatter` so that `fallback` is just a string that is substituted for invalid queries, instead of being
the entire return value. Previously, `"Age: missing"` would result in `None`, not it results in `"Age: <missing>"`.
This change allows for better debugging as it becomes clear exactly which queries are failing.
* Add function docstrings

* Rename `Getter` to `Query` to more accurately describe what the class does
* Migrate queries to use `JQL`
* The migration opens the door to nested queries in `Query`, allowing queries, prefixed with to be used as arguments to specials, or even as values in the supported argument data structures
* Special arguments are no longer parsed as JSON, allowing features like sets, query nesting, and support for single and double quoted strings.
* `Formatter` no longer uses `{{}}` to surround queries. Instead, all queries must be prefixed with ``, so `"{{name}} {{age}}" -> "name age"`. must be used to get a literal in a formatted string: `"bobgmail.com"` -> `"bobgmail.com"`
* `Formatter` got about a 2x performance boost
* Added `$wrap(prefix, suffix)` to combine `$prefix` and `$suffix`
* Added `$remove_nulls`
* Added `$lookup(map, fallback=None)`
* Added `$wildcard(next, just_value=True)`, which allows level of nesting to be "skipped", such that a list of sub-values where next is present
* Added a fallback argument to `$index`
* Added `$print` to display the current value in the query
* Added `$injec`t to allow any valid argument value to be injected into the query to be accessed and transformed by subsequent fields and specials