E está no ar mais um PDF da série HOWTO, desta vez abordando o RDoc, marcação de documentação para códigos escritos em Ruby.

O RDoc é utilizado por quase todos os grandes projetos como Ruby on Rails e RSpec, dentre muitos outros.

Este guia de 17 páginas mostra como utilizar o RDoc, com muitos exemplos de formatação.

O PDF é gratuito pode ser baixado em http://howtocode.com.br/documentando-projetos-com-rdoc.

Não perca tempo e baixe já a sua cópia!

A primeira coisa que você precisa fazer é instalar a gem.

sudo gem install recurrence

Depois, basta adicionar à biblioteca.

require "rubygems"
require "recurrence"

A maneira mais simples de usar é instanciar um objeto através dos métodos de classe daily, weekly, monthly e yearly, que permitem criar eventos diários, semanais, mensais e anuais, respectivamente.

r = Recurrence.daily

Para retornar a próxima data, você deve utilizar o método Recurrence#next.

r.next
#=> Fri, 18 Dec 2009
 
r.next
#=> Fri, 18 Dec 2009

Você também pode utilizar o método Recurrence#next!, que altera a variável interna de data, como mostra o exemplo abaixo.

r.next!
#=> Fri, 18 Dec 2009
 
r.next!
#=> Sat, 19 Dec 2009

Se você quiser, pode especificar o intervalo de dias que o evento pode se repetir; basta utilizar a opção :starts e :ends.

# define the starting date to 2009-12-24
r = Recurrence.daily(:starts => Date.new(2009, 12, 24))
 
# define the ending date to 2009-12-31
r = Recurrence.daily(:ends => Date.new(2009, 12, 31))

Você também pode passar essas datas como strings, desde que elas sejam interpretadas pelo método Date#parse.

r = Recurrence.daily(:starts => "2009-12-24")

Os atalhos são uma excelente maneira de tornar o código mais semântico, mas em alguns casos é melhor seguir com o bom e velho método new.

r = Recurrence.new(:every => :week, :on => :saturday, :interval => 2)

Como você pode ver no exemplo acima, estamos criando um evento semanal, que acontece aos sábados, a cada duas semanas. Ao utilizar o método Recurrence#next! você terá algo como isso:

r.next!
#=> Sat, 19 Dec 2009
 
r.next!
#=> Sat, 02 Jan 2010

Você também pode especificar uma lista com os dias da semana que o evento deve ocorrer.

r = Recurrence.weekly(:on => [:saturday, :sunday])
 
r.next!
#=> Sat, 19 Dec 2009
 
r.next!
#=> Sun, 20 Dec 2009
 
r.next!
#=> Sat, 26 Dec 2009

Para acessar uma lista com todos os eventos disponíveis, basta utilizar o método Recurrence#events.

r.events
#=> [Sun, 20 Dec 2009, Sun, 27 Dec 2009]

Esse método fará irá guardar a lista de datas geradas, aumentando a performance se ele for acessado mais de uma vez. Se você quiser regerar essas datas, pode utilizar o método Recurrence#events!.

Também é possível verificar se uma data está no intervalo especificado no objeto Recurrence.

r = Recurrence.weekly(:on => :saturday)
 
r.include? "2009-12-19"
#=> true

Como usar na prática

Como você pode ver, o Recurrence é totalmente parametrizado. Essa abordagem permite que você armazene os itens necessários para montar sua recorrência em um banco de dados, por exemplo. Digamos que você tenha um modelo Event, com o seguinte schema:

class CreateEvents < ActiveRecord::Migration
  def self.up
    create_table :events do |t|
      t.string :title,        :null => false
      t.binary :meta,         :null => false
      t.date   :scheduled_to, :null => false
    end
  end
end

Os atributos que serão utilizados no Recurrence são :meta e :scheduled_to. O primeiro irá armazenar o tipo de recorrência e as informações como dia, intervalo, etc. Já o segundo, irá armazenar a próxima data do evento, para diminuir a geração de datas. O modelo Event pode armazenar os atributos como este exemplo:

class Event < ActiveRecord::Base
  serialize :meta, Hash
 
  validates_presence_of :meta, :title, :scheduled_to
end

Veja um exemplo de como cadastrar um evento “Pagamento”, que acontece todo mês no dia 5.

options = {:every => :month, :on => 5}
r = Recurrence.new(options)
 
event = Event.new(:title => "Pagamento", :meta => options, :scheduled_to => r.next)
event.save!

Na hora de montar o objeto de recorrência, você pode utilizar algo como isto:

event = Event.first
 
r = Recurrence.new(event.meta.merge(:starts => event.scheduled_to))
r.next
#=> Tue, 05 Jan 2010

Se você precisar exibir um evento mais de uma vez, utilize este mesmo processo e exiba os eventos com o método events.

Finalizando

Criar eventos recorrentes nem sempre é uma tarefa simples, principalmente no que diz respeito à performance. O José Valim fez uma série de contribuições que ajudaram a melhor esse ponto, além de outras funcionalidades como os atalhos.

Para conhecer mais sobre as opções disponíveis do Recurrence, acesse o README do projeto no Github.

Subject

O RSpec possui um método muito útil chamado subject, que retorna uma instância da classe que está sendo utilizada como contexto do exemplo.

describe User do
  it { should_not be_admin }
end

A grande vantagem desta abordagem é que você aumenta consideravelmente a legibilidade de suas especificações. Mas você não precisa utilizar apenas o contexto especificado no método describe; se quiser, você pode definir o seu próprio!

describe User do
  subject { User.new(:admin => true) }
  it { should be_admin }
end

Quando outros tipos de objetos (como módulos ou strings) são passados ao método describe, ele irá retornar o próprio objeto.

Message expectation

O método stub_chain

Sempre que você precisar fazer uma chamada encadeada e quiser verificar o último valor, utilize o método stub_chain. Ele permite transformar um bloco como este

describe "Mocks" do
  before do
    @user = mock()
    @things = mock()
    @recent = mock()
 
    @user.stub!(:things).and_return(@things)
    @things.stub!(:recent).and_return(@recent)
    @recent.should_receive(:count).and_return(100)
  end
 
  it "should return the recent things count from an user" do
    @user.things.recent.count.should == 100
  end
end

em uma coisa bem mais simples como esta

describe "Mocks" do
  before do
    @user = mock()
    @user.stub_chain(:things, :recent, :count).and_return(100)
  end
 
  it "should return the recent things count from an user" do
    @user.things.recent.count.should == 100
  end
end

O método and_return

Você alguma vez precisou acessar um stub mais de uma vez e queria que ele retornasse diferentes valores em cada chamada? Veja este exemplo.

require "open-uri"
 
class Dice
  API_URL = "http://www.random.org/integers/?num=1&min=1&max=6&col=1&base=10&format=plain&rnd=new"
 
  def roll
    open(API_URL).to_i
  end
end

Toda vez que o método roll for chamado, ele irá fazer uma requisição diferente ao http://random.org. Imagine que por algum motivo você precisasse retornar diferentes valores toda vez que o método open você invocado. Tudo o que você precisa fazer é retornar mais de um valor com o método and_return.

describe Dice do
  before do
    subject.should_receive(:open).and_return("1", "4", "2")
  end
 
  it "should not cache request" do
    subject.roll.should == 1
    subject.roll.should == 4
    subject.roll.should == 2
  end
end

O método with

O RSpec disponibiliza uma série de métodos que podem ser usados em conjunto com o método with. Veja alguns exemplos:

module Echo
  extend self
 
  def echo(*args)
    args.inspect
  end
end
 
describe Echo do
  # with any kind of argument
  specify("anything") {
    subject.should_receive(:echo).with(anything)
    subject.echo(1)
  }
 
  # with hash containing values
  specify("hash_including") {
    subject.should_receive(:echo).with(hash_including(:say => "hello"))
    subject.echo(:say => "hello")
  }
 
  # with an instance of String
  specify("instance_of") {
    subject.should_receive(:echo).with(instance_of(String))
    subject.echo("hello")
  }
 
  # with an object that responds to some methods
  specify("duck_type") {
    subject.should_receive(:echo).twice.with(duck_type(:<<))
    subject.echo(Array.new)
    subject.echo(String.new)
  }
end

Para ver mais exemplos, acesse https://gist.github.com/45b97f90a83c8acf3f29.

before e after globais

Muitas vezes precisamos preparar nosso ambiente antes de executarmos nossos testes. Quando isso precisa ser feito em mais de uma especificação, você pode diminuir a duplicação de código utilizando blocos globais.

No seu arquivo spec_helper.rb, você pode utilizar os métodos append_before, append_after, prepend_before e prepend_after.

Spec::Runner.configure do |config|
  config.prepend_after { `rm -rf some/path` }
end

Pending

Em vez de comentar temporariamente exemplos que você não quer que sejam executados, você pode utilizar o método pending. O método pending pode ser utilizado nos blocos de before. Assim, todos os exemplos daquele contexto de describe serão automaticamente marcados como pendente.

describe "Pending examples" do
  before do
    pending
  end
 
  # lots of examples
end

Você também pode deixar apenas um exemplo pendente.

describe "Pending examples" do
  it "should be pending" do
    pending "need to work on it"
    Env.setup!
  end
end

Ou apenas uma parte dele.

describe "Pending examples" do
  it "should be pending with a block" do
    pending("need to working on it as well") do
      Env.setup!
    end
  end
end

Uma outra alternativa (que não é deixar como pendente mas sim desabilitado) é utilizar o método xit em vez de it.

describe "Pending examples" do
  xit "should be pending with alias" do
    Env.setup!
  end
end

Matchers personalizados

Sempre que você perceber que está repetindo um padrão na hora de escrever seus exemplos, automatize o processo criando novos matchers. O RSpec possui duas maneiras diferentes de fazer isso. A mais simples delas é utilizando o método simple_matcher. Crie um módulo chamado TheAnswerMatchers para adicionarmos novos matchers.

module TheAnswerMatchers
  def be_the_answer
    simple_matcher do |given, matcher|
      # save some typing
      the_answer = "the Answer to Life, the Universe, and Everything"
 
      matcher.description = "be #{the_answer}"
      matcher.failure_message = "expected #{given.inspect} to be #{the_answer}"
      matcher.negative_failure_message = "expected #{given.inspect} not to be #{the_answer}"
      given == 42
    end
  end
end

Agora, basta fazer com que o RSpec reconheça esses novos matchers; é só incluir o módulo.

Spec::Runner.configure do |config|
  config.include TheAnswerMatchers
end

E para escrever seus exemplos, você pode usar o matcher be_the_answer:

describe "The Answer to Life, the Universe, and Everything" do
  specify { 42.should be_the_answer }
  specify { "the wrong answer".should_not be_the_answer }
end

Finalizando…

Como você pode perceber, é bem simples escrever exemplos melhores no RSpec. Se você olhar as specs do RSpec, encontrará bastante coisa legal que você normalmente não veria (porque tem muita coisa para ler) no RDocs.

E você, tem alguma dica para compartilhar?

Se você não pode comparacer, pode ver os slides

Gostaria de agradecer aos comentários positivos e, principalmente, aos organizadores. Keep on rockin’!

Após um ano e meio de WebCo e, eventualmente, Abril Digital, chegou a hora de continuar meu caminho. Há alguns meses eu já não me divertia fazendo meu trabalho e acho que isso foi uma consequência. Fiz grandes amizades; algumas ainda estão lá, mas muitas outras já saíram. Espero poder trabalhar com essas pessoas novamente no futuro; sem dúvida, é disso que mais sentirei falta!

Como a vida continua, estou disponível para projetos em período integral. Se você tem algum projeto interessante e precisa de um profissional de alto nível em sua equipe, entre em contato através do e-mail/Google Talk fnando.vieira@gmail.com. Aos que puderem encaminhar este post para pessoas que possam ter interesse em ter-me em suas equipes, um muito obrigado.

Em um dos slides eu disse que era possível ter algo como

def color(type=:hex, *values)
end

Obviamente, isso não funciona e eu falei besteira das grandes! Os valores que o splat irá agrupar, sempre excluirá o primeiro item definindo a variável type. Duhhhh… O que eu provavelmente queria ter dito era algo como isso

def color(type=:hex, value)
end
 
color(:rgb, [255, 255, 255])
color("#fff")

De qualquer modo, definir valores-padrão em qualquer ordem é uma funcionalidade interessante, mas que deve ser utilizada com cuidado!

Se você não pode assistir minha palestra, pode pelo menos ver os slides! :)

O PDF O que mudou no Ruby 1.9 pode ser comprado por apenas R$7,00. Aproveite pois é por tempo limitado e volta ao preço normal à partir de 16/10/2009!

PS: Infelizmente, tive que sair correndo na hora do almoço porque minha esposa, que está grávida, não estava passando bem e tivemos que correr para o hospital. Ela já está se sentindo melhor!

Acabei de publicar o próximo PDF da série HOWTO: O que mudou no Ruby 1.9.

Este guia de 50 páginas mostra o que foi adicionado no Ruby 1.9 e o que deixou de funcionar. O conteúdo é direto e sem enrolações, com muitos exemplos. A revisão do conteúdo foi feita pelo Luiz Rocha.

O PDF pode ser comprado por apenas R$10,00 e o pagamento pode ser feito pelo PagSeguro. Acesse http://howtocode.com.br/o-que-mudou-no-ruby-1-9 e veja mais informações.

Sem nenhum embasamento, sempre achei que o tempo excessivo se dava ao uso do Factory Girl, devido sua interação com o banco de dados. Hoje, decidi tirar a prova e fiquei surpreso com alguns números obtidos em um benchmark entre RSpec e Shoulda, como você pode conferir abaixo.

Preparando o ambiente

O primeiro passo, foi criar um aplicativo novo com apenas um único modelo chamado Post.

class CreatePosts < ActiveRecord::Migration
  def self.up
    create_table :posts do |t|
      t.string :title
      t.text :content
 
      t.timestamps
    end
  end
 
  def self.down
    drop_table :posts
  end
end

Antes de realizar o benchmark, foram executados os comandos rake db:migrate e rake db:test:prepare. Depois, foram criados branches específicos para cada um dos testes.

Foram realizados 4 tipos de teste:

• Shoulda com Factory Girl
• Shoulda sem Factory Girl
• RSpec com Factory Girl
• RSpec sem Factory Girl

Todos os testes acima foram executados no Ruby 1.8.7 (2009-06-08 patchlevel 173) e Ruby 1.9.1 ruby 1.9.1 (2009-07-16 p243 revision 24175) com Rails 2.3.3. Os tempos foram obtidos utilizando o comando time ao executar a rake task padrão com o comando time rake.

Veja abaixo como foram os testes realizados.

Shoulda com Factory Girl

A primeira medição foi feita utilizando Shoulda com Factory Girl. Para criar o objeto, foi utilizada a factory abaixo.

Factory.define :post do |f|
  f.title "Lorem ipsum dolor sit amet"
  f.content "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
            eiusmod tempor incididunt ut labore et dolore magna aliqua."
end
 
class PostTest < ActiveSupport::TestCase
  context "Post with defaults" do
    setup do
      @post = Factory(:post)
    end
 
    10_000.times do |i|
    should "do assertion #{i}" do
        assert_equal @post.title, "Lorem ipsum dolor sit amet"
      end
    end
  end
 
  context "Post with custom title" do
    setup do
      @post = Factory(:post, :title => "Lorem ipsum dolor sit amet FTW")
    end
 
    10_000.times do |i|
      should "do assertion #{i}" do
        assert_equal @post.title, "Lorem ipsum dolor sit amet FTW"
      end
    end
  end
end

Shoulda sem Factory Girl

Os testes sem Factory Girl utilizaram a abordagem de se ter um método para criar o objeto.

class PostTest < ActiveSupport::TestCase
  context "Post with defaults" do
    setup do
      @post = create_post
    end
 
    10_000.times do |i|
      should "do assertion #{i}" do
        assert_equal @post.title, "Lorem ipsum dolor sit amet"
      end
    end
  end
 
  context "Post with custom title" do
    setup do
      @post = create_post(:title => "Lorem ipsum dolor sit amet FTW")
    end
 
    10_000.times do |i|
      should "do assertion #{i}" do
        assert_equal @post.title, "Lorem ipsum dolor sit amet FTW"
      end
    end
  end
 
  private
    def create_post(options={})
      Post.create({
        :title => "Lorem ipsum dolor sit amet",
        :content => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
                    eiusmod tempor incididunt ut labore et dolore magna aliqua."
      }.merge(options))
    end
end

RSpec com Factory Girl

Para testar o RSpec com Factory Gir, foi utilizado o código abaixo.

describe Post do
  describe "with defaults" do
    before do
      @post = Factory(:post)
    end
 
    10_000.times do |i|
      it "should do assertion #{i}" do
        @post.title.should == "Lorem ipsum dolor sit amet"
      end
    end
  end
 
  describe "with custom title" do
    before do
      @post = Factory(:post, :title => "Lorem ipsum dolor sit amet FTW")
    end
 
    10_000.times do |i|
      it "should do assertion #{i}" do
        @post.title.should == "Lorem ipsum dolor sit amet FTW"
      end
    end
  end
end

RSpec sem Factory Girl

E aqui vão os testes escritos para RSpec sem utilizar o Factory Girl.

describe Post do
  describe "with defaults" do
    before do
      @post = create_post
    end
 
    10_000.times do |i|
      it "should do assertion #{i}" do
        @post.title.should == "Lorem ipsum dolor sit amet"
      end
    end
  end
 
  describe "with custom title" do
    before do
      @post = create_post(:title => "Lorem ipsum dolor sit amet FTW")
    end
 
    10_000.times do |i|
      it "should do assertion #{i}" do
        @post.title.should == "Lorem ipsum dolor sit amet FTW"
      end
    end
  end
 
  private
    def create_post(options={})
      Post.create({
        :title => "Lorem ipsum dolor sit amet",
        :content => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
                    eiusmod tempor incididunt ut labore et dolore magna aliqua."
      }.merge(options))
    end
end

Test::Unit com Factory Girl

class PostTest < ActiveSupport::TestCase
  def setup
    @post = Factory(:post)
  end
 
  10_000.times do |i|
    self.class_eval <<-TXT
      def test_assertion_#{i}
        assert_equal @post.title, "Lorem ipsum dolor sit amet"
      end
    TXT
  end
end
 
class PostWithCustomTitleTest < ActiveSupport::TestCase
  def setup
    @post = Factory(:post, :title => "Lorem ipsum dolor sit amet FTW")
  end
 
  10_000.times do |i|
    self.class_eval <<-TXT
      def test_assertion_#{i}
        assert_equal @post.title, "Lorem ipsum dolor sit amet FTW"
      end
    TXT
  end
en

Test::Unit sem Factory Girl

class PostTest < ActiveSupport::TestCase
  def setup
    @post = create_post
  end
 
  10_000.times do |i|
    self.class_eval <<-TXT
      def test_assertion_#{i}
        assert_equal @post.title, "Lorem ipsum dolor sit amet"
      end
    TXT
  end
 
  private
    def create_post(options={})
      Post.create({
        :title => "Lorem ipsum dolor sit amet",
        :content => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
                    eiusmod tempor incididunt ut labore et dolore magna aliqua."
      }.merge(options))
    end
end
 
class PostWithCustomTitleTest < ActiveSupport::TestCase
  def setup
    @post = create_post(:title => "Lorem ipsum dolor sit amet FTW")
  end
 
  10_000.times do |i|
    self.class_eval <<-TXT
      def test_assertion_#{i}
        assert_equal @post.title, "Lorem ipsum dolor sit amet FTW"
      end
    TXT
  end
 
  private
    def create_post(options={})
      Post.create({
        :title => "Lorem ipsum dolor sit amet",
        :content => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
                    eiusmod tempor incididunt ut labore et dolore magna aliqua."
      }.merge(options))
    end
end

Resultados

Antes de mostrar os resultados, quero dizer que fiquei extremamente impressionado com os resultados obtidos com Shoulda no Ruby 1.9.1; houve uma diminuição de pelo menos 5 minutos em relação ao mesmo teste executado no Ruby 1.8.7. No caso do RSpec, não houve diferença significativa.

O Test::Unit saiu em desvantagem nesse benchmark; para adicionar os testes, foi utilizado o método class_eval, que é uma operação bastante dispendiosa.

E se você não aguenta mais esperar pelos números, aqui vão eles:

Como eu jamais podia esperar, o Shoulda é o problema e não o Factory Girl! Embora eu acredite que a implementação do Shoulda seja infinitamente mais simples que a do RSpec, ela consegue ser muito mais lenta!

Pessoalmente, nunca usei o Shoulda em meus projetos pessoais. E, com certeza, não será agora que irei utilizá-lo!

Se quiser adicionar algum benchmark, veja o código utilizado nestes testes no Github: http://github.com/fnando/benchmark-rspec-shoulda/.

Update: Adicionei os tempos para os testes usando Test::Unit.

Strings

Existem cinco maneiras diferentes de se definir uma string no Ruby.

string = "Ruby is awesome!"
string = 'Ruby is awesome!'
string = %q(Ruby is awesome!)
string = %Q(Ruby is awesome!)
string = <<-TXT
Ruby is awesome!
TXT

O que difere uma das outras é a capacidade de se interpolar código Ruby na string.

lang = "Ruby"
 
puts "#{lang} is awesome!"
# => Ruby is awesome!
 
puts '#{lang} is awesome!'
# => #{lang} is awesome!
 
puts %Q(#{lang} is awesome!)
# => Ruby is awesome!
 
puts %q(#{lang} is awesome!)
# => #{lang} is awesome!
 
puts <<-TXT
#{lang} is awesome!
TXT
# => Ruby is awesome!

Arrays

O Array também possui formas diferentes de instanciação.

items = ["Ruby", "is", "awesome!"]
items = %w(Ruby is awesome!)
items = %W(Ruby is awesome!)

E de forma similar, a diferença entre as duas últimas formas é a interpolação de código Ruby.

lang = "Ruby"
 
items = %w(#{lang} is awesome!)
# => ["\#{lang}", "is", "awesome!"]
 
items = %W(#{lang} is awesome!)
# => ["Ruby", "is", "awesome!"]

Expressões regulares

Expressões regulares podem ser definidas de três formas diferentes.

regex = /ruby/sim
regex = %r(ruby)sim
regex = Regexp.new("ruby", Regexp::MULTILINE|Regexp::IGNORECASE|Regexp::EXTENDED)

Não existem diferenças na execução das expressões regulares; na prática, se sua expressão possui muitas aspas, é interessante usar o atalho %r().

Comandos Shell

A execução de comandos Shell pode ser feita de três maneiras diferentes.

`pwd`
%x(pwd)
system "pwd"

A única diferença prática é que o método system irá enviar o resultado para STDOUT, enquanto %x(pwd) e `pwd` irão retornar a resposta da execução.

Lembra aquela pesquisa que fiz há um tempo atrás? Este é o resultado! Acabei de publicar o primeiro PDF de uma série chamada HOWTO: Rails Application Templates.

Neste tutorial você aprenderá como criar templates para personalizar seu aplicativo e evitar todo aquele trabalho manual e chato de aplicativos criados do zero.

Como ainda estou estudando a melhor forma de gerar e gerenciar o conteúdo, iniciei com uma publicação mais simples e, o que é melhor, totalmente gratuita!

Para fazer o download, acesse http://howto.simplesideias.com.br/rails-application-templates