Object.yaml

--- 
:name: Object
:comment: |-
  Object is the root of Ruby's class hierarchy.  Its methods are available
  to all classes unless explicitly overridden.
  
  Object mixes in the Kernel module, making the built-in kernel functions
  globally accessible. Although the instance methods of Object are defined
  by the Kernel module, we have chosen to document them here for clarity.
  
  In the descriptions of Object's methods, the parameter <i>symbol</i> refers
  to a symbol, which is either a quoted string or a Symbol (such as
  <code>:name</code>).
:instance_methods: 
- :name: to_enum
  :arglist: |-
    obj.to_enum(method = :each, *args)
    obj.enum_for(method = :each, *args)
  :comment: |-
    Creates a new Enumerator which will enumerate by on calling +method+ on
    +obj+.
    
    +method+:: the method to call on +obj+ to generate the enumeration
    +args+:: arguments that will be passed in +method+ <i>in addition</i>
             to the item itself.  Note that the number of args
             must not exceed the number expected by +method+
    
    === Example
    
      str = "xyz"
    
      enum = str.enum_for(:each_byte)
      enum.each { |b| puts b }
      # => 120
      # => 121
      # => 122
    
      # protect an array from being modified by some_method
      a = [1, 2, 3]
      some_method(a.to_enum)
- :name: enum_for
  :arglist: |-
    obj.to_enum(method = :each, *args)
    obj.enum_for(method = :each, *args)
  :comment: |-
    Creates a new Enumerator which will enumerate by on calling +method+ on
    +obj+.
    
    +method+:: the method to call on +obj+ to generate the enumeration
    +args+:: arguments that will be passed in +method+ <i>in addition</i>
             to the item itself.  Note that the number of args
             must not exceed the number expected by +method+
    
    === Example
    
      str = "xyz"
    
      enum = str.enum_for(:each_byte)
      enum.each { |b| puts b }
      # => 120
      # => 121
      # => 122
    
      # protect an array from being modified by some_method
      a = [1, 2, 3]
      some_method(a.to_enum)
- :name: extend
  :arglist: obj.extend(module, ...)    -> obj
  :comment: |-
    Adds to _obj_ the instance methods from each module given as a
    parameter.
    
       module Mod
         def hello
           "Hello from Mod.\n"
         end
       end
    
       class Klass
         def hello
           "Hello from Klass.\n"
         end
       end
    
       k = Klass.new
       k.hello         #=> "Hello from Klass.\n"
       k.extend(Mod)   #=> #<Klass:0x401b3bc8>
       k.hello         #=> "Hello from Mod.\n"
- :name: object_id
  :arglist: |-
    obj.__id__       -> fixnum
    obj.object_id    -> fixnum
  :comment: |-
    Returns an integer identifier for <i>obj</i>. The same number will
    be returned on all calls to <code>id</code> for a given object, and
    no two active objects will share an id.
    <code>Object#object_id</code> is a different concept from the
    <code>:name</code> notation, which returns the symbol id of
    <code>name</code>. Replaces the deprecated <code>Object#id</code>.
- :name: display
  :arglist: obj.display(port=$>)    -> nil
  :comment: |-
    Prints <i>obj</i> on the given port (default <code>$></code>).
    Equivalent to:
    
       def display(port=$>)
         port.write self
       end
    
    For example:
    
       1.display
       "cat".display
       [ 4, 5, 6 ].display
       puts
    
    <em>produces:</em>
    
       1cat456
- :name: nil?
  :arglist: nil?()
  :comment: |-
    call_seq:
      nil.nil?               -> true
      <anything_else>.nil?   -> false
    
    Only the object <i>nil</i> responds <code>true</code> to <code>nil?</code>.
- :name: ===
  :arglist: obj === other   -> true or false
  :comment: |-
    Case Equality---For class <code>Object</code>, effectively the same
    as calling  <code>#==</code>, but typically overridden by descendants
    to provide meaningful semantics in <code>case</code> statements.
- :name: =~
  :arglist: obj =~ other  -> nil
  :comment: |-
    Pattern Match---Overridden by descendants (notably
    <code>Regexp</code> and <code>String</code>) to provide meaningful
    pattern-match semantics.
- :name: "!~"
  :arglist: obj !~ other  -> true or false
  :comment: |-
    Returns true if two objects do not match (using the <i>=~</i>
    method), otherwise false.
- :name: eql?
  :arglist: |-
    obj == other        -> true or false
    obj.equal?(other)   -> true or false
    obj.eql?(other)     -> true or false
  :comment: |-
    Equality---At the <code>Object</code> level, <code>==</code> returns
    <code>true</code> only if <i>obj</i> and <i>other</i> are the
    same object. Typically, this method is overridden in descendant
    classes to provide class-specific meaning.
    
    Unlike <code>==</code>, the <code>equal?</code> method should never be
    overridden by subclasses: it is used to determine object identity
    (that is, <code>a.equal?(b)</code> iff <code>a</code> is the same
    object as <code>b</code>).
    
    The <code>eql?</code> method returns <code>true</code> if
    <i>obj</i> and <i>anObject</i> have the same value. Used by
    <code>Hash</code> to test members for equality.  For objects of
    class <code>Object</code>, <code>eql?</code> is synonymous with
    <code>==</code>. Subclasses normally continue this tradition, but
    there are exceptions. <code>Numeric</code> types, for example,
    perform type conversion across <code>==</code>, but not across
    <code>eql?</code>, so:
    
       1 == 1.0     #=> true
       1.eql? 1.0   #=> false
- :name: hash
  :arglist: hash()
  :comment: |-
    Generates a <code>Fixnum</code> hash value for this object.
    This function must have the property that a.eql?(b) implies
    a.hash <code>==</code> b.hash.
    The hash value is used by class <code>Hash</code>.
    Any hash value that exceeds the capacity of a <code>Fixnum</code> will be
    truncated before being used.
    
         "waffle".hash #=> -910576647
- :name: <=>
  :arglist: obj <=> other -> 0 or nil
  :comment: Returns 0 if obj === other, otherwise nil.
- :name: class
  :arglist: obj.class    -> class
  :comment: |-
    Returns the class of <i>obj</i>. This method must always be
    called with an explicit receiver, as <code>class</code> is also a
    reserved word in Ruby.
    
       1.class      #=> Fixnum
       self.class   #=> Object
- :name: singleton_class
  :arglist: obj.singleton_class    -> class
  :comment: |-
    Returns the singleton class of <i>obj</i>.  This method creates
    a new singleton class if <i>obj</i> does not have it.
    
    If <i>obj</i> is <code>nil</code>, <code>true</code>, or
    <code>false</code>, it returns NilClass, TrueClass, or FalseClass,
    respectively.
    If <i>obj</i> is a Fixnum or a Symbol, it raises a TypeError.
    
       Object.new.singleton_class  #=> #<Class:#<Object:0xb7ce1e24>>
       String.singleton_class      #=> #<Class:String>
       nil.singleton_class         #=> NilClass
- :name: clone
  :arglist: obj.clone -> an_object
  :comment: |-
    Produces a shallow copy of <i>obj</i>---the instance variables of
    <i>obj</i> are copied, but not the objects they reference. Copies
    the frozen and tainted state of <i>obj</i>. See also the discussion
    under <code>Object#dup</code>.
    
       class Klass
          attr_accessor :str
       end
       s1 = Klass.new      #=> #<Klass:0x401b3a38>
       s1.str = "Hello"    #=> "Hello"
       s2 = s1.clone       #=> #<Klass:0x401b3998 @str="Hello">
       s2.str[1,4] = "i"   #=> "i"
       s1.inspect          #=> "#<Klass:0x401b3a38 @str=\"Hi\">"
       s2.inspect          #=> "#<Klass:0x401b3998 @str=\"Hi\">"
    
    This method may have class-specific behavior.  If so, that
    behavior will be documented under the #+initialize_copy+ method of
    the class.
- :name: dup
  :arglist: obj.dup -> an_object
  :comment: |-
    Produces a shallow copy of <i>obj</i>---the instance variables of
    <i>obj</i> are copied, but not the objects they reference.
    <code>dup</code> copies the tainted state of <i>obj</i>. See also
    the discussion under <code>Object#clone</code>. In general,
    <code>clone</code> and <code>dup</code> may have different semantics
    in descendant classes. While <code>clone</code> is used to duplicate
    an object, including its internal state, <code>dup</code> typically
    uses the class of the descendant object to create the new instance.
    
    This method may have class-specific behavior.  If so, that
    behavior will be documented under the #+initialize_copy+ method of
    the class.
- :name: taint
  :arglist: obj.taint -> obj
  :comment: |-
    Marks <i>obj</i> as tainted---if the <code>$SAFE</code> level is
    set appropriately, many method calls which might alter the running
    programs environment will refuse to accept tainted strings.
- :name: tainted?
  :arglist: obj.tainted?    -> true or false
  :comment: Returns <code>true</code> if the object is tainted.
- :name: untaint
  :arglist: obj.untaint    -> obj
  :comment: Removes the taint from <i>obj</i>.
- :name: untrust
  :arglist: obj.untrust -> obj
  :comment: Marks <i>obj</i> as untrusted.
- :name: untrusted?
  :arglist: obj.untrusted?    -> true or false
  :comment: Returns <code>true</code> if the object is untrusted.
- :name: trust
  :arglist: obj.trust    -> obj
  :comment: Removes the untrusted mark from <i>obj</i>.
- :name: freeze
  :arglist: obj.freeze    -> obj
  :comment: |-
    Prevents further modifications to <i>obj</i>. A
    <code>RuntimeError</code> will be raised if modification is attempted.
    There is no way to unfreeze a frozen object. See also
    <code>Object#frozen?</code>.
    
    This method returns self.
    
       a = [ "a", "b", "c" ]
       a.freeze
       a << "z"
    
    <em>produces:</em>
    
       prog.rb:3:in `<<': can't modify frozen array (RuntimeError)
        from prog.rb:3
- :name: frozen?
  :arglist: obj.frozen?    -> true or false
  :comment: |-
    Returns the freeze status of <i>obj</i>.
    
       a = [ "a", "b", "c" ]
       a.freeze    #=> ["a", "b", "c"]
       a.frozen?   #=> true
- :name: to_s
  :arglist: obj.to_s    -> string
  :comment: |-
    Returns a string representing <i>obj</i>. The default
    <code>to_s</code> prints the object's class and an encoding of the
    object id. As a special case, the top-level object that is the
    initial execution context of Ruby programs returns ``main.''
- :name: inspect
  :arglist: obj.inspect   -> string
  :comment: |-
    Returns a string containing a human-readable representation of
    <i>obj</i>. If not overridden and no instance variables, uses the
    <code>to_s</code> method to generate the string.
    <i>obj</i>.  If not overridden, uses the <code>to_s</code> method to
    generate the string.
    
       [ 1, 2, 3..4, 'five' ].inspect   #=> "[1, 2, 3..4, \"five\"]"
       Time.new.inspect                 #=> "2008-03-08 19:43:39 +0900"
- :name: singleton_methods
  :arglist: obj.singleton_methods(all=true)    -> array
  :comment: |-
    Returns an array of the names of singleton methods for <i>obj</i>.
    If the optional <i>all</i> parameter is true, the list will include
    methods in modules included in <i>obj</i>.
    Only public and protected singleton methods are returned.
    
       module Other
         def three() end
       end
    
       class Single
         def Single.four() end
       end
    
       a = Single.new
    
       def a.one()
       end
    
       class << a
         include Other
         def two()
         end
       end
    
       Single.singleton_methods    #=> [:four]
       a.singleton_methods(false)  #=> [:two, :one]
       a.singleton_methods         #=> [:two, :one, :three]
- :name: instance_variables
  :arglist: obj.instance_variables    -> array
  :comment: |-
    Returns an array of instance variable names for the receiver. Note
    that simply defining an accessor does not create the corresponding
    instance variable.
    
       class Fred
         attr_accessor :a1
         def initialize
           @iv = 3
         end
       end
       Fred.new.instance_variables   #=> [:@iv]
- :name: instance_variable_get
  :arglist: obj.instance_variable_get(symbol)    -> obj
  :comment: |-
    Returns the value of the given instance variable, or nil if the
    instance variable is not set. The <code>@</code> part of the
    variable name should be included for regular instance
    variables. Throws a <code>NameError</code> exception if the
    supplied symbol is not valid as an instance variable name.
    
       class Fred
         def initialize(p1, p2)
           @a, @b = p1, p2
         end
       end
       fred = Fred.new('cat', 99)
       fred.instance_variable_get(:@a)    #=> "cat"
       fred.instance_variable_get("@b")   #=> 99
- :name: instance_variable_set
  :arglist: obj.instance_variable_set(symbol, obj)    -> obj
  :comment: |-
    Sets the instance variable names by <i>symbol</i> to
    <i>object</i>, thereby frustrating the efforts of the class's
    author to attempt to provide proper encapsulation. The variable
    did not have to exist prior to this call.
    
       class Fred
         def initialize(p1, p2)
           @a, @b = p1, p2
         end
       end
       fred = Fred.new('cat', 99)
       fred.instance_variable_set(:@a, 'dog')   #=> "dog"
       fred.instance_variable_set(:@c, 'cat')   #=> "cat"
       fred.inspect                             #=> "#<Fred:0x401b3da8 @a=\"dog\", @b=99, @c=\"cat\">"
- :name: instance_variable_defined?
  :arglist: obj.instance_variable_defined?(symbol)    -> true or false
  :comment: |-
    Returns <code>true</code> if the given instance variable is
    defined in <i>obj</i>.
    
       class Fred
         def initialize(p1, p2)
           @a, @b = p1, p2
         end
       end
       fred = Fred.new('cat', 99)
       fred.instance_variable_defined?(:@a)    #=> true
       fred.instance_variable_defined?("@b")   #=> true
       fred.instance_variable_defined?("@c")   #=> false
- :name: remove_instance_variable
  :arglist: obj.remove_instance_variable(symbol)    -> obj
  :comment: |-
    Removes the named instance variable from <i>obj</i>, returning that
    variable's value.
    
       class Dummy
         attr_reader :var
         def initialize
           @var = 99
         end
         def remove
           remove_instance_variable(:@var)
         end
       end
       d = Dummy.new
       d.var      #=> 99
       d.remove   #=> 99
       d.var      #=> nil
- :name: instance_of?
  :arglist: obj.instance_of?(class)    -> true or false
  :comment: |-
    Returns <code>true</code> if <i>obj</i> is an instance of the given
    class. See also <code>Object#kind_of?</code>.
- :name: kind_of?
  :arglist: |-
    obj.is_a?(class)       -> true or false
    obj.kind_of?(class)    -> true or false
  :comment: |-
    Returns <code>true</code> if <i>class</i> is the class of
    <i>obj</i>, or if <i>class</i> is one of the superclasses of
    <i>obj</i> or modules included in <i>obj</i>.
    
       module M;    end
       class A
         include M
       end
       class B < A; end
       class C < B; end
       b = B.new
       b.instance_of? A   #=> false
       b.instance_of? B   #=> true
       b.instance_of? C   #=> false
       b.instance_of? M   #=> false
       b.kind_of? A       #=> true
       b.kind_of? B       #=> true
       b.kind_of? C       #=> false
       b.kind_of? M       #=> true
- :name: is_a?
  :arglist: |-
    obj.is_a?(class)       -> true or false
    obj.kind_of?(class)    -> true or false
  :comment: |-
    Returns <code>true</code> if <i>class</i> is the class of
    <i>obj</i>, or if <i>class</i> is one of the superclasses of
    <i>obj</i> or modules included in <i>obj</i>.
    
       module M;    end
       class A
         include M
       end
       class B < A; end
       class C < B; end
       b = B.new
       b.instance_of? A   #=> false
       b.instance_of? B   #=> true
       b.instance_of? C   #=> false
       b.instance_of? M   #=> false
       b.kind_of? A       #=> true
       b.kind_of? B       #=> true
       b.kind_of? C       #=> false
       b.kind_of? M       #=> true
- :name: tap
  :arglist: obj.tap{|x|...}    -> obj
  :comment: |-
    Yields <code>x</code> to the block, and then returns <code>x</code>.
    The primary purpose of this method is to "tap into" a method chain,
    in order to perform operations on intermediate results within the chain.
    
        (1..10)                .tap {|x| puts "original: #{x.inspect}"}
          .to_a                .tap {|x| puts "array: #{x.inspect}"}
          .select {|x| x%2==0} .tap {|x| puts "evens: #{x.inspect}"}
          .map { |x| x*x }     .tap {|x| puts "squares: #{x.inspect}"}
- :name: method
  :arglist: obj.method(sym)    -> method
  :comment: |-
    Looks up the named method as a receiver in <i>obj</i>, returning a
    <code>Method</code> object (or raising <code>NameError</code>). The
    <code>Method</code> object acts as a closure in <i>obj</i>'s object
    instance, so instance variables and the value of <code>self</code>
    remain available.
    
       class Demo
         def initialize(n)
           @iv = n
         end
         def hello()
           "Hello, @iv = #{@iv}"
         end
       end
    
       k = Demo.new(99)
       m = k.method(:hello)
       m.call   #=> "Hello, @iv = 99"
    
       l = Demo.new('Fred')
       m = l.method("hello")
       m.call   #=> "Hello, @iv = Fred"
- :name: public_method
  :arglist: obj.public_method(sym)    -> method
  :comment: Similar to _method_, searches public method only.
- :name: define_singleton_method
  :arglist: |-
    define_singleton_method(symbol, method) -> new_method
    define_singleton_method(symbol) { block } -> proc
  :comment: |-
    Defines a singleton method in the receiver. The _method_
    parameter can be a +Proc+, a +Method+ or an +UnboundMethod+ object.
    If a block is specified, it is used as the method body.
    
       class A
         class << self
           def class_name
             to_s
           end
         end
       end
       A.define_singleton_method(:who_am_i) do
         "I am: #{class_name}"
       end
       A.who_am_i   # ==> "I am: A"
    
       guy = "Bob"
       guy.define_singleton_method(:hello) { "#{self}: Hello there!" }
       guy.hello    #=>  "Bob: Hello there!"
- :name: send
  :arglist: |-
    obj.send(symbol [, args...])        -> obj
    obj.__send__(symbol [, args...])      -> obj
  :comment: |-
    Invokes the method identified by _symbol_, passing it any
    arguments specified. You can use <code>__send__</code> if the name
    +send+ clashes with an existing method in _obj_.
    
       class Klass
         def hello(*args)
           "Hello " + args.join(' ')
         end
       end
       k = Klass.new
       k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"
- :name: public_send
  :arglist: obj.public_send(symbol [, args...])  -> obj
  :comment: |-
    Invokes the method identified by _symbol_, passing it any
    arguments specified. Unlike send, public_send calls public
    methods only.
    
       1.public_send(:puts, "hello")  # causes NoMethodError
- :name: respond_to?
  :arglist: obj.respond_to?(symbol, include_private=false) -> true or false
  :comment: |-
    Returns +true+ if _obj_ responds to the given
    method. Private methods are included in the search only if the
    optional second parameter evaluates to +true+.
    
    If the method is not implemented,
    as Process.fork on Windows, File.lchmod on GNU/Linux, etc.,
    false is returned.
    
    If the method is not defined, <code>respond_to_missing?</code>
    method is called and the result is returned.
- :name: respond_to_missing?
  :arglist: obj.respond_to_missing?(symbol, include_private) -> true or false
  :comment: |-
    Hook method to return whether the _obj_ can respond to _id_ method
    or not.
    
    See #respond_to?.
:class_methods: []