README.md.rx

# josn
{{ npm.link("josn-cli") }} is a command-line `JSON` viewer, written in `JavaScript` and `TypeScript`.

I felt the need for a JSON browser when I was working on {{ gh.link("iaseth/top-100-yc-companies") }}.
I primarily use it to verify the JSON data collected in my web scraping projects.
I have created a similar tool ({{ gh.link("iaseth/jsonplus", "jsonplus") }}) in `C++`,
which is a lot more limited in functionality.

Four of my other projects, {{ gh.link("iaseth/josnlib", "josnlib") }}, {{ gh.link("iaseth/whichtype", "whichtype") }},
{{ gh.link("iaseth/jslice", "jslice") }} and {{ gh.link("iaseth/jtransform", "jtransform") }},
actually started out as modules within `josn`,
but were later made separate packages to allow for easier testing and code reuse.

I am using {{ gh.link("iaseth/readmix", "readmix") }} for generating this README.
You can view the source file [here](https://github.com/iaseth/josn/blob/master/README.md.rx).


## Table of contents
{{ tableOfContents(doc) }}


## Installation
You can install {{ "josn-cli" | NpmLink }} with the following command:
=> npm i -g josn-cli
Now you should be able to run the `josn` command in your terminal.


## Updating JOSN
You can update `josn` with the following command:
=> npm i -g josn-cli@latest


## Usage
* **Printing whole files**

	Provide the `filepath` as the first argument.
	* This will print the whole file as indented JSON:
		=> josn filename.json
	* When you supply a `path` that is a directory, `josn` will automatically select the `package.json` inside that directory:
		=> josn reactapp
		This is equivalent to writing:
		=> josn reactapp/package.json
	* When you supply a `path` that is a directory but it does not contain a `package.json`, `josn` will try to find a `json` file in that directory:
		=> josn mydata/
		If the directory contains a single `JSON` file, then `josn` will select it.
		Otherwise, it will list all the `JSON` files in that directory.

* **Printing an object**

	You can use the `keyName` to traverse inside an object.
	* This will print the `dependencies` object inside `package.json`:
		=> josn package.json dependencies
	* `josn` is case insensitive, so you might as well write this:
		=> josn package.json Dependencies
	* Or even this:
		=> josn package.json DEPENDENCIES
	* And you can skip parts of the key name if it is unique enough:
		=> josn package.json dep
		This will print the first `key` that starts with the prefix `dep`.
	* You can use a `colonArg` for selecting just the `keys` or `values` in an object:
		=> josn package.json dependencies :keys
		=> josn package.json dependencies :values
		Both, `:keys` and `:values` have a shorthand syntax:
		=> josn package.json dependencies :k
		=> josn package.json dependencies :v

* **Printing an array element**

	You can use numbers to select array elements.
	* This will print the first element of the data array:
		=> josn data.json data 0
	* You can also use negative indexes to select an element from the end:
		=> josn data.json data -1
		This will print last element of `data` array.
	* You can use a `colonArg` for selecting just the `even` or `odd` elements in an Array:
		=> josn data.json data :even
		=> josn data.json data :odd
		Keep in mind that array indexes start at 0, so `:even` will select elements at `0, 2, 4, etc` and vice-versa.
	* You can use a `colonArg` for slicing an Array:
		=> josn data.json data :10         // select first 10 elements
		=> josn data.json data -10:        // select last 10 elements
		=> josn data.json data 2:5         // select elements from 2 to 4
		The slice syntax is heavily inspired by its counterpart in `Python`.


## Demos
`JOSN` comes with a bunch of demo JSON files to get you started.
| Title | Name | Source | Description |
| ----- | ---- | ------ | ----------- |{% for demo in parse("src/demos.json").demos %}
| {{ demo.title }} | [`{{ demo.filename }}`](https://github.com/iaseth/josn/tree/master/demojsons/{{ demo.filename }}) | {{ gh.link(demo.repo) }} | {{ demo.description }} |{% endfor %}

Use the following command to view the list of available demo JSON files in your `josn` installation:
=> josn --print-demos
You can open a demo file with the `@demoname` syntax:
=> josn @colors.json colors :10 --table
You can omit the extension `.json` for demos:
=> josn @colors colors :10 --table


## List of flags
| Short | Long | Description | Status |
| ----- | ---- | ----------- | ------ |{% for flag in parse("node_modules/josnlib/dist/flags.json").flags %}
| {{ flag.singleFlag }} | {{ flag.doubleFlag }} | {{ flag.description }} | {{ "✓" if flag.isDone else "✗" }} |{% endfor %}


## Package details
{{ npm.packageDetails() }}


## Dependencies
{{ npm.dependencyTable() }}


## Dev dependencies
{{ npm.devDependencyTable() }}


## License
{{ "LICENSE.md" | File }}


{{ giveCredit() }}