Module: Kernel

Defined in:
lib/merb-core/core_ext/kernel.rb,
lib/merb-core/test/test_ext/rspec.rb

Instance Method Summary collapse

Instance Method Details

#__caller_info__(i = 1) ⇒ Array[Array]

:api: private

Examples:

__caller_info__(1)
  # => ['/usr/lib/ruby/1.8/irb/workspace.rb', '52', 'irb_binding']

Parameters:

  • i (Fixnum) (defaults to: 1) —

    The caller number. Defaults to 1.

Returns:

  • (Array[Array]) —

    The file, line and method of the caller.



333
334
335
 
# File 'lib/merb-core/core_ext/kernel.rb', line 333

def __caller_info__(i = 1)
  file, line, meth = caller[i].scan(/(.*?):(\d+):in `(.*?)'/).first
end

#__caller_lines__(file, line, size = 4) ⇒ Array[Array]

:api: private

Examples:

__caller_lines__('/usr/lib/ruby/1.8/debug.rb', 122, 2) # =>
  [
    [ 120, "  def check_suspend",                               false ],
    [ 121, "    return if Thread.critical",                     false ],
    [ 122, "    while (Thread.critical = true; @suspend_next)", true  ],
    [ 123, "      DEBUGGER__.waiting.push Thread.current",      false ],
    [ 124, "      @suspend_next = false",                       false ]
  ]

Parameters:

  • file (String) —

    The file to read.

  • line (Fixnum) —

    The line number to look for.

  • size (Fixnum) (defaults to: 4) —

    Number of lines to include above and below the the line to look for. Defaults to 4.

Returns:

  • (Array[Array]) —

    Triplets containing the line number, the line and whether this was the searched line.



358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/merb-core/core_ext/kernel.rb', line 358

def __caller_lines__(file, line, size = 4)
  line = line.to_i
  if file =~ /\(erubis\)/
    yield :error, "Template Error! Problem while rendering", false
  elsif !File.file?(file) || !File.readable?(file)
    yield :error, "File `#{file}' not available", false
  else
    lines = File.read(file).split("\n")
    first_line = (f = line - size - 1) < 0 ? 0 : f
    
    if first_line.zero?
      new_size = line - 1
      lines = lines[first_line, size + new_size + 1]
    else
      new_size = nil
      lines = lines[first_line, size * 2 + 1]
    end

    lines && lines.each_with_index do |str, index|
      line_n = index + line
      line_n = (new_size.nil?) ? line_n - size : line_n - new_size
      yield line_n, str.chomp
    end
  end
end

#__profile__(name, min = 1, iter = 100) ⇒ String

Note:

Requires ruby-prof (sudo gem install ruby-prof)

Takes a block, profiles the results of running the block specified number of times and generates HTML report.

:api: private

Examples:

__profile__("MyProfile", 5, 30) do
  rand(10)**rand(10)
  puts "Profile run"
end

Assuming that the total time taken for #puts calls was less than 5% of the
total time to run, #puts won't appear in the profile report.
The code block will be run 30 times in the example above.

Parameters:

  • name (#to_s) —

    The file name. The result will be written out to Merb.root/“log/#name.html”.

  • min (Fixnum) (defaults to: 1) —

    Minimum percentage of the total time a method must take for it to be included in the result. Defaults to 1.

Returns:

  • (String) —

    The result of the profiling.



411
412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/merb-core/core_ext/kernel.rb', line 411

def __profile__(name, min=1, iter=100)
  require 'ruby-prof' unless defined?(RubyProf)
  return_result = ''
  result = RubyProf.profile do
    iter.times{return_result = yield}
  end
  printer = RubyProf::GraphHtmlPrinter.new(result)
  path = File.join(Merb.root, 'log', "#{name}.html")
  File.open(path, 'w') do |file|
    printer.print(file, {:min_percent => min,
                    :print_file => true})
  end
  return_result
end

#debugger ⇒ Object

Define debugger method so that code even works if debugger was not requested. Drops a note to the logs that Debugger was not available.



462
463
464
465
466
 
# File 'lib/merb-core/core_ext/kernel.rb', line 462

def debugger
  Merb.logger.info! "\n***** Debugger requested, but was not " +
    "available: Start server with --debugger " +
    "to enable *****\n"
end

#dependencies(*args) ⇒ Object

Loads both gem and library dependencies that are passed in as arguments. Execution is deferred to the Merb::BootLoader::Dependencies.run during bootup.

Parameters

*args<String, Hash, Array> The dependencies to load.

Returns

Array[(Gem::Dependency, Array)]

Gem::Dependencies for the

dependencies specified in args.

:api: public



176
177
178
179
180
181
182
183
184
 
# File 'lib/merb-core/core_ext/kernel.rb', line 176

def dependencies(*args)
  args.map do |arg|
    case arg
    when String then dependency(arg)
    when Hash   then arg.map { |r,v| dependency(r, v) }
    when Array  then arg.map { |r|   dependency(r)    }
    end
  end
end

#dependency(name, *opts, &blk) ⇒ Object

Loads the given string as a gem. Execution is deferred until after the logger has been instantiated and the framework directory structure is defined.

If that has already happened, the gem will be activated immediately, but it will still be registered.

Parameters

name<String> The name of the gem to load. *ver<Gem::Requirement, Gem::Version, Array, #to_str>

Version requirements to be passed to Gem::Dependency.new.
If the last argument is a Hash, extract the :immediate option,
forcing a dependency to load immediately.

Options

:immediate when true, gem is loaded immediately even if framework is not yet ready. :require_as file name to require for this gem.

See examples below.

Notes

If block is given, it is called after require is called. If you use a block to require multiple files, require first using :require_as option and the rest in the block.

Examples

Usage scenario is typically one of the following:

  1. Gem name and loaded file names are the same (ex.: amqp gem uses amqp.rb). In this case no extra options needed.

dependency “amqp”

  1. Gem name is different from the file needs to be required (ex.: ParseTree gem uses parse_tree.rb as main file).

dependency “ParseTree”, :require_as => “parse_tree”

  1. You need to require a number of files from the library explicitly (ex.: cherry pick features from xmpp4r). Pass an array to :require_as.

dependency “xmpp4r”, :require_as => %w(xmpp4r/client xmpp4r/sasl xmpp4r/vcard)

  1. You need to require a specific version of the gem.

dependency “RedCloth”, “3.0.4”

  1. You want to load dependency as soon as the method is called.

dependency “syslog”, :immediate => true

  1. You need to execute some arbitraty code after dependency is loaded:

dependency “ruby-growl” do

g = Growl.new "localhost", "ruby-growl",
           ["ruby-growl Notification"]
g.notify "ruby-growl Notification", "Ruby-Growl is set up",
      "Ruby-Growl is set up"

end

When specifying a gem version to use, you can use the same syntax RubyGems support, for instance, >= 3.0.2 or >~ 1.2.

See rubygems.org/read/chapter/16 for a complete reference.

Returns

Gem::Dependency

The dependency information.

:api: public



111
112
113
114
115
116
117
118
 
# File 'lib/merb-core/core_ext/kernel.rb', line 111

def dependency(name, *opts, &blk)
  immediate = opts.last.delete(:immediate) if opts.last.is_a?(Hash)
  if immediate || Merb::BootLoader.finished?(Merb::BootLoader::Dependencies)
    load_dependency(name, caller, *opts, &blk)
  else
    track_dependency(name, caller, *opts, &blk)
  end
end

#enforce!(opts = {}) ⇒ Object

Checks that the given objects quack like the given conditions.

:api: public

Parameters:

  • opts (Hash) (defaults to: {}) —

    Conditions to enforce. Each key will receive a quacks_like? call with the value (see Object#quacks_like? for details).

Raises:

  • (ArgumentError) —

    An object failed to quack like a condition.



452
453
454
455
456
 
# File 'lib/merb-core/core_ext/kernel.rb', line 452

def enforce!(opts = {})
  opts.each do |k,v|
    raise ArgumentError, "#{k.inspect} doesn't quack like #{v.inspect}" unless k.quacks_like?(v)
  end
end

#extract_options_from_args!(args) ⇒ Object

Extracts an options hash if it is the last item in the args array. Used internally in methods that take *args.

:api: public

Examples:

def render(*args,&blk)
  opts = extract_options_from_args!(args) || {}
  # [...]
end

Parameters:

  • args (Array) —

    The arguments to extract the hash from.



438
439
440
 
# File 'lib/merb-core/core_ext/kernel.rb', line 438

def extract_options_from_args!(args)
  args.pop if (args.last.instance_of?(Hash) || args.last.instance_of?(Mash))
end

#given(*args, &example_group_block) ⇒ Object 



3
4
5
6
7
8
9
10
11
12
13
14
 
# File 'lib/merb-core/test/test_ext/rspec.rb', line 3

def given(*args, &example_group_block)
  args << {} unless Hash === args.last
  params = args.last
  
  params[:shared] = true
  
  describe(*args) do
    prepend_before(:each) do
      self.instance_eval(&example_group_block)
    end
  end
end

#load_dependencies(*args) ⇒ Object

Note:

Each argument can be:

String

Single dependency.

Hash

Multiple dependencies where the keys are names and the values versions.

Array

Multiple string dependencies.

Loads both gem and library dependencies that are passed in as arguments.

:api: private

Examples:

dependencies “RedCloth” # Loads the the RedCloth gem

dependencies “RedCloth”, “merb_helpers” # Loads RedCloth and merb_helpers

dependencies “RedCloth” => “3.0” # Loads RedCloth 3.0

Parameters:

  • *args (String, Hash, Array) —

    The dependencies to load.



202
203
204
205
206
207
208
209
210
 
# File 'lib/merb-core/core_ext/kernel.rb', line 202

def load_dependencies(*args)
  args.map do |arg|
    case arg
    when String then load_dependency(arg)
    when Hash   then arg.map { |r,v| load_dependency(r, v) }
    when Array  then arg.map { |r|   load_dependency(r)    }
    end
  end
end

#load_dependency(name, clr, *ver, &blk) ⇒ Gem::Dependency

Note:

If the gem cannot be found, the method will attempt to require the string as a library.

Loads the given string as a gem.

This new version tries to load the file via ROOT/gems first before moving off to the system gems (so if you have a lower version of a gem in ROOT/gems, it’ll still get loaded).

:api: private

Parameters:

  • name (String, Gem::Dependency) —

    The name or dependency object of the gem to load.

  • *ver (Gem::Requirement, Gem::Version, Array, #to_str) —

    Version requirements to be passed to Gem.activate.

Returns:



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/merb-core/core_ext/kernel.rb', line 138

def load_dependency(name, clr, *ver, &blk)
  begin
    dep = name.is_a?(Gem::Dependency) ? name : track_dependency(name, clr, *ver, &blk)
    return unless dep.require_as
    Gem.activate(dep)
  rescue Gem::LoadError => e
    e.set_backtrace dep.original_caller
    Merb.fatal! "The gem #{name}, #{ver.inspect} was not found", e
  end

  begin
    require dep.require_as
  rescue LoadError => e
    e.set_backtrace dep.original_caller
    Merb.fatal! "The file #{dep.require_as} was not found", e
  end

  if block = dep.require_block
    # reset the require block so it doesn't get called a second time
    dep.require_block = nil
    block.call
  end

  Merb.logger.verbose!("loading gem '#{dep.name}' ...")
  return dep # ensure needs explicit return
end

#rescue_require(library, message = nil) ⇒ Object

Deprecated.

Does a basic require, and prints a message if an error occurs.

:api: private

Parameters:

  • library (to_s) —

    The library to attempt to include.

  • message (String) (defaults to: nil) —

    The error to add to the log upon failure. Defaults to nil.



219
220
221
222
223
224
225
 
# File 'lib/merb-core/core_ext/kernel.rb', line 219

def rescue_require(library, message = nil)
  Merb.logger.warn("Deprecation warning: rescue_require is deprecated")
  sleep 2.0
  require library
rescue LoadError, RuntimeError
  Merb.logger.error!(message) if message
end

#track_dependency(name, clr, *ver, &blk) ⇒ Gem::Dependency

Keep track of all required dependencies.

:api: private

Parameters:

  • name (String) —

    The name of the gem to load.

  • *ver (Gem::Requirement, Gem::Version, Array, #to_str) —

    Version requirements to be passed to Gem::Dependency.new.

Returns:



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/merb-core/core_ext/kernel.rb', line 21

def track_dependency(name, clr, *ver, &blk)
  options = ver.last.is_a?(Hash) ? ver.pop : {}
  new_dep = Gem::Dependency.new(name, ver.empty? ? nil : ver)
  new_dep.require_block = blk
  new_dep.require_as = options.key?(:require_as) ? options[:require_as] : name
  new_dep.original_caller = clr
  
  deps = Merb::BootLoader::Dependencies.dependencies

  idx = deps.each_with_index {|d,i| break i if d.name == new_dep.name}

  idx = idx.is_a?(Array) ? deps.size + 1 : idx
  deps.delete_at(idx)
  deps.insert(idx - 1, new_dep)

  new_dep
end

#use_orm(orm, &blk) ⇒ Object

Used in Merb.root/config/init.rb to tell Merb which ORM (Object Relational Mapper) you wish to use. Currently Merb has plugins to support ActiveRecord, DataMapper, and Sequel.

Parameters

orm<Symbol>

The ORM to use.

Returns

nil

Example

use_orm :datamapper

# This will use the DataMapper generator for your ORM
$ merb-gen model ActivityEvent

Notes

If for some reason this is called more than once, latter
call takes over other.

:api: public



248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/merb-core/core_ext/kernel.rb', line 248

def use_orm(orm, &blk)
  begin
    Merb.orm = orm
    orm_plugin = "merb_#{orm}"
    Kernel.dependency(orm_plugin, &blk)
  rescue LoadError => e
    Merb.logger.warn!("The #{orm_plugin} gem was not found.  You may need to install it.")
    raise e
  end
  nil
end

#use_template_engine(template_engine, &blk) ⇒ Object

Used in Merb.root/config/init.rb to tell Merb which template engine to prefer.

Parameters

template_engine<Symbol>

The template engine to use.

Returns

nil

Example

use_template_engine :haml

# This will now use haml templates in generators where available.
$ merb-gen resource_controller Project

:api: public



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/merb-core/core_ext/kernel.rb', line 305

def use_template_engine(template_engine, &blk)
  Merb.template_engine = template_engine

  if template_engine != :erb
    if template_engine.in?(:haml, :builder)
      template_engine_plugin = "merb-#{template_engine}"
    else
      template_engine_plugin = "merb_#{template_engine}"
    end
    Kernel.dependency(template_engine_plugin, &blk)
  end
  
  nil
rescue LoadError => e
  Merb.logger.warn!("The #{template_engine_plugin} gem was not found.  You may need to install it.")
  raise e
end

#use_test(*args) ⇒ Object 



284
285
286
 
# File 'lib/merb-core/core_ext/kernel.rb', line 284

def use_test(*args)
  use_testing_framework(*args)
end

#use_testing_framework(test_framework, *test_dependencies) ⇒ Object

Used in Merb.root/config/init.rb to tell Merb which testing framework to use. Currently Merb has plugins to support RSpec and Test::Unit.

Parameters

test_framework<Symbol>

The test framework to use. Currently only supports :rspec and :test_unit.

Returns

nil

Example

use_test :rspec

# This will now use the RSpec generator for tests
$ merb-gen model ActivityEvent

:api: public



277
278
279
280
281
282
 
# File 'lib/merb-core/core_ext/kernel.rb', line 277

def use_testing_framework(test_framework, *test_dependencies)
  Merb.test_framework = test_framework
  
  Kernel.dependencies test_dependencies if Merb.env == "test" || Merb.env.nil?
  nil
end