{"id":13526173,"url":"https://github.com/bakpakin/binser","last_synced_at":"2025-08-28T23:48:21.647Z","repository":{"id":79569312,"uuid":"40440952","full_name":"bakpakin/binser","owner":"bakpakin","description":"Customizable Lua Serializer","archived":false,"fork":false,"pushed_at":"2023-03-02T17:41:15.000Z","size":76,"stargazers_count":214,"open_issues_count":3,"forks_count":26,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-08-20T02:47:45.356Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","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/bakpakin.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-08-09T15:29:47.000Z","updated_at":"2025-08-19T21:21:43.000Z","dependencies_parsed_at":"2023-05-02T04:23:29.083Z","dependency_job_id":null,"html_url":"https://github.com/bakpakin/binser","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/bakpakin/binser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bakpakin%2Fbinser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bakpakin%2Fbinser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bakpakin%2Fbinser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bakpakin%2Fbinser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bakpakin","download_url":"https://codeload.github.com/bakpakin/binser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bakpakin%2Fbinser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272582506,"owners_count":24959419,"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","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-08-01T06:01:26.092Z","updated_at":"2025-08-28T23:48:21.570Z","avatar_url":"https://github.com/bakpakin.png","language":"Lua","funding_links":[],"categories":["Lua","Serialization"],"sub_categories":[],"readme":"# binser - Customizable Lua Serializer\n\n[![Build Status](https://travis-ci.org/bakpakin/binser.svg?branch=master)](https://travis-ci.org/bakpakin/binser)\n\nThere already exists a number of serializers for Lua, each with their own uses,\nlimitations, and quirks. binser is yet another robust, pure Lua serializer that\nspecializes in serializing Lua data with lots of userdata and custom classes\nand types. binser is a binary serializer and does not serialize data into\nhuman readable representation or use the Lua parser to read expressions. This\nmakes it safe and moderately fast, especially on LuaJIT. binser also handles\ncycles, self-references, and metatables.\n\n## How to Use\n\n### Example\n```lua\nlocal binser = require \"binser\"\n\nlocal mydata = binser.serialize(45, {4, 8, 12, 16}, \"Hello, World!\")\n\nprint(binser.deserializeN(mydata, 3))\n-- 45\ttable: 0x7fa60054bdb0\tHello, World!\n```\n\n### Serializing and Deserializing\n```lua\nlocal str = binser.serialize(...)\n```\nSerialize (almost) any Lua data into a Lua string. Numbers, strings, tables,\nbooleans, and nil are all fully supported by default. Custom userdata and custom\ntypes, both identified by metatables, can also be supported by specifying a\ncustom serialization function. Unserializable data should throw an error. Aliased to `binser.s`.\n\n```lua\nlocal results, len = binser.deserialize(str[, index])\n```\nDeserialize any string previously serialized by binser. Can optionally start at \nan index in the string (to drop leading characters). Index is 1 by default. Unrecognized data should\nthrow an error. Results is a list of length len. Aliased to `binser.d`.\n\n```lua\nlocal ... = binser.deserializeN(str, n[, index])\n```\nDeserializes at most n values from str. The default value for n is one,\nso `binser.deserializeN(str)` will deserialize exactly one value from string, and\nignore the rest of the string. Can optionally start at a given index, which\nis 1 by default. Aliased to `binser.dn`.\n\n### Custom types\n```lua\nlocal metatable = binser.register(metatable, name, serialize, deserialize)\n```\nRegisters a custom type, identified by its metatable, to be serialized.\nRegistering types has two main purposes. First, it allows custom serialization\nand deserialization for userdata and tables that contain userdata, which can't\notherwise be serialized in a uniform way. Second, it allows efficient\nserialization of small tables with large metatables, as registered metatables\nare not serialized.\n\nThe `metatable` parameter is the metatable the identifies the type. The `name`\nparameter is the type name used in serialization. The only requirement for names\nis that they are unique. The `serialize` and `deserialize` parameters are\na pair of functions that construct and destruct and instance of the type.\n`serialize` can return any number of serializable Lua objects, and\n`deserialize` should accept the arguments returned by `serialize`.\n`serialize` and `deserialize` can also be specified in `metatable._serialize`\nand `metatable._deserialize` respectively.\n\nIf `serialize` and `deserialize` are omitted, then default table serializers are\nused, which work very well for most tables. If your type describes userdata,\nhowever, `serialize` and `deserialize` must be provided.\n\n```lua\nlocal class = binser.registerClass(class[, name])\n```\nRegisters a class as a custom type. binser currently supports 30log and\nmiddleclass. `name` is an optional parameter that defaults to `class.name`.\n\n```lua\nlocal metatable = binser.unregister(name)\n```\nUsers should seldom need this, but to explicitly unregister a type, call this.\n\n#### Templates\n\nIf binser's already compact serialization isn't enough, and you don't want to write\ncomplex and error prone custom serializers, binser has a functionality called templating.\nTemplates specify the layout of a custom type, so that table keys don't need to be serialized\nmany times. To specify a template, add the `_template` key to the metatable of your type.\n\nAn example:\n```lua\nlocal template = {\n\t\"name\", \"age\", \"salary\", \"email\",\n\tnested = {\"more\", \"nested\", \"keys\"}\n}\n\nlocal Employee_MT = {\n\tname = \"Employee\",\n}\n\nlocal joe = setmetatable({\n\tname = \"Joe\",\n\tage = 11,\n\tsalary = \"$1,000,000\",\n\temail = \"joe@example.com\",\n\tnested = {\n\t\tmore = \"blah\",\n\t\tnested = \"FUBAR\",\n\t\tkeys = \"lost\"\n\t}\n}, Employee_MT)\n\n-- Print length of serialized employee without templating\n-- 117\nbinser.registerClass(Employee_MT)\nprint(#binser.s(joe))\nbinser.unregister(Employee_MT)\n\n-- Print length of serialized employee with templating\n-- 72\nEmployee_MT._template = template\nbinser.registerClass(Employee_MT)\nprint(#binser.s(joe))\n```\n\nIn the above example, the resulting serialized value with templating is nearly half of the size of the default\ntable serialization.\n\n### Resources\n\nIf there are certain objects that don't need to be serialized at all, like\nimages, audio, or any system resource, binser can mark them as such to only\nserialize a reference to them. Resources must be registered in a similar way to\ncustom types and given a unique name.\n```lua\nlocal resource = binser.registerResource(resource, name)\n```\nRegisters a resource.\n\n```lua\nlocal resource = binser.unregisterResource(name)\n```\nResources can be unregistered in a similar manner as custom types.\n\n### File IO\nMostly for convenience, binser has functions for writing and reading to files.\nThese work through Lua's built in IO.\n\n```lua\nbinser.writeFile(filepath, ...)\n```\nSerializes Lua objects and writes them to a file. Overwrites the previous file.\n\n```lua\nbinser.appendFile(filepath, ...)\n```\nSame as writing to a file, but doesn't overwrite the old file.\n\n```lua\nlocal results, len = binser.readFile(filepath)\n```\nReads and deserializes a file.\n\nThe trio of file convenience function have shortened aliases as well.\n\n| Function          | Alias    |\n|-------------------|----------|\n|`binser.writeFile` |`binser.w`|\n|`binser.appendFile`|`binser.a`|\n|`binser.readFile`  |`binser.r`|\n\n## Why\nMost Lua serializers serialize into valid Lua code, which while very useful,\nmakes it impossible to do things like custom serialization and\ndeserialization. binser was originally written as a way to save game levels\nwith images and other native resources, but is extremely general.\n\n## LuaRocks\nbinser is available as a rock on [LuaRocks](https://luarocks.org/). Install via:\n```\nluarocks install binser\n```\n\n## Testing\nbinser uses [busted](http://olivinelabs.com/busted/) for testing. Install and\nrun `busted` from the command line to test.\n\n## Notes\n* Serialized strings can contain unprintable and null characters.\n* Serialized data can be appended to other serialized data. (Cool :))\n* The functions `binser.serialize`, `binser.deserialize`, and `binser.deserializeN` can be shortened to\n`binser.s`, `binser.d`, and `binser.dn` as handy shortcuts.\n\n## Bugs\nPull requests are welcome, please help me squash bugs!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbakpakin%2Fbinser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbakpakin%2Fbinser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbakpakin%2Fbinser/lists"}