Book Review, "Pro Active Record"


BookReviewsRuby

Published by Apress
By Kevin Marshall, Chad Pytel, Jon Yurek
Book Info
Sample Chapter: Ch. 01 – Introducing Active Record
Table of Contents

Years ago when I was in PHP Land (now I travel quite a bit more! haha), I strugged for months with how to write a good ORM . It was tough, because I wanted to abstract the “boring logic” of retrieving records from a database without writing SQL but still remain flexible enough. I never really came up with a good model. I used the DAO from “extreme php” library which I think was a knock off from java. It was ok, but I still didn’t feel like I had “arrived”.

When I discovered Ruby on Rails, I found ActiveRecord. Ahh HA! Finally, this is what I was looking for. At first I thought it was part of Rails, but its not. Its a standalone library and you can use it with straight up ruby scripts.

I got a review copy of “Pro Active Record” some time ago and read it some when I got it, then some later, and now I am going to officially write up a review!

If you do anything with Active Record, get this book. The things that are briefly mentioned in most Rails books are described in detail in this book.

Chapter 1 – Introducing Active Record

Most of the time, the first chapters of a book are boring to me. I don’t need another “History of the Internet” or how “HTML was developed” … blah blah. But this one, the story is only 1 page. And it actually has some introductory scripts on using Active Record, so you can see right away how it works. It also explains the benefits of MVC and why ORMs are good. Some people still don’t get it!

Chapter 2 – Active Record and SQL

This chapter helps you translate the “sql in your head” to how to write it with Active Record. I’ve used Active Record so much that now I have forgotten most of my SQL, which is kind of embarrassing. :) I now find writing sql tedious and boring! I would have actually called this chapter “Demystifying Active Record” since it explains why all the dynamic finders work. You’ll also find transactions and locking explained here.

Chapter 3 – Setting up Your Database

Migrations! The Awesome Thing that can turn into a nightmare for large rails projects with multiple developers…. definitely have to decide on some best practices with your team on this one. The chapter has only one thing to say about this — assume any checked in migration has already been run by your team and the migration should not be edited and checked back in! You’ll have to make another migration file with your changes.

[tip]
Nola's Note: When you make a migration, test it both UP and DOWN!! Here's what I do --
write a migratiion
rake db:migrate (go up to the version with new code)
rake db:migrate VERSION=n-1, (go to version before the latest)
rake db:migrate (back to lastest)
rake db:migrate VERSION=0 (back to blank db)
rake db:migrate (back to latest)
[/tip]

Just to be sure its all good — even on a new database!

Chapter 4 – Core Features of Active Record

Now is the fun stuff – Callbacks. This is magic. This makes Active Record so flexible, and is one thing I could never figure out how to do with my PHP ORMs. I use call backs to set defaults for fields. If its just a straight default, then I set it in the database but if I need to make a decision, (if this field then this field..) then I can use it in a callback.

Associations – at first this is very confusing! I don’t know how many times I got “has_many” and “belongs_to” mixed around in the beginning.

Validations – Awesome. I had to do some ruby code without a database and I really really really missed the validations. It took me like 5x longer than it should! Understanding all of these validation methods will make your life so much more enjoyable. I really really hate doing boring, repetitive stuff…it seems so wasteful to me.

Chapter 5 – Bonus Features

Everybody likes a bonus and this isn’t even the last chapter of the book.

Java people will like the Active Record Observers — seems a little AOP to me (aspect orienteted programming) and something I probably have neglected to use to their fullest extent.

Acting up — Learn how to “save time” with the “acts_as” magic: List, Tree, Nested Sets. If your data needs these structures, you got it made. I can imaging how much longer it would take to write this stuff in perl or php.

Composed of – I haven’t used this, but this looks like a good way to make sensible objects out of database tables. There is quite a bit of explanation and examples of this, it will come in handy.

There are a few other in depth explanations of things, such as method_missing which is how alot of the magic happens. Rock on.

Chapter 6 – Active Record Testing and Debugging

Ahh yes, Testing. My favorite subject. My friends who know how much I love testing say I am sick. I must have an inner need to PROVE I am right or something, haha.

The chapter goes into depth about using test_unit with Active Record, sadly no RSpec. But, it does go into all the error messages that Active Record throws so you can write good try/catch blocks and make very exact error messages (probably best logged for the admin rather then displayed to the user!)

Chapter 7 – Working with Legacy Schema

Here’s how you work with that old database that just won’t die… or that management won’t let you totally redo. Active Record follows some of the principles of Rails “convention over configuration” … relying on table and column naming conventions to figure out how to build your object….but still giving you a way out if you want your tables singular and your primary id field called “myawesomeid” instead of “id”

I’ve used some of these things on an older database and it was possible! Not too bad if thats what you have to work with.

[soapbox]
Some people find this annoying "oh gosh! my library can't make decisions for me! OMG! That sucks" .. to that I say, "Umm ok. But if you follow these conventions then I can come into your project and know exactly what is going on" ... like with web standards, we all harp on how IE and FF do things differently, yet people want to bellyache about Active Record preferring to have plural names and id field called "id". Right.

Follow the dang convention and find something worth complaining about to complain about. :)
[/soapbox]


Chapter 8 – Active Record and The Real World

This chapter goes into depth about the library and encourages you to go read the Active Record code. Always a good idea to know what it is you are using :) I’ve actually learned ruby better by reading source code. The chapter walks you through basic structure of the files. Very cool.

[soapbox]
I used to work at a place that didn't like any "outside code" because they were afraid "OMG ... it will send our passwords to Russia!" ... ok, well I am not an idiot. I read over any code that I use that I didn't write. I look at the tests to see if I am using it right. I even RUN the tests so I can be sure its working as advertised.
[/soapbox]

Alternatives to Active Record – with EXAMPLES! If something about Active Record doesn’t set too well with you, take a look at the alternatives. Sometimes I look at the alternatives and decide that the first wasn’t so bad after all. You’ll find examples of DBI, Og, ActiveRelation.

Finally a section on Q and A finishes up this book. The Appendix has a complete reference of ActiveRecord methods to make this book a well rounded reference, tips, documentation and very handy to have at your desk!

HAML Tip


RubyTips and Tricks

So we were having an issue with haml and using a text-area output. It had indentation when it should not have and double indented after doing a save. A quick google search brought me to Ray Morgan’s Blog for the answer. Basically instead of using the = sign use a ~ and it will preserve whitespace. Thanks Ray. I am posting it here so I will remember where to find it if/when I forget what the answer was in the future.

Call Me! A quick how-to for getting dialable phone numbers in your Rails app.


RailsRubyThoughtsTips and Tricks

This might be something everyone knows but just in case I figured I would post a quick how-to on getting a clickable phone number in your Rails app. This example is only for the iPhone user_agent but you can make it work for other types as well as long as you know the user_agent.

Place the following code snippet in your application.rb file

 session :mobile => true, :if => proc { |request| Utility.mobile?(request.user_agent) }

  class Utility

    def self.mobile?(user_agent)
      user_agent =~/(iPhone)/i
    end
  end

Then in your view or your presenter code put a check for the session variable and if it is set then display the clickable phone number with the tel protocol in the href like so


"tel:#{contact.phone}"

and if its not set then just do things normally. Make sure you have the check there because if you don’t then when someone clicks the link in the browser it will complain about not understanding the tel protocol.

A Hello World for Ruby on Ragel 6.0


IntroductionsPythonRubyThoughts

This is an updated version of this tutorial. This updated version is compatible with Ruby 1.8 and Ruby 1.9, and Ragel 6.0. A version of this tutorial in Portuguese is available here.

By the end of this post, you’ll be able to turn a simple string “h” into the much longer and more interesting string “hello world!” using the magic of Ragel, all from the comfort of Ruby. Ragel is a very powerful state machine compiler and parser generator, which is at the heart of software like Mongrel and Hpricot. It’s able to generate C, C++, Objective-C, D, Java or Ruby code.

Ragel has excellent documentation provided by the author. My goal here is just to give you some context so that the documentation “sticks” when you read it, and to give you a working example which you can modify as you explore Ragel’s functionality. If you want to skip ahead, the full example is here.

The first step, of course, is installing Ragel. The Ragel home page has a Download section which lists ports for various platforms. If you already have Ragel installed, check that the version is 6.0 or higher. You can also compile and install Ragel from the source. Even if you don’t want to install from source it’s handy to have a copy of it to get some examples to play with. The subversion repository for Ragel is located here:

http://svn.complang.org/ragel/trunk/

As usual the test/ directory is your friend, also check out the examples/ directory. As per this thread, try searching for “LANG: ruby”.

When writing Ragel code, you create a file with a .rl extension. The .rl file is written in the “host” language, in this case Ruby, and the Ragel machine specification is embedded within the Ruby code using special delimiters. There’s actually no obligation to specify a state machine, so a perfectly valid .rl file is:

puts "hello world"

Don’t worry, I’m going to do a better Hello World than that, but this is a good place to start. To convert this .rl file into an executable .rb file, use the “ragel” command with a -R flag to indicate that you want Ruby code.

ragel -R hello_world.rl

This will create a file entitled hello_world.rb with the following contents:

# line 1 "hello_world.rl"
puts "hello world"

I’ll, er, leave executing that file as an exercise for the diligent student.

Ragel actually does this conversion in 2 stages. First it creates an XML file, then converts the XML to Ruby. If you want to view this intermediate XML then you can pass the -x flag in addition to the -R flag.

ragel -R -x simple_state_machine.rl > simple_state_machine.xml

Now, let’s write some actual Ragel. Start a new .rl file or download the example and read along. We’re going to create a machine which prints “hello world!” when it’s passed the string “h”, and does nothing otherwise. To indicate to the ragel compiler that we are writing instructions for it, and not Ruby code, we need to place our Ragel code within double-percent-sign-curly-brackets %%{ and }%% , or you can enter a single line instruction by just typing %%. (See page 6 of the User Guide.) Here’s our state machine specification:

%%{
  machine hello;
  expr = "h";
  main := expr @ { puts "hello world!" } ;
}%%

A quick overview of what’s happening here. The name of this machine is “hello” (Ragel makes us name it). It recognizes a single token, the string “h”. When it encounters that token, it performs (in Ruby) the action:

puts "hello world"

Now, if you were to run the ragel command on this file it would compile, but you would basically end up with a blank Ruby file. We have only specified the machine, we also have to tell Ragel to actually translate this machine into Ruby code using Ragel’s write statements. The first write statement we need to add is

  %% write data;

If you add this line after the state machine definition block, it will compile, as long as you remember to add a blank line afterwards. (After you’ve worked with parsers for a while you come to appreciate newlines in a whole new way.) After adding this line and compiling, you should have a rather significant Ruby file with lots of class << self statements all generated by Ragel. You don't need to study this code, at least not right now. It's pretty dull and ugly. And, if you run the ruby file at this point, you won't see any output.

There are 2 more write statements to add, and for convenience we're going to place them within a ruby method. The argument to this method is going to be the string we want to parse. Ragel expects to find a variable named "data" containing an array of ASCII codes, so we will need to convert our string to an array. This is done very easily in Ruby using the unpack method.

def run_machine(data)
  data = data.unpack("c*") if data.is_a?(String)
  %% write init;
  %% write exec;
end

write init tells Ragel that we want to generate initialization code for the state machine. The code Ragel generates here is:

begin
  p ||= 0
  pe ||= data.length
  cs = hello_start
end

The variable p keeps track of which character in the data string we are currently parsing, starting at 0. pe is an upper limit for p. cs stores the current state of the state machine, and here it is initialized to the starting state of the state machine. These variables are discussed in the User Guide.

write exec tells Ragel to write the meat of the parser (finally!). The code generated here will actually take an input (the data argument) and determine what the state of the system should be based on that input, executing any actions which might be triggered along the way. Let's add some puts statements so we can follow the code execution.

def run_machine(data)
  data = data.unpack("c*") if data.is_a?(String)
  puts "Running the state machine with input #{data}..."

  %% write init;
  %% write exec;

  puts "Finished. The state of the machine is: #{cs}"
  puts "p: #{p} pe: #{pe}"
end

Just add 2 more lines at the end to call run_machine with various arguments and then we can actually compile and run our state machine.

run_machine "h"
run_machine "x"

And here we go...

Running the state machine with input 104...
hello world!
Finished. The state of the machine is: 2
p: 1 pe: 1
Running the state machine with input 120...
Finished. The state of the machine is: 0
p: 0 pe: 1

It worked! Now, to help us interpret the values of p, pe and cs let's take a look at the state chart of this state machine. Ragel has built-in Graphviz support to create state charts. We need to use the -V flag instead of -R.

ragel -V simple_state_machine.rl > simple_state_machine.dot

If you render the resulting simple_state_machine.dot file in Graphviz, you should get something like this:

State Chart for Simple State Machine

We can see that the state machine has only one possible transition, from state 1 to state 2. When we passed "h" as the parameter to run_machine we did indeed end up with the variable cs (current state) equal to 2 at the end of our run. When "x" was passed, we ended up with cs = 0. 0 is the error state, indicating that an error occurred in the state machine. (You can tell that 0 is the error state by reading some of the variable assignments generated by write data, the code I said was dull and ugly.)

In the label 104/4:18 over the arrow transitioning from state 1 to state 2, the 104 corresponds to the ASCII code for the letter "h". (Type "?h" in irb.) The / indicates that an action is being performed, and 4:18 tells us that the action starts at line 4, column 18 of the .rl file. Had we given our action a name, that would have appeared here instead of the file position.

By the way, here's the (textmate-specific) shell script I use to run all these steps quickly:

ragel -R simple_state_machine.rl
ragel -V simple_state_machine.rl > simple_state_machine.dot
dot -Tpng simple_state_machine.dot > simple_state_machine.png
open simple_state_machine.png
ruby simple_state_machine.rb
mate simple_state_machine.out

Now, try running this code:

  run_machine "hh"

You should get:

Running the state machine with input 104104...
hello world!
Finished. The state of the machine is: 0
p: 1 pe: 2

You don't get "hello world!" twice. Sorry. Our state machine is only looking at a the first character we pass. It knows we gave it two characters, the variable pe = 2, but after it evaluates the first character it's in a final state. There's no arrow coming out of the state 2 circle. So, passing additional input results in the system entering the error state. If we want the entire data string to be evaluated, we need to make a small change to our machine specification.

main := expr+ @ { puts "hello world!" } ;

Endless Simple State Machine

(Try expr* instead of expr+ and see how the state chart is different.)

Now, try running this new state machine with inputs "hhh" and "hxh":

Running the state machine with input 104104104...
hello world!
hello world!
hello world!
Finished. The state of the machine is: 2
p: 3 pe: 3
Running the state machine with input 104120104...
hello world!
Finished. The state of the machine is: 0
p: 1 pe: 3

When we pass "hhh", we get a "hello world!" for each "h". When we pass "hxh", we get the first "hello world!", but when we hit the "x" we enter the error state, so the last "h" doesn't get evaluated.

Here's one more example, this time without defining a run_machine method:

  %%{
    machine hello_and_welcome;
    main := ( 'h' @ { puts "hello world!" }
            | 'w' @ { puts "welcome" }
            )*;
  }%%
    data = 'whwwwwhw'
    %% write data;
    %% write init;
    %% write exec;

Hello and Welcome State Machine

welcome
hello world!
welcome
welcome
welcome
welcome
hello world!
welcome

So, there you go. Hours of entertainment await you. We've only scratched the surface of Ragel's features here, but you should now be able to navigate through the User Guide without too much trouble. If you need a better reason than "fun" to play with Ragel, then bear in mind that parsers are a great tool for constructing Domain Specific Languages (DSLs), and state machines are magic code shrinking machines for situations where you need to keep track of the, er, state of something and control the transitions between states (i.e. business logic). I would highly recommend everyone to read this article about Ragel which inspired me to check it out. If you're into Rails, then take a look at the acts_as_state_machine plugin which might be more intuitive than Ragel at first. If the DSL angle is more your cup of tea then you might want to look at ANTLR instead, which has a different focus and feature set than Ragel.

Programming from the (under)ground up


ApprenticeshipIntroductionsRailsRubyThoughts

Hello. Welcome to my first article.

And my brand spankin new, made-from-scratch stab at programming. It’s going to be a bumpy ride: bumpy like fun-old-rollercoaster-bumpy not trainwreck-bumpy (universe willing).

Please allow me to rattle off some quick background facts so you know what planet I’m coming from. I’m a 26 year old retired bartender. I did that for more years than I care to say (ok fine, 8). I fancy myself an amateur artist; basically, I paint for therapy and fun. I’ve always liked things of a nerdy nature (i.e. writing very basic html in a webshell on angelfire when I was 13, Magic the Gathering, guys who majored in Astrophysics, etc). I consider myself very confident and intelligent, and it’s a shame that went to waste for so many years. That being said, years of bartending with no substantial plans for the future wore me out and made me feel quite desperate for awhile.

Then something changed. I got beat down so much by the universe’s way of telling me to stop f’ing around, that I got fed up with being fed up. Well, Desi McAdam happens to be one of my favorite people on the planet and a very close friend, and she had always offered to teach me programming…intensively. She and my other longtime friend/ROR evangelist Obie Fernandez had always told me they thought I’d be a great programmer. I didn’t know what they were talking about. So I called up my dear Desi and said “I’ll do whatever it takes. Let’s do this thing.”

I thought I was going to be learning in my off time while still bartending and getting tutored whenever Desi was in town. I knew this would take a very, very, very long time, but I felt ready for the challenge.

As it turned out, she and Obie were down here in Florida on the beach working with this fabulous guy Mark Smith. I had met him some weeks before, and we all had a great time together. They wanted to bring an apprentice on to the small team, so voila! Here I am. I am now in full on training starting with nothing but my instinctual and intellectual abilities and no experience. I am extremely grateful for the opportunity I have, and I intend to give back to Desi and Obie by trying hard to be a bad ass programmer.

Desi is putting alot of effort into being my personal, full-time tutor, and I think she rocks socks for it.

So I’m offering up myself, my victories, and my many future foibles here for your musing and amusement.

Cheers and enjoy