{"_id":"@5cover/mkast","name":"@5cover/mkast","dist-tags":{"latest":"2.0.1"},"versions":{"2.0.1":{"name":"@5cover/mkast","version":"2.0.1","description":"AST generator (Python)","homepage":"https://github.com/5cover/mkast#readme","bugs":{"url":"https://github.com/5cover/mkast/issues"},"repository":{"type":"git","url":"git+https://github.com/5cover/mkast.git"},"keywords":["ast","parser","generator"],"bin":{"mkast":"src/mkast/__main__.py","mkast-init":"pip install -r ./requirements.txt"},"license":"Unlicense","author":{"name":"5cover"},"scripts":{"test":"pytest"},"_id":"@5cover/mkast@2.0.1","gitHead":"9b4478dd02d225bb09be8102bbe6a15e41b5e9f5","_nodeVersion":"24.7.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-kezNRgPdGSflQNG4REcwag2EcfLFqYcI5mVflvpF/uGFEZyfmclVjWR1FW13IlS5GsNd+5ZZIWRWWOPn83R9ng==","shasum":"c46859e1fc9c10afef8ed09e79a87b2cba853304","tarball":"https://registry.npmjs.org/@5cover/mkast/-/mkast-2.0.1.tgz","fileCount":17,"unpackedSize":36824,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDCxTuAgiIari6Ti8DvDz7Xmtko51VQLSyoSHbSHkg1YAIgAdhXpJtUlEYY3uC3b9a35hvbTSRbNVj/2HNE3rS7aA0="}]},"_npmUser":{"name":"5cover","email":"thediscover22450@gmail.com"},"directories":{},"maintainers":[{"name":"5cover","email":"thediscover22450@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mkast_2.0.1_1757963943843_0.6499704187554838"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-15T19:19:03.787Z","2.0.1":"2025-09-15T19:19:04.094Z","modified":"2025-09-15T19:19:04.332Z"},"maintainers":[{"name":"5cover","email":"thediscover22450@gmail.com"}],"description":"AST generator (Python)","homepage":"https://github.com/5cover/mkast#readme","keywords":["ast","parser","generator"],"repository":{"type":"git","url":"git+https://github.com/5cover/mkast.git"},"author":{"name":"5cover"},"bugs":{"url":"https://github.com/5cover/mkast/issues"},"license":"Unlicense","readme":"# mkast\r\n\r\n> [WARNING]\r\n> If you're installing from NPM, you'll need to install dependencies manually with: `npx mkast-init`.\r\n\r\n[![PyPI version](https://badge.fury.io/py/mkast.svg)](https://badge.fury.io/py/mkast)\r\n![PyPI - Downloads](https://img.shields.io/pypi/dm/mkast)\r\n[![License: Unlicense](https://img.shields.io/badge/License-Unlicense-yellow.svg)](https://opensource.org/license/Unlicense)\r\n![Tests](/mkast/actions/workflows/tests.yml/badge.svg)\r\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)\r\n[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)\r\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\r\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)\r\n\r\n## What is it?\r\n\r\n**mkast** is a CLI tool that generates an AST data structure from a language-agnostic description expressed in YAML.\r\n\r\n## Usage\r\n\r\nLatest schema URLs:\r\n\r\n[Input schema](https://raw.githubusercontent.com/5cover/mkast/refs/heads/main/src/mkast/schemas/nodes.json)\r\n\r\n[Config schema](https://raw.githubusercontent.com/5cover/mkast/refs/heads/main/src/mkast/schemas/config.json)\r\n\r\nThe schemas are also shipped in the package and can be imported from there\r\n\r\n### Installing\r\n\r\nThe easiest way is to install **mkast** is from PyPI using pip:\r\n\r\n```sh\r\npip install mkast\r\n```\r\n\r\n### Running\r\n\r\n`./ast.py < input.yml`\r\n\r\nFirst, import the library.\r\n\r\n```python\r\nimport mkast\r\n```\r\n\r\n#### Input\r\n\r\nThe input is a YAML file containing one or two documents.\r\n\r\nIf the input contains two documents, the first document is considered configuration; the second document is considered as the actual input.\r\n\r\nAn AST is expressed as a tree of nodes. There are two kinds of nodes: **product** nodes, having **properties**, are product types, while **union** nodes represent the sum type of other nodes.\r\n\r\n## Configuration\r\n\r\nConfiguration can be specified at four levels.\r\n\r\n1. Individual options\r\n2. First document of a bi-document input\r\n3. `-c` option\r\n4. Defaults\r\n\r\nEach level takes precedence over the ones below.\r\n\r\nConfiguration options:\r\n\r\nname|type|default value|description\r\n-|-|-|-\r\nknown_types|array of identifier|[]|Types to always consider defined\r\nroot|identifier||If defined, adds an outer union node wrapping everything\r\ncommon_props|map of identifier &rarr; identifier|{}|Common properties present in every product node\r\ntarget|\"csharp\" or \"agnostic\"|(value is required)|Output languages.\r\nnamespace|identifier||Namespace or package name\r\nassert|code snippet||Expands to an assertion statement. $1 is replaced by the boolean expression to assert\r\nimports|array of identifier|[]|Importations to add to the top of the file\r\nunion|snippet|depends on target language|Expands to the declaration of an union node. $1 is replaced by the name of the node.\r\nproduct|snippet|depends on the target language|Expands to the declaration of an product node. $1 is replaced by the name of the node.\r\nmodifiers|map of modifier char &rarr; modifier (see dedicated section)|{}|Modifiers are used to hook into the type names and expressions emitted.\r\n\r\nModifiers:\r\n\r\nname|char|description\r\n-|-|-\r\none|(empty)|Implicit. Used to wrap every type or apply an invariant everywhere.\r\noptional|?|Optional element\r\none or more|+|Non-empty list of elements\r\nzero or more|*|List of elements\r\n\r\nModifier code snippets (all optional):\r\n\r\nname|expands to|arguments\r\n-|-|-\r\ntype|The type name|$1 is replaced by the payload type.\r\nmust|A boolean expression that validates the value. Used in combination with assertions.|$1 is replaced by the name of the variable to check.\r\nnone_when|A boolean expression that indicates when it is invalid to unwrap the value.|$1 is replaced by name of the variable to check.\r\nunwrap|An expression that yields the payload value. Or, if there are multiple payload values (such as for lists), a boolean expression that is true when all the values satisfy $2.| $1 is replaced by the name of the variable to unwrap. $2, if present, is replaced by the payload validation boolean expression (based on $1).\r\n\r\n## Features\r\n\r\n### Properties\r\n\r\nProperties have a type which is checked to exist.\r\n\r\nTypes marked as *Do Not Touch* (by prefixing them with an equal sign `=`) are not checked and their casing is not altered.\r\n\r\nMultiple `?`, `+`, and `*` suffixes can be appended for optionals, non-empty lists and lists respectively.\r\n\r\n### Casing\r\n\r\nThe casing of identifiers is altered to match the conventions of the target language.\r\n\r\nIn the agnostic language, snake_case is used and expected as input.\r\n\r\n## TODO\r\n\r\n- [x] merge complex configs values from different sources\r\n  - [x] imports\r\n  - [x] modifiers\r\n\r\n- [ ] instead of visiting on the fly, build a data structure and revisit. this means we'll be able to query the properties and subnodes of a node when generating it, which will allow for:\r\n  - [ ] smarter code generation (semi-colon body)\r\n  - [ ] mermaid class diagram target\r\n  - [ ] csharp: only strictly necessary interfaces in base type list (currently all parents are added)\r\n\r\n- [ ] union node properties: currently, we decide to make a product node if it contains properties (which is why we need root in config to wrap everything in an interface). this means we cannot have interfaces with properties. solution: use '*' for products and '+' for sum types\r\n- [ ] account for the empty modifier in csharp.py (currently it seems to be ignored)\r\n\r\n- [ ] Modifier stack-ability (C# nullable reference types cannot be stacked)\r\n\r\n- [x] Multi-document input support\r\n- [x] Optional root\r\n\r\n- [x] Customize target (current config attr is not read)\r\n- [ ] Target-specific options\r\n- [x] Configure modifiers (config is read (untested), but not used)\r\n\r\n- [x] read from config file so options can be persisted on a per-project basis\r\n- [x] C# target:\r\n  - [x] Custom namespace\r\n  - [x] Custom common properties\r\n  - [x] Custom root type\r\n- [x] Known type option\r\n- [x] Use argparse\r\n","readmeFilename":"README.md","_rev":"1-5aa837a6dfa4788fb62c4a6191608cf3"}