{"id":13747394,"url":"https://github.com/msgpack/msgpack-ruby","last_synced_at":"2025-05-12T15:14:44.710Z","repository":{"id":423196,"uuid":"2479813","full_name":"msgpack/msgpack-ruby","owner":"msgpack","description":"MessagePack implementation for Ruby / msgpack.org[Ruby]","archived":false,"fork":false,"pushed_at":"2025-03-18T11:08:13.000Z","size":6461,"stargazers_count":770,"open_issues_count":2,"forks_count":120,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-08T11:44:52.312Z","etag":null,"topics":["msgpack"],"latest_commit_sha":null,"homepage":"http://msgpack.org/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msgpack.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","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":"2011-09-29T04:10:15.000Z","updated_at":"2025-05-06T02:54:00.000Z","dependencies_parsed_at":"2024-06-18T11:08:20.210Z","dependency_job_id":"ca273719-86d5-4b40-aea3-9aed329c40f7","html_url":"https://github.com/msgpack/msgpack-ruby","commit_stats":{"total_commits":1865,"total_committers":103,"mean_commits":"18.106796116504853","dds":0.7050938337801609,"last_synced_commit":"94835a778e5349458afacdf95a2775e38b77d301"},"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgpack%2Fmsgpack-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgpack%2Fmsgpack-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgpack%2Fmsgpack-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msgpack%2Fmsgpack-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msgpack","download_url":"https://codeload.github.com/msgpack/msgpack-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253247686,"owners_count":21877904,"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":["msgpack"],"created_at":"2024-08-03T06:01:27.479Z","updated_at":"2025-05-12T15:14:44.656Z","avatar_url":"https://github.com/msgpack.png","language":"Ruby","readme":"# MessagePack\n\n[MessagePack](http://msgpack.org) is an efficient binary serialization format.\nIt lets you exchange data among multiple languages like JSON but it's faster and smaller.\nFor example, small integers (like flags or error code) are encoded into a single byte,\nand typical short strings only require an extra byte in addition to the strings themselves.\n\nIf you ever wished to use JSON for convenience (storing an image with metadata) but could\nnot for technical reasons (binary data, size, speed...), MessagePack is a perfect replacement.\n\n```ruby\nrequire 'msgpack'\nmsg = [1,2,3].to_msgpack  #=\u003e \"\\x93\\x01\\x02\\x03\"\nMessagePack.unpack(msg)   #=\u003e [1,2,3]\n```\n\nAdd msgpack to your Gemfile to install with Bundler:\n\n```ruby\n# Gemfile\ngem 'msgpack'\n```\n\nOr, use RubyGems to install:\n\n    gem install msgpack\n\nOr, build msgpack-ruby and install from a checked-out msgpack-ruby repository:\n\n    bundle\n    rake\n    gem install --local pkg/msgpack\n\n\n## Use cases\n\n* Create REST API returing MessagePack using Rails + [RABL](https://github.com/nesquena/rabl)\n* Store objects efficiently serialized by msgpack on memcached or Redis\n  * In fact Redis supports msgpack in [EVAL-scripts](https://redis.io/docs/latest/commands/eval/)\n* Upload data in efficient format from mobile devices such as smartphones\n  * MessagePack works on iPhone/iPad and Android. See also [Objective-C](https://github.com/msgpack/msgpack-objectivec) and [Java](https://github.com/msgpack/msgpack-java) implementations\n* Design a portable protocol to communicate with embedded devices\n  * Check also [Fluentd](https://www.fluentd.org) which is a log collector which uses msgpack for the log format (they say it uses JSON but actually it's msgpack, which is compatible with JSON)\n* Exchange objects between software components written in different languages\n  * You'll need a flexible but efficient format so that components exchange objects while keeping compatibility\n\n## Portability\n\nMessagePack for Ruby should run on x86, ARM, PowerPC, SPARC and other CPU architectures.\n\nAnd it works with MRI (CRuby) and Rubinius.\nPatches to improve portability are highly welcomed.\n\n\n## Serializing objects\n\nUse `MessagePack.pack` or `to_msgpack`:\n\n```ruby\nrequire 'msgpack'\nmsg = MessagePack.pack(obj)  # or\nmsg = obj.to_msgpack\nFile.binwrite('mydata.msgpack', msg)\n```\n\n### Streaming serialization\n\nPacker provides advanced API to serialize objects in streaming style:\n\n```ruby\n# serialize a 2-element array [e1, e2]\npk = MessagePack::Packer.new(io)\npk.write_array_header(2).write(e1).write(e2).flush\n```\n\nSee [API reference](http://ruby.msgpack.org/MessagePack/Packer.html) for details.\n\n## Deserializing objects\n\nUse `MessagePack.unpack`:\n\n```ruby\nrequire 'msgpack'\nmsg = File.binread('mydata.msgpack')\nobj = MessagePack.unpack(msg)\n```\n\n### Streaming deserialization\n\nUnpacker provides advanced API to deserialize objects in streaming style:\n\n```ruby\n# deserialize objects from an IO\nu = MessagePack::Unpacker.new(io)\nu.each do |obj|\n  # ...\nend\n```\n\nor event-driven style which works well with EventMachine:\n\n```ruby\n# event-driven deserialization\ndef on_read(data)\n  @u ||= MessagePack::Unpacker.new\n  @u.feed_each(data) {|obj|\n     # ...\n  }\nend\n```\n\nSee [API reference](http://ruby.msgpack.org/MessagePack/Unpacker.html) for details.\n\n## Serializing and deserializing symbols\n\nBy default, symbols are serialized as strings:\n\n```ruby\npacked = :symbol.to_msgpack     # =\u003e \"\\xA6symbol\"\nMessagePack.unpack(packed)      # =\u003e \"symbol\"\n```\n\nThis can be customized by registering an extension type for them:\n\n```ruby\nMessagePack::DefaultFactory.register_type(0x00, Symbol)\n\n# symbols now survive round trips\npacked = :symbol.to_msgpack     # =\u003e \"\\xc7\\x06\\x00symbol\"\nMessagePack.unpack(packed)      # =\u003e :symbol\n```\n\nThe extension type for symbols is configurable like any other extension type.\nFor example, to customize how symbols are packed you can just redefine\nSymbol#to_msgpack_ext. Doing this gives you an option to prevent symbols from\nbeing serialized altogether by throwing an exception:\n\n```ruby\nclass Symbol\n  def to_msgpack_ext\n    raise \"Serialization of symbols prohibited\"\n  end\nend\n\nMessagePack::DefaultFactory.register_type(0x00, Symbol)\n\n[1, :symbol, 'string'].to_msgpack  # =\u003e RuntimeError: Serialization of symbols prohibited\n```\n\n## Serializing and deserializing Time instances\n\nThere are the timestamp extension type in MessagePack,\nbut it is not registered by default.\n\nTo map Ruby's Time to MessagePack's timestamp for the default factory:\n\n```ruby\nMessagePack::DefaultFactory.register_type(\n  MessagePack::Timestamp::TYPE, # or just -1\n  Time,\n  packer: MessagePack::Time::Packer,\n  unpacker: MessagePack::Time::Unpacker\n)\n```\n\nSee [API reference](http://ruby.msgpack.org/) for details.\n\n## Extension Types\n\nPacker and Unpacker support [Extension types of MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md#types-extension-type).\n\n```ruby\n# register how to serialize custom class at first\npk = MessagePack::Packer.new(io)\npk.register_type(0x01, MyClass1, :to_msgpack_ext) # equal to pk.register_type(0x01, MyClass)\npk.register_type(0x02, MyClass2){|obj| obj.how_to_serialize() } # blocks also available\n\n# almost same API for unpacker\nuk = MessagePack::Unpacker.new()\nuk.register_type(0x01, MyClass1, :from_msgpack_ext)\nuk.register_type(0x02){|data| MyClass2.create_from_serialized_data(data) }\n```\n\n`MessagePack::Factory` is to create packer and unpacker which have same extension types.\n\n```ruby\nfactory = MessagePack::Factory.new\nfactory.register_type(0x01, MyClass1) # same with next line\nfactory.register_type(0x01, MyClass1, packer: :to_msgpack_ext, unpacker: :from_msgpack_ext)\npk = factory.packer(options_for_packer)\nuk = factory.unpacker(options_for_unpacker)\n```\n\nFor `MessagePack.pack` and `MessagePack.unpack`, default packer/unpacker refer `MessagePack::DefaultFactory`. Call `MessagePack::DefaultFactory.register_type` to enable types process globally.\n\n```ruby\nMessagePack::DefaultFactory.register_type(0x03, MyClass3)\nMessagePack.unpack(data_with_ext_typeid_03) #=\u003e MyClass3 instance\n```\n\nAlternatively, extension types can call the packer or unpacker recursively to generate the extension data:\n\n```ruby\nPoint = Struct.new(:x, :y)\nfactory = MessagePack::Factory.new\nfactory.register_type(\n  0x01,\n  Point,\n  packer: -\u003e(point, packer) {\n    packer.write(point.x)\n    packer.write(point.y)\n  },\n  unpacker: -\u003e(unpacker) {\n    x = unpacker.read\n    y = unpacker.read\n    Point.new(x, y)\n  },\n  recursive: true,\n)\nfactory.load(factory.dump(Point.new(12, 34))) # =\u003e #\u003cstruct Point x=12, y=34\u003e\n```\n\n## Pooling\n\nCreating `Packer` and `Unpacker` objects is expensive. For best performance it is preferable to re-use these objects.\n\n`MessagePack::Factory#pool` makes that easier:\n\n```ruby\nfactory = MessagePack::Factory.new\nfactory.register_type(\n  0x01,\n  Point,\n  packer: -\u003e(point, packer) {\n    packer.write(point.x)\n    packer.write(point.y)\n  },\n  unpacker: -\u003e(unpacker) {\n    x = unpacker.read\n    y = unpacker.read\n    Point.new(x, y)\n  },\n  recursive: true,\n)\npool = factory.pool(5) # The pool size should match the number of threads expected to use the factory concurrently.\n\npool.load(pool.dump(Point.new(12, 34))) # =\u003e #\u003cstruct Point x=12, y=34\u003e\n```\n\n## Buffer API\n\nMessagePack for Ruby provides a buffer API so that you can read or write data by hand, not via Packer or Unpacker API.\n\nThis [MessagePack::Buffer](http://ruby.msgpack.org/MessagePack/Buffer.html) is backed with a fixed-length shared memory pool which is very fast for small data (\u003c= 4KB),\nand has zero-copy capability which significantly affects performance to handle large binary data.\n\n## How to build and run tests\n\nBefore building msgpack, you need to install bundler and dependencies.\n\n    gem install bundler\n    bundle install\n\nThen, you can run the tasks as follows:\n\n### Build\n\n    bundle exec rake build\n\n### Run tests\n\n    bundle exec rake spec\n\n### Generating docs\n\n    bundle exec rake doc\n\n## How to build -java rubygems\n\nTo build -java gems for JRuby, run:\n\n    rake build:java\n\nIf this directory has Gemfile.lock (generated with MRI), remove it beforehand.\n\n## Updating documents\n\nOnline documentation (https://ruby.msgpack.org) is generated from the gh-pages branch.\nTo update documents in gh-pages branch:\n\n    bundle exec rake doc\n    git checkout gh-pages\n    cp -a doc/* ./\n\n## Copyright\n\n* Author\n  * Sadayuki Furuhashi \u003cfrsyuki@gmail.com\u003e\n* Copyright\n  * Copyright (c) 2008-2015 Sadayuki Furuhashi\n* License\n  * Apache License, Version 2.0\n","funding_links":[],"categories":["Ruby","Gems"],"sub_categories":["Serialization"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsgpack%2Fmsgpack-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsgpack%2Fmsgpack-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsgpack%2Fmsgpack-ruby/lists"}