From ed27cdd5c5c16822ff8e490e05c52ae36e1d30c0 Mon Sep 17 00:00:00 2001
From: Christopher Aue <mail@christopheraue.net>
Date: Mon, 13 Jun 2016 20:17:29 +0200
Subject: [PATCH] Added documentation how to custom serialize and preserve
 symbols

---
 README.rdoc | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.rdoc b/README.rdoc
index fca46754..a098d43e 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -91,6 +91,36 @@ or event-driven style which works well with EventMachine:
 
 See {API reference}[http://ruby.msgpack.org/MessagePack/Unpacker.html] for details.
 
+= Serializing and deserializing symbols
+
+By default, symbols are serialized as strings:
+
+    packed = :symbol.to_msgpack     # => "\xA6symbol"
+    MessagePack.unpack(packed)      # => "symbol"
+
+This can be customized by registering an extension type for them:
+
+    MessagePack::DefaultFactory.register_type(0x00, Symbol)
+
+    # symbols now survive round trips
+    packed = :symbol.to_msgpack     # => "\xc7\x06\x00symbol"
+    MessagePack.unpack(packed)      # => :symbol
+
+The extension type for symbols is configurable like any other extension type.
+For example, to customize how symbols are packed you can just redefine
+Symbol#to_msgpack_ext. Doing this gives you an option to prevent symbols from
+being serialized altogether by throwing an exception:
+
+    class Symbol
+        def to_msgpack_ext
+            raise "Serialization of symbols prohibited"
+        end
+    end
+
+    MessagePack::DefaultFactory.register_type(0x00, Symbol)
+
+    [1, :symbol, 'string'].to_msgpack  # => RuntimeError: Serialization of symbols prohibited
+
 = Extension Types
 
 Packer and Unpacker support {Extension types of MessagePack}[https://github.com/msgpack/msgpack/blob/master/spec.md#types-extension-type].