Module Kernel
In: lib/core/facets/blank.rb
lib/core/facets/bitmask.rb
lib/core/facets/boolean.rb
lib/core/facets/kernel/here.rb
lib/core/facets/kernel/not_nil.rb
lib/core/facets/kernel/resc.rb
lib/core/facets/kernel/ask.rb
lib/core/facets/kernel/__here__.rb
lib/core/facets/kernel/respond.rb
lib/core/facets/kernel/in.rb
lib/core/facets/kernel/object_hexid.rb
lib/core/facets/kernel/complete.rb
lib/core/facets/kernel/callstack.rb
lib/core/facets/kernel/object_class.rb
lib/core/facets/kernel/demo.rb
lib/core/facets/kernel/d.rb
lib/core/facets/kernel/__dir__.rb
lib/core/facets/kernel/instance_send.rb
lib/core/facets/kernel/instance_assign.rb
lib/core/facets/kernel/ergo.rb
lib/core/facets/kernel/tap.rb
lib/core/facets/kernel/try.rb
lib/core/facets/kernel/method.rb
lib/core/facets/kernel/populate.rb
lib/core/facets/kernel/instance_variables.rb
lib/core/facets/kernel/singleton_class.rb
lib/core/facets/kernel/source_location.rb
lib/core/facets/kernel/returning.rb
lib/core/facets/kernel/silence.rb
lib/core/facets/kernel/require_relative.rb
lib/core/facets/kernel/constant.rb
lib/core/facets/kernel/identical.rb
lib/core/facets/kernel/maybe.rb
lib/core/facets/kernel/instance_class.rb
lib/core/facets/kernel/deep_copy.rb
lib/core/facets/kernel/require_all.rb
lib/core/facets/kernel/extension.rb
lib/core/facets/kernel/as.rb
lib/core/facets/kernel/object_send.rb
lib/core/facets/kernel/attr_singleton.rb
lib/core/facets/kernel/qua_class.rb
lib/core/facets/kernel/__class__.rb
lib/core/facets/kernel/equate.rb
lib/core/facets/kernel/with.rb
lib/core/facets/kernel/__get__.rb
lib/core/facets/kernel/val.rb
lib/core/facets/kernel/__method__.rb
lib/core/facets/kernel/p.rb
lib/core/facets/metaid.rb
lib/core/facets/lazy.rb

Methods

External Aliases

binding -> here
  A shorthand pronoun for binding().
  a = 3
  b = here
  eval( "a", b )  #=> 3
caller -> pp_callstack
class -> object_class
  Defines object_classas an alias of class. This is an alternative to class, akin to object_id.
__send__ -> instance_send
  Private send.
equal? -> identical?
class -> __class__
  Defines core method class as an alias of class. This allows you to use class as your own method, without loosing the ability to determine the object‘s class.
instance_variable_get -> __get__
  Shadow method for instance_variable_get.
instance_variable_set -> __set__
  Shadow method for instance_variable_set.

Public Instance methods

Create a single bit bitmask.

  Bit(0)  #=> 1
  Bit(1)  #=> 2
  Bit(2)  #=> 4

This is equivalent to n-shift: "1 << n".

CREDIT: Thomas Sawyer, George Moschovitis

[Source]

    # File lib/core/facets/bitmask.rb, line 97
97:   def Bit(n)
98:     1 << Integer(n)
99:   end

Similar to FILE, DIR provides the directory path to the current executing script.

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/__dir__.rb, line 8
 8:   def __DIR__
 9:     c = caller.first
10:     return nil unless c.rindex(/:\d+(:in `.*')?$/)
11:     file = $` # File.dirname(c)
12:     return nil if /\A\((.*)\)/ =~ file # eval, etc.
13:     #File.expand_path(File.dirname(file))
14:     File.dirname(file)
15:   end

Outputs the file, line and current method.

  caller(1).first
  "/usr/lib/ruby/1.8/irb/workspace.rb:52:in `irb_binding'"

CREDIT: William Mason

[Source]

    # File lib/core/facets/kernel/__here__.rb, line 9
 9:   def __HERE__
10:     caller(1).first
11:   end

Retreive the current running method name.

  def tester; __callee__; end
  tester  #=> :tester

Technically callee should provided alias names, where as method should not. But we‘ll have to leave that distinction to Ruby 1.9+.

[Source]

    # File lib/core/facets/kernel/__method__.rb, line 33
33:     def __callee__
34:       /\`([^\']+)\'/.match(caller(1).first)[1].to_sym
35:     end

Retreive the current running method name.

  def tester; __method__; end
  tester  #=> :tester

Technically callee should provided alias names, where method should not. But we‘ll have to leave that distinction to Ruby 1.9+.

[Source]

    # File lib/core/facets/kernel/__method__.rb, line 14
14:     def __method__
15:       /\`([^\']+)\'/.match(caller(1).first)[1].to_sym
16:     end

Returns a As-functor that allows one to call any ancestor‘s method directly of the given object.

  class A
    def x ; 1 ; end
  end

  class B < A
    def x ; 2 ; end
  end

  class C < B
    def x ; as(A).x ; end
  end

  C.new.x  #=> 1

[Source]

    # File lib/core/facets/kernel/as.rb, line 22
22:   def as(ancestor, &blk)
23:     @__as ||= {}
24:     unless r = @__as[ancestor]
25:       r = (@__as[ancestor] = As.new(self, ancestor))
26:     end
27:     r.instance_eval(&blk) if block_given?
28:     #yield(r) if block_given?
29:     r
30:   end

Very simple convenience method to get a console reply.

  ask "Are you happy?", "Yn"

On the command line one would see.

  $ Are you happy? [Yn]

Responding:

  $ Are you happy? [Yn] Y <ENTER>

The ask method would return "Y".

[Source]

    # File lib/core/facets/kernel/ask.rb, line 19
19:   def ask(question, answers=nil)
20:     $stdout << "#{question}"
21:     $stdout << " [#{answers}] " if answers
22:     $stdout.flush
23:     until inp = $stdin.gets ; sleep 1 ; end
24:     inp.strip
25:   end

Takes an array or hash with default values and creates singleton attr_accessors for each.

  attr_singleton_accessor { :x => 1, :y => 2 }
  @x          #=> 1
  @y          #=> 2
  self.x = 3
  self.y = 4
  self.x      #=> 3
  self.y      #=> 4

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/attr_singleton.rb, line 54
54:   def attr_singleton_accessor(*args)
55:     #h, a = *args.partition{|a| Hash===a}
56:     (class << self ; self ; end).send( :attr_accessor, *args )
57:     #(class << self ; self ; end).send( :attr_accessor, *h.keys )
58:     #h.each { |k,v| instance_variable_set("@#{k}", v) }
59:   end

Takes an array or a hash with default values and creates singleton attr_readers for each.

  attr_singleton_reader {:x => 1, :y => 2}
  @x       #=> 1
  @y       #=> 2
  self.x   #=> 1
  self.y   #=> 2

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/attr_singleton.rb, line 14
14:   def attr_singleton_reader(*args)
15:     #h, a = *args.partition{|a| Hash===a}
16:     (class << self ; self ; end).send( :attr_reader, *args )
17:     #(class << self ; self ; end).send( :attr_reader, *h.keys )
18:     #h.each { |k,v| instance_variable_set("@#{k}", v) }
19:   end

Takes an array or a hash with default values and creates singleton attr_writers for each.

  attr_singleton_writer { :x => 1, :y => 2 }
  @x           #=> 1
  @y           #=> 2
  self.x = 3
  self.y = 4
  @x           #=> 3
  @y           #=> 4

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/attr_singleton.rb, line 34
34:   def attr_singleton_writer(*args)
35:     #h, a = *args.partition{|a| Hash===a}
36:     (class << self ; self ; end).send( :attr_writer, *args )
37:     #(class << self ; self ; end).send( :attr_writer, *h.keys )
38:     #h.each { |k,v| instance_variable_set("@#{k}", v) }
39:   end

An object is blank if it‘s nil, empty, or a whitespace string. For example, "", " ", nil, [], and {} are blank.

This simplifies

  if !address.nil? && !address.empty?

to

  if !address.blank?

[Source]

    # File lib/core/facets/blank.rb, line 14
14:   def blank?
15:     respond_to?(:empty?) ? empty? : !self
16:   end

Returns true is an object is class TrueClass or FalseClass, otherwise false.

  true.bool?   #=> true
  false.bool?  #=> true
  nil.bool?    #=> false

[Source]

     # File lib/core/facets/boolean.rb, line 127
127:   def bool?
128:     (true == self or false == self)
129:   end

Parse a caller string and break it into its components, returning an array. Returns:

For example, from irb,

  call_stack(1)

produces

[["(irb)", 2, :irb_binding],

 ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, :irb_binding],
 ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, nil]]

Note: If the user decides to redefine caller() to output data in a different format, prior to requiring this, then the results will be indeterminate.

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/callstack.rb, line 27
27:   def callstack( level = 1 )
28:     call_str_array = pp_callstack(level)
29:     stack = []
30:     call_str_array.each{ |call_str|
31:       file, lineno, method = call_str.split(':')
32:       if method =~ /in `(.*)'/ then
33:         method = $1.intern()
34:       end
35:       stack << [file, lineno.to_i, method]
36:     }
37:     stack
38:   end

Repeat loop until it yeilds false or nil.

  a = [3, 2, 1]
  complete do
    b << a.pop
  end
  b  #=> [3, 2, 1, nil]

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/complete.rb, line 13
13:   def complete
14:     loop { break unless yield }
15:   end

This is similar to +Module#const_get+ but is accessible at all levels, and, unlike const_get, can handle module hierarchy.

  constant("Fixnum")                  # -> Fixnum
  constant(:Fixnum)                   # -> Fixnum

  constant("Process::Sys")            # -> Process::Sys
  constant("Regexp::MULTILINE")       # -> 4

  require 'test/unit'
  Test.constant("Unit::Assertions")   # -> Test::Unit::Assertions
  Test.constant("::Test::Unit")       # -> Test::Unit

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/constant.rb, line 18
18:   def constant(const)
19:     const = const.to_s.dup
20:     base = const.sub!(/^::/, '') ? Object : ( self.kind_of?(Module) ? self : self.class )
21:     const.split(/::/).inject(base){ |mod, name| mod.const_get(name) }
22:   end

Like p but gives file and line number.

  d("hi")

produces

  /home/dave/projects/foo.rb, 38
  "hi"

TODO: This is borderline "prime". Keep here? Another copy of it exits in dtools.rb

[Source]

    # File lib/core/facets/kernel/d.rb, line 15
15:   def d(*x)
16:     puts "#{__FILE__}, #{__LINE__}"
17:     x.each{ |e| puts e.inspect } #p(*x)
18:     x.size > 1 ? x : x.last #x.last
19:   end

Anything that can be marshaled can be copied in totality. This is also commonly called a deep_copy.

  "ABC".copy  #=> "ABC"

[Source]

    # File lib/core/facets/kernel/deep_copy.rb, line 8
 8:   def deep_copy
 9:     Marshal::load(Marshal::dump(self))
10:   end

Forces the result of a promise to be computed (if necessary) and returns the bare result object. Once evaluated, the result of the promise will be cached. Nested promises will be evaluated together, until the first non-promise result.

If called on a value that is not a promise, it will simply return it.

[Source]

     # File lib/core/facets/lazy.rb, line 219
219:   def demand( promise )
220:     if promise.respond_to? :__result__
221:       promise.__result__
222:     else # not really a promise
223:       promise
224:     end
225:   end

For debugging and showing examples. Currently this takes an argument of a string in a block.

  demo {%{ a = [1,2,3] }}
  demo {%{ a.slice(1,2) }}
  demo {%{ a.map { |x| x**3 } }}

Produces:

  a = [1,2,3]             #=>  [1, 2, 3]
  a.slice(1,2)            #=>  [2, 3]
  a.map { |x| x**3 }      #=>  [1, 8, 27]

TODO: Is there a way to do this without the eval string in block? Preferably just a block and no string.

[Source]

    # File lib/core/facets/kernel/demo.rb, line 19
19:   def demo(out=$stdout,&block)
20:     out << sprintf("%-25s#=>  %s\n", expr = block.call, eval(expr, block.binding).inspect)
21:   end

During this trying time when no one can get their techie catchwords to stick to the refrigerator no matter how hard they slap it # with the enchanted magnetic spatula, it’s good to know that the contrived phrases really do fly, graceful and unclasped and bearing north toward chilled shrimp. I know what my Hallowe’en pumpkin is going to say.

                      -- why the lucky stiff

CREDIT: WhyTheLuckyStiff

[Source]

    # File lib/core/facets/metaid.rb, line 69
69:   def eigenclass
70:     (class << self; self; end)
71:   end

Sets $VERBOSE to true for the duration of the block and back to its original value afterwards.

CREDIT: David Heinemeier Hansson

[Source]

    # File lib/core/facets/kernel/silence.rb, line 67
67:   def enable_warnings
68:     old_verbose, $VERBOSE = $VERBOSE, true
69:     yield
70:   ensure
71:     $VERBOSE = old_verbose
72:   end

Broad equality.

Checks to see if the object x is in any way equal to the reciever, starting with the identity equals? and ending with #===.

[Source]

    # File lib/core/facets/kernel/equate.rb, line 9
 9:   def equate?(x)
10:     equal?(x) || eql?(x) || self == x || self === x
11:   end

Yield self -or- return self.

  "a".ergo.upcase #=> "A"
  nil.ergo.foobar #=> nil

  "a".ergo{ |o| o.upcase } #=> "A"
  nil.ergo{ |o| o.foobar } #=> nil

This is like tap, but tap yields self -and- returns self.

CREDIT: Daniel DeLorme

[Source]

    # File lib/core/facets/kernel/ergo.rb, line 17
17:   def ergo &b
18:     if block_given?
19:       b.arity == 1 ? yield(self) : instance_eval(&b)
20:     else
21:       self
22:     end
23:   end

Don‘t say it!

[Source]

   # File lib/core/facets/kernel/extension.rb, line 4
4:   def extension
5:     class << self; self; end
6:   end

Returns true is an object is class FalseClass, otherwise false.

  true.false?   #=> false
  false.false?  #=> true
  nil.false?    #=> false

[Source]

     # File lib/core/facets/boolean.rb, line 116
116:   def false?
117:     (false == self)
118:   end

Schedules a computation to be run asynchronously in a background thread and returns a promise for its result. An attempt to demand the result of the promise will block until the computation finishes.

As with Kernel.promise, this passes the block a promise for its own result. Use wisely.

[Source]

     # File lib/core/facets/lazy.rb, line 234
234:   def future( &computation ) #:yields: result
235:     Lazy::Future.new(&computation)
236:   end

Is self included in other?

  5.in?(0..10)       #=> true
  5.in?([0,1,2,3])   #=> false

[Source]

    # File lib/core/facets/kernel/in.rb, line 8
 8:   def in?(other)
 9:     other.include?(self)
10:   end

Set instance variables using a hash.

  instance_assign('@a'=>1, '@b'=>2)
  @a   #=> 1
  @b   #=> 2

WARNING: instance_assign will be deprecated. Use instance_vars.update instead.

[Source]

    # File lib/core/facets/kernel/instance_assign.rb, line 32
32:   def instance_assign(hash)
33:     hash.each do |k,v|
34:       k = "@#{k}" if k !~ /^@/
35:       instance_variable_set(k, v)
36:     end
37:     return self
38:   end

Easy access to an object qua class, otherwise known as the object‘s metaclass or singleton class. This implemnetation alwasy returns the class, even if a block is provided to eval against it.

    It is what it is.

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/instance_class.rb, line 19
19:   def instance_class(&block)
20:     (class << self; self; end).module_eval(&block) if block
21:     (class << self; self; end)
22:   end

Return instance variable values in an array.

  class X
    def initialize(a,b)
      @a, @b = a, b
    end
  end

  x = X.new(1,2)

  x.instance_values   #=> { "a"=>1, "b"=>2 }

WARNING: instance_values will be deprecated. Use instance_vars.to_hash instead.

[Source]

    # File lib/core/facets/kernel/instance_assign.rb, line 17
17:   def instance_values
18:     instance_variables.inject({}) do |values, name|
19:       values[name[1..-1]] = instance_variable_get(name)
20:       values
21:     end
22:   end

[Source]

   # File lib/core/facets/kernel/instance_variables.rb, line 3
3:   def instance_vars
4:     InstanceVariables.new(self)
5:   end
load_local(relative_feature, safe=nil)

Alias for load_relative

Load file from same dir as calling script.

  load_local 'templib'

CREDIT: Paul Brannan, Pragmatic Programmers

[Source]

    # File lib/core/facets/kernel/require_relative.rb, line 35
35:     def load_relative(relative_feature, safe=nil)
36:       c = caller.first
37:       fail "Can't parse #{c}" unless c.rindex(/:\d+(:in `.*')?$/)
38:       file = $` # File.dirname(c)
39:       if /\A\((.*)\)/ =~ file # eval, etc.
40:         raise LoadError, "require_relative is called in #{$1}"
41:       end
42:       absolute = File.expand_path(relative_feature, File.dirname(file))
43:       load absolute, safe
44:     end

Random generator that returns true or false. Can also take a block that has a 50/50 chance to being executed.

  maybe  #=> true
  maybe  #=> false

[Source]

    # File lib/core/facets/kernel/maybe.rb, line 9
 9:   def maybe(chance = 0.5, &block)
10:     if block then
11:       yield if rand < chance
12:     else
13:       rand < chance
14:     end
15:   end

Alias a method defined in the metaclass (ie. singleton class).

  def X.y?; "y?" ; end
  X.meta_alias "ynot?", "y?"
  X.ynot?  #=> y?

CREDIT: Trans

[Source]

    # File lib/core/facets/metaid.rb, line 11
11:   def meta_alias(*args)
12:     meta_class do
13:       alias_method(*args)
14:     end
15:   end

Easy access to an object‘s "special" class, otherwise known as it‘s metaclass or singleton class.

[Source]

    # File lib/core/facets/metaid.rb, line 47
47:   def meta_class(&block)
48:     if block_given?
49:       (class << self; self; end).class_eval(&block)
50:     else
51:       (class << self; self; end)
52:     end
53:   end

Add method to a meta-class —i.e. a singleton method.

  class X; end
  X.meta_def(:x){"x"}
  X.x  #=> "x"

CREDIT: WhyTheLuckyStiff

[Source]

    # File lib/core/facets/metaid.rb, line 38
38:   def meta_def( name, &block )
39:     meta_class do
40:       define_method( name, &block )
41:     end
42:   end

Evaluate code in a metaclass. This is equivalent to ‘meta_class.instance_eval’.

CREDIT: WhyTheLuckyStiff

[Source]

    # File lib/core/facets/metaid.rb, line 22
22:   def meta_eval(str=nil, &blk)
23:     if str
24:       meta_class.instance_eval(str)
25:     else
26:       meta_class.instance_eval(&blk)
27:     end
28:   end
metaclass(&block)

Alias for meta_class

Easy access to method as object, and they retain state.

  def hello
    puts "Hello World!"
  end

  m1 = method!(:hello)   #=> <Method: #hello>

  def m1.annotate
    "simple example"
  end

  m2 = method!(:hello)
  m2.annotate  #=> "simple example"

[Source]

    # File lib/core/facets/kernel/method.rb, line 20
20:   def method!(s)
21:     #( @__methods__ ||= {} )[s.to_sym] ||= method(s)
22:     $FIRST_CLASS_METHODS[self][s.to_sym] ||= method(s)
23:   end
non_nil?()

Alias for not_nil?

The opposite of nil?.

  "hello".not_nil?     # -> true
  nil.not_nil?         # -> false

CREDIT: Gavin Sinclair

[Source]

    # File lib/core/facets/kernel/not_nil.rb, line 10
10:   def not_nil?
11:     not nil?
12:   end

Returns the object id as a string in hexideciaml, which is how Ruby reports them with inspect.

  "ABC".object_hexid  #=> "0x402d359c"

[Source]

    # File lib/core/facets/kernel/object_hexid.rb, line 8
 8:   def object_hexid
 9:     return "0x" << ('%.x' % (2*self.__id__))  #[1..-1]
10:   end

Send only to public methods.

  class X
    private
    def foo; end
  end

  X.new.object_send(:foo)
  => NoMethodError: private method `foo' called for #<X:0xb7ac6ba8>

TODO: object_send needs to change for 1.9.

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/object_send.rb, line 20
20:   def object_send(name,*args,&blk)
21:     #instance_eval "self.#{name}(*args)"
22:     if respond_to?(name)
23:       __send__(name,*args,&blk)
24:     else #if respond_to?(:method_missing)
25:       __send__(:method_missing,name,*args,&blk)
26:     #else
27:     #  raise NoMethodError
28:     end
29:   end

Alternate to standard p method that outputs Kernel#inspect to stdout, but also passes through the orginal argument(s).

  x = 1
  r = 4 + q(1)
  p r

produces

  1
  5

TODO: DEPRECATE as of 1.9, if it will do this.

[Source]

    # File lib/core/facets/kernel/p.rb, line 18
18:   def p(*x)
19:     x.each{ |e| puts e.inspect } #p(*x)
20:     x.size > 1 ? x : x.last #x.last
21:   end

Assign via accessor methods using a hash, associative array or block.

  object.populate( :a => 1, :b => 2 )
  object.populate( :a, 1, :b, 2 )
  object.populate( [:a, 1], [:b, 2] )
  object.populate( *[[:a, 1], [:b, 2]] )
  object.populate{ |s| s.a = 1; s.b = 2 }

These are all the same as doing:

  object.a = 1
  object.b = 2

Using an associative array instead of hash guarentees order of assignemnt.

Using a hash or array will not raise an error if the accessor does not exits —it will simply be skipped.

TODO: Better name, set_with ?

[Source]

    # File lib/core/facets/kernel/populate.rb, line 25
25:   def populate(data=nil) #:yield:
26:     if data
27:       data.each do |k,v|
28:         send("#{k}=", v) if respond_to?("#{k}=")
29:       end
30:     end
31:     yield(self) if block_given?
32:     self
33:   end

The promise() function is used together with demand() to implement lazy evaluation. It returns a promise to evaluate the provided block at a future time. Evaluation can be demanded and the block‘s result obtained via the demand() function.

Implicit evaluation is also supported: the first message sent to it will demand evaluation, after which that message and any subsequent messages will be forwarded to the result object.

As an aid to circular programming, the block will be passed a promise for its own result when it is evaluated. Be careful not to force that promise during the computation, lest the computation diverge.

[Source]

     # File lib/core/facets/lazy.rb, line 208
208:   def promise( &computation ) #:yields: result
209:     Lazy::Promise.new(&computation)
210:   end

Easy access to an object qua class, otherwise known as the object‘s singleton class.

Yes, another one.

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/qua_class.rb, line 10
10:   def qua_class(&block)
11:     if block_given?
12:       (class << self; self; end).class_eval(&block)
13:     else
14:       (class << self; self; end)
15:     end
16:   end

Require a pattern of files. This make is easy to require an entire directory, for instance.

  require_all 'facets/time/*'

You can also you require_all relative to the current script simply by using DIR.

  require_all(__DIR__ + '/foo/*')

[Source]

    # File lib/core/facets/kernel/require_all.rb, line 13
13:   def require_all(pat)
14:     $LOAD_PATH.each do |path|
15:       fs = Dir[File.join(path,pat)]
16:       unless fs.empty?
17:         fs.each { |f|
18:           Kernel.require(f) unless File.directory?(f)
19:         }
20:         break;
21:       end
22:     end
23:   end
require_local(relative_feature)

Alias for require_relative

Require file from same dir as calling script.

  require_local 'templib'

CREDIT: Paul Brannan, Pragmatic Programmers

[Source]

    # File lib/core/facets/kernel/require_relative.rb, line 11
11:     def require_relative(relative_feature)
12:       c = caller.first
13:       fail "Can't parse #{c}" unless c.rindex(/:\d+(:in `.*')?$/)
14:       file = $` # File.dirname(c)
15:       if /\A\((.*)\)/ =~ file # eval, etc.
16:         raise LoadError, "require_relative is called in #{$1}"
17:       end
18:       absolute = File.expand_path(relative_feature, File.dirname(file))
19:       require absolute
20:     end

Provides a shortcut to the Regexp.escape module method.

  resc("H..LO")   #=> "H\\.\\.LO"

  TODO: Should this be deprecated in favor of String#to_re/to_rx ?

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/resc.rb, line 11
11:   def resc(str)
12:     Regexp.escape(str.to_s)
13:   end

Like respond_to? but returns the result of the call if it does indeed respond.

  class X
    def f; "f"; end
  end

  x = X.new
  x.respond(:f)  #=> "f"
  x.respond(:g)  #=> nil

CREDIT: Trans

[Source]

    # File lib/core/facets/kernel/respond.rb, line 16
16:   def respond(sym, *args)
17:     return nil if not respond_to?(sym)
18:     send(sym, *args)
19:   end
respond_with_value(sym, *args)

Alias for respond

A Ruby-ized realization of the K combinator.

  returning Book.new do |book|
    book.title = "Imperium"
    book.author = "Ulick Varange"
  end

Technically, returning probably should force the return of the stated object irregardless of any return statements that might appear within it‘s block. This might differentiate returning from with, however it also would require implementation in Ruby itself.

CREDIT: Mikael Brockman

[Source]

    # File lib/core/facets/kernel/returning.rb, line 18
18:   def returning(obj=self) #:yield:
19:     yield obj
20:     obj
21:   end

Call parent class/module methods once bound to self.

TODO: Does this have the proper scope for send?

[Source]

    # File lib/core/facets/kernel/as.rb, line 36
36:   def send_as(ancestor, sym, *args, &blk)
37:     ancestor.instance_method(sym).bind(self).call(*args,&blk)
38:   end

Set setter methods using a another object.

  class X
    attr_accessor :a, :b
    def initialize( a, b )
       @a,@b = a,b
    end
  end

  obj1 = X.new( 1, 2 )
  obj2 = X.new

  obj2.set_from(obj1)

  obj2.a  #=> 1
  obj2.b  #=> 2

TODO: populate_from(obj) ?

[Source]

    # File lib/core/facets/kernel/populate.rb, line 54
54:   def set_from(obj, *fields)
55:     unless fields.empty?
56:       fields.each do |k|
57:         send( "#{k}=", obj.send("#{k}") )  #if self.respond_to?("#{k}=") && obj.respond_to?("#{k}")
58:       end
59:     else
60:       setters = methods.collect { |m| m =~ /=$/ }
61:       setters.each do |setter|
62:         getter = setter.chomp('=')
63:         if obj.respond_to?(getter)
64:           send( setter, obj.send(getter) )
65:           fields < getter
66:         end
67:       end
68:     end
69:     fields
70:   end

[Source]

    # File lib/core/facets/kernel/silence.rb, line 27
27:   def silence_stderr #:yeild:
28:     silence_stream(STDERR) { yield }
29:   end

[Source]

    # File lib/core/facets/kernel/silence.rb, line 32
32:   def silence_stdout #:yeild:
33:     silence_stream(STDOUT) { yield }
34:   end

Silences any stream for the duration of the block.

  silence_stream(STDOUT) do
    puts 'This will never be seen'
  end

  puts 'But this will'

CREDIT: David Heinemeier Hansson

[Source]

    # File lib/core/facets/kernel/silence.rb, line 13
13:   def silence_stream(*streams) #:yeild:
14:     on_hold = streams.collect{ |stream| stream.dup }
15:     streams.each do |stream|
16:       stream.reopen(RUBY_PLATFORM =~ /mswin/ ? 'NUL:' : '/dev/null')
17:       stream.sync = true
18:     end
19:     yield
20:   ensure
21:     streams.each_with_index do |stream, i|
22:       stream.reopen(on_hold[i])
23:     end
24:   end

Sets $VERBOSE to nil for the duration of the block and back to its original value afterwards.

  silence_warnings do
    value = noisy_call # no warning voiced
  end

  noisy_call  # no warning is voiced

CREDIT: David Heinemeier Hansson

[Source]

    # File lib/core/facets/kernel/silence.rb, line 55
55:   def silence_warnings
56:     old_verbose, $VERBOSE = $VERBOSE, nil
57:     yield
58:   ensure
59:     $VERBOSE = old_verbose
60:   end

Just like silence_stream, but will default to STDOUT, STDERR if no streams are given.

[Source]

    # File lib/core/facets/kernel/silence.rb, line 39
39:   def silently(*streams) #:yeild:
40:     streams = [STDOUT, STDERR] if streams.empty?
41:     silence_stream(*streams){ yield }
42:   end
singleton(&block)

Alias for singleton_class

Easy access to an object‘s "special" class,

One day these names must be reconciled!

[Source]

    # File lib/core/facets/kernel/singleton_class.rb, line 7
 7:   def singleton_class(&block)
 8:     if block_given?
 9:       (class << self; self; end).class_eval(&block)
10:     else
11:       (class << self; self; end)
12:     end
13:   end

[Source]

   # File lib/core/facets/kernel/source_location.rb, line 5
5:     def source_location
6:       file, line, meth = *caller(1).first.split(':')
7:       return file, line
8:     end

Like super but skips to a specific ancestor module or class.

  class A
    def x ; 1 ; end
  end

  class B < A
    def x ; 2 ; end
  end

  class C < B
    def x ; super_as(A) ; end
  end

  C.new.x  #=> 1

[Source]

    # File lib/core/facets/kernel/as.rb, line 73
73:   def super_as(klass=self.class.superclass, *args, &blk)
74:     unless self.class.ancestors.include?(klass)
75:       raise ArgumentError
76:     end
77:     called = /\`([^\']+)\'/.match(caller(1).first)[1].to_sym
78:     klass.instance_method(called).bind(self).call(*args,&blk)
79:   end

Returns method of a parent class bound to self.

[Source]

    # File lib/core/facets/kernel/as.rb, line 50
50:   def super_method(klass, meth)
51:     unless self.class.ancestors.include?(klass)
52:       raise ArgumentError, "Not an ancestor for super_method-- #{klass}"
53:     end
54:     klass.instance_method(meth).bind(self)
55:   end

The tap K-Combinator. This yields self -and- returns self.

Note, Ruby 1.9+ does not appear to support the zero arity instance_eval option.

[Source]

    # File lib/core/facets/kernel/tap.rb, line 10
10:     def tap(&b)
11:       if block_given?
12:         b.arity == 1 ? yield(self) : instance_eval(&b)
13:       end
14:       self
15:     end

Boolean conversion for not being nil or false. Other classes may redefine this to suite the particular need.

  "abc".to_b   #=> true
  true.to_b    #=> true
  false.to_b   #=> false
  nil.to_b     #=> false

[Source]

    # File lib/core/facets/boolean.rb, line 94
94:   def to_b
95:     self ? true : false
96:   end

Returns true is an object is class TrueClass, otherwise false.

  true.true?   #=> true
  false.true?  #=> false
  nil.true?    #=> false

[Source]

     # File lib/core/facets/boolean.rb, line 105
105:   def true?
106:     (true == self)
107:   end

Try a method.

  @person ? @person.name : nil

vs

  @person.try(:name)

CREDIT: Chris Wanstrath

[Source]

    # File lib/core/facets/kernel/try.rb, line 12
12:   def try(method, default=nil)
13:     if respond_to? method
14:       send method
15:     else
16:       default
17:     end
18:   end

Tests to see if something has value. An object is considered to have value if it is not nil? and if it responds to empty?, is not empty.

  nil.val?     #=> false
  [].val?      #=> false
  10.val?      #=> true
  [nil].val?   #=> true

[Source]

    # File lib/core/facets/kernel/val.rb, line 12
12:   def val?
13:     return false if nil?
14:     return false if empty? if respond_to?(:empty?)
15:     true
16:   end

Like returning but exectures the block via instance_eval.

  def foo
    with values = [] do
      self << 'bar'
      self << 'baz'
    end
  end

  foo # => ['bar', 'baz']

[Source]

    # File lib/core/facets/kernel/with.rb, line 15
15:   def with(obj=self, &block)
16:     obj.instance_eval(&block)
17:   end

[Validate]