Struggling With Ruby

Printing Labels

2010-11-25T21:17:00.002Z

I recently had a need to print labels from our database. The factory produces samples; the idea is that they enter the samples into the database, which spits out a label to stick on it. Analysts then update the record as the results come in.

After some rather lengthy discussions with my IT supplier we went for a Zebra GK420t label printer. The accompanying CD has a manual for programming in a language called ZPL, allowing me to set up my labels with complete flexibility.

Configuring a Printer Port

I am in a Windows environment, and some of this is specific to Windows.

The general strategy is to use Ruby to create a file, and then copy the file to the serial port. Most PCs nowadays do not have a serial port, but you can pretend the printer is on a serial port using the "net use" command at the DOS prompt. It is first necessary to share your printer on the network. Then, at the server where your project is run from, type something like this (comp01 is the computer's network name, zebra is the share name for the printer):

net use lpt4 \\comp01\zebra /persistent:yes

You can check if the printer is still assigned to that port using "net use".

If only it were that simple. Windows runs services in their own environment, so setting the printer at the prompt is great for when you are developing the project, as you run your web server from the command prompt. Then you go live, and now the project is run as a service on Tomcat or whatever, and has no clue about what you have done at the command prompt.

The way I got around this was to put code into a file in config/initial, like this:

printer = File.read('config/printer.cfg').strip
command = "net use lpt4 \"#{printer}\""
`net use lpt4 /delete`
result = `#{command}`

Everytime Rails starts up, this reads the printer name from a file called config/printer.cfg, deletes the old setting and applies the new.

Printing

Using the "copy" command, you can now send a file to the printer. I think it is useful to try that before getting into Ruby to ensure that works, so here is an example ZPL file (for labels 100x50 mm).

^XA
~SD15
^LL200
^PW750
^FO50,60^ADN,36,40^FDMy first line^FS
^FO50,110^ADN,36,20^FDA second line^FS
^FO50,160^ADN,36,20^FDThe third line^FS
^FO50,220^ADN,18,10^FDMy company^FS
^FO50,245^ADN,18,10^FDCreated at 1847 on 13/Sep/10^FS
^FO35,50^GB680,160,2^FS
^XZ
END

Here is some Ruby code that will generate a new file on the fly, and send it to the printer. Note that ZPL does not require that data is sent in the order in which it appears on the label.

require 'date'

class Printer
PRINTER = 'lpt4'
COMPANY = 'My Company Ltd'

def self.print_label lines
  # Accept either a string with line breaks embedded,
  # or an array of strings
  # (assume each line is not too long)
  lines = lines.split("\n") if lines.is_a? String

  # A "here document" defines the basic label,
  # With a box, date and company name
  text = <<-END
    ^XA
    ~SD15
    ^LL200
    ^PW750
    ^FO50,#{70 + 50 * lines.length}^ADN,18,10^FD#{COMPANY}^FS
    ^FO50,#{95 + 50 * lines.length}^ADN,18,10^FDCreated at #{DateTime.now.strftime('%H%M on %d/%b/%y')}^FS
    ^FO35,50^GB680,#{10 + 50 * lines.length},2^FS
    ^FO50,#{60}^ADN,36,40^FD#{lines[0]}^FS
    END

  # Each line sent is now added
  (1..lines.length).each do |i|
    text << "^FO50,#{60 + 50 * i}^ADN,36,20^FD#{lines[i]}^FS\n"
  end

  # The file terminator is tagged on the end
  text << "^XZ"

  # The file is created
  File.open("print.txt", "w") { |file| file << text }

  # In Rails, stop at this point if in a unit test
  return 'not printed' if RAILS_ENV == "test"

  # Create a DOS command
  command = "copy #{RAILS_ROOT}/print.txt #{PRINTER}"

  # Usually Ruby will convert forward slashes to backslashes
  # in Windows, but not here
  command.gsub! '/', '\\'

  # Use backticks for the system command
  # so we can capture the output
  result = `#{command}`

  # Printed okay
  return 'label printed' if result =~ /1 file\(s\) copied/

  # Problem, so return the error message and command
  "Label failed with error \"#{result}\", command was \"#{command}\""
end
end


Printer.print_label ["My first line", "A second line", "The third line"]

You may want to consider whether two people might try to print at the same time. If the second writes a new file before the first has printed it, both users will get the second label. My understanding is that Rails handles one request at a time, so I do not think this is a problem, and for me, uses will only be printing from a single computer anyway.

Struggling with Ruby: Contents Page

Monkeybars, a UI framework

2010-11-06T13:57:00.001Z

Finding a decent UI for use with Ruby is something of an on-going quest. I blogged a couple of years ago about Ruby Shoes, which is a very neat idea, but is limited, and not really suited to big projects. I am not too sure how well it is being supported nowadays, though there is some activity at GitHub.

So recently I was looking at Monkeybars. Monkeybars is not a UI as such, but a framework for using Swing inside an IDE. It attempts to hide all the underlying Java, so you just design your interface through your IDE, and the rest is Ruby (specially, JRuby of course, for Swing).

There is a problem with Monkeybars; it does not work with recent versions of JRuby. I found an older version in an example file, and that works old (I have reported this as a bug here).

Installation

Installing is simple (this will also install the "rawr" gem):

gem install monkeybars

Create a project

To create a new project:

monkeybars my_project
cd my_project
rawr install

You than need to set it up in your IDE. Monkeybars was designed with NetBeans in mind, and that is the IDE I use too (it obviously needs both Ruby and Java included). It needs to be a Java project, as you are actually running a Java application that uses Ruby, so your new NetBeans project will be a "Java Project with Existing Sources". You need to point NetBeans to the source packages in the "my_project/src" folder. Once the project is created, right click on "Libraries" in the project browser, select "Add JAR/Folder" and select the .jar files in "my_project/lib/java".

When you first run your project, NetBeans will ask for the main file; select "org.rubyforge.rawr.Main"

Create your model-view-controller

Just like Rails, you can use a rake task to generate these (in ths example, called "main"):

rake generate ALL=src/main

This will generate the files:
* src/main/main_controller.rb
* src/main/main_view.rb
* src/main/main_model.rb

Create the UI

You actually need a fourth file, which is the UI itself. In the IDE, right click on the folder (in this case "main") in the project browser, and select New - JFrame Form, and give it a suitable name (I chose MainJFrame). You can now add components graphically, using your IDE. The important point to remember is that any component you want your Ruby code to interact with should have a Ruby-friendly name. A "Quit" option on the file menu might be "quit_menu_item", but the menu itself you can leave to the default.

To keep it simple, drag a label on to the dialog box, and set the variable name (found under the code tab) to "message".

Edit the view

The main_view.rb file is the glue between the Java UI and your Ruby code. The first thing it needs is the name of your Java UI. Then it needs to know how the components on the UI map (or more accurately, properties of the components) to the model. In this example, then we need only two lines.

class MainView < ApplicationView
set_java_class 'main.MainJFrame'
map :model => :message, :view => "message.text"
end

You can have as many map statements as you need, one for each component that displays data (not required for buttons, etc. that generate events only). The :view part means that one end of the link is to the text property of the JLabel that we called "message". The other end of the link is the message property in the model.

You can set a mapping to be one way, by adding a :using value. In our example, the label cannot be edited directly by the user, so we only want the data to go from the model to the UI component, not the other way around (you can flip "nil" and ":default" to have the data go the other way only, but your model needs to provide read and write access to the property even so, because of the way Monkeybars creates a new model with the view data, then transfers data from that to the real model).

map :model => :message, :view => "message.text", :using => [:default, nil]

You can also use the ":using" value to specify a method to convert the data; give the method name instead of :default.

Edit the controller

The controller needs to be told the name of the model, and the name of the view. You can also set an action for when the dialog close is clicked. All of this is done for you, and is all we need for this simple application.

class MainController < ApplicationController
set_model 'MainModel'
set_view 'MainView'
set_close_action :exit
end

However, if you have any way for the user to interact with your dialog box, that gets captured here. Let us suppose you have a "Quit" option on yor file menu, and you have set the variable name to "quit_menu_item". This method will respond to that menu item being selected, and ask for confirmation.

def quit_menu_item_action_performed
r = javax.swing.JOptionPane.showConfirmDialog(nil,
          "Do you really want to quit?",
          "Confirmation",
          javax.swing.JOptionPane::YES_NO_OPTION,
          javax.swing.JOptionPane::QUESTION_MESSAGE)
exit if r == javax.swing.JOptionPane::YES_OPTION
end

Here is another example for a button; the user presses the button and the text in two JTextAreas is used to update the model (the first JTextArea is called "text_area_1", but mapped to "text1" in the model, using map :model => :text1, :view => "text_area_1.text" in the view). The update_model method is used to transfer data to the model. Then the update method in the model is called (this is a method I have written, to do what I need in my model). Finally, update_view is called so the UI is updated to reflect the new state of the model.

def update_button_action_performed
model.text1 = view_state.model.text1
model.text2 = view_state.model.text2
model.update
update_view
end

What happens is that calling view_state creates a new instance of the model, and this is populated with the values from the UI. You can then copy across the values you want into the real model. A convenience method, update_model, can be used instead.

def update_button_action_performed
update_model(view_state.model, :text1, text2)
model.update
update_view
end

This is how the controller will handle most events, first transfer the data from the UI to the model, then call a method in the model, then update the view, so you could have one method to create a whole set.

%w(up down edit cut paste insert).each do |action|
%w(button menu_item).each do |type|
  class_eval <<-"END"
    def #{action}_#{type}_action_performed
      model.text = view_state.model.text
      model.#{action}
      update_view
    end
  END
end
end

You can set the value for set_close_action to :nothing, :exit, :close, :dispose or :hide. If you want other functionality, override one of those methods in the controller (I found I could override close, but not exit).

Edit the model

The model needs to include accessor methods for all the properties you mapped to in the view, and methods for all the actions. In our simple example, like this:

attr_accessor :message

You can set properties through properly defined methods, but that is something of a minefield, I have found, and better avoided.

There is no more to say about the model; Monkeybars makes no assumptions about it, and it has no parent class to inherit from (other than Object). This is where you do the real work.

Struggling with Ruby: Contents Page

Iterating through records

2010-06-01T20:48:00.002+01:00

Occasionally, you want to be able to go through the records in a table one by one, i.e., from a page showing one record, you want to be able to jump to the next or previous record. One way I have seen to do this is with named_scopes. i like named_scopes, but really, they are not the solution in this case; a simple method for the model is more elegant. Compare:

Post.forward(@post)[0]
@post.forward

Note that a named_scope returns an array. Also, I have called the method forward, as next is a keyword in Ruby. Here are the two methods to go either way.

def forward
 Post.find(:all, :conditions => ["id > ?", id], :limit => 1, :order => "id ASC")[0]
end

def back
 Post.find(:all, :conditions => ["id < ?", id], :limit => 1, :order => "id DESC")[0]
end

If you want a looped list, you can use these two methods, which will loop around to other end of the list. They use the fact that nil is taken as false, and that Ruby uses lazy evaluation for Boolean arithmetic. he scond part of the expression is only evaulated if the first works out to be nil. There is also a random method, so you can jump around the list. I have made this a class method so you can also jump into a random point in the list.

def forward
 Post.find(:all, :conditions => ["id > ?", id], :limit => 1, :order => "id ASC")[0] || Post.find(:first, :order => "id ASC")
end

def back
 Post.find(:all, :conditions => ["id < ?", id], :limit => 1, :order => "id DESC")[0] || Post.find(:first, :order => "id DESC")
end

def self.random
 Post.find(:first, :offset =>rand(Post.count :all))
end

On your show view, add links like this:


<%= link_to 'Previous', :id => @post.back %> |
<%= link_to 'Random', :id => Post.random %> |
<%= link_to 'Next', :id => @post.forward %>

Struggling with Ruby: Contents Page

Moving to Rails 2.3.8

2010-05-28T21:37:00.003+01:00

I have recently decided to move to Rails version 2.3.8. I have tried rails 2.3 a while ago, but it did not agree with JRuby. As JRuby 1.5 is now available, I thought I should give it another go. Though I had the same problem, I fixed it this time.

application_controller.rb
The first change is that app/application.rb must be renamed to app/application_controller.rb, which certainly makes it more consistent.

JRuby and Rake
I think this was the issue that stopped my moving to 2.3.2. Running any rake command that accesses the database (and, for example, the test tasks invoke database tasks, so will do this as well) generates this:

rake aborted!
Task not supported by 'jdbcpostgresql'

The problem seems to have been know about two years ago (see here; more recently here). When Rake has to interact with the database, it checks the hash generated from your database.yml file, and finds the adapter is called jdbcpostgresql. It then compares this against the adapters it knows, trying - and failing - to match postgresql. The solution is to edit the rakes file that handles database interactions (rails-2.3.8\lib\tasks/databases.rake) and change every occurance of "postgresql" or 'postgresql' (with quotes) to /postgresql/. Now it will sucessfully match the jdbc adapter. Obviously if you are using another database, you need to change it for that.

Is test_helper loaded twice?
I have a couple of constants defined in test/test_helper.rb, and this causes warning that they have already been defined. I can only assume this is because the file is getting loaded twice, but I could not see why that might be the case.

Also in test/test_helper.rb, you need to change:

class Test::Unit::TestCase

... to:

class ActiveSupport::TestCase

Otherwise, you will get "undefined method `use_transactional_fixtures=' "

Deprecation warnings

"Giving :session_key to SessionStore is deprecated, please use :key instead."

In config/environment.rb, change :secret_key to :key. It will look something like this:

config.action_controller.session = {
:key => '_AuthSampleLog_session',
:secret      => #some big hex number
}

"Using assert_redirected_to with partial hash arguments is deprecated"

Usually, your redirect will specify a controller and an action, but occasionally you specify something else as well, such as an id. Now in Rails assert_redirected_to checks each of the key-value pairs that you specify (this is confusing because the API says they are all optional; considered with redirect_to they are option; they just have to match up).

So this is fine, because the test specifies the controller and the action.
# In the controller
redirect_to :controller => :audits, :action => :edit
# In the controller test
assert_redirected_to :controller => :audits, :action => :edit

In this case, the test must also specify the id, because it is given in the redirect_to.
# In the controller
redirect_to :controller => :audits, :action => :edit, :id => @audit_section.audit_id
# In the controller test
assert_redirected_to :controller => :audits, :action => :edit, :id => as.audit_id

Integration testing
I found some odd things happened with logging out in my integration tests; eventually isolated this to a known bug:
https://rails.lighthouseapp.com/projects/8994/tickets/2200-session-support-broken

Struggling with Ruby: Contents Page

Ruby Unit Testing

2010-05-02T22:04:00.000+01:00

Ruby has a built-in unit testing facility, Test::Unit. To use it, create a new file, and define a class that inherits from Test::Unit::TestCase. This is best done in a separate folder, by the way, so you can easily release your project without the unit tests (Rails sets this all up for yu by the way).

# Load in the unit test classes
require 'test/unit'
# Load in your class to be tested
require 'things'

class ThingsTest < Test::Unit::TestCase

 def setup
   # Set up some test conditions here
   # This will be invoked before each test
 end

 def teardown
   # This will be invoked after each test
   # Use to close connections, etc.
 end
end

You will also need to define your tests. Each test goes in its own method, the name of which must begin "test" (as Ruby will search your class for such methods for testing).

def test_thing_creates_okay
 # assertions
end

There are several assertions you can use to test the results. Here are some of the more common ones:

assert_equal      # Compares two objects
assert            # Tests for true
assert_nil        # Tests for nil
assert_raise      # Tests an exception is thrown
assert_in_delta   # Test two floats are within a given amount

Rails (since about 2.2) uses a different format for tests:

test "Thing creates okay" do
 # assertions
end

The end result is the same. In Rails, test is a method that dynaally defines a method (in this case called "test_thing_creates_okay") with the given block.

Running Tests

If you are using NetBeans you can run a test simply by right clicking on the file being tested, and selecting test. NetBeans can work out which the relevant test is as long as it is named conventionally (eg the test for things.rb would be things_test.rb). Alternatively, you can right click on the test file, and selecting test or run.

To test from the command prompt, simply run the test file through ruby (eg ruby things_test.rb; if you are using JRuby, do jruby things_test.rb).

For a big project, you can collect all your tests together to form a test suite. Just create a Ruby file that requires each of the tests in turn, and run that through Ruby. Alternativerly, put this in your test suite, and it will automatically go though every file in that folder that has a name ending "_test.rb".

files = Dir.entries(File.dirname(__FILE__)).select do |file|
 file =~ /_test.rb$/
end
files.each { |file| require file }

Testing private methods and variables

Here is a trivial class with an instance variable and a private method.

class UnitTestee
 def initialize x
   @val = x
 end

 private

 def do_stuff y
   @val * @val * y
 end
end

I can test the private method using send, like this:

def test_do_stuff
 @ut = UnitTestee.new 12
 assert_equal 12 * 12 * 5, @ut.send(:do_stuff, 5)
end

Note that I have left Ruby to calculate 12 * 12 * 5; not only does this save me doing it, it makes it clearer where the number comes from (even better to use named constants, of course).

To access the instance variable, I can define a new method. Doing that in my test file means that the new method is not part of the API. Here is one way to do it (there are others):

def test_variable
 @ut = UnitTestee.new 12
 eval "def @ut.get_val; @val; end"
 assert_equal 12, @ut.get_val
end

Note

Test files often include something like this at the start:

$:.unshift File.join(File.dirname(__FILE__),'..','lib')

This simply adds the code folder (called "lib" here) to the load path, so Ruby can find the file to be tested.

Struggling with Ruby: Contents Page

Using partials as methods

2010-05-01T20:30:00.000+01:00

Most of my models have an associated view that lists the records on the index page. Rails generates the code, so generally I do not worry about it, but if I am doing the same thing across a dozen models/controllers, surely it would be better to just do it once? Actually, I am not sure. You do not save any typing, as Rails generates the views (assuming you are in the habit of specifying all your columns from the start), and it is less readable this way. Anyway, let us look at how it can be done, and you can decide for yourself if it is worth while or not.

The way to achieve this is through a partial. Conceptually a partial is just a method that returns a chuck of HTML code You send it a few parameters mapped to the :local key, it processes your code, and returns the HTML. I want my partial accessible from any view, so I created a new folder, app/views/shared, with a partial called _table.rhtml.

I will be invoking my table from within a view with something like this:

<%=
  render :partial => 'shared/table', :locals => {
    :list => SamplesHelper::WORKSHEET_LIST,
    :data => @worksheets,
    :links => check_role?('analyst') ? :edit : :show,
  }
%>

The render method is sent a hash with a :partial key that maps to the location of the file (without the underscore), and a :locals key with my parameters. This is the standard procedures for partils. Within locals I have chosen to require three parameters that will define how the table is drawn. The first, :data, is simply an array of ActiveRecord::Base objects, that is, the database records that Rails got for me.

The :links parameter determines whether the user sees links to show, to show and edit, or to show, edit and destroy. In this case, I am checking if the user has the "analyst" role; if he does, I want the edit and show links, otherwise just the show links.

Finally, the :list parameter is an array of hashes, which I chose to define in a helper file, and which might look like this:

WORKSHEET_LIST = [
  {:heading => "Date", :column => "created_at.format_date"},
  {:heading => "Type", :column => :name},
  {:heading => "Sample", :column => :sample.number},
]

This will give me three columns, with the given headings, and the values from the given columns (or rather, method calls). Note that the first is a symbol, the others are strings. This will be explained later.

My partial looks like this:

<table align="center">
  <tr>
    <% list.each do |item| %>
      <th><%= item[:heading] %></th>
    <% end %>
    <th colspan="<%= [:none, :show, :exit, :destroy].index(links) %>"> </th>
  </tr>

<% for datum in data %>
  <tr class="<%= cycle('odd', 'even') %>">
    <% list.each do |item| %>
      <td><%= item[:column].is_a?(Symbol) ? h(datum.send(item[:column])) : eval("datum.#{item[:column]}") %></td>
    <% end %>
    <td><%= link_to 'Show', { :action => :show, :id => datum.id } %></td>
    <% unless links == :show %>
      <td><%= link_to 'Edit', { :action => :edit, :id => datum.id } %></td>
    <% end %>
    <% if links == :destroy %>
      <td><%= link_to 'Destroy', { :action => :destroy, :id => datum.id }, :confirm => 'Are you sure?', :method => :delete %></td>
    <% end %>

  </tr>
<% end %>
</table>

For the headings, it iterates through the list, pulling out the :heading value. Then it iterates over the records, and for each record again iterates through the list, this time pulling out the column value. If the :column value is a symbol, the send method is invoked, and the output HTML-escaped. If the :column value is a string, an eval is performed, allowing you to do something more involved (in the example, format a date). Note that this is not HTML-escaped; I have methods that return HTML strings to, for example, highlight values a certain colour, so this preserves that feature. However, you should consider carefully if this is safe in your situation. Note that I coud have defined a formated_created_at method in my model, and invoked that method using a symbol, rather than "created_at.format_date".

The table pads out the headings over the links at the right, and adds only those links that are requested.

As an aside, I was surprised to find that the parameters you send in the :locals hash really are local variables; I expected them to be method calls, like the supposed variables for columns in ActiveRecord.

I added a section at the top of the page that verifies the parameters are there. It just throws an exception if a required parameter is missing, and defines a default for the :links value should that one be missing.

<%
  raise RuntimeError.new("list not set for _form") unless defined? list
  raise RuntimeError.new("data not set for _form") unless defined? data

  links = :show unless defined? links
%>

I think it is important to document your partial, so anyone using it knows what he has to supply in the way of parameters.

<%#
This partial must be sent:
- an array of hashes called "list"
- an array of ActiveRecords in "data"; the records from the database

It can also be sent:
- a value, "links" set to one of: :edit, :show, :destroy (defaults to :show)

The hashes in the array "list" must have a :heading key and a :column key.
The :heading key should map to a string, giving the column name.
The :column key should map to a symbol or string.
If a symbol, then that will be used the send method on the record, and the
output with be HTML-escaped; use this for model column names.
If a string is supplied, it will be used in an eval
method call, and the output will not be HTML-escaped.
%>

The last thing to do is to test your partial. This needs to be done as a functional test, because you need the infrastructure that that implies. This means we need a new action, let us call it _render, which can be defined in the ApplicationController class (but in the test_helper.rb file, so it only exists in your tests). The action firstly executes a string, params[:eval], which would set up any instance variables required for your test. The page is then rendered, using the partial as defined in params[:args].

class ApplicationController
  def _render
    eval(params[:eval]) unless params[:eval].nil?
    render :inline => "<%= render #{params[:args]} %>"
  end
end

You should create a new file with your other functional tests. You need to tell Rails which controller it will use (should be okay to use any of them), using the tests method. You may need to load in some records (or you can use fixtures), and you may need to log in.

The meat of the test is the get command, invoking the _render action defined before, with two arguments, the parameters for the partial, and the code for grabbing some ActiveRecords to show (both as strings, please note).

class PartialTest < ActionController::TestCase
  tests ChembaseRefsController

  def test_table
    load_sample_records
    login_as 'librarian', @request


    get :_render, :args => ":partial => 'shared/table', :locals => {
      :list => ChembaseRefsHelper::REFS_LIST,
      :data => @chembase_refs,
      :links => :destroy,
    }", :eval => "@chembase_refs = ChembaseRef.find :all"

    doc = REXML::Document.new @response.body
    assert_equal ChembaseRef.count(:all) + 1, doc.elements.to_a("table/tr").length#, "#{@response.body}\n"
    assert_equal ChembaseRefsHelper::REFS_LIST.length + 1, doc.elements.to_a("table/tr/th").length#, "#{@response.body}\n"
  end

The method ends by creating an XML document from the respoonse, and testing the number of columns and rows are what they should be.

Struggling with Ruby: Contents Page

Operator Overloading

2010-04-24T08:52:00.003+01:00

Ruby permits operator overloading, allowing you to define how operators will work with your own (or indeed any) classes. Here is a quick example, showing how to define the addition operator. Note that you get the += for free.

class Tester1
 def initialize x
   @x = x
 end

 def +(y)
   @x + y
 end
end

a = Tester1.new 5
puts(a + 3)
# => 8
a += 7
puts a
# => 12

The definition is not commutative, i.e., trying to do 3 + a would fail. To get that to work you would need to override the addition method in Integer - and I think that would be a bad idea.

The next example shows how to override comparison operators. Note that by overriding the equality operator, you get the inequality operator for free. Also note that you are not restricted to returning a boolean; in this example <= returns a string.

class Tester2
 def initialize ary
   @ary = ary
 end

 attr_reader :ary

 def ==(y)
   @ary.length == y.ary.length
 end

 def <(y)
   @ary.length < y.ary.length
 end
 def <=(y)
   '@ary.length < y.ary.length'
 end
end

b = Tester2.new %w(zero one two three)
puts b == Tester2.new([1, 2, 3, 4, 5])
# => false
puts b != Tester2.new([1, 2, 3, 4, 5])
# => true
puts b < Tester2.new([1, 2, 3, 4, 5])
# => true
puts b <= Tester2.new([1, 2, 3, 4, 5])
# => "@ary.length < y.ary.length"

You need to be careful when overriding operators, as it has the potential to make your code unfathomable. One time I think it is particular useful, however, is to add array-like properties to a class, for example to access an underlying array, as in this example. Note how the += operator has to be defined via the + operator. Also, the index operator needs two methods if you want to be able to both read from and write to it.

class Tester3
 def initialize ary
   @ary = ary
 end

 def [](y)
   @ary[y]
 end

 def []=(y, value)
   @ary[y] = value
 end

 def <<(y)
   @ary << y
 end

 def +(y)
   @ary << y
 end
end

c = Tester3.new %w(zero one two three)
puts c[3]
# => three
c << 'four'
puts c[4]
# => four
c += 'five'
puts c[5]
# => five

As an aside, be aware that << and += are not the same for an Array object (though they are for Tester3). The += operator requires an array, the members of which are added to the existing array. The << operator appends the new object to the array; if the new object is an array, you have the new array nested inside the existing array.

You cannot override keywords, such as "or", nor can you override:

&& & || | () {} :: . ~ .. ...

Struggling with Ruby: Contents Page

XML and Ruby

2010-04-20T18:17:00.001+01:00

When you come back to XML after using YAML, it is a real pain in the neck. However, sometime we have to do it.

REXML offers a comprehensive set of functions for negotiating an XML document, so this is what I used to read an XML document into a Ruby data structure.

First, the setting up. Load in the REXML library, and include it for convenience. Load in the XML file.

require "rexml/document"
include REXML

file = File.new("materials.xml")
doc = REXML::Document.new file

In my XML, materials in the root node, and this has a number of children, msds, which in turn have a number of children, material. Each material node has a set of attributes, plus some child nodes of its own.

Each element has an attributes attribute and an elements attribute. You can iterate though these using each, but you can also select specific nodes by sending a path to the each method. I want to start by iterating through the msds nodes:

doc.elements.each("materials/msds") do |msds|
 # do stuff
end

For each iteration though the loop, I then need to go though that elements nodes with an inener loop.

For the material nodes, I need to go though the attributes. The each method of attributes has two parameters for the block, the name and value. Easy to add these to a hash (material_data).

material.attributes.each do |name, value|
 material_data[name.to_sym] = value
end

To extract specific values from a node, into a hash, I did this:

h = { :name => element.text,
     :type => element.name,
     :file => element.attributes["file"] }

The text method gets the inner text from the element, name gives the tag name, and attributes["file"] gets the value of the "file" attribute.

require "rexml/document"
include REXML

file = File.new("materials.xml")
doc = REXML::Document.new file

data = []

doc.elements.each("materials/msds") do |msds|
 msds_data = []
 msds.elements.each("material") do |material|
   material_data_ary = []
   material.elements.each do |element|
     h = { :name => element.text,
           :type => element.name,
           :file => element.attributes["file"] }

     material_data_ary << material_data =" {" msds =""> material_data_ary }
   material.attributes.each {|name, value| material_data[name.to_sym] = value }

   msds_data << msds =""> msds_data, :file => msds.attributes["file"] }
end

REXML API
http://www.germane-software.com/software/rexml/doc/
Tutorial
http://www.germane-software.com/software/rexml/docs/tutorial.html
Further
http://www.developer.com/lang/article.php/3672621

Struggling with Ruby: Contents Page

Testing for Valid HTML

2010-04-01T19:18:00.002+01:00

There is a gem for testing valid HTML called RailsTidy, however, when I tried to use it I got "RuntimeError: can't find the symbol `tidyCreate' ", which seems to relate to calling non-Ruby code (possibly failing because I am using JRuby?). So anyway, I looked at doing my own.

The best way to approach this is to create a method that works like the usual assert_x methods, so it can be invoked like this:

def test_should_get_index
 get :index
 assert_response :success
 assert_not_nil assigns(:posts)
 assert_validates
end

The skeleton of my method is going to look like this:

def assert_validates message = ''
 clean_backtrace do
   msg = build_message(message, "Invalid HTML found")
   assert_block(msg) do
     # Code here
   end
 end
end

In common with other assert_x methods, it will accept an optional message. The clean_backtrace method does what it says. It catches AssertionFailedErrors, cleans the backtrace, and rethrows the error. I am using it to ensure backtraces from my method are consistent with the backtrace from other such methods.

Inside that block, I use the assert_block method. This is the workhorse of all assertions; it catches and counts failures and errors, based on what happens inside its block. If it returns true, the test passes. One limitation here is that it seems impossible to modify the message from within the block, so we can report back what the problem was.

Now to check the HTML is valid. I am going to cheat here, and actually check that it is valid XML, as then I can palm the work off on REXML (remember the require "rexml/document").

begin
 REXML::Document.new @response.body
 true
rescue REXML::ParseException => ex
 false
end

The code attempts to create an XML document from the body of the response. The block returns true if this was fine, and false if REXML threw an exception. You could put a print statement in there tto indicate where the problem is; I prefered to run any offending page through a proper validator (eg here or href="http://htmlhelp.com/cgi-bin/validate.cgi">here) once a problem is found, as it tells you exactly what it is.

Here is the whole thing, which should be inside ActiveSupport::TestCase, in test_helper.rb. I have added a constant, so you can turn validation on or off.

require "rexml/document"

# Do you want to validate?
VALIDATE = true

def assert_validates message = ''
 # Do not bother if validation is turned off
 return unless VALIDATE
 # Do not bother unless it is actually HTML
 return unless @response.content_type == "text/html"

 clean_backtrace do
   assert_block(build_message(message, "Invalid HTML found")) do
     begin
       REXML::Document.new @response.body
       true
     rescue REXML::ParseException => ex
       puts ex
       false
     end
   end
 end
end

You can check a whole bunch of tests in one file by adding a teardown method, like this.

def teardown
 assert_validates
end

If an action results in a redirect, this will only test that the redirect directive is valid HTML, not that the page the user is sent to is. That page is not generated during a functional test (though it will be if another action returns that page, and you test that action).

You could put the assert_validates method into a module, and include that module in both ActiveSupport::TestCase and ActionController::Integration::Session. This would allow you to validate in your integration tests too. I am not sure that that actually has any benefit; you would seem to be testing the same thing twice.

Struggling with Ruby: Contents Page

Variables

2010-03-31T20:09:00.002+01:00

In Ruby (as in most OO languages) there are four sort of variables; global, class, instance and local. In languages like Java and C++, you must declare a variable before use, and where you do that determines what sort it is. In Ruby, variables are not declared, so we need another way to indicate this; a prefix.

Variables can contain any object in Ruby; you can readily assign a string to a variable that previously held an integer. Variable names must begin with a lower-case letter or underscore (after the prefix). By convention, they are all lower-case, with words separated by underscores (eg my_variable).

Local Variables

Local variables have no prefix. They exist only within a block of code, such as a method. Once the block completes, the variable disappears.

def test2
local1 = 2
local1.times do
local2 = 3
p "l1=#{local1} l2=#{local2}"
end
p "l1=#{local1}"
#p "l2=#{local2}"  # Out of scope
end

Instance Variables

An instance variable belongs to that one instance of the class. It is denoted by a single at symbol (eg @var), and can be accessed from any instance of a class from within a method. They have private access... however, you can access them anyway through these methods:

instance_variables    # Array of strings, listing instance variables
instance_variable_defined?
instance_variable_set
instance_variable_get
remove_instance_variable  # Private method

You can also use attr_accessor, attr_reader and attr_writer to allow others to access your instance variables. Note that while the above methods do require the at sign, these three methods do not.

You can also access instance variables using self. These two statements are equivalent.

self.var = 19
@var = 19

Class Variables

A class variable belongs to the whole class (and indeed subclasses), and is accessible from anywhere inside the class, or from any instance of the class. If you change the value in one instance, it will be changed in every instance. It must start with two at symbols (eg @@var).

In Rails, you can access a class variable like a class method (eg MyClass.var) for a descendant of ActiveRecord::Base (analogous to how you access column names). Outside Rails class variables have private access.

Class variables have some perhaps surprising behavior when you look at inheritance, as a value set in a subclass can affect other classes. Let us see that in action. SubClass1 has a parent, SuperClass, a sibling, SubClass2, and a child SubSubClass1.

class SuperClass
@@var1 = 11
@@var2 = 21
def self.out1; @@var1; end
def self.out2; @@var2; end
end

class SubClass1 < var1 =" 12" var3 =" 31" var1 =" 13" var3 =" 32" var2 =" 22"> 13
p SubClass1.out1
# => 13
p SubClass2.out1
# => 13

# @var2 is in the top class and its grandchild class. Despite "skipping
# a generation", the value set in the sub-sub-class still affects the
# super-class
p SuperClass.out2
# => 22
p SubSubClass1.out2
# => 22

# @var3 is in the sibling classes only, not in a common super-class. In this
# case setting the value in one has no effect on the other.
p SubClass1.out3
# => 31
p SubClass2.out3
# => 32

There are a set of methods available to use class variables, analogous to those for instance variables.

class_variables    # Array of strings, listing instance variables
class_variable_defined?
class_variable_set
class_variable_get
remove_class_variable  # Private method

In Rails, you can define setters and getters just as you can for instance variables; cattr_accessor, cattr_reader and cattr_writer.

Global Variables

A global variable must start with a dollar (eg $var). It accessible from any class at any time. They are generally regarded as something to avoid; better to keep sections of code isolated from each other as far as possible.

Ruby has a number of predefined global variables. I do not like to use them myself; they make code that much harder to understand, and where there is a more explicit alternative, I would always use that. However, there is a list here.

There is an interesting trace feature for global variables. The trace_var method takes either a string or a symbol representing the global variable (with the dollar sign), together with a proc object (the documentation claims it will take a string or block as well; I do not believe that that is true).

trace_var "$global_var", proc do |x|
puts "$global_var is now #{x}"
end

You can set more than one trace on a global variable, and you can remove them (all) with untrace_var.

The global_variables method will return an array of strings, the names of all the global variables (complete with dollar sign).

Special Variables

Ruby includes a handful of special variables:

self     # "this" in Java, etc.
true
false
nil      # "null" in Java, etc., also counts as false
__FILE__ # the current file
__LINE__ # the current line number.

All Together Now

Let us them all in action. Here is some sample code.

$global_var = 32

class TestClass
@@class_var = 14

def initialize
@instance_var = 20
end

def test
local_var = 7
$global_var += 1
@@class_var += 1
@instance_var += 1
local_var += 1
puts "$global_var=#{$global_var}"
puts "@@class_var=#{@@class_var}"
puts "@instance_var=#{@instance_var}"
puts "local_var=#{local_var}"
end
end

Both $global_var and @@class_var are set when the file is loaded. While $global_var is available to everything, @@class_var can only be accessed from within TestClass. Looking at @instance_var, this will be set to 20 for a specific instance of TestClass when the instance is created. It will be incremented whenever test is invoked on that instance, in contrast to $global_var and @@class_var, both of which will get incremented every time test is invoked on any instance. Finally, local_var is created when it is set in the test method, and destroyed when the method terminates.

Struggling with Ruby: Contents Page

Capturing File Uploads

2010-03-18T20:45:00.002Z

Here is the requirement: The web page asks the user to upload a file. The data in the file is then used to populate a new record in the database.

The first thing I want, then, is for the view to have a file upload button. Here is what worked for me:

<% form_tag 'create', :multipart => true do %>
<%= hidden_field_tag :sample_id, @sample.id %>
<p>
<%= file_field_tag 'datafile' %>
</p>
<p>
File names can only contain numbers, letters, hyphens and underscores, and must end ".csv".
Files must be on your C: drive to be successfully uploaded.
</p>
<p>
<%= submit_tag "Okay" %>
</p>

You could also use the form_for method instead, with file_field, rather than file_field_tag.

Some points to note:

You need to flag the form as "multipart", so that the file gets submitted as one part, and other data on the form as a second part. My experience is that uploaded files are a little restricted, and will not upload from a networked drive, or if there are strange characters in the name, and I warn the user of this. This may be dependant on your system. In this particular case, I am looking for a .csv file. The file type may need to be defined as a MIME type (CSV is registed by default).

The file received is of the UploadedTempfile type, and seems to be useable like any other file. As far as I can tell, Rails closes and deletes it for you. It is accessible though params in the normal way (so as params[:datafile] from the above code).

params[:datafile].each_line do |s|
# do stuff
end

I could not find away to process a CSV file using the CSV library; it seems to demand a filename, rather than the file itself. I was obliged to do it by hand (in my case I knew every field would be surrounded by quotes, so it is pretty easy).

In the functional test, just send the file as a parameter (with a test file in the fixtures folder).

post :create, :sample_id => Sample.find(:first).id,
   :datafile => File.new("#{RAILS_ROOT}/test/fixtures/results.csv")

Struggling with Ruby: Contents Page

Rails: Singularize and Pluralize

2010-03-11T21:18:00.002Z

Rails has functions buit-in that will turn a word into its plural or singular. It uses this when generating models, etc. to create names that conform to the standard (so user.rb but users_controller.rb). The rules are set up in a file called:

...\lib\ruby\gems\1.8\gems\activesupport-2.3.2\lib\active_support\inflections.rb

The action all happened inside a block like this:

module ActiveSupport
 Inflector.inflections do |inflect|
   # definitions
 end
end

There are four types of rules. The first sets a general rule for making a plural, like this:

inflect.plural(/([^aeiouy]|qu)y$/i, '\1ies')

If the regular expression in the first parameter matches, then it is replaced by the the second parameter (but note that a capture group is used, so a part of the discarded ending is still used). This rule will match a word ending in y, but not preceded by a vowel, replacing the "y" with "ies"

The second sets a rule for making a singluar, like this (which is the reverse of the previous):

inflect.singular(/([^aeiouy]|qu)ies$/i, '\1y')

Then there are the irregulars, defined like this:

inflect.irregular('person', 'people')

And those that do not change, like this:

inflect.uncountable(%w(equipment information rice money species series fish sheep))

Unfortunately, it is not perfect (not in 2.3.3 anyway), which is why I was obliged to learn about it. For example:

inflect.plural(/(octop|vir)us$/i, '\1i')

The plural of virus is viruses, not viri; octopus can use either form, though octopuses is prefered (see here).

The particular one I ran up against was this, for "metal analyses":

inflect.singular(/((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$/i, '\1\2sis')
inflect.singular(/(^analy)ses$/i, '\1sis')

The system runs through the rules starting with the last defined, until it finds a match. For "analyses", it hits the second of the lines shown above, and returns "analysis" (why this was not put in as an irregular I cannot imagine). There is no match there for "metal analysis" as the pattern specifies the start of the string. So it looks at the previous rule. Now a match is found. However, this match defines several capture groups, the first is "analy", the second is just the "a", and both these are used in the replacement, so the resulting plural goes like this:

<whatever was before the pattern> <"analy"> <"a"> <"sis">

"metal analyses -> metal analyasis

Because the replacement uses only the first and second capture groups, the other words in that rule work fine. For "theses", for example, the "t" is in capture group 8, which is not used. And as analysis on its own gets caught by the previous rule, the error can easily be missed.

This issue was bought up as a bug, but dismissed (see here). The simple workaround is to define your own rule. I have done this in a file inside config/initializers (I have called mine called initial.rb).

ActiveSupport::Inflector.inflections do |inflect|
 inflect.singular(/(analy|ba|diagno|parenthe|progno|synop|the)ses$/i, '\1sis')
end

You can add as many of your own rules as you like. As they get added later, they will take precedence over the existing rules.

Struggling with Ruby: Contents Page

Adventures in programming...

2010-03-04T18:19:00.002Z

Back in the day I used to love text-based adventure games (the one that stands out is Leather Goddesses of Phobos). I have made several attempts to write my own, in various languages from BASIC, to C, to Java. The use of an object-orientated language like Java was a big help, but I was recently wondering how Ruby might work (whether it will even come to anything is dubious).

Ruby has a number of apparent advantages, and a consideration of how the data file might be illustrates that.

def setup
 locations = [
   Location.new(:id => :start, :name => 'The Start', :south => :hall,
                :north => :lobby),
   Location.new(:id => :hall, :name => 'The Great Hall', :north => :lobby),
   Location.new(:id => :lobby, :name => 'The Swanky Lobby', :south => :hall),
 ]
 items = [
   Item.new(:id => :sword, :name => "Widowmaker Sword", :loc => :hall),
   Item.new(:id => :robes, :name => "Magical Robes", :loc => :lobby,
            :wearable => true),
   Item.new(:id => :health, :name => "Healing Potion", :loc => :hall,
            :consume => "He gained 5 hit points.<% @char[:health] += 5 %>"),
 ]
 characters = [
   Character.new(:id => :boris, :name => 'Boris', :location => 'Home',
                 :inv_limit => 2, :health => 5),
 ]
 commands = [
     {:verb => :take_from, :alias => [/^take ([\w ]+) from (\w+)$/,
                                      /^take ([\w ]+) out of (\w+)$/,
                                      /^remove ([\w ]+) from (\w+)$/],
       :item_not_here => "It's not there."
     },
     {:verb => :get, :alias =>       [/^get ([\w ]+)$/,
                                      /^take ([\w ]+)$/,
                                      /^pick up ([\w ]+)$/],
       :okay => "+char+ picked up +item+.",
       :item_not_here => "It's not there.",
       :inv_limit => "You're holding enough already.",
       :cannot_get_static => "You can't get that!"
     },
     {:verb => :examine, :alias =>   [/^examine ([\w ]+)$/,
                                      /^look at ([\w ]+)$/,
                                      /^describe ([\w ]+)$/],
       :item_not_present => "It's not here.",
     },
     {:verb => :simple_com, :alias => [/^look$/],
       :script => "<%= @location.describe %>",
     },
 ]
 World.new locations, items, characters, commands
end

Data files are code

In all my previous attempts, my data files have been simple text files (perhaps in XML). This time I took the example of Rails; migrations, the routes files and rake files are all Ruby code, so there is far more you can put in there when you configure. Previously I have had to write code just to load my data; not so this time.

It should be easy to extend the system, even in run time. Create a new data file, perhaps with code to modify existing locations, and run it as a script.

Hashes

Ruby just asks for you to use hashes for pretty much everything (again, Rails does this a lot). They are so easy to create, to use and to pass around. Sure, Java has hashes too, but it never encouraged me to use them (so really this is only an apparent advantage).

At its simplest, you just make everything, whether the player, an item or the location, a hash, and give it the values appropriate. Want to add a new property? Just add a new value to the relevant hashes and away you go.

Want to save the data? In one line you can save an array of hashes to YAML, and load it back in in another line.

Regular Expressions

For understanding what the user is saying, regular expressions are so useful. An input like "put the cat in the bag" can readily be matched against /^put ([\s ])+ in ([\s ])$/, and straight away you can pull out what went in where (regular expressions have been in Java since 1.4; too late for when I was trying to use it).

Dynamic Method Calls

Once the command has been recognised, the appropriate method can be invoked simply by calling send, with the :verb value from the hash. Could be done using reflection in Java, but not as easy. Earlier languages... no way.

Scripts

With Ruby a scripting language, it is easy to just put scripts into the hashes. In the healing potion above, an ERB script is used to restore health.

Ruby Sockets

2010-03-03T17:26:00.002Z

I was messing around with Ruby sockets, and came up with a simple chat-server. Testing proved to be rather more complicated... If you run this program, you can connect to it using "telnet 6606".

require 'socket'
require 'thread'

# Boardcaster maintains a list of users.
class Broadcaster
 def initialize; @users = []; end
 def add user; @users << socket =" TCPServer.open(6606)" broadcaster =" Broadcaster.new" lock =" Mutex.new">")
   user = {:name => s.gets.strip, :socket => s }
   b.add user
   print("#{user[:name]} is accepted\n")
   s.write("Hello #{user[:name]}\n\rUsers on-line: #{b.list}\n\r>")
   while true
     st = s.gets.strip
     #p st
     break if st == 'bye'
     lock.synchronize do
       b.broadcast "#{user[:name]} says \"#{st}\"\n\r>"
     end
   end
   lock.synchronize do
     b.broadcast "#{user[:name]} has left\n\r>"
   end
   s.close
   b.remove user
   print("#{user[:name]} is gone\n")
 end

end

This was my first experience of both threads and sockets on Ruby, and with regards to threads, I have to admit to being pretty clueless! However, it does seem worthwhile locking the shared resource, b, when used on a thread.

Sockets seems straightforward enough. A new socket is opened using the TCPServer class. Data is collected with gets, and sent with write. At the end it is closed. I suspect there should be some exception handling in there, but it certainly proves the concept.

Testing Stream-Handling Methods

Okay, so now I want to test my methods that handle streams. Let us suppose that you have a method that accepts data from some stream and outputs to another, like the broadcast method above, and you want to test it. How do you do it?

First, let me simplify, and instead consider this method:

def get_data source, sink
 print "\n>"
 name = source.gets.strip
 print "\n>"
 age = source.gets.strip
 sink.print "Name: #{name}, age: #{age}"
end

This could be invoked for use with the keyboard like this

get_data $stdin, $stdout

Or across a network, like this:

require 'socket'
socket = TCPServer.open(6606)
get_data socket, socket

If I want to test that method the trick is to use StringIO objects.

def test_get_data1
 StringIO.open { |sink|
   get_data(StringIO.new("Boris\n32\n"), sink)
   assert_equal "Name: Boris, age: 32", sink.string
 }
end

Actually, Ruby would happily let you use the same StringIO object for both input and output, but the output would be appended to the input string, so your assertion would need to check for both the input and the output.

def test_get_data2
 StringIO.open("Boris\n32\n") { |io|
   get_data(io, io)
   assert_equal "Boris\n32\nName: Boris, age: 32", io.string
 }
end

That is bad; if we change the get_data method to accept different input, we would need to change the test in two places, and that is clearly a bad thing. Well, okay, we change it so the input gets inserted into what we expect. The problem now is that Ruby is modifying that string during the test, so we need instead to give Ruby a duplicate of the input string for it to play with, so we still have the orignal for comparison at the end.

def test_get_data3
 input = "Boris\n32\n"
 StringIO.open(input.clone) { |io|
   get_data(io, io)
   assert_equal "#{input}Name: Boris, age: 32", io.string
 }
end

Then again, perhaps we need to rethink. The whole thing can be generalised into a new method, which can test any method against any input. The test itself can then be reduced to a single line.

def test_get_data4
 stream_test("Boris\n32\n", "Name: Boris, age: 32") do |io|
   get_data(io, io)
 end
end

def stream_test input, output
 StringIO.open(input.clone) { |io|
   yield io
   assert_equal "#{input}#{output}", io.string
 }
end

A serious problem with all of these is that errors do not get caught by the test regime. A message is sent to the output, but the error is not counted in the totals (failures, on the other hand, are). I guess this is because the redirect is capturing the exception. A way around this is to capture the exception inside the block, and then flag this as a failure:

def stream_test input, output
 StringIO.open(input.clone) { |io|
   begin
     yield io
   rescue Exception => ex
     assert false, "ERROR: #{ex.inspect}\n#{$!.backtrace[0..12] * "\n"}"
   end
   assert_equal "#{input}#{output}", io.string
 }
end

Testing Multiple Threads

Those tests are all very well, but my Broadcast object sends messages to multiple users. How do I test that? Now I need threads in my tests!

Here is a test method that worked for me:

def test_broadcast
 # SETTING UP

 # The number of threads to spawn
 number = 100
 test_string = 'teststring'
 b = Broadcaster.new
 # Define strings outside the blocks so we can access them
 # later on
 string_ary = Array.new(number, '')
 thread_ary = Array.new(number)
 main_s = nil

 # LISTENING THREADS
 # A number of threads are spawned, they listen for
 # messages for 0.2 seconds, then write their StringIO
 # string to string_ary, before terminating.

 number.times do |i|
   # Spawn a new thread
   thread_ary[i] = Thread.start(b, i) do
     # Create a StringIO object to collect the string
     StringIO.open do |sink|
       # Create a new user, and add it to the Broadcaster
       user = {:name => 'test1', :socket => sink }
       b.add user
       # Wait a short time for the message to be broadcast
       # Choose wisely, 0.2 on my system led to failures
       sleep(0.3)
       # Set s1 to a copy of the sink string, so it
       # is still around outside the block
       string_ary[i] = sink.string.clone
     end
   end
 end

 # SENDING THREAD
 # On the main thread, this sends the message, then waits
 # for all the other threads to terminate.

 # Create a StringIO object to collect the string
 StringIO.open do |sink|
   begin
     # Create a new user, and add it to the Broadcaster
     user = {:name => 'test2', :socket => sink }
     b.add user
     # Broadcast the test string
     b.broadcast(test_string)
     # Wait for the other threads to finish
     # by which time the broadcast should have been received.
     number.times { |i| thread_ary[i].join }
     main_s = sink.string.clone
   rescue Exception => ex
     # Flag any exceptions as a failure
     assert false, ex.inspect
   end
 end

 # TESTING
 # Test all the threads received the test_string
 assert_equal test_string, main_s
 number.times { |i| assert_equal test_string, string_ary[i] }
end

Struggling with Ruby: Contents Page

Using Java Applets

2010-01-30T12:32:00.002Z

I had a system that I wanted to create where the user could do some complicated manipulation of data, before sending the results to the database. It seemed to me that a Java applet would be the best way to interface with the user, but how to interface the applet with Rails?

The applet itself was very straightforward. It picks up the initial data from two parameters, rt and pc (each a list of floats, combining to make pairs of data). I also needed a public class that would return the results in a string.

package railsapplet;

public class MyApplet extends javax.swing.JApplet {
  MyData data;

  @Override
  public void init() {
      String rt = getParameter("rt");
      String pc = getParameter("pc");
      data = new MyData(rt, pc);
      // Set up UI
  }

  // etc.

  public String getOutput() {
      return data.getOutput();
  }
}

I packaged my Java in a jar file, insides public/applets. My view needed to reference that applet.

<applet codebase="http://<%= ApplicationController::SITE %>/applets"
      width="400" height="400"
      code="railsapplet.MyApplet.class" archive="railsapplet.jar"
      name="myapplet"
      id="myapplet"
      align="center">
<param name="rt" value="<%= @rt.join(" ") %>">
<param name="pc" value="<%= @pc.join(" ") %>">
<hr />
If you were using a Java-enabled browser,
you would see an applet right now.
<hr />
</applet>

The code base points to the public/applets folder (using a constant, SITE, for the domain and port). The two variables @rt and @pc are arrays of floats, which are compiled into strings. These can then be picked up by the applet.

Okay, so I have got the data from the database, and into my applet. The uses plays around with it, then wants to send the results back to the database. There are number of ways to get data out of an applet. One such is to use a JSObject in the applet to communicate with elements on the web page. However, the easiest way is to use JavaScript.

This JavaScript function will search the page for the "myapplet" element, then call the getOutput() method on it (retrieving the data from the applet). The string is placed in the "output" element.

<script language="JavaScript">
function getOutput() {
document.getElementById('output').value = document.getElementById('myapplet').getOutput();
}
</script>

To get it all to work, you need a little form on the web page, with a button and a hidden input. Click the button and the results will go on the hidden input, and the form then submitted.

<% form_tag :action => :glc_update do %>
  <input type="hidden" name="output" id="output" />
  <button type="button" onclick="getOutput(); submit();">Okay</button>
<% end %>

After that, it is up to Rails to examine the string, extracting the results.

Struggling with Ruby: Contents Page

The named_scope in Rails

2009-12-22T21:45:00.002Z

The named_scope method allows you to set up shortcuts to narrow searches within set parameters. It is invoked in the model, something like this:

class Computer < ActiveRecord::Base
named_scope :active, :conditions => {:in_use => true}
named_scope :networked, :conditions => "(network_id <> \"\")"
named_scope :recent,    lambda { {:conditions => ["created_at > ?", 1.months.ago ] } }
end

Note the use of the lambda. If you simply compared the created_at to the date, you would be comparing it to the date the named_scope was invoked, rather than the current date (you might object that Rails reloads the model each time, so the difference might not be so much, but that does not seem to affect your named_scopes). You might also want to do this if you want to access another model. Say your database has a list of types, and this model has a field for the ID of one of those types. You want to collect all the records by the name of the type, so you need to access the table for the other model to get the ID. But that model might not be loaded when this one is, so you have to delay getting the ID. Or perhaps you want to send parameters to a named_scope through the lambda.

# Use a lambda to access a later loading model
named_scope :blue, lambda {
{ :conditions => ["(colour_id = #{Colour.find_by_name('blue').id})"] }
}
# Use a lambda to allow parameters
named_scope :located, lambda { |loc|
{ :conditions => {:location_id => loc } }
}

You can also use named_scopes for other things, such as ordering.
named_scope :ordered, :order => 'created_at ASC'
Now to get an array of computers in use, just do this:

Computer.active

You can chain named_scopes together, and also with find. Now I can list all the blue computers at location 5, in ascending order of record creation, or all the networked computers running WinXP just like this:

Computer.blue.located(5).ordered
Computer.networked.find_by_os("winxp")

References
http://ryandaigle.com/articles/2008/8/20/named-scope-it-s-not-just-for-conditions-ya-know
http://snippets.aktagon.com/snippets/210-How-to-use-named-scope-in-Rails
http://jitu-blog.blogspot.com/2009/07/looking-into-rails-namedscope.html
http://stackoverflow.com/questions/137630/encapsulating-sql-in-a-namedscope

Notes
A named_space can be used with will_paginate without a problem:

@samples = Sample.outstanding.ordered.paginate :page => params[:page], :per_page => 16

I found that I had to restart my web server when trying these out to get the named_scopes to reload.

Also, if named_scope does not like your condition, it just fails to define a new method. There is no warning or hint about what could be wrong. All you get is a method_missing complaint when you try to invoke it.

Struggling with Ruby: Contents Page

Using Sub-directories in Rails Projects

2009-12-16T21:31:00.004Z

If you have a big project, you are going to want to break it up into parts, grouping, say, controllers for a certain part in one sub-directory. I found a couple of blog pages saying how to do this (basically you set up a name space in routes.rb, and prefix the controller class names with that name space, with the views in a similarly-named subdirectory):

http://myles.eftos.id.au/blog/2005/11/15/sub-directories-on-rails/
http://www.purpleworkshops.com/articles/grouped-controllers

However, they paint it rather simpler than it really is.

The Namespace for Controllers
Okay, so I have a number of controllers relating to a sample logging system, and I want to put them all inside a directory called sample_log. This corresponds to a Ruby namespace (because I might have a controller called TopController in each part of the system, so Rails needs a way to guarantee they are distinct). All the views need to be in their own subdirectory too, with the same name. Each of my controllers' class name needs to be prefixed with the name of the namespace:

class SampleLog::SamplesController < ApplicationController

Then you need to set up your routes, so that Rails knows you are using a namespace:

map.namespace :sample_log do |submap|
submap.resources :samples
# other controllers
end

At this point, you should be able to get pages, with a URL something like this:

http://localhost:3000/sample_log/samples/

Links
So far so good. The tricky part (especially if you already have a project that you want to do this to) is handling links in and out of the subdirectory. The standard link_to method invocation looks like this:

link_to 'Cylinders', :controller => 'cylinders'

This will generate a link within the sub-directory. How do you link to other subdirectories, or to the top level? Append a slash to your controller name, like this:

link_to 'Cylinders', :controller => '/cylinders'
link_to 'Samples', :controller => '/sample_log/samples'

The various helper methods like new_samples_path and edit_samples_path seem to work fine, but require the directory name to be appended to the method name (run rake routes to see the helper methods listed):

link_to 'List', sample_log_generic_samples_path
link_to 'Show', sample_log_generic_sample_path(@sample)
link_to 'Edit', edit_sample_log_generic_sample_path(@sample)
redirect_to sample_log_samples_path

However, Rails does not seem to be able to cope with links like this (use the helper methods just mentioned instead):

link_to 'Show', @sample
redirect_to @sample

For some reason, Rails does not provide a helper method for destroy, so you will need to given that link through the action:

link_to 'Destroy', { :action => :destroy, :id => sample.id },
               :confirm => 'Are you sure?',
               :method => :delete

If you use the form_for functionality, or polymophic methods (presumably with STI), you need to send the directory as a parameter (as a symbol or string), wrapped up in an array:

form_for([:sample_log, @sample]) do |f|
link_to 'Edit', edit_polymorphic_path([:sample_log, @samples[1]])

Pointing to templates and partials
Any time you explicitly invoke a template in a controller, you will obviously need to change that so it points to the correct directory, and in your views, your partials will need to be adjusted similarly if you are using the full directory path (which you might do if the partial is in the directory of another controller).

# This works (as does the implicit version, i.e., no render statement at all)
render :action => 'show'

# This
render :template => 'samples/show'
# ...becomes this
render :template => 'sample_log/samples/show'

# This
render :partial => 'samples/list_table_row',
             :collection => @samples
# ... becomes this
render :partial => 'sample_log/samples/list_table_row',
             :collection => @samples

# But this stays the same
render :partial => 'list_table_row',
             :collection => @samples

Functional Testing
You will need to modify your functional tests. Just as with the controllers, they need to go into an identically name directory, and put into the correct name space. Rake will find the tests in subdirectories without any prompting.

class SampleLog::SamplesControllerTest < ActionController::TestCase

Besides that, the other major change is to make sure all your paths are defined using helper methods, as in the controller.

Integration Testing
These tests will need to be modified so your HTTP requests point to the right URL, and the templates you expect are in the right folder

# This
get "/samples/home"
# ... becomes
get "/sample_log/samples/home"

# This
assert_template "samples/home"
# ... becomes
assert_template "sample_log/samples/home"

Models
Controllers and views are closely coupled, so if you want your controllers in a subdirectory, your views must be in an identically named subdirectory. On the other hand, your models can be handled independantly (when I was trying this out, I moved the controllers and views of one section first, and had the project working fine with the corresponding models still in the top app/model directory, then I moved all the models for all the sections, and again had it working fine, then moved the remaining controllers and views). That said, it would seem to me that best practice has to be to have your directory structure identical for controllers, views and models.

You have two choices with the models. The first is to use the same namespace concept as the controllers. In this case, the database name also needs to have the nampespace prepended.

sample_log/sample.rb    # The file name
SampleLog::Sample       # The class name
sample_log_samples      # The database

That is probably the best way to go if you are starting from scratch, but if you are modifying an existing project, you could find that there are a lot of changes required (and so a lot of potential for errors).

The alternative is to forget the name spaces, and just make sure Rails can find your files. Two (nearly identical) approaches can be seen here:

http://toolmantim.com/articles/keeping_models_in_subdirectories
http://www.paperplanes.de/2007/5/2/namespacing_your_rails_model_an.html

The basic idea is that you tell Rails about the location of your models. Rails keeps an array of paths that it loads from, so you need to add your new paths to that in config/environment.rb. This code snippet adds three folders, sample_log, computer_log and user_log and would go inside the Rails::Initializer.run do |config| block.

ary = %w(sample computer user)
ary.each do |dir|
 config.load_paths << "#{RAILS_ROOT}/app/models/#{dir}_log" end

That is all you need to do for your models. The unit tests can be shifted into their own subdirectory if you want (and I think you should), but none of the unit test or model files need to be changed at all.

ActionMailer
One last point. If you put your ActionMailer templates in a subdirectory, you need to tell ActionMailer where to find them. You do that in config/environment.rb, inside the big Rails::Initializer.run block, like this:

config.action_mailer.template_root = "#{RAILS_ROOT}/app/views/#{my_sub_dir}"

Struggling with Ruby: Contents Page

Ruby Arrays

2009-11-07T13:17:00.003Z

An array is a group of values in a certain order. You can mix-and-match what you put in the array (it is all objects with Ruby), including hashes and other arrays.

a = ['one', 2, 3.0]

A quick way to create an array of strings (if each string is a single word) is like this (you can use any matching brackets, or indeed more punctuation):

a = %w(one two three)
# => ["One", "Two", "Three"]

To add an element to an existing array do this:

array << "new element"

You can join two arrays using the addition operator.

b = [4, 16]
c = a + b
# =>  ["One", "Two", "Three", 4, 16]

Use include? to determine if the given object is in the array. To access an array member use [], or at or fetch. The [] and at methods return nil if the index is out of range, while fetch throws an exception, or a default value of given. A negative index counts back from the end, while a range returns a subset of the array.

ary = %w(zero one two three four five six)
p ary[2]
# => "two"
p ary.at(3)
# => "three"
p ary[-1]
# => "six"
p ary[2..4]
# => ["two, "three", "four"]

delete_if
Ruby has some very neat tricks with arrays. Want to delete all the elements of an array of hashes that have a body that is nil?

array.delete_if { |x| x.body.nil? }

The delete_if removes from the array any elements that evaulate to true in the block. Note that the delete_if method seems to ignore the convention of naming methods that affect the object itself with an exclamation mark.

join
The join method concatenates each member of an array into a long string. The supplied parameter is used to separate each item. The * operator does the same.

a = %w(one two three four)
# => ["one", "two", "three", "four"]
a * ', '
# => "one, two, three, four"

map, select and reject
The map method (aka collect) constructs a new array by processing each element in the array as per the block, while select returns a new array containing only those elements where the block evaluates to true. The reject method gives an array for the elements where the block is not true.

people = [
{:name => 'Fred', :age => 19},
{:name => 'Boris', :age => 23},
{:name => 'Mary', :age => 27},
]

p people.map {|e| e[:name]}
# => ["Fred", "Boris", "Mary"]

p people.select {|e| e[:age] <> [{:name=>"Fred", :age=>19}]

p people.reject {|e| e[:age] <> [{:name=>"Boris", :age=>23},
                               {:name=>"Mary", :age=>27}]

sort
The sort method will, as the name suggests, sort the array, using the <=> relationship. Alternatively you can supply block to have it sorted by a custom comparison.

people.sort { |a, b| a[:age] <=> b[:age] }
   # youngest to oldest

Note that your comparison must return -1, 0, or +1. In this example, I therefore could not use <.

If you use the Enumerable mixin discussed later you also have a sort_by method. This is not as fast to run, but can be quicker to code. In this method, the block determines a value for the element, for ranking purposes. Here is the previous example re-written.

people.sort_by { |a| a[:age] }

pop and push, shift and unshift
You can use push and pop to add or remove the last element, and

unshift and shift to add and remove from the start.

a = %w(one two three)
# => ["one", "two", "three"]
a.push 'four'
# => ["one", "two", "three", "four"]
a.pop
# => "four"
a
# => ["one", "two", "three"]
a.unshift 'zero'
# => ["zero", "one", "two", "three"]
a.shift
# => "zero"
a
# => ["one", "two", "three"]

Extending Array, part 1
You can, of course, add your own methods to Array. Here are some examples.

class Array

# Shuffle an array
# from http://snippets.dzone.com/posts/show/2994
def shuffle
sort_by { rand }
end
def shuffle!
self.replace shuffle
end


# Randomly pick one element of the array.
def pick
fetch rand(length)
end


# Returns a total over each element in the array
# where the value for an element is determined
# by the given block. This example will look
# through an array of hashes
# and return the total of the square of values
# with the key :value
# ary.total { |e| e[:value] * e[:value] }
def total &prc
val = 0
each do |e|
 val += prc.call(e)
end
val
end


# Returns an element that best fits the criteria
# given by the block. This example will look
# through an array of hashes and return the element
# with the highest value with the key :value
# ary.find_best { |x, y| x[:value] < y[:value] }
def find_best &prc
best = fetch(0)
each { |e| best = e if yield(best, e) }
best
end


# Returns the elements of the given array as
# string with each element listed
# in the form "one, two and three".
def list
join(', ').reverse.sub(' ,', ' dna ').reverse
end
end

Extending Array, part 2
Another way to extend Array is to "mixin" the Enumerable module.

class Array
include Enumerable
end

This has several interesting methods (and also some that are already in Array). Use any? and all? to determine if at least one element evalauates to true on the block, or all of them do.

a = %w(one two three)
a.any? {|e| e.length == 5}
# => true
p a.all? {|e| e.length == 5}
# => false

You can find an element in an array using find (aka detect). This method returns the first element for which the block evaulates to true. The method takes an optional parameter, this is returned if no element is found that fits.

people.find { |e| e[:age] == 23 }

The inject method combines each element of the array.

total_age = people.inject(0) { |memo, e| memo += e[:age] }
# => 69

The supplied parameter is the initial value (in this example, zero). This is technically optional, but going to be necessary in most cases (including this example) for the calculation to work in the first iteration. The memo is the ongoing value, so the increment is added to this.

Ref:
http://www.ruby-doc.org/core/classes/Array.html
http://ruby-doc.org/core/classes/Enumerable.html

Struggling with Ruby: Contents Page

Duck-typing

2009-10-22T21:21:00.002+01:00

Let us say I want to be able to output a variety of objects (say strings, floats and dates) on a web page. With Java I would create a new class with over-loaded methods, like this (warning: my Java is getting rusty, and this is untested):

class Formatter {
  SimpleDateFormat sdf = new SimpleDateFormat("MM/dd/yy");

  public static String show(String s) { return s; }
  public static String show(Date d) { return sdf.format(d); }
  public static String show(double x) { return x < 0.05 ? '<0.1' : "" + (Math.round(x * 10) / 10.0); }
  public static String show(Object o) { return o.toString(); }
}

To invoke, I would use this:

Formatter.show(myObject);

Java will select the method based on the class I send. Note that there is a method for object to catch anything unexpected.

In Ruby, I would approach this quite differently. There is no need for a new class, just modify the existing classes. This is not possible in Java; I could extend Date, but I would have to ensure that every date I sent was of my date class. String and float cannot be extended at all.

class String
  def show
    to_s
  end
end

# Remember the require 'date.rb'
class DateTime
  DATE_FORMAT = '%d/%b/%y'

  def show
    strftime(DATE_FORMAT)
  end
end

class Float
  def show
    self < 0.05 ? '<0.1' : (self * 10).round / 10.0
  end
end

class Object
  def show
    to_s
  end
end

That is more verbose, but the result is much neater, much more object-orientated, as now the method can be invoked like this:

my_object.show

I have a library of useful Java methods. It is a collection of static methods that do various operations on arrays and strings. In Ruby, I am building up a library that changes how arrays and string behave. Just occasionally, that is not the best way - again because of duck-typing, as it happens. Say I have a method to format dates consistently. All it does is invoke strftime with a certain format string. I could define my method as part of the DateTime class, however I would then be unable to use it with Time objects. In this case, I am better adding the method to the Object class, then DateTime, Date and Time objects would all be able to use it, as they all have strftime methods (and duck-typing allows this to work).

The Case Statement and Relationship Operator

2009-10-21T20:18:00.002+01:00

Ruby supports a case statement, in which the value of something is matched against a set of options

case value
when 1, 2, 5
do_this
when 3
do_that
else
do_the_other
end

In this example the first when will catch three different values. Note that unlike the C family of languages, there is no break statement used. Options cannot fall though to the next one.

You do not need to give a parameter to the case statement, as seen here.

case
when @t == 7
p 't is 7'
when @s == :this
p 's is :this'
else
p 'none of the above'
end

In this form, the case is like an if/elsif chain.

if @t == 7
p 't is 7'
elsif @s == :this
p 's is :this'
else
p 'none of the above'
end

So why use case? Well, case returns a value, so instead we could do this:

s = case
when @t == 7
't is 7'
when @s == :this
's is :this'
else
'none of the above'
end

The Relationship Operator

The case statement uses the relationship operator, === (aka triple equals or trequals operator) when comparing the value to each when. The relationship operator is really a method, and in Object the relationship operator is defined to do the same as the equals operator. However, the important point here is that it can be overridden as required. Patterns override it to check for a match, and the Range class overrides it to check if the value is within the range. That allows you to do things like this:

mark = 56

grade = case mark
when 1..25
'Fail'
when 26..50
'C'
when 51..75
'B'
when 76..100
'A'
else
'Out of range!'
end

Here grade is set to 'B' because (51..75) === 56 evaulates to true. Note that this is calling the === method on 51..75. Write it the other way around, 56 === (51..75), and the === method of 56 is invoked, and the expression evaluates to false.

See more here:
http://www.pmamediagroup.com/2009/07/dont-call-it-case-equality/

Struggling with Ruby: Contents Page

Gotchas for Models

2009-09-22T21:19:00.005+01:00

I have hit a few issues using Rails, some very frustrating. Here are a selection that relate to the models.

Constructors with Arguments
The first is how to handle a constructor that will take a parameter. In Ruby, when you call new for a class, the object is created, then the initialize method is invoked. If you want to do that for your model, then you need to invoke the initialize method in the superclass to ensure everything is set up, and that is done through the super keyword.

The problem is that super takes with it all the parameters that were sent to the method. If your initialize takes two parameters, both parameters get sent to the initialize in ActiveRecord::Base, which throws an exception, because it expects just one; a hash. The solution is to use brackets with super; super().

On a kind of related note, see this page about why overriding initialize may not be the best solution, as Rails sometimes creates objects another way.
http://blog.dalethatcher.com/2008/03/rails-dont-override-initialize-on.html

Column Values
The second gotcha is accessing column values within the model. When you are not in the model, it is very simple:

@post.title = 'My new title'
s = @post.body

Ruby and Rails work together to make this seem as though you are accessing a variable in a class. However, the reality is that you are invoking methods, and this runs into problems when you do it from inside the class. You might imagine that this would work:

class Post < ActiveRecord::Base
 def initialize params = {}
   body = params[:body]
   s = body
   title = "Post: #{s[0..100]}"
 end
end

It does not. The s = body line is fine; I guess Ruby notes that no variable called body exists, so invokes the method_missing method, and everything is good. Not so with title = 'My new title'. Ruby assumes that this is an assignment to a new variable, rather than a method invocation (why does the interpretor not check in the method exists first? I can only assume this is a performance issue). This has lead to some obscure bugs where values are mysteriously failing to get assigned. The solution is to prefix with self., which gives Ruby the hint that this is a method call.

class Post < ActiveRecord::Base
 def test
   self.title = 'My new title'
   s = body
 end
end

Migrations
One of the most common reason my unit tests do not work is that I have done a migration on the development database, and forgotten the testing database (rake db:test:prepare).

Fixtures and Migrations
When you create a model, some default fixtures are also created for testing. If you subsequently modify the migration file, those fixtures might not work, and you will get an error like this when you run your test:

ActiveRecord::StatementInvalid: Mysql::Error: #42S22Unknown column

Reverting to Rails 2.2.2
Rails 2.3.2 adds a new helper file for new models, in units/test/helpers. If you then revert to 2.2.2, this will crash rake when you run your unit tests (but other tests will be okay).

Saving records
When you save a record (and it is not a new record), Rails will work out what has changed, and only update those fields that have actually changed. However, it is not that reliable at spotting a change. In this example, no change is made.

r = MyRecord.find 19
r.description.sub! 'this', 'that'
r.save

The problem is that Rails uses a flag on each attribute, and if you do not set the flag, the attribute is not updated. Assignment automatically sets the flag, so it is easy to over-look. The following will work fine:

r = MyRecord.find 19
r.description = r.description.sub 'this', 'that'
r.save

The alternative is to tell Rails explicitly that the attribute is being changed:

r = MyRecord.find 19
r.description_will_change
r.description.sub! 'this', 'that'
r.save

Refs:
http://api.rubyonrails.org/classes/ActiveRecord/Dirty.html
http://ryandaigle.com/articles/2008/3/31/what-s-new-in-edge-rails-dirty-objects

First may not be first
I have database that has been in use for some ten months ago. I wanted to retrieve the very first sample. Should be easy:

Sample.find(:first)

Apparently not. This was retrieving a record from only a couple of weeks ago, with an ID of 1269. And in my development database, when I tested this, it worked fine. To get the right sample, I had to specify what to order by (I have no idea what ordering brings record 1269 to the front).

Sample.find(:first, :order => "created_at ASC")

Erroneous commas in hash assignments
This one is not limited to models. If you are assigning values to a hash, an extra comma can wreak havoc! Usually extraneous punction is ignored (extra semi-colons, for example), or throws an error. Not in this case.

h = {}
h[:name] = 'Fred'
h[:desc] = 'Big'

p h.inspect
# => "{:name=>\"Fred\", :desc=>\"Big\"}"

h[:name] = 'Fred',
h[:desc] = 'Big'

p h.inspect
# => "{:name=>[\"Fred\", \"Big\"], :desc=>\"Big\"}"

Changes to a file not always noted
While you are developoing your system, chances are you will have your local web server running, and will be looking at how the web site behaves and looks as you make changes. Generally, this is fine. However, some changes that you make are not going to change the web site, for example, changes to files in config. If you have the console open, and type reload! you might find that even changes to your model (I think this may be when connected to the production database, so it is going to be very rare, admittedly). You may need to shut down the console or web server, and restart it to get the changes to have an effect.

Struggling with Ruby: Contents Page

Displaying Usage Statistics on a Bar Graph

2009-06-16T21:38:00.002+01:00

My last post was about creating images of line graphs in Rails. Now I am going to have a go at histograms (bar graphs), using HTML to draw the graph, rather than creating an image.

The Data
I recently wanted to see how frequently entries were added to a table in my database. Each entry has a created_at column, so it should be easy to break this down by week or by month. Or so I thought. It was not as easy as I had hoped. There is no simple Rails way to group records within a set time interval. Instead, I had to use some actual SQL. And as my development PC is running MySQL and my server has PostgreSQL, I had to use two different dialects of SQL. It is not pretty, but this is what worked for me. First, I set up a SQL string (I did this in the controller while trying it out, but moved it to config/initializers/constants.rb later; you need to restart the web server after changing constants.rb):

module Sql
# SQL to get usage stats by week

# Different SQL for different dialects
# Both will generate the number of days since the year dot
# when the records was created
# MySQL has year and dayofyear functions
MYSQL_YEAR = 'year(created_at)'
MYSQL_DAY = 'dayofyear(created_at)'
# PostgreSQL uses the extract function for both
POSTGRESQL_YEAR = 'extract(year from created_at)'
POSTGRESQL_DAY = 'extract(doy from created_at)'
# Select the correct SQL based on the name of the database adapter
SQL_YEAR = ActiveRecord::Base.configurations[RAILS_ENV]['adapter'].match(/mysql/) ?
             MYSQL_YEAR : POSTGRESQL_YEAR
SQL_DAY = ActiveRecord::Base.configurations[RAILS_ENV]['adapter'].match(/mysql/) ?
             MYSQL_DAY : POSTGRESQL_DAY

# The rest of the SQL is the same
# The second line calculates the week number for the record
SQL =
<<END
select count(sample_reference) as count,
      floor((#{SQL_YEAR} * 365 + #{SQL_DAY}) / 7) as week,
      #{SQL_YEAR} as year,
      floor(#{SQL_DAY} / 7) as week_no
      from samples
      group by week
      order by week desc
      ;
END

end

You do have to careful when invoking SQL directly that you guard against SQL injection attacks. Not a problem in this case as the SQL command is in no way altered by the end-user.

SQL does have functions for getting the week number, however, funny things happen just before the new year, with records created in week zero, but in the previous year, so I abandoned using these functions. Months would have easier, but I wanted weeks.

The Controller
After all that, the method in my controller is fairly simple. Some sites I looked at used establish_connection before connection. As I understand it, establish_connection tells Rails that you want to potentially make a connection to a database, allowing you to create actual connections as oftyen as you like in the future. Rails does that automatically for ActiveRecord, so there is no need in this situation for me to. The map method adds a new key-value pair to each hash in the array; this will be used for the labels (eg "2009 week 3").

def graph
ary = ActiveRecord::Base.connection.select_all(Sql::SQL)
@result = ary.map do |e|
  e['label'] = "#{e['year']} week #{e['week_no']}"
  e
end
end

A Generic Partial
I created a partial to display the results in the bar graph. This is a general thing that could be used in any number of web pages to display this sort of data. It uses HTML to extend a small image across a table, according to the data. Note that this uses the find_best method I described on the blocks page; this pulls out the entry with the highest count, against which all the others are scaled.

<table>
<%
max = data.find_best { |x, y| x['count'].to_i < y['count'].to_i }['count'].to_i
data.each do |element|
  count = element['count'].to_i
  size = "#{count * 800 / max}x20"
%>
<tr>
  <td><%=h element['label'] %></td>
  <td><%=h count %></td>
  <td><%= image_tag 'bar.gif', :size => size %></td>
</tr>
<% end %>
</table>

The View
The partial is invoked like this:

<%= render :partial => 'bargraph',
              :locals => { :data => @result } %>

In the locals hash, :data is mapped to the array that holds the data. Each entry in the array must have a 'count' value, used for the size of the bar, and another value, the key for which is 'label'.

Struggling with Ruby: Contents Page

Displaying Trends on a Graph Image

2009-06-15T21:19:00.002+01:00

This builds on my last two posts on drawing images for Rails with Java.

My objective here was to display values from a series of records on a graph to show possible trends (specifically analytical results for samples submitted to a lab). There are two quite separate issue here involving firstly extracting data from the database table, and secondly creating an image of a line graph on-the-fly.

Getting the Data
Step one, then, is to grab the data. The easy way is to just use find all:

ary = Worksheet.find :all

However, that could involve a lot of data coming across from your database that you do not need. We are only interested in the contents of one column. Better to just extract out the data from that column.

ary = Worksheet.find :all, :select => 'result'

This gives us an array of Worksheet objects, but each object has only the specific column set to a value. We need to grab those values, and the map method gives an easy way to convert to an array of numbers. This can all go inside a class method in Worksheet (in this case the name of the column is in a variable, column_name, to keep it general).

def self.collect_data column_name
Worksheet.find(:all, :select => column_name).map do |e|
e.send(column_name)
end
end

Draw the Graph
Step two is drawing the graph (see also here for drawing with Java on Rails). I created a new Ruby class in its own file in the models directory, using class methods. I wanted the graph to be able to scale itself, but for the lower and upper bounds to be round numbers; the graph_limits methods handles that.

Here is the basis of the class. Java needs to be included, and for convenience I have imported all the Java classes I will be using. Then I set up some constants:

include Java

class Graph

java_import java.io.ByteArrayOutputStream
java_import java.awt.image.BufferedImage
java_import java.awt.Color
java_import java.awt.RenderingHints
java_import java.awt.geom.GeneralPath
java_import java.awt.geom.Line2D
java_import java.awt.Font
java_import java.awt.BasicStroke
java_import javax.imageio.ImageIO

WIDTH = 800
HEIGHT = 600
FOREGROUND = Color.new 0.2, 0.2, 0.2
BACKGROUND = Color.new 0.95, 0.95, 0.95
PLOT = Color.blue
FONT = Font.new("SansSerif", Font::PLAIN, 22)

end

I wrote three helper methods (all protected). Note that the second uses the find_best method I described on the blocks page;

  # Converts the data point to a vertical
# position on the image,
# scaled between min and max.
def self.calc y, min, max
19.0 * HEIGHT / 20 - (y - min) *
   18 * HEIGHT / (max - min) / 20
end

# Determines the minimum and maximum
# values from the data, and rounds them
# down and up respectively to give lower
# and upper display limits.
def self.graph_limits data
# See my blocks page for find_best method
min = data.find_best { |x, y| x > y }
max = data.find_best { |x, y| x < y }
modifier = 10 **
        -(Math.log10(max - min).floor)
min = (min * modifier).floor *
        1.0 / modifier
max = (max * modifier).ceil *
        1.0  / modifier
# Ruby allows a method to return
# multiple values
return min, max
end

# Draws a line and label for the y-axis
def self.graph_line g2, text, h
g2.drawString(text, 0, h)
# Note that Line2D uses inner
#  classes, accessed via ::
g2.draw(Line2D::Double.new(WIDTH / 10,
            h, 9 * WIDTH / 10, h));
end

Now that we have the foundations, we can draw the graph.

  def self.line_graph data
min, max = graph_limits data

# Set up image object
off_image = BufferedImage.new(WIDTH, HEIGHT,
                 BufferedImage::TYPE_INT_ARGB)
g2 = off_image.createGraphics()
g2.setRenderingHint(RenderingHints::KEY_ANTIALIASING,
        RenderingHints::VALUE_ANTIALIAS_ON)

# Set up background
g2.setPaint(BACKGROUND)
g2.fillRect(0, 0, WIDTH - 1, HEIGHT - 1)
# Note: You get wierd results if you do not
# fill your background
g2.setPaint(FOREGROUND)
g2.drawRect(0, 0, WIDTH - 1, HEIGHT - 1)

# Set up the y-axis (no x-axis drawn)
g2.setFont(FONT)
graph_line g2, min.to_s[0..5], HEIGHT * 9 / 10
graph_line g2, max.to_s[0..5], HEIGHT / 10
graph_line g2, ((min + max) / 2).to_s[0..5],
                   HEIGHT / 2

# Convert data to image coordinates
x_points = Array.new(data.length) do |i|
 (i * 8.0 * WIDTH / (data.length - 1) / 10) +
       WIDTH / 10
end
y_points = Array.new(data.length) do |i|
  calc(data[i], min, max)
end

# Generate a GeneralPath object from the
# coordinates
polygon = GeneralPath.new(
               GeneralPath::WIND_EVEN_ODD,
               data.length)
polygon.moveTo(x_points[0], y_points[0])
(1...x_points.length).each do |index|
  polygon.lineTo(x_points[index],
                   y_points[index])
end

# Draw the GeneralPath object
g2.setPaint(PLOT)
g2.setStroke(BasicStroke.new(1.5))
g2.draw(polygon)

# Convert for web image
os = java.io.ByteArrayOutputStream.new
ImageIO.write(off_image, "gif", os)
String.from_java_bytes(os.toByteArray)
end

Ptting it Together
Step 3 is to put it all together. In my controller I put in a new method (this needs to be mentioned as a collection in your routes, as it has no specific record associated with it):

  def graph
respond_to do |format|
  format.html
  format.gif  do
    send_data Graph.line_graph(
              Worksheet.collect_data('result')),
              :type => "image/gif",
              :disposition => "inline"
  end
end
end

The important part is the bit starting with send_data. The collect_data method is invoked on Worksheet, returning an array of values from the "result" column of the database table. This is sent to the line_graph method of Graph, which generates the image.

Finally, we need a view. This must be called graph.html.erb, of course, and should include the following:

<%= image_tag "/Worksheet/graph/x.gif", :size => "800x600" %>

If this was an image for a specific record in your table, you would need the id of the record. As this image is for a collection of records, no id is applicable. Nevertheless, you need something there, so I have called in "x".

Struggling with Ruby: Contents Page

Creating Images For Rails With Java

2009-06-09T20:37:00.003+01:00

Some time ago I had a look at RMagick to create images on-the-fly in a Rails application. The problem with RMagick is that it is not compatible with JRuby, and if you are going to be using TomCat as your webserver, you need to be using JRuby. However, JRuby does present a ready alternative through Java.

To look at this I created a new controller, images_controller, in an existing Rails project. In hindsight, images might have been a bad name, as there is a folder called public/images already. However, Rails was able to work out whether the image should come from public/images or via my images controller, so the issue is really only whether it is confusing to the developer.

The first thing you need to do is set up the new MIME types. There are various places you can do this, but the correct one, I believe, is in config/initializers/mime_types.rb. This is what I added:

Mime::Type.register "image/jpg", :jpg
Mime::Type.register "image/png", :png
Mime::Type.register "image/gif", :gif

Now let us create the controller. The first thing you need to do is include Java. Then you should import all the classes you will need. The second step is optional, but the alternative is writing out the full name of he Java classes every time you use them, which leads to longer and harder to read code. Note that unlike in Java you cannot use the * wildcard to import a whole bunch of classes in one line. Here is the start of my controller:

class ImagesController < ApplicationController
include Java

java_import java.io.ByteArrayOutputStream
java_import java.io.File

java_import java.awt.image.BufferedImage
java_import java.awt.Color
java_import java.awt.RenderingHints
java_import java.awt.geom.GeneralPath
java_import java.awt.Font

java_import javax.imageio.ImageIO
end

Now I need an action defined by a method, image. A clever feature of Rails is that you can respond differently depending on the file extention, which is what I do here. The respond_to block directs the action to the correct format (as long as the format is a known MIME type).

The HTML response is blank. Rails will do the default action, which is to return a page derived from the view images/image.html.erb. The other three responses follow the same format. Each invokes the send_data method, with the data (the image) as the first parameter, followed by a hash of options. The :type is simply the MIME type. The :disposition determines if the data is to be displayed ("inline"), or downloaded ("attachment"). For attachments, you can set a :filename parameter too, and there is also a :status parameter, which conveniently defaults to 200, success.

API for send_data:
http://api.rubyonrails.org/classes/ActionController/Streaming.html

def image
@name = params[:id]

respond_to do |format|
 format.html
 format.jpg  do
   send_data get_jpeg(@name), :type => "image/jpeg",
                     :disposition => "inline"
 end
 format.png  do
   send_data get_png(@name), :type => "image/png",
                     :disposition => "inline"
 end
 format.gif  do
   send_data get_gif(@name), :type => "image/gif",
                     :disposition => "inline"
 end
end
end

So that just leaves the methods that generate the image data. These should all be protected, by the way.

This first method simply grabs a file from public/images and displays it. Once it has the file, it creates an output stream, and writes the image file to that stream in the specified format. It then converts from the stream to a Ruby string, via a Java byte array.

def get_jpeg filename
imagefile = File.new("#{RAILS_ROOT}/public/images/#{filename}.jpg")
os = ByteArrayOutputStream.new
ImageIO.write(ImageIO.read(imagefile), "jpeg", os)
String.from_java_bytes(os.toByteArray)
end

Converting to another format is trivial (though noticeably slower).

def get_png filename
imagefile = File.new("#{RAILS_ROOT}/public/images/#{filename}.jpg")
os = ByteArrayOutputStream.new
ImageIO.write(ImageIO.read(imagefile), "png", os)
String.from_java_bytes(os.toByteArray)
end

This version does an operation, converting the image to its negative.

def get_jpeg filename
imagefile = File.new("#{RAILS_ROOT}/public/images/#{filename}.jpg")
bi = ImageIO.read(imagefile)
big = bi.getGraphics

# Create a look-up table as an array
lut = Array.new(256) { |j| 256 - j }
# Convert to Java byte array
jlut = lut.to_java :byte
# Convert to Java byte look-up table
blut = java.awt.image.ByteLookupTable.new(0, jlut)
# Convert to Java operation look-up table
op = java.awt.image.LookupOp.new(blut, nil)
# Apply the operation
dest = op.filter(bi, nil)
# Draw the new image
big.drawImage(dest, 0, 0, nil);
# Create an output stream, and write the image to it
os = ByteArrayOutputStream.new
ImageIO.write(dest, "jpeg", os)
String.from_java_bytes(os.toByteArray)
end

The next method actually generates a GIF image on-the-fly, putting the filename in the middle of a simple image. The basic methodology is to create a blank BufferedImage object (rather than from a file), use that to create a Graphics2d object (just as before). The image is built by calling methods on the Graphics2d object, and finally the last three lines create the output stream and write the image to it (just as before).

WIDTH = 400
HEIGHT = 300

def get_gif filename
off_image = BufferedImage.new(WIDTH, HEIGHT,
         BufferedImage::TYPE_INT_ARGB)

g2 = off_image.createGraphics()
g2.setRenderingHint(RenderingHints::KEY_ANTIALIASING,
         RenderingHints::VALUE_ANTIALIAS_ON)

# Set up background
g2.setPaint(Color.lightGray)
g2.draw3DRect(0, 0, WIDTH - 1, HEIGHT - 1, true);
g2.draw3DRect(3, 3, WIDTH - 7, HEIGHT - 7, false);

x = 7;
y = 7;
x3_points = [x, WIDTH - 2 * x, x, WIDTH - 2 * x]
y3_points = [y, HEIGHT - 2 * y, HEIGHT - 2 * y, y]
filled_polygon = GeneralPath.new(GeneralPath::WIND_EVEN_ODD,
              x3_points.length);
filled_polygon.moveTo(x3_points[0], y3_points[0])
(1...x3_points.length).each do |index|
 filled_polygon.lineTo(x3_points[index], y3_points[index])
end
filled_polygon.closePath()
g2.setPaint(Color.red)
g2.fill(filled_polygon)
g2.setPaint(Color.black)
g2.draw(filled_polygon)
g2.setPaint(Color.yellow)
g2.setFont(Font.new("Helvetica", Font::PLAIN, 22))
g2.drawString(filename, WIDTH / 2, HEIGHT / 2)

os = java.io.ByteArrayOutputStream.new
ImageIO.write(off_image, "gif", os)
String.from_java_bytes(os.toByteArray)
end

Okay, so we can generate images; how do we get them on to a web browser? The easy way (to test the above work) is to invoke it though the address bar. Say I have an image saved in public/images called sheep.jpg, I can use the following:

http://localhost:3000/images/image/sheep.jpg
# => Gives a negative of the image
http://localhost:3000/images/image/sheep.png
# => Gives the PNG converted image
http://localhost:3000/images/image/sheep.gif
# => Gives the generated GIF with "sheep" written on it

What we really want to to have those images embedded in a web page. So here is a view, views/images/image.html.erb, that will do just that:

<h1>My <%= @name %> image</h1>

<%# This image has been generated on the fly and served via my controller %>
<%= image_tag "/images/image/#{@name}.gif", :size => '400x300' %>

<%# This image has been processed and served via my controller %>
<%= image_tag "/images/image/#{@name}.jpg", :size => '400x300' %>

<%# This image has been processed and served via my controller; uses HTML tags directly %>
<img alt="Sheep" height="300" src="/images/image/<%= @name %>.jpg" width="400" />

<%# This image has been processed and served via my controller as a PNG %>
<%= image_tag "/images/image/#{@name}.png", :size => '400x300' %>

<%# This image came directly from public/images %>
<%= image_tag "/images/#{@name}.jpg", :size => '400x300' %>

<%# This image has been processed and served via my controller, va a helper method %>
<%= images_image_tag @name, :jpg, :size => '400x300' %>

One of those methods uses a helper method, and that would be my prefered way. Here is that method:

def images_image_tag name, type, options = {}
image_tag "/images/image/#{@name}.#{type.to_s}", options
end

Struggling with Ruby: Contents Page

JRuby and Java

2009-06-08T21:20:00.006+01:00

If you are using JRuby you can access Java functionality in your Ruby code pretty easily. Two possible reasons to do this are to create an involved user interface (for simple GUIs the Shoes toolkit is excellent, but it is somewhat limited), and to create images on-the-fly for your Rails application (RMagick offers an alternative, but cannot be used with Tomcat, which requires JRuby). I may be posting on both these later, but first, I want to explore the basics of using Java from Ruby.

I am using NetBeans, which has a particular file structure for projects, and also makes the creation of a JAR file very easy (just press F11 and the main project gets built and compressed into a JAR file inside the dist folder). For testing purposes, I created a project called JavaForRuby (and so a package name javaforruby), with a simple test class, TestObject, which has two instance variables, with setters and getters, and a static method, getStatus, which returns a String object.

And so to the Ruby side. You need to be running JRuby, of course. I had some problems getting my Java classes to work, and this seemed to be resolved by using a more recent version of JRuby (1.3.0RC1), though I am sure it should work with older versions.

The first thing to do is introduce Java to Ruby, then you need to get your JAR linked up, and then your class loaded. Once that is done, the class can be accessed:

include Java

require "#{File.dirname(__FILE__)}/../../JavaForRuby/dist/javaforruby.jar"

include_class "javaforruby.TestObject"

p TestObject.getStatus

Creating and using an instance of a Java object is simple:

tobj = TestObject.new 'My Tester', 5
p tobj.class      # => Java::Javaforruby::TestObject
p tobj.java_class # => class javaforruby.TestObject
p tobj.get_name   # => "class javaforruby.TestObject"My Tester"
p tobj.get_value  # => 5
tobj.set_name 'My Renamed Tester'
p tobj.get_name   # => "My Renamed Tester"

Note that I used the conventions of Java to define the object, but the conventions of Ruby to access it from Ruby; JRuby has associated get_name in Ruby with getName() in Java.

Let us try using an array. JRuby adds a to_java method to Array, and this takes a single parameter, the class of the objects for the array.

ja = %w(one two three).to_java :string
p ja.java_class     # => [Ljava.lang.String;
p ja[0]             # => "one"
p ja[0].class       # => String
ja.each { |e| p e } # => "one"
                   "two"
                   "three"

What happens if you do not tell it the object type? Well, the each method still works the same; the system works out what each object is. Accessing elements by their index is not so good (I did wonder if fetch might work, but throws an NoMethodError exception).

ja = %w(one two three).to_java
p ja.java_class     # => [Ljava.lang.Object;
p ja[0]             # => #<Java::JavaLang::String:0x155d3a3 @java_object=#<Java::JavaObject:0x57e787>>
p ja[0].class       # => "Java::JavaLang::String
ja.each { |e| p e } # => "one"
                   "two"
                   "three"

We can combine the array and the custom class to make a Java array of Java objects in Ruby.

toja = [
TestObject.new('My First Tester', 5),
TestObject.new('Second', 93),
TestObject.new('Last Tester', 42),
].to_java

toja.each { |e| p e.get_name }

Hashes are no problem either.

hash = {:name => 'Fred', :age => 27}
java_hash = java.util.HashMap.new(hash)
p java_hash.get :name  # => "Fred"

Rather than using the full path name in the method call, you can import each class. You should be able to import a complete package, though I could not get it to work with JRuby 1.3.0RC1 (but I could with 1.1.6).

java_import "java.util.HashMap"
# import "java.util"
# include_package "java.util"

hash = {:name => 'Fred', :age => 27}
java_hash = HashMap.new(hash)
p java_hash.get :name

You can use import rather than java_import, and many tutorials indeed do this. However, import conflicts with Rake, and so, although your system will work as expected, your tests will fail with a NameError and complaints about a 'const_missing' (thanks to Charles Oliver for pointing this out).

Also, I had a problem with import java.io.File. Ruby warns that the constant File already exists ("warning: already initialized constant File"), and I think that this gets overwritten, and the code that is expecting the original value gets very confused... You need to restart your web server after that. Again, java_import seems to fix this.

See also:
http://wiki.jruby.org/wiki/Calling_Java_from_JRuby

Struggling with Ruby: Contents Page

Date and Time in Rails

2009-05-12T21:58:00.002+01:00

Rails adds some extra time and date functionality to Ruby, and so you can do cool things like 10.years. However, when you scratch below the surface, it all becomes a bit mysterious. I put this into a view to investigate:

<%
[1.seconds, 1.minutes, 1.hours, 1.days, 1.months, 1.years].each do |period|
%>
<ul>
<li><%="value=#{period}"%></li>
<li><%="inspect=#{period.inspect}"%></li>
<li><%="class=#{period.class}"%></li>
<li><%="Duration?=#{period.is_a?(ActiveSupport::Duration)}"%></li>
<li><%="to_i=#{period.to_i}"%></li>
<li><%="to_i.class=#{period.to_i.class}"%></li>
<li><%="to_i.inspect=#{period.to_i.inspect}"%></li>
</ul>
<% end %>

The output for seconds looked like this:

value=1

inspect=1 second

class=Fixnum

Duration?=true

to_i=1

to_i.class=Fixnum

to_i.inspect=1

It would seem that what we are using here are ActiveSupport::Duration objects, which are pretending to be Fixnum objects. Their value is the duration in seconds, but an inspect will add the units, and for days, months and years will give the value in those units (but minutes and hours are given in seconds). I would guess the point here is to fool other methods into treating these objects as Fixnum objects, while retaining the added functionality. Curiously, the years method returns an object that pretends to be a Float, even though it does admit to being an ActiveSupport::Duration.

By the way, each of these methods has a singular alias; year can be used instead of years, etc.

Something else a little odd here (I am multiply the first by 1.0 to convert to float arithmetic):

<p>Number of days in a month: <%= 1.0 * 1.months / 1.days %></p>
<p>Number of months in a year: <%= 1.years / 1.months %></p>
<p>Number of days in a year: <%= 1.years / 1.days %></p>

The result:

Number of days in a month: 30.0
Number of months in a year: 12.175
Number of days in a year: 365.25

So the Rails system quietly ignores anomolous leap years (the last was in 1900, the next in 2100 so is a reasonable approximation), but more bizarrely has slightly more than 12 months in a year. Would it not have made more sense to have 30.4375 days in a month?

Rails also introduces the ActiveSupport::TimeWithZone object. This is an object that "acts like" a Time object, but can handle different time zones.

The created_at and updated_at fields of an ActiveRecord return objects of this type. You can also convert an ActiveSupport::Duration to an ActiveSupport::TimeWithZone using ago (and its alias since) and from_now (and its alias until). Both these statements produce ActiveSupport::TimeWithZone objects:

first_sample = Sample.find(:first).created_at
now = 0.seconds.ago

Arithmetic with ActiveSupport::TimeWithZone objects will give a Float object representing a number of seconds (surely an ActiveSupport::Duration masquerading as a Float would make more sense).

elapsed = now - first_sample

You can use ActiveSupport::TimeWithZone objects in your database searches.

# Find all samples changed in the last week
Sample.find :all :conditions => ["updated_at > ?", 1.week.ago]
# Count all samples created between 1 and 2 years ago.
Sample.count :conditions => ["created_at > ? AND created_at < ?", 2.years.ago, 1.year.ago]

Regular Expressions in ruby

2009-05-09T23:14:00.005+01:00

A Regexp is a Ruby object representing a RegEx or "regular expression". So what exactly is a "regular expression"? It is a sort of string that can be used to match against another string. You could think of it as a template or a set of rules that a string can be compared to. Creating a Regexp object is much like creating a string, except that you use the forward slash to delimit it, rather than quote marks.

r = /my regular expression/

Alternatively, you can use this notation (you seem to be able to use any punctuation, just like %q for a string and %w for a word array):

r = %r|my regular expression|
r = %r
r = %r=my regular expression=

That regular expression will just match the string "my regular expression", anywhere in a string. The power of regular expressions lies in their use of wild cards, as we will see later.

Several standard Ruby methods take Regexp objects, but the most basic use is a simple comparison. There are two ways to do that; using the =~ operator or the match method in String. Both can be used either way around:

s = 'Here is my string'
r = /s my/
s.match r
r.match s
s =~ r
r =~ s

The difference is that the match method returns a MatchData object if a match is found, while the =~ operator gives the position of the match. However, the special variable $~ holds the MatchData for the last Regexp comparison performed, so this information is still available (personally, I do not like the built-in globals; if you want the MatchData object, use the match method, and everyone else with have a better idea of what you are doing). See later for more on MatchData.

So what can we put into a regular expression? There is a variety of options allowing you to specify your template as broadly or as narrowly as you want.

.             any character except newline
[ ]           any single character of set
[^ ]          any single character NOT of set
*             0 or more previous regular expression
*?            0 or more previous regular expression (non-greedy)
+             1 or more previous regular expression
+?            1 or more previous regular expression (non-greedy)
?             0 or 1 previous regular expression
??
|             alternation
( )           grouping regular expressions
^             beginning of a line or string
$             end of a line or string
{m,n}        at least m but most n previous regular expression
{m,n}?       at least m but most n previous regular expression (non-greedy)
\1-9          nth previous captured group
\A            beginning of a string
\b            backspace(0x08)(inside[]only)
\b            word boundary(outside[]only)
\B            non-word boundary
\d            digit, same as[0-9]
\D            non-digit
\S            non-whitespace character
\s            whitespace character[ \t\n\r\f]
\W            non-word character
\w            word character[0-9A-Za-z_]
\z            end of a string
\Z            end of a string, or before newline at the end
\/            forward slash

Some simple examples
Here are some examples to get us going.

# Simple pattern matches to dog
p1 = /dog/
p (p1 =~ 'cat-dog') # => 4
p (p1 =~ 'cat-doggy') # => 4
p (p1 =~ 'cat-dig') # => nil
p (p1 =~ 'cat-fox') # => nil

# Pattern matches to d, any letter, then g
p1 = /d\wg/
p (p1 =~ 'cat-dog') # => 4
p (p1 =~ 'cat-doggy') # => 4
p (p1 =~ 'cat-dig') # => 4
p (p1 =~ 'cat-fox') # => nil

# Pattern matches to d, any vowel, then g
p1 = /d[aeiou]g/
p (p1 =~ 'cat-dog') # => 4
p (p1 =~ 'cat-doggy') # => 4
p (p1 =~ 'cat-dig') # => 4
p (p1 =~ 'cat-fox') # => nil

# Pattern matches to dog at end of string
p1 = /dog\Z/
p (p1 =~ 'cat-dog') # => 4
p (p1 =~ 'cat-doggy') # => nil
p (p1 =~ 'cat-dig') # => nil
p (p1 =~ 'cat-fox') # => nil

# Pattern matches to d, anything other than o or u, then g
p1 = /d[^ou]g/
p (p1 =~ 'cat-dog') # => nil
p (p1 =~ 'cat-doggy') # => nil
p (p1 =~ 'cat-dig') # => 4
p (p1 =~ 'cat-fox') # => nil

The MatchData object
If you bracket sections of your Regexp, you can then "capture" these subsections. Each subsection can be accessed as though the MatchData object as an array, with the first element being the entire matched string (though methods like each cannot be used). Use the offset method to determine the position in the string for each group. Here it is in action:

s = "Here is a string with http://www.mydomain.com/path/to/mypage.html in it"
r = /http:\/\/([a-z.]*)(\/[a-z]*)*(\/[a-z]*.html)/i
m = r.match s
p m.string
p m.pre_match
# => "Here is a string with "
p m.post_match
# => " in it"
p m[0]
# => "http://www.mydomain.com/path/to/mypage.html"
p m.offset(0)
# => [22, 65]
p m[1]
# => "www.mydomain.com"
p m.offset(1)
# => [29, 45]
p m[2]
# => "/to"
p m.offset(2)
# => [50, 53]
p m[3]
# => "/mypage.html"
p m.offset(3)
# => [53, 65]
p m[4]
# => nil
#p m.offset(4)
# => IndexError
p m.length
# => 4
p m.size
# => 4

If you want an actual array, use to_a or captures (the latter includes only the capture groups, the former also has the entire match as the first element).

m.captures.each { |e| p e }
# => "www.mydomain.com"
# => "/to"
# => "/mypage.html"
m.to_a.each { |e| p e }
# => "http://www.mydomain.com/path/to/mypage.html"
# => "www.mydomain.com"
# => "/to"
# => "/mypage.html"

I was surprised to find that you can only capture as many subsections as you have brackets. Even though the Regexp matches one subsection to two parts of the URL ("/path" and "/to"), only the last one appears in the array.

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

Shortcut to capture groups
If you only want to pick one section out from a string, there is a quick way to do it. Both of these will pick out a number that follows a space, but the second way is much more conmcise.

# The usual way
md = s.match(/ ([0-9]+)/)
p md.nil? ? nil : md[1]

# The quick way
p s[/ ([0-9]+)+/, 1]

Note that for the first method we have to check for nil (no match is found), otherwise you will throw an error, as you are calling [] on nil. The quick way just returns nil if there is no match.

Back-references to capture groups - or not
A captured group can be refered to later in the pattern. Here is an example:

pattern = /aa(\d+)-\1/
pattern =~ 'aa1234-1234' # => 0
pattern =~ 'aa1234-1233' # => nil

The pattern requires at least one digit inside the brackets. This is the capture group. The backslash-one refers back to this group, and requires that the exact same number is repeated.

Note that capture groups number from one, rather than zero.

You may not want to have back-references to your capture group (remembering that you are limited to only 9 back-references). In the next example, question-mark-colon is used to indicate that we want to capture a group, but not to count it for back reference. We are looking for three groups of numbers in the pattern. The third should be identical to the second, but by marking the first as not counted, we can use \1 instead of \2. This trick allows you to have any number of captures, despite being limited to only nine back references.

pattern = /(?:\d+)-(\d+)-\1/
s = 'bird-cat-12-654-654-otter'
match = pattern.match s
match.to_a.each { |e| p e }
# => "12-654-654"
# => "654"
# => "done"

If you use the String.scan method, it splits a string into an array, each member of which matches the given pattern. If the pattern includes a capture group, then it is the part that is captured that goes into the array. However, if you use ?: yoiu can stop that behavior, to get the whole match (or another capture).

Multiple matches
Often you want to match multiple occurances.

\d       Match exactly one digits
\d?      Match one or zero digits
\d*      Match zero or more digits
\d+      Match 1 or more digits
\d{2,5}  Match between 2 and 5 digits
aeiou*   Match "aeio" followed by any number of "u"
[aeiou]* Match any number of vowels
(aeiou)* Match any number of sequences of "aeiou"

Greedy vs non-greedy
A greedy match will try to match against as many characters as possible, while a non-greedy will match against as few as possible. Here is a simple example to illustrate:

s = "Here another string"
greedy = /[a-z]* [a-z]*/
non_greedy = /[a-z]*? [a-z]*?/
p greedy.match(s)[0]     # => "ere another"
p non_greedy.match(s)[0] # => "ere "

The * will match against a number (or zero) of the preceding, so in the two Regexp objects, they will look for a match against a group of letters, then a space, then a group of letters. The difference is the second has the ?, which makes the * non-greedy.

In both cases they ignore "H" as it does not fit, then they find a match for "e". The match continues, as both are allowed a variable number of letters, and they then match the space. Finally each can have a variable number of lower case letters. The non-greedy version aims for the fewest - in this case zero. The greedy version grabs all it can, so gets "another".

Alternatives
For a set of alternative characters, put them inside square brackets. For sequences, use curved brackets, separated by vertical bars.

[aeiou]   Match any one vowel
(dog|cat) Match either "dog" or "cat"

Building Regexp objects dynamically
You can use #{} when defining a Regexp, just as you can for a double-quoted string. Here is a real example that adds two new methods to the String class (the Rails API already adds them, by the way):

class String
def starts_with? sub
match(/^#{sub}/)
end

def ends_with? sub
match(/#{sub}$/)
end
end

The argument sent to the method gets incorporated into the Regexp. Note how ^ and $ are used to anchor the match to the start of the end of the string respectively.

Case sensitivity and other options
You can change the way the pattern matches either by appending a control code, to change the whole pattern, or using extended patterns (borrowed from Perl). These are things you can insert into a pattern inside brackets, following a question mark. For example, you can use i and -i to turn case sensitivity on and off.

# Case sensitive by default
pattern1 = /fox-cat-dog/
pattern1 =~ 'fox-cat-dog' # => 0
pattern1 =~ 'fox-CaT-dog' # => nil
pattern1 =~ 'fox-CaT-doG' # => nil

# Whole pattern modified, case insensitive
pattern2 = /fox-cat-dog/i
pattern2 =~ 'fox-cat-dog' # => 0
pattern2 =~ 'fox-CaT-dog' # => 0
pattern2 =~ 'fox-CaT-doG' # => 0

# Pattern behavior modified within the pattern
# case sensitivity turned off then back on
pattern2 = /fox-(?i)cat-(?-i)dog/
pattern2 =~ 'fox-cat-dog' # => 0
pattern2 =~ 'fox-CaT-dog' # => 0
pattern2 =~ 'fox-CaT-doG' # => nil

# Pattern behavior modified within the pattern
# case sensitivity turned off for substring
pattern2 = /fox-(?i:cat)-dog/
pattern2 =~ 'fox-cat-dog' # => 0
pattern2 =~ 'fox-CaT-dog' # => 0
pattern2 =~ 'fox-CaT-doG' # => nil

The full list of options is:

/i         case insensitive
/m         multiline mode - '.' will match newline
/x         extended mode - whitespace is ignored
/o         only interpolate #{} blocks once
/[neus]    encoding: none, EUC, UTF-8, SJIS, respectively

The last two can, I think, only be used to modify the whole pattern.

Comments
There are various other options using the brackets-question-mark notation. You can embed a comment:

pattern2 = /cat(?#comment)dog/
pattern2 =~ 'catdog' # => 0

This makes more sense with the x option just mentioned, which causes the pattern to ignore whitespace, and so allow formatting and comments like this:

pattern1 = /\d\d\d   (?# Looking for three digits  )
        -        (?# followed by a hash        )
        \d\d\d   (?# and abother three digits  )
       /x
p pattern1.match('578 123-678ref 567')[0]
# => "123-678"

Looking ahead
You can also look ahead at what follows, without getting the next bit including in your match. You can check that pattern is either there or is absent, as show in this example. In the first instance, pattern1 looks for three numbers follwed by "ref", but the resultant match has only the three numbers. Then pattern2 looks for three numbers not followed by a space.

pattern1 = /\d\d\d(?=ref)/
pattern2 = /\d\d\d(?! )/
pattern3 = /\d?(?! )/
p pattern1.match('578 123 678ref 567')[0]
# => "678"
p pattern2.match('578 123 678ref 567')[0]
# => "678"
p pattern3.match('578 123 678ref 567')[0]
# => "57"

And also...
One final option:

(?>)          nested anchored sub-regexp. stops backtracking.

Means nothing to me, but I mention it for completeness.

Struggling with Ruby: Contents Page

Using JavaScript with Ruby on Rails

2009-04-21T20:33:00.001+01:00

Okay, this is a blog about Ruby and Rails, however, there are occasions when you want to do some processing at the client end, and JavaScript is the usual language to do that with. It is pretty straightforward to add JavaScript to your Rails web application. The strategy I employ is to write a static web page with the script on it, and get that working, and then transfer that to the Rails view.

One imortant time to use JavaScript is for user-defined code. You can save the code to your database, for use later. But rather than invoke it in Ruby on your server (which is going to be a big security risk), use JavaScript on the client machine instead. Here are a couple of examples that I have used.

Moving the focus
This script will more the focus to the first text field or text area form element on the page (after checking that there is a form). I have this in my application-wide layout, so the focus gets set for every form in my application.

<script>
// Sets the form focus to the first element found in forms[0] that
// is a textfield or text area
function setFocus() {
// Bail if no form on page
if (document.forms[0] == null) return;

// Iterate though elements
for (var i = 0; i < document.forms[0].elements.length; i++) {
  e = document.forms[0].elements[i];
  if ((e.type == "text") || (e.type == "textarea")) {
    e.focus();
    break;
  }
}
}

</script>  

<body onload="setFocus()">

Two buttons to add default values
First some background: This was for a table of laboratory samples. Occasionally, analysis is not required, and I wanted a quick way to note that in the comments text area. This helper method adds a link; click on it and the text is added to the text area.

def not_required_button
js = "sample_comments.value += \'Not required.\'"
"<a onclick=\"#{js}\" class=\"not-button\">[n/r]"
end

The method builds a little string of JavaScript, and then uses that in some HTML. I set up the CSS class like this:

a.not-button {
color: silver;
font-size: 10px;
cursor: pointer;
}

The next example is a bit more complicated. Again this was for the table of laboratory samples, and there are several different types of samples requiring different fields. To handle that, I created an array of hashes; each hash held the information for one field (for example, how to display it). The edit and show actions iterate through the array, and display the fields based on the values in the hash. Several fields usually require the next number in a sequence, so what I wanted was a button the user could click to add that number. This helper method does just that:

def count_button field
return '' if !field[:count]
old_value = Sample.maximum field[:column_name]
js = "#{sample_#{field[:column_name]}}.value = \'#{old_value.nil? ? 1 : old_value + 1}\'"
"<input type=\"button\" onclick=\"#{js}\" value=\"\#\"}>"
end

The method accepts the hash for the field as a parameter. If the value of count is not set to true, then no button is wanted, and the method returns. Otherwise, it searches the Sample table for the highest value already there, and adds one to that (or uses one as the value if there are none there yet). Then it builds the JavaScript, in the string js. The tricky bit is working out what JavaScript will expect the element to be called; the convention is class_column, all in lowercase and underscored (you can confirm that by looking at the HTML source of your output page, of course). The JavaScript code is in turn is put into the HTML code for the button.

Struggling with Ruby: Contents Page

The Model Part 5 - Find and other ActiveRecord methods

2009-03-23T20:26:00.005Z

The find method
ActiveRecord provides a lot of functionality through the find method and its derivatives. Here are some examples:

Post.find 45
# Retrieves the post with id=45
Post.find 2, 4, 5
# Gets the posts with id equal to 2, 4 and 5 (as an array)
Post.find :first
# Retrieves the first post in the database
Post.find :last
# Retrieves the last post in the database
Post.find :all
# Retrieves all the posts (as an array)
Post.find_by_author 'F2Andy'
# Retrieves the first post in the database authored by F2Andy
Post.find_all_by_author 'F2Andy'
# Retrieves all the posts in the database authored by F2Andy
Post.find_all_by_author_and_title 'F2Andy', 'ActiveRecord find'
Post.find :all, conditions => { :title => 'ActiveRecord find',
                             :author => 'F2Andy'}
# Both these retrieves all the posts in the database with
# the given author and title

There are various options you can include in your search, as illustrated here, which gets the 21st through to 30th posts, ordered by the title:

Post.find_all_by_author 'F2Andy', :order => 'title',
                    :offset => 20, :limit => 10

You can determine whether the ordering goes up or down using ASC and DESC (defaults to ASC). The offset is ignored if limit is not present.

When you know what you are searching for, ActiveRecord has it covered. However, often we do not. Do a search of Google, and you are looking for one or more words within the text. To do that for ActiveRecord you need to delve into SQL a little.

Dipping a Toe into SQL
Rails helps you to some degree, and to see how, let us perform that last search again.

Post.find :all, :conditions => ['author = ? AND title = ?',
                     'F2Andy', 'ActiveRecord find']

Notice the :conditions key. This maps to an array. The first element is the base string, some SQL code including question marks. All the other elements are substituted for the question marks in order. The SQL command that is used will be something like:

SELECT * FROM Post WHERE author = "F2Andy" AND
                       title = "ActiveRecord find"

You can use symbols rather than question marks. It is a little more long-winded, but makes it clear what goes where, and you can go in any order, so would be preferable in all but the simplest of cases.

Post.find :all,
:conditions => ['author = :author AND title = :title?',
:author => 'F2Andy', :title => 'ActiveRecord find'}]

ActiveRecord does some kind of sanitising to protect against SQL injection attacks. While the following will work, it is a bad idea, as it will bypass that process:

Post.find :all,
 :conditions => 'author = "F2Andy" AND title = "ActiveRecord find"'
Post.find_by_sql 'SELECT * FROM Post WHERE author = "F2Andy" AND title = "ActiveRecord find"'

However, for complex searches, this might be your only option (an interesting page on that can be seen here).

Using Wildcards
So now we are ready to search for a fragment within a field. In SQL, you use the LIKE keyword, rather than the equals sign, and use % as a wildcard. Let us suppose I have a database of literature references, and I am searching for one author, Smith.

refs = Ref.find :all,
 :conditions => [ "authors LIKE ?", "%Smith%" ]

This will return any record where "Smith" appears in the authors field.

Case Insensitive
There is no standard for doing case sensitive/insensitive seaches in SQL (and no help from Rails either), nor any standard about which should be the default (indeed, that depends on how the database is set up).

On PostgreSQL, you can use ILIKE to do case insensitive searches:

refs = Ref.find :all,
 :conditions => [ "authors ILIKE ?", "%smith%" ]

On MySQL, you can change the collaton method (this seems to be the usual SQL strategy, however as each database system has its own collations, it still varies between databases; SQL Server uses SQL_Latin1_General_CP1_CI_AS I think).

refs = Ref.find :all,
 :conditions => [ "authors LIKE ? COLLATE utf8_general_ci",
                   "%smith%" ]

What this all means is that the only safe way is to convert to all lower (or upper) case. The only way I could get this to work was to change the search term before hand (possibly due to how Rails sanitises the SQL).

term = "Smith".downcase
refs = Ref.find :all,
 :conditions => [ "LOWER(authors) LIKE ?", "%#{term}%" ]

Complicated searches
So what if we want to search for muliple words in multiple fields? What you need to do is build a search string that each term with be put into, and an array of terms. Here is an addition to ActiveRecord::Base that will do just that.

class ActiveRecord::Base
# Retrieves all ActiveRecords that contain the
# user supplied keywords.
# The hash parameter should contain column name
# mappings to strings of keywords. For example:
#  refs = Ref.search :authors => 'smith jones',
#                   :body => 'ruby search'
# This will retrieve any record containing both
# "smith" and "jones" in the authors field, and
# "ruby" and "search" in the body field.
# The search is case insensitive.
# Note that simply sending the params hash from
# the controller will not work, as this includes
# values for :action and :controller.
def self.search params
 # This will becomes the base for the SQL string
 sql_fragments = []
 # This is the array of search terms. The first
 #entry is just a place holder; this will be
 # replaced by the SQL string at the end.
 search_terms = ['']
 params.each_pair do |k, v|
   v.split.each do |e|
     sql_fragments << "LOWER(#{k.to_s}) LIKE ?"
     search_terms << "%#{e.downcase}%"
   end
 end
 # Now assemble the SQL string and put it at
 # the start of the array of terms.
 search_terms[0] = sql_fragments.join(' AND ')
 find :all, :conditions => search_terms
end
end

Other methods

The delete and destroy methods
These take an id or an array of ids to delete a set of records, returning the number of records set. The destroy method actually creates a new instance, populates it with data from the table, then calls the destroy method on the object, so will be slower, but will ensure any custom code in the destroy method and any callbacks and filters is invoked.

Post.delete 19
Post.destroy [23, 67, 103]

The delete_all and destroy_all methods
These are similar to find :all, and will accept the same sort of conditions. As with delete and destroy, destroy_all is slower as the objects are instantiated first.

Post.delete_all :conditions => [ "user_name = ? AND category = ?",
    user_name, category ]

The exists? method
This method returns true if one or more records matching the condition exists. Note that it accepts either an id, or the condition itself (rather than :condition mapping to the condition)

Post.exists? 45
Post.exists? :user_name => user_name, :category => category
Post.exists? ["user_name = ? AND category = ?",
                   user_name, category]

Calculations
As well as retrieving records, you can perform calculations, using average, maximum, minimum and sum. Examples from the API:

Person.calculate(:count, :all) # The same as Person.count
Person.average(:age) # SELECT AVG(age) FROM people...
Person.minimum(:age,
 :conditions => ['last_name != ?', 'Drake'])
# Selects the minimum age for everyone with a last name other
# than 'Drake'
Person.minimum(:age, :having => 'min(age) > 17',
 :group => :last_name)
# Selects the minimum age for any family without any minors
Person.sum("2 * age")

You can also use count. Again, examples from the API:

Person.count
# returns the total count of all people
Person.count(:age)
# returns the total count of all people
# whose age is present in database
Person.count(:conditions => "age > 26")
Person.count(:conditions => "age > 26 AND job.salary > 60000",
 :include => :job)
# because of the named association, it finds the DISTINCT
# count using LEFT OUTER JOIN.
Person.count(:conditions => "age > 26 AND job.salary > 60000",
 :joins => "LEFT JOIN jobs on jobs.person_id = person.id")
# finds the number of rows matching the conditions and joins.
Person.count('id', :conditions => "age > 26")
# Performs a COUNT(id)
Person.count(:all, :conditions => "age > 26")
# Performs a COUNT(*) (:all is an alias for '*')

Ruby dates and times

2009-03-18T21:30:00.000Z

Ruby has three classes for handling time, Date, DateTime and Time.

Time is part of the core language, while Date and DateTime are part of standard Ruby; to use Date and DateTime you will need to load in date.rb. Here is some code that initialises each with the current date/time.

t = Time.now
# => Fri Feb 06 08:56:27 +0000 2009
require 'date'  # Needed for Date and DateTime
# => true
d = Date.today
# => #<Date: 4909737/2,0,2299161>
dt = DateTime.now
# => #<DateTime: 14140044704711/5760000,0,2299161>

As you can see, despite its name, the Time class holds the date as well as the time. The inspect method of Time gives a convenient output; not so Date or DateTime. However, the to_s method is a little more useful. The best option is to use the strftime method for all of them, which gives you full control over how time and dates are formated.

p t.inspect
# => "Fri Feb 06 08:56:27 +0000 2009"
p d.inspect
# => "#"
p t.to_s
# => "Fri Feb 06 08:56:27 +0000 2009"
p d.to_s
# => "2009-02-06"
p dt.to_s
# => "2009-02-06T08:56:10+00:00"
p d.strftime('%H%M on %d/%b/%y')
# => "0000 on 06/Feb/09"
p t.strftime('%H%M on %d/%b/%y')
# => "0856 on 06/Feb/09"
p dt.strftime('%H%M on %d/%b/%y')
# => "0856 on 06/Feb/09"

The full list of options (from here):

  %a - The abbreviated weekday name ("Sun")
 %A - The  full  weekday  name ("Sunday")
 %b - The abbreviated month name ("Jan")
 %B - The  full  month  name ("January")
 %c - The preferred local date and time representation
 %d - Day of the month (01..31)
 %H - Hour of the day, 24-hour clock (00..23)
 %I - Hour of the day, 12-hour clock (01..12)
 %j - Day of the year (001..366)
 %m - Month of the year (01..12)
 %M - Minute of the hour (00..59)
 %p - Meridian indicator ("AM" or "PM")
 %S - Second of the minute (00..60)
 %U - Week  number  of the current year,
         starting with the first Sunday as the first
         day of the first week (00..53)
 %W - Week  number  of the current year,
         starting with the first Monday as the first
         day of the first week (00..53)
 %w - Day of the week (Sunday is 0, 0..6)
 %x - Preferred representation for the date alone, no time
 %X - Preferred representation for the time alone, no date
 %y - Year without a century (00..99)
 %Y - Year with century
 %Z - Time zone name
 %% - Literal "%" character

You can also create Date, Time and DateTime objects using the new method. Date and DateTime default to midnight on the 1st of January 1988, while Time defaults to the current date and time. With Date and DateTime you can set specific values. The parameter list starts with the biggest units, years, and gets smaller. Successive arguments are optional.

p Date.new.strftime('%H%M on %d/%b/%y')
# => "0000 on 01/Jan/88"
p DateTime.new.strftime('%H%M on %d/%b/%y')
# => "0000 on 01/Jan/88"
p Date.new(2006).strftime('%H%M on %d/%b/%y')
# => "0000 on 01/Jan/06"
p Date.new(2006, 4).strftime('%H%M on %d/%b/%y')
# => "0000 on 01/Apr/06"
p Date.new(2006, 4, 7).strftime('%H%M on %d/%b/%y')
# => "0000 on 07/Apr/06"
p DateTime.new(2006, 4, 7).strftime('%H%M on %d/%b/%y')
# => "0000 on 07/Apr/06"
p DateTime.new(2006, 4, 7, 8).strftime('%H%M on %d/%b/%y')
# => "0800 on 07/Apr/06"
p DateTime.new(2006, 4, 7, 8, 23).strftime('%H%M on %d/%b/%y')
# => "0823 on 07/Apr/06"

Using date and time examples.

d2 = d1 >> 2  # d2 will be two months later than d1
d2 = d1 << 2  # d2 will be two months earlier than d1
d.month
dt.day
d.wday  # Day of week, Monday = 1
d.yday # Day of the year
d.zone # Time zone
d.leap?  # Leap year?
dt.hour
dt.min
dt.sec
dt.sec_fraction

You can determine the different between two dates just be taking one from the other. The complication is that the result is a Rational.

d1 = Date.new 2004
d2 = Date.new 2005
d2 - d1
# => Rational(366, 1)

A Rational object consists of two numbers. Basically it is a fraction; the first number goes on top, the second number of the bottom (in mathematics, a rational number is one that can be expressed as a faction with finite digits; as opposed to, for example, pi, which is an irrational number). The number of days between the 1st January 2004 and 2005 is 366 divided by 1. You can freely use Date and DateTime objects together; the result is always the number of days expressed as a fraction, as a Rational object. You can convert your Rational object to an array cotaining the hours, minutes, second and the second fraction with Date.day_fraction_to_time.

According to here, Time is written in C, and is therefore some 20 times faster than Date/DateTime. However, it can only handle dates from 1970 to 2039 (Unix epoch)

Humanize time/date:
http://www.i76.nl/weblog/ruby-date-time

Struggling with Ruby: Contents Page

Accessors

2009-03-15T10:42:00.002Z

In Ruby, variables are always private; they cannot be directly accessed from outside the object (constants are always public). However, it is often the case that you do need to allow some access. One way would be to define methods that set and get the values. For example:

class TestClass
def initialize id, name
  @id = id
  @name = name
end

def id
  @id
end

def name
  @name
end

def name= s
  @name = s
end
end

# Test it works properly
tc = TestClass.new 12, 'Boris'
p tc.id
p tc.name
tc.name = 'Alfie'
p tc.name

Note that the id cannot be set after the object is created; it is a read-only attribute.

Ruby offers a short cut for getters and setters. The above class can be re-written like this:

class TestClass
def initialize id, name
  @id = id
  @name = name
end

attr_reader :id
attr_accessor :name
end

The class behaves just the same, so the test code will work here as well, but all that clutter has been removed.

There is also a method for write-only attributes, and several attributes can be listed, separated with commas:

attr_reader :size, :address, :dir

What is happening is that attr_reader is a method (in the Module class), that takes the parameter :id, and dynamically defines the id method.

Having said that, here is an interesting article (written for Java, but applicable to any object-orientated language) about why getters and setters are evil (sometimes):
http://www.javaworld.com/javaworld/jw-09-2003/jw-0905-toolbox.html

Struggling with Ruby: Contents Page

Constants

2009-03-14T08:40:00.000Z

The Ruby interpreter will take anything that has a name beginning with a capital letter as being a constant.

# Variables
n = 67
s = 'my string'

#Constants
N = 89
TITLE = 'My great program'
class MyClass end

Not really constant?
Variables and constants are really pointers to objects. This has some practical consequences that may be unexpected. Let us set some up:

S = s = 'My string'
N = n = 23
X = x = 12.6

Then we can see what happens what we modify the object:

s << ' is longer'
n += 4
x += 3.5

Perhaps the odd thing here is that modifying s also modifies the constant, S. But is that so odd? Both s and S point to the same string. Modify the string, and naturally what they both point to has changed. So what is surprising is that the others have not changed (as an aside, this is also the situation in Java, but in Java, numbers are primitives, not objects; in Ruby everything is an object). Numbers have one object each to represent each value (though they will not all exist in te virtual machine t any one time of course). Change the value, and it will point to a new instance that stands for the new value.

Note that for the string, I used << rather than +=. Although they both concatenate strings, The former changes the existing string, while the latter creates a new string. If I had used += in the above, s would change to point to the new string, while S would still point to the old string.

So you can readily modify the object that a constant points to, but you cannot change what object it points to... Can you? Well, yes you can. The only issue is that the interpreter gives a warning. Here is an IRb session:

irb(main):011:0> Constant = 'My string'
=> "My string"
irb(main):012:0> Constant = 56
(irb):12: warning: already initialized constant Constant
=> 56

It turns out that constants are only really constant by convention, and there is nothing to stop you changing them and no guarantee that they will remain the same (just as setting a method as private is no guarantee that it cannot be invoked from anywhere).

Struggling with Ruby: Contents Page

Ruby blocks

2009-03-07T21:38:00.005Z

A block is a chunk of code. What is great in Ruby is the way they can be passed as an argument to a method. For example, that is what is happening here:

(0..10).each { |x|
  p x
}

The (0..10) is a Range object, with a method, each. The method is passed the block (everything between the curly braces). Blocks can be defined with do and end, rather than curly braces (but note that the precedence is different).

(0..10).each do |x|
p x
end

Implicitly passing blocks
Here is an example of passing a block to a custom method, test. Note that test does not mention the block at all, so the block is considered to have been passed implicitly. Where the block is used is with the yield statement.

def test
  p yield(5, 'house')
  p yield(100, 'mansion')
end

test { |i, s|
  puts "You are in the block #{i} #{s}"
  "Returning #{i} #{s}"
}

# Output:

# You are in the block 5 house
# "Returning 5 house"
# You are in the block 100 mansion
# "Returning 100 mansion"

So what is going on? The test method is invoked, and passed a block of code. Inside the test method, Ruby iterates though each line until it reaches a yield statement, and when it does, it runs the code block passed to the method. The yield statement is kind of like a method call, in that you can pass it arguments (and it will insist on the right number of arguments), and it can return a value too. You can think of yield as an alias for your block, so in the above example, yield is sent a number and a string, and returns a new string.

Naturally the block will be run every time Ruby encounters a yield statement, which is twice in the above example.

Iterating with blocks
Okay, now it gets a bit hairy, and web pages that actually address this become correspondingly rare...

How do you get the method that is receiving a block to iterate over an Array or Hash? In this example, a method, test, is added to the class Array, then an Array object is ceated and test is invoked.

class Array
  def test
    total = 0
    each { |x|
      p yield(5 + x)
      total += x
    }
    total
  end
end

ma = [12, 34, 8]
p ma.test { |y|
  p y
  y - 5
}

# Output:

# 17
# 12
# 39
# 34
# 13
# 8
# 54

The first point to note is the each statement and its associated block. This is what allows us to iterate over the Array (or Hash). The each statement sets up a variable, x. This will take the value of each member of the array in turn, as normal. On the next line there is the yield statement. This invokes the block that was received, sending it the current value from the array, plus five.

The block is set up to accept a single value, and to call it y, which it then prints. It then returns this value minus five.

Back with the yield statement, and the test method prints the returned value. Then it adds the current value from the array, x, to the variable total. Once the loop finishes (all the array members have been done), total is used as a return value for the test method.

Back outside the test method, the returned value is printed.

Here are more useful examples for the Array class.

class Array
  # Allows you to loop over an array, accessing
  # both the index and the value
  def each_pair
    each_index { |i| yield i, fetch(i) }
  end

  # As the each method, but skips the first element
  def each_not_first
    each_index { |i| yield fetch(i) unless i == 0 }
  end

  # Returns a total over each element in the array
  # where the value for an element is determined
  # by the given block.
  def total &prc
    val = 0
    each { |e| val += prc.call(e) }
    val
  end

  # Returns an element that best fits the criteria
  # given by the block.
  # Note that I have used yield here, it seems to work
  # better if you have more than one parameter;
  # "warning: multiple values for a block parameter..."
  def find_best &prc
    best = first
    each_not_first { |e| best = e if yield(best, e) }
    best
  end
end

# Example array
ary = [
  {:name => 'one', :value => 56},
  {:name => 'two', :value => 79},
  {:name => 'three', :value => -5},
]

# This uses each_pair to print both the index,
# and the name of the item.
ary.each_pair { |index, item| "#{index}: #{item[:name]}" }

# This example uses total to add up the
# values of each element.
p ary.total { |e| e[:value] }

# This one uses find to get the element with the
# highest value.
p ary.find { |x, y| x[:value] < y[:value] }

Explicitly passing blocks
If you want to be able handle the block other than through yield, you need to pass it explicitly. All this involves is listing it in the arguments. Note that the block must be last in the list, and has to be preceded by an ampersand (but the ampersand should not be present when used later in your code). When you do this, the block is converted to a Proc object (which I discussed here; note that you cannot pass a Proc object in lieu of a block).

def test &prc
  puts "The block is of the #{prc.class} class"
  puts prc.call('This') unless prc.nil?
end

test { |s| "#{s} does nothing" }

test

# Output:

# The block is of the Proc class
# This does nothing
# The block is of the NilClass class

Apparently, this is significantly slower than using implicit passing. The block is invoked with call; arguments to that are passed to the block.

Note that you cannot set a default value for a block in the arguments of method, however, as shown above, if no block is given the variable will be set to nil.

Many languages have a 'with' statement (Visual BASIC and Pascal). This example adds that functionality to Ruby, and also compares explicit and implicit passing:

# Define a complicated data struction
data = { :ary => %w(one two three four) }

# Define a method, 'use', for all objects
# This version uses explicit passing
class Object
  def use &prc
    prc.call self
  end
end

# This version uses implicit passing
class Object
  def use
    yield self
  end
end

# invoke 'use' on a specific member of the data structure
data[:ary][2].use do |x|
 # Do stuff with x, rather than data[:ary][2]
 p "The number is #{x}"
end

Moving to Rails 2.2.2

2009-02-20T21:23:00.008Z

Having just made the move from 2.1.2 to 2.2.2, I hought I wold share some of the issues I came across. There was a bug in 2.1.2 which meant that the image_tag method appended a dot to the end of the image filename, which has been resolved, so that is a good start.

Partials
The way you use partials has been updated in Rails 2.2. While the changes are certainly an improvement, modifying code is not fun (I had about 50 changes to make; thank goodness functional testing will catch your mistakes).

The basic change is that render_partial and render_partial_collection now accept a single hash, rather than a string indicating the file and the important variable, and can be accessed through the render method (thanks to mcclelland for pointing that out). The hash should have the file mapped to the :partial key, and any variables you want in your partial go in a hash mapped to the :locals key (so immediately we can see this is an improvement; you can pass as many of these as you want). These are accessed like local variables in your partial (but really as method calls, I assume). Class variables can be accessed in your partial just as they can in normal views.

To render a collection, just map it to :collection. You can also map any HTML code you want between the elements of your collection to the :spacer key. Rails works out that if :partial is present, it has to render a partial, and if :collection is present, it has to render that partial as a collection, so I would use render for everything (and personally, I would have removed or made private render_partial and render_partial_collection given that we all have to change our code anyway).

Let us see how it has changed. In this first example, a single variable is passed, which I have called :list (so I do not have to change the partial itself):

# Old version
<%=  render_partial 'list', @events %>

# New version
<%=  render :partial => 'list', :locals => { :list => @events } %>

Here is a table that uses two partials. The first, for the headings, requires no variables. The second is passed an array mapped to :collection:

# Old version
<table width="100%">
<%=  render_partial 'table_headings', nil %>
<%=  render_partial_collection 'table_row', @samples %>
</table>

# New version
<table width="100%">
<%=  render :partial => 'table_headings' %>
<%=  render :partial => 'table_row', :collection => @samples %>
</table>

Error pages
There are three error pages in the public directory, which Rails uses when something goes wrong in the production environment (rather than giving error details). I think these were passed through ERb previously. This is no longer the case.

Testing
When running tests, if the system encounters an error, it just gives up, instead of noting the error, and moving on to the next test. I strongly suspect this is a bug.

If a user tries to do something when logged in, but without the required role, he gets redirected to the root page. In the controller, I specify a controller and an action. Previously, I could specify that in the redirect too, but not now. It took some seaching to find that I needed this:

assert_redirected_to "http://test.host/"

Another change in that Rails now generates tests in a different form:

#Old format
def test_my_method
some_code
end

#New format
test "my method" do
some_code
end

The old format still works - no need to change all your old tests. Rather than creating a whole new set of methods, you are now invoking the test method... which then defines a new method by prepending test_ to the name, and then doing exactly the same as it did previously.

Tomcat problem
Having got everything working fine in the development environment, and all tests passing, I was confident to move to the production environmemt...

19-Feb-2009 14:40:58 org.apache.catalina.core.ApplicationContext log
SEVERE: unable to create shared application instance
org.jruby.rack.RackInitializationException: undefined method `cache_template_loading=' for ActionView::Base:Class
...
19-Feb-2009 11:23:00 org.apache.catalina.core.ApplicationContext log
SEVERE: Exception caught
java.lang.NullPointerException
at org.jruby.rack.DefaultRackDispatcher.process(DefaultRackDispatcher.java:32)
at org.jruby.rack.RackFilter.doFilter(RackFilter.java:51)

Oh dear. After much searching (and updating JRuby from 1.1.4 to 1.1.6), I found this forum thread. The solution was to remove the following line from config/environment/production.rb (may also be in config/environment.rb):

config.action_view.cache_template_loading = true

A has_one problem
An obscure bug I came across for the has_one/belongs_to relationship. When I attempted to access one model from the other, I got a NoMethodError exception, and a complaint that I was tryong to do nil.include?. My has_many/belongs_to relationships worked fine. The problem was related to setting the time zone. I have no idea how that can be, but I was not the only one:
http://www.nabble.com/Strange-error...-td21313953.html
http://www.railsformers.com/article/activerecord-timezone-settings-bug

Anyway, the solution is to delete or comment out the old time zone configuration in config/environment.rb, and put in a new one.

  #config.time_zone = 'UTC'
config.active_record.default_timezone = :utc

Additional: Rails 2.3.2 has been out for a while, and I have tried using that. The only noticeable difference was application.rb was renamed to application_controller.rb. Right up until I tried to deploy on Tomcat and it all stopped working. There is a word around here, but I have a suspicion this assumes you have created your project with a more recent version of Rails than I did. Anyway, it did not work for me, so I am back on 2.2.2.

Further addition: Going back to 2.2.2 caused my unit tests to fail mysteriously, with rake just giving up (though functionals and integration tests were fine, and each unit test on its own was fine). It turned out that new models I had added with 2.3.2 had an additional test in test/units/helpers, and this was upsetting the rake task (possibly because I had deleted the associated helper files).

Struggling with Ruby: Contents Page

The Ruby Proc

2009-02-13T00:01:00.005Z

In Ruby a Proc (short for procedure) is a block of code, bound to a variable (closely related to a block, discussed here). As is always the way in Ruby, a Proc is an object, and so can be created with the new method, though, as discussed later, it is generally preferable to use the lambda method. Here are some examples (expanding on those in the Ruby documention):

# A Proc can have one, none or many arguments
times7 = Proc.new {|n| n * 7 }
statement = Proc.new { 'from statement' }
multiply3 = Proc.new {|x, y| x * y }

The code in the Proc object can be invoked by using the call method.

p times3.call(12)               #=> 36
p times5.call(5)                #=> 25
p times7.call(8)                #=> 56
p times3.call(times5.call(4))   #=> 60

p statement.call                #=> "from statement"
p multiply.call(4, 3)           #=> 12

You can pass around Proc objects like any other object:

def gen_times(factor)
 return Proc.new {|n| n*factor }
end

class ProcTest
 # Class variable is a Proc
 @@times13 = Proc.new {|n| n * 13 }

 # Method uses various Proc objects
 def test
   times11 = Proc.new {|n| n * 11 }
   p times11.call(3)
   p @@times13.call(7)
   times2 = gen_times(2)
   p times2.call(19)
 end

 # Method uses a Proc passed as an argument
 def test_argument prc
   p prc.call(4)
 end
end

# ProcTest object instantiated, and methods called
pt = ProcTest.new
pt.test
pt.test_argument Proc.new {|x| x + 5}

Instead of using call, you can invoke the code using square brackets notation. The following are equivalent:

multiply.call(4, 3)
multiply[4, 3]

Proc.new vs lambda
If you call a Proc with too few arguments, Ruby will pad them out with the nil object, so multiply.call(14) above would invoke the Proc code with 14 and nil (which would generate an error in this case). Any extra arguments are simply discarded.

The Kernal has a method lambda (there is also a method proc, which reportedly does the same as Proc.new, but I found it identical to lambda) which will also give a Proc object, but in this case the Proc will raise an ArgumentError is the argument count is wrong.

count_nils_new = Proc.new {|x, y, z|
"#{x.nil?} #{y.nil?} #{z.nil?}"
}

count_nils_lambda = lambda {|x, y, z|
"#{x.nil?} #{y.nil?} #{z.nil?}"
}

# The 4 is quietly discarded
p count_nils_new.call(1, 2, 3, 4)

# The method is sent 1, 2, nil
p count_nils_new.call(1, 2)

# The method is sent nil, nil, nil
p count_nils_new.call

# This is fine
p count_nils_lambda.call(1, 2, 3)

# These will all generate an ArgumentError
p count_nils_lambda.call(1, 2, 3, 4)
p count_nils_lambda.call(1, 2)
p count_nils_lambda.call

Proc objects have an arity method that can be used to determine how many arguments the Proc is expecting.

Using return in a Proc
Using an explicit return in a Proc object created with Proc.new (but not lambda) will cause the calling method to return that value.

def with_return_and_new
prc = Proc.new { return 'This is printed' }
prc.call
'Never seen'
end

def no_return_with_new
prc = Proc.new { 'no_return_with_new' }
prc.call
'This is printed'
end

def with_return_and_lambda
prc = lambda { return 'with_return_and_lambda' }
prc.call
'This is printed'
end

p with_return_and_new
p no_return_with_new
p with_return_and_lambda

It seems that the Proc object is returning not just the value, but the return command too. In general, therefore, it is a bad idea to use an explicit return inside a Proc object defined with Proc.new (if only because the effect will be confusing to anyone with out a good understanding of Ruby peculiarities). This is discussed more here:
http://innig.net/software/ruby/closures-in-ruby.rb

API for the Proc object:
http://www.ruby-doc.org/core/classes/Proc.html

See also:
http://eli.thegreenplace.net/2006/04/18/understanding-ruby-blocks-procs-and-methods/
http://blog.sidu.in/2007/11/ruby-blocks-gotchas.html

Struggling with Ruby: Contents Page

The Singleton in Ruby

2009-02-08T12:46:00.004Z

When I first read about singletons in Ruby, I assumed this was a reference to the singleton pattern; perhaps the classic example of a pattern, and in my opinion not much use (actually Ruby has a Singleton module for doing just this). However, in Ruby the singleton is something else entirely.

The singleton is a method that is attached to a single instance of a class. Here is a simple example:

s1 = 'what'
s2 = 'where'
s3 = 'when'

def s1.hello
 p "Hello world"
end

class << s2
  def hello
    p "Hello world"
  end
end


s1.hello
s2.hello
begin
  s3.hello
rescue NoMethodError
  p $!
end

p s1.singleton_methods
    # => ["hello"]
p s2.singleton_methods
   # => ["hello"]
p s3.singleton_methods
   # => []

Three strings are created. The first two have singleton methods added to them in slightly different ways. The singleton methods can be invoked on that specific instance, but not on any other object of that class. Finally, the singleton_methods method is invoked to show how these methods can be listed.

Technically, the object itself does not get a new method. Objects can only hold variables, not methods. Rather, the object has a metaclass, or virtual class, and this metaclass is where the new method is. This is what class << s2 is accessing.

Class methods
You can also add singleton methods to the class, where they become class methods. The logic here is that the class is itself an object, and these methods are being added to a single instance of the Class class. This code illustrates three ways to add a singleton to a class.

def String.goodbye1
 p "Goodbye world (1)"
end

class String
 def self.goodbye2
   p "Goodbye world (2)"
 end
end

class String
 class << self
  def goodbye3
   p "Goodbye world (3)"
  end
 end
end

p String.singleton_methods
# => ["goodbye3", "goodbye2", "goodbye1"]

It is interesting to note that "String" is actually a constant that holds a Class object, and this is why it is capitalised.

Note: Some believe that class << self is bad; this suggests there may be more going on here.

The singleton_methods method returns all methods for the class that are not inherited from a superclass. Use singleton_methods false to exclude methods from modules.

See also:
http://ola-bini.blogspot.com/2006/09/ruby-singleton-class.html

http://whytheluckystiff.net/articles/seeingMetaclassesClearly.html

Struggling with Ruby: Contents Page

Modules

2009-02-03T21:15:00.003Z

A module is a collection of methods and constants, much like a method. However, a module cannot be instantiated. Instead, a module is added to an existing class or object to create a "mixin". Here is an example of a module, with both a method and a constant defined:

module TestModule
TEST_CONST = 1000

def hello
  p "Hello"
end
end

The are two ways to add a module to your class, using the keywords include or extend:

class TestClass1
include TestModule
end

class TestClass2
extend TestModule
end

The include statement causes all the methods in the module to be added as instance methods, and also allows the constants to be accessed through the method. In contrast, the extend statement adds all the methods as class methods, and does nothing with the constants. Let us look at the constants first:

p TestModule::TEST_CONST
p TestClass1::TEST_CONST
begin
p TestClass2::TEST_CONST
rescue NameError
p $!
end

The class methods. TestClass2 had the module added using extend, so the method in the module is a class method:

begin
TestClass1.hello
rescue NoMethodError
p $!
end
TestClass2.hello

Finally the instance methods. TestClass1 had the module added using include, so the method in the module is an instance method. Note that you can add a module to an object at run time, but in that case the extend keyword is used:

# Create some instances
tc1 = TestClass1.new
tc2 = TestClass2.new
tc2too = TestClass2.new

# Methods accessible at the instance level
tc1.hello
begin
tc2.hello
rescue NoMethodError
p $!
end

# Module added at runtime
tc2.extend TestModule
tc2.hello
begin
tc2too.hello
rescue NoMethodError
p $!
end

I think the logic here is that extend is used for singletons; a single class or a single instance of the class.

Instantiation
Ruby will invoke the included or extended methods in your module, if they exist, when the module is included or extended respectively. These have to be defined as class methods - even though this is not a class. As far as I know, this is the only time you do tat for a module. Both methods should take a single parameter; the object or class to which the module is being added. An example:

module TestModule
def self.included base
  p "I am being included by #{base}"
end

def self.extended base
  p "I am being extended by #{base}"
end
end

class TestClass1
include TestModule
end

class TestClass2
extend TestModule
end

p 'Classes now defined'

tc2 = TestClass2.new
tc2.extend TestModule

# Output
#
# => "I am being included by TestClass1"
# => "I am being extended by TestClass2"
# => "Classes now defined"
# => "I am being extended by #<TestClass2:0x987a33>"

See also:
http://www.juixe.com/techknow/index.php/2006/06/15/mixins-in-ruby/

Struggling with Ruby: Contents Page

The View Part 4 - Using Select in Forms

2009-01-24T19:36:00.005Z

Last time around, I discussed forms, I am now going to focus on the select widget, as I found this particular mysterious at first. I am going to assume you have already read the page on forms.

Using f.select
The easiest way to use select is inside a FormBuilder block. While most FormBuilder code is in form_helper.rb, the select is in form_options_helper.

Suppose you have a column for integers in your database table (let us say "status", for example, in a table called "posts"). You want the user to be able to select an option from a drop-down list to set the value of the column. First, you need a set of options, and this is best defined in your model. This could be an array or a hash. If you use a hash, you can assign values to options yourself, but generally an array will be sufficient. I am going to use a hash, so in posts.rb, there will be this constant defined:

STATUS_OPTIONS = {'Read' => 1, 'Unread' => 2, 'Deleted' => 12}

Then, in the view, you just need a f.select. It might look something like this (with other fields removed for clarity):

<% form_for(@post) do |f| %>
<p>
Please select:
<%= f.select(:status, Post::STATUS_OPTIONS) %>
</p>
<p>
<%= f.submit "Update" %>
</p>
<% end %>

The f.select takes two parameters, the first being the name of the column (or any method as a symbol), the second is the array or hash. That is all you need to do. Rails will handle the saving and setting of the options for you.

Be aware that if you use an array, Rails will ignore the index. The value returned from the column method must be a value in the array, rather than a number for the index, and similarly what is set will be value, not the index. Personally, I found that annoying, so created a new method that would accept an array, and build a select element using the indices with the values.

# See actionpack/lib/action_view/helpers/form_options_helper.rb
module ActionView
 module Helpers
   class FormBuilder
     def array_select(method, choices, options = {}, html_options = {})
       h = {}
       choices.each_index { |i| h.store(choices[i], i)}
       @template.select(@object_name, method, h, objectify_options(options), @default_options.merge(html_options))
     end
   end
 end
end

Using select_tag
The select_tag method is a bit poor, as it does not accept an array or hash, demanding instead a string with each entry surrounded by "<option>" and "</option>". Why it was not designed to accept an array and a value I cannot imagine. Instead, you have to use the options_for_select helper method, like this:

<%= select_tag("post[status]",
options_for_select(Post::STATUS_OPTIONS,
                  @post.status))
%>

However, there is also a select method that does the job.

<%= select(:post, :status, Post::STATUS_OPTIONS) %>

I imagine this was a later addition to Rails.

NOTE: I have read that select_tag should be used for GET commands, and select for POST (see here).

Submit on change to a select
Sometimes, you want the user to be able to select from a list, and to be taken straight to a new web page, without having to click on a button. This is pretty easy, with a bit of JavaScript. I set up a helper method to do that:

def submit_on_change
{:onchange => 'submit()'}
end

You can then add that method to your select or select_tag. Note that select takes two optional hashes, and you want to use the second, so I have put in an empty hash in that case.

<%= f.select :status, Post::STATUS_OPTIONS, {}, submit_on_change %>

<%= select_tag "post[status]",
 options_for_select(Post::STATUS_OPTIONS,
        @post.status),
 submit_on_change %>

Another select example
Here is an example of using a select box to choose a web page. The web pages are set up in the model:

HELP_PAGES = {'Main' => 'index', 'Ruby Basics' => 'ruby', 'Ruby Classes' => 'classes'}

In the view, this code will set up the select (note that there is no submit button; be aware that any user with JavaScript disabled will not be able to navigate using this):

<% form_tag( {:action => :help, }, :method => :get) do %>
<%= select_tag "page", options_for_select(Post::HELP_PAGES),
             submit_on_change %>
<% end %>

In the controller, the chosen page is handled:

def help
@page = params[:page]
# etc...
end

The collection_select method
Let us suppose you have one table associated with another, and want to be able to have the user select a record from one table for a record in the other. Let us go back to the archetypal blog application: Posts can be associated with a category (so a post belongs_to a category; a category has_many posts and the post table has a column called "category_id"). The user clicks on new post, writes his throughts, then can select from a list of categories from a drop-down list. How do we create such a thing?

This is what the collection_select method is for. As with select, there are two forms, one associated with a FormBuilder object, the other not.

<%= f.collection_select(:category_id,
     Category.find(:all), :id, :name) %>
<%= collection_select(:post, :category_id,
 Category.find(:all), :id, :name) %>

Note that the second form requires an extra parameter specifying the table we are modifying. The next parameter, :category_id in the example, is a method that is called to set the value; generally that will be the name of the column in the table you are modifying.

The next parameter is an array (kind of) of ActiveRecords; this is the list of options that will be available to the user. The next parameter, :id, is the method used by Rails to get values for each option of the select, while the next parameter determines the display name for the options. In effect, these two are the column names in the other table. To generate the list of options in the example, Rails iterates through the array of categories, and for each member it calls the "id" method to set the value, and the "name" method to set the text that is displayed.

As with select, there are two optional parameters for hashes of options.

As it turns out, you are not restricted to ActiveRecords. I tried it with this TestClass:

class TestClass
def initialize id, name
@id = id
@name = name
end
attr_reader :id, :name
end

Setting up an array:

  TEST_ARRAY = [
TestClass.new(12, 'First of all'),
TestClass.new(54, 'Middle'),
TestClass.new(32, 'Last and finally'),
]

And then using the collection_select like this:

<%= collection_select(:comment, :post_id,
      Comment::TEST_ARRAY, :id, :name) %>

However, I have no idea why you would want to do that, rather than using a hash with select.

Selecting Dates
There are are set of methods to help you handle dates. If you are inside a FormBuilder block, just use date_select like this (Rails will even do this for you when you generate views):
<%= f.date_select :birthday %>
ActiveRecord will handle the rest. Outside FormBuilder you can use date_select or select_date (why not date_select_tag, which would be more consistent?). I found date_select easier to set up, but the values in the hash are not trivial to handle. I found some useful code here:

# Reconstruct a date object from date_select helper form params
def build_date_from_params(field_name, params)
Date.new(params["#{field_name.to_s}(1i)"].to_i,
     params["#{field_name.to_s}(2i)"].to_i,
     params["#{field_name.to_s}(3i)"].to_i)
end

date = build_date_from_params(:published_at, params[:article])

The API:
http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html
http://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html
http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html

See also:
http://shiningthrough.co.uk/Select+helper+methods+in+Ruby+on+Rails

Struggling with Ruby: Contents Page

The View Part 3 - Using Forms

2009-01-23T22:12:00.003Z

The basic component of a form for a view on Rails is the form_for method in ActionView::Helpers::FormHelper. This takes an object as an argument, and applies that object to the form components in a block. The variabe f is a FormBuilder object.

form_for(@post) do |f|
f.label :name
f.text_field :name
f.label :body
f.text_area :body
f.submit "Update"
end

Actually, it is not quite as simple as that, as you need to mix in the HTML, so in your view, the above becomes:

<% form_for(@post) do |f| %>
<p>
  <%= f.label :name %>

  <%= f.text_field :name %>
</p>
<p>
  <%= f.label :body %>

  <%= f.text_area :body %>
</p>
<p>
  <%= f.submit "Update" %>
</p>
<% end %>

It is a good idea to put in <%= f.error_messages %> as the second line in your form (and indeed Rails will do this for you), as this will display error messages for you (for example, if the user's input fails validation).

There are a number of methods available for the FormHelper object that will place widgets on the web page. These ones are listed in the API:

check_box
file_field
hidden_field
label
password_field
radio_button
text_area
text_field

The check_box method should be associated with a Boolean field. The hidden_field is useful for data you do not want the user to have access to, but which has to saved with the rest of the fields (but if a field is missing from the form, the record will retain the previous value).

Using radio_button
Suppose you have a column for integers in your database table (let us say "status", for example, in a table called "posts"). You want the user to be able to select an option.

First, you need a set of options, and this is best defined in your model. I am going to use a hash, so in posts.rb, there will be this constant defined:

STATUS_OPTIONS = {'Read' => 1, 'Unread' => 2, 'Deleted' => 12}

Then, in the view, you just need something like this:

<% Post::STATUS_OPTIONS.each_pair do |k, v| %>
<%= k + f.radio_button("status", v) %>
<% end %>

Ruby will iterate through the hash, Post::STATUS_OPTIONS. For each element, it will create a radio button.

Buttons that do not submit
Sometimes you want a button that does not submit the form. You can still use the submit method, just set the :type to map to "button. Here is an example of how to create a button that will invoke a JavaScript function called calc.

<%= f.submit 'Calc', { :onclick => 'calc()', :type => "button", } %>

Other Forms
Sometimes you want to create a form that is not associated with a particular record, such as a search form. For this you use methods from the ActionView::Helpers::FormTagHelper module. The same sort of methods are available, but with _tag as a suffix.

Use form_tag to create the basic form. You can give it a URL segment, or the usual URL parameters. The form_tag method seems to default to POST, so for this show example, I had to specify the method as GET.

<% form_tag({:action => :show, :id => 1}, :method => :get) do %>
<%= submit_tag 'Show 1' %>
<% end %>

Or using the URL:

<% form_tag '/posts/update/1' do %>
<%= submit_tag 'Update 1' %>
<% end %>

Here is a more interesting example, doing the same as the first example (just for illustration - there is no good reason to not do it the other way), with radio buttons. Note that the method is now PUT for update. Also, the tag name is of the form post[status] (for the model called "post", and the field called "status"). When Rails receives the request, the value of status will be put in a hash called post, which will go inside the params hash. This is the standard Rails technique, and is what happens in the earlier example, behind the scenes. This means the controller does not need changing.

<% form_tag({:action => :update, :id => @post.id},
           :method => :put) do %>
<p>
  <%= label_tag 'Name' %>

  <%= text_field_tag 'post[name]', @post.name %>
</p>
<p>
  <%= label_tag 'Body' %>

  <%= text_area_tag 'post[body]', @post.body %>
</p>
<% i = 0
  Post::STATUS_OPTIONS.each_pair do |k, v| %>
  <%= k + radio_button_tag('post[status]', v,
            @post.status == v) %>
<% end %>
<%= submit_tag "Update" %>
<% end %>

Hopefully tomorrow I will post about select.

The API:
http://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html
http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html

Struggling with Ruby: Contents Page

Ruby Methods Part 4 - Calling Methods

2009-01-21T21:11:00.004Z

Ruby has three (at least) ways to call a method on an object. This code illustrates their use. First, a class is defined with four methods, one of which is private, one is a class method and another takes a parameter. The class is instantiated, and then the methods accessed using the various techniques.

# Define a class with three methods
class MethodTest
def public_method
 p 'In public_method'
end

def method_with_argument x
 p "In public2_method - #{x}"
end

def self.class_method
 p 'In class_method'
end

private
def private_method
 p 'In private_method'
end
end

# Create instance of class
mt = MethodTest.new

# Invoke methods with the dot operator
mt.public_method
mt.method_with_argument('hello')
MethodTest.class_method
begin
mt.private_method
rescue NoMethodError
p $!
end

# Invoke methods with send
mt.send :public_method
mt.send :method_with_argument, 'Hello'
MethodTest.send :class_method
mt.send :private_method

# Invoke methods as objects
mt.method(:public_method).call
mt.method(:method_with_argument).call 'Hello'
MethodTest.method(:class_method).call
mt.method(:private_method).call

The dot operator
I guess this is the most familiar technique, and is common to other languages, like Java and C++. Private methods are not accessible, and instead a NoMethodError is raised (and a message is produced informing you that the method is private).

The send method
The send method is a part of the Object class and so is available to all objects. It invokes the named method (must be a symbol). As the named method is now being invoked from within the object, this means that all the methods are available, including private and protected methods.

Note that you can also use __send__, in case you have overwritten the send method. Overwriting __send__ will generate a warning that it is a bad idea; Rails uses __send__ a lot, for example, on the assumption that no one would be stupid enough to over-write it.

A good example of using the send method is where you want to access database columns in a large table, where the columns are numbered sequentially, say column0, column1, column2, etc. Rails will handle the generation of methods that will allow @mytable.column1 = 5 and x = @mytable.column1, but how do you get the total of the columns? Let us suppose ten such columns.

total = 0
10.times {|i|
total += send("column" + i.to_s)
}

Strangely, Ruby is quite a stickler for types. In Java or C# you could write "column" + i, but Ruby requires the to_s method to explicitly convert to a string. The send method sends a message (in OO talk) to the named method, column0, column1, etc. To assign a value, you need to append an equals sign to the method name. This loop assigns zero to each column:

10.times {i
send("column" + i.to_s + "=", 0)
}

The send method is a variable length method; just send it the right number of parameters for the method you are invoking.

The method object
Everything in Ruby is an object, including methods. You can access the method object with my_object.method(:my_method). Here is an example of using the method object for the length method of string

s = "string"
puts s.method(:length).class   # => Method
puts s.method(:length).call  # => 6
puts s.method(:length).methods.sort

# => ["==", "===", "=~", "[]", "__id__", "__send__", ...

As seen earlier, the method that the object represents can be invoked using the call method. As with send, this allows you to access private and protected methods. By the way, you can convert a method to a Proc using the to_proc method.

One important practical difference between using send and using the Method object is that the latter will only work on methods that are actually defined. It will not work for method calls that go though method_missing, including calls to column names for ActiveRecord or calls to the various find methods in Rails. This is because the method has to be defined to become an object.

API for the Method object:
http://www.ruby-doc.org/core/classes/Method.html

Struggling with Ruby: Contents Page

Rails Mailer

2009-01-09T22:58:00.003Z

Rails includes a mailer facility. To use it, you need a model - a class that inherits from ActionMailer::Base - and the best way to do that is use Rails to generate it:

ruby script/generate mailer MyMailer send_book

This also creates some default views (in this case just one, send_book) and tests, but we will discuss that later. Let us suppose we want to send an e-mail with a record from a table called books. In a moment, we will set up a method called send_book in MyMailer, but first, let us look at how we will invoke the mailer. In books_controller, to send the mail, you need to invoke a class method that starts deliver_.

MyMailer.deliver_send_book(:user => current_user, :data => find_book)

Somewhere in ActionMailer::Base, there is a method_missing method that handles your request. It creates an instance of MyMailer, does some setting up that we do not have to worry about, then invokes the method send_book. This is where we assign values specific to this e-mail. It might look like this:

def send_book(options)
@recipients  = "#{options[:user].email}"
@from        = "book-database@mydomain.com"
@subject     = "Record from book database"
@sent_on     = Time.now
@content_type = 'text/html'
@body[:user] = options[:user]
@body[:book]  = options[:data]
end

Note that this will send the message in HTML format; it will default to plain text if there is no @content_type.

Next the method_missing method creates the text of the e-mail. It does this in the normal Rails manner, i.e., from a file in the views folder. In this case it will use views/my_mail/send_book.html.erb. When you create views/my_mail/send_book.erb, you have access to any variable you assign to the @body hash, so in the example above, I could use @user and @book, just as in a normal view. Similarly, you can use partials from other models/controllers in the normal way.

Finally ActionMailer sends the e-mail. It needs to know your your mail settings, which it will collect from a file mail.rb in config/initializers. This might look something like this:

# Email settings
ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
  :address => "smtp.mydomain.com",
  :port => 25,
  :domain => "mydomain.com",
  :authentication => :login,
  :user_name => "rails",
  :password => "secret"
}

You can use your helper files in your mail views just like your normal views, just remember to declare them at the top of MyMailer:

helper :application

The one slight difference is that you cannot do helper :all. I imagine an oversight in Rails.

Attachments can be added easily:

  attachment "application/rtf" do |a|
  a.body = File.read 'some_file.rtf'
  a.filename = 'samples.rtf'
end

Testing
You can test your mailer. Rails will have generated a default unit test (no functional testing as there is no controller for a mailer).

require 'test_helper'

class MyMailerTest < ActionMailer::TestCase
tests MyMailer
def test_send_book
  @expected.subject = 'MyMailer#send_book'
  @expected.body    = read_fixture('send_book')
  @expected.date    = Time.now

  assert_equal @expected.encoded,
    MyMailer.create_send_book(@expected.date).encoded
end

end

NB: The generated unit test includes a statement tests MyMailer. This seems to just invoke write_inheritable_attribute, which appears to make a copy of the class variables in te superclass in the subclass.

Struggling with Ruby: Contents Page

Exception Handling

2009-01-04T20:46:00.011Z

You can define your own exceptions in Ruby very easily, just extend a suitable class (that is, StandardError or any of its sub-classes):

class MyError < StandardError

end

To see how exceptions are handled, let us look at this example:

try_counter = 0
begin
 try_counter += 1
 puts 'Here 1'
 raise MyError.new "Text" unless try_counter > 5
 puts 'Here 2'
rescue MyError
 puts 'Here 3 - MyError encountered'
 retry
rescue StandardError
 puts "Here 4 - Other error encountered (#{$!.inspect})" + caller.inspect
 raise
else
 puts 'Here 5 - No errors'
ensure
 puts 'Here 6 - Always done'
end

Exceptions are handled by blocks. The risky code goes into the first chunk of the block. If an exception is encountered, the program will jump to the end of that chunk and look for an appropriate action. In the above example, it will first look at rescue MyError. If the exception is of the MyError class - or a sub-class - then the program will not run the code folling the rescue. Note that you can list multiple exception classes, separated by commas.

Otherwise, it will look further. The next rescue is for StandardError, so this will catch all errors of the StandardError type or its sub-classes - except for MyClass, as that would have been caught earlier. All rescuable exceptions must inherit from StandardError (but see later), so this is set up to catch all exceptions, but that need not be the case; uncaught exceptions will be passed on up the stack to whatever else might handle them.

The else chunk will get performed after the initial chunk has completed successfully (i.e., without raising an exception). Finally, the ensure chunk gets performed whatever the outcome.

An exception is raised using the raise keyword. Exceptions are just objects, so are instantiated just like any other object. They typically take a string parameter, which you can use to give a descriptive message. Alternatively, you use this form:

raise MyError.new "Test"
raise MyError, "Text", caller
raise MyError, "Text"
raise "Text"     # For the default RuntimeError

You can put a retry in a rescue chunk, as in the example above. The program will jump back to the start of the block, and start again. In the second rescue chunk, there is a raise on its own. This will pass the exception ouside of the block, to be handled by some higher up error handling system.

Also in that chunk, note that the $! code is the exception. If you prefer, you can set your own name for this.

rescue StandardError => err
 puts "Here 4 - Other error encountered (#{err.inspect})" + caller.inspect
raise

Here is the output from the first example:

Here 1
Here 3 - MyError encountered
Here 1
Here 3 - MyError encountered
Here 1
Here 3 - MyError encountered
Here 1
Here 3 - MyError encountered
Here 1
Here 3 - MyError encountered
Here 1
Here 2
Here 5 - No errors
Here 6 - Always done

Stack Trace
To see the stack trace, use the backtrace method. This returns an array of strings. To just see the top dozen entries, you could use this:

$!.backtrace[0..12] * "\n"

Exceptions that do not inherit from StandardError
The superclass for all exceptions is Exception. The theory is that all exceptions that a program should be expected to recover from are either StandardError or a subclass of it, which is why I described them as "rescuable exceptions " earlier. If no exception is specified, rescue will default to StandardError.

However, there may be times you want to recover from other exceptions. A particular example I came across is a SyntaxError thrown by ERB. The offending syntax was in a data file, not my application; my application should have caught the error, and reported it back to the user. This is entirely different to a syntax error in my code, and in my opinion ERB should throw its own exceptions that inherit from StandardError. Time-out errors are another example, as discussed here.

To catch all exceptions use:

rescue Exception

The rescue statement modifier
Rescue can be used in a way analogous to if and unless. For example:

test rescue do_stuff

This statement will run the method test, and if it encounters an error (specifically StandardError or subclasses) it will invoke do_stuff. You can use this to assign a default value if a method fails, like this:

s = test rescue "Default value"

The rescue stament returns the value "Default Value". You could write it with brackets, which might help make sense of it:

s = (test rescue "Default value")

You can concatenate statement with semi-colons, but cannot use blocks.

s = test rescue do_stuff; "Default value"

See also:
http://whynotwiki.com/Ruby_/_Exception_handling

Catch and Throw
The catch and throw facility in Ruby is not really exception handling at all, though it does have similarities. As it shares keywords with Java exception handling, it seems to get lumped into any discussion on exceptions. This page is no different.

Calling a throw will interrupt the program flow, causing it to jump to the named catch. Use this format to set up a catch block. Any time throw :my_label is called within the block (including within methods called from the block).

catch :my_label do
 do_stuff
throw :my_label
 do_not_do this_stuff
end

You can use the throw to return a value to catch (which will be nil otherwise).

value = catch :my_label do
 do_stuff
throw :my_label, "My result"
 do_not_do this_stuff
end

Struggling with Ruby: Contents Page

Integration testing

2008-12-12T21:44:00.006Z

I found this to be quite frustrating. Integration testing appears to be a relatively recent addition to Rails (since 1.1 I think), and pehaps for that reason there is not much on the web that explains the basics of how to do it. Coupled to that, my application is using an authentication system that I copied from a web site, and so I was just not that familiar with what is supposed to happen (at least, when I started; I know it a lot better after going through this). Also, the authentication system has some odd quirks, like defining session (rather than sessions) as a route, for a controller called sessions_controller.

Integration testing can be thought of functional testing for multiple controllers. This allows you to set up involved "stories" in which the user does a sequence of actions. Rails automatically generates unit and functional tests for you when you create a scaffold, but not an integration test (as it is not specific to one model/controller). However, there is a script to do the job for you.

ruby script/generate integration_test GeneralStories

Here is a test for the user authentication mentioned before:

  def test_authentication
   user_bob = {:login => 'bob', :username => 'Robert',
       :email => 'test@here.com', :password => '12345678',
       :password_confirmation => '12345678', }
   new_password = 'new_secret'
 
   goes_to_home_page
   goes_to_login
   fails_to_log_in_with user_bob
   goes_to_signup
   signs_up_with user_bob
   goes_to_login
   logs_in_with user_bob
   goes_to_change_password
   changes_password user_bob, new_password
   logs_out
   goes_to_login
   logs_in_with user_bob
   goes_to_home_page
 end

The code here is easy enough. A test method has to start test_ so Rails knows it is a test. First a hash is set up with details for a user, as well as a new password. Thereafter, it runs through a sequence of methods, each one corresponding to a single page download to the user (purely because that seems a convenient way to break it up). Reading down the sequence, we can read the story. The user goes to the home page, attempts to log in, but fails, then signs up, successfully logs in, changes his password, logs off, and logs on again, ending up back at the home page.

All the tricky stuff is, of course, hidden away in those methods. I am just going to look at the two involved in changing the password to illustrate the methodology.

def goes_to_change_password
 get "/change_password"
 assert_equal 200, status
 assert_equal "/change_password", path
end

This corresponds to the user clicking on the "Change Password" link. The get command is equivalent to an HTTP GET. You then check the HTTP result is 200, and the returned page is correct. The next method is rather more complicated.

def changes_password(user_options, new_password)
 post "/accounts/update",
      :old_password => user_options[:password],
      :password => new_password,
      :password_confirmation => new_password
 follow_redirect!
 assert_equal 'Password successfully updated.', flash[:notice]
 assert_equal "/", path
 assert_equal 200, status
 user_options[:password] = new_password
 user_options[:password_confirmation] = new_password
end

Now the post command is invoked, for HTTP POST. The values on the form are sent in the form of a hash. Rails usually expects a hash of a hash here, which would look like this (and in the controller would be accessed with params[:user]):

  post "/accounts/update",
    user => {:old_password => user_options[:password],
             :password => new_password,
             :password_confirmation => new_password}

I am not sure why my authentication system was set up differently; perhaps for older versions of Rails. If the action is successful, the user is redirected, and we want to see where that goes, so the next statement, follow_redirect!, does just that. Then we check everything: the flash notice should confirm the change, the path should be at the root and the HTTP status should be 200. Finally, a little bit of house-keeping; the user hash is updated with the new password ready to test logging on in a later step.

Multiple Sessions
In the background, Rails has a session object on the go, and this allows your test to proceed. If you want to you can invoke the session explicitly. One reason to do that would be to test what happens if multiple users are logged in at the same time (though I am suspicious that people use this when it is not necessary). It goes something like this (based in part on code here):

def test_signup_new_person
 user_bob = {:login => 'bob', :username => 'Robert',
    :email => 'test1@here.com', :password => '12345678',
    :password_confirmation => '12345678'}
 user_mary = {:login => 'mary', :username => 'Mary',
    :email => 'test2@here.com', :password => '12345678',
    :password_confirmation => '12345678'}
 new_password = 'new_secret'

 open_session do bob
   open_session do mary
     bob.extend(MyTestingDSL)
     mary.extend(MyTestingDSL)

     bob.goes_home
     bob.goes_to_login
     bob.fails_to_log_in_with user_bob
     bob.goes_to_signup
     bob.signs_up_with user_bob
     mary.goes_to_signup
     bob.goes_to_login
     bob.logs_in_with user_bob
     mary.signs_up_with user_mary
     bob.goes_to_change_password
     bob.changes_password user_bob, new_password
     mary.goes_to_login
     mary.logs_in_with user_mary
     bob.logs_out
     bob.goes_to_login
     bob.logs_in_with user_bob
     bob.goes_home
   end
 end
end

The test itself is more or less the same, except that the sequence is wrapped up in a block for open_session, and the session is addressed directly. This allows two sessions to be set up, bob and mary. The methods are set up the same, but again are wrapped up, this time in a module called MyTestingDSL. The module is mixed in to the session before the methods are invoked.

Finally...
I found it helpful to end my assertion with a call to this method:

def flash_me
 "Error encountered. Flash[:error]=#{flash[:error]} Flash[:notice]=#{flash[:notice]}"
end

For example:

assert_equal 200, status, flash_me

If the assertion fails, you will get told the contents of flash. The method definition needs to be inside the module, if you are using sessions explicitly.

I found trouble-shooting a test failure to be something of a nightmare. The test informs you at which line in the test line it failed, but that gives you no clue about when in your actual code the problem is. It will report the same error (<200> expected but was <500>) for anything from an action that is not recognised, to an exception thrown in your model or a misnamed column. The best solution I found was to pepper the code with statements assigning values to the flash, which would then show up using the flash_me method above. Here is an example (with additional lines in red):

def qualify
  flash[:notice] = 'here'
  begin
  @worksheet_meta_data = WorksheetMetaData.find(params[:id])
  flash[:error] = '@worksheet_meta_data = nil' if @worksheet_meta_data.nil?
  s = @worksheet_meta_data.qualify current_user.username
  if s.nil?
    flash[:notice] = "WorksheetMetaData was qualified (#{@worksheet_meta_data.qualified_by})."
  else
    flash[:error] = "Qualification failed: #{s}"
  end
  rescue Exception => ex
    flash[:error] = "ex=#{ex}"
  end
  redirect_to(@worksheet_meta_data)
end

I also commented out the redirect! statement, so after the get or post, there is the assert, with a flash_me to see the result. The first extra line will confirm that the method is being invoked (are you using the right controller, action, and id; these might give a 404 error if not). Then everything up to the redirect is wrapped in a rescue block so any errors thrown get recorded in flash[:error]. Inside the block, I check

I would be interested to hear of any better ideas.

Struggling with Ruby: Contents Page

Ruby Classes

2008-12-10T21:27:00.004Z

In Ruby, everything is an object. You can find the class of an object with my_object.class, which returns an object of the Class class.

10.class  # => Fixnum
10.class.class # => Class
"Hello World".class # => String

If you do not have an instance of a class, you can determine the name of the class using the inspect method (this might be useful if you are in a class method in a super class and want to know the subclass).

The superclass method will produce the superclass.

10.class.superclass # => Integer
10.class.superclass.superclass # => Numeric
10.class.superclass.superclass.superclass # => Object

As in Java, everything inherits from Object.

You can check if an object is of a certain class using the is_a? method. This will return true if the object is of the given class or of a subclass of it.

"Hello World".is_a? String # => true
"Hello World".is_a? Fixnum # => false
"Hello World".is_a? Object # => true

What methods are there?
The methods method returns an array of method names for an object, while a call on methods from the class will produce an array of class methods.

"Hello".methods
String.methods

There are also methods that list more particular methods, such as public_instance_methods or private_methods.

You can also check if an object has an associated method with the respond_to? or method_defined? methods. Unlike methods, these two methods will not find private methods. The respond_to? method really does what it say - it tells you if the object will respond to the method call, rather than if the method exists. Often an object can respond to method calls where there is no method present using the method_missing functionality (discussed here). Rails uses this a lot. For a model, Post, calling Post.methods will locate no find methods, but the respond_to? method confirms they are there. method_defined? will tell you if the method actually exists.

"Hello".respond_to? 'length' # => true
String.respond_to? 'constants' # => true
Post.respond_to? 'find_by_name' # => true
Post.method_defined? 'find_by_name' # => false

See also:
http://www.ruby-doc.org/docs/ProgrammingRuby/html/ospace.html

Dynamically adding a method
You can add a method to a class at runtime, using the define_method method. Note that this method is private (so the first attempt below results in an error), and so must be invoked with the send method.

a = "what".class.define_method('hello') {p 'Hello World'}
# => NoMethodError: private method `define_method' called for String:Class
a = "what".class.send(:define_method, 'hello') {p 'Hello World'}
# => #<Proc:0x08cb9294@(irb):17>
irb(main):018:0> "say hello".hello
# => Hello World

You can even replace existing methods:

"what".length
=> 4
a = "random".class.send(:define_method, 'length') { 10 }
=> #<Proc:0x08caaf28@(irb):21>
"what".length
=> 10

Alternatively (and more simply), you can define methods for existing classes just like you would for your own class. The first example could be done like this:

class String
  def hello
    p 'Hello World'
  end
end

I can see security issues here if someone can change how your classes' behave at runtime, and how do you comprehensively unit test if you cannot be sure how the String class behaves? All part of the fun of a dynamic language...

ObjectSpace
ObjectSpace is the Ruby reflection mechanism. It is a module that tracks all the current objects. You can list them with this:

ObjectSpace.each_object{ i puts i}

I had over 8000 objects in one IRB session. You can specify the class of an object to list, for example, this will list all objects of the Class class (only 466 of them):

ObjectSpace.each_object(Class) { i puts i}

Creating new objects dynamically
You can use the ObjectSpace to create a new object from a string containing the class name (see here), but I prefer using the eval method. eval simply interprets a given string as Ruby (like the synonymous method in JavaScript). The eval method is none too fast, but I do not know how it compares to using ObjectSpace.

def create_object class_name
  eval("#{class_name}.new")
end

Struggling with Ruby: Contents Page

Ruby Methods Part 2 - Not Overloading!

2008-12-05T20:45:00.007Z

Method overloading is a common feature of several object-orientated languages. It allows the same name to be used for methods that perform the same, but accept different parameter types. Here is an example in Java:

  // Method overloading in Java
 public int myMethod(String name, int age, int shoeSize) {
   // do stuff
 }

 public int myMethod(String name, int shoeSize) {
   myMethod(name, 0, shoeSize) {
 }

 public int myMethod(int age, int shoeSize) {
   myMethod("", age, shoeSize) {
 }

 public int myMethod() {
   myMethod("", 0, 0) {
 }

 // Invoking
 public int main(String[] args) {
   myMethod("F2Andy", 43, 8);
   myMethod("F2Andy", 8);
   myMethod(43, 8);
   myMethod();
 }

Ruby does not support method overloading, something I found very surprising at first. I suspect the reason is the way Ruby handles objects. Java is very strict that what gets sent to a method is exactly what the method expects. That gives (I would imagine) more robustness, but at the loss of flexibility.

Ruby has what could be described as "method over-writing" instead of overloading. In this example, the second test method over-writes the first:

def test s
 puts "hello test"
end

def test
 puts "goodbye test"
end

test                # Causes "goodbye test" to be printed
#test "my string"   # Causes an error:
   # wrong # of arguments(1 for 0) (ArgumentError)

See here for how to use alias if you still need to access the old methods:
http://www.zweknu.org/blog/index.rhtml?start=77&

Default values and dynamic typing
Ruby has four tricks to mimic method overloading, and I am going to bundle the first two together. The first is default values in the method definition. Simply give a parameter a default value and it becomes optional. The second is the way Ruby handles objects; dynamic typing. Ruby does not care what sort of object you throw at a method, leaving the method writer the chance to handle different classes in different ways. In the next example the method has a default value - "default" - but the method is written in such a way that it will accept any class of object:

def test t = 'default'
 puts "goodbye test t=#{t}"
end

test           # => "goodbye test t=default"
test 34        # => "goodbye test t=34"

Something to consider, then, is how you handle unexpected objects in your class. One way is to ignore the issue, making the assumption that the method user knows what he is doing and any problems will be caught by the Ruby system.

def test t = 'default'
 puts 'goodbye test t=' + t
end

test "one"     # => "goodbye test t=one"
#test 2        # => can't convert Fixnum
              # into String (TypeError)

Let us look at another example to see what options we have:

def test n
 puts n.abs
end

test -4          # => 4
test 2           # => 2
#test "three"    # => undefined method `abs'
                # for "three": String (NoMethodError)

Rather than relying on your own method calls to generate errors, you might prefer to check that what you receive in your method is what you are expecting. You can then be quite clear about what exceptions your method is throwing, and more importantly, you will not have exceptions thrown half way through you method leaving the system in an unpredictable state.

def test n
 raise StandardError.new("Oops, not a Fixnum") unless n.is_a? Fixnum
 puts n.abs
end

test -4          # => 4
test 2           # => 2
test "three"     # => Oops, not a Fixnum
                # (StandardError)

Then again, perhaps you do not care what class the object is. The important question is whether it will behave as you expect. Instead of testing that it is of the right class, you could test that it responds to the appropriate methods calls. In this next example, a new method, abs, is added to the String class (how that is done was the subject of another post). Now the test method checks that the object it is given will respond to the necessary method call. This technique offers a lot more flexibility, but does rely on the API user sending sensible objects to the method. Does it really make sense that a string should return the ASCII code of the first character when asked for its absolute value? However, I would say that that is up to the API user; he has the responsibility now of ensuring the object he sends makes sense. You would need to check for each and every method call in your code.

class String
 def abs
   self[0]
 end
end

def test n
 raise StandardError.new('Oops, object does not respond to abs') unless n.respond_to? 'abs'
 puts n.abs
end

puts "three".abs     # => 116
test -4              # => 4
test 2               # => 2
test "three"         # => 116

What would have happened if I had defined the abs method on String to return a string, rather than a Fixnum?
Using hashes for parameters
The third trick is to use a hash, and this is done throughout Rails. In the next example, the method expects a hash. Note that the default is set to be an empty hash, to avoid errors with nil.

def test options = {}
 puts "hello #{options[:name]}"
end

test                     # => "hello "
test "here"              # => "hello "
test :name => 'F2Andy'   # => "hello F2Andy"

Compared to method overloading, there are advantages on both sides. If you have an existing method and you want to add overloading, it is no problem in Java. In Ruby, chances are your existng method is not expecting a hash and you either have to change your existing method calls or write the new method to expect either a hash or the original type. However, if your Ruby method already accepts a hash, adding more parameters becomes trivial - just add them to method calls if desired, and use in the method code where needed.

Variadic functions
Finally, Ruby supports variadic functions. These are methods that accept a vaiable number of parameters. In Ruby this is indicated by an asterix in the method parameter list, before the last parameter. This will then become an array holding all the "left over" values. Here is an example:

def vari_method name, *values
 puts name
 values.each { |x|
   puts " -#{x}"
 }
end

vari_method 'fruit', 'apple', 'banana', 'pear'

When vari_method is invoked, 'fruit' goes into the name variable, and the three other strings are collected into a single array, values. The method prints the name, then lists each member of the array. There is no reason for the members of the array to be of the same class or in any way connected to each other.

Struggling with Ruby: Contents Page

Ruby Methods Part 1 - The Basics

2008-12-04T21:36:00.006Z

A Ruby method definition starts with the keyword def followed by the method name and the parameter names, and ends with the keyword end.

def test
puts "Hello World"
end

test   # Causes "Hello World" to be printed

Note that unlike Java and C#, Ruby does not require the return type or the parameter types to be stated. Every Ruby method returns a value. In the above example, puts returns nil, and as this is the last statement in the method test, test will also return nil. The return keyword is entirely optional (though necessary if you want to jump out of the middle of a method, of course).

Visibility
By default, all methods are public; they can be accessed from anywhere by anything.

Private methods can only be accessed from with the class and (unlike Java et al) its subclasses. That said, you can access private methods from anywhere using the send method, or modify their visibility on-the-fly, so it would seem that this is more advisory than anything else; the API writer is telling you that you probably should not use those methods.

The private keyword indicates that all subsequent methods (until public or protected is encounted) will be private.

class MyClass
def public_method
 puts "In public_method"
end

# You can access private methods within the class
def private_via_public_method
 puts "private_via_public_method"
 private_method
end

private  # Flags all subsequent methods
        # as private

def private_method
 puts "In private_methodstance_method"
end
end

class MySubClass < MyClass
# You can also access private methods
# within any subclass
def private_via_subclass_public_method
 puts "private_via_subclass_public_method"
 private_method
end
end

mc = MyClass.new
mc.private_via_public_method
mc.public_method
#mc.protected_method    # Protected method
                     # not visible
#mc.private_method      # Private method
                     # not visible

mc.send :private_method # Private method
                     # accessed with send

# Visibility can be changed dynamically
class MyClass
public :private_method
end

mc.private_method      # Private method is
                    # now visible

The third visibility type is protected, which is a little more esoteric. The protected visibility is very similar to private, except that protected allows you call method from a different object, as long as that object is of the same class or subclass. To put it another way, private is restricted to the specific object, protected is restricted to the class.

class MyClass
# You can access private methods on the
# object within the class
def private_via_public_method
 private_method
end

# You can access protected methods on another
# object within the class
def protected_via_other_public_method
 mc = MyClass.new
 mc.protected_method
end

# This will fail
# You cannot access private methods on another
# object, even within the class
def private_via_other_public_method
 mc = MyClass.new
 mc.private_method
end

protected
def protected_method
 puts "In protected_method"
end

private
def private_method
 puts "In private_methodstance_method"
end
end

The important point here is that both private and protected methods can only be used with the class (or subclass), but that private methods are further restricted to calls that do not require the dot operator.

As an aside, in Ruby all constants are public, and all variables are private

Class methods
Class methods are methods that are applied to the class rather than to a specific instance of the class. The most important example of a class method is new; in Rails the find method is also used very frequently.

s = String.new "My string"  # Equivalent to
                              # s = "My string"
post = Post.find :first     # gets the first record
                         # from the posts table

As can be seen, class methods are invoked by using the class name, rather than the object, and as in the examples above they are often used to create or retrieve instances of the class.

Class methods are written much like instance methods, but with the keyword self before the method name. You cannot call a class method from an instance of the class, or call an instance method from the class itself. This does mean you can have a class method with the same name as an instance method.

See the next section for an example of a class method.

The initialize method
I have already mentioned the new class method. What this does is create a new instance of the object, and then it invokes the initialize method, if it exists. The initialize method is always private; there seems no way to change that. However, you can invoke it from within your class.

The following code illustrates the use of initialize and class methods.

class MyClass
def initialize
 puts "In initialize"
end

def self.class_method
 puts "In class_method"
end

def instance_method
 puts "In instance_method"
end
end

MyClass.class_method     # Prints "In class_method"
mc = MyClass.new         # Would cause error; cannot call class methods on an object
#mc.class_method         # Prints "In initialize"
mc.instance_method       # Prints "In instance_method"

Class initialize method?
Sometimes you might want to do something to set up your class. You want it to run before any instances and created. I believe Rails does this for ActiveRecords, inspecting the database to see what fields are present, so it will know how to handle requests, rather than inspecting the database each time a request is made.

There is no method that supports this, you just put your code straight into the class definition.

class MyClass
p 'This will be printed when the class is loaded'

def initialize
 p 'This will be printed when an object is instantiated'
end
end

Multiple return results
Pretty much every modern language allows you to send multiple arguments to a function/procedure/method. How many allow you to return multiple arguments? Certainly not the C derivatives, and really I cannot see why that should be so. At the machine code level, I would assume there is no difference. I would guess the reason is that C is based on a mathematical concept of functions, F = f(x,y,z), and Java and C# had followed suit.

Not so Ruby, which allows you to return as many values as you like. Here is a trivial example to illustrate that:

def test
return return 1, 'two', 3
end

a, b = test
p a # => 1
p b # => "two"

a, b, c, d = test
p a # => 1
p b # => "two"
p c # => 3
p d # => 4

Note that in this case the return keyword is required. What is actually returned is an array containing each each return value. This can lead to confusion...

def tester
  return 3, 6
end

def output x, y = nil
  p "x=#{x} y=#{y}"
end

x, y = tester
output x, y
# => "x=3 y=6"

output tester
# => "x=36 y="

The first call to tester correctly gets the two values assigned to the two variables. However, the second fails; the array is passed directly to the output method, which has no clue about the context, and just sees an array. What is really happening is a bit of trickery. Ruby does not pass back multiple values at all; it just passes back an array when multiple values are used with return. Meanwhile, at the other end, Ruby allows multiple varaibles to be set from an array.

x, y = [7, 6]
output x, y

Overall we have the illusion of muliple returns.

blog on dynamically creating methods:
http://ola-bini.blogspot.com/2008/05/dynamically-created-methods-in-ruby.html

Struggling with Ruby: Contents Page

Ruby File Access

2008-11-22T22:29:00.013Z

Reading Files
Note that while Ruby accepts backslashes, it seems to prefer forward slashes in file paths, even on Windows.

You can access the contents of a file like this:

file = File.open(filename, 'r')
do_stuff_with file
file.close

To test if the end of the file has been reached, use file.eof?. To test if a file has been closed, use file.closed?.

You can read the entire contents of file in a block:

contents = File.open(filename, 'r') { |file| file.read }

Or just:

contents = File.open('test.txt', 'r').read

If you prefer, you can put each line of the file into an array:

lines = []
File.open(filename, 'rb') { |file|
file.each_line { |line|
 lines << line
}
}

Note that file here is exactly the same object as in the very first example. The big advantage of using it in a block is that Ruby will ensure the file is closed for you. You can use each_byte to iterate through the bytes (or, of course, your custom do_stuff_with file method). You can break lines at any character, for example, at the full stops:

lines = []
File.open(filename, 'rb') { |file|
file.each_line('.') { |line|
 lines << line
}
}

Alternatively, use IO.foreach:

lines = []
IO.foreach(filename, '.') { |line|
lines << line
}

Or simply use IO.readlines (why was it not named read_lines?):

lines = IO.readlines(filename, '.')

Writing Files
To write data to a file, you can do something like this:

file = File.new("test.txt", "w")
file.syswrite("First line of text")
file.syswrite("Second line of text")
file.close

However, the prefered way, as with reading a file, is to do it in a block, and leave it to Ruby to close the file:

File.open("test.txt", "w") { |file|
file.syswrite("First line of text")
file.syswrite("Second line of text")
}

As well as syswrite, you can also use write, print, puts (adds a return at the end of the line), p (alias for puts) and printf (formated print, just like the C function of the same name). Or you can use the append function:

File.open("test.txt", "w") { |file|
file << "First line of text"
file << "Second line of text"
}

Binary Files
Binaries files are just the same; you just add a b to the second parameter of the open method. This example reads the contents of a binary file to contents (which is a string, by the way), and then writes that to a new binary file:

contents = File.open(in_filename, 'rb').read

File.open(out_filename, 'wb') { |file|
file << contents
}

Manipulating Files
These are all pretty self-explanatory:

File.rename(old_filename, new_filename)
File.exists?(filename)
File.file?(filename)
File.delete(filename)
File.directory?(filename)
File.executable?(filename)  # Returns true for a text file!
File.readable?(filename)
File.writable?(filename)
File.zero?(filename)
File.size(filename)   # Return 0 if the size is zero
File.size?(filename)   # Returns nil if the size is zero
File.ftype(filename)

Using Directories
You can list the contents of a directory at least three way:

Dir.entries(dir)  # Surprisingly, no default for current directory
Dir["#{dir}/*.txt"] #
`dir`

The first and second will produce arrays of the files in the given folders. The first has just the filenames, and starts with entries for "." and "..". The second has the full path for each file, but does have the facility to filter (as in the example, only .txt files will be listed). The third uses a backquoted string to invoke a system command, and will produce a flat string with the same contents that you would see if you typed "dir" at the command prompt (presumably an error on some operating systems).

Other methods:

Dir.pwd                  # Gets the current directory
Dir.chdir('c:')          # Changes the current directory (to c:)
Dir.mkdir('newfolder')   # Create a new directory
Dir.delete('newfolder')  # Or unlink or rmdir

Putting It Together
Here is an actual program. It uses the directory functionality to create an array of file names conforming to the filter (in this case, files end .nif; NetImmersion format), then iterates through the array. For each filename, the file is opened in binary format, the contents read to a string, and then each occurance of one set of strings replaced by another (this was subst, an array of hashes, giving replacement names for texture files). Finally, the file is saved, again in binary format, with a new filename.

files = Dir["#{mesh_dir}/in_r*.nif"]
print "Found #{files.length} files.\n"
Dir.chdir(mesh_dir)
files.each { |f|
contents = File.open(f, 'rb').read
subst.each { |h|
 contents.gsub!(h[:old], h[:new])
}
File.open(f.gsub(/In_R/i, 'And'), 'wb') { |file|
 file << contents
}
print '.'
}
print "\nDone.\n"

File data in with code?
If you put __END__ in your code, Ruby execution will terminate at that point. Everything beyond that will be considered data, and can be accessed as a file, DATA. Here is a complete program to illustrate that:

p DATA.read

__END__

Your data goes here

Reading a CSV file
This is trivial, as Ruby provides a library to do just this.

require "csv"
values = CSV.read "C:/my-data.csv"

This gives you your data in a two dimensional array.

Struggling with Ruby: Contents Page

Contents Page

2008-11-15T10:40:00.047Z

This is not a blog in the true sense, where I create a new post each time I learn something. Instead, I am collecting what I learn into a collection of larger posts, and updating those posts as I learn more. Below is a list (a contents page if you like) of posts to date (22/Dec/09) grouped by topic, rather than chronologically, for easy reference.

Ruby Basics
Constants
Variables
Conditional statements
Case statements and relationship operator
Loops
Regular Expressions
Exception Handling

Methods, classes, etc.
Ruby Classes
Duck-typing
Methods - Basics
Methods - Not Overloading
Methods - method_missing
Methods - calling
Modules
Singletons
Proc objects
Blocks
Accessors
Operator Overloading

The Ruby Library (excluding Rails)
Hashes
Arrays
Strings
File Access
Time, Date and DateTime
Unit Testing
YAML
REXML for XML
Sockets
GUI with Shoes
GUI with Monkeybars (and Swing)

Miscellaneous
JRuby and Java

Links to APIs
Because I am always refering to these three...
Array
String
Hash

Rails
Building a Project
Basic Project
Deploying on Tomcat

The Model
Creation
Validation and Association
Interactive Rails Environment
Testing
Find and other methods
Date and Time
Gotchas

The Controller
Routing
Basic Methods
Render and Filter
Functional Testing
Testing for valid HTML

The View
ERB and Links
Scope, Helpers and Partials
Using Forms
Using Select/Options
Partials as methods

Handling Images On Rails
Dynamic Images with RMagick
Dynamic Images with Java
Generating Line Graphs with Java
Uploadable Images with File Column

More On Rails
Integration Testing
Rails Mailer
Usage Statistics on a Bar Graph with HTML
Single Table Inheritance
Moving to Rails 2.2.2
Moving to Rails 2.3.8
Using JavaScript
Using Java applets
Organising in Subdirectories
named_scope
Iterating through records
Singularize and Pluralize
Capturing file uploads

Useful Links
General Ruby and Rails
Good Rails tutorial that go beyond the very basic:
http://www.akitaonrails.com/2008/5/25/rolling-with-rails-2-1-the-first-full-tutorial-part-1

Book on Ruby (not Rails):
http://ruby.activeventure.com/programmingruby/book/index.html

FAQ
http://www.ruby-doc.org/docs/ruby-doc-bundle/FAQ/FAQ.html

Cheatsheet:
http://www.ilovejackdaniels.com/cheat-sheets/ruby-on-rails-cheat-sheet/

Quick ref:
http://www.zenspider.com/Languages/Ruby/QuickRef.html

Others
PDF generation:
http://prawn.majesticseacreature.com/

XML handling with REXML
http://www.germane-software.com/software/rexml/docs/tutorial.html
http://www.developer.com/lang/article.php/3672621

The Controller Part 4 - Functional Testing

2008-11-15T09:20:00.009Z

Functional testing targets individual methods in your controllers. It tests the user is redirected, gets the right HTTP response and so on, without actually generating any web pages (though it does generate the HTML so will find errors there).

Setting it up
Rails creates functional tests, but there are a few things to be done first... The test database must be set up (though this was probably done when you did your unit testing):

rake db:test:prepare

As with unit testing the require needs altering, if you are using NetBeans 6.1: require 'test_helper' becomes require 'test/test_helper'. You should now be able to run the default tests put there by Rails (depending on the changes you have made to the controller and model). Outside of an IDE, the easiest way is using rake.

rake test (run all tests)
rake test:functionals (run all functional tests)
rake test:recent (run all test files modified in last 10 minutes)

There are typically three parts to a test method. The first part is setting up, and might include, for instance, logging a user on. The second, and only required, part calls the method and checks changes to the database. The third part checks the HTTP result.

def test_should_get_new
 login
 get :new
 assert_response :success
end

Method Calls
By default, controller method calls have all the parameters you would expect (eg :controller), but often you want to add more. In this example, an extra parameter is given. This is equivalent to ?run=199 at the end of the URL.

get :new, :run => '199'

In his example, parameters for a model are given. This is equivalent to data in a form, as usually accessed via params. I found that this was essential for create, otherwise there is no data in your model, and so nothing gets saved and the test fails.

post :create, :sample => { :sample_reference => 'P12345', :sample_type => 'PP1'}

Checking the results
While your view can, of course, access any instance variable in the controller, you do not have direct access to those variables from within your tests. Instead, they can be accessed though the assigns method. This allows you to test against values.

assert_not_nil assigns(:samples)
assert_equal 1, assigns(:samples).length
assert_equal 'glc', assigns(:sample).analysis
 # Test value of a specific attribute for one record

To check the returned HTTP code, just use the standard method:

assert_response :redirect

Other options are :success, :missing and :error. Not sure why you would test for the last two.

You can also test the template used. This is for those occasions when you specified a template (like this; render :template => 'folder/template'), otherwise the template is nil.

assert_template 'samples/new'

The last check is where the page has been redirected to. You can use the same parameters for assert_redirected_to that you can for redirect_to.

assert_redirected_to :controller => 'samples', :action => 'home'
assert_redirected_to samples_path
assert_redirected_to sample_path(assigns(:sample))

See also:
http://api.rubyonrails.com/classes/ActionController/Assertions/ResponseAssertions.html

You can also check what has happened to your database table with the assert_difference method. Wrap this method around your method call, and it will check that the number of records has changed by the appropriate amount. This example checks the number of records for a model called Post has increased by one (the default value) when a new record is created:

def test_should_create_post
 assert_difference('Post.count') do
   post :create, :post => { }
 end
 assert_redirected_to post_path(assigns(:post))
end

The destroy method needs to check that the number of records has decreased by one, so in that case the method call looks like this:

    assert_difference('Post.count', -1) do

What assert_difference does is to determine the value of the first parameter (Post.count in the example), then run the block, and then determine the value of the first parameter again. It then compares the value before and after, and checks that difference against the second parameter (which defaults to +1).

Fixtures
Fixtures are a way to easily generate example data. You can point your tests to a fixtures file with:

fixture :my_data

By default, rails includes the statement fixture :all in tester_helper.rb, so all the fixtures get loaded for all your tests.

Rails will look for test/fixtures/my_data.yml (or test/fixtures/my_data.csv), and use the data in there to create a data structure, my_data (actually, I suspect my_data is a method that returns the data_structure, but the effect is the same), as well as in your database table. Here is an example of a fixtures file, employees.yml.

:one
name: Fred Smith

:two
name: Mary Jones

You can access specific records from your fixtures using their label. For the employees fixture, to access Fred Smith, use:

employees(:one)

Functional testing gets a little more complicated once you have a model that belongs_to another (see here for how to set up the model). Let us suppose the companies.xml fixture file look like this:

:one
name: The Excellent Software Company

:two
name: MegaSoft Ltd

In the Employees fixture file, employees.yml, you can set up the association for the company very easily. Just add a key named after your associated model, with the value equal to the label you used for your entry (without the colon):

:one
name: Fred Smith
company: one

:two
name: Mary Jones
company: one

To assign a company to an employee in a test, use something like this:

post :create, :employee => {:name => 'Tom Johnson', :company => companies(:one) }

Preventing something when testing
It may be desirable to prevent some actions happening while testing, for example, confirmation e-mails being sent whenever a new user account is set up. This is easily done by checking ENV['RAILS_ENV'].

def my_method
return if ENV['RAILS_ENV'] == 'test'   # Do not during testing
do_stuff_only_if_not_in_test_environment
end

Obviously this could cause potential problems, as you are specifically not testing some of your code, so use with care!

Testing functions that require a logged in user
This is what works for me...

At the start of each relevant method, put in a line like this:

login_as_admin(@request)

In test_helper.rb, define the login method, something like this:

def login_as_admin(request)
 user = User.new
 user.login = "tester"
 user.email = "tester@domain.com"
 user.username = "Test Administrator"
 #...
 # Set up other details, permissions, etc.
 #...
 request.session[:user_id] = user.id
end

You should also test that a user will get redirected if not logged in (and that a user logged in but with permissions gets redirected too). Here is how:

def test_should_be_refused_without_login
 get :new   # Example method to test
 assert_response :redirect
 assert_redirected_to :controller => 'session', :action => 'new'
end

Similar methods can be set up for other user roles, to test how the system behaves.

Testing helper methods
You can test your helpers (in application_help.rb) in your functional tests.

class HelperTest < Test::Unit::TestCase
  include ActionView::Helpers::TextHelper
  include ActionView::Helpers::TagHelper
  include ApplicationHelper
  # include whatever helpers you want to test here, sometimes you'll need
  # to include some of the Rails helpers, as I've done above.

  def test_some_helper
  end
end

However, you do not have access to the usual Rails helpers, and so any of your methods that rely on them are going to generate errors. There may well be a way around that that I have yet to discover, though as some Rails helpers use the context of the web user to determine their behavior (eg, the output of link_to depends on the current web page) there may not.

Credit: http://blog.lathi.net/articles/2006/03/31/testing-rails-helpers

Testing filter methods
You can test filter methods via the usual fuctional tests, for example having one test in which a user is signed in, and another in which the user is not. However, I feel it is better to also test the method itself. I would describe that as unit testing, but as your filter may well do a redirect, you will have to test it in your functional tests. This will be a protected, instance method, so can be invoked like this:

MyModelsController.new.send(:check)

However, as far as I can find, there is no way to set the params variable, so you cannot test a filter that, for example checks an id exists (see forum thread here for more).

What to test
My opinion is that you need one functional test for each outcome of each action in your controller. If an action can result in either of two pages being rendered, then that action needs two tests (that said, I rarely bother to test for when a save fails). This rule of thumb does rely on you having pretty much nothing in your controller besides setting up the instance variable, and deciding what page to display; all the complicated stuff is in the models, and that is adequately covered in your unit tests.

Things to watch out for
If you get a error complaining about a database table or column missing check that the table or column really is there via SQL - have you updated your test tables after modifying them in the development environment? Alternatively, if there is not supposed to be a table or column of that name (eg a subclass in STI or a model you later removed), check the test/fixtures directory; Rails may be trying to put data from here into your old table - just delete the .yml file for an erroneous table, or edit the data to remove references to the erroneous column.

If you are getting 300 responses when you expect successes, it might be because you need to set up a session with an appropriate user.

I write tests by copy-and-pasting existing tests. This leaves me liable to having two tests with the same name. Ruby will give no warning about this, but will only perform one of the tests, which can lead to a false sense of security.

You cannot rely on the values of the id field. In the development database they number sequentially from 1, but in the test database they start at some huge number.

I had a method that found the most recent entry of a certain type in the database and used that as a template for a new one. This is difficult to test, because all the entries in your fixtures file get created at the same time, so you have no idea which one will be selected as the most recent. Fortunately, in my case I had a reference number for each record and I could use that instead.

The data in fixture files gets loaded without validation, which is fair enough. However, validation will apply to the method calls in your tests. So if your update test uses update_attributes, and is working with a record that will not validate (perhaps the record has a required field missing, or the same supposedly unique field as another), the result will be that update_attributes will return false, with no clue as to why. It took me about a long time to realise this.

Similarly, if your create method is failing to increase the count in your database table, it may be because the validation fails.

Be aware that functional testing will not check any of your links actually go anywhere, or that your web pages make sense.

I have to say that in setting up functional tests for my project, most of the errors it turned up were down to the testing, rather than real bugs...

Struggling with Ruby: Contents Page

Loops

2008-11-02T23:18:00.004Z

Ruby has several options for loops; I will start with for and each loops. In practical terms, there is not a lot between for and each besides style, though each is actually a method call that takes a block, while for seems to be a language feature. They both iterate over a collection, which could be a hash, a string, an array or a range. Let us look at ranges first.

For and each with ranges
Use of a range takes the place of the normal for/next loop. In these examples, 1..10 and 1...11 are Range objects; the three dots indicates that the end stops before the terminator, two dots indicates it includes the terminator. These three examples will all print out the numbers 1 to 10, illustrating the difference between each and for, and the two and three dots.

for i in 1..10
 do_stuff
end

for i in 1...11
 do_stuff
end

(1..11).each do i
 do_stuff
end

Ruby is perfectly happy with characters and variables in a Range object, and the next example shows how a range can be assigned to a variable.

r = 'a'..'z'
for i in r
 puts i
end

n = 5
(1..n).each do i
 puts i
end

These loops output the Range object, by the way, and you can test if something is within a range using the member? method (eg r.member? "c").

A quick note about arrays and ranges. I got really confused by putting square brackets around a range. What is [1..5]? This is an array with a single member, and that member is a Range object.

For and each with arrays, hashes and strings
The each method allows you to iterate over each member of a string, an array or a hash.

array.each { member do_stuff_with(member) }
array.each do member
 do_stuff_with(member)
end

For a hash, you pass two values to the block

hash.each { key, value do_stuff_with(key, value) }
hash.each do key, value
 do_stuff_with(key, value)
end

You can use the for feature with hashes and arrays too, for example:

h = {:a => 19, :b => 35, :c => 3456}
for k, v in h
 puts "key=#{k} value=#{v}"
end

The times method
In Ruby everything is an object, and integer objects (of the class Fixnum) have a method called times, which, like each, accepts a block, and iterates from zero up to one less that the number. In these examples, the numbers zero to nine are printed.

10.times { i puts(i) }

10.times do i
 puts i
end

n = 10
n.times { i puts i }

Invoking times on a negative number will create a loop with zero iterations!

The yield feature
You can easily define your own methods that work like each and times, using the keyword yield. Say this method is defined in a class, Car:

def cars
 yield "Red car"
 yield "Green car"
 yield "Blue car"
end

The following will then produce a list of cars; red, green and blue.

m = MyClass.new
m.cars { c puts c }

The cars method runs until it hits the yield, and at that point passes the value back to the calling code, which then processes it as required. Then the loop goes again, and the cars method continues to the next yield stament. The loop iterates until it runs out of yields (the cars method will run to the end regardless of any further yields in the code).

The while and until loops
Ruby also supports while and until. The until loop is just a while not loop. There appears to be no option to check the conditional after the iteration that I have found.

Infinite loops
You can also create infinite loops with the loop method. Hmm, beter make sure there is some way to break out of the loop, which brings us to:

The break, redo, retry, next and return keywords
Ruby also has some interesting keywords to modify loop behaviour. As with C and derivatives, the break statement drops you out of the current loop. The next statement replaces continue; it stops the current iteration, moves to the next one, and passes control to the condition at the end of the loop. The retry statement is similar, but does not move to the next iteration; it repeats the current one. The redo statement starts the whole loop from the first iteration. There is also a return statement, which drops you straight out of the entire method (and optionally takes a parameter; a value returned by the method).

Struggling with Ruby: Contents Page

Conditional statements

2008-11-01T18:19:00.006Z

Before going any further, try this in the Ruby interactive console:

puts false or true        # prints false
puts true and false       # prints true

Surprisingly, what gets printed is false and true respectively. What is going on? The problem is that and and or do not bind as strongly as the method call. In effect, you are doing this:

(puts false) or true
(puts true) and false

Contrast this with && and . These bind more tightly than the method call, and so behave as you would expect.

puts false  true        # prints true
puts true && false        # prints false

More on operator precedence here:
http://www.techotopia.com/index.php/Ruby_Operator_Precedence

if and unless
While C and its derivatives have only if (condition) statement; Ruby supports two conditionals, if and unless, each in two formats:

if condition
 statement
end

unless !condition
 statement
end

statement if conditional

statement unless !conditional

You can optionally surround your conditional in brackets.

Ruby uses lazy conditionals. In the following code, if s is nil, Ruby knows that the expression will be false, and so does not test s.length > 10 - which is good, because that would throw an exception. This could, however, be a problem if you are changing the state of something in your condition; it might not change as often as you might imagine.

if !s.nil? and s.length > 10
 puts 'Long string'
end

Conditional assignments can be done with the ||= operator.

s ||= "default"

The way this works is that nil counts as false, and in effect it say s = s || "default". If s is nil or false, then s becomes "default", otherwise it keeps its orignal value.

Ruby also supports the usual tertiary operator:

x = conditional ? value1 : value2

Struggling with Ruby: Contents Page

YAML

2008-10-27T20:56:00.012Z

YAML is a format for structuring data in a file, like XML. Rails uses YAML to configure your databases, but it does so in such a way that you hardly notice. However, YAML is pretty neat, and you could be missing out.

YAML stands for "Yet Another Markup Language" (here). Or perhaps for "YAML Ain't Markup Language" (here). I guess it depends on whether you think it is a markup language or not (actually the latter seems the more common one).

There are basically two types of data; that which goes into a hash, and that which goes into an array.

name: value
- value

You can combine them to make complex data structures, such as this array of hashes:

-
  name: Tom
  age: 32
-
  name: Dick
  age: 19

And in fact you can also enter arrays and hashes more like Ruby:

- { name: Tom, age: 32}
- { name: Dick, age: 19}

Or as an array of arrays:

- [Tom, 32]
- [Dick, 19]

Comments start with a hash, #, just like Ruby. Ruby/YAML guesses the type from the format. Strings can be surrounded with single-quotes, double-quote (allowing escape sequences) or nothing. Repeated data can be replaced by an "anchor", by labelling the first occurance. Labels begin with an ampersand, and references to the label with an asterix. Use | or > for data that goes on to more than one line. The former preserves line breaks, the latter does not (see the example at the end of the YAML and Ruby section).

This example show all of these, and uses symbols as the keys, rather than string as above.

-
  :name: Tom         # A string
  :age: 32           # An integer
  :male: true        # A boolean
  :born: 1972-02-29  # A date
  :address: &add
    213 Main Street
    Big City
    England
  :comment:
    This is a potentially very
    long comment that will be
    just one line long.
-
  :name: Dick
  :age: 19
  :address: *add
  :comment: 'A very short comment'

See here for more details:
http://yaml.org/spec/current.html

By the way, NetBeans 6.1 flags up strings that go on to multiple lines as errors; this seems to be a bug in NetBeans.

YAML and Ruby
To use the data from your YAML file in a Ruby program, the first step is to load the YAML library:

require 'yaml'

Then load the data:

config = YAML.load(yaml_string)       # From string
config = YAML.load_file("config.yml") # From file

Then you can access to data just as you would any array of hashes (or whatever your data structure):

x = config[0]['age']    # x -> 32

Note that if you want to use symbols as the keys to your hashes the string needs to be prefixed with a colon (as in the examples above).

Going the other way is nearly as easy:

yaml_string = config.to_yaml            # To string
File.open('config.yml', 'w') do |out|   # To file
   YAML.dump(config, out)
end

Here is an example program that includes the YAML text (as a "here" document), and illustrates how YAML handles text that goes over multiple lines:

require 'YAML'

y = <<YAML_TEXT
:first: >
    This is a folded block,
    line breaks are discarded
    for spaces. The line ends
    with a return.
:second: |
    This is a literal block,
    and so the line-breaks
    are preserved. Again the
    line ends with a return
:third:
    This is a folded block
    too, as YAML defaults
    to that. However, this time
    there is no return at the end.
:fourth: And again a folded
         block formated slightly
         differently, with no return
         at the end.
YAML_TEXT

h = YAML.load(y)
p h[:first]
 # => "This is a folded block, line breaks are discarded for spaces. The line ends with a return.\n"
p h[:second]
 # => "This is a literal block,\nand so the line-breaks\nare preserved. Again the\nline ends with a return\n"
p h[:third]
 # => "This is a folded block too, as YAML defaults to that. However, this time there is no return at the end."
p h[:fourth]
 # => "And again a folded block formated slightly differently, with no return at the end."

You can combine several data structures into a single file. Each should start with three dashes on a line on their own to indicate the start of a new document. Use the load_stream method to open the file. For example:

  data_doc = YAML::load_stream(File.open('data.yml'))
  NAME_SCHEMAS = data_doc.documents[0]
  DATA_TYPES = data_doc.documents[1]
  CATEGORIES = data_doc.documents[2]

YAML and Rails
You can use a YAML file to kick start your database table in Rails. Rails already uses YAML, so no need for the require. The YAML file goes in the root directory for your web application.

One way that I have seen is to put the code inside your migration file, and when you migrate, the data goes straight into your table. However, this is a short term solution only. What happens in your production database or for testing? You could clone your database, but the prefered Rail way is to use Rake to generate the database tables, based on what is in db/schema.rb, and that will not have any initialisation data.

What I have done (and it may not be the best way) is to write setup methods in my models, which can be invoked from a console session. In this example, for a model called Role, defining the roles a user can have

  def self.setup_roles
    return false unless Role.find(:all).length == 0
    Role.create(:rolename => 'administrator')
    Role.create(:rolename => 'manager')
    true
  end

Note that the method fitrst tests to see if there are any roles present already, and only adds the default roles if not. In your tests you can invoke the setup method before a test to load in the data, and be sure that it is the same default data as in your development and production databases.

Struggling with Ruby: Contents Page

Single Table Inheritance

2008-10-23T22:01:00.003+01:00

Rails supports Single Table Inheritance (STI). In this pattern, the superclass is the only model with an associated table in the database, and any object of that class and any subclass is stored in that same table. Rails use a special column named "type" which stores the class name (this means that you will have problems if you name a column "type" for any other reason).

The Models
To implement, create the top level object as a model as normal (with generate scaffold works best for me), but include a column called "type" that is a string. You also need to include every column that all your subclasses will use (though you can, of course, add columns later, as normal).

For each subclass, create a model (again, I recommend generate scaffold). Modify the model so that the class inherits from the desired superclass, and delete the database migration. Migrate the database, and you are pretty much done.

See also:
http://wiki.rubyonrails.org/rails/pages/SingleTableInheritance
http://www.juixe.com/techknow/index.php/2006/06/03/rails-single-table-inheritance/

You can access all the objects in the class hierarchy through the top level class, or a specific class through other classes.

A < B < C < ActiveRecord::Base
C.find :all # Get all objects in the table, whatever the class
B.find :all # Get objects of type B only (not A)

Your superclass will need all the fields of all the subclasses - otherwise there will be no table column for field. Each subclass needs its own controller and map.resources entry in routes.rb.

Controllers and Views

So how does STI affect the controllers and the views?

Possibly not at all. You can have one controller for each model, all completely independant, all with their own set of views. However, there is a good chance that there will be some overlap. It is quite likely that you will want to use the same "show" view for each model, for example. Let us suppose SubClass is a subclass of SuperClass; the default show method is this:

def show
  @sub_class = SubClass.find(params[:id])
end

It is very easy to point the render method to the SuperClass view (remembering to rename the variable to what super_class/show.html.erb is expecting):

def show
  @super_class = SubClass.find(params[:id])
  render :template => 'super_class/show'
end

We can go a step further. If we set up SubClassController to inherit from SuperClassController, we do not need a show method in SubClassController at all; it can all be handled in SuperClassController. This will work without any changes to SuperClassController, but your object will be of the SuperClass type, and you will lose all the benefits of subclassing. It is better to instantiate your object as the subclass:

def show
  @super_class = eval("#{params[:controller].classify}.find(params[:id])")
  render :template => 'super_class/show'
end

Other methods for the SuperClass (destroy can be used as is):

def index
  @super_class = eval("#{params[:controller].classify}.find")
  render :template => 'super_class/index'
end

def edit
  @super_class = eval("#{params[:controller].classify}.find(params[:id])")
  render :template => 'super_class/update'
end

def create
  @super_class = eval("#{params[:controller].classify}.new(params[:#{params[:controller].singularize}])")
  if @super_class.save
    flash[:notice] = 'Record was successfully created.'
    redirect_to(:controller => 'super_class' , :action => 'show')
  else
    render :template => 'super_class/new'
  end
end

def update
  @super_class = eval("#{params[:controller].classify}.find(params[:id])")
  if @super_class.update_attributes(params[params[:controller].singularize.to_sym])
    flash[:notice] = 'Record was successfully updated.'
    redirect_to(:action => 'show')
  else
    render :action => 'edit'
  end
end

One last point. In your helps, instead of naming a model for the links, use polymorphic, eg, edit_polymorphic_path(super_class) rather than edit_super_class_path(super_class). This will make Rails point to the right controller for your subclass, whatever it might be.

Struggling with Ruby: Contents Page

The View Part 2 - Scope and Helpers

2008-10-17T18:42:00.010+01:00

Scope
There are significant limits to what you can access from a view.

For local variables, you can only access variables defined in that view (anywhere in the file, not just that section of Ruby). You cannot access local variables in the controller, or in another view (not even in the layout that gets processed with your view).

You can access instance and class variables in your controller, as long as they have already been defined in the respective method (I guess a new instance is created with each web request). You cannot access instance and class variables that you have defined by calling a method from the view (they will always be null).

Helpers
This brings us to helpers. Helpers are methods in modules that you keep mostly hidden out of the way. The idea is to keep as much Ruby code out of the views, so helpers are mainly for use in that context. Helpers are the only methods you can access, other than instance methods for an instance you have access to.

In the helper folder
You can put your helpers in the helper folder. Rails puts in a helper :all directive, which will automatically load any helpers it finds there, as well as creating an ApplicationHelper file, plus a helper file for each controller or scaffold you generate. In this configuration all helpers are available to all views, regardless of what file you put it in.

Helpers are set up just like any other Ruby method, the only difference being that the file is a module, not a class.

module ApplicationHelper
def project_name
'My Great Web App'
end
end

The file must be named in the format "_helper.rb", and the module named "Helper".

In the lib folder
Helpers can go into the lib directory, with a filename of the form _help.rb. Again, these are modules, not classes, and look just as before. You need to point Rails to the file, with this in the controller:
helper :myfile

Rails will then look for myfile_helper.rb, which should contain a module MyfileHelper.

In the controller
If you want to be able to access your helper methods in your controller too, your only option is to put them into the controller, and flag them as helpers.

To be able to access the methods, you need to put them in your controller (or application controller to allow all views and controllers to use them). the methods are set up as normal, but you need a "helper_method" macro at the top to register the specified methods as helpers.
helper_method :myfirstmethod, :mysecondmethod

Accessing Rails' helpers
You can use the helpers in Rails in your own helpers (at least in your helpers folder). For example, the following will set up a quick link to page, using the standard link_to helper.

def link_to_log
link_to 'Sample Log', { :action => 'home', :controller => 'samples' }, :method => :get
end

As an aside, I once had a method, select_options, in a controller that was used by several views, and worked fine. I decided it would be better in a helper, and so moved it across. It stopped working, the interpreter complaining there was no such method. Other methods in the helper file worked fine, even in the same view. After some head scratching, I decided that the problem was due to a name conflict; changing the name of the method got it working again. Why would it fail to find the method (as opposed to invoking the other method or complaining about the wrong number of arguments)? I do not know. However, should your view fail to find a helper method, this could be the reason.

Testing Helpers

Naturally you will want to test your helpers. You may be able to do this in your unit tests, but you may require the infrastruction that comes with a functional test - and anyway, helpers are for views/controllers, not models, so it makes more sense here.

Here are the bare bones of a test file:

require 'test_helper'

class AppHelperTest < ActionController::TestCase
tests SampleLog::GlcsController

include ApplicationHelper
include ActionView::Helpers::UrlHelper
include ActionView::Helpers::TagHelper

def test_link_code
  # code here
end
end

Note that it is necessary to specify which controller you are testing. It may not matter; just pick any. To get access to your new methods, include the helper class. To get access to other methods, include them too. In the above, I wanted access to link_to in ActionView::Helpers::UrlHelper, which in turn accessed escape_once in ActionView::Helpers::TagHelper.

For more on helpers see also:
http://api.rubyonrails.com/classes/ActionController/Helpers/ClassMethods.html

Edit: This page originally hada section on partials, however, partials have changed a lot in Rails 2.2.2, and most of it was no longer true. See this page:
http://strugglingwithruby.blogspot.com/2009/02/moving-to-rails-222.html

Struggling with Ruby: Contents Page

Deploying a Ruby on Rails Application

2008-10-09T21:25:00.005+01:00

I am in the process of developing a laboratory sample logging application, and before going to far down the road wanted to check it would work in the production environment. For development I am using WEBrick, MySQL and Ruby (1.8.6) with NetBeans (6.1), but the server has PostgreSQL, with Tomcat (which requires JRuby), so there are plenty of potential problems moving from one to the other. If you do not have Ruby installed, you still need to use "jruby " before rake.

Moving to JRuby and PostgreSQL
NOTE: I had a problem moving to JRuby, as I had Ruby installed as well, and I had not realised that "gem install " will install a gem to Ruby, rather than JRuby, and so I had a rather confusing time with gems installed in the wrong place. To install a gem specifcally on JRuby use "jruby -S gem install ", and to use rake and warble, likewise prefix the command with "jruby -S " The -S swich tells jruby to use its own version of the binary. See more here:
http://wiki.jruby.org/wiki/Getting_Started#How_do_I_run_rake.2C_gem.2C_etc

My first step was to install JRuby 1.1.4 on the server (JRuby already includes Gems), and then Rails (with: "jruby -S gem install rails -y --no-ri"). All very easy. Then I had to create a database server in PostgreSQL, which I did through the command line:
createdb mydb

I created a new project as normal in Rails, and modified the database.yml file to this:

development:
 adapter: jdbcpostgresql
 encoding: unicode
 database: mydb_development
 username: postgres
 password:
 host: localhost
 port: 5432

test:
 adapter: jdbcpostgresql
 encoding: unicode
 database: mydb_test
 host: localhost
 username: postgres
 password:

production:
 adapter: jdbcpostgresql
 encoding: unicode
 database: mydb_production
 host: localhost
 username: postgres
 password:

I chose to use JDBC, if you chose not to, just delete "jdbc" from the above.

Then I could use rake to create the databases ("jruby -S rake db:create:all"). Next I copied across the contains of the app and the db/migrate folders from my PC to the server, along with routes.rb (you might want other files from config too) and the stylesheets (I did not copy the tests; there seemed no point). I migrated my databases ("jruby -S rake db:migrate").

Then I installed the gem to handle database connections, either one, depending on whether you want to use JDBC or not:

jruby -S gem install postgres-pr
jruby -S gem install activerecord-jdbcpostgresql-adapter

At this point I could fire up the server, and check everything was okay (with "jruby script/server"), or use the interactive environment (with "jruby script/console").

So I had transferred to a different computer (though it could as well been the same computer, if I had been willing to install PostgreSQL on it) with a different database and a different Ruby; there were several issues that I have glossed over, but once you know what to do, pretty straightforward. No actual deployment yet though.

Moving to the Production Environment
To ensure the production database is used, in config/environment.rb uncomment this line:
ENV['RAILS_ENV'] = 'production'

To create the database tables in the production database:
jruby -S rake environment RAILS_ENV=production db:migrate

Warbler
I used Warbler to create a .war file (Warbler replaces GoldSpike). More information from here:
http://caldersphere.rubyforge.org/warbler/http://wiki.jruby.org/wiki/Warbler

Warbler is installed with:
jruby -S gem install warbler

By default, Warbler will package Rails, but no other gems. To change that (so the database connections are including), first create a config file using warbler ("warble config"). This creates a new file in your application config/warbler.rb. Edit the file to include the gems you require, or insert the following code to include all gems:

# From http://wiki.jruby.org/wiki/Warbler
# Include all gems which are used by the web application
require "#{RAILS_ROOT}/config/boot"
BUILD_GEMS = %w(warbler rake rcov)
for gem in Gem.loaded_specs.values
 next if BUILD_GEMS.include?(gem.name)
 config.gems[gem.name] = gem.version.version
end

Some other configuration setting can be found in tmp/war/WEB-INF/web.xml

Now create the .war file with:
warble
This should give the following output (if it has an mk command, then it is using Ruby rather than JRuby, I think):
jar cf mydb.war -C tmp/war .

Note that warbler requires access to a Java JDK, so you need that in your path (PATH=C:\Program Files\Java\jdk1.6.0_07\bin;C:\jruby-1.1.4\bin;%path%).

Moving to Tomcat
The .war file can then be dragged to the Tomcat webapps directory. You may need to restart Tomcat, but not necessarily. Tomcat will decompress the .war file and the web application can now be accessed with:
http://<servername>:8080/<app>

8080 is the default port for Tomcat. is the project name, which is the folder name for your application.

To replace an old version in Tomcat, you need to stop Tomcat, delete the directory with your project name (which Tomcat created by decompressing your old .war file), copy across your new .war, and restart Tomcat.

Overall it probably took me two to three times longer to deploy the application than it did to build the first draft of it, however, now I know what to do, it will be much, much quicker next time!

Struggling with Ruby: Contents Page

file_column

2008-10-03T18:49:00.008+01:00

file_column is a simple plugin that lets users upload images, which can then be displayed. There are alternatives out there; this was the first I found, but does the job so well I looked no further.

Download from here:
http://www.kanthak.net/opensource/file_column/

Install by dumping the files in vendor\plugins inside your project.

file_column does not work properly with more recent Rails. Modify file_column_help.rb

url = ""
url << request.relative_url_root.to_s << "/"
url << object.send("#{method}_options")[:base_url] << "/"

url = "/"
url << object.send("#{method}_options")[:base_url] << "/"

I think it allows for sub-domains and stuff like that, so is unnecessary in most cases. It fails as request (or @request) is nil. Why should that be?

Example

For a table called empire, with a column called image:

In the model, use something like this:

file_column :image, :magick => { :geometry => "200x100>" }

The magic bit uses RMagick to limit the size of the image.

In the new view, use something like this:

<% form_for(@empire, :html=> {:multipart=>true}) do f %>
<%= file_column_field "empire", "image" %>

In the show view, use something like this:

<%= unless @empire.image.nil?
image_tag url_for_file_column("empire", "image"), :align=>"right"
end %>

This will only display an image if one is entered in the database (though the file might still be missing). Note the align right option; this is not how it is documented; it should be done through a hash called option, but that did not work for me.

No changes in the controller.

Update: For Rails 2.2.2
Using this in Rails 2.2.2, I also had to make a change in file_column.rb, around line 619:

my_options = FileColumn::init_options(options,
                              Inflector.underscore(self.name).to_s,
                              attr.to_s)

Becomes:

my_options = FileColumn::init_options(options,
                              ActiveSupport::Inflector.underscore(self.name).to_s,
                              attr.to_s)

Update: Functional Testing
I found this quite a problem, with little guidance anywhere on the web as to what I should be doing. However, this is what I got working. The application is for a record of cylinder batches, each batch requiring a scanned certificate in PDF format.

test "should update cylinder_batch with file" do
 login_as 'manager', @request
 cb = CylinderBatch.find(:first)
 filename = 'LittleBookOfRuby.pdf'
 test_file = File.new("#{RAILS_ROOT}/test/fixtures/#{filename}")

 put :update, :id => cb.id, :cylinder_batch => { :certificate => test_file}
 assert File.exists? "#{RAILS_ROOT}/test/tmp/file_column/cylinder_batch/certificate/#{cb.id}/#{filename}"
 assert_redirected_to cylinder_batch_path(assigns(:cylinder_batch))
 cb2 = CylinderBatch.find cb.id
 assert_equal "#{RAILS_ROOT}/test/tmp/file_column/cylinder_batch/certificate/#{cb.id}/#{filename}", cb2.certificate

 get :delete_certificate, :id => cb.id
 assert !File.exists?("#{RAILS_ROOT}/test/tmp/file_column/cylinder_batch/certificate/#{cb.id}/#{filename}")
 assert_redirected_to cylinder_batch_path(assigns(:cylinder_batch))
 cb2 = CylinderBatch.find cb.id
 assert_nil cb2.certificate
end

The method is broken into three parts, the first setting up a few things, the second testing the update method with a new file, and the third part testing the delete_certificate method for removing a file. Usually I would only do one controller method per test method, but in this case one method sets up the other, while the other cleans up after the first, so this was more convenient.

I put a test file in the fixtures folders. This should be of the same type as you expect in your application. I tried using a YAML file, and while file_column would save the file, it did not update the table; I think file_column rejects file types it does not know. Also as a general point, be aware that file_column does not like anything besides letters, digits, underscores and hyphens in filenames.

In the parameters for the update method, I simply map the file to the appropriate column name. The file object contains the filename as well as the contents, and file_column can sort it all out. I then check that the file exists in the appropriate directory, the database has been updated correctly and the user redirected.

In the last section, after calling the delete_certificate method in the controller, I just check the file has gone, the database entry is nil and the redirect again. Simple. When you know how.

Struggling with Ruby: Contents Page

Ruby GUI

2008-09-13T14:10:00.004+01:00

I have been looking at how easy it would be to put a GUI front-end on Ruby. Ruby has no native support for a GUI (one place Java and C# really win over Ruby), and while Rails has become the standard for web aplications, there are numerous options for a GUI plug-in.

I have had a look at Tk, Fox and Swing (for JRuby). Recently, however, I found Ruby Shoes. Shoes is a very simple GUI, but that is part of its appeal. I doubt it has the comprehensive range of widgets that Tk does, for instance, but it can cope with JPEGs, which Tk cannot (as far as I could find). Also Shoes is dead easy to use:. Download. Install. Start the Shoes application, point it at your ruby file (or one of the samples included). Your application is runnning.

Unlike most other GUI toolkits, Shoes is not just a Ruby front end to an existing kit, which seems to make it feel more Ruby-like.

However, the big problem with Shoes is that there is no menu support incorporated. See this forum thread for a discussion on that:
http://www.ruby-forum.com/topic/165398

Find Shoes here:
http://code.whytheluckystiff.net/shoes/

My Quick Guide to Shoes

Everything in Shoes goes inside a Shoes.app block (usually, anyway). The simplest Shoes application is therefore

Shoes.app do
end

You can put in some options at this point - in a hash of course.

Shoes.app :title => "A Great Application", :width => 400, :height => 600, :resizable => false do

As usual, your require statements go at the very top of the file. Inside the Shoes.app block you can place the code that determines the GUI format and your methods.

Widgets are laid out inside either of two layouts, stacks for vertical stacking, and flows for horizonal flowing widgets. They can be nested for complex interfaces.

flow do
end

stack :margin_left => 5, :margin_right => 10, :width => 1.0, :height => 200, :scroll => true do
end

Note that the width in the second example is 1.0, i.e., 100%. You can assign the layout to a class variable, and then manipulate it later in a method for dynamic interfaces.

@gui_completed = stack
@gui_completed.clear

Flow and stack are not analogous. In the flow layouts, components fill a line, then go on to the next line, while in a stack, it is strickly one above the other. Shoes does not like horizontally scrollbars (neither do I). Sometimes components will stretch to fill the available room, and if they do that for a flow, they end up on the next line, and it looks more like a stack. The solution is to specify widths.

You can also use absolute positioning with :left and :top.

The background method set the background. If this is inside a layout, the background for the layout is set. The border method works the same

background white
background "back.jpg", :height => 40 # Set the top 40 pixels tan
border blue, :strokewidth => 5
background "#000".."#FFF", :curve => 15 # Gradient filled, black at the top
background "#000".."#FFF", :curve => 15, :angle => 90 # Gradient rotated 90 degrees anti-clockwise

You can use :width, :height, :right, :bottom to put different backgrounds along a certain side or corner. The :curve option should give your panel rounded corners, but not if you specify a border (note that the KNS manual says :radius; this is out of date).

You can manipulate your panels.

@my_stack.clear
@my_stack.clear { add_new_stuff }
@my_stack.append { add_new_stuff }
@my_stack.prepend { add_new_stuff }
@my_stack.before existing_component { add_new_stuff }
@my_stack.after existing_component { add_new_stuff }
@my_stack.remove existing_component
@my_stack.hide
@my_stack.show

Text can be done with: banner, title, subtitle, tagline, caption, para, inscription (in descending order of size).

title 'Here is my Application'
para 'some simple text'
caption "A caption, in red", :margin => 8
para strong('Some text in bold (like caption)')
para "Some fancy text", :stroke => red, :fill => yellow, :font => "Monospace 12px"

As well as accepting a string, these methods will also take arrays. You can use that to put in formatting within a line. In the second example, a link is created (looking as on a web page); click on it and the do_stuff method is invoked.

para ['Some text with ', strong('this'), ' in bold']
capture 'Please click ', link('here') { do_stuff }, '.' # Square brackets are optional

Options include strong, em, code, del, ins, link, span, sub, sup. It does not seem to cope well with characters outside the standard ASCII set. You can dynamically change content with the replace method.

You can change the style of a link (for the whole application).
style(Link, :underline => false, :stroke => 'red')

Text boxes can be done with edit_line or edit_box. The second example has some default text. The block gets invoked each time the text box is used, so @note will always have the text currently in the text box. How easy is that?

@text1 = edit_line :margin_left => 10, :width => 180
@text2 = edit_box "Default text", :width => 1.0, :height => 200, :margin_bottom => 20 do
@note = @text2.text
end

Buttons are easy too. When the button is pressed, the code in the block is invoked.

button("Add", :margin_left => 5) { add_todo(@add.text); @add.text = '' }
button "Swap" do
swap
end

There are some built in functions for dialog boxes:

ask("What is your name?")
confirm("Would you like to proceed?")
ask_open_file
ask_save_file
ask_open_folder
ask_save_folder
ask_color("Pick a Color")

Most components can be moved and resized

@comp.move(x, y)
@comp.size(w, h)

You can capture mouse movement like this:

motion do x, y
@o.move width - x, height - y
end

click do button, x, y
# button is 1for left button, 2 for right
end

Images are very easy, just use image, with the path to your image (plus style optins as required). Images can be changed on the fly by setting the path attribute (but why not have a replace method like there is for text elements?).

@little_image = image 'picture.jpg', :width => 50, :height => 50
@little_image.path = 'alternative.jpg'

You can even access the clipboard:

self.clipboard = ""

Shoes supports dropdown lists (list_box), checkboxes (check) and radio buttons (radio). see the manual included with the download for details. The big omission is menus, as mentioned earlier, but hopefully this will be rectified by the end of the year.

See also:
http://hackety.org/2008/06/12/martinDemellosGooeyChallenge.html
http://www.infoq.com/news/2007/09/ruby-shoes

Struggling with Ruby: Contents Page

Ruby Hashes

2008-09-03T18:13:00.015+01:00

Ruby uses hashes a lot to pass data around, and one reason for that is that they are just so easy to use. A hash is a object that contains a number of name-value pairs; a dictionary. A hash with a single entry is created like this:
h = {name1 => value1}

In practice, the name is usually a symbol, and the value often a string, so this would be the usual format:
h = {:name1 => 'value1'}

For multiple entries, separate with commas.
h = { :name1 => 'value1', :name2 => 'value2', :name3 => 'value3' }

In method calls the curly brackets seem not to be required or even desired. This can make it seem as though the method takes several parameters rather than a single hash; I think that is deliberate.

New name-value pairs can be added

h[:newname] = 'new value'
h.store :newname, 'new value'

Values can be accessed like an array:

value = h[:name1]
h[:name1] = 'new value'
h[:name1] = nil

Some web sites suggest the last of these will delete the entry; not so! To delete, use the delete method:

h.delete(:mykey)

However, accessing the key with the value is not trivial (as far as I can see). Here are two options:

h.invert[:value1]
h.find{ |k,v| == :value1 }[0]

To determine if a hash has a certain key, do this:

h.key? :my_key

You can loop through a hash with the each method. This example outputs each name-value pair (I believe the order is arbitrary).
h.each { |x,y| puts "Name #{x} Value #{y}" }

The delete_if method iterates through the hash and removes any entry for which the block evaluates to true. Note that as with the delete_if method in Aaray, this does not conform to the convention of an explanation mark for methoids that change the original.

Useful article:
http://www.informit.com/articles/article.aspx?p=26943&seqNum=3

By the way, Rails uses HashWithIndifferentAccess, which is special as it allows strings and symbols to be used interchangeably as keys when accessing values.

Struggling with Ruby: Contents Page

Dynamic Images on Rails

2008-08-22T22:29:00.011+01:00

You can serve images through a dedicated method (or action) in your controller, but to use the format facility, you need to register the MIME type. A lot of places say to do that in environment.rb, but leave you stranded after that. What is missing is the require you need in there too:

require 'action_controller/mime_type'

However, I now believe they are wrong (or perhaps out-of-date), and the correct place to put them is in (to ensure they work in the interactive environment):
config/initializers/mime_types.rb
For example:

Mime::Type.register "image/png", :png
Mime::Type.register "image/gif", :gif

In your controller, you can now do this (for the usual post controller example):

# GET /posts/1
# GET /posts/1.xml
# GET /posts/1.gif
# GET /posts/1.png
def show
 @post = Post.find(params[:id])
 respond_to do format
   format.html # show.html.erb
   format.xml { render :xml => @post }
   format.gif { render :text => @post.get_image_as_gif.to_blob,
            :status => 200, :content_type => 'image/gif' }
   format.png { render :text => @post.get_image_as_png.to_blob,
            :status => 200, :content_type => 'image/png' }
 end
end

This will respond to a request in four ways depending on the extension, serving up an image if it ends .gif or .png. The methods for creating the images go in Post.

To embed the image in the web page (note that pages can display slightly faster if you give the size and it is good practice to provide some alt text):

<%= image_tag formatted_post_path(@post, :gif),
        :size => "250x250", :alt => "Image title" %>

Using RMagic
RMagick is a Ruby interface for ImageMagick, and seems to be the biggest image drawing package for Ruby.
http://www.imagemagick.org/RMagick/doc/

Unfortunately, there is no documentation with it about using it with Rails, and precious little elsewhere. There is an example program, axes.rb, so by way of illustration, this is how to convert it for use in Rails.

1. Move the require 'RMagick' to the top of the file, as normal.
2. Wrap the program in a method, with def get_image_as_png (or whatever) at the top, and end at the bottom.
3. Edit the bottom from this:

labels.draw(canvas)
#canvas.display
canvas.write("axes.gif")
exit

To this:

labels.draw(canvas)
canvas.format = 'png'
canvas
end

If there is any problem with your code, Rails just refuses to send the image, with no error message anywhere I could find. If there is no image getting through, try using the interactive environment; it will not display images, but it will show the error messages.

Note that images have to be converted to blobs before sending. I have choosen to do that in the controller's show method above. Also, you do have to inform RMagick of your file format before invoking to_blob (get a "no decode delegate for this image format" error otherwise).

Some useful pages:
http://jeremyweiland.com/archives/49
http://nubyonrails.com/articles/dynamic-graphics-with-rails-1-2
http://macdiggs.com/2007/03/08/rmagickrvg-outputting-an-inline-image/

Colour names:
http://www.imagemagick.org/www/color.html

Using RMagick with FileColumn
FileColumn is a plug-in that makes it very easy to allow users to upload images to your site, and then display them. It uses RMagick, but this seems to lead to a name clash. I found it was necessary to use "include Magick" inside any model that I was using RMagick, rather than specifying Magick::Draw, etc., as Rails complained that the latter was un undefined constant in FileColumn otherwise. Strangely this was not the case in the controller.

Struggling with Ruby: Contents Page

Additional: If you use JRuby, you will need to use Jva to create images, see here. That page also explores in more depth how to access images in your views, relevant to RMagick images as well as Java.

The Model Part 4 - Testing

2008-08-18T22:22:00.009+01:00

Rails sets up the skeleton for unit testing when it creates a model. The skeleton is all set to run, though it does not actually test anything, with one trivial test case. However, there are a few steps of preparation:

Set up the "test" database
You need to do this whenever you make changes to the database (any time you do a migration basically). There is a rake task that will do this for you:
rake db:test:prepare

Note: Rake also supports db:test:clone and db:test:clone_structure; what db:test:prepare does is make a good guess as to which of those is best and does that.

Set up the fixtures
Rails generates a fixtures file for each model. A fixture is a file containing entries to populate the database before running each test. If you used the references type for any attributes in your model, you will need to have a belongs_to tag in your model, so that Rails will understand these to be my_model_id rather than my_model. You will get a SQL error otherwise complaining about an unknown column name.

Correct the require
If you are using NetBeans 6.1, you need to modify the require so Rails can find the test_helper file. require 'test_helper' should be require 'test/test_helper'. This has been corrected in NetBeans 6.5.

The default test should now work. In NetBeans you can right click in the file contents (i.e., the right pane), and choose test from the menu to just unit test a single file, or right click the project in the left pane and select test to run all unit tests.

Tests
Rails creates one test file for each model. I write one test method to test one use-case of a method, but I usually put in several assertions to check that the state is what I think it is before and after the method call.

Note that tests are run alphabetically. Also, be warned that if two tests have the same name, only one will be run, and you will receive no warning that one was not.

I find unit tests often involve significantly more code that the methods they test, and so most of the bugs are in the tests. However, once the bugs are gone, and the tests are passed, you do have a lot more confidence in your code. If you decide to rewrite the code, the tests should still work fine and are an excellent way to test your rewrite.

There is an issue with how comprehensive testing should be. If you have a method that manipulates a string, should you test if with nil, objects of a variety of other classes, string objects where the class has been modified? In Java or C# most of these are irrelevant.

Testing Exceptions
Use this:

e = assert_raise(RuntimeError) { my_code_that_raises }
assert_match(/Error message here/i, e.message)

From Jason Roelofs here:
http://groups.google.com/group/ruby-talk-google/browse_thread/thread/1553af54ab8beaf7

Testing Helpers
Not really models, but they can and should be tested the same. Helpers are modules, so you just need to include them. Here is how:

require 'test/test_helper'

class AppHelperTest < ActiveSupport::TestCase

include ApplicationHelper

def test_my_helper_method
end
end

Testing private and protected methods
t is just as important to test these methods, but how do you access them from outside the class? In Ruby it is actually very easy to access private methods using the send method. This will accept your method name (as a symbol), followed by the appropriate arguments. Something like this:

assert_equal 'My expected result',
  my_model.send(:my_private_method, arg1, arg2)

Tips
If you want to test your model with the parameters from a complex form, you can get Rails to build the hash for you. Throw an exception at the start of the controller method that will handle the submitted form, then, in your web browser, submit the form. Rails will hit the exception, and show an error page, which will include the POST data as a Ruby hash. Copy-and-paste into your test. Rails creates a special hash in which symbols and strings are equivalent for keys; chances are you will need to convert the strings to symbols (assuming you are accessing values with symbols).

There is an excellent series of blog pages on unit testing by Kevin Skoglund that starts here:
http://www.nullislove.com/2007/11/14/testing-in-rails-part-1-unit-testing-in-ruby/
For easy reference, part ten lists the assertions available here:
http://www.nullislove.com/2008/02/20/testing-in-rails-part-10-assertions/

Struggling with Ruby: Contents Page

The Model Part 3 - Interactive Rails Environment

2008-08-13T21:49:00.010+01:00

Interactive Rails Environment (IRE)
You can test the methods in your model in an Interactive Rails Environment (IRE), just like IRb. Navigate to your project's root directory, and type:

ruby script/console

In this environment you can access all your models, and the development database (the other databases can be accessed by appending "test" or "production" as a parameter to the above).

When you are in the Rails interactive environment, you can invoke reload! after modifying your code to get Rails to notice the changes. However, if you have an object on the go, it will lose its methods (at least, all your methods; methods inherited from, say, ActiveRecord::Base will still be there).

Here is an example session:

>> p = Post.find :first
=> #
>> p.test
test
=> nil
>> reload!
Reloading...
=> true
>> p.test
NoMethodError: undefined method `test' for #<post:0xafcd578>
from c:/ruby/lib/ruby/gems/1.8/gems/activerecord-2.1.0/lib/active_record/attribute_methods.rb:256:in `method_missing'
from (irb):4
>> p = Post.find :first
=> #<post>
>> p.test
test
=> nil

As can be seen above, the solution is to retrieve the object again after reload. The problem seems to be down to versions; the old object is an instance of the old version, which no longer exists.

See also:
http://www.spacevatican.org/2008/5/28/reload-me-reload-me-not
http://rpheath.com/posts/163-rails-tips-and-tricks-part-3

Struggling with Ruby: Contents Page

The View Part 1 - ERB and Links

2008-08-11T20:10:00.006+01:00

Rails uses the Model-View-Controller architecture. I have already discussed the model (here) and the controller (here); today it is the turn of the view.

The render method usually (depending on the parameters, as discussed with controllers) opens up a file, parses the file through ERB, and sends the result back to the requesting web browser. There really is not much more to it than that. The only complications are HTML and control structures.

As the web browser is expecting an HTML formatted page, your ERB template must be in HTML. Generally this is split between two files - the layout and the view itself - with the layout having the header and footer (both in the HTML sense, and the generic stuff at the top and bottom of all your pages), and the view having the HTML specific to that view. You really do need a good knowledge of HTML to do anything beyond the basics, but if you can cope with Ruby, HTML is dead easy.

ERB
ERB (embedded Ruby) is a template system built into the Ruby standard library, and used by Rails. It takes a template string, and where it finds certain codes will perform Ruby processing, substituting the output of that with the codes in the template. Here is an example IRb session using ERB:

require 'ERB'
template = ERB.new 'My template is called <%= @name %>'
@name = 'Fred'
puts template.result(binding)

The first line points the interpreter to the ERB.rb file (as this is in the standard library, not the core library). The second line creates a new ERB object called template. The last line calls the results method on template. The binding parameter gives the context so the template uses the value of @name from here, rather than some other method.

ERb supports a number of tags. Your Ruby code should go between the tags.

<% %> Perform the Ruby code; no output
<%= %> Perform the Ruby code; output the result
<%=h %> Perform the Ruby code; output the HTML escaped result
<%# %> Comment (note that unlike an HTML comment this is not visible to a visitor looking at the HTML source)

A % at the begining of the line can also be used to indicate that the line is ruby code (escape with %%). This appears to not be used conventionally. Also, <%% or %%> are replaced with <% or %> respectively, presumably to make it easier to write pages about ERb.

Actually, <%=h some_ruby_code %> is a bit of a trick. It is actually a method call, for the h method. It could be written <%= h(some_ruby_code) %>; it is just the same.

Reference
http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/

ERB and Rails
Rails already includes ERB, so the require 'ERB' is not required.

The layout file, pehaps application.html.erb, must include a call to the yield method, like this:
<%= yield %>

The yield uses the view file, perhaps edit.html.erb, parsing it with ERB, and inserting the result into layout result.

All this processing is done in your controller's superclass (ActionController::Base), so the environment used (the binding) is that of the method in your controller. ERB can access any variables and methods that you can inside that method.

Links
ActionController::Base includes some methods to help with links. The link_to method will generate the HTML code for a simple link, as in this example:

<%= link_to 'New post', new_post_path %>

"New post" is the text that will appear in the link. The method new_post_path will generate the URL on the fly (and will take into account the current URL; if the web browser is at http://mydomain.com/, your page will require a different URL to http://mydomain.com/posts/index).

As well as link_to there are also button_to, link_to_if and link_to_unless methods.

API for link_to (with links to alternatives)
http://www.railsapi.org:8100/actionview-helpers-urlhelper-link_to

Ruby Strings

2008-07-26T16:26:00.017+01:00

Java and C# take the view that strings are fundamental to the language and that API users should be able to rely on them doing exactly what is expected, and so the String class is set in stone, and each instance of String is immutable. Ruby takes the other road, allowing the user to do whatever he wants with a string. The Ruby way is certainly more convenient; whether there are security implications I am not sure (though unlike Java and C#, Ruby is not targetted at running within a web page).

API documentation:
http://www.ruby-doc.org/core/classes/String.html

There are a surprisingly large number of ways of defining a string in Ruby.

Double-quoted: Uses backslash escapes (like C, etc.), and embedding variables and code with #{some_code} (use \# for a hash).

%Q notation: %Q/My text/ is almost the same as "My text", or %Q[My text] or %Q@My text@ or whatever (not letters or numbers!). You can use a backslash to include your terminating chartacter, eg %Q!This is important\! Really it is.!.

Single-quoted: No escapes (except \' for a single quote). Single quoted strings require less processing than double quoted, though I suspect the difference is insignificant.

%q notation: %q/My text/ is almost the same as 'My text'.

Return
If you include a return in your string (i.e., it goes on to multiple lines), that gets converted into a return!

s = "First
Second"
p s # => "First\nSecond"

On Windows a return is \n (as in Java, and as opposed to C# which defaults to \r\n).

Concatenating and appending
Concatenation as in Java and C#

a = "first string" + " second string"
   # => a = "first string second string"
a += " third string"
   # => a = "first string second string third string"

But with an append method too.

a << " third string"
   # => a = "first string second string third string"

This is the more efficient way (+= creates a new string from the two parts).

Note that using << to add an integer between 0 and 255 adds the character (this is because Ruby does not have a character type as such).

a = "hello"
a << 72 # a is "helloH"

Adding other numbers generates an error. This is one place that Java and C# beat Ruby; they can cope with adding numbers (and indeed any class) to a string without an explicit conversion.

Repetition (how is that useful exactly?)

a = "repeated " * 4
   # => "repeated repeated repeated repeated "

Extracting bits
Extract characters as though it is an array

a[n]     # the nth character (starting from zero)
a[-n]    # the nth character from the end (starting from 1)
a[n..m]  # a substring from n to m (same as a[n,m]
a[n...m] # a substring from n to m-1
a[n]     # The ASCII value of the character
a[n].chr # The actual character

Note that a[n..m] is perfectly happy with variable names rather than specific numbers.

You can also replace chunks in a similar manner.

s = "Here is short string"
# => "Here is short string"
s['short'] = 'long'
# => "long"
s
# => "Here is long string"

It only replaces the first occurance, but can accept regex expressions.

Methods
A list of string methods from here:
http://www.wellho.net/solutions/ruby-string-functions-in-ruby.html

To change case:
capitalize - first character to upper, rest to lower
downcase - all to lower caseswapcase - changes the case of all letters
upcase - all to upper case

To rejustify:
center - add white space padding to center string
ljust - pads string, left justified
rjust - pads string, right justified

To trim:
chop - remove last character
chomp - remove trailing line separators
squeeze - reduces successive equal characters to singles
strip - deletes leading and trailing white space

To examine:
count - return a count of matches
empty? - returns true if empty
include? - is a specified target string present in the source?
index - return the position of one string in another
length or size - return the length of a string
rindex - returns the last position of one string in another
slice - returns a partial string

To encode and alter:
crypt - password encryption
delete - delete an intersection
dump - adds extra \ characters to escape specials
hex - takes string as hex digits and returns number
next or succ - successive or next string (eg ba -> bb)
oct - take string as octal digits and returns number
replace - replace one string with another
reverse - turns the string around
slice! - DELETES a partial string and returns the part deleted
split - returns an array of partial strings exploded at separator (eg, s.split(/_/) )
sum - returns a checksum of the string
to_f and to_i - return string converted to float and integer
tr - to map all occurrences of specified char(s) to other char(s)
tr_s - as tr, then squeeze out resultant duplicates
unpack - to extract from a string into an array using a template

To iterate:
each - process each character in turn
each_line - process each line in a string
each_byte - process each byte in turn
upto - iterate through successive strings (see "next" above)

One that I find partuicularly useful is split, which will break a string into an array of substrings, breaking at the characters you specify (either a string or a regex; defaults to whitespace):

s = "Here is a\nstring"
# => "Here is a\nstring"
s.split
# => ["Here", "is", "a", "string"]
s.split(/a|e|i|o|u/)
# => ["H", "r", " ", "s ", "\nstr", "ng"]

Also interesting is scan, which kind of does the opposite of split. Again it returns an array, but this time of the text that matches, rather than the text between the matches. This one example will return an array of links from an HTML document:

links = content.scan(/<a .+?<\/a>/i)

System commands
A back quoted string (eg `dir`) gets sent as a command to the OS. The system method in Kernal does similar (eg, system dir). You can also use %x[], for example, %x[dir].

Here Document
A "here document" is yet another form of string, designed for large one-off chunks of text (mm, not good for internationalisation). It is denoted by <<, followed by the terminator.

a = <<END
Some text
END

b = <<-NONSENSE
The hyphen allows the terminator to be indented
NONSENSE

do_stuff(<<TERMI, other_parameters
This text will all
go into the method as the
first parameter
TERMI

You can do operations directly on your here document, as shown here:

p(<<-EOS.reverse)
  This is my string
EOS
# => "\ngnirts ym si sihT  "

Formated String
You can also generate a formated string with the % operator, which is more or less equivalent to the sprintf method. One difference is that the % operator requires an array for multiple substitutions.

"%d" % 12
sprintf "%d", 12
   # => "12"
"x = %04d, y = %s, z = %.2f" % [12, "value", 1.234]
sprintf "x = %04d, y = %s, z = %.2f", 12, "value", 1.234
   # => "x = 0012, y = value, z = 1.23"
x = 1.12345
n = 2
"%.#{n}f" % x
sprintf "%.#{n}f", x
   # => 1.12

What is useful about this is that you can pass your format string around, and apply the subsitutions to it multiple times.

a = "x = %04d, y = %s, z = %.2f"
c = a % [12, "value", 1.234]
   # c is "x = 0012, y = value, z = 1.23"
c = a % [42, "other value", -11.2]
   # now c is "x = 0042, y = other value, z = -11.20"

Templates
From here:
http://freshmeat.net/articles/view/447/

This useful technique will go through the template string, substituting any occurance of something inside :::, with the string in the hash, values, as determined by the names in the hash
templateStr.gsub( /:::(.*?):::/ ) { values[ $1 ].to_str }

For more complex template usage, Ruby has ERB (see here).

Other Manipulations
Rails offers a variety of new methods for changing strings, including pluralize and tableize; methods used by Rails to convert between table names, class names and filenames.
http://api.rubyonrails.org/classes/ActiveSupport/CoreExtensions/String/Inflections.html

Here is a way to split camel case into title case:

"MyCamelCaseClassName".split(/(?=[A-Z])/).join(" ")
   # => "My Camel Case Class Name"

Struggling with Ruby: Contents Page