# binmark

> Markup language and tool for generating binary files

Latest version **1.0.0** (published 2023-01-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install binmark
pnpm add binmark
yarn add binmark
bun add binmark
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2023-01-12 |
| First published | 2023-01-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Nicholas Humfrey |
| Maintainers | njh |
| Keywords | hex, markup, binary |

## Links

- npm: https://www.npmjs.com/package/binmark
- Repository: https://github.com/njh/binmark-js
- Homepage: https://github.com/njh/binmark-js#readme
- Issues: https://github.com/njh/binmark-js/issues
- npm.io page: https://npm.io/package/binmark

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 1.0.0 (latest) — 2023-01-12

## README

binmark.js
==========

_binmark_ is a markup language and JavaScript library for describing binary files,
that is easier to read and write than a continuous stream of hexadecimal characters.


The following characters are supported:

| Character     | Description                                              |
|---------------|----------------------------------------------------------|
| 0-9 and a-f   | A byte as hexadecimal. Must be two characters long.      |
| Whitespace    | Ignored                                                  |
| Colon or Dash | Ignored - useful for improving readability               |
| .nnn          | A 8-bit decimal integer                                  |
| ""            | A string of ASCII characters                             |
| #             | The start of a comment - the rest of the line is ignored |
| \             | Escape sequences (\0 \a \b \f \n \r \t \v)               |


Example
-------

Given the following sample input file, which is reasonably easy read:

    30             # Packet Type 3: Publish
    .17            # Remaining length (17 bytes)
    0004           # Topic name length
    "test"         # Topic name
    "hello world"  # Payload


But why?
--------

I created _binmark_ after my test cases, when writing test cases for my Arduino IPv6 Library,
EtherSia, started resulting in long strings of hexadecimal characters in my code. I 
decided that these would be better in seperate external files and realised that I had the 
freedom to decide on the file format, to make them easier to read and write.

A long stream of hexadecimal is difficult to both read and write - particularly picking 
out the different fields and sections. By adding some whitespace, punctuation and 
comments, it is much easier.

Possible uses:

* Describing expected data for automated tests
* Creating new file formats before tools to generate them exist
* Documenting a data structure in a human readable way
* Alternative to a using a hex editor


Design Decisions
----------------

This was my thought process while designing _binmark_:

* Readable and concise to write for humans
* Simple for a machine to parse and convert
* Streamable - don't require input to be loaded into a buffer more parsing
* ASCII input - try and avoid potential weird character-set problems
* Not so complex that there wouldn't be other implementations in other languages

---
_Source: https://npm.io/package/binmark · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._