{"id":22423323,"url":"https://github.com/prantlf/oscript-parser","last_synced_at":"2025-08-01T07:32:12.274Z","repository":{"id":57316451,"uuid":"324857487","full_name":"prantlf/oscript-parser","owner":"prantlf","description":"A parser for the OScript language written in JavaScript. With an AST walker, a syntax checker (lint) and a code-executing interpreter.","archived":false,"fork":false,"pushed_at":"2022-04-24T16:53:19.000Z","size":615,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-16T10:36:38.572Z","etag":null,"topics":["ast","ast-walker","interpreter","lexer","lint","oscript","parser","parsing","syntax-checker","tokenizer","walker"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-12-27T22:07:15.000Z","updated_at":"2024-01-14T00:01:58.000Z","dependencies_parsed_at":"2022-08-25T20:40:31.134Z","dependency_job_id":null,"html_url":"https://github.com/prantlf/oscript-parser","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Foscript-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Foscript-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Foscript-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Foscript-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/oscript-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228348371,"owners_count":17905899,"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":["ast","ast-walker","interpreter","lexer","lint","oscript","parser","parsing","syntax-checker","tokenizer","walker"],"created_at":"2024-12-05T18:09:59.731Z","updated_at":"2024-12-05T18:10:00.414Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OScript Parser\n\n[![NPM version](https://badge.fury.io/js/oscript-parser.png)](http://badge.fury.io/js/oscript-parser)\n[![Build Status](https://github.com/prantlf/oscript-parser/workflows/Test/badge.svg)](https://github.com/prantlf/oscript-parser/actions)\n[![codecov](https://codecov.io/gh/prantlf/oscript-parser/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/oscript-parser)\n[![Dependency Status](https://david-dm.org/prantlf/oscript-parser.svg)](https://david-dm.org/prantlf/oscript-parser)\n[![devDependency Status](https://david-dm.org/prantlf/oscript-parser/dev-status.svg)](https://david-dm.org/prantlf/oscript-parser#info=devDependencies)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nA parser for the [OScript language] written in JavaScript. Returns an [abstract syntax tree] (AST). See also [oscript-ast-walker] for traversing the AST and [oscript-interpreter] for its execution.\n\n## Synopsis\n\n```js\nimport { parseText } from 'oscript-parser'\nconst program = parseText('i = 0', { sourceType: 'script' })\nconsole.log(JSON.stringify(program))\n```\n\n## Installation\n\nUse your favourite package manager to install this package locally in your Node.js project:\n\n```\nnpm i oscript-parser\npnpm i oscript-parser\nyarn add  oscript-parser\n```\n\nIf you want to use the executables `osparse` or `oslint` from `PATH`, install this package globally instead.\n\n## API\n\nThe OScript AST resembles the [AST for JavaScript], but it includes nodes specific to the OScript syntax. See the [language grammar] and the [AST node declarations].\n\nThe OScript language is case-insensitive. Values of keywords and identifiers in tokens and AST nodes (`value` property) are converted lower-case to make comparisons and look-ups more convenient. If you need the original letter-case, enable the raw AST node content (`raw` property) by the `rawIdentifiers` parser option.\n\n### Parser\n\nThe output of the parser is an Abstract Syntax Tree (AST) formatted in JSON. The parser functionality is exposed by `parseText()` and `parseTokens()`. The `parseText()` expects an input text. The `startTokenization()` expects an input text with tokens already produced by `tokenize()`.\n\nThe available options are:\n\n- `defines: {}` Preprocessor named values. For evaluating preprocessor directives.\n- `tokens: false` Include lexer tokens in the output object. Useful for code formatting or partial analysis in case of errors.\n- `preprocessor: false` Include tokens of preprocessor directives and the content skipped by the preprocessor. Useful for code formatting.\n- `comments: false` Include comment tokens in the output of parsing\n  or lexing. Useful for code formatting.\n- `whitespace: false` Include whitespace tokens in the output of parsing\n  or lexing. Useful for code formatting.\n- `locations: false` Store location information on each parsed node.\n- `ranges: false` Store the start and end character locations on each parsed node.\n- `raw: false` Store the raw original of identifiers and literals.\n- `rawIdentifiers: false` Store the raw original of identifiers only.\n- `rawLiterals: false` Store the raw original of literals only.\n- `sourceType: 'script'` Set the source type to `object`, `script` or `dump`\n  (the old object format).\n- `oldVersion: undefined` Expect the old version of the OScript language.\n- `sourceFile: 'snippet'` File name to refer in source locations to.\n\nThe default options are also exposed through `defaultOptions` where\nthey can be overridden globally.\n\n```js\nimport { parseText } from 'oscript-parser'\nconst program = parseText('foo = \"bar\"', { sourceType: 'script' })\n// { type: \"Program\",\n//   body:\n//     [{ type: \"AssignmentStatement\",\n//        variables: [{ type: \"Identifier\", value: \"foo\" }],\n//        init: [{ type: \"StringLiteral\", value: \"bar\" }]\n//     }]\n// }\n```\n\n### Lexer\n\nThe lexer can be used independently of the parser. The lexer functionality is exposed by `tokenize()` and `startTokenization()`. The `tokenize()` will return an array of tokens. The `startTokenization()` will return a generator advancing to the next token up until `EOF` is reached. The `EOF` itself will not be returned as a token. The options are the same as for the method `parse()`, except for `tokens`, which will be ignored.\n\nEach token consists of:\n\n- `type` expressed as an enum flag which can be matched with `tokenTypes`.\n- `value`\n- `line`, `lineStart`\n- `range` can be used to slice out the raw token content. For example, `foo = \"bar\"` will return a `StringLiteral` token with the value `bar`. Slicing out the range on the other\nhand will return `\"bar\"`.\n\n```js\nimport { tokenize } from 'oscript-parser'\nconst tokens = tokenize('foo = \"bar\"', { sourceType: 'script' })\n// [{ type: 8, value: \"foo\", line: 1, lineStart: 0, range: [0, 3] }\n//  { type: 32, value: \"=\", line: 1, lineStart: 0, range: [4, 5]}\n//  { type: 2, value: \"bar\", line: 1, lineStart: 0, range: [6, 11] }]\n```\n\nTokens can be consumed incrementally by an iterator:\n\n```js\nimport { startTokenization } from 'oscript-parser'\nconst iterator = startTokenization('foo = \"bar\"', { sourceType: 'script' })\niterator.next() // { value: { type: 8, value: \"foo\", line: 1, range: [0, 3] } }\niterator.next() // { value: { type: 32, value: \"=\", line: 1, range: [4, 5]} }\niterator.next() // { value: { type: 2, value: \"bar\", line: 1, range: [6, 11] } }\niterator.next() // { done: true }\n```\n\n## Tools\n\n### osparse(1)\n\nThe `osparse` executable can be used from the shell by installing `oscript-parser` globally using `npm`:\n\n```\n$ npm i -g oscript-parser\n$ osparse -h\n\nUsage: osparse [option...] [file]\n\nOptions:\n  --[no]-tokens           include lexer tokens. defaults to false\n  --[no]-preprocessor     include preprocessor directives. defaults to false\n  --[no]-comments         include comments. defaults to false\n  --[no]-whitespace       include whitespace. defaults to false\n  --[no]-locations        store location of parsed nodes. defaults to false\n  --[no]-ranges           store start and end token ranges. defaults to false\n  --[no]-raw              store raw identifiers \u0026 literals. defaults to false\n  --[no]-raw-identifiers  store raw identifiers \u0026 literals. defaults to false\n  --[no]-raw-literals     store raw identifiers \u0026 literals. defaults to false\n  --[no]-context          show near source as error context. defaults to true\n  --[no]-colors           enable colors in the terminal. default is auto\n  -D|--define \u003cname\u003e      define a named value for preprocessor\n  -S|--source \u003ctype\u003e      source type is object, script (default) or dump\n  -O|--old-version        expect an old version of OScript. defaults to false\n  -t|--tokenize           print tokens instead of AST\n  -c|--compact            print without indenting and whitespace\n  -w|--warnings           consider warnings as failures too\n  -s|--silent             suppress output\n  -v|--verbose            print error stacktrace\n  -p|--performance        print parsing timing\n  -V|--version            print version number\n  -h|--help               print usage instructions\n\nIf no file name is provided, standard input will be read. If no source type\nis provided, it will be inferred from the file extension: \".os\" -\u003e object,\n\".e|lxe\" -\u003e script, \".osx\" -\u003e dump. The source type object will enable the\nnew OScript language and source type dump the old one by default.\n\nExamples:\n  echo 'foo = \"bar\"' | osparse --no-comments -S script\n  osparse -t foo.os\n```\n\nExample usage:\n\n```\n$ echo \"i = 0\" | osparse -c -S script\n\n{\"type\":\"Program\",\"body\":[{\"type\":\"AssignmentStatement\",\n \"variables\":[{\"type\":\"Identifier\",\"value\":\"i\"}],\n \"init\":[{\"type\":\"NumericLiteral\",\"value\":0}]}]}\n```\n\n### oslint(1)\n\nThe `oslint` executable can be used in the shell by installing `oscript-parser` globally using `npm`:\n\n```\n$ npm i -g oscript-parser\n$ oslint -h\n\nUsage: oslint [option...] [pattern ...]\n\nOptions:\n  --[no]-context      show near source as error context. defaults to true\n  --[no]-colors       enable colors in the terminal. default is auto\n  -D|--define \u003cname\u003e  define a named value for preprocessor\n  -S|--source \u003ctype\u003e  source type is object, script (default) or dump\n  -O|--old-version    expect an old version of OScript. defaults to false\n  -e|--errors-only    print only files that failed the check\n  -w|--warnings       consider warnings as failures too\n  -s|--silent         suppress output\n  -v|--verbose        print error stacktrace\n  -p|--performance    print parsing timing\n  -V|--version        print version number\n  -h|--help           print usage instructions\n\nIf no file name is provided, standard input will be read. If no source type\nis provided, it will be inferred from the file extension: \".os\" -\u003e object,\n\".e|lxe\" -\u003e script, \".osx\" -\u003e dump. The source type object will enable the\nnew OScript language and source type dump the old one by default.\n\nExamples:\n  echo 'foo = \"bar\"' | oslint -S script\n  oslint -t foo.os\n```\n\nExample usage:\n\n```\n$ echo \"i = 0\" | oslint\nsnippet succeeded\n```\n\n### Error Handling\n\nIf tokenizing or parsing fails, a non-zero exit code will be returned by either of `osparse` and `oslint` and the error with an extra context will be printed on the console. For example, after deleting an equal sign (`=`) from [example.os]:\n\n\u003c!--\n$ oslint example.os\n\nexample.os failed with 1 error and 0 warnings\nexample.os:7:28: error: modifier, type, function, script or end expected near 'public'\n 5｜\n 6｜ public object Document inherits CORE::Node\n 7｜  override Boolean fEnabled TRUE\n  ｜                            ~~~~\n 8｜\n 9｜  // Gets a livelink document\n```\n--\u003e\n\u003cpre\u003e\n\u003cspan style=\"font-weight:bold;color:gray;\"\u003e$ oslint example.os\u003c/span\u003e\n\nexample.os \u003cspan style=\"font-weight:bold;color:red;\"\u003efailed\u003c/span\u003e with 1 error and 0 warnings\n\u003cspan style=\"font-weight:bold;color:gray;\"\u003eexample.os:7:28: \u003c/span\u003e\u003cspan style=\"font-weight:bold;color:red;\"\u003eerror: \u003c/span\u003e\u003cspan style=\"font-weight:bold;color:gray;\"\u003e\u0026lt;modifier\u0026gt;, \u0026lt;type\u0026gt;, function, script or end expected near 'public'\u003c/span\u003e\n 5｜\n 6｜ public object Document inherits CORE::Node\n \u003cspan style=\"font-weight:bold;color:teal;\"\u003e7\u003c/span\u003e｜  override Boolean fEnabled \u003cspan style=\"font-weight:bold;color:teal;\"\u003eTRUE\u003c/span\u003e\n  ｜                            \u003cspan style=\"font-weight:bold;color:teal;\"\u003e~~~~\u003c/span\u003e\n 8｜\n 9｜  // Gets a livelink document\n\u003c/pre\u003e\n\nAll output of `oslint` goes to standard output. For `osparse`, the result AST goes to standard output and error and timing information to standard error.\n\n## License\n\nCopyright (c) 2020-2022 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[AST for JavaScript]: https://github.com/estree/estree#readme\n[OScript language]: ./doc/grammar.md#oscript-language-grammar\n[language grammar]: ./doc/grammar.md#oscript-language-grammar\n[AST node declarations]: ./dist/index.d.ts#L115\n[abstract syntax tree]: ./dist/index.d.ts#L115\n[AST]: ./dist/index.d.ts#L115\n[example.os]: https://github.com/prantlf/vscode-oscript/blob/master/pkg/examples/example.os\n[oscript-ast-walker]: https://github.com/prantlf/oscript-parser/tree/master/pkg/walker#readme\n[oscript-interpreter]: https://github.com/prantlf/oscript-parser/tree/master/pkg/interpreter#readme\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Foscript-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Foscript-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Foscript-parser/lists"}