{"id":16017314,"url":"https://github.com/njh/binmark","last_synced_at":"2025-03-18T03:30:58.758Z","repository":{"id":65245064,"uuid":"73325957","full_name":"njh/binmark","owner":"njh","description":"Markup language and tool for generating binary files","archived":false,"fork":false,"pushed_at":"2023-03-22T16:14:35.000Z","size":33,"stargazers_count":21,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-15T16:19:53.063Z","etag":null,"topics":["binary","binmark","hex","markup-language","test"],"latest_commit_sha":null,"homepage":"https://www.aelius.com/njh/binmark/","language":"C","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/njh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-09T22:21:17.000Z","updated_at":"2023-11-07T12:43:47.000Z","dependencies_parsed_at":"2023-02-12T06:01:29.392Z","dependency_job_id":null,"html_url":"https://github.com/njh/binmark","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fbinmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fbinmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fbinmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fbinmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njh","download_url":"https://codeload.github.com/njh/binmark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221705359,"owners_count":16866949,"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","binmark","hex","markup-language","test"],"created_at":"2024-10-08T16:05:00.343Z","updated_at":"2024-10-27T16:37:42.278Z","avatar_url":"https://github.com/njh.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"binmark\n=======\n\n[![Build Status](https://travis-ci.com/njh/binmark.svg?branch=master)](https://travis-ci.com/njh/binmark)\n\n_binmark_ is a markup language and tool for describing binary files, that is easier to\nread and write than a continuous stream of hexadecimal characters.\n\nThis implementation is a C/C++ library and command line tool.\n\n\nThe following characters are supported:\n\n| Character     | Description                                              |\n|---------------|----------------------------------------------------------|\n| 0-9 and a-f   | A byte as hexadecimal. Must be two characters long.      |\n| Whitespace    | Ignored                                                  |\n| Colon or Dash | Ignored - useful for improving readability               |\n| .nnn          | A 8-bit decimal integer                                  |\n| \"\"            | A string of ASCII characters                             |\n| #             | The start of a comment - the rest of the line is ignored |\n| \\             | Escape sequences (\\0 \\a \\b \\f \\n \\r \\t \\v)               |\n\n\nExample\n-------\n\nGiven the following sample input file, which is reasonably easy read:\n\n    30             # Packet Type 3: Publish\n    .17            # Remaining length (17 bytes)\n    0004           # Topic name length\n    \"test\"         # Topic name\n    \"hello world\"  # Payload\n\nThe default is to output as a binary stream - visualised here using the hexdump command:\n\n    ./binmark -b tests/mqtt_publish.bm | hexdump -C\n    00000000  30 11 00 04 74 65 73 74  68 65 6c 6c 6f 20 77 6f  |0...testhello wo|\n    00000010  72 6c 64                                          |rld|\n    00000013\n\nIt is also possible to output as C data structure:\n\n    ./binmark -c tests/mqtt_publish.bm\n    uint8_t buffer[] = {\n        0x30, 0x11, 0x00, 0x04, 0x74, 0x65, 0x73, 0x74, \n        0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, \n        0x72, 0x6c, 0x64\n    };\n\nOr as a stream of hexadecimal text:\n\n    ./binmark -x tests/mqtt_publish.bm\n    301100047465737468656c6c6f20776f726c64\n\n\nBut why?\n--------\n\nI created _binmark_ after my test cases, when writing test cases for my Arduino IPv6 Library,\nEtherSia, started resulting in long strings of hexadecimal characters in my code. I \ndecided that these would be better in seperate external files and realised that I had the \nfreedom to decide on the file format, to make them easier to read and write.\n\nA long stream of hexadecimal is difficult to both read and write - particularly picking \nout the different fields and sections. By adding some whitespace, punctuation and \ncomments, it is much easier.\n\nPossible uses:\n\n* Describing expected data for automated tests\n* Creating new file formats before tools to generate them exist\n* Documenting a data structure in a human readable way\n* Alternative to a using a hex editor\n\n\nDesign Decisions\n----------------\n\nThis was my thought process while designing _binmark_:\n\n* Readable and concise to write for humans\n* Simple for a machine to parse and convert\n* Streamable - don't require input to be loaded into a buffer more parsing\n* ASCII input - try and avoid potential weird character-set problems\n* Not so complex that there wouldn't be other implementations in other languages\n\n\nOther Languages\n---------------\n\n* JavaScript: https://github.com/njh/binmark-js\n\n\nLicense\n-------\n\n`binmark` is licensed under the terms of the MIT license.\nSee the file [LICENSE](/LICENSE.md) for details.\n\n\nNaming\n------\n\n_binmark_ was originally written in 2016 with the name _hext_.\nIt was renamed in 2023 to have a more unique name that wasn't being used by other projects.\n\n\nContact\n-------\n\n* Author:    Nicholas J Humfrey\n* Twitter:   [@njh](http://twitter.com/njh)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjh%2Fbinmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjh%2Fbinmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjh%2Fbinmark/lists"}