Publish Ruby gems to RubyForge in 10 minutes

What?

A quick tutorial to how to publish your ruby gems to the rubyforge gem listing in just under 10 minutes.

This is a fat-reduced version of nuby on rails' tutorial. Thanks for the great info!

Why?

You want to share your code, right? Sharing your ruby code is *really easy*!

How?

Using hoe. This assumes you already have a rubyforge account and a project approved. See https://rubyforge.org/account/register.php to set up an account and http://rubyforge.org/register/projectinfo.php to register a project.

Setup

sudo gem install hoe --include-dependencies

Set your environment EDITOR variable, if you haven't already. Edit ~/.profile or ~/.bash_login or equivelant, and put in

# ~/.bash_login
export EDITOR=/usr/bin/mate -w

Set up your computer to be able to talk to rubyforge. This will open a configuration file in your editor. Change the username and email

rubyforge setup

Log in to rubyforge

rubyforge login

Sow your project

For a project registered with rubygorge as object-stash you would do:

sow object-stash

This creates a directory object-stash with the files:

History.txt
Manifest.txt
Rakefile
README.txt
bin
    sparklines
lib
    sparklines.rb
test
    test_sparklines.rb

It will list in the command line what you need to fix in the auto generated files.

*Note* If your project name contains a dash - you will have to fix the the class name from "Object-stash" to ObjectStash in lib/object-stash.rb and Rakefile. A shortcoming of hoe, but a minor one.

If you want to auto-publish your documentation to the project main site, e.g. http://object-stash.rubyforge.org/, then edit Rakefile and add:

p.remote_rdoc_dir = '' # Release to root

Write your code

Add and edit files in lib

Release

Run

rake check_manifest

to make sure your Manifest file is correct. The lines with a - are listed in the Manifest but don’t exist on disk. The lines with a + are not in the Manifest but are on the disk.

*Note* Make sure the file ends with at least one blank line!

Now edit History.txt

== 1.0.1

* New version
 * Features

Update the version number in your ruby class files:

# lib/object-stash.rb
class ObjectStash
 VERSION = '1.0.1'
end

Release!

rake release VERSION=1.0.1

Publish your docs!

rake publish_docs

View docs and install your gem remotely

Go to your project's base url to view the docs, e.g. http://object-stash.rubyforge.org/.

Install your own gem! As easy as 1, 2,

sudo gem install object-stash

Skim - Potential OS X PDF Editor (Open Source)

Looking around for a PDF viewer that lets me annotate the document and doesn't suck, I ran into Skim, an open source PDF viewer and annotator for OS X. It has some obvious shortcomings (such as not being able to edit text), but it's ahead of all other contestants.

I wish it could but it can't...

• ... edit the document text
• ... export annotations such that other PDF viewers can see them

However, it...

• Underlines
• Highlights
• Strikes-through
  

And, like Preview...

• ... makes red ovals
  
  
  
  
  
• ... creates blaring yellow comment boxes
  
  
  
  

And, somewhat unnecessarily...

• ... Green Boxes!
  
  
  
  
  
  
  
  
  
  
• ... Icon notes! (Text appears if you double click)
  
  
  
  
  
  

The verdict

Better armored than Preview, but also more cluttered. Clearly the best alternative so far - however, no cigar. It seems to me like someone could make a name for himself cracking this nut. Takers...?

Full screenshot

Sequential Contracts in Ruby - Design by Contract Extension

What?

Software Designed By Contract is constructed along with terms of use and guaranteed behavior.

There are (at least) three types of contracts:

• Pre-conditional contracts specify conditions that have to be met before a function is used, e.g. the demand that a value passed into a function is greater than or equal to 0
• Post-conditional contracts specify conditions that are guaranteed to be be fulfilled after a functionality is used, e.g. ruby's Array#flatten! method guarantees that the resulting array is either nil or one-dimensional.
• Sequence contracts specify the sequence in which functionalities are allowed to be used. For example, a File class could specify the sequence File#open, multiple File#read's, File#close.
  

Why?

While documenting expected conditions gives the user of a software component an indicator what and what not to do, this cannot guarantee that conditions are actually met and can result in unexpected errors. Thus, we want a method to formally define contracts and ensure that they are met at run-time.

Ruby does not have built in support for contracts, but Ruby programmers Martin and Brian created a neat module for pre- and post-conditional contracts. However, it does not support sequential contracts. I recently had the need for sequential contracts in Ruby, and so decided to go ahead and implement it.

How?

To declare a sequential contract for a class, you first define the methods and then declare the sequence in which you expect the methods of any given object to be called. Let's say we have a Greeter class that creates conversing objects:

class Greeter

  def greet
    puts "Hello!"
  end

  def ignore
    puts "Pss!"
  end

  def ask_question
    puts "How are you?"
  end

  def talk
    puts "Blah blah blah"
  end

  def give_answer
    puts "Good thank you!"
  end

  def say_goodbye
    puts "Bye!"
  end

  def leave
    puts "Walking away..."
  end
end

Obviously, we would not want our greeter to first greet and then ignore you, or leave before it says goodbye. So let's declare a sequence contract after the methods of the Greeter class:

g = Greeter.new
g.greet

g.ask_question
# Must say goodbye before you leave!
g.leave

Now, if we create a Greeter and have it behave in a bad manner (e.g. ask a question without saying hello, or leaving before saying goodbye), then an IllegalSequence exception is raised:

# Declare a sequential contract
extend SequenceContract
  sequence_contract do
  start do
   transition 'greet' => :chat
   transition 'ignore' => :walk_away
  end
  state :chat do
    transition 'ask_question' => :chat
    transition 'talk' => :chat
    transition 'give_answer' => :chat
    transition 'say_goodbye' => :walk_away
  end
  state :walk_away do
   transition 'leave' => :done
  end
end

Together with test cases, the whole baddabing looks like:

require 'test/unit'
class TestSequenceContract < Test::Unit::TestCase

class Greeter
# Declare a sequential contract
include SequenceContract

def greet
 puts "Hello!"
end

def ignore
 puts "Pss!"
end

def ask_question
 puts "How are you?"
end

def talk
 puts "Blah blah blah"
end

def give_answer
 puts "Good thank you!"
end

def say_goodbye
 puts "Bye!"
end

def leave
 puts "Walking away..."
end

sequence_contract do
 start do
   transition 'greet' => :chat
   transition 'ignore' => :walk_away
 end
 state :chat do
   transition 'ask_question' => :chat
   transition 'talk' => :chat
   transition 'give_answer' => :chat
   transition 'say_goodbye' => :walk_away
 end
 state :walk_away do
   transition 'leave' => :done
 end
end
end

def test_illegal_sequence
  g = Greeter.new
  assert_nothing_raised do
   g.greet
   g.ask_question
  end
  assert_raises SequenceContract::IllegalSequence do
   g.leave
  end
end

def test_legal_sequence
  assert_nothing_raised do
   g = Greeter.new
   g.greet
   g.ask_question
   g.say_goodbye
   g.leave
  end
end

def test_multiple_instances
  g = Greeter.new
  assert_nothing_raised do
   g.greet
   g.ask_question
   g.say_goodbye
  end
  g = Greeter.new
  assert_raises SequenceContract::IllegalSequence do
   g.leave
  end
  assert_nothing_raised do
   g.greet
   g.ask_question
   g.say_goodbye
   g.leave
  end
end
end # TestSequenceContract

The SequenceContract module itself can be found here for now.

The computation beast awakens

More than a 100 years ago, Charles Babbage fathered the first abstract form of the computation beast into our world, in the shape of mathematics. This was the first modern day incantation of its primordial being.

. . .

Thirty years ago, you had to be able to count in hexadecimal (base 16) in order to make computers operate. Today, the everyday user has no idea these numbers provide the memory address to each and every little piece of data we use - your music, documents, programs and images.



Twenty years ago, you had to be able to use a teletype terminal to use a computer. Today we have personal computers with (sometimes) intuitive graphical interfaces, which we interacted with using a mouse or our fingers. Tomorrow we may do it by brain stimulus - already we have monkeys control robots and blind men seeing.


Ten years ago you had to know HTML in order to publish textual on the web. Today we blog, post videos, edit content and otherwise contribute with no technical knowledge beyond turning on a computer and using a web browser. Still, at the root of it all lie the hexadecimal representation of the binary, digital data that makes this all possible, from the transnational low of information to its pixelated display on your screen.


Today you have to spend years learning programming and various programming languages in order to create applications. At the root, however, programming is merely control and manipulation of information flow; tomorrow the technical threshold will be surmounted and programming will reduce to this (not less beastly) principle - complexity management through architectural and patterned structuring.

What I am saying is this: Computation is a beast of unimaginable capacity, and software its physical incarnation. Today, this beast is still in its early infancy, and we cannot predict or comprehend its mature form. Thus far, the technical threshold for participation in its development and nurture has been high enough to exclude all but the wiz and the nerd. However, technical literacy is on the rise, and with every human being a potential contributor to the most powerful tool of abstraction of human time we are in for exciting times.

Listen - you can hear it rumble...