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 <code>:hello</code> ;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 <code>:hello</code>:;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 <code>[:hello, :hello]</code>:;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"'<code>"hello"</code> 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 (<code>:@name</code>).;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<code>:E</code> 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 (<code>Hash.new 0</code>).  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 (<code>:E</code> 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