U:RDoc::TopLevel[ iI"marshal.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[šS:RDoc::Markup::Heading: leveli: textI"Marshal Format;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"QThe Marshal format is used to serialize ruby objects. The format can store ;TI"Garbitrary objects through three user-defined extension mechanisms.;T@ o; ;[I"RFor documentation on using Marshal to serialize and deserialize objects, see ;TI"the Marshal module.;T@ o; ;[I"IThis document calls a serialized set of objects a stream. The Ruby ;TI"Pimplementation can load a set of objects from a String, an IO or an object ;TI"%that implements a +getc+ method.;T@ S; ; i; I"Stream Format;T@ o; ;[I"TThe first two bytes of the stream contain the major and minor version, each as ;TI"Ma single byte encoding a digit. The version implemented in Ruby is 4.8 ;TI"E(stored as "\x04\x08") and is supported by ruby 1.8.0 and newer.;T@ o; ;[ I"RDifferent major versions of the Marshal format are not compatible and cannot ;TI"Qbe understood by other major versions. Lesser minor versions of the format ;TI"Scan be understood by newer minor versions. Format 4.7 can be loaded by a 4.8 ;TI"Limplementation but format 4.8 cannot be loaded by a 4.7 implementation.;T@ o; ;[I"TFollowing the version bytes is a stream describing the serialized object. The ;TI"Sstream contains nested objects (the same as a Ruby object) but objects in the ;TI"Nstream do not necessarily have a direct mapping to the Ruby object model.;T@ o; ;[I"SEach object in the stream is described by a byte indicating its type followed ;TI"Sby one or more bytes describing the object. When "object" is mentioned below ;TI"@it means any of the types below that defines a Ruby object.;T@ S; ; i; I"true, false, nil;T@ o; ;[I"JThese objects are each one byte long. "T" is represents +true+, "F" ;TI"1represents +false+ and "0" represents +nil+.;T@ S; ; i; I"Fixnum and long;T@ o; ;[ I"S"i" represents a signed 32 bit value using a packed format. One through five ;TI"Lbytes follows the type. The value loaded will always be a Fixnum. On ;TI"M32 bit platforms (where the precision of a Fixnum is less than 32 bits) ;TI"7loading large values will cause overflow on CRuby.;T@ o; ;[ I"TThe fixnum type is used to represent both ruby Fixnum objects and the sizes of ;TI"Kmarshaled arrays, hashes, instance variables and other types. In the ;TI"Tfollowing sections "long" will mean the format described below, which supports ;TI"full 32 bit precision.;T@ o; ;[I"5The first byte has the following special values:;T@ o:RDoc::Markup::List: @type: NOTE: @items[o:RDoc::Markup::ListItem: @label[I" "\x00";T;[o; ;[I"5The value of the integer is 0. No bytes follow.;T@ o;;[I" "\x01";T;[o; ;[I"JThe total size of the integer is two bytes. The following byte is a ;TI"Npositive integer in the range of 0 through 255. Only values between 123 ;TI":and 255 should be represented this way to save bytes.;T@ o;;[I" "\xff";T;[o; ;[I"JThe total size of the integer is two bytes. The following byte is a ;TI"6negative integer in the range of -1 through -256.;T@ o;;[I" "\x02";T;[o; ;[I"RThe total size of the integer is three bytes. The following two bytes are a ;TI"$positive little-endian integer.;T@ o;;[I" "\xfe";T;[o; ;[I"RThe total size of the integer is three bytes. The following two bytes are a ;TI"$negative little-endian integer.;T@ o;;[I" "\x03";T;[o; ;[I"QThe total size of the integer is four bytes. The following three bytes are ;TI"&a positive little-endian integer.;T@ o;;[I" "\xfd";T;[o; ;[I"RThe total size of the integer is two bytes. The following three bytes are a ;TI"$negative little-endian integer.;T@ o;;[I" "\x04";T;[o; ;[ I"RThe total size of the integer is five bytes. The following four bytes are a ;TI"Jpositive little-endian integer. For compatibility with 32 bit ruby, ;TI"Ronly Fixnums less than 1073741824 should be represented this way. For sizes ;TI"2of stream objects full precision may be used.;T@ o;;[I" "\xfc";T;[o; ;[ I"QThe total size of the integer is two bytes. The following four bytes are a ;TI"Jnegative little-endian integer. For compatibility with 32 bit ruby, ;TI"Qonly Fixnums greater than -10737341824 should be represented this way. For ;TI"8sizes of stream objects full precision may be used.;T@ o; ;[ I"QOtherwise the first byte is a sign-extended eight-bit value with an offset. ;TI"PIf the value is positive the value is determined by subtracting 5 from the ;TI"Qvalue. If the value is negative the value is determined by adding 5 to the ;TI" value.;T@ o; ;[I"SThere are multiple representations for many values. CRuby always outputs the ;TI"&shortest representation possible.;T@ S; ; i; I"Symbols and Byte Sequence;T@ o; ;[ I"N":" represents a real symbol. A real symbol contains the data needed to ;TI"Odefine the symbol for the rest of the stream as future occurrences in the ;TI"Sstream will instead be references (a symbol link) to this one. The reference ;TI"Tis a zero-indexed 32 bit value (so the first occurrence of :hello ;TI" is 0).;T@ o; ;[I"RFollowing the type byte is byte sequence which consists of a long indicating ;TI"Tthe number of bytes in the sequence followed by that many bytes of data. Byte ;TI" sequences have no encoding.;T@ o; ;[I"OFor example, the following stream contains the Symbol :hello:;T@ o:RDoc::Markup::Verbatim;[I""\x04\x08:\x0ahello" ;T: @format0o; ;[I"P";" represents a Symbol link which references a previously defined Symbol. ;TI"TFollowing the type byte is a long containing the index in the lookup table for ;TI"$the linked (referenced) Symbol.;T@ o; ;[I"NFor example, the following stream contains [:hello, :hello]:;T@ o;;[I""\x04\b[\a:\nhello;\x00" ;T;0o; ;[I"MWhen a "symbol" is referenced below it may be either a real symbol or a ;TI"symbol link.;T@ S; ; i; I"Object References;T@ o; ;[ I"RSeparate from but similar to symbol references, the stream contains only one ;TI"Ncopy of each object (as determined by #object_id) for all objects except ;TI"Ktrue, false, nil, Fixnums and Symbols (which are stored separately as ;TI"Tdescribed above) a one-indexed 32 bit value will be stored and reused when the ;TI"Hobject is encountered again. (The first object has an index of 1).;T@ o; ;[I"R"@" represents an object link. Following the type byte is a long giving the ;TI"index of the object.;T@ o; ;[I"EFor example, the following stream contains an Array of the same ;TI"'"hello" object twice:;T@ o;;[I""\004\b[\a\"\nhello@\006" ;T;0S; ; i; I"Instance Variables;T@ o; ;[ I"N"I" indicates that instance variables follow the next object. An object ;TI"Tfollows the type byte. Following the object is a length indicating the number ;TI"Mof instance variables for the object. Following the length is a set of ;TI"Qname-value pairs. The names are symbols while the values are objects. The ;TI"Csymbols must be instance variable names (:@name).;T@ o; ;[I"QAn Object ("o" type, described below) uses the same format for its instance ;TI"!variables as described here.;T@ o; ;[I"KFor a String and Regexp (described below) a special instance variable ;TI"6:E is used to indicate the Encoding.;T@ S; ; i; I" Extended;T@ o; ;[I"T"e" indicates that the next object is extended by a module. An object follows ;TI"Tthe type byte. Following the object is a symbol that contains the name of the ;TI"&module the object is extended by.;T@ S; ; i; I" Array;T@ o; ;[I"P"[" represents an Array. Following the type byte is a long indicating the ;TI"Mnumber of objects in the array. The given number of objects follow the ;TI" length.;T@ S; ; i; I" Bignum;T@ o; ;[I">"l" represents a Bignum which is composed of three parts:;T@ o;;;;[o;;[I" sign;T;[o; ;[I"MA single byte containing "+" for a positive value or "-" for a negative ;TI" value.;To;;[I" length;T;[o; ;[I"NA long indicating the number of bytes of Bignum data follows, divided by ;TI"Otwo. Multiply the length by two to determine the number of bytes of data ;TI"that follow.;To;;[I" data;T;[o; ;[I"2Bytes of Bignum data representing the number.;T@ o; ;[I"PThe following ruby code will reconstruct the Bignum value from an array of ;TI" bytes:;T@ o;;[ I"result = 0 ;TI" ;TI"*bytes.each_with_index do |byte, exp| ;TI"( result += (byte * 2 ** (exp * 8)) ;TI" end ;T;0S; ; i; I"Class and Module;T@ o; ;[ I"O"c" represents a Class object, "m" represents a Module and "M" represents ;TI"Reither a class or module (this is an old-style for compatibility). No class ;TI"Ror module content is included, this type is only a reference. Following the ;TI"Ptype byte is a byte sequence which is used to look up an existing class or ;TI"module, respectively.;T@ o; ;[I"=Instance variables are not allowed on a class or module.;T@ o; ;[I"@If no class or module exists an exception should be raised.;T@ o; ;[I"IFor "c" and "m" types, the loaded object must be a class or module, ;TI"respectively.;T@ S; ; i; I" Data;T@ o; ;[I"Q"d" represents a Data object. (Data objects are wrapped pointers from ruby ;TI"Textensions.) Following the type byte is a symbol indicating the class for the ;TI"JData object and an object that contains the state of the Data object.;T@ o; ;[I"TTo dump a Data object Ruby calls _dump_data. To load a Data object Ruby calls ;TI"K_load_data with the state of the object on a newly allocated instance.;T@ S; ; i; I" Float;T@ o; ;[I"P"f" represents a Float object. Following the type byte is a byte sequence ;TI"Ccontaining the float value. The following values are special:;T@ o;;;;[o;;[I" "inf";T;[o; ;[I"Positive infinity;T@ o;;[I" "-inf";T;[o; ;[I"Negative infinity;T@ o;;[I" "nan";T;[o; ;[I"Not a Number;T@ o; ;[I"NOtherwise the byte sequence contains a C double (loadable by strtod(3)). ;TI"OOlder minor versions of Marshal also stored extra mantissa bits to ensure ;TI"Fportability across platforms but 4.8 does not include these. See;To;;: LABEL;[o;;[I"ruby-talk:69518;T;[o; ;[I"for some explanation.;T@ S; ; i; I"%Hash and Hash with Default Value;T@ o; ;[ I"S"{" represents a Hash object while "}" represents a Hash with a default value ;TI"Rset (Hash.new 0). Following the type byte is a long indicating ;TI"Sthe number of key-value pairs in the Hash, the size. Double the given number ;TI" of objects follow the size.;T@ o; ;[I"NFor a Hash with a default value, the default value follows all the pairs.;T@ S; ; i; I"Module and Old Module;T@ S; ; i; I" Object;T@ o; ;[ I"P"o" represents an object that doesn't have any other special form (such as ;TI"Na user-defined or built-in format). Following the type byte is a symbol ;TI"Rcontaining the class name of the object. Following the class name is a long ;TI"Qindicating the number of instance variable names and values for the object. ;TI"ADouble the given number of pairs of objects follow the size.;T@ o; ;[I"NThe keys in the pairs must be symbols containing instance variable names.;T@ S; ; i; I"Regular Expression;T@ o; ;[ I"M"/" represents a regular expression. Following the type byte is a byte ;TI"Tsequence containing the regular expression source. Following the type byte is ;TI"Ta byte containing the regular expression options (case-insensitive, etc.) as a ;TI"signed 8-bit value.;T@ o; ;[ I"RRegular expressions can have an encoding attached through instance variables ;TI"O(see above). If no encoding is attached escapes for the following regexp ;TI"Rspecials not present in ruby 1.8 must be removed: g-m, o-q, u, y, E, F, H-L, ;TI"N-V, X, Y.;T@ S; ; i; I" String;T@ o; ;[ I"J'"' represents a String. Following the type byte is a byte sequence ;TI"Tcontaining the string content. When dumped from ruby 1.9 an encoding instance ;TI"Tvariable (:E see above) should be included unless the encoding is ;TI" binary.;T@ S; ; i; I" Struct;T@ o; ;[ I"R"S" represents a Struct. Following the type byte is a symbol containing the ;TI"Pname of the struct. Following the name is a long indicating the number of ;TI"Smembers in the struct. Double the number of objects follow the member count. ;TI"PEach member is a pair containing the member's symbol and an object for the ;TI"value of that member.;T@ o; ;[I"PIf the struct name does not match a Struct subclass in the running ruby an ;TI" exception should be raised.;T@ o; ;[I"QIf there is a mismatch between the struct in the currently running ruby and ;TI"Lthe member count in the marshaled struct an exception should be raised.;T@ S; ; i; I"User Class;T@ o; ;[I"R"C" represents a subclass of a String, Regexp, Array or Hash. Following the ;TI"Ttype byte is a symbol containing the name of the subclass. Following the name ;TI"is the wrapped object.;T@ S; ; i; I"User Defined;T@ o; ;[ I"Q"u" represents an object with a user-defined serialization format using the ;TI"S+_dump+ instance method and +_load+ class method. Following the type byte is ;TI"Ma symbol containing the class name. Following the class name is a byte ;TI"Gsequence containing the user-defined representation of the object.;T@ o; ;[I"TThe class method +_load+ is called on the class with a string created from the ;TI"byte-sequence.;T@ S; ; i; I"User Marshal;T@ o; ;[ I"Q"U" represents an object with a user-defined serialization format using the ;TI"R+marshal_dump+ and +marshal_load+ instance methods. Following the type byte ;TI"Sis a symbol containing the class name. Following the class name is an object ;TI"containing the data.;T@ o; ;[I"NUpon loading a new instance must be allocated and +marshal_load+ must be ;TI"*called on the instance with the data.;T: @file@:0@omit_headings_from_table_of_contents_below0