{"id":23222828,"url":"https://github.com/pmunch/binaryparse","last_synced_at":"2025-08-16T13:54:00.683Z","repository":{"id":55600722,"uuid":"113347009","full_name":"PMunch/binaryparse","owner":"PMunch","description":"Binary parser for Nim","archived":false,"fork":false,"pushed_at":"2021-03-24T21:36:15.000Z","size":51,"stargazers_count":71,"open_issues_count":3,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-11T13:25:59.004Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Nim","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/PMunch.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-06T17:29:00.000Z","updated_at":"2024-08-18T06:29:13.000Z","dependencies_parsed_at":"2022-08-15T04:10:10.241Z","dependency_job_id":null,"html_url":"https://github.com/PMunch/binaryparse","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/PMunch%2Fbinaryparse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PMunch%2Fbinaryparse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PMunch%2Fbinaryparse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PMunch%2Fbinaryparse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PMunch","download_url":"https://codeload.github.com/PMunch/binaryparse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247364931,"owners_count":20927226,"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":[],"created_at":"2024-12-18T23:14:25.051Z","updated_at":"2025-04-05T16:29:18.451Z","avatar_url":"https://github.com/PMunch.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"binaryparse\n===========\nThis module implements a macro to create binary parsers. The parsers\ngenerated reads from a Stream and returns a tuple with each named field.\nThe general format the macro takes is:\n\n``[type]\u003csize\u003e: \u003cname\u003e[options]``\n\nWhere optional fields are in [] brackets and required fields are in \u003c\u003e\nbrackets. Each field has separate meanings, as described in the table below:\n\n========== ==================================================================\nName       Description\n---------- ------------------------------------------------------------------\ntype       This is the type of value found in this field, if no type is\n           specified then it will be parsed as an integer. Supported types\n           are ``u`` to get unsigned integers, ``f`` for floating point,\n           ``s`` for strings, and ``*`` for custom parser.\nsize       The size, in *bits*, of the field to read. For uint and int values\n           from 1 to 64 inclusive are supported. For floats only 32 and 64\n           are supported. Strings use this field to specify the amount of\n           characters to read into the string. If they don't specify a size\n           they will be read to the first NULL byte (this only applies to\n           strings). When the custom parser type is specified the size field\n           is used to name the custom parser procedure.\nname       The name of the value, this will be used as the name in the\n           resulting tuple. If the value doesn't need to be stored one can\n           use ``_`` as the name and it will not get a field in the result.\noptions    These will change the regular behaviour of reading into a field.\n           Since they are so different in what they do they are described\n           below instead of in this table.\n========== ==================================================================\n\nMany binary formats include special \"magic\" sequences to identify the file\nor regions within it. The option ``= \u003cvalue\u003e`` can be used to check if a\nfield has a certain value. If the value doesn't match a MagicError is\nraised. Value must match the value of the field it checks. When the field is\na string type the exact length of the magic string is read, to include a\nterminating NULL byte use ``\\0`` in the string literal.\n\nTo read more fields of a certain kind into a sequence you can use the option\n``[[count]]`` (that is square brackets with an optional count inside). If no\ncount is specified and the brackets left empty it must be the last field or\nthe next field needs to be a magic number and will be used to terminate the\nsequence. If it is the last field it will read until the end of the stream.\nAs count you can use the name of any previous field, literals, previously\ndefined variables, or a combination. Note that all sequences are assumed to\nterminate on a byte border, even if given a statically evaluatable size.\n\nAnother thing commonly found in binary formats are repeating blocks or\nformats within the format. These can be read by using a custom parser.\nCustom parsers technically supports any procedure that takes a Stream as the\nfirst argument, however care must be taken to leave the Stream in the correct\nposition. You can also define the inner format with a parser from this module\nand then pass that parser to the outer parser. This means that you can easily\nnest parsers. If you need values from the outer parser you can add parameters\nto the inner parser by giving it colon expressions before the body (e.g the\ncall ``createParser(list, size: uint16)`` would create a parser\n``proc (stream: Stream, size: uint16): \u003creturn type\u003e``). To call a parser\nuse the ``*`` type as described above and give it the name of the parser and\nany optional arguments. The stream object will get added automatically as the\nfirst parameter.\n\nWhen creating a parser you get a tuple with two members, ``get`` and ``put``\nwhich is stored by a let as the identifier given when calling createParser.\nThese are both procedures, the first only takes a stream (and any optional\narguments as described above) and returns a tuple containing all the fields.\nThe second takes a stream and a tuple containing all the fields, this is the\nsame tuple returned by the ``get`` procedure and writes the format to the\nstream.\n\nExample:\nIn lieu of proper examples the binaryparse.nim file contains a ``when\nisMainModule()`` block showcasing how it can be used. The table below\ndescribes that block in a bit more detail:\n\n======================= =====================================================\nFormat                  Description\n----------------------- -----------------------------------------------------\n``u8: _ = 128``         Reads an unsigned 8-bit integer and checks if it\n                        equals 128 without storing the value as a field in\n                        returned tuple\n``u16: size``           Reads an unsigned 16-bit integer and names it\n                        ``size`` in the returned tuple\n``4: data[size*2]``     Reads a sequence of 4-bit integers into a ``data``\n                        field in the returned tuple. Size is the value read\n                        above, and denotes the count of integers to read.\n``s: str[]``            Reads null terminated strings into a ``str`` field in\n                        the returned tuple. Since it's given empty brackets\n                        the next field needs to be a magic field and the\n                        sequence will be read until the magic is found.\n``s: _ = \"9xC\\0\"``      Reads a non-null terminated string and checks if it\n                        equals the magic sequence.\n``*list(size): inner``  Uses a pre-defined procedure ``list`` which is called\n                        with the current Stream and the ``size`` read\n                        earlier. Stores the return value in a field ``inner``\n                        in the returned tuple.\n``u8: _ = 67``          Reads an unsigned 8-bit integer and checks if it\n                        equals 67 without storing the value.\n======================= =====================================================\n\nThis file is automatically generated from the documentation found in\nbinaryparse.nim. Use ``nim doc2 binaryparse.nim`` to get the full documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmunch%2Fbinaryparse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmunch%2Fbinaryparse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmunch%2Fbinaryparse/lists"}