{"id":13831808,"url":"https://github.com/Deep-Symmetry/bytefield-svg","last_synced_at":"2025-07-09T15:33:27.116Z","repository":{"id":39759386,"uuid":"244111840","full_name":"Deep-Symmetry/bytefield-svg","owner":"Deep-Symmetry","description":"Node module that generates byte field diagrams in SVG format","archived":false,"fork":false,"pushed_at":"2024-10-25T02:08:59.000Z","size":1171,"stargazers_count":128,"open_issues_count":0,"forks_count":20,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-09T09:46:20.153Z","etag":null,"topics":["byte","clojure","diagram-generator","nodejs","svg"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Deep-Symmetry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"Deep-Symmetry","liberapay":"deep-symmetry","custom":"https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=LG5NLFL5T372W\u0026source=url"}},"created_at":"2020-03-01T08:17:13.000Z","updated_at":"2024-11-06T21:11:28.000Z","dependencies_parsed_at":"2023-11-21T18:30:00.580Z","dependency_job_id":"54e67940-8ea7-4093-af1d-fa5b9320e9a1","html_url":"https://github.com/Deep-Symmetry/bytefield-svg","commit_stats":{"total_commits":200,"total_committers":10,"mean_commits":20.0,"dds":0.275,"last_synced_commit":"d7bd7311e734a22fc1ad0e12420f49b0cf538941"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":"Deep-Symmetry/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deep-Symmetry%2Fbytefield-svg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deep-Symmetry%2Fbytefield-svg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deep-Symmetry%2Fbytefield-svg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deep-Symmetry%2Fbytefield-svg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Deep-Symmetry","download_url":"https://codeload.github.com/Deep-Symmetry/bytefield-svg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225565928,"owners_count":17489288,"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":["byte","clojure","diagram-generator","nodejs","svg"],"created_at":"2024-08-04T10:01:40.713Z","updated_at":"2025-07-09T15:33:27.077Z","avatar_url":"https://github.com/Deep-Symmetry.png","language":"Clojure","funding_links":["https://github.com/sponsors/Deep-Symmetry","https://liberapay.com/deep-symmetry","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=LG5NLFL5T372W\u0026source=url"],"categories":["Clojure"],"sub_categories":[],"readme":"# bytefield-svg\n\nA Node module for generating byte field diagrams like\n[this one](https://deepsymmetry.org/images/test.svg).\nInspired by the LaTeX [`bytefield`](https://ctan.org/pkg/bytefield?lang=en)\npackage. Powered by a [Clojure](https://clojure.org)-based\n[domain specific language](https://bytefield-svg.deepsymmetry.org/)\n(now built on top of [SCI](https://github.com/borkdude/sci), the\nSmall Clojure Interpreter).\n\n[![License](https://img.shields.io/badge/License-Eclipse%20Public%20License%202.0-blue.svg)](#license)\n\n\u003ca href=\"https://deepsymmetry.org/images/test.svg\"\u003e\u003cimg alt=\"Sample byte field diagram\"\n     src=\"doc/assets/sample-byte-field.png\" width=\"698\" height=\"375\"\u003e\u003c/a\u003e\n\n## Usage\n\nThis is published to npm, so you can install it for use in a Javascript\nproject by running:\n\n    npm install bytefield-svg\n\nOr you can install it globally for use anywhere by running:\n\n    npm install -g bytefield-svg\n\nThe language you use to create diagrams has its own\n[documentation site](https://bytefield-svg.deepsymmetry.org/).\n\n### Invoking from Javascript\n\nOnce installed, you can generate diagrams in your code like this:\n\n```javascript\nconst generate = require('bytefield-svg');\n\nconst source = `\n;; Put your diagram DSL here, or read it from a file, or build it...\n`;\nconst diagram = generate(source);\nprocess.stdout.write(diagram);\n```\n\nBy default, a full SVG file is generated, complete with XML version\nand namespaces. If you want to generate a simple `\u003csvg\u003e` tag which is\nsuitable for embedding inside an HTML document, you can request that\nby calling `generate` like this:\n\n```javascript\n// setup code omitted...\nconst diagram = generate(source, { \"embedded\": true });\n```\n\nOf course, you can do other things than writing the diagram to standard out.\nFor a few more examples of usage, you can see the\n[cli.js](https://github.com/Deep-Symmetry/bytefield-svg/blob/master/cli.js)\nsource in this project which implements the command-line interface, our next\ntopic:\n\n### Invoking from the Command Line\n\nThis package also installs a command-line tool. If you have installed it\nglobally, you can simply invoke it as `bytefield-svg`. If you have installed\nit locally, you can invoke it using `npx bytefield-svg` within your project.\n\nWith no arguments, the tool will read the diagram source from standard in, and\nwrite it to standard out. So you can generate the example diagram from this\nRead Me, as long as you have the [`test.edn`\nfile](https://github.com/Deep-Symmetry/bytefield-svg/blob/master/test.edn),\nby running:\n\n    bytefield-svg \u003ctest.edn \u003etest.svg\n\nYou can also use the `-s` or `--source` command-line argument to specify\nthat the tool should read from a named file rather than standard in, and\n`-o` or `--output` to write to a named file rather than standard out, which\nmight be helpful in a scripting pipeline:\n\n    bytefield-svg --source test.edn --output test.svg\n\nIf you supply just a filename with no command-line flag, it is assumed\nto be the diagram source file.\n\nNormally the output is a full SVG file, complete with XML version\ninformation and namespaces. If instead you want to generate a simple\nSVG tag which is suitable for embedding inside an HTML document, you\ncan supply the `-e` or `--embedded` flag.\n\nInvoking it with `-h` or `--help` displays this usage information.\n\n    -h, --help            Display this usage guide.\n    -s, --source string   File from which to read the diagram source, defaults to\n                          standard in.\n    -o, --output string   File to which to write the SVG diagram, defaults to\n                          standard out.\n    -e, --embedded        Emit a simple \u003csvg\u003e tag suitable for embedding in an\n                          HTML document. (The default is to emit a full SVG file\n                          with XML version and namespaces.)\n\n## Getting Help\n\n\u003ca href=\"https://zulip.com\"\u003e\u003cimg align=\"right\" alt=\"Zulip logo\"\n src=\"doc/assets/zulip-icon-circle.svg\" width=\"128\" height=\"128\"\u003e\u003c/a\u003e\n\nDeep Symmetry\u0026rsquo;s projects are generously sponsored with hosting\nby \u003ca href=\"https://zulip.com\"\u003eZulip\u003c/a\u003e, an open-source modern team\nchat app designed to keep both live and asynchronous conversations\norganized. Thanks to them, you can \u003ca\nhref=\"https://deep-symmetry.zulipchat.com/#narrow/stream/354684-other-projects\"\u003echat\nwith our community\u003c/a\u003e, ask questions, get inspiration, and share your\nown ideas.\n\n## Background\n\nThe DSL has been nicely validated by porting all of the LaTeX\ndocuments I needed it for to an [Antora documentation\nsite](https://djl-analysis.deepsymmetry.org/djl-analysis/track_metadata.html).\n\nAs that site suggests, this package\u0026rsquo;s main purpose is to act as\nan [Asciidoctor](https://asciidoctor.org) extension, and in fact\n[asciidoctor-bytefield](https://github.com/Deep-Symmetry/asciidoctor-bytefield)\nhas now been published to enable that.\n\n## Building\n\nTo build a development build of `bytefield-svg` from source, clone the\nrepository and make sure you have [Node.js](https://nodejs.org/en/)\nand the [Clojure CLI\ntools](https://clojure.org/guides/getting_started) installed, then\nfrom the top-level directory of your cloned repo run:\n\n    npm install\n    npm run build\n\nThis will create the file `lib.js`. At that point, you can generate\n[the sample diagram](https://deepsymmetry.org/images/test.svg) by running:\n\n    node cli.js test.edn \u003etest.svg\n\n(The [`test.edn`\nfile](https://github.com/Deep-Symmetry/bytefield-svg/blob/master/test.edn)\nis present in this project. It renders a diagram from the above-linked\ndocumentation site. With some well-designed helper functions in\nsite\u0026rsquo;s own include file, the source for an even more attractive\nversion of the diagram shrinks to\n[this](https://github.com/Deep-Symmetry/dysentery/blob/379555f21244354c4dc0c9711c8cb3a3552bc64b/doc/modules/ROOT/examples/dbserver_shared.edn)).\n\nThe [DSL documentation](https://bytefield-svg.deepsymmetry.org/) is\nhosted on deepsymmetry.org, and built out of the [doc](doc) folder,\nwhich includes build instructions. (They are slightly more complex\nthan if you were using `asciidoctor-bytefield`, because they want to\nbuild against the latest version of `bytefield-svg` in case they are\ndemonstrating unreleased features that haven\u0026rsquo;t yet made it to\nthe that extension.)\n\nTo check for outdated dependencies, you can run:\n\n    clojure -M:outdated\n\n## Releasing\n\nTo cut a release, check for outdated dependencies as above, update the\nversion in `package.json`, tag and push to GitHub, then run:\n\n    npm install\n    npm run release\n    npm publish\n\n## License\n\n\u003ca href=\"https://deepsymmetry.org\"\u003e\u003cimg align=\"right\" alt=\"Deep Symmetry\"\n src=\"doc/assets/DS-logo-github.png\" width=\"250\" height=\"150\"\u003e\u003c/a\u003e\n\nCopyright © 2020–2025 [Deep Symmetry, LLC](https://deepsymmetry.org)\n\nDistributed under the [Eclipse Public License\n2.0](https://opensource.org/licenses/EPL-2.0). By using this software\nin any fashion, you are agreeing to be bound by the terms of this\nlicense. You must not remove this notice, or any other, from this\nsoftware.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeep-Symmetry%2Fbytefield-svg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDeep-Symmetry%2Fbytefield-svg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeep-Symmetry%2Fbytefield-svg/lists"}