Jolicitron
A library and CLI to quickly build parsers for Google Hash Code problem inputs.
How to use it
Jolicitron is mainly about assigning names to integers. Hash Code problem inputs look like this:
3 2 4
3
4 5
6 7
8 9
10 11
Using the problem statement, this can be made sense of, and it's useful to parse it into a data structure that has descriptive names. For example, say the problem is about drones carrying items, and we would like this as an output:
{
"nsteps": 3,
"nitems": 2,
"ndrones": 4,
"drones": [
{ "x": 4, "y": 5 },
{ "x": 6, "y": 7 },
{ "x": 8, "y": 9 }
],
"itemWeights": [10, 11]
}
Jolicitron can help us do that. But we need to work first. We need to describe how the output should look like and it which order its pieces appear in the input file. This is done using a what jolicitron calls a schema. It's a JSON value that's similar to a JSON Schema. Here's a schema that works for the above input:
{
"type": "object",
"properties": [
{
"name": "nsteps",
"value": {
"type": "number"
}
},
{
"name": "nitems",
"value": {
"type": "number"
}
},
{
"name": "ndrones",
"value": {
"type": "number"
}
},
{
"name": "drones",
"value": {
"type": "array",
"length": "ndrones",
"items": {
"type": "object",
"properties": [
{
"name": "x",
"value": {
"type": "number"
}
},
{
"name": "y",
"value": {
"type": "number"
}
}
]
}
}
},
{
"name": "items",
"value": {
"type": "array",
"length": "nitems",
"items": {
"type": "number"
}
}
}
]
}
This is a handful, but there's lots of shortcuts that can help write compact schemas. Keep on reading for more.
Once we have schema, we run the following command, given the schema has been
saved to schema.json
and the input to input.txt
:
npx jolicitron --schema=schema.json --input=input.txt --output=output.json
And that's it really!
Writing schemas
Schemas describe both how to read the values in the input file and how to arrange them into a JSON structure.
Basic schemas
Jolicitron reads the input file as a sequence of tokens. Tokens are groups of
characters that are neither spaces or newlines. Tokens can be parsed into two
types: number
or string
. A schema to parse a single token to a number is
{ "type": "number" }
or simply "number"
. Same with string
. Those basic
types can be aggregated into objects and arrays.
Object schemas
A schema describing an object has the following form:
{
"type": "object",
"properties": [
{ "name": "property1", "value": <schema for the property> },
...other properties
]
}
Notice that properties
is an array. That's important because this array
denotes the order in which the properties appear in the input file.
An object schema can be shortened to its property
array, so this schema:
[
{ "name": "property1", "value": <schema for the property> },
...other properties
]
...is equivalent to the previous one.
Properties can also be shortened in different ways.
A property of type number
can be shortened to its property name, so the schema
["property1"]
is the same as [{ "name": "property1", "value": "number" }]
.
Properties that are arrays of numbers can be shortened to ["propertyName", "arrayLength"]
. This is expanded to:
{
"name": "propertyName",
"value": {
"type": "array",
"length": "arrayLength",
"items": "number"
}
}
A third element can be added to the short array form to specify the item schema.
For example, ["propertyName", "arrayLength", "string"]
denotes a property that
is array of string. Note that the third element can be any schema, not just
simple types.
Array schemas
A schema describing an array has the following form:
{
"type": "array",
"length": <reference to a variable>,
"items": <schema for the items of the array>
}
length
must be the name of a property in the same object where the array is,
or a parent object. This property must be of type number, and the number
collected when reading the input file must denote the length of the array.
Example:
[
"arrayLength",
{
"name": "arrayProperty",
"value": {
"type": "array",
"length": "arrayLength",
...
}
}
]
When writing array schemas, the type
property may be omitted (length
is
enough to assume the schema is for an array). If items
is omitted, jolicitron
assumes an array of numbers.
Real-world examples
Check out the examples to understand how to use jolicitron on passed Hash Code problems.
Command-line interface
See npx jolicitron --help
.
Programmatic interface
import jolicitron from "jolicitron";
const schema = ["nitems", ["items", "nitems", ["weight"]]];
const input = "3 1 10 100";
const result = jolicitron(schema, input);
console.log(result);
// logs { nitems: 3, items: [{ weight: 1 }, { weight: 10 }, { weight: 100 }]}
Changelog
- 3.0.0
-
breaking refactor: basically a complete rewrite
- new API
- orders of magnitude faster
-
breaking refactor: basically a complete rewrite
- 2.1.0
- support for string tokens
-
⚠ if your program relies on the fact that string tokens raise errors, then this is actually a breaking change
-
- support for string tokens
- 2.0.1
- documentation fixes
- 2.0.0
- breaking refactor: made builder parameters positional (see #11)
- breaking refactor: module exports the build function directly (see #10)
-
breaking refactor:
save
andsave.usingName(name)
collapsed into a singlesave([name])
-
breaking refactor: replaced
n.usingName
withn
'slength
option
- 1.1.0
-
indices
option forn
-
- 1.0.2
- package.json/readme update
- example for https://tonicdev.com/npm/jolicitron
- 1.0.1
- package.json/readme update
- 1.0.0
- initial release