<commit_before>json-ls
=======

JSON helpers for Loom


## installation

Download the library into its matching sdk folder:

    $ curl -L -o ~/.loom/sdks/sprint33/libs/Json.loomlib \
        https://github.com/pixeldroid/json-ls/releases/download/v0.0.1/Json-sprint33.loomlib

To uninstall, simply delete the file:

    $ rm ~/.loom/sdks/sprint33/libs/Json.loomlib


## usage

0. declare a reference to the Json loomlib in your `.build` file:
    *
    ```json
    "references": [
        "System",
        "Json"
    ],
    ```
0. import `pixeldroid.json.Json`
0. instantiate a new `pixeldroid.json.Json` and call the `fromString()` or `fromObject()` method on it
0. retrieve values for key / item chains as desired
0. print to formatted JSON string with JsonPrinter

```ls
var jsonString:String = File.loadTextFile('assets/json.json');
var j:Json = Json.fromString(jsonString);
trace(j.keys['key_name'].items[2].value);
```

```ls
var jsonObject:Dictionary.<String, Object> = { "bool": true, "array": [1,23], "string": "one two three" };
var j:Json = Json.fromObject(jsonObject);
trace(JsonPrinter.print(j, JsonPrinterOptions.compact));
```

### JsonPrinter

This library includes a configurable JSON pretty-printer, with three pre-defined configurations for convenience:

#### Standard

As you would find from jsonlint:

```json
{
    "array": [
        1,
        23
    ],
    "bool": true,
    "string": "one two three"
}
```

#### Compact

A tighter formatting that retains readability:

```json
{
  "array": [ 1, 23 ],
  "bool": true,
  "string": "one two three"
}
```

#### Minified

No extra whitespace:

```json
{"array":[1,23],"bool":true,"string":"one two three"}
```

### JsonDemo

see an example of using Json here:

* [JsonDemo.build][JsonDemo.build]
* [JsonDemo.ls][JsonDemo.ls]

you can compile and run the demo from the command line:

    $ rake demo:gui

## working from source

> first install [loomtasks][loomtasks]

### compiling

    $ rake lib:install

this will build the Json library and install it in the currently configured sdk

### running tests

    $ rake test

this will build the Json library, install it in the currently configured sdk, build the test app, and run the test app.


## contributing

Pull requests are welcome!


[loomtasks]: https://github.com/pixeldroid/loomtasks "loomtasks"
[JsonDemo.build]: ./test/src/JsonDemo.build "build file for the demo"
[JsonDemo.ls]: ./test/src/JsonDemo.ls "source file for the demo"<commit_msg>update README for release<commit_after>json-ls
=======

JSON helpers for Loom

- `Json` - a utility to simplify json data access
- `JsonPrinter` - a pretty printer for json data


## installation

Download the library into its matching sdk folder:

    $ curl -L -o ~/.loom/sdks/sprint34/libs/Json.loomlib \
        https://github.com/pixeldroid/json-ls/releases/download/v0.0.2/Json-sprint34.loomlib

To uninstall, simply delete the file:

    $ rm ~/.loom/sdks/sprint34/libs/Json.loomlib


## usage

0. declare a reference to the Json loomlib in your `.build` file:
    *
    ```json
    "references": [
        "System",
        "Json"
    ],
    ```
0. import `pixeldroid.json.Json`
0. instantiate a new `pixeldroid.json.Json` and call the `fromString()` or `fromObject()` method on it
0. retrieve values for key / item chains as desired
0. print to formatted JSON string with JsonPrinter

```ls
var jsonString:String = File.loadTextFile('assets/json.json');
var j:Json = Json.fromString(jsonString);
trace(j.keys['key_name'].items[2].value);
```

```ls
var jsonObject:Dictionary.<String, Object> = { "bool": true, "array": [1,23], "string": "one two three" };
var j:Json = Json.fromObject(jsonObject);
trace(JsonPrinter.print(j, JsonPrinterOptions.compact));
```

### Json

Loom provides the [JSON][loom-json] class, which provides strongly typed access to values, requiring  separate accessors for every data type, and two families of these accessors for retrieving from Objects or Arrays. There are 18 basic accessors, and 2 methods for determining type.

The `Json` class in this library aims to simplify access to json data, using the `Json` class itself as the single container type, which exposes only 3 basic accessors, and 1 more for type retrieval:

- `keys` - a Dictionary of Json instances, indexed by Strings
- `items` - an Array of Json instances
- `value` - the actual data for the instance
- `type` - any basic System type, or Json
  * `Null`, `Boolean`, `Number`, `String`, `Vector`, `Dictionary`, `Json`

For comparison, the code snippets below present two ways to retrieve the second value of the nested array indexed by `r` in the following json data:

```json
{
   "key": [
      {"a":1.23, "b":45.67},
      {"x":8, "y":9},
      {"q":[1,2], "r":[3,4], "n":null}
   ],
}
```

> `json.json`

#### Using `system.JSON`

```ls
var jsonString:String = File.loadTextFile('assets/json.json');
var j:JSON = JSON.parse(jsonString);
trace(j.getArray('key').getArrayObject(2).getArray('r').getArrayNumber(1));
```

#### Using `pixeldroid.json.Json`


```ls
var jsonString:String = File.loadTextFile('assets/json.json');
var j:Json = Json.fromString(jsonString);
trace(j.keys['key'].items[2].keys['r'].items[1]);
```


### JsonPrinter

This library includes a configurable JSON pretty-printer, with three pre-defined configurations for convenience:

#### Standard

As you would find from jsonlint:

```json
{
    "array": [
        1,
        23
    ],
    "bool": true,
    "string": "one two three"
}
```

#### Compact

A tighter formatting that retains readability:

```json
{
  "array": [ 1, 23 ],
  "bool": true,
  "string": "one two three"
}
```

#### Minified

No extra whitespace:

```json
{"array":[1,23],"bool":true,"string":"one two three"}
```

### JsonDemo

see an example of using Json here:

* [JsonDemo.build][JsonDemo.build]
* [JsonDemo.ls][JsonDemo.ls]

you can compile and run the demo from the command line:

    $ rake demo:gui

## working from source

> first install [loomtasks][loomtasks]

### compiling

    $ rake lib:install

this will build the Json library and install it in the currently configured sdk

### running tests

    $ rake test

this will build the Json library, install it in the currently configured sdk, build the test app, and run the test app.


## contributing

Pull requests are welcome!


[loomtasks]: https://github.com/pixeldroid/loomtasks "loomtasks"
[loom-json]: http://docs.theengine.co/loom/1.1.4813/api/system/JSON.html "Loom JSON class"
[JsonDemo.build]: ./test/src/JsonDemo.build "build file for the demo"
[JsonDemo.ls]: ./test/src/JsonDemo.ls "source file for the demo"
{'fraction_non_alphanumeric': 0.1426628381441741, 'fraction_numerical': 0.012392322804896478, 'mean_word_length': 3.9058561897702, 'pattern_counts': {'":': 34, '<': 5, '<?xml version=': 0, '>': 8, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3447217', 'n_tokens_mistral': 2247, 'n_tokens_neox': 2112, 'n_words': 698}