{"id":18988286,"url":"https://github.com/marhop/literate-binary","last_synced_at":"2025-04-19T23:54:58.014Z","repository":{"id":72731049,"uuid":"142486904","full_name":"marhop/literate-binary","owner":"marhop","description":"Integrate handcrafted binary and documentation","archived":false,"fork":false,"pushed_at":"2024-03-31T22:36:00.000Z","size":168,"stargazers_count":37,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-29T13:52:14.310Z","etag":null,"topics":["binary","hex","markdown"],"latest_commit_sha":null,"homepage":"","language":"Haskell","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/marhop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2018-07-26T19:47:18.000Z","updated_at":"2022-11-16T21:12:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"2e605b45-e636-4245-8141-60b91f20fa5b","html_url":"https://github.com/marhop/literate-binary","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marhop%2Fliterate-binary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marhop%2Fliterate-binary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marhop%2Fliterate-binary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marhop%2Fliterate-binary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marhop","download_url":"https://codeload.github.com/marhop/literate-binary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249255595,"owners_count":21238796,"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":["binary","hex","markdown"],"created_at":"2024-11-08T16:43:20.909Z","updated_at":"2025-04-19T23:54:57.997Z","avatar_url":"https://github.com/marhop.png","language":"Haskell","readme":"# literate-binary\n\nThere are times when a binary file has to be crafted *by hand*, be it for\ntesting purposes, for research, or just for some weird kind of fun. Usually, a\nhex editor is the tool of choice for straightforward binary editing. But what\nabout documentation? There is no way to enter inline comments or other\nexplanatory prose in a hex editor, leading to separation of hex code and\ndocumentation. (Or worse, to no documentation at all.)\n\nWouldn't it be great if there was a way to combine binary (expressed as hex\ncode) and textual content in the same file? If both a binary file and\naccompanying documentation in formats like HTML or PDF could be generated from\nthe same source file? There is!\n\nJust write a [Markdown] file [like this example][example]. Run it through your\nfavourite Markdown converter (mine is [Pandoc]) to create a pretty HTML or PDF\ndocument; run it through [`lb`][lb] to create a binary file from its hex\ncontent.\n\n                    pandoc -\u003e documentation.{html,pdf,docx,...}\n                  /\n    source.bmp.md\n                  \\\n                    lb     -\u003e binary.bmp\n\nObviously, this is inspired by [Donald Knuth's ideas on literate\nprogramming](https://en.wikipedia.org/wiki/Literate_programming); hence the\nname.\n\nThere are several example files in the [examples/](examples/) directory. I have\nalso written a [long blog post][blog] that explains how to build a TIFF file\nusing literate binary.\n\n# Syntax\n\nThe [`lb` (literate binary) tool][lb] produces a binary file from a [Markdown]\ninput file. The binary is made up by all [code blocks] in the input file tied\ntogether. All other content including inline code in backticks `` `like this` ``\nis ignored. The code blocks must contain nothing but hex strings, whitespace and\ncomments. The set of valid hex strings is defined as follows:\n\nEach sequence of hex characters (0-9, A-F, upper or lower case) with even length\nlike `00ff` is a valid hex string; each pair of characters in this sequence\ntranslates to one byte in the usual fashion. Given hex strings x and y and a\npositive integer n, the following macros are valid hex strings as well:\n\n  * A *repetition* of the form `(x){n}`. This translates to the byte sequence\n    corresponding to x, repeated n times. The integer n may be followed by a\n    multiplicative suffix `K` (factor 2¹⁰, KiB), `M` (factor 2²⁰, MiB), or `G`\n    (factor 2³⁰, GiB). Examples: `(00ff){3}` → `00ff00ff00ff`, `(00){2M}` → 2\n    MiB of NULL bytes\n  * An *alternative* of the form `(x|...|y)`. This translates to the byte\n    sequence corresponding to either x or ... or y, selected randomly. Example:\n    `(00|ff|3333)` → one of `00`, `ff` or `3333`\n  * A *range* of the form `(x-y)`. This translates to one random byte sequence\n    from the range defined by x and y. Example: `(0c-0f)` → one of `0c`, `0d`,\n    `0e` or `0f`\n  * The special range `.` (a single dot). This translates to one random byte, so\n    it is equivalent to the range `(00-ff)`.\n  * A *string* of the form `\"...\"` or `'...'` with arbitrary text content inside\n    the quotes. The quote sign itself may appear inside the string escaped by a\n    backslash like `\\\"`, a literal backslash has to be escaped by another\n    backslash like `\\\\`. This translates to the UTF-8 encoded byte sequence\n    corresponding to the quoted string content. (Note that ASCII is a subset of\n    UTF-8.) Example: `\"foo bar\"` → `666f6f20626172`\n\nWhen combining an alternative, a range or a string with a repetition, redundant\nparentheses are not required: `(x|y){n}` is equivalent to `((x|y)){n}`,\n`(x-y){n}` is equivalent to `((x-y)){n}`, `.{n}` is equivalent to `(.){n}`, and\n`\"foo\"{3}` is equivalent to `(\"foo\"){3}`.\n\nComments start with a `#` sign and end at the end of the line.\n\nIt is possible to exclude single code blocks from processing; [fenced code\nblocks] with the `.nobin` class are ignored by `lb`. This can be used to add\ncode other than binary, or to \"comment out\" a whole code block.\n\n# Usage\n\nGet a binary [here][releases] and put it in your PATH (and, if necessary, make\nit executable -- hint: `chmod u+x lb`). Then:\n\n    $ lb --help\n    $ lb source.bmp.md --output binary.bmp\n    $ echo '(00ff){42} 0a' | lb --plain\n\nNote that no Markdown is involved in the last command, just *plain* hex code.\nStrictly speaking, this defeats the purpose of literate binary, reducing `lb` to\na beefed-up reverse hex dump tool. Anyway, it's useful for quick tests, so never\nmind.\n\n# Contributing\n\nPull requests, particularly well-documented example files (minimal file format\nexamples, misuse of format specifications, ...) are greatly appreciated!\n\n# Building from source\n\nThis tool is written in Haskell, so you need GHC (compiler) and Cabal (build\ntool), best installed with [ghcup] if you use a Unix-like OS. Clone the Git\nrepository, change to its top level directory and run the following commands to\nbuild and optionally install the `lb` binary:\n\n    $ cabal build\n    $ cabal install\n\n[Markdown]: https://daringfireball.net/projects/markdown/basics\n[Pandoc]: https://pandoc.org\n[lb]: https://github.com/marhop/literate-binary\n[releases]: https://github.com/marhop/literate-binary/releases\n[example]: examples/bitmap/bitmap.md\n[blog]: https://martin.hoppenheit.info/blog/2022/writing-binary-by-hand/\n[code blocks]: https://pandoc.org/MANUAL.html#verbatim-code-blocks\n[fenced code blocks]: https://pandoc.org/MANUAL.html#fenced-code-blocks\n[ghcup]: https://www.haskell.org/ghcup/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarhop%2Fliterate-binary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarhop%2Fliterate-binary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarhop%2Fliterate-binary/lists"}