{"id":16774020,"url":"https://github.com/hgwood/jolicitron","last_synced_at":"2025-07-11T19:35:14.295Z","repository":{"id":47513367,"uuid":"52224830","full_name":"hgwood/jolicitron","owner":"hgwood","description":"A parser builder for Google Hash Code problem inputs","archived":false,"fork":false,"pushed_at":"2024-06-16T18:41:43.000Z","size":815,"stargazers_count":6,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-21T09:16:42.596Z","etag":null,"topics":["google-hash-code","parse"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hgwood.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-21T19:54:33.000Z","updated_at":"2022-02-21T21:40:08.000Z","dependencies_parsed_at":"2022-09-04T18:22:25.087Z","dependency_job_id":null,"html_url":"https://github.com/hgwood/jolicitron","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hgwood/jolicitron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgwood%2Fjolicitron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgwood%2Fjolicitron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgwood%2Fjolicitron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgwood%2Fjolicitron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hgwood","download_url":"https://codeload.github.com/hgwood/jolicitron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgwood%2Fjolicitron/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264887343,"owners_count":23678667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-hash-code","parse"],"created_at":"2024-10-13T06:47:47.975Z","updated_at":"2025-07-11T19:35:14.269Z","avatar_url":"https://github.com/hgwood.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jolicitron\n\nA library and CLI to quickly build parsers for Google Hash Code problem inputs.\n\n## How to use it\n\nJolicitron is mainly about assigning names to integers. Hash Code problem inputs\nlook like this:\n\n```\n3 2 4\n3\n4 5\n6 7\n8 9\n10 11\n```\n\nUsing the problem statement, this can be made sense of, and it's useful to parse\nit into a data structure that has descriptive names. For example, say the\nproblem is about drones carrying items, and we would like this as an output:\n\n```json\n{\n  \"nsteps\": 3,\n  \"nitems\": 2,\n  \"ndrones\": 4,\n  \"drones\": [\n    { \"x\": 4, \"y\": 5 },\n    { \"x\": 6, \"y\": 7 },\n    { \"x\": 8, \"y\": 9 }\n  ],\n  \"itemWeights\": [10, 11]\n}\n```\n\nJolicitron can help us do that. But we need to work first. We need to describe\nhow the output should look like and it which order its pieces appear in the\ninput file. This is done using a what jolicitron calls a schema. It's a JSON\nvalue that's similar to a JSON Schema. Here's a schema that works for the above\ninput:\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": [\n    {\n      \"name\": \"nsteps\",\n      \"value\": {\n        \"type\": \"number\"\n      }\n    },\n    {\n      \"name\": \"nitems\",\n      \"value\": {\n        \"type\": \"number\"\n      }\n    },\n    {\n      \"name\": \"ndrones\",\n      \"value\": {\n        \"type\": \"number\"\n      }\n    },\n    {\n      \"name\": \"drones\",\n      \"value\": {\n        \"type\": \"array\",\n        \"length\": \"ndrones\",\n        \"items\": {\n          \"type\": \"object\",\n          \"properties\": [\n            {\n              \"name\": \"x\",\n              \"value\": {\n                \"type\": \"number\"\n              }\n            },\n            {\n              \"name\": \"y\",\n              \"value\": {\n                \"type\": \"number\"\n              }\n            }\n          ]\n        }\n      }\n    },\n    {\n      \"name\": \"items\",\n      \"value\": {\n        \"type\": \"array\",\n        \"length\": \"nitems\",\n        \"items\": {\n          \"type\": \"number\"\n        }\n      }\n    }\n  ]\n}\n```\n\nThis is a handful, but there's lots of shortcuts that can help write compact\nschemas. Keep on reading for more.\n\nOnce we have schema, we run the following command, given the schema has been\nsaved to `schema.json` and the input to `input.txt`:\n\n```sh\nnpx jolicitron --schema=schema.json --input=input.txt --output=output.json\n```\n\nAnd that's it really!\n\n## Writing schemas\n\nSchemas describe both how to read the values in the input file and how to\narrange them into a JSON structure.\n\n### Basic schemas\n\nJolicitron reads the input file as a sequence of tokens. Tokens are groups of\ncharacters that are neither spaces or newlines. Tokens can be parsed into two\ntypes: `number` or `string`. A schema to parse a single token to a number is\n`{ \"type\": \"number\" }` or simply `\"number\"`. Same with `string`. Those basic\ntypes can be aggregated into objects and arrays.\n\n### Object schemas\n\nA schema describing an object has the following form:\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": [\n    { \"name\": \"property1\", \"value\": \u003cschema for the property\u003e },\n    ...other properties\n  ]\n}\n```\n\nNotice that `properties` is an array. That's important because this array\ndenotes the order in which the properties appear in the input file.\n\nAn object schema can be shortened to its `property` array, so this schema:\n\n```json\n[\n  { \"name\": \"property1\", \"value\": \u003cschema for the property\u003e },\n  ...other properties\n]\n```\n\n...is equivalent to the previous one.\n\nProperties can also be shortened in different ways.\n\nA property of type `number` can be shortened to its property name, so the schema\n`[\"property1\"]` is the same as `[{ \"name\": \"property1\", \"value\": \"number\" }]`.\n\nProperties that are arrays of numbers can be shortened to `[\"propertyName\", \"arrayLength\"]`. This is expanded to:\n\n```json\n{\n  \"name\": \"propertyName\",\n  \"value\": {\n    \"type\": \"array\",\n    \"length\": \"arrayLength\",\n    \"items\": \"number\"\n  }\n}\n```\n\nA third element can be added to the short array form to specify the item schema.\nFor example, `[\"propertyName\", \"arrayLength\", \"string\"]` denotes a property that\nis array of string. Note that the third element can be any schema, not just\nsimple types.\n\n### Array schemas\n\nA schema describing an array has the following form:\n\n```json\n{\n  \"type\": \"array\",\n  \"length\": \u003creference to a variable\u003e,\n  \"items\": \u003cschema for the items of the array\u003e\n}\n```\n\n`length` must be the name of a property in the same object where the array is,\nor a parent object. This property must be of type number, and the number\ncollected when reading the input file must denote the length of the array.\n\nExample:\n\n```json\n[\n  \"arrayLength\",\n  {\n    \"name\": \"arrayProperty\",\n    \"value\": {\n      \"type\": \"array\",\n      \"length\": \"arrayLength\",\n      ...\n    }\n  }\n]\n```\n\nWhen writing array schemas, the `type` property may be omitted (`length` is\nenough to assume the schema is for an array). If `items` is omitted, jolicitron\nassumes an array of numbers.\n\n## Real-world examples\n\nCheck out the\n[examples](https://github.com/hgwood/jolicitron/tree/master/examples) to\nunderstand how to use jolicitron on passed Hash Code problems.\n\n## Command-line interface\n\nSee `npx jolicitron --help`.\n\n## Programmatic interface\n\n```js\nimport jolicitron from \"jolicitron\";\n\nconst schema = [\"nitems\", [\"items\", \"nitems\", [\"weight\"]]];\nconst input = \"3 1 10 100\";\nconst result = jolicitron(schema, input);\nconsole.log(result);\n// logs { nitems: 3, items: [{ weight: 1 }, { weight: 10 }, { weight: 100 }]}\n```\n\n## Changelog\n\n- 3.0.0\n  - _breaking_ refactor: basically a complete rewrite\n    - new API\n    - orders of magnitude faster\n- 2.1.0\n  - support for string tokens\n    - ⚠ if your program relies on the fact that string tokens raise errors, then\n      this is actually a breaking change\n- 2.0.1\n  - documentation fixes\n- 2.0.0\n  - _breaking_ refactor: made builder parameters positional (see #11)\n  - _breaking_ refactor: module exports the build function directly (see #10)\n  - _breaking_ refactor: `save` and `save.usingName(name)` collapsed into a\n    single `save([name])`\n  - _breaking_ refactor: replaced `n.usingName` with `n`'s `length` option\n- 1.1.0\n  - `indices` option for `n`\n- 1.0.2\n  - package.json/readme update\n  - example for https://tonicdev.com/npm/jolicitron\n- 1.0.1\n  - package.json/readme update\n- 1.0.0\n  - initial release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhgwood%2Fjolicitron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhgwood%2Fjolicitron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhgwood%2Fjolicitron/lists"}