Requiring files

The require statement is executed at runtime (there is no compile-time!) and uses the global variable $: to decide where to look for the file. You can modify or inspect $: if you discover that it can't find the file you're trying to include.

Caveat: require will include the same file again if you spell the path differently

Workaround: Use File.expand_path

require File.expand_path(File.dirname(__FILE__) + "/../config/environment")

Caveat: the starting file is not counted as already required

So if you did something like this, you could end up stuck in an infinite loop:

#starting_file.rb
require "a.rb"

#a.rb
require "starting_file.rb"

Then run -- don't require, just run it from the command line -- starting_file.rb
> ruby starting_file.rb

Granted, you probably shouldn't have circular dependencies like that, but if you do (by accident or design), I think it should be smarter than to get stuck in an infinite loop and overflow the stack! I would consider this a bug.

require_local

I'm sure glad the folks at http://facets.rubyforge.org/ wrote this little extension, because I get sick of always doing requires like this:

require File.dirname(__FILE__) + "/something_in_the_same_directory"

How verbose and ugly. Here's the better way that you've been looking for:

require "rubygems"
require 'facets/core/kernel/require_local'
require_local "something_in_the_same_directory"

http://extensions.rubyforge.org/ has a similar method: require_relative

Why using require_local is more reliable than relying on the $LOAD_PATH and the "." directory

Example:

Even something as innocent-looking as this line at the top of a test can spell trouble:

require 'test/test_helper'

It causes a problem when you try to execute the test script from a directory other than the one the developer anticipated.

active_record_test.rb:2:in `require': no such file to load -- test/test_helper (LoadError)

That kind of brittleness, I hope you will agree, ought to be avoided.

Case in point: http://activescaffold.googlecode.com/svn/tags/current/test/extensions/active_record_test.rb

p $LOAD_PATH  # Added by Tyler
require 'test/test_helper'

If we run it from the root of the plugin directory, the test works just fine!

~/code/plugins/activescaffold > ruby test/extensions/active_record_test.rb
["/usr/lib/ruby/site_ruby/1.8", "/usr/lib/ruby/site_ruby/1.8/i386-linux", "/usr/lib/ruby/site_ruby", "/usr/lib/site_ruby/1.8", "/usr/lib/site_ruby/1.8/i386-linux", "/usr/lib/site_ruby", "/usr/lib/ruby/1.8", "/usr/lib/ruby/1.8/i386-linux", "."]
Loaded suite test/extensions/active_record_test
...

You can see that it had no trouble finding the file 'test/test_helper', because the $LOAD_PATH contains the path ".", which in my case was ~/code/plugins/activescaffold.

But I for one am used to running tests directly from the directory that contains the test. What happens if I try to run the test from within the test/extensions directory?

~/code/plugins/activescaffold/test/extensions > ruby active_record_test.rb
["/usr/lib/ruby/site_ruby/1.8", "/usr/lib/ruby/site_ruby/1.8/i386-linux", "/usr/lib/ruby/site_ruby", "/usr/lib/site_ruby/1.8", "/usr/lib/site_ruby/1.8/i386-linux", "/usr/lib/site_ruby", "/usr/lib/ruby/1.8", "/usr/lib/ruby/1.8/i386-linux", "."]
active_record_test.rb:2:in `require': no such file to load -- test/test_helper (LoadError)
...

Uh oh. You will notice that even though the value of the $LOAD_PATH variable is identical, it wasn't able to find 'test/test_helper' due to the fact that "." no longer refers to ~/code/plugins/activescaffold but now refers to ~/code/plugins/activescaffold/test/extensions! So even though it tried looking for './test/test_helper', that ended up causing it to search for ~/code/plugins/activescaffold/test/extensions/test/test_helper, which is obviously not a valid path.

The moral of the story is that we shouldn't make assumptions about:

• what's been added to $LOAD_PATH by this point (not demonstrated, but still true)
• what the current working directory (= "." = Dir.getwd) is

Instead of doing this:

require 'test/test_helper'

, consider doing this:

require 'facets/core/kernel/require_local'
require_local '../test_helper'

Or, if for some reason you really want to use $LOAD_PATH, then you should rely on an entry in $LOAD_PATH whose meaning is fixed, not one which changes depending on which directory you are in at the moment:

$LOAD_PATH << File.join(File.dirname(__FILE__), '..', '..')
require 'test/test_helper'

(This will add a path such as "/home/tyler/code/plugins/activescaffold/test/extensions/../.." onto the $LOAD_PATH.)

Then you can be 100% confident that the require 'test/test_helper' will succeed no matter which directory you run the script from.

Load path/include path

$: and $LOAD_PATH are equivalent

Add a path to it like this: $LOAD_PATH << 'my/path'

How to require a file if it exists, but otherwise silently continue

path=File.expand_path(File.dirname(__FILE__) + "/../../../../vendor/plugins/shared/lib/test_helper.rb"); require path if FileTest.exists?(path)

Or could we do that more cleanly with a begin/rescue block ?

How to require all the files in a certain directory

The quick, no-dependency-way:

Dir[File.dirname(__FILE__) + '/tasks/*.rake'].each {|f| load f}

The slightly prettier way:

(using qualitysmith_extensions)

require_all File.dirname(__FILE__) + '/tasks/*.rake'

Caveat: require only works with files ending in .rb!

I knew it worked to omit the ".rb" from the require command...

Either of these work:

require 'my_file'  # finds my_file.rb
require 'my_file.rb'  # finds my_file.rb

What I didn't know was that you can't use require to load files that don't end in .rb! For example, if you have a file bin/my_command (not my_command.rb), then this will fail:

require 'my_command'

This, however, works (but inherits any problems that load comes with, such as possibly doubly loading a file):

load 'my_command'

[Gems (category)]

The file gem_b/the_name.rb, if it exists, may be loaded instead of the the_name/the_name.rb file (from the the_name gem)

In other words, if you simply do a require 'gem_name' in your code and expect it to load that file (gem_name.rb) from the gem_name gem, you may be in for a surprise if there is another gem out there that happens to have a file by the same name and happens to be in a more preferred position in the load path.

Here's a real-life example that happened to me, when I was trying to do require 'ruby2ruby'...

Initial symptoms:

> sudo gem install ruby2ruby
> irb
irb -> require 'ruby2ruby'
    => true

irb -> def a(&block); block.to_ruby; end
    => nil

irb -> a { foo() }
NoMethodError: undefined method `to_ruby' for #<Proc:0xb7c80bd8@(irb):3>
        from (irb):2:in `a'
        from (irb):3

What?? The documentation for ruby2ruby suggests that the method `to_ruby' is defined for objects of class Proc!

Further investigation:

> gemwhich ruby2ruby
/usr/lib/ruby/gems/1.8/gems/ZenHacks-1.0.1/lib/ruby2ruby.rb

Oh.

After putting appropriate debug output code in both of:

• /usr/lib/ruby/gems/1.8/gems/ZenHacks-1.0.1/lib/ruby2ruby.rb
• /usr/lib/ruby/gems/1.8/gems/ruby2ruby-1.1.6/lib/ruby2ruby.rb

> irb
irb -> require 'ruby2ruby'
Loaded ZenHacks gem version
    => true

There are 2 solutions to this problem:

The least-destructive / easiest way to get around this is to simply activate the gem you want to include the file from before you do the require...

> irb
irb -> gem 'ruby2ruby'
    => true

irb -> require 'ruby2ruby'
Loaded ruby2ruby gem version
    => true

The other solution is to simply move the file you don't want to be loaded out of the way (or simply remove it).

> sudo mv /usr/lib/ruby/gems/1.8/gems/ZenHacks-1.0.1/lib/ruby2ruby.rb /usr/lib/ruby/gems/1.8/gems/ZenHacks-1.0.1/lib/ruby2ruby.rb2

> gemwhich ruby2ruby
/usr/lib/ruby/gems/1.8/gems/ruby2ruby-1.1.6/lib/ruby2ruby.rb

> irb
irb -> require 'ruby2ruby'
Loaded ruby2ruby gem version
    => true

This method:

• requires you to have write permissions to whatever directory the gems are stored in.
• will cause any code that uses ZenHacks and tries to use the version of ruby2ruby.rb found there, to fail (unless the ruby2ruby gem's ruby2ruby.rb is backwards compatible...).

That's what I ended up doing, because I think the version from the ruby2ruby gem is the official, most up-to-date version of that code; and more importantly, it's the only version that works the way I expect it to.

When I follow an example I find on the web that says you can just require 'ruby2ruby' and then do such-and-such, I want it to hold true for me too! The ZenHacks gem, as cool as it may be, has no business interfering with that behavior (the behavior that would have existed for require 'ruby2ruby' had the ZenHacks gem not been installed).

Now I can do this and it behaves as expected:

> irb
irb -> require 'ruby2ruby'
    => true

irb -> def a(&block); block.to_ruby; end
    => nil

irb -> a { foo() }
    => "proc {\n  foo()\n}"

Can you reference variables that haven't been initialized?

Yes, if they are global variables or instance variables.

No, if they are local variables or class variables.

def demonstrate
  puts $a
  puts @a
  puts a    # error!
  puts @@a  # error!
end
demonstrate

nil
nil
using_undefined_variables.rb:6:in `demonstrate': undefined local variable or method `a' for main:Object (NameError)
        from using_undefined_variables.rb:9

irb -> a
NameError: undefined local variable or method `a' for main:Object
        from (irb):1

irb -> @@a
NameError: uninitialized class variable @@a in Object
        from (irb):7

irb -> @a
    => nil

irb -> $a
    => nil

How do you check if a variable is defined?

Not like this:

irb -> defined?(:a)
    => "expression"

because that checks if the symbol

defined? is a very special method that doesn't act like other methods. The difference is that you can pass undefined local and class variables to defined? and you won't get an error!

defined? returns nil if the variable (or whatever?) is not defined and returns what kind of "thing" it is if it is defined...

irb -> defined?(a)
    => nil
irb -> defined?(@a)
    => nil
irb -> defined?(@@a)
    => nil
irb -> defined?($a)
    => nil


irb -> a = 'a local variable'
    => "a local variable"
irb -> @a = 'an instance variable'
    => "an instance variable"
irb -> @@a = 'a class  variable'
    => "a class  variable"
irb -> $a = 'a global variable'
    => "a global variable"

irb -> defined?(a)
    => "local-variable"
irb -> defined?(@a)
    => "instance-variable"
irb -> defined?(@@a)
    => "class variable"
irb -> defined?($a)
    => "global-variable"

How do you check if a constant is defined?

At first I thought you might use const_defined? ... but then I saw that you have to ask that of a specific module. What if you just define a constant at the global scope (not in a module)? Then which module would you to check if that constant is defined? I couldn't get that to work at all.

Instead, use the language-built-in (I couldn't find it in the RDoc for Kernel/Module/etc.) check defined? . It will be nil if it's not defined, non-nil if it is defined!

Foo = true
puts Module.const_defined?(:Foo)
# => false
puts defined? Foo
# => constant

What's the difference between a constant and a variable?

Besides that constants begin with a capital letter and variables do not...?

Does it let you change constants? (Yes)

Yes, but it will raise a warning:

irb -> PI
NameError: uninitialized constant PI
        from (irb):1
irb -> PI=3
    => 3

irb -> PI=4
(irb):3: warning: already initialized constant PI
    => 4

irb -> PI
    => 4

However, you may not change a constant from a method apparently:

irb -> def foo; PI=4; end
SyntaxError: compile error
(irb):1: dynamic constant assignment
def foo; PI=4; end
            ^
        from (irb):1

However, this is Ruby, and like most restrictions in Ruby, you can get around this one:

irb -> def foo; self::class::const_set(:PI, 4); end
    => nil

irb -> foo
    => 4

irb -> PI
    => 4

Different scope: To whom do the constants actually belong?

They always belong to a class/module, it appears; you can't just have local constants like in the same way that you can have local variables.

irb -> MODEL_DIR="/path/to/models"
    => "/path/to/models"

irb -> Kernel::MODEL_DIR = "something else entirely"
    => "something else entirely"

irb -> MODEL_DIR
    => "/path/to/models"

irb -> Object::MODEL_DIR
    => "/path/to/models"

irb -> class Foo
irb(main):010:1> MODEL_DIR="Foo's MODEL_DIR"
irb(main):011:1> end
    => "Foo's MODEL_DIR"

irb -> MODEL_DIR
    => "/path/to/models"

irb -> Object::const_get(:MODEL_DIR)
    => "/path/to/models"

irb -> Foo::MODEL_DIR
    => "Foo's MODEL_DIR"

I would have to say that it looks like unless Ruby has some reason to think you want it elsewhere (f.e., you give an explicit scope, Foo::, or you're inside of a class), it will think you want the constant to be defined for the class object "Object".

Checking if a constant is defined

This could be useful, for example, if you want to conditionally mix in a module or something only if a class is available.

include CoolFeature if CoolFeatureModule.const_defined?(:CoolClass)

(not a good example, I know)

Caveat: Did you mean to have 2 variables reference the same object or two copies of the object?

I easily forget that variables and objects are different. A variable just points to an object. So you can have two variables referring to the same object ... even without meaning to! Really! Believe me!

Demonstration:

irb -> original = new = "hi there"; new.capitalize!; original + " => " + new
    => "Hi there => Hi there"

It may not be obvious unless you know Ruby, but original = new = "hi there" causes both original and new (two variables) to both point to the same object in memory. So changing the one variable will affect the other. See, they have the same object_id:

irb -> original == new
    => true
irb -> original.object_id == new.object_id
    => true
irb -> "#{original.object_id} == #{new.object_id}"
    => "-604147648 == -604147648"

The proper way to create independently modifiable copies of an object is with the dup (duplication) method, like so:

irb -> original = "hi there"; new = original.dup; new.capitalize!; original + " => " + new
    => "hi there => Hi there"

It's a little more verbose, but I don't know of a conciser way of doing it!

Observe how the objects have different object IDs:

irb -> original == new
    => false
irb -> original.object_id == new.object_id
    => false
irb -> "#{original.object_id} != #{new.object_id}"
    => "-604271038 != -604271048"

That's because they really are two separate objects!

Variable scope/accessibility

cattr_accessor|attr_accessor

mattr_accessor (for modules)

Instance (member) variables

From within a method, it's easy enough to access an instance variable. You just refer to it as @foo or whatever it's called.

Outside of the class, it's a little bit harder:

# Doesn't work:
irb -> a.@foo
SyntaxError: compile error
(irb):9: syntax error, unexpected tIVAR
        from (irb):9

# But you can access it this way:
irb -> a.instance_variable_get(:@foo)
    => []

Reminder: You should never access an instance variable like that (I only use it for debugging). Instead, create accessor methods for it, using attr_writer, attr_reader, or attr_accesor.

Class variables

People.send(:class_variable_set, :@@lifespan, 0.minute)

mod.class_variables will only report which class variable have been set (initialized)

irb -> class A; def self.hi; @@a = 1 end; end
    => nil

# You might expect it to list @@a, but it doesn't really treat it as a class_variable until the moment it is initialized
irb -> A.class_variables
    => []

irb -> A.hi
    => 1

irb -> A.class_variables
    => ["@@a"]

For reasons such as that, it's usually a good idea to initialize class variable in the class scope, even if you will later change them from within a method...

irb -> class B; @@b = nil; def self.hi; @@b = 1 end; end
    => nil

irb -> B.class_variables
    => ["@@b"]

Example of: Passing hash as if we had named parameters

Source: http://docs.rubyrake.org/read/chapter/4#pa

task :name => [:prereq1, :prereq2]

NOTE: Although this syntax looks a little funky, it is legal Ruby. We are constructing a hash where the key is :name and the value for that key is the list of prerequisites. It is equivalent to the following …

hash = Hash.new
hash[:name] = [:prereq1, :prereq2]
task(hash)

"returning": Tell it what you're returning in case you forget and accidentally return the result of a method call!

Part of ActiveSupport, but [Should be core Ruby (category)]

It also feels a little more concise and elegant and Rubyish...

(modified quote) (source: http://errtheblog.com/post/29)

def change_state(object_id, new_state)
  returning find(object_id) do |object|
    object.state = new_state
    object.save
  end
end

instead of:

def change_state(object_id, new_state)
  object = find(object_id)
  object.state = new_state
  object.save
  object
end

(/modified quote)

Because otherwise you might forget that Ruby automatically returns the result of the last line in the block and accidentally return object.save or something:

def change_state(object_id, new_state)
  object = find(object_id)
  object.state = new_state
  object.save
end

Another example:

def cd_rails_root
  returning(FileUtils.getwd) { FileUtils.cd(RAILS_ROOT) }
end

Silliness: alias and alias_method

I prefer to use alias_method rather than alias.

alias_method :orig_meth, :meth
def meth # override it...
alias_method :new_meth, :old_meth

The order of arguments is reversed for alias...stupidly.

[Caveat (category)]: Object#send invokes private methods

It totally bypasses any privacy restrictions that the author of that class may have put in. In other words, it lets you call methods that have been marked as "private".

It is arguably a [good thing (category)] that Ruby provides a way to call private methods -- for those times when you really need to -- but in general this should be considered a [bad practice (category)].

Sometimes, it can even lead to some unexpected behavior. For instance, when a private method by that name exists but a public method does not. Example:

This example is taken from a real-world problem we ran across with Rails. We (Lance/Jim) discovered some really strange behavior where it threw an error if we tried to invoke a method via send (which the plugin in question (ActiveScaffold) was probably doing, since it was probably just looping through a list of column names) but it worked fine if we invoked the method directly!

record.send(:task)
=> ArgumentError (0 for 1)

but:

record.task
=> "test"

Very unintuitive for these two methods of calling a method should have different behavior!

The reason the send(:task) was raising an ArgumentError in our particular case was because we were somehow requiring "rake" somewhere in our code (something we probably shouldn't have been doing), and Rake was mixing in some Rake-specific private methods into the Object class (something it probably shouldn't have been doing), among them task. This private method was defined by Rake to expect 1 argument.

We were only passing 0 arguments, however, because we expected task to be a normal old attribute reader method for our ActiveRecord model, and obviously you shouldn't have to pass any arguments just to ask a model what the current value of one of its attributes is.

However, due I believe to some performance optimizations done by the ActiveRecord developers, those methods are not even created until they are needed. In other words, the first time you call an attribute reader, the message is caught by method_missing, which then dynamically creates the reader methods for you.

So in our case, we just got unlucky with our timing. If we had already accessed one of the models attributes in the "normal" (non-send) way prior to this point in the code, then the public method would have already existed, the private task method would not have been called, and this code would have worked as designed.

(Should also be filed under / transcluded by: "Caveat: ActiveRecord attribute accessor methods aren't created until first accessed", "Ruby / Problems with creating methods at run-time")

Wouldn't it be nice, then, if there were a "send" method that would only send to public methods?

Fortunately, the Facets core library provides just that — in the form of object_send. It will invoke the public method provided as its first argument, or (if there isn't a matching method by that name) method_missing, or (if there is no method_missing), raise raise an error (not sure if I like that behavior -- shouldn't it just send method_missing, in case we want a parent class to handle it?).

Currently (1.8.51) implemented as:

  # File lib/facets/core/kernel/object_send.rb, line 9
  def object_send(name,*args,&blk)
    #instance_eval "self.#{name}(*args)"
    if respond_to?(name)
      send(name,*args,&blk)
    elsif respond_to?(:method_missing)
      method_missing(name,*args,&blk)
    else
      raise NoMethodError
    end
  end

Question: Why is that in Kernel and not in Object?

Really, Object#send should only send to public methods (by default)! It should only send to private methods if you specifically request it to consider private methods as candidates (perhaps via a :ignore_privacy => true) option.

We shouldn't have to use a custom-written method to get the public-only behavior.

Rescue statement modifier within method call

irb -> p(Dir.entries(d).grep(/erb/) rescue)
SyntaxError: compile error
(irb):7: syntax error, unexpected kRESCUE_MOD, expecting ')'
p(Dir.entries(d).grep(/erb/) rescue)
                                   ^
        from (irb):7

To get around this, you'll need to throw on one more set of parentheses:

irb -> p((Dir.entries(d).grep(/erb/) rescue []))
[]
    => nil

Multi-line comments

=begin
Your
comment
here
=end

Useful for commenting out a block of code.

You can also tell it what type of comment. The following special types are ones that I know of so far:

• =begin rdoc -- begins an RDoc block
• =begin test -- begins an inline test that will be read by Reap's test extraction tool

branching structures (if, case, ...) can be used inline in expressions even!

irb -> 'Is it true? ' + if false then 'yes' else 'no' end
    => "Is it true? no"

statement/expression "modifiers" (comes after expression)

the "if" expression modifier

This can apply to a single statement:

irb -> puts 'statement' if false
    => nil

or to a block (of any size):

irb -> begin; puts 'hi'; puts 'bye'; end if false
    => nil

irb -> begin; puts 'hi'; puts 'bye'; end if true
hi
bye
    => nil

You can also have the if clause apply to a section of code by enclosing in parentheses:

irb -> (puts 'First statement'; puts 'Second statement') if false
    => nil

irb -> puts 'First statement'; puts 'Second statement' if false
First statement
    => nil

Order of evaluation of statement modifiers

Example 0:

These don't work:

irb -> puts message if message = 'hi'
NameError: undefined local variable or method `message' for main:Object
        from (irb):1

FileUtils.rm(file) if File.exist?(file = '/path/to/file')

Example 1: This works:

        diff_output = Subversion.diff(external.container_dir)
        puts diff_output unless diff_output.blank?

but you can't (unfortunately) condense that into one statement. In other words, this doesn't work as desired:

        puts (diff_output = Subversion.diff(external.container_dir)) unless diff_output.blank?

See:

irb -> require 'rubygems'; require 'active_support'
irb -> puts (diff_output = "some long diff output") unless diff_output.blank?
    => nil

That's because when the Ruby parser hits "diff_output =", even though it doesn't evaluate it at that point, it still initializes diff_output to nil. Next, diff_output.blank? is evaluated and finds diff_output to still be nil. So the unless block evaluates to unless false and the block it is protecting (which actually sets the (diff_output = "some long diff output")) does not get evaluated. Kind of unintuitive and disappointing at times, but not too bad. We just have to write this as two lines instead of one in this case.

Example 2: validating arguments

Suppose you have a multiple-choice "option" named how and you want to validate that the caller gave it one of the valid options. If it's not one of the valid options, you want to print out a nice error message that lists what the valid options are. The setup code is:

    options = args.last.is_a?(Hash) ? args.last : {}
    how = options.delete(:how) || :capture

Now how would we validate the how option?

    raise ArgumentError.new(":how option must be one of #{valid_options.inspect}") unless (valid_options = [:capture, :exec, :popen]).include? how

That actually works, because the unless clause (which gets executed first) sets up the array for the "then" clause...

irb -> how = :vapidly
    => :vapidly
irb -> raise ArgumentError.new(":how option must be one of #{valid_options.inspect}") unless (valid_options = [:capture, :exec, :popen]).include? how
ArgumentError: :how option must be one of [:capture, :exec, :popen]
        from (irb):6
        from :0

irb -> how = :capture
    => :capture
irb -> raise ArgumentError.new(":how option must be one of #{valid_options.inspect}") unless (valid_options = [:capture, :exec, :popen]).include? how
    => nil

We could have also written it like this:

    unless (valid_options = [:capture, :exec, :popen]).include? how
      raise ArgumentError.new(":how option must be one of #{valid_options.inspect}")
    end

Example 3

Suppose you want to only print the results of some method call, but only if the results are not ""...

It feels like you should be able to do it with one line, like this...

puts output = obj.some_method() unless output == ""

but that doesn't work.

We're forced to break it into 2 lines.

output = obj.some_method()
puts output unless output == ""

In this case, if all you're worried about is getting blank lines when the method returns a blank line, you could use print instead.

print output = obj.some_method() unless output == ""

But that doesn't solve the more general problem. Which is that an if/unless statement modifier (that comes after the statement) can never check and respond to an input that exists only after running the statement to which the modifier applies. This is because the if/unless statement modifier is evaluated before the statement it is guarding.

It looks to me like the only way to do what I'm trying to do with a single statement is to use the "regular" old if/then/else statement inline in my puts statement.

irb -> unless (a = "") == "" then puts a else 'doing nothing' end
    => "doing nothing"

irb -> unless (a = "not an empty string") == "" then puts a else 'doing nothing' end
not an empty string
    => nil

So, applying that to my more specific example:

unless (output = obj.some_method()) == "" then puts output else end

Not as concise or readable as I'd hoped, but it does get the job done in one line.

"rescue" statement modifier / how to execute multiple statements as if they were one

Be sure you realize that only the statement immediately following the rescue belongs to the rescue clause (will only be executed if an exception is raised). Any statements after that will be executed unconditionally.

To demonstrate:

irb -> "Something that doesn't raise an exception." rescue p 'something'; p 'else'
"else"
    => nil

If you need to execute multiple statements as if they were one, just throw a begin/end around them! This would be the correct way to do what the above example was trying to do:

irb -> "Something that doesn't raise an exception." rescue begin; p 'something'; p 'else'; end
    => "Something that doesn't raise an exception."

irb -> raise "An exception"                         rescue begin; p 'something'; p 'else'; end
"something"
"else"
    => nil

||= (conditional initialization operator)

I love this operator. It lets you initialize a variable to a default only if the variable isn't already set.

My only complaint about it is that it doesn't work for booleans. (It also sometimes doesn't work how I'd like for hashes, arrays, as I'll explain in a bit.)

Ruby 101 for .NET developers: The strange ||= operator (http://www.softiesonrails.com/2007/2/6/ruby-101-for-net-developers-the-strange-OR-operator). Retrieved on 2007-03-29 14:44.

Sometimes in Ruby you'll come across some code that looks like this: stuff ||= [ ] or maybe stuff ||= { } What's going on here? First, if you're new to Ruby, you may not realize how the || operator really works, so let's digress for a minute and talk about that first. The || operator is a short-circuited logical OR operator. If I say a = "hello" b = a || "goodbye" What is the value of b? It will be "hello". Since a evaluated to something that's not nil and not false, it stopped right there (short circuited itself) and assigned be a reference to a. But suppose a was nil instead: a = nil b = a || "goodbye" Now, b will become "goodbye". Since a was nil, the OR operator continued to evaluate the next expression, which was "goodbye". So b becomes "goodbye". If you're with me so far, then you're already rounding third base. Now, you probably already know that this: a = a + 5 can be shortened to this: a += 5 right? In Ruby, this same idea gets applied to the OR operator. Instead of writing this: a = a || "baseball" This means, if a already has a value, then keep it; but it it's nil, then assign it to "baseball". But horrors, what a lot of typing! A good Ruby programmer would do this instead and save two whole keystrokes: a ||= "baseball" In other words, a will become "baseball" if it was nil (or false) before, otherwise it will just keep its original value.

[caveats (category)] Doesn't work for booleans

irb -> def foo(a) a ||= true; a end
    => nil

irb -> foo(false)
    => true

Sets a to true (the default value) even though a non-default value (false) was passed in! The consequences for not understanding this important point could be tragic! It's the difference between true and false.

Workaround:

irb -> def foo(a) a ||= true if a.nil?; a end
    => nil

irb -> foo(false)
    => false

More verbose, but it gives the (IMHO) desired behavior.

Better solution? Well, we can't just make up a new operator in Ruby, unfortunately, but we might be able to solve it with a new method...

irb -> class Object; def default(default) self = default if self.nil? end; end
SyntaxError: compile error
(irb):33: Can't change the value of self
class Object; def default(default) self = default if self.nil? end; end

Ohp! Never mind. I guess Ruby doesn't like that. I bet it woulda worked though...

irb -> class Object; def default(default) puts "Setting to default value of #{default}" if self.nil? end; end

irb -> foo(false)
    => nil

irb -> foo()
Setting to default value of true
    => nil

What if you want a [] variable to be treated as nil (uninitialized) value and to set it to a default if it is either nil or []?

irb -> a = []
    => []

irb -> (!a.empty?)
    => false

irb -> (!a.empty? || a)
    => []

irb -> !a.empty? || (a = ['default', 'array'])
    => ["default", "array"]

irb -> a
    => ["default", "array"]


irb -> a = []
    => []

irb -> a = ['default', 'array'] if a.empty?
    => ["default", "array"]

That works!

But it wouldn't work so well if a were nil.

irb -> a = nil
    => nil

irb -> !a.empty? || (a = ['default', 'array'])
NoMethodError: undefined method `empty?' for nil:NilClass
        from (irb):14

Unless we did this:

irb -> class NilClass; def empty?; true; end; end
    => nil

irb -> !a.empty? || (a = ['default', 'array'])
    => ["default", "array"]

or this:

irb -> a && !a.empty? || (a = ['default', 'array'])
    => ["default", "array"]

or this:

irb -> a = ['default', 'array'] if a && !a.empty?
    => ["default", "array"]

or this:

irb -> a = nil
irb -> a = ['default', 'array'] if a.nil? || (a && a.empty?)
    => ["default", "array"]

irb -> a = []
irb -> a = ['default', 'array'] if a.nil? || (a && a.empty?)
    => ["default", "array"]

How about the case where it is not nil or []?

irb -> a = ['existing', 'array']
    => ["existing", "array"]

irb -> a = ['default', 'array'] if a.nil? || (a && a.empty?)
    => nil

irb -> a
    => ["existing", "array"]

Cool, that works. Except that the assignment line returns nil, which may not be what we want. Maybe we'd rather the assignment line returned a ... ?

irb -> (a = ['default', 'array'] if a.empty? else a)
SyntaxError: compile error
(irb):10: syntax error, unexpected kELSE, expecting ')'
(a = ['default', 'array'] if a.empty? else a)
                                          ^

Once again assuming this...

irb -> class NilClass; def empty?; true; end; end
    => nil

Let's see if we can get the assignment line to return a.

irb -> a = []
    => []

irb -> ((a = ['default', 'array'] if a.empty?) || a).each {|e| puts e}
default
array
    => ["default", "array"]

Good, it used the default!

irb -> a = ['existing', 'array']
    => ["existing", "array"]

irb -> ((a = ['default', 'array'] if a.empty?) || a).each {|e| puts e}
existing
array
    => ["existing", "array"]

Good, it used the existing value of a (rather than overriding with a default)!

When would you want to do that? I don't know.

Here's the situation that originally motivated me to solve that problem: I wanted to use the value of ARGV (which I expected to be a list of directories), unless ARGV was empty ([]), in which case I just wanted by default to use the current directory (['.']). I didn't have any control of ARGV; it's always an array ([] if there are no args), so I couldn't just use ||=, because that only works if it is nil.

But then I realized that ARGV was a constant and I couldn't change its values by doing something like ||= anyway. This is what I ended up doing:

      ((['.'] if ARGV.empty?) || ARGV).each do |dir|
        ...
      end

and then changed to:

      (if ARGV.empty? then ['.'] else ARGV end).each do |dir|
        ...
      end

[caveats (category)] Can't do (var ||= "") += "string"

Why would I want to do that? So that I don't have to write it as two lines, of course! Compactness.

The problem, you see, is that you can't call + on nil variables (a default behavior of NilClass that I prefer to change)

irb -> string += 'some thing'
NoMethodError: undefined method `+' for nil:NilClass
        from (irb):1

I could always do this:

string ||= ""
string += "string"

But that's sort of a pain. I sort of wish I could do this:

irb -> (string ||= "") += 'some thing'
SyntaxError: compile error
(irb):2: syntax error, unexpected tOP_ASGN, expecting $end
(string ||= "") += 'some thing'
                  ^
        from (irb):2

The reason it doesn't like that, of course, is that the l-value of an assignment (which += is) must be a variable, not an expression. I sort of think it should be able to use the variable mentioned in the expression (string), but oh well.

This works, however:

irb -> string += 'this' if string ||= ''
    => "this"

irb -> string += ' works' if string ||= ''
    => "this works"

[Parallel assignment (category)]

See also: Pickaxe p. 340 (the rules), Pickaxe p. 90 (examples)

Why would you want to use it?

• it's concise!
• you can use it to swap variables (a, b = b, a)

lvalues, ... = *rvalue

"The rvalue is replaced with the elements of the array, with each element forming its own rvalue."

irb -> a, b, c = *[1, 2, 3];  "a=#{a}, b=#{b}, c=#{c}"
    => "a=1, b=2, c=3"

lvalues, ... = array

irb -> array = [1, 2, 3]
irb -> a, b, c = array;  "a=#{a}, b=#{b}, c=#{c}"
    => "a=1, b=2, c=3"

If there are more lvalues than rvalues...

... the excess will be assigned the value nil.

irb -> a, b, c = 1;  "a=#{a.inspect}, b=#{b.inspect}, c=#{c.inspect}"
    => "a=1, b=nil, c=nil"

If the last lvalue is prefixed with a *: a, ..., *catch_all = ...

(without the *)

irb -> a, b, catch_all = 1, 2, 3, 4, 5; "a=#{a}, b=#{b}, catch_all=#{catch_all.inspect}"
    => "a=1, b=2, catch_all=3"

but (with the *):

irb -> a, b, *catch_all = 1, 2, 3, 4, 5; "a=#{a}, b=#{b}, catch_all=#{catch_all.inspect}"
    => "a=1, b=2, catch_all=[3, 4, 5]"

It also works when there is only one lvalue and it is prefixed with a *.

irb -> *vars = 1, 2, 3; vars
    => [1, 2, 3]

More examples...

irb -> array = [3, 4, 5]

irb -> a, b, not_really_a_catch_all = 1, 2, array; "a=#{a}, b=#{b}, not_really_a_catch_all=#{not_really_a_catch_all.inspect}"
    => "a=1, b=2, not_really_a_catch_all=[3, 4, 5]"
# Simply assigns the value of array to not_really_a_catch_all

irb -> a, b, *catch_all = 1, 2, *array; "a=#{a}, b=#{b}, catch_all=#{catch_all.inspect}"
    => "a=1, b=2, catch_all=[3, 4, 5]"
# Has the same end result, but uses a catch-all and a splat (*array).

irb -> a, b, *catch_all = 1, 2, array; "a=#{a}, b=#{b}, catch_all=#{catch_all.inspect}"
    => "a=1, b=2, catch_all=[[3, 4, 5]]"
# Probably not what you want.

irb -> a, b, catch_all = 1, 2, *array; "a=#{a}, b=#{b}, catch_all=#{catch_all.inspect}"
    => "a=1, b=2, catch_all=3"
# The splat was too big to catch! The excess from the splat (4, 5) just ended up being ignored.

They are performed in parallel (effectively), so swapping is possible

irb -> a, b = 1, 2
    => [1, 2]

irb -> a, b = b, a;  "a=#{a}, b=#{b}"
    => "a=2, b=1"

But they are also performed in order, so if an rvalue has side-effects, it may affect the next rvalue

irb -> a, b, c  =  (x = 0), (x += 1), (x += 1)
    => [0, 1, 2]

irb -> x
    => 2

The return value of the multiple assignment is an array

irb -> return_val = (a, b, c = 1, 2, 3)
    => [1, 2, 3]

[Example of * operator with an Array (category)]

Either of these works:

irb -> a, b, c = *['something']*3
    => ["something", "something", "something"]

irb -> "a=#{a}, b=#{b}, c=#{c}"
    => "a=something, b=something, c=something"

irb -> a, b, c = ['something']*3
    => ["something", "something", "something"]

irb -> "a=#{a}, b=#{b}, c=#{c}"
    => "a=something, b=something, c=something"

[values, not references (category)]

This should be self-evident to the astute Rubyist, but I've forgotten it at least once so I'll just give this reminder for my own sake then.

irb -> a, b, c = 1, 2, 3
    => [1, 2, 3]

irb -> vars = [a, b, c]
    => [1, 2, 3]
# vars now contains a reference to a, b, and c, right? Wrong.

irb -> *vars = 4, 5, 6;  "a=#{a}, b=#{b}, c=#{c}"
    => "a=1, b=2, c=3"

irb -> vars
    => [4, 5, 6]

a, b, and c are not changed at all by this. Only vars (the actual lvalue) is changed.

Are variables references, pointers, or what?? / Do things get passed/returned by value or by reference?

This concept/question is actually very important for every serious Ruby developer to understand. I know it's sure gotten me very confused before.

The short version is [may not be 100% technically accurate, but conceptually it works to describe what's going on]:

• variables are really just pointers to objects
• most operations you do to a variable (var.operate!) actually end up changing the object to which it points
• variable assignment (var = ) is different: it points the variable to a different object; it does not modify the original object!

You can tell what object a variable "points to" by inspecting its object_id. Each distinct object has a unique object_id. It is possible for more than one variable to point to the same object (and thus have the same object_id).

If we were to compare Ruby with C++, Ruby's variables are a lot like by-reference in C++: you can't just change what they point to with as much freedom as you can with C++ pointers, but -- much like by-reference argument passing in C++ -- the variable you pass in to a method can be modified by the function. Likewise, if a method returns a variable, that variable can be modified by the caller. Don't you forget that.

{ Some examples using strings

These examples illustrate that method calls on a variable do not change the "object_id" of that variable. In other words, after calling these methods, the variable still points to the same object.

irb -> a = "a"; a.object_id
    => -604332868

irb -> a.replace("b"); a.object_id
    => -604332868

irb -> a.concat "b"; a.object_id
    => -604332868

irb -> a.upcase!; a.object_id
    => -604332868

See how the object_id of a was -604332868 in all cases?

Now here are some examples to illustrate that using = on a variable to do an assignment will usually cause the variable to point to a new/different object.

I said usually, because sometimes an assignment will not change the target of the variable, like when you assign a variable to itself, or pass the variable to a method that returns the object.

irb -> a = "a"; a.object_id
    => -604365948

irb -> a = a; a.object_id
    => -604365948

irb -> def return_arg(arg) arg end; a = return_arg(a); a.object_id
    => -604365948

But usually an assignment results in a new object being created. Observe:

irb -> a = "a"; a.object_id
    => -604212148
# That's what we start with.

irb -> a = "b"; a.object_id
    => -604251578
# That's really just a shorter way of saying:
irb -> a = String.new("b"); a.object_id
    => -604265298
# Each string literal actually constructs a new object, even if you *spell* the string exactly the same. Symbols do not have this behavior, which is partly what makes them so cool...

irb -> print "a".object_id, " ", "a".object_id
-604361848 -604361868    => nil    # (different objects)
irb -> print :"a".object_id, " ", :"a".object_id
164578 164578    => nil            # (same object...every time!)

irb -> a = "a" + ""; a.object_id
    => -604235568
# Even though the resulting string *looks* the same ("a") -- the string is still "spelled" the same before and after -- the + operator actually (unconditionally) results in a new object being constructed.

irb -> a += "b"; a.object_id
    => -604280198
# You might *think* that this would just add "b" to the end of the existing object (to which a points). It doesn't though; it creates a new object. Use a.concat("b") if you want it to *modify* a's current object rather than creating a new object.
# a += "b" is just short for this (and we've already observed that String#+ *always* creates a new String object):
irb -> a = a + "b"; a.object_id
    => -604318858

irb -> def return_arg(arg) arg + "" end; a = return_arg(a); a.object_id
    => -604228528

Did you see how every one of those operations showed a to have a different object_id? That's because each one of them actually created a new String object and associated the variable a with that new String object.

The docs [1] confirm what we have already observed about the + operator:

str + other_str => new_str Concatenation—Returns a new String containing other_str concatenated to str. "Hello from " + self.to_s #=> "Hello from main"

} Some examples using strings

Are variables passed/returned by value or reference?

You've already seen one example where they are both passed and returned by reference.

irb -> a = "a"; a.object_id
    => -604250678

irb -> def return_arg(arg) arg end; a = return_arg(a); a.object_id
    => -604250678

(the exact same object that is passed ends up being returned)

So I guess that answers your question, doesn't it. The rest of my examples will just further illustrate that, but the concept is really easy to remember: yes, everything is by reference [if I understand correctly].

So even though the following returns a different object than is passed in, the object that the caller gets back is the same object that existed when we called return from within the method.

irb -> def return_arg(arg) return arg + "" end; a = return_arg(a); a.object_id
    => -604347018

This can be illustrated even more clearly by putting a puts inside of the method...

irb -> def return_arg(arg)
         new_str = arg + ""; 
         puts new_str.object_id;
         new_str
       end;
       a = return_arg(a); a.object_id
-604280118
    => -604280118

[Caveats (category)] Attribute reader methods can actually be used to modify the object's instance variables

You may think your object's private data is safe just because you've provided an attr_reader and not an attr_writer. This is not necessarily the case, however, so you need to be careful!

In particular, an attr_reader> method will return the attribute (instance variable) by reference, so the caller can modify the instance variable all she likes. This may disturb some folks, because it seems like the reader should be read-only.

If this were C++, we'd even declare the reader as const. But you don't have quite that degree of protection of your object's internal data as you do in C++, unfortunately. In fact, there's a way to get around practically every encapsulation "convention" provided by Ruby; they're really just "conventions", not rules that are enforced by Ruby (use obj.send(:private_method_A), for instance, to call private_method_A as if it were a public method). [To do: move to its own section].

class A
  attr_reader :options
  def initialize
    @options = []
  end
end

a = A.new
puts a.options.object_id  # to show that the a.options() method returns the variable it is reading *by reference*...
a.options() << 'flum1'    # and with this "reference" to A's private @options data, we can do whatever we'd like!
a.options() << 'flum2'
p a.options

-604226398
["flum1", "flum2"]

Illustration of how to create a "reference" to an object (so you have 2 variables pointing to the same object)...

my_ref = a.options
p my_ref.object_id        # to show that my_ref *points* to the same object as a
my_ref.replace ['zroo']   # we operate on my_ref, but end up changing the object that a points to (since they point to the same object)
p a.options

-604226398
["zroo"]

Also note (yet again) that this trick only works if the return value is an actual variable rather than an "expression"... If you were to implement your attribute reader like this...

  def options
    @options | []
  end

...instead of like this...

  def options
    @options
  end

...then you would effectively make it read-only! a.options().replace, a.options() << element would modify some object, certainly, but it could never be used to modify @options. (Take that, you people-who-try-to-directly-access-my-object's-instance-variables-rather-than-going-through-the-interface-I've-provided!)

Also note how in the following example...

class A
  def initialize
    @options = []
  end
  def options
    @options | []
  end
end

a = A.new
puts a.options.object_id
puts a.options.object_id
puts a.options.object_id
a.options() << 'flum2'
p a.options

...each call to a.options returns a different object. (Has that fact sunk into your mind yet??)

-604404818
-604404858
-604404898
[]

How to make a new variable "reference" an existing object ([Examples (category)] of the difference between = and replace())

Simplest possible example:

irb -> a = "a"; a.object_id
    => -604430038

irb -> my_ref = a; my_ref.object_id
    => -604430038

irb -> my_ref.replace("c")
    => "c"

irb -> a
    => "c"

Example that shows that arrays maintain "references" (rather than just the values) to their member objects too...

irb -> a = "a"; b = "b"; a.object_id
    => -604430038

irb -> array = [a, b]
    => ["a", "b"]

irb -> array[0].object_id
    => -604430038

irb -> my_ref = array[0]
    => "a"

irb -> my_ref = array[0]; my_ref.object_id
    => -604430038

irb -> my_ref = "c"; my_ref.object_id
    => -604549458

irb -> my_ref = array[0]; my_ref.object_id
    => -604430038

irb -> my_ref.replace("c"); my_ref.object_id
    => -604430038

irb -> a
    => "c"

([Examples (category)] of the difference between = and replace())

irb -> def foo(input)
         puts $a.object_id
         puts input[0].object_id
         $a = 'b'
         puts $a.object_id
         puts input[0].object_id
         puts input[0]
       end
    => nil

irb -> $a, $b = 'a', 'b'
    => ["a", "b"]

irb -> foo([$a, $b])
-604472168  # (the original object (containing 'a'))
-604472168  # (the original object (containing 'a'))
-604486558  # $a was changed to point to the object containing 'b'
-604472168  # but input[0] still points to the original object (containing 'a')
a           #     input[0] still points to the original object (containing 'a')
    => nil

irb -> $b
    => "b"  # $a was changed to point to the object containing 'b'

[Problems (category)] Why I wish Ruby had proper pointers (even if every object did have a replace() method, that still doesn't let you change types) ([Examples (category)] of the difference between = and replace())

Sometimes you want to have your method accept an array of objects and then modify those objects and have your changes visible outside of the method (as opposed to just modifying local variables).

The following example using Strings illustrates how this is possible with classes that implement the replace() method.

require 'stringio'
def change_vars!(vars)
  puts "Before:"
  puts vars.map { |v| v.inspect }.join(", ")

  vars.each do |v|
    v.replace 'new'
  end

  puts "After:"
  puts vars.map { |v| v.inspect }.join(", ")
end

$a, $b = ['old']*2
change_vars! [$a, $b]

Before:
"old", "old"
After:
"new", "new"

Note, however, that replace() can't be used to change the type of the variable.

require 'stringio'
def change_vars!(vars)
  puts "Before:"
  puts vars.map { |v| v.inspect }.join(", ")

  vars.each do |v|
    v.replace StringIO.new
  end

  puts "After:"
  puts vars.map { |v| v.inspect }.join(", ")
end

$a, $b = ['old']*2
change_vars! [$a, $b]

Before:
"old", "old"
...:in `replace': can't convert StringIO into String (TypeError)
        from temp.rb:11:in `change_vars!'
        from temp.rb:10:in `each'
        from temp.rb:10:in `change_vars!'
        from temp.rb:19

Those were contrived examples. Here's what I really want to be able to do:

• pass an array of objects to capture_output; these objects will be of type IO
• in capture_output, I want to be be able to use an iterator and change every object in the array that was passed in to be a different object (a new object, of type StringIO)

require 'stringio'
def capture_output(vars = [$stdout], &block)
  puts "Before:"
  puts vars.map { |v| v.inspect }.join(", ")

  vars.each do |v|
    v = StringIO.new
  end

  puts "After:"
  puts vars.map { |v| v.inspect }.join(", ")
end

capture_output [$stdout, $stderr]

This proves to be impossible to do the way I had imagined doing it for the following reasons:

• Even though v is a "reference" to $stdout, when I do v = StringIO.new, it breaks the reference and causes v (a local variable, by the way) to be a "reference" to the newly constructed StringIO object. $stdout is unchanged.
• I would just use IO#replace, but that (1) doesn't exist, and (2) even if it did exist, all it could do would be to replace itself with another object of the same type, not with a different type (unless we did some Ruby/DL magic, but let's not go there...).

This output confirms that $stdout escapes our efforts to change it:

Before:
#<IO:0xb7f18030>, #<IO:0xb7f1801c>
After:
#<IO:0xb7f18030>, #<IO:0xb7f1801c>

Any other bright ideas?

Kernel has a global_variables method, but it just returns an array containing the names of all the global variables; it doesn't help you to modify those variables (like $GLOBALS does in PHP). I was hoping for a global_variable_set method like there is a class_variable_set and instance_variable_set.

You can't use eval() as an lvalue, or you might be able to do something like eval(global_name) = new_value.

If you are able to enumerate ahead of time all possible variables that might be passed in and write a special case for each of those variables, then the following solution "works"...

require 'stringio'
def capture_output(vars = [$stdout], &block)
  puts "Before:"
  puts vars.map { |v| v.inspect }.join(", ")

  vars.each do |v|
    case v
      when $stdout
        $stdout = StringIO.new
      when $stderr
        $stderr = StringIO.new
    end
  end

  puts "After:"
  puts vars.map { |v| v.inspect }.join(", ")
end

capture_output [$stdout, $stderr]

(this has the desired effect)

That's a huge "if", however. I want a solution that works for any variables that may be passed in -- not just input that matches one of the pre-defined allowed variables. I want a generic solution that works for any variables, and any number of variables.

Even if that requisite condition is satisfied, I'm certainly not satisfied with that solution -- all that duplication is uuuugly.

The following "solution" also "works":

require 'stringio'
def capture_output(vars = [$stdout], &block)
  puts "Before:"
  puts vars.map { |v| eval(v).inspect }.join(", ")

  vars.each do |v|
    eval(v + " = StringIO.new")
  end

  puts "After:"
  puts vars.map { |v| eval(v).inspect }.join(", ")
end

capture_output ["$stdout", "$stderr"]

But it is just as ugly. evaling strings containing variable names just to set a variable? That is stooping to the utter depths of programmer desperation. It's too kludgey. I'd just rather not use eval to get the job done, if you know what I mean.

But that's the best I've come up with. Please inform me of a better solution!

Proposed to Ruby language: Either of the following would be satisfactory to me:

• Add a standard Pointer class to the language
• Add a built-in Kernel#global_variable_set method.

Can I pass argument by reference so that the method can return more than one return value?

No, not usually. But it shouldn't matter because Ruby provides a better way to return more than one return value.

def analyze_string(input, size)
  size = input.length
  puts size.object_id
  input
end

size = nil
puts size.object_id
puts analyze_string("Hmm...", size)
puts "And its size was: #{size}"

4
23
Some string
And its size was:

I must have told you a 1000 times by now: var = does not change the object pointed to by var; instead, it re-points var to a different object.

"Fine", you say, "we'll just use replace".

"Okay, go for it!" I say, smiling because I know it won't work.

def analyze_string(input, size)
  size.replace input.length
  puts size.object_id
  input
end

size = Fixnum.new
puts size.object_id
puts analyze_string("Some string", size)
puts "And its size was: #{size}"

undefined method `new' for Fixnum:Class (NoMethodError)

How about this?:

...
size = 0
puts size.object_id
puts analyze_string("Some string", size)
puts "And its size was: #{size}"

undefined method `replace' for 0:Fixnum (NoMethodError)

"So we're out of luck then, right?"

"Well, not entirely. We just have to approach the problem from a different angle ... the Ruby way."

def analyze_string(input)
  return input[0..0], input.length
end

first_letter, size = analyze_string("Some string")
puts "The first letter was: #{first_letter}"
puts "And its size was: #{size}"

The first letter was: S
And its size was: 11

So there you have it: even though you can "pass arguments by reference" and change those objects from within your method some of the time (like when you pass in objects that respond to replace, such as String), it is probably not a good habit to get into, and it certainly not the preferred way of returning multiple values.

Boolean expressions

[just for fun (category)] If some common English boolean phrases were translated into Ruby...

def die!; "You're dead." end
def skate; "I'm skating" end
xmp "skate or die!"
def skate; "I'm "; !"skating" end
xmp "skate or die!"


def ticket!; "You just got a ticket!" end
def click_it; "I clicked it" end
xmp "click_it or ticket!"
def click_it; not 'wearing a seat belt' end
xmp "click_it or ticket!"


class << it = Object.new
  def will_hurt; "Ouch! Hey, that hurt!" end
end
def litter; "I'm just a-litterin' away!" end
xmp "litter and it.will_hurt"
def litter; "Okay, I'll stop! I will"; not "litter any more." end
xmp "litter and it.will_hurt"

skate or die!
    ==>"I'm skating"
skate or die!
    ==>"You're dead."
click_it or ticket!
    ==>"I clicked it"
click_it or ticket!
    ==>"You just got a ticket!"
litter and it.will_hurt
    ==>"Ouch! Hey, that hurt!"
litter and it.will_hurt
    ==>false

Creating hashes without enclosing in {/}

A common Ruby idiom for methods is to make the last argument an "options" hash... This allows for some cleaner syntax and more flexibility in your calls...

• you can specify as many options as you'd like, or none at all
• you can specify them in any order

irb -> def m(arg1, arg2, options = {}); p [arg1, arg2, options]; end
    => nil

irb -> m 'arg1', 'arg2', :option1 => true, :option2 => :maybe
["arg1", "arg2", {:option1=>true, :option2=>:maybe}]
    => nil

It only works in certain cases, though...

You can only omit the {/} for the last argument, however...

irb -> def m(arg1, arg2, options = {}, arg4 = nil); p [arg1, arg2, options, arg4]; end
    => nil

irb -> m 'arg1', 'arg2', :option1 => true, :option2 => :maybe, 'arg4'
SyntaxError: compile error
(irb):19: syntax error, unexpected '\n', expecting tASSOC
        from (irb):19
        from :0

If you need to pass an argument after your "options" hash, then you need to enclose the hash with {/}...

irb -> m 'arg1', 'arg2', {:option1 => true, :option2 => :maybe}, 'arg4'
["arg1", "arg2", {:option1=>true, :option2=>:maybe}, "arg4"]
    => nil

This conciser syntax without the {/} also works to a limited extent within arrays...

irb -> ['arg1', 'arg2'] + [:option_1 => 'hi']
    => ["arg1", "arg2", {:option_1=>"hi"}]

It seems it only works if the hash is the only element of the array, though, (even when you put the hash as the last element) which seems kind of arbitrary if you ask me....

irb -> ['arg1', 'arg2'] + ['arg3', :option_1 => 'hi']
SyntaxError: compile error
(irb):25: syntax error, unexpected tASSOC, expecting ']'
['arg1', 'arg2'] + ['arg3', :option_1 => 'hi']

Assigning a method call to a local variable of the same name

irb -> def foo
         'foo'
       end

Don't do this:

irb -> foo = foo
    => nil
irb -> foo
    => nil

When it sees the foo that you are assigning to foo, it will have already registered the local variable "foo" and initialized it with a value of nil. (Recall that bare names are treated as locals if the local has been initialized already. It is only treated as a method call if there is no local variable by that name!) In other words, it is identical to doing this:

irb -> foo = nil
    => nil
irb -> foo = foo
    => nil

Instead, be sure to use the () symbols so that it knows that is a method call.

irb -> foo = foo()
    => "foo"

irb -> foo
    => "foo"

Or, just assign it to a variable with a different name than your method:

irb -> snoo = foo
    => "foo"

No problem!

Syntax: operator associativity / precedence / order of operations

Caveat: {/} have higher precedence than do/end !

From Pickaxe

Pickaxe, p. 168

def one(arg)
  if block_given?
    "block given to 'one' returns #{yield}"
  else
    arg
  end
end
def two
  if block_given?
    "block given to 'two' returns #{yield}"
  end
end
result1 = one two {
  "'three'" 
}
#result1 = one(two {
#  "'three'" 
#})
result2 = one two do
  "'three'"
end
#result2 = one(two) do
#  "'three'"
#end
puts "With {/}   : #{result1}" # => With {/}   : block given to 'two' returns 'three'
puts "With do/end: #{result2}" # => With do/end: block given to 'one' returns 'three'

Using {/} instead of do/end can cause bugs

The Rake User Guide (http://docs.rubyrake.org/read/chapter/4#page23) makes it clear that using {/} can lead to unexpected problems, because it may pass your block to the wrong method! :

Blocks may be specified with either a do/end pair, or with curly braces in Ruby. We strongly recommend using do/end to specify the actions for tasks and rules. Because the rakefile idiom tends to leave off parenthesis on the task/file/rule methods, unusual ambiguities can arise when using curly braces. For example, suppose that the method object_files returns a list of object files in a project. Now we use object_files as the prerequisites in a rule specified with actions in curly braces.

  # DON'T DO THIS!
  file "prog" => object_files {
    # Actions are expected here (but it doesn't work)!
  }

Because curly braces have a higher precedence than do/end, the block is associated with the object_files method rather than the file method.

This is the proper way to specify the task …

  # THIS IS FINE
  file "prog" => object_files do
    # Actions go here
  end

Using do/end instead of {/} can also cause bugs

Unfortunately, I've found that one is not necessarily safe just because one follows the rule of always using do/end for all multi-line blocks. Even then you can cause behavior that may not be what you expected unless you understand the difference pretty well...

I guess it's best simply to understand the difference in associativity (rather than blindly following a convention you don't understand) and use whichever one yields the associativity you are wanting.

I first ran into this problem with this simple-looking piece of code.

  puts output_streams.map do |output_stream|
    output_stream.inspect
  end.join ", "

To my surprise, it gave an error:

undefined method `join' for nil:NilClass (NoMethodError)

I had to change it to {/}, supposedly the wrong way to multi-line blocks...

  puts output_streams.map { |output_stream|
    output_stream.inspect
  }.join ", "

A closer look...

irb -> puts [1, 2].map do |v| 
  v 
end.join ", "
1
2
NoMethodError: undefined method `join' for nil:NilClass
        from (irb):18
        from :0

What??

irb -> puts [1, 2].map do |v| v end
1
2
    => nil

Ah... So I guess the default associativity of:

puts [1, 2].map do |v| v end.join ", "

is actually:

puts([1, 2].map do |v| v end).join ", "

(evaluates to nil.join ", ") ...which is not what I wanted in this case!

This is more along the lines of what I wanted...

irb -> puts( [1, 2].map do |v| v end.join(", ") )
1, 2
    => nil

Of course I could have always done it with {/} like this...

irb -> puts [1, 2].map { |v| v }.join(", ")
1, 2
    => nil

but I originally had it on multiple lines so I thought I was "supposed to" use do/end.

To summarize the difference in behavior:

meth1 objA.iterator_meth do block end.meth2
= (meth1 objA.iterator_meth do block end).meth2

meth1 objA.iterator_meth { block }.meth2
yields = meth1 (objA.iterator_meth { block }).meth2

Conclusion: Using {/} for multi-line blocks is not necessarily the "wrong" way. It sure beats putting tons of extra parentheses to effect your desired associativity, IMHO! So {/} can sometimes be the preferred option, even for multi-line blocks!

More specifically, objA.iterator_meth do block end.meth1.meth2
is okay, but if you're passing the result of your block-taker to another method, then {/} might be safer/more appropriate...
meth1 objA.iterator_meth { block end.meth2 }.

Caveat: method call has higher associativity than range (..) operator

Don't accidentally do this:

'a'..'z'.each {|letter| print letter}
=> z

Do this instead:

('a'..'z').each {|letter| print letter}
=> abcdefghijklmnopqrstuvwxyz

Caveat: &&/|| have higher precedence than and/or !

Observe:

irb -> a = true and false

irb -> a
    => true       # <--- !!!

# Same as doing this:
irb -> (a = true) and false

This is not a bug. It's just something to be aware of. It's just the order of operator precedence: = comes before and. Period.

In the first example, the assignment a = true happens regardless of what follows 'and'. This is because the = operator (?) has a higher precedence than 'and'. So it happens first and then the 'and' is evaluated.

With && it is different.

irb -> a = true && false

irb -> a
    => false

true && false is evaluated before the assigment. Then the result of true && false (which is false) is assigned to a.

This is probably what you would want to do most of the time (rather than a = something and something_else).

boolean operators (and and or)

I think this is the same in almost all languages, but just as a reminder, if you don't specify parentheses, it will evaluate the operators from left to right. So this:

 > true or false and false
=> false

is really the same as this:

 > (true or false) and false
=> false

To override that default order of operations you must use parentheses:

 > true or (false and false)
=> true

How do I execute an external program?

What happens to standard error (stderr)?

For those commands that only capture stdout (`...`, IO.popen), you should probably decide between one of two options:

• Discard stderr (result = `command 2>/dev/null`)
• Redirect stderr to stdout (result = `command 2>&1`)

The default behavior (if you don't do either of those) is for the standard error to just appear on screen as normally would if you had run the program independently (not from a script). This can be pretty odd/confusing, though, if you were attempting to silently capturing the output of some command but you still got some output from it. It's not always clear where the output is coming from (your command or the command you're trying to capture). That's why I prefer to either discard it or capture it. But you have to remember to one or the other or it may just appear on screen instead!

popen

How do I use popen?

IO.popen("other_program", "w+") do |pipe|
  pipe.puts "here, have some input"
  pipe.close_write  # If other_program process doesn't flush its output, you probably need to use this to send an end-of-file, which tells other_program to give us its output. If you don't do this, the program may hang/block, because other_program is waiting for more input.
  output = pipe.read
end

# You can also use the return value from your block. (exit code stored in $? as usual)
output = IO.popen("other_program", "w+") do |pipe|
  pipe.puts "here, have some input"
  pipe.close_write
  pipe.read
end

http://ruby-doc.org/core/classes/IO.html#M002294

Runs the specified command string as a subprocess; the subprocess’s standard input and output will be connected to the returned IO object. If cmd_string starts with a ``-’’, then a new instance of Ruby is started as the subprocess. The default mode for the new file object is ``r’’, but mode may be set to any of the modes listed in the description for class IO. If a block is given, Ruby will run the command as a child connected to Ruby with a pipe. Ruby’s end of the pipe will be passed as a parameter to the block. In this case IO::popen returns the value of the block. If a block is given with a cmd_string of ``-’’, the block will be run in two separate processes: once in the parent, and once in a child. The parent process will be passed the pipe object as a parameter to the block, the child version of the block will be passed nil, and the child’s standard in and standard out will be connected to the parent through the pipe. Not available on all platforms.

(Example) Getting child process id

irb -> pipe = IO.popen('uname')
    => #<IO:0xb7dd19b0>

irb -> pipe.readlines
    => ["Linux\n"]

irb -> "Parent is #{Process.pid}"
    => "Parent is 27577"

irb -> "popen's child process is #{pipe.pid}"
    => "popen's child process is 31914"

irb -> pipe.close
    => nil

irb -> "popen's child process is #{pipe.pid}"
IOError: closed stream

What if I want to use popen to capture stderr too?

If you just want it combined with stdout, you can simply redirect the stderr stream into the stdout stream (2>&1).

If you want to capture them separately, check out Open3.

http://ruby-doc.org/core/classes/Open3.html#M005449

  Open3.popen3('nroff -man') { |stdin, stdout, stderr| ... }

How long will it wait?

If you call read (etc.), it will wait until there is more output or the command finished (EOF)

Be careful, because your process will block if there is no more output!

Bad idea:

sleeper = IO.popen("sleep 10000"); puts sleeper.read

You will be waiting for a long time. sleep will never produce any output, because (if you read your docs carefully), "Reads at most length bytes from the I/O stream, or to the end of file if length is omitted or is nil." There is no end of file... so it blocks and waits for one.

Equally bad idea, because sleep will never produce any output, not even 1 character of output.

sleeper = IO.popen("sleep 10000"); puts sleeper.read(1)

Better idea:

irb -> sleeper = IO.popen("sleep 1"); p sleeper.read
""
    => nil

Even though the sleep doesn't return any output, at least read will stop blocking when the subcommand terminates .

In the following example, read(1) causes the process to block until the subprocess flushes its output. It ends up taking a full 5 seconds before we get any input.

irb -> countdown = IO.popen("ruby -e '5.downto(0) {|i| puts i; sleep 1}'"); countdown.read(1)
5
4
3
2
1
0
    => nil

By contrast, this returns immediately, because $stdout.sync tells Ruby to flush the output immediately every time you try to output something:

irb -> countdown = IO.popen("ruby -e '$stdout.sync = true; 5.downto(0) {|i| puts i; sleep 1}'"); countdown.read(1)
    => "5"

In the case of a bi-directional pipe ('w+') (stdout+stdin)... be sure you call close_write!

Good idea:

irb -> IO.popen("grep food", "w+") { |pipe| pipe.puts "have some food"; pipe.close_write; output = pipe.read }
    => "have some food\n"

Bad idea:

irb -> IO.popen("grep food", "w+") { |pipe| pipe.puts "have some food"; output = pipe.read }
[Will block, waiting for input. Have to Ctrl-C to interrupt.]
IRB::Abort: abort then interrupt!!

When you close a popened pipe and that process is still running, your process will wait for it...

sleeper = IO.popen("sleep 10000") # The child process goes to sleep
sleeper.close
# The parent process will now wait for the sleep command to finish...

Sometimes you want to have more (interactive) control over the subprocesses that you start up.

You could always use the timeout library and Process.kill the child process if it takes too long.

You might also consider using fork, or using IO.select (with a timeout) to check if any more output is available...

How do you you close your pipe and kill that process without waiting for it???

irb -> pipe = IO.popen('sleep 1000')
    => #<IO:0xb7d4cd78>

irb -> pipe.pid
    => 28120

irb -> Process.kill 'TERM', pipe.pid

irb -> pipe.close

How do I read up until a certain input is reached and then exit the popen?

Simple way

def read_until(pipe, stop_at, verbose = true)
  lines = []
  while line = pipe.gets
    break if line =~ stop_at
    puts line if verbose
    lines << line
  end
  lines
end

IO.select way

I haven't figured out yet when you would need to use this method, but this is the method used by Jamis Buck's GDB wrapper (http://weblog.jamisbuck.org/assets/2006/9/25/gdb.rb), so it must have some use, right?

def read_until(pipe, stop_at, verbose = true)
  lines = []
  line = ""
  while result = IO.select([pipe])  #, nil, nil, 10)
    next if result.empty?

    c = pipe.read(1)
    break if c.nil?

    line << c
    break if line =~ stop_at

    # Start a new line?
    if line[-1] == ?\n
      puts line if verbose
      lines << line
      line = ""
    end
  end
  lines
end

The online RDocs for IO.select and Kernel.select both say to "See Kernel#select."

So instead, I will rely on my trusty Pickaxe book, p. 528-529 [3]:

IO.select(read_array
[, write_array
[, error_array
[, timeout]]] )
=> array or nil

Performs a low-level select call, which waits for data to become available from input/output devices. The first three parameters are arrays of IO objects or nil. The last is a timeout in seconds, which should be an Integer or a Float. The call waits for data to become available for any of the IO objects in read_array, for buffers to have cleared sufficiently to enable writing to any of the devices in write_array, or for an error to occur on the devices in error_array. If one or more of these conditions are met, the call returns a three-element array containing arrays of the IO objects that were ready. Otherwise, if there is no change in status for timeout seconds, the call returns nil. If all parameters are nil, the current thread sleeps forever.

select( [$stdin], nil, nil, 1.5 )       »       [[#<IO:0x401ba090>], [], []]

Forking processing

How do I fork a child process?

Depends on whether you want to run Ruby code (same program) or an external program in your child process...

# Run an external program (command) in the child process
exec(command) if fork.nil?
# ...
Process.wait

-or-

# Run some Ruby code (same program) in the child process
fork do
  puts "In child process. parent pid is #$$"
  exit 99
end
child_pid = Process.wait
puts "Child (pid #{child_pid}) terminated with status #{$?.exitstatus}"

http://corelib.rubyonrails.org/classes/Kernel.html#M002088

The parent process should use Process.wait to collect the termination statuses of its children or use Process.detach to register disinterest in their status; otherwise, the operating system may accumulate zombie processes.

Using IO.popen('-')

irb -> "Parent process is #{Process.pid}"
    => "Parent process is 27577"

irb -> IO.popen('-') {|pipe| $stderr.puts "#{Process.pid} is here, pipe is #{pipe}"}
32579 is here, pipe is
27577 is here, pipe is #<IO:0xb7d700ac>

Getting process id

http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/9105

> |How can I get the PID of a program run in a ruby script. I've 
> |looked at open, popen, system, and %x//, and various Process 
> |methods, but haven't figured it out.
 
> IO#pid for open, popen.  No way provided for system and `` (yet).

http://www.hostingforum.ca/262611-getting-pid-external-command.html

def my_system(*cmd)
  pid = fork do
    exec(*cmd)
    exit! 127
  end
  yield pid if block_given?
  Process.waitpid(pid)
  $?
end

irb -> my_system("sleep 3") { |pid| 
  puts "other process id is #{pid}"
  Process.kill "TERM", pid 
}
Pid is 22586
    => #<Process::Status: pid=22586,signaled(SIGTERM=15)>

[Caveats (category)] Ruby's `...`, system, and exec require executable scripts (non-binaries) to have shebang line!

Bash doesn't care! As long as the executable bit is set, it will be happy to run it for you!

> echo -e "echo 'bash_hi'" > bash_hi_no_shebang; chmod 0700 bash_hi_no_shebang
> cat bash_hi_no_shebang
echo 'bash_hi'
> /home/tyler/bash_hi_no_shebang
bash_hi

Ruby, however, is a bit more picky about what it will run for you. You will get a mysterious command not found if it doesn't like your script.

irb -> `/home/tyler/bash_hi_no_shebang`
(irb):37: command not found: /home/tyler/bash_hi_no_shebang
    => ""

! Even though the command (the file) does exist!

But this does work from ruby:

[tyler: ~]> echo -e '#!'"/bin/bash\necho 'bash_hi'" > bash_hi; chmod 0700 bash_hi
[tyler: ~]> /home/tyler/bash_hi
bash_hi

irb -> `/home/tyler/bash_hi`
    => "bash_hi\n"

The shebang line makes all the difference!

Which techniques work to start/fork a process that needs to interact with the user (as in, a text editor)?

Let's face it, some command-line programs are interactive and need full access to the [terminal]. They are "[full-screen]" and may do fancy [ANSI] tricks. Examples: editors, top.

For these cases, not all methods of starting process work equally well. system is the technique that works the best.

These work:

• system('vim') (seems like the safest bet)
• exec('editor') if fork.nil? (with varying degrees of success)
• exec('vim') (but you can't execute code after that)

These do not work:

• `vim`

Details:

irb -> system('vim temp'); p File.readlines('temp')
[it started up vim, where I wrote "hi there", saved, and exited]
["hi there\n"]
    => nil
/pre>

<pre>
irb -> `vim`
Vim: Warning: Output is not to a terminal
[Then it just hung there, not giving any feedback at all when I typed. Ctrl-C, Ctrl-D, etc. were all ineffectual. The only thing I could do at this point was Ctrl-Z.]
> pkill -9 irb
[11]+  Killed                  irb

Warning: Don't run exec('vim') if fork.nil? from within irb. That had the weirdest behavior of them all. I really do not understand what it did to the terminal, but it really screwed it up visually so it was hard to tell what you were doing or even what program you were doing it in. I was lucky to be able exit out of everything alive (and by alive I mean successfully).

irb -> exec('editor') if fork.nil?
[a bunch of guessing, trying various exit commands, and eventually escaping]

When I finally got out of irb, a reset command was necessary to fix my terminal.

It seemed to work fine though if just executed with straight ruby (not irb):

> cat temp.rb
exec('vim temp') if fork.nil?
Process.wait
p File.readlines('temp')
> ruby temp.rb
[fired up vim]
"temp" 1L, 9C written
["hi there\n"]

Timing out an operation

http://pleac.sourceforge.net/pleac_ruby/processmanagementetc.html

# implemented thanks to http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/1760
require 'timeout'

begin
    timeout(5) {
        waitsec = rand(10)
        puts "Let's see if a sleep of #{waitsec} seconds is longer than 5 seconds..."
        system("sleep #{waitsec}")
    }
    puts "Timeout didn't occur"
rescue Timeout::Error    
    puts "Timed out!"
end

Signals

Sending a Signal

http://pleac.sourceforge.net/pleac_ruby/processmanagementetc.html

Process.kill(9, pid)                    # send $pid a signal 9
Process.kill(-1, Process.getpgrp())     # send whole job a signal 1
Process.kill("USR1", $$)                # send myself a SIGUSR1
Process.kill("HUP", pid1, pid2, pid3)   # send a SIGHUP to processes in @pids
#-----------------------------
begin
    Process.kill(0, minion)
    puts "#{minion} is alive!"
rescue Errno::EPERM                     # changed uid
    puts "#{minion} has escaped my control!";
rescue Errno::ESRCH
    puts "#{minion} is deceased.";      # or zombied
rescue
    puts "Odd; I couldn't check the status of #{minion} : #{$!}"
end

Installing a Signal Handler (trap)

http://pleac.sourceforge.net/pleac_ruby/processmanagementetc.html

Kernel.trap("QUIT", got_sig_quit)       # got_sig_quit = Proc.new { puts "Quit\n" }
trap("PIPE", "got_sig_quit")            # def got_sig_pipe ...
trap("INT") { ouch++ }                  # increment ouch for every SIGINT
#-----------------------------
trap("INT", "IGNORE")                   # ignore the signal INT
#-----------------------------
trap("STOP", "DEFAULT")                 # restore default STOP signal handling

http://svn.tylerrick.com/public/ruby/examples/trap-chaining_two_signal_handlers.rb

# See ~/code/gemables/qualitysmith_extensions/lib/qualitysmith_extensions/kernel/trap_chain.rb for the final product

def trap_chain(*args, &block)
  previous_interrupt_handler = trap("INT") {}
  trap("INT") do
    block.call
    previous_interrupt_handler.call unless previous_interrupt_handler == "DEFAULT"
  end
end
trap_chain("INT") { puts "Handler 1"; }
trap_chain("INT") { puts "Handler 2"; puts "Exiting..."; exit }
trap_chain("INT") { puts "Handler 3" }
trap_chain("INT") { puts "Handler 4" }

Process.kill "INT", 0

loop do
  # Press Ctrl-C to interrupt this loop
end

# Outputs:
Handler 4
Handler 3
Handler 2
Exiting...

Temporarily Overriding a Signal Handler

http://pleac.sourceforge.net/pleac_ruby/processmanagementetc.html

# the signal handler
def ding
    trap("INT", "ding")
    puts "\aEnter your name!"
end

# prompt for name, overriding SIGINT
def get_name
    save = trap("INT", "ding")

    puts "Kindly Stranger, please enter your name: "
    name = gets().chomp()
    trap("INT", save)
    name
end

Links

http://pleac.sourceforge.net/pleac_ruby/processmanagementetc.html

How to write to a file

irb -> require 'tmpdir'
    => true

irb -> Dir.tmpdir
    => "/tmp"

irb -> File.open(my_filename = "#{Dir.tmpdir}/my_file", "w") { |file| file.puts "woo!" }
    => nil

irb -> File.open(my_filename, "r") { |file| puts file.gets }
woo!
    => nil

irb -> File.delete(my_filename)
    => 1

How to find out the location of the "temp" directory

irb -> require 'tmpdir'
    => true

irb -> Dir.tmpdir
    => "/tmp"

irb -> File.open(my_filename = "#{Dir.tmpdir}/my_file", "w") { |file| file.puts "woo!" }
    => nil

irb -> File.open(my_filename, "r") { |file| puts file.gets }
woo!
    => nil

irb -> File.delete(my_filename)
    => 1

How to read in a file

The quickest and easiest way is probably with

• File.read -- gets you a single lnong string
• File.readlines (or IO.readlines -- don't ask me why we have both).

irb -> File.read('foo')
    => "line1\nline2\n"

irb -> File.readlines('foo')
    => ["line1\n", "line2\n"]

irb -> require 'rubygems'
irb -> require 'extensions/symbol'

irb -> f = File.open('foo', 'w') { |f| f.puts 'line1'; f.puts 'line2' }
    => nil

irb -> File.readlines('foo')
    => ["line1\n", "line2\n"]
irb -> File.readlines('foo').map(&:chomp)
    => ["line1", "line2"]

You can also open a file and then read from it, if you want a bit more control...

irb -> f = File.open('foo', 'w') { |f| f.puts 'line1'; f.puts 'line2' }
    => nil

Writing filters / file processors/transformers in Ruby

Using ARGF

Here's a "simple" example:

http://eigenclass.org/hiki.rb?eigenclass.org+repainted+1

I used a quick Ruby script to rewrite the CSS stylesheets (making most colors 20% darker), and you're getting a new logo with a 50% probability on each pageview. Here's the (trivial) code:

#!/usr/bin/env ruby

FACTOR = 0.8

def transform_color(r, g, b)
  case r + g + b
  when 255..600
    [r, g, b].map{|x| (FACTOR * x).to_i}
  else
    [r, g, b]
  end
end

css = ARGF.read
css.gsub!(/#[0-9A-Fa-f]{6}/) do |color|
  "#" + 
    transform_color(*color[1..6].scan(/../).map{|x| Integer("0x#{x}") }).map{|x| "%02X" % x}.join("") 
end

css.gsub!(/#[0-9A-Fa-f]{3}(?=[^0-9A-Fa-f])/) do |color|
  r, g, b = color[1..3].scan(/./).map{|x| Integer("0x#{x}#{x}") }
  "#" + 
    transform_color(r, g, b).map{|x| "%02X" % x}.join("") 
end

puts css

Using File.open_as_string

Facets

http://facets.rubyforge.org/src/doc/rdoc/core/classes/File.html#M000692

  # Reverse contents of "message"
  File.open_as_string("message") { |str| str.reverse! }

require 'facets/core/file/self/open_as_string'

irb -> FileUtils.touch 'foo'
    => ["foo"]

irb -> File.open_as_string('foo') { |s| puts s }

    => nil

irb -> File.open_as_string('foo') { |s| s = "Initial contents\n" }; puts File.read('foo')

    => nil

irb -> File.open_as_string('foo') { |s| s.replace "Initial contents\n" }; puts File.read('foo')
Initial contents
    => nil

irb -> File.open_as_string('foo') { |s| s += "Another line\n" }; puts File.read('foo')
Initial contents
    => nil

irb -> File.open_as_string('foo') { |s| s << "Another line\n" }; puts File.read('foo')
Initial contents
Another line
    => nil


FileUtils.touch 'foo'
File.open_as_string('foo') { |s| s.replace "Initial
contents\n" } # Don't do s = "..."!
File.open_as_string('foo') { |s| s << "Another line\n"
} # Don't do s += "..."!
File.open_as_string('foo') { |s| s.gsub! /old/, 'new' } # Must use in-place version (gsub!), not gsub

matches.rb

Practically a one-liner!

$stdin.each_line do |filename|
  puts filename if IO.read(filename.chomp) =~ /#{Regexp.escape(ARGV[0])}/
end

ARGF

Pickaxe, p. 335 or English library RDoc

An object that provides access to the concatenation of the contents of all the files given as command-line arguments, or $stdin (in the case where there are no arguments). $< supports methods similar to a File object: inmode, close, closed?, each, each_byte, each_line, eof, eof?, file, filename, fileno, getc, gets, lineno, lineno=, path, pos, pos=, read, readchar, readline, readlines, rewind, seek, skip, tell, to_a, to_i, to_io, to_s, along with the methods in Enumerable. The method file returns a File object for the file currently being read. This may change as $< reads through the files on the command line. Read only.

How do I check if the output stream has been redirected to a pipe?

I want to output in color if it has not been redirected to a pipe, but not output in color if output has been redirected.

In other words, these should generate two different outputs:

my_script.rb | cat -
my_script.rb

I thought maybe this would be the case when the output has been redirected, but it appears not to be the case: ($> != STDOUT)

What else can I check??

.

http://www.ruby-doc.org/core/classes/Dir.html

See also': Ruby / Input/output

How to get the current working directory

Dir.getwd or FileUtils.pwd

How to change the working directory (cd)

 > require 'rubygems'
=> true
 > require 'rake'
=> true
 > Rake::FileList
=> Rake::FileList
 > FileUtils.pwd
=> "/var/www/whatever_app/db"
 > FileUtils.cd '..'; FileUtils.pwd
=> "/var/www/whatever_app"
 > FileUtils.cd 'config'; FileUtils.pwd
=> "/var/www/whatever_app/config"
 > FileList['*']
=> ["environments", "environment.rb", "routes.rb", "boot.rb", "database.yml", "lighttpd.conf", "deploy.rb", "database.mydb.yml"]

[listing files (category)][file globbing (category)] How to get a list of all files in the current directory using Dir

If by "current directory" you mean the directory that this script is in (File.dirname(__FILE__)):

Dir.new(File.dirname(__FILE__)).each do |file|
  unless ['.', '..'].include? file
    puts file
  end
end

If instead, you mean "current directory" should be what Dir.getwd would return, then this is what you want:

Dir.new('.').each do |file|
  unless ['.', '..'].include? file
    puts file
  end
end

But often we don't want to print out the files; we just want them returned as an array...

For that, we have Dir.entries. Unfortunately, it also includes the ., .. entries that we almost never want...

Dir.new('.').entries.reject {|f| [".", ".."].include? f}

We can also do the same thing only using an Enumerator (handy, for instance, if Dir hadn't provided an entries method)...

require 'qualitysmith_extensions/enumerable/enum'

Dir.new('.').enum(:each).to_a

Dir.new('.').enum(:each).reject {|f| [".", ".."].include? f}

If you want to exclude all entries beginning with a . (such as .svn and other directories that are supposed to be hidden)...

Dir.new('.').entries.reject {|f| f =~ /^\./}

[Complaint] Path building is very non-object-oriented

If you're lazy, you can just do it like this:

require File.dirname(__FILE__) + "/lib/svn.rb"

but that's not platform independent. So you're supposed to do it like this:

require File.join(File.dirname(__FILE__), "../lib/svn.rb")

This looks a lot more like procedural programming though: You call File.join and pass it two strings. It looks really ugly to me.

Why not instead have two path component objects and tell them to add each other?

I'm imagining something like this, we can just use the + operator:

require File.dirname(__FILE__).to_path + "../lib/svn.rb".to_path

[cleaning paths (category)] Pathname and File.expand_path

irb -> require 'pathname'

irb -> Pathname.new('/usr/lib/../bin').to_s
    => "/usr/lib/../bin"

irb -> Pathname.new('/usr/lib/../bin').cleanpath.to_s
    => "/usr/bin"

irb -> File.expand_path('/usr/lib/../bin')
    => "/usr/bin"

Files and directories: [listing files (category)]/[file globbing (category)]/[file traversal (category)]/[iteration (category)]

Dir.glob

How does it compare with Dir.multiglob and FileList?

Dir.multiglob [Ruby Facets (category)]

  Dir.multiglob( '*.rb', '*.py' )
  Dir.multiglob( '*', :recurse => true )
  Dir.multiglob('**/*')

How does it compare with FileList?

How to test if something is a directory

File::Stat.new(path).directory?

or

FileTest.directory?(path)

Iterating through contents of a directory

  Dir.new(base_dir = "./some_directory/").each do |name|
    path = "#{base_dir}#{name}"
    if dir_name !~ /^\./
      # Do something with #{path}
    end
  end

Non-directories only:

  Dir.new(base_dir = "./some_directory/").each do |name|
    path = "#{base_dir}#{name}"
    if dir_name !~ /^\./ and !FileTest.directory?(path)
      # Do something with #{path}
    end
  end

Isn't there a better/conciser way?

Hmm, not that I've found so far...

Directory tree traversal ("recursion")

I wrote a class DirectoryRecurser.rb that traverses a directory for you and calls a callback block that you supply once for each entry.

But http://www.ruby-doc.org/core/classes/Find.html looks like a cleaner way to do the same thing.

List all files (paths) within a directory (recursively)

http://svn.tylerrick.com/public/ruby/examples/listing_files_with_Dir_and_Find.rb

require 'find'
require 'fileutils'
Find.find(dir) do |path|
  if FileTest.directory?(path)
    if File.basename(path)[0] == ?. and File.basename(path) != '.'
      Find.prune
    else
      next
    end
  else
    puts path
  end
end

Or, if you'd rather get an array of paths back, use Find.select instead of Find.find...

gem 'qualitysmith_extensions'
require 'qualitysmith_extensions/find/select'
files = Find.select(dir) do |path|
  ...
  true
end

Example: Recursively remove .svn directories

Recursively remove .svn directories (ruby script) (http://textsnippets.com/posts/show/735). Retrieved on 2007-02-08 10:03.

require 'find'
require 'fileutils'
Find.find('./') do |path|
  if File.basename(path) == '.svn'
    FileUtils.remove_dir(path, true)
    Find.prune
  end
end

FileList

http://facets.rubyforge.org/src/doc/rdoc/more/classes/FileList.html (Ported from the version that's part of Rake.)

require 'rubygems'
require 'facets/more/filelist'

The Pickaxe book, p. 230, points out that FileList automatically ignores commonly unused files (like the CVS directory).

 > require 'rubygems'
=> true
 > require 'rake'
=> true
 > Rake::FileList
=> Rake::FileList
 > FileUtils.pwd
=> "/var/www/whatever_app/db"
 > FileUtils.cd '..'; FileUtils.pwd
=> "/var/www/whatever_app"
 > FileUtils.cd 'config'; FileUtils.pwd
=> "/var/www/whatever_app/config"
 > FileList['*']
=> ["environments", "environment.rb", "routes.rb", "boot.rb", "database.yml", "lighttpd.conf", "deploy.rb", "database.mydb.yml"]

file globbing with FileList

This is much like file globbing on the command line. That is, you can use * to get a list of all files in the current directory. I think FileList is even more powerful though: you can use ** to indicate that you don't care how many subdirectories deep it has to traverse.

FileList["**/*.rb"].each do |filename|
  puts filename
end

FileList: include and exclude

FileList['{lib,test,examples}/**/*.rb', '[A-Z]*'].exclude('TODO').to_a

a find command with FileList

http://onestepback.org/index.cgi/Tech/Rake/FindInCode.red

 #!/usr/bin/env ruby
 require 'rake'
 FileList["**/*.rb"].egrep(Regexp.new(ARGV.first))

Dates, Times, and Datetimes, oh my!

How do you create a new Date/Time from (year, month, day) values?

Confusingly, the Rdoc (at http://www.ruby-doc.org/core/classes/Date.html#M000480) shows the documentation for new0 where it should show the documentation for new! That is, you can't even find the documentation for new() in the standard Rdoc!!

Find it here instead: http://www.rubycentral.com/pickaxe/lib_standard.html#Date.new

How do I turn a string into a Date?

(how do I "parse" a string that contains a date)

irb -> require 'date'

irb -> Date.strptime('2007-04-04')
    => #<Date: 4908389/2,0,2299161>

irb -> Date.parse('2007-04-04')
    => #<Date: 4908389/2,0,2299161>

irb -> Time.parse('2007-04-04')
    => Wed Apr 04 00:00:00 -0700 2007

irb -> DateTime.parse('2007-04-04')
    => #<DateTime: 4908389/2,0,2299161>

What's the difference between Date and Time and DateTime?

To do: make a table that shows which methods are available in each

/usr/lib/ruby/1.8/date.rb

DateTime is a subclass of Date which makes these methods (among others) public:

• hour()
• min()
• sec()

Caveat: you may need to require certain date classes for certain Date/Time features

> ruby -rtime -e 'p $LOADED_FEATURES.grep(/date/); puts Time.parse("2007-01-01")'
["date/format.rb", "parsedate.rb"]
Mon Jan 01 00:00:00 -0800 2007

> ruby -rdate -e 'p $LOADED_FEATURES.grep(/date/); puts Date.parse("2007-01-01")'
["date/format.rb", "date.rb"]
2007-01-01

So "parsedate.rb" is needed in order to parse for Time, but not for Date. Odd.

Caveat: irb gives you an incomplete Date class by default

irb -> Date
    => Date

irb -> $LOADED_FEATURES.grep /date/
    => ["date/format.rb", "parsedate.rb"]

irb ->  Date::civil(2003, 4, 8)
NoMethodError: undefined method `civil' for Date:Class
        from (irb):4
irb -> require 'date'
    => true

irb -> $LOADED_FEATURES.grep /date/
    => ["date/format.rb", "parsedate.rb", "date.rb"]

irb ->  Date::civil(2003, 4, 8)
    => #<Date: 4905475/2,0,2299161>

Plain old ruby, however, doesn't give you any Date class at all by default...

> ruby -e 'Date'
-e:1: uninitialized constant Date (NameError)

My solution to this confusion was to add this line to my .irbrc:

require 'date'      # Since irb only gives you ["date/format.rb", "parsedate.rb"] by default!

How to increment by day or month

irb -> (Date.new(2006, 12, 14) + 1).to_s
    => "2006-12-15"

irb -> (Date.new(2006, 12, 14) >> 1).to_s
    => "2007-01-14"

irb -> require 'date'

irb -> date =  Date.strptime('2008-03-16')
irb -> puts date
2008-03-16

irb -> date = date + 7
irb -> puts date
2008-03-23

irb -> date = date >> 1
irb -> puts date
2008-04-23

What's the difference between Time and Datetime??

...

Having Date, Time, and Datetime classes but no easy way to convert between them

Ruby on Rails's ActiveSupport provides the much-needed Time.to_date() conversion...but that should be core Ruby!!

How do you instantiate a Date object with the current date/time? What's the equivalent of Time.now in the Date class?

Date.today

How do I get an ISO-8601 date?

> require 'date'
> Date.today.to_s
    => "2006-08-21"

> DateTime.now.to_s
    => "2006-08-21T13:08:34-0700"

> DateTime.now..to_s[0..18]
    => "2006-08-21T13:14:15"

# For Time objects:
> Time.now.strftime("%Y-%m-%d %H:%M:%S")
    => "2008-07-17 02:25:53"

How do I create a Time object from a Unix timestamp?

>> Time.at(1161200857)
=> Wed Oct 18 12:47:37 PDT 2006

Date: Iterators for days

# Print the days from 2006-11-01 through 2006-11-05
irb -> require 'date'

irb -> ((a=Date.new(2006, 11, 1)) .. a+4).each {|d| puts d.to_s}
2006-11-01
2006-11-02
2006-11-03
2006-11-04
2006-11-05

More examples

irb -> now = Time.now; "#{now.strftime("%a")}, #{now.strftime("%b")} #{now.day}, #{now.year}"
    => "Wed, Nov 1, 2006"

  def date_options(today)
    [
      "Not sure",
      (today + 1 .. today + 13).select { |date|
        Date::DAYNAMES[date.wday] != "Sunday"
      }.collect { |date|
        "#{date.strftime("%a, %b")} #{date.day}"
      }.collect { |option_string|
        [
          "#{option_string} - morning",
          "#{option_string} - afternoon"
        ]
      },
      "Other"
    ].flatten
  end

produces

["Not sure",
 "Thu, Nov 2 - morning",
 "Thu, Nov 2 - afternoon",
 "Fri, Nov 3 - morning",
 "Fri, Nov 3 - afternoon",
 "Sat, Nov 4 - morning",
 "Sat, Nov 4 - afternoon",
 "Mon, Nov 6 - morning",
 "Mon, Nov 6 - afternoon",
 "Tue, Nov 7 - morning",
 "Tue, Nov 7 - afternoon",
 "Wed, Nov 8 - morning",
 "Wed, Nov 8 - afternoon",
 "Thu, Nov 9 - morning",
 "Thu, Nov 9 - afternoon",
 "Fri, Nov 10 - morning",
 "Fri, Nov 10 - afternoon",
 "Sat, Nov 11 - morning",
 "Sat, Nov 11 - afternoon",
 "Mon, Nov 13 - morning",
 "Mon, Nov 13 - afternoon",
 "Tue, Nov 14 - morning",
 "Tue, Nov 14 - afternoon",
 "Other"]

[Libraries (category)]

See also Rails_plugins_and_libraries_/_Lower-level#.5BRuby-level.5D:_Dates_and_times

DateUtils

Chronic

http://chronic.rubyforge.org/

  Chronic.parse('tomorrow')
    #=> Mon Aug 28 12:00:00 PDT 2006

  Chronic.parse('monday', :context => :past)
    #=> Mon Aug 21 12:00:00 PDT 2006

  Chronic.parse('this tuesday 5:00')
    #=> Tue Aug 29 17:00:00 PDT 2006

  Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
    #=> Tue Aug 29 05:00:00 PDT 2006

Exception hierarchy

The rescue statement modifier

Intro

rescue doesn't always have to be used with a begin block. You can do rescues even more concisely.

irb -> raise 'an error' rescue "Hey, there was an error!"
    => "Hey, there was an error!"

Or, most concisely of all:

irb -> raise 'an error' rescue nil
    => nil

It really doesn't get more concise than that for exception handling. If you just want to silence exceptions and you don't want to actually do any intelligent handling of them then rescue nil is your ticket.

Details

When you use rescue as a statement modifier, it rescues StandardError and its subclasses. You can't specify which class of exception(s) that you want to rescue like you can with the normal version of rescue (begin ... rescue Exception => exception ... end, for example).

You also can't do such things as "ensure" when you use this style of rescue.

Caveat: The thing you pass to rescue is what it should do when there's a StandardError -- not the class of exceptions that it should rescue

That fact is a bit confusing, because it's different from the normal begin/rescue blocks.

irb -> begin
         raise "A runtime error"
       rescue RuntimeError
         "The thing that I want to happen when there's a RuntimeError"
       end
    => "The thing that I want to happen when there's a RuntimeError"

but:

irb -> raise "A runtime error" rescue "The thing that I want to happen when there's a RuntimeError"
    => "The thing that I want to happen when there's a RuntimeError"

If you forget this fact, you may be surprised when the error class itself is returned:

irb -> raise "A runtime error" rescue TypeError
    => TypeError

As soon as the error is rescued and you're no longer in the rescue block, $ERROR_INFO/$! resets to nil.

irb -> require 'English'
    => true

irb -> $ERROR_INFO
    => nil

irb -> raise "A runtime error" rescue puts $ERROR_INFO.inspect
#<RuntimeError: A runtime error>
    => nil

irb -> $ERROR_INFO
    => nil
irb -> $!
    => nil

Example: print errors without stopping

Use this trick when you want to see error messages that are raised but you want execution to continue:

irb -> NotARealClass.new() rescue $stderr.puts $!.inspect
#<NameError: uninitialized constant NotARealClass>
    => nil

or just:

irb -> NotARealClass.new() rescue $stderr.puts $!
uninitialized constant NotARealClass
    => nil

http://codeforpeople.com/lib/ruby/autorequire/autorequire-0.0.0/README

    # rescues error and prints its message- support method for samples/*
    #
    def print_error
      yield
    rescue Exception => e
      puts "#{ e } (#{ e.class })!"
    end

Like all things in Ruby, rescue has a return value

This can be useful, for example, when you need to assign a default value to a variable if an error occurs.

irb -> an_important_variable = SomethingThatWillRaiseAnError.do_calculation rescue "a sane default value"
    => "a sane default value"

You may be thinking (if you come from a background in other, less orthogonal languages), how can you do things like rescue puts $!.inspect? You can do that because puts, like all methods and blocks, has a return value.

irb -> a = puts "whatever"
whatever
    => nil

irb -> puts a
nil
    => nil

irb -> a = raise 'arg!' rescue puts 'whatever'
whatever
    => nil

irb -> puts a
nil
    => nil

Can have an ensure without a begin block

def something_that_might_raise_an_error
  raise "an error"
ensure
  puts "that we print this no matter what"
end

something_that_might_raise_an_error rescue puts $!

that we print this no matter what
an error

Object-orientedness

• The Ruby Language FAQ: Classes and modules

Object-orientedness: Classes and objects

Class hierarchy of fundamental classes

I think it's pretty important to get this much clear:

irb -> Class.superclass
    => Module

irb -> Module.superclass
    => Object

irb -> Object.superclass
    => nil

irb -> Class <= Module and Module <= Object
    => true

Class is subclass of Module

I have frequently been confused because I forgot that Class is a subclass of Module. So when I find some method in Module, I fail to realize that I can use that same method in Class as well!

So don't be alarmed, for example, that you can't find Class.class_method_set in the rdoc. Instead, you'll find that there is Module.class_method_set. You can still do this:

irb -> String.send(:class_variable_set, :@@what, 3)
    => 3

Okay, I'm confused. String.superclass is Object, not Class. So how does it inherit class_variable_set from Module?? (Or does it not?)

Class is the only known subclass of Module

If there is any other subclass of Module, please tell me!!

irb -> class Example end
    => nil
irb -> Example.class <= Module
    => true
irb -> Example <= Module
    => nil
irb -> Example.class
    => Class

irb -> "Another".class
    => String
irb -> "Another".class <= Module
    => nil

So you can check if an argument is either a Class or a Module by asking arg.class <= Module.

I think that's exactly what they were doing in the Pickaxe Ruby book, p. 389 in this example:

class Module
  ...
  def Module::doc(aClass)
    # If we're passed a class or module, convert to string
    aClass = aClass.name if aClass.class <= Module
    @@docs[aClass]
  end
end
puts Module::doc(Example)   # Example is a class, so aClass.class is Class, and Class <= Module
puts Module::doc("Another") # "Another" is not a class and is not a module, so it fails that test

(I wonder why they didn't just check aClass.is_a?(Class) or aClass.is_a?(Module)...wouldn't that have been easier to read?)

Reopening a class that has/had a superclass specified

Which of these is legal?:

class B < A
end
class B < C
end
# no!

class B < A
end
class B
end

class B
end
class B < A
end

Inheriting from a ... function (dynamically-determined class)???

/usr/lib/ruby/gems/1.8/gems/rails-1.1.6/lib/rails_generator/commands.rb

  class Base < DelegateClass(Rails::Generator::Base)

Methods

How do you call a class method?

from an instance method of the same class

Here's one way I've found that works:

class Klass
  def my_instance_method
    self.class.my_class_method
  end

I like it only marginally better than:

class Klass
  def my_instance_method
    MyClass.my_class_method
  end

from another class method of the same class

class Klass
  def self.my_instance_method
    self.my_class_method
  end

Overriding methods

"Inside a subclass, calling super is sufficient by itself — you don’t have to specify the method name or arguments. It figures them out automagically from the current method and arguments. It can be overridden if necessary." (http://woss.name/2006/05/07/notes-from-a-rails-course/)

"Mixins (using include) behave as if they are inherited methods. So you can override them and call super and so on, as usual." (http://woss.name/2006/05/07/notes-from-a-rails-course/)

[Obscure useless tip] Can't set self= ? Try replace.

Can't do:

class Array
        def stupid
                self = [self[0]]
        end
end

Will give "Can't change the value of self"

Instead:

class Array
        def stupid
                self.replace [self[0]]
        end
end

replace doesn't necessarily exist in every class, but it exists in Array, Hash, String, ...

Singleton classes: Object-specific classes

See Pickaxe book, Chapter 24. Classes and Objects: How Classes and Objects Interact, p. 382-383

Ruby allows you to create a class tied to a particular object. In the following example, we create two String objects. We then associate an anonymous class with one of them, overriding one of the methods in the object's base class and adding a new method.

a = "hello"
b = a.dup

class <<a
  def to_s
    "The value is '#{self}"
  end
  #...
end
a.to_s      #=> "The value is 'hello'"   [uses to_s from anonymous class that we just created for a]
b.to_s      #=> "hello"                  [uses to_s from String class]

This example uses the class <<obj notation, which basically says "build me a new class just for the object obj." We could also have written it as

#...
def a.to_s
  #...
end
#...

The effect is the same in both cases: a class is added to the object a. This gives us a strong hint about the Ruby implementation: a virtual class is created and inserted as a's direct class. a's original class, String, is made this virtual class's superclass. [...]

Virtual classes / meta classes / singleton classes

Technically, according to the Pickaxe book p. 380-382, each object has a meta/virtual/singleton class associated with it. I'm kind of confused by what difference (if any) there exists between those 3 terms.

Pickaxe p. 382 (Matz):

"Every object in Ruby has its own attributes (methods, constants, and so on) that in other languages are held by classes. It's just like each object having its own class."

"To handle per-object attributes, Ruby provides a classlike something for each object that is sometimes called a singleton class."

"Singleton methods": Adding methods to objects as opposed to classes

When would you want to do that?

• Whenever you only plan on calling the method on that particular method...
• When you don't want to clutter up your base classes with your ["domain-specific"] methods...

[Real-world sightings (category)]

TkVariable example

Pickaxe p. ??:

require 'tk'
...
checked = TkVariable.new
def checked.status
  value == "1" ? "Yes" : "No"
end
status = TkLabel.new do
  text checked.status
  ...
end
...
TkCheckButton.new do
  variable checked
  ...
end
TkButton.new do
  text "Show status"
  command { status.ext(checked.status) }
end

In this example, we add behavior to a single TkVariable object: we add a status method to the checked object. Why do we do that? Because we want the text of a label to be tied to the current result of that method. And we don't want the label to display the non-user-friendly valus "1" or "0"; rather, we want to show something user friendly like "Yes" or "No".

We only use it for this one object, so there's no use in re-opening the TkVariable class and adding the method to all TkVariable objects. Nor do we really want to go through all the work of creating a special container class just to contain a TkVariable object and provide a status method.

Mocha::Expectation#with

http://mocha.rubyforge.org/classes/Mocha/Expectation.html#M000017

     # File lib/mocha/expectation.rb, line 169
169:     def with(*arguments, &parameter_block)
170:       @parameters, @parameter_block = arguments, parameter_block
171:       class << @parameters; def to_s; join(', '); end; end
172:       self
173:     end

Here a to_s method is added to a singleton class created just for the @parameters object.

Problem: you have a method that you want available to Strings objects used by your class but you don't want to litter the base String class with them.

(Very often in the context of: Adding a presentation layer to your data layer.)

Subclassing won't get you anywhere, since you can't control the type of objects returned by other methods (they'll return Strings, not "CustomStrings" (or whatever), so we'll just have to deal with it.)

Also, we don't want to go the procedural, non-OOP way of just calling a global/class-method...

number_to_currency(1234567890.50)     => $1,234,567,890.50

colorize_svn_diff(svn("diff file1"))

Yuck.

We want it to be object-oriented. So it should look closer to this (although not necessarily exactly), with a method being called on the object, rather than the object being passed to some method from another class:

(1234567890.50).to_currency

svn("diff file1").colorize

Rails has a bunch of "helper" methods like this that (I believe) cause your view code to be very un-object-oriented. (See f.i. NumberHelper)

Solution 1: Add these methods to the base class.

Add the methods directly to Float or to String.

Sure that would work...some of the time. But it would be very prone to name collisions. Other libraries that you're using might have had the same idea about adding methods with those names to Float or String. Even within your own application, you may want to have more than one method called "to_currency" or "colorize". You may want to display currencies one way in this report or quite another way over somewhere else.

Solution 2: Singleton methods.

Attempt 1

irb -> def svn(args); "output from `#{args}`"; end
    => nil

irb -> module Svn; module Diff; def colorize; self + " (colorized)"; end; end; end
    => nil

irb -> svn("diff file1").extend(Svn::Diff).colorize
    => "output from `diff file1` (colorized)"

Attempt 2: singleton_send: Create a singleton class with the method you need and then call it, with a single command

irb -> class Object; def singleton_send(mod, *args); self.extend(mod); self.send(*args); end; end
    => nil

irb -> svn("diff file1").singleton_send(Svn::Diff, :colorize)
    => "output from `diff file1` (colorized)"

Published at http://qualitysmithext.rubyforge.org/classes/Object.html#M000027

Duck typing

Pickaxe book p. 367: "In Ruby, the class is never (OK, almost never) the type. Instead, the type of an object is defined more by what the object can do. In Ruby, we call this duck typing. If an object walks like a duck and talks like a duck, then the interpreter is happy to treat it as if it were a duck."

[Example (category)] StringIO

Can use it interchangeably any place that expects a file IO object! It doesn't care! As long as it responds to all the same messages, the users of the object don't care.

[Monkey patching (category)]

Bruce Tate (2007-03-13). Crossing borders: Extensions in Rails: The anatomy of an acts_as plug-in (http://www-128.ibm.com/developerworks/java/library/j-cb03137/index.html). Retrieved on 2007-03-14 16:44.

([reopening classes (category)])(Warning)

In Ruby, you can open up any class and redefine it quickly. This capability is one of Ruby's greatest strengths because of the increased flexibility. But the capability is a weakness too. Too much flexibility can lead to code that's difficult to understand and maintain, so be careful.

[Monkey patching (category)]: If you override attribute my_attr, will it also override my_attr= for you?

alias_method :date_placed, :creation_date

Will that also override :date_placed= as well?

Nope, you need to override that separately:

alias_method :date_placed=, :creation_date=

Is there/should there be another method that does both of these for you? Hmm...

Object-orientedness: Modules and mixins

How do I define class methods in my module that should be mixed into the includer class?

How not to do it:

module ActsAsCat
  def self.acts_as_cat(a)
    ...
  end
end

class ActiveRecord::Base
  include ActsAsCat
end

That doesn't work because when you include ActsAsCat, it although it mixes in all constants, variables, and methods from ActsAsCat into ActiveRecord::Base, acts_as_cat is defined as a class method, not a normal method. Class methods are not mixed in. (This is unfortunate and unintuitive in my opinion. I wonder why it can't be fixed by a future version of Ruby. Discuss)

This works:

module ActsAsCat
  def self.included(base)
    base.extend ClassMethods
  end

  module ClassMethods
    def acts_as_cat(a)
      ...
    end
  end
end

class ActiveRecord::Base
  include ActsAsCat
end

What does it do? base.extend mixes in all the instance methods of ActsAsCat::ClassMethods (acts_as_cat in this case) are mixed into the class represented by base (in this case, ActiveRecord::Base). So they become class methods.

Actually, an easier way to make class methods be mixed in when including is to use Facets' class_extension method.

append_features or included?

You can also define append_features instead of included. What's the difference? Well, the Ruby docs say ...

(http://ruby-doc.org/core/classes/Module.html#M000743) included(mod) is a "Callback invoked whenever the receiver is included in another module or class. This should be used in preference to Module.append_features if your code wants to perform some action when a module is included in another."

(http://ruby-doc.org/core/classes/Module.html#M000719) append_features(mod): "When this module is included in another, Ruby calls append_features in this module, passing it the receiving module in mod. Ruby’s default implementation is to add the constants, methods, and module variables of this module to mod if this module has not already been added to mod or one of its ancestors." This seems like a more fitting place to mix in ClassMethods.

I think we should heed the manual's advice and use "included" "in preference to Module.append_features". Why? (1) It's a nicer-sounding, more intuitive name. (2) The manual says to. (3) Because then we don't have to remember to call super like we would if we overrode append_features.

What does it mean to define a class/module within a class?

Also: [the difference between extend/include (category)] [extended/included (category)]

And why would you want to do such a thing?

class Command
  def initialize(subcommand)
    self.extend(self.class.const_get(:"Subcommand#{subcommand}"))
  end

  module SubcommandA
    def self.extended(base)
      puts "#{self.name} got extended into #{base.class.name}" end
    def self.included(base)
      puts "#{self.name} got included into #{base.class.name}" end
  end

  class SubcommandC
    def initialize
      puts "SubcommandC#initialize"
    end
  end
end

puts Module.constants.grep(/^Command/)
puts Command.constants.grep(/^Sub/).sort.map{|a| '\\ ' + a}
puts

puts "Including/extending at outermost level"
include Command::SubcommandA
self.extend Command::SubcommandA

puts
puts "Command.new(:A)"
Command.new(:A)

puts
puts "What about the *class* within a class?"
Command::SubcommandC.new

It looks like the class SubcommandC defined within the class Command behaves just as if it had been defined within a module named Command. In other words, our class behaved like a module.

That sort of makes sense that a class can be used like a module. It (Class) is, after all, a subclass of Module. (I'm not sure why I was so surprised to see modules defined within classes then!)

irb -> Class.superclass
    => Module

That's actually really nice that Ruby gives you that flexibility. It doesn't arbitrarily say "No, you can't put classes inside of classes! You can only put them in modules." It helps keep things clean because you can use your class for namespacing as well as for data storage (instance variables) and behavior (methods).

What is the outermost scope, actually? What is the receiver then? To what does an include apply?

If every method call has a receiver (an object), then what is the receiver if you just do a "bare word" (not qualified at all) method, like this?:

some_method

irb will tell that it is operating on an instance of (and I don't mean subclass of) Object:

irb -> self
    => main

irb -> self.class
    => Object

So any method calls you make will be directed to that Object object (or Kernel, but that's another topic) unless you tell it otherwise.

You can tell irb to point to a different object, by the way, ...

irb -> irb s
Welcome!

irb#1 -> self
      => "test"

irb#1 -> self[0..0]
      => "t"

Okay, that's nice and all, but what does it mean for me? Well, it would be nice if we understood what happened when we did include at the outer scope.

  module SubcommandA
    def self.extended(base)
      puts "#{self.name} got extended into #{base.class.name}" end
    def self.included(base)
      puts "#{self.name} got included into #{base.class.name}" end
  end
end

puts "Including/extending at outermost level"
include Command::SubcommandA
self.extend Command::SubcommandA

yields:

Including/extending at outermost level
Command::SubcommandA got included into Class
Command::SubcommandA got extended into Object

So it looks like [class methods](?) like include will be received by Class.

(Yes, the Class constant does refer to an object, in case you were wondering...

irb -> Class.object_id
    => -604440958

)

How does Kernel work then?

Question: Kernel is a module. So if the outer scope is Object, how come we're able to call the methods of Kernel (like "puts") as bare names?

It's almost as if Kernel is mixed into Object.

Indeed, that seems to be what this is telling us:

irb -> self.class.ancestors
    => [Object, PP::ObjectMixin, Kernel]

Yet its methods don't show up in Object...

irb -> self.class
    => Object
irb -> self.methods.grep /puts/
    => []
irb -> self.instance_methods.grep /puts/
NoMethodError: undefined method `instance_methods' for main:Object
        from (irb):13

irb -> Object.methods.grep /puts/
    => []
irb -> Object.instance_methods.grep /puts/
    => []

irb -> Kernel.methods(false).grep /puts/
    => ["puts"]
irb -> Kernel.instance_methods.grep /puts/
    => []

..., so was it really mixed in or does Ruby handle Kernel specially (internally)?

The RDoc for Kernel lists puts (and most other methods) under the heading "Public Instance methods". And yet...

If Kernel were actually mixed into Object, we should see behavior more like this...

irb -> module Whatever; def foo; end; end
    => nil
irb -> include Whatever
    => Object

irb -> self.methods.grep /foo/
    => ["foo"]

irb -> Object.methods.grep /foo/
    => ["foo"]

That is, we should see it listed in the Object.methods array. But it isn't.

So again I wonder, how does Kernel work?

Could the Kernels methods (puts at least) actually be class methods?

These are the only instance methods that Kernel claims to have:

irb -> Kernel.instance_methods(false).sort
    => ["==", "===", "=~", "__id__", "__send__", "class", "clone", "display", "dup", "eql?", "equal?", "extend", "freeze", "frozen?", "gem", "hash", "id", "inspect", "instance_eval", "instance_of?", "instance_variable_get", "instance_variable_set", "instance_variables", "is_a?", "kind_of?", "method", "methods", "nil?", "object_id", "pretty_inspect", "private_methods", "protected_methods", "public_methods", "require", "require_gem", "respond_to?", "send", "singleton_methods", "taint", "tainted?", "to_a", "to_s", "type", "untaint"]

So either the RDocs are lying by listing puts in the "Public Instance Methods" section, or I'm not understanding something.

Either way, I'm confused.

Here are some of the class methods provided by Kernel (I only included the interesting/familiar methods in this list, because it's a long list, but you can see that they're all class methods):

irb -> puts (Kernel.methods - Object.methods - Kernel.instance_methods).sort
irb -> require 'qualitysmith_extensions/module/class_methods'
irb -> puts Kernel.class_methods
`
at_exit
binding
block_given?
caller
catch
eval
exec
exit
fork
getc
gets
global_variables
lambda
load
p
pp
print
proc
putc
puts
raise
rand
require
sleep
system
throw

So puts is a class method! ... right?

So when we use these methods as bare names, somehow it knows to find them in Kernel.

Still don't understand how that works, unless Object inherits from Kernel or something, which I doubt they do...

irb -> Object.superclass
    => nil

I know that it's mixed into Object...

irb -> self.class.ancestors
    => [Object, PP::ObjectMixin, Kernel]

but I didn't think that mixing in a module caused the class methods to be added to the includer class. Am I wrong here?

set_trace_func doesn't tell us if the method called was a class method or instance method... Otherwise the following trace might have been more informative...

require 'rubygems'
require 'unroller'
Unroller::trace(:include_c_calls => true) { puts 'hi' }
#Identical output if we do this instead:
#Unroller::trace(:include_c_calls => true) { Kernel.puts 'hi' }

 | - (  c-call)     Kernel block_given? (/usr/lib/ruby/gems/1.8/gems/unroller-0.0.13/lib/unroller.rb:323)
 | - (c-return)     Kernel block_given? (/usr/lib/ruby/gems/1.8/gems/unroller-0.0.13/lib/unroller.rb:323)
 |    Unroller::trace(:include_c_calls => true) { puts 'hi' }           | t.rb:3
 | - (  c-call)     Kernel       puts (t.rb:3 )
 | - (  c-call)         IO      write (t.rb:3 )
hi | - (c-return)         IO      write (t.rb:3 )
 | - (  c-call)         IO      write (t.rb:3 )

 | - (c-return)         IO      write (t.rb:3 )
 | - (c-return)     Kernel       puts (t.rb:3 )

So if we "override" puts by defining a local method of that name, what actually happens? Why can't it find Kernel#puts ?

irb -> def puts; 'nothing'; end
    => nil

irb -> puts
    => "nothing"

And yet we can still access it as a module (class) method!...

irb -> Kernel.puts

    => nil

So it is a module method ... right? It's both? I'm confused.

Actually, it only finds them in Kernel if they don't exist as local methods (in a more local scope). But maybe that's nothing unusually as far as the resolution of instance/class methods goes...

Local methods that match the same name as a Kernel method will be used instead of the Kernel method

So we can "override" methods sort of like this...

irb -> def exec; end
    => nil

irb -> exec
    => nil

We're not actually overriding the method when we do this however -- the Kernel method is still callable if we qualify the method call with some scope information -- we're just taking advantage of the [method call resolution order] of Ruby: instance methods, then class methods (?).

irb -> Kernel.exec('date')
Wed Feb 21 09:48:26 PST 2007

(To actually override a Kernel method, just re-open the Kernel class.)

Question: If we override `, however, how do we call the Kernel version???

irb -> def `(*args); p args; end
    => nil

irb -> `date`
["date"]
    => nil

irb -> Kernel.`hi`
(irb):19: warning: parenthesize argument(s) for future version
SyntaxError: compile error
(irb):19: unterminated string meets end of file
        from (irb):19
        from :0

irb -> Kernel.`(hi)
     " `
SyntaxError: compile error
(irb):24: unterminated string meets end of file
        from (irb):24
        from :0

Well, when lacking a more elegant solution, the send method usually gets the job done!

irb -> Kernel.send(:`, 'date')
    => "Wed Feb 21 10:07:11 PST 2007\n"

What does/can a mixin do?

http://www.rubycentral.com/book/classes.html

When a class includes a module, that module's instance methods become available as instance methods of the class. It's almost as if the module becomes a superclass of the class that uses it. Not surprisingly, that's about how it works. When you include a module, Ruby creates an anonymous proxy class that references that module, and inserts that proxy as the direct superclass of the class that did the including. The proxy class contains references to the instance variables and methods of the module.

(This means you can call super from a class and it will call the corresponding method of (one of) the modules that it has mixed in.)

Mixins: What's a mixin?

Bruce Tate (2007-03-13). Crossing borders: Extensions in Rails: The anatomy of an acts_as plug-in (http://www-128.ibm.com/developerworks/java/library/j-cb03137/index.html). Retrieved on 2007-03-14 16:44.

A module has method definitions, but no base inheritance hierarchy. Instead, you can attach modules to any existing Ruby class. If the concept is new to you, think of a module as an interface plus the implementation for that interface. The nice thing about a module is that you can attach its functionality to any existing Ruby class, and you can attach as many as you want. You can also leverage a class's existing capabilities. This technique is called mixing in. C++ uses multiple inheritance to provide a similar capability, but with ugly complications. The Java founders eliminated multiple inheritance to address those complications. With modules, you can get some of the benefits of multiple inheritance without the sticky complications. Languages such as Smalltalk and Python also support mix-in inheritance.

Mixins: who needs multiple inheritance?

Brown, Gregory (2007-01-11). inheritance concept in ruby (http://groups.google.com/group/comp.lang.ruby/browse_thread/thread/aac34ed1e5ac40d1/c7b7d59e35c8ff25?lnk=gst&q=inheritance). Retrieved on 2007-02-02 11:20.

The real complication with multiple inheritance is that you end up inheriting the ancestors of both parent classes. When you use a mixin, the additional methods are tacked on to a class in the heirarchy, rather than creating another set of ancestors. Since modules live outside of the tree of inheritance, they can be used to provide functionality without complicating the ancestry chain. See Comparable and Enumerable for excellent and practical uses of modules.

In which cases do the two scenarious (M.I. and mixins) cause different behaviors? Is it only related to member visibility? If yes, how exactly?

if:

A < B < C

and module D is mixed into C, there is still a single path back to A.

Had we used multiple inheritence (if it were possible), perhaps

F < E < D

so now, C has two distinct roots, A and F.

Now imagine circular dependencies and other complications. Scary! :)

So modules allow you to avoid the verbosity of interfaces without complicating the chain of ancestors.

Brown, Gregory (2007-01-12 12:13). inheritance concept in ruby (http://groups.google.com/group/comp.lang.ruby/browse_thread/thread/aac34ed1e5ac40d1/c7b7d59e35c8ff25?lnk=gst&q=inheritance). Retrieved on 2007-02-02 11:20.

That is, the exact same thing happens when you have a class include two modules and both implement the 'hello' method. There is no self-evident way of choosing, so you have to come up with an arbitrary choice like that of order of call to 'include'.

Yes, this is true.

However the issue is rarely with immediate dependencies, but dependency chains.

I.e., with mixins,

If I have A->B->C and C mixes in D, then E

the lookup is C,E,D,B,A

which logically is quick intuitive if you think about it.

If I have A->B->C

and  ?->D->C

and

?->E->C

Those two question marks represent two independent dependency chains that you cannot be sure what they implement without knowing the ancestors of each.

Since modules live outside of the hierarchy, you will only be likely to run into this problem with bad design. The point of mixins (and multiple inheritance) really, is to address orthogonal concerns. Name collision is a sign of either a code smell, or just a really complex system that is going to need a lot of thought to begin with.

Brown, Gregory (2007-01-19 20:20). Digging Deep: Mixing it up (or in) with Modules (http://www.oreillynet.com/ruby/blog/2007/01/digging_deep_mixing_it_up_or_i_1.html). Retrieved on 2007-02-02 11:20.

So this post will focus on a recent topic on RubyTalk, the merit of using Mixins as a suitable replacement for multiple inheritance.

Overview

If you haven’t worked with multiple inheritance before, or aren’t familiar with object oriented programming, this article isn’t going to be super helpful. However, as a quick review, the core concept of multiple inheritance is that an object can have more than one parent class. For example, perhaps you have a Student class, and you want to say Joe is a student, but he’s also a musician and a rubyist. Single inheritance would not let you have this kind of structure without awkward hackery, so multiple inheritance would make life easier.

Though I’m sure there are folks out there who can explain why Java’s interfaces help simplify things in some cases, this sort of thing is a notorious source of annoyance in Java. A lot of times single inheritance just doesn’t do the trick. So often when folks hear that Ruby is single inheritance, they get sort of nervous.

On the gripping hand, there are plenty of languages in which incorrect use of MI can really bite you. C++ and Perl would be common culprits [...].

Ruby I suppose is lucky enough to be able to happily steal good ideas and throw away the bad ones. With this in mind, I think the Mix-in idea really fits the language.

But isn’t a Module just a container / a crippled Class ?

A short definition of a Module would likely be ‘a ruby class that cannot be instantiated and does not live within the class hierarchy’. It wouldn’t be 100% complete, but it’s enough to work with.

This at first sounds inconsequential. But the semantic power that such a construct provides is rather vast. David Black mentioned that he likes the idea of having both a noun like construct as well as an adjective like construct available for modeling.

That’s is a pretty good way to put it. This object is an Array. It is Enumerable.

If you look closely, you’ll see the distinction. The relationship is not really an ‘is a’ for the latter, but more describes some behavior the object has. It’s noun vs. adjective, when it all boils down.

...

I see the point, but I still don’t get how to use these things in my modeling

Basically, if you’re already familiar with modeling multiple inheritance in a sane way, the leap to mix-ins will be relatively small. However, if you’re new to the concept, it might take a little extra leap. Going back to David’s analogy, classes are our Noun component and modules our adjective.

Perhaps we have a Record construct and we want to be able to add tags to these records( a la folksonomy ). This is an ideal time to say an object with the ability to be tagged is Taggable, which is a nice adjective, and makes a nice module.

Subclasses vs. mixins

Hodel, Eric (2006-08-23). Subclassing vs include (http://blog.segment7.net/articles/2006/08/23/subclassing-vs-include). Retrieved on 2007-02-02 11:51.

In memcached Basics for Rails Rob Sanheim asked: [W]hy make the cached model a class to extend instead of a module? Whether or not a model is cached should be an implementation detail, and shouldn’t define the hierarchy for a class. I know I would rather not use the power of (single!) inheritance just to cache something, when a mix-in should be plenty powerful to do it. The short answer is: Using a class the correct way to overlay features on top of another class. Here’s my long answer: When you use a class you get super, and super is a beautiful thing. It automatically walks your class’ ancestors and calls the right method in the right order. A module doesn’t have this property so you can’t use it to overlay features on top of a class. The class’ implementation will always be called before the module’s implementation. Now you’re going to say something about using alias to shuffle methods around. You could do that, but you’ll have to do this for each method you want to overlay (five in CachedModel) which involves lots of extra typing “do_the_thingy_without_the_stuff” that you could have had for free (and more-prettily) with “super”. You also get another problem that may cause subtle bugs. When you use alias to overlay features the order of execution is dependent upon the order the files are required in! Intentionally writing code where the behavior may change file load order gives me the heebie-jeebies. Having to do all that work to get the benefits of a subclass tells me that a module isn’t powerful enough to do what a subclass can, so a module isn’t the right way to add a cache. I avoid* using modules to overlay features of a class, but do use them to add orthogonal or complementary features. Typically when I write a module it ends up being used like Comparable, Enumerable or Singleton. When I need to do something invasive a subclass is better. Finally, making the argument that adding caching to ActiveRecord::Base via a subclass shouldn’t define the inheritance argument is very subjective. I could justify using a subclass by saying that ActiveRecord is a data storage class, and CachedModel is just another data store. If you want caching, inherit from CachedModel. If you don’t want caching, inherit from ActiveRecord::Base. Jim Weirich said 1 day later: Hi Eric, I’m not sure I’m following your reasoning. Eric: When you use a class you get super, and super is a beautiful thing. Agree about the beauty thing. But modules participate in super chaining as well. [How?] Eric: A module doesn't have this property so you can't use it to overlay features on top of a class. The class's implementation will always be called before the module's implementation. The current class's methods will be called before both the module and the parent class. The module functions will be called before the parent class. Which seems to be the right thing to do. Unless you are talking about something more subtle where the module is mixed-in in more than one place in the inheritance heirarchy. Thanks. Rob Sanheim said 1 day later: Hi Eric, Thanks for the detailed response. I’m curious as to why a module wouldn’t work wrt the point Jim made. I’m aware of the amount of magic going on in the finder methods, so I agree 100% things could get very nasty if you had to alias and chain things… Regarding the inheritance issue – it just seems to me that having a “Cacheable” module makes much more sense (assuming the implementation isn’t horrible). In a perfect world, I’d also prefer including ActiveRecord::Base so my business models could extend from anything, and possibly also mixin ActiveCVS, ActiveLDAP, etc. I see the models main concern being the business logic and data, and how that data gets persisted is secondary. That said, I’ll admit my real world code hasn’t yet seen the need for abstract business superclasses, so Ruby’s power might allow metaprogramming to take the place of deeper class hiearchies. Eric Hodel said 2 days later: Jim: Lately I’ve seen lots of use of modules for layering functionality on top of classes implemented so that you don’t have to add include Blah into every subclass, particularly from rails. (For example flash.rb, from an older revision so its more clear.) I find this particularly messy. CachedModel needs to override both instance and class methods, and include only adds instance methods. To work around this Rails adds a ClassMethods module and automatically includes it as appropriate. I find a separate module for extending class methods isn’t nearly as readable or organized as having everything in one place. I also can’t remember when which callbacks get called when, but super is simple and easy to understand. ... James Mead said 11 days later: Perhaps the more pertinent question is – should ActiveRecord::Base be a class? It could be argued that both persistence and caching are orthogonal concerns relative to the business logic of your domain.

[extension/non-core] Passing parameters along with your include

/usr/lib/ruby/gems/1.8/gems/facets-1.8.51/lib/facets/more/paramix.rb (Should be documented on the Module class page, but it seems that dependency.rb's documentation "trumped" that)

  module Mixin
    def hello
      puts "Hello from #{Mixin(:name)}"
    end
  end

  class MyClass
    include Mixin, :name => 'Ruby'
  end

  m = MyClass.new
  m.hello -> 'Hello from Ruby'

(What's the difference between the terms "iterator" and "enumerator", by the way? I think iterator is the preferred term most of the time.)

Things you can do with Enumerable objects

• inject
• map
• ...

delete_if (Array)
delete_if (Set)
delete_if (Hash)

concise iterator/map/collect calls with Symbol.to_proc

A very concise way to use map to do a method call on all elements

(requires http://extensions.rubyforge.org/)

irb -> require 'rubygems'
irb -> require 'extensions/symbol'

irb -> :size.to_proc
    => #<Proc:0xb7bfab00@/usr/lib/ruby/gems/1.8/gems/extensions-0.6.0/lib/extensions/symbol.rb:24>

irb -> ["three", "different", "words"].map(&:size)
    => [5, 9, 5]

       # The old-school method that you'll never go back to now that you know the concise alternative:
irb -> ["three", "different", "words"].map{|a|a.size}
    => [5, 9, 5]

How does it work? PragDave has a great explanation. "It’s an incredibly elegant use of coercion and of closures." I agree!

Example uses

Accumulate/sum up some numbers:

irb -> require 'rubygems'
irb -> require 'extensions/symbol'

irb -> sum = [3, 1, 9, 6].inject(&:+)
    => 19

irb -> %w{a couple words}.map(&:capitalize).join(' ')
    => "A Couple Words"

irb -> require 'rubygems'
irb -> require 'extensions/symbol'

irb -> f = File.open('foo', 'w') { |f| f.puts 'line1'; f.puts 'line2' }
    => nil

irb -> File.readlines('foo')
    => ["line1\n", "line2\n"]
irb -> File.readlines('foo').map(&:chomp)
    => ["line1", "line2"]

Enumerable#map_send(meth, *args) {|e.send(meth, *args)| ...} [Ruby Facets (category)]

http://facets.rubyforge.org/src/doc/rdoc/core/classes/Enumerable.html#M001330

# File lib/facets/core/enumerable/map_send.rb, line 3
  def map_send(meth, *args)
    if block_given?
      map{|e| yield(e.send(meth, *args))}
    else
      map{|e| e.send(meth, *args)}
    end
  end

Sometimes Symbol#to_proc isn't enough because it doesn't let you pass args. map_send is the answer to this!

irb -> require 'facets/core/enumerable/map_send.rb'

irb -> [1,2,3].map_send(:+, 3)
    => [4, 5, 6]

Enumerable#every / Array#every! [Ruby Facets (category)]

http://facets.rubyforge.org/src/doc/rdoc/core/classes/Enumerable.html#M001236

Returns an elementwise Functor. This allows you to map a method on to every element.

irb -> require 'facets/core/enumerable/every'

  [1,2,3].every + 3           #=> [4,5,6]

  ['a','b','c'].every.upcase  #=> ['A','B','C']

Arguably more readable than map.

irb -> require 'facets/core/enumerable/map_send.rb'

irb -> [1,2,3].map_send(:+, 3)
    => [4, 5, 6]

How do I collect an "each"-type iterator as a collection?

irb -> "tyler".each_byte {|l| p l }
116
121
108
101
114

How do I convert that into the array [116, 121, 108, 101, 114] instead?

Sure, I can do this:

irb -> a = []; "tyler".each_byte {|l| a << l }; a
    => [116, 121, 108, 101, 114]

But isn't there a more elegant way???

Yes! See next question...

How do I turn an "each" into a "map"?

Use an Enumerable::Enumerator object! Very handy.

The plain map method is equivalent to this:

Enumerable::Enumerator.new(object, :each).map{|value| value}

Example:

irb ->  require 'enumerator'

irb ->  Enumerable::Enumerator.new(['a', 'b', 'c'], :each).map{|value| value}
    => ["a", "b", "c"]

irb -> ['a', 'b', 'c'].map{|value| value}
    => ["a", "b", "c"]

Fine, you don't need an Enumerator to do that... But to "catch" the values that are yielded by other values and get them returned as an array, I really don't know any other good way to do it...

irb -> Enumerable::Enumerator.new(['a', 'b', 'c'], :each_with_index).map{|value, index| [index, value]}
    => [[0, "a"], [1, "b"], [2, "c"]]

irb -> Enumerable::Enumerator.new(['a', 'b', 'c'], :each_with_index).map{|value, index| "#{index+1}. #{value}"}
    => ["1. a", "2. b", "3. c"]

...

Kernel#enum

require 'qualitysmith_extensions/kernel/enum'

Why would you want an "each" to be a "map"?

When you want to chain several "map"-type iterators together, that's when.

irb -> "line 1\nline 2".each_line {|line| "* #{line}"}.map {|line| (' '*2) + line}
    => ["  line 1\n", "  line 2"]

We wanted the each_line to prefix the line with a bullet. But that's not what happened. each_line actually returns the receiver unchanged!

irb -> "line 1\nline 2".each_line {|line| "* #{line}"}
    => "line 1\nline 2"

That's fine with that iterator is the "end of the line", so to speak (the last iterator in a chain of iterators):

irb -> "line 1\nline 2".each_line {|line| puts "* #{line}"}
* line 1
* line 2
    => "line 1\nline 2"

... but not so cool when you want to chain something on after it.

Solution with Enumerators:

irb -> require 'enumerator'
    => true

irb -> Enumerable::Enumerator.new("line 1\nline 2", :each_line).map {|line| "* #{line}"}.map {|line| (' '*2) + line}
    => ["  * line 1\n", "  * line 2"]

But what if you want that enumerator in the middle of a chain of map-type iterators?

How to insert an enumerator in the middle of a chain of map-type iterators

We want to do something sort of like this (but obviously not exactly like this):

irb -> n = 3; (1..n).to_a.map {|i| "line #{i}"}.join("\n").Enumerable::Enumerator.new(our_string_weve_built_so_far, :each_line).map {|line| "* #{line}"}.map {|line| (' '*2) + line}
NoMethodError: undefined method `Enumerable' for ["line 1", "line 2", "line 3"]:Array
        from (irb):9
        from :0

We could probably solve this with a Functor. But, more directly (no extra classes) and generically, we could solve it like this:

irb -> class Object; def with_self; yield self end; end
    => nil

irb -> n = 3; (1..n).to_a.map {|i| "line #{i}"}.join("\n").with_self {|our_string_weve_built_so_far| Enumerable::Enumerator.new(our_string_weve_built_so_far, :each_line)}.map {|line| "* #{line}"}.map {|line| (' '*2) + line}
    => ["  * line 1\n", "  * line 2\n", "  * line 3"]

That's pretty ugly and verbose, though. Let's see if we can concisify it a bit. I see that Enumerable defines several "enum_" methods. I'm very curious why they didn't throw in a generic "enum" method that let you pass in the name of the iterator to be used.

irb -> [].class.ancestors
    => [Array, Enumerable, Object, PP::ObjectMixin, Kernel]

irb -> Enumerable.instance_methods.grep /^enum/
    => ["enum_slice", "enum_cons", "enum_with_index"]

No matter. We'll just write our own.

http://code.qualitysmith.com/gemables/our_extensions/lib/enumerable/enum.rb

irb -> require 'enumerator'
irb -> module Enumerable def enum(iterator) Enumerable::Enumerator.new(self, iterator) end; end
    => nil

And we can see that it works marvelously:

irb -> n = 3; (1..n).to_a.map {|i| "line #{i}"}.join("\n").enum(:each_line).map {|line| "* #{line}"}.map {|line| (' '*2) + line}
    => ["  * line 1\n", "  * line 2\n", "  * line 3"]

[good example of iterator] all?

tasks/install_tasks.rake [Not yet released (category)]

      if !status.empty? and status.all? { |line| line =~ /^\?/ or line =~ /^A.*\.$/ }
        SVN.add '*'
        SVN.remove_without_delete 'log/*.log'
      end

Translated to English: if all of the status lines returned by Subversion begin with a ? or an A, then...

[good example of iterator] collect + max

This block of code goes through each of the task objects, looks at the length of its name, and uses the highest one as the width for display purposes.

      width = displayable_tasks.collect { |t|
        t.name.length
      }.max

collect actually returns an array containing all the lengths, and then max gets the highest item in the array.

From: /usr/lib/ruby/gems/1.8/gems/rake-0.7.1/lib/rake.rb :

    def display_tasks_and_comments
      displayable_tasks = Rake::Task.tasks.select { |t|
        t.comment && t.name =~ options.show_task_pattern
      }
      width = displayable_tasks.collect { |t|
        t.name.length
      }.max
      displayable_tasks.each do |t|
        printf "rake %-#{width}s  # %s\n", t.name, t.comment
      end
    end

each_line

irb -> "a\nb".each_line {|a| puts a }
a
b
    => "a\nb"

General

Debugging Ruby can be made difficult when the classes/modules you are working with may have been reopened any number of times anywhere in your code base. By the time other modules have been mixed in and methods overrided, the resulting class may be completely different than how you think it is. How do you even know what methods exist??

These might help a little:

• Object#public_methods
• Object#private_methods
• Object#protected_methods
• instance_variables
• instance_methods

How to examine call stack?

• Kernel#caller

Debugging: Why can't it load [filename]??

Say, for instance, it's not finding a file named 'foo' when you do require 'foo'.

• The first thing to check, of course, is the spelling of the filename.
• Next, check $LOAD_PATH... The file (relative path) must exist in one of the paths listed there, or it won't find it.
• Unless you're using RubyGems or some other library that changes the default behavior of require/load...

Here's some debug code I used one time. Not sure it's generally useful though...

  p $LOAD_PATH

  $LOAD_PATH.each {|d| print "For #{d}:"; p    (Dir.entries(d).grep(/foo/) rescue []) }
  puts "Was found in: " + $LOAD_PATH.find {|d| (Dir.entries(d) rescue []).include?('foo.rb') }

  require 'foo'

Problem: inspect is too verbose?

Here's one way to just have it print the methods you care about:

[:whatever, :some_method].each {|method| puts "#{method} = #{self.send(method)}"}

as an alternative to:

puts self.inspect

Also consider using pp object or puts object.to_yaml, as they can be far more readable a lot of th etime.

Problem: you can't always print to stdout to do debugging

Sometimes I look at someone else's code (like Rails) to try to figure out how it works. Sometimes just looking at the code doesn't tell me enough; I need to inspect the values of variables as they are running.

So.... I can either try to mess with the breakpointer/debugger... or I could just dump the values I want to a file and inspect it after I run the code.

You never know what logging facilities are available. Best to just rely on primitive built-in file-writing mechanism, like those that the File class provides.

Make sure your ~/temp directory is writable, and then add this wherever you want to dump stuff.

File.open("/home/tyler/temp/debugging.log", "a") { |file| file.puts an_interesting_variable }

or

    File.open("debugging.log", "w") { |file| file.puts '' }
    def out(out); File.open("debugging.log", "a") { |file| file.puts out }; end

watch cat $debugging.log

Why doesn't it show the entire backtrace?

[Questions (category)][Problems (category)]

Sometimes, when the backtrace is really long, Ruby tries to be helpful and omits part of the backtrace (replacing the omitted section with the number of lines that were omitted, as in "... 54 levels...", sort of like this:

./script/../config/../../lib/rails_profiler.rb:39:in `log': You have a nil object when you didn't expect it! (NoMethodError)
The error occurred while evaluating nil.info    from ./script/../config/../vendor/rails/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb:145:in `execute'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb:346:in `catch_schema_changes'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb:145:in `execute'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb:160:in `insert'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/base.rb:1811:in `create_without_callbacks'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/callbacks.rb:254:in `create_without_timestamps'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/timestamp.rb:39:in `create'
        from ./script/../config/../vendor/rails/activerecord/lib/active_record/base.rb:1789:in `create_or_update_without_callbacks'
         ... 54 levels...
        from ./script/../config/../vendor/rails/activesupport/lib/active_support/dependencies.rb:495:in `require'
        from ./script/../config/../vendor/rails/railties/lib/commands/server.rb:40
        from ./script/server:4:in `require'
        from ./script/server:4

I have to say, however, that despite the good intentions of whomever added this "feature", it is often not helpful. What if I want to see the entire backtrace?

Unfortunately, I don't think there's any (easy, built-in) way to enable the showing of the full backtrace.

Instead one is forced to rescue the exception yourself and print out the full backtrace.

You have to go to (one of the) outer file (the one listed at the bottom of the incomplete backtrace), and surround the offending line/lines with something like this:

begin
  # block within which the exception is raised
rescue Exception => exception
  puts exception.class.name + ": " + exception.message
  puts exception.backtrace.join( "\n" )
end

So it's doable, but a bit of a pain...

And you have to remember to remove that code when you are done...

References:

• http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/98649 Re: Can't see entire traceback

Libraries

Unroller

RuntimeProfile