npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

bytefield-svg

v1.8.0

Published

Generate byte field diagrams in SVG format from a Clojure/EDN DSL

Downloads

705

Readme

bytefield-svg

A Node module for generating byte field diagrams like this one. Inspired by the LaTeX bytefield package. Powered by a Clojure-based domain specific language (now built on top of SCI, the Small Clojure Interpreter).

License

Usage

This is published to npm, so you can install it for use in a Javascript project by running:

npm install bytefield-svg

Or you can install it globally for use anywhere by running:

npm install -g bytefield-svg

The language you use to create diagrams has its own documentation site.

Invoking from Javascript

Once installed, you can generate diagrams in your code like this:

const generate = require('bytefield-svg');

const source = `
;; Put your diagram DSL here, or read it from a file, or build it...
`;
const diagram = generate(source);
process.stdout.write(diagram);

By default, a full SVG file is generated, complete with XML version and namespaces. If you want to generate a simple <svg> tag which is suitable for embedding inside an HTML document, you can request that by calling generate like this:

// setup code omitted...
const diagram = generate(source, { "embedded": true });

Of course, you can do other things than writing the diagram to standard out. For a few more examples of usage, you can see the cli.js source in this project which implements the command-line interface, our next topic:

Invoking from the Command Line

This package also installs a command-line tool. If you have installed it globally, you can simply invoke it as bytefield-svg. If you have installed it locally, you can invoke it using npx bytefield-svg within your project.

With no arguments, the tool will read the diagram source from standard in, and write it to standard out. So you can generate the example diagram from this Read Me, as long as you have the test.edn file, by running:

bytefield-svg <test.edn >test.svg

You can also use the -s or --source command-line argument to specify that the tool should read from a named file rather than standard in, and -o or --output to write to a named file rather than standard out, which might be helpful in a scripting pipeline:

bytefield-svg --source test.edn --output test.svg

If you supply just a filename with no command-line flag, it is assumed to be the diagram source file.

Normally the output is a full SVG file, complete with XML version information and namespaces. If instead you want to generate a simple SVG tag which is suitable for embedding inside an HTML document, you can supply the -e or --embedded flag.

Invoking it with -h or --help displays this usage information.

-h, --help            Display this usage guide.
-s, --source string   File from which to read the diagram source, defaults to
                      standard in.
-o, --output string   File to which to write the SVG diagram, defaults to
                      standard out.
-e, --embedded        Emit a simple <svg> tag suitable for embedding in an
                      HTML document. (The default is to emit a full SVG file
                      with XML version and namespaces.)

Background

The DSL has been nicely validated by porting all of the LaTeX documents I needed it for to an Antora documentation site.

As that site suggests, this package's main purpose is to act as an Asciidoctor extension, and in fact asciidoctor-bytefield has now been published to enable that.

Building

To build a development build of bytefield-svg from source, clone the repository and make sure you have Node.js and the Clojure CLI tools installed, then from the top-level directory of your cloned repo run:

npm install
npm run build

This will create the file lib.js. At that point, you can generate the sample diagram by running:

node cli.js test.edn >test.svg

(The test.edn file is present in this project. It renders a diagram from the above-linked documentation site. With some well-designed helper functions in site's own include file, the source for an even more attractive version of the diagram shrinks to this).

The DSL documentation is hosted on netlify, and built out of the doc folder, which includes build instructions. (They are slightly more complex than if you were using asciidoctor-bytefield, because they want ot build against the latest version of bytefield-svg in case they are demonstrating unreleased features that haven't yet made it to the that extension.)

To check for outdated dependencies, you can run:

clojure -M:outdated

Releasing

To cut a release, check for outdated dependencies as above, update the version in package.json, tag and push to GitHub, then run:

npm install
npm run release
npm publish

License

Copyright © 2020–2023 Deep Symmetry, LLC

Distributed under the Eclipse Public License 2.0. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software.