H3RALD - Tag 'ruby' (RSS Feed)

Glyph 0.4.0 Released

h3rald@h3rald.com — Fri, 03 Sep 2010 17:45:00 -0000

This new release of Glyph introduces an unusually large number of features, improvements and bugfixes. Not so much in terms of new macros maybe (no index or bibliography support for now, but it will come, don’t worry!), but rather… pretty much everything else!

Web Output

By far the biggest feature of this release is support for multi-file output, i.e. the possibility to transform your book into a web site. You’ve asked for it, I needed it too, and now it’s finally here.

An example? Sure. Take the Glyph Book (now a 98-page PDF file) for instance. My only regret was that a long PDF is quite heavy to digest and peruse, especially if you’re in a hurry. It would be so much nice to have it available online, in chunks of more manageable size.

Well, here it is. That’s the very same document, split in several HTML files with a custom layout that matches this site’s. The good news is that you can do it too:


section[
  @title[This title is compulsory]
  @id[random_section]	
  @src[topic_file.glyph]
]

Note the @src attribute? It basically includes the specified topic file. So by creating a document.glyph file like this, you can create a tidy table of contents (not a single include macro) and get a website for free. Glyph, as usual, takes care of anything for you, especially links between topics. Just link away like you did so far, nothing changes from previous versions, it will just work as expected (read more).

HTML5 Output

Compared to Web output, HTML5 support was trivial and only took a few hours to implement and test. You can now produce single-file HTML5-compliant documents (html5 output format) or even HTML5-compliant web sites (web5 output). Just using section tags instead of div tags made it worth it.

Of course, the default CSS files have been updated to be compatible with HTML5 output too.

Project Statistics

Anoher big thing was a shiny new command, glyph stats, which brings — guess — stats. No more chasing after bookmark references, just type glyph stats --bookmark=#web_output and you’ll know where the #web_output bookmark was defined and what links to it. Similar stats are available for:

macros
links
files
snippets

glyph stats -m tells me that I used 3236 macro instances throughout the Glyph book. Just so you know.

Custom tasks and commands

“Glyph is extensible”, “Glyph lets you create your own macros”, …great, but kinda limited right? No more. Glyph now lets you create custom Rake tasks and even custom commands.

Have a look at this page for more information on what you can do and how. You can now extend Glyph in any way you like (including adding custom output formats) without having to touch its core, just do it within your own project.

wkhtmltopdf

Last but not least, you no longer need Prince XML to produce PDF file. Granted, Prince is awesome and the PDF it produces are very, very nice… but if you want to produce PDFs commercially and want to same some money, you can now use wkhtmltopdf: it’s free and open source, and it keeps getting better and better.

...and more to come!

After this release I’m going to take a small break from Glyph. Nothing major, I just want to redesign my site (again) and find the time to write a proper Glyph tutorial. This doesn’t mean that development will be halted or anything, just that it will take a few months for Glyph 0.5.0 to come out.

Meanwhile, there may be bugfix releases (depends how many bugs turn up). It would be a good time to come out of the closet and propose/vote on new features!

Hope you enjoy using Glyph 0.4.0, and if you need anything or feel social, remember that the doors of the Glyph User Group are always open!

Book Review: Distributed Programming with Ruby

h3rald@h3rald.com — Tue, 22 Jun 2010 11:30:00 -0000

Back when I read ‡‡‡‡‡PLACEHOLDER¤1‡‡‡‡‡ for the first time, I distinctly remember a short reference to DRb, the Distributed Ruby library included in the Standard Library.

“Cool!” — I thought

…and that was pretty much it. The documentation for DRb was pretty much nonexistent (at the time), I didn’t need it, so I pretty much forgot about it altogether until this book came out.

Distributed Programming with Ruby fills a very particular niche of the Ruby programming world: distributed programming. Moreover, this book is somehow justified by the scarce documentation on the subject:

Although these libraries [DRb and rinda] have been included with Ruby for many years now, they have received little or no attention (or documentation). This has led to a lot of FUD
(fear, uncertainty, and doubt) about what these libraries can and cannot do, and when they are appropriate to use (if at all).

— Mark Bates, Distributed Programming with Ruby

But there’s more. This book gives the reader a complete overview of what’s out there, in the Ruby world, to support distributed programming. This includes quite a few gems and libraries besides the ones provided in the standard library.

Overview

The book is organized into four parts, each dealing with a particular set of Ruby libraries related to distributed programming.

The author, Mark Bates, does a good job maintaining a sort of continuity in the examples throughout the book: you’ll get accustomed to a Logger class of some kind being punctually re-implemented more or less once per chapter, using a different library.

Additionally, the libraries described in the book are ordered by “reverse preference” in each part of the book, so normally the libraries described later on in a part fix some of the shortcomings of the preceding ones.

Part I: Standard Library

This part is the most important of all: it gives you the very basics about Distributed Programming and it describes the “building blocks” (DRb and Rinda) used in nearly all the other libraries described in the book. If you want you can skip some chapters in the other parts of the book, but make sure this part is crystal clear in your head before proceeding any further.

Part II: Third-Party Frameworks and Libraries

If you read part I, you’re probably a bit disappointed by DRb and Rinda and the amount of code you have to write to make simple things work in a distributed environment. The good news is that there are some Ruby gems out there that can make life simpler:

Part III: Distributed Message Queues

In this part, the author introduces more in detail the concept of distribute message queues, and also the technologies and protocols available not only in the Ruby world but elsewhere. It focuses on two libraries:

Starling, originally used by Twitter.
AMQP, an implementation of the AMQP protocol in Ruby, that can be used in conjunction with RabbitMQ, an Erlang-based messaging system.

Part IV: Distributed Programming with Ruby on Rails

The book ends somewhat abruptly with this last part that deals with distributed programming in the Rails world. It feels a bit like a last-minute addendum that I would have left for an appendix, nevertheless it briefly introduces BackgrounDRb and Delayed Job.

Technical Analysis

Unlike other technical books, this one can (must?) be read sequentially. Generally each chapter focuses on a library, describes how to install it and use it, and highlights its pros and cons. Typically, the “cons” are solved in the following chapter by another library, and so on…

The book is not meant to contain a full technical reference of each library, and it’s quite short (256 pages), so you really get the most out of it if you read it all, from start to finish. I didn’t realize there were so many different libraries in this particular niche of Ruby programming, and Mark does a good job demistifying some of them.

One thing that really struck me out of this book is the focus on gems. We’re not talking about mainstream frameworks like Rails or Merb here, but rather of some rather specialized, smaller libraries that fullfill very specific tasks. Personally, I don’t remember any other Ruby book doing this in the same way, and I was quite happy about it.

On the other hand, gems are a double-edged sword: while some of them are really cool and well-maintained, others may disappear tomorrow with no prior notice. I was actually very surprised to see even some of the quirks of these gems documented in the book:

p91: “Notice that we added client { } to the bottom of the server file. The reason for this appears to be a bug or flaw in the Starfish architecture.”

Really? Hasn’t it be fixed now? Apparently not, that’s the way it works, so no, you can’t blame the author of the book for this.

Formatting and Readability

As I pointed out earlier, this book is somehow meant to be read sequentially, and Mark does a good job making sure you don’t get bored. Chapters and sections are quite short and there’s a good text/code ratio: the examples are short and clear, and you don’t have to try them out yourself, because most of the time the author does it for you. It’s not infrequent for the author to tell you to run “wrong” code, but that’s a great way to show you how to do the right thing right afterwards.

Sidebars and boxes are used properly and they do provide actual value-added content: some information on a non-Ruby technology, some tips and tricks on how to run things smoothly, etc. On the other hand, one thing I couldn’t stand were the endnotes. I must say I don’t like endnotes at the best of times, but when they are pointless I just can’t suffer them. Each chapter has its own fair share of endnotes, but unfortunately most of them are just URLs to Wikipedia pages or RubyForce/GitHub projects: I would have preferred the URLs inline with the rest of the text, but that’s just me.

Style and Contents

Mark has a nice, informal writing style. Exactly what you expect from a programming book nowadays, even if sometimes it feels a bit too informal:

p86: “I think I understand what Eric means by all that. However, that is as deep as the documentation goes on the subject. I have not been able to test what I think he means, so I won’t make any grand promises about what the library can and cannot do in regards to expiring/renewing registrations.”

Although this is not something you’d see in a professional book everyday, it definitely helps to connect with the reader: Mark is one of us after all, even if he happens to have created quite a few interesting projects, like the Mack framework, the Distribunaut library (which is also mentioned in his book, but in a very impartial way) and Configatron. From his book you understand that he’s neither one of those rockstar developers nor one of those famous authors who just writes books for a living: he’s a competent programmer who knows quite a bit about a particular, but relevant, niche of Ruby programming.

Final Thoughts

This is one of those books I’d like to see a second edition of. Partly because there are some relatively new gems which have been left out (BrB, for example), partly because this is a rather hot topic at the moment, and different solutions are popping out at a rather extreme rate.

The decision to write about mainly about gems was bold but necessary, and I’d really like to see more authors doing that, but with extra care. From reading this book, you understand that there’s no silver bullet when it comes to Distributed Programming, but rather different tools to do different jobs.

The thing I missed the most? A proper conclusion to the book. You’re left with two chapter about Rails-specific libraries which could have easily become appendixes, and nothing else. I would have liked a sort of “summing up” end chapter (re-)highlighting the pros and cons of each library and a sort of feature matrix.

Nevertheless, it was well worth my time and it proved to be a very good resource to get started in writing distributed Ruby programs.

Glyph 0.3.0 Released

h3rald@h3rald.com — Sun, 13 Jun 2010 12:10:00 -0000

The third release of Glyph is out!

For those checking it out for the first time, Glyph is a Rapid Document Authoring Framework focused on extensibility and content reuse. For an example of what Glyph can do, have a look at Glyph's free PDF book.

This release brings more stability to Glyph, more speed, and features affecting Glyph's core functionality. As a consequence, some incompatibilities had to be introduced – but after all, better now than later.

New parser and performance improvements

This release's big news is the brand new Glyph Parser. Until this release, Glyph relied on the awesome Treetop library for parsing Glyph language. Treetop is great when it comes to creating language parsers effortlessly, but it can add quite a bit of an overhead especially when using dot star patterns.

So I ran a few benchmarks and in the end decided to write my very own (first!) parser from scratch using just the StringScanner class, which is part of Ruby Standard Library. It took me a bit to get used to it, but in the end I managed to create something able to produce an Abstract Syntax Tree exactly the way I wanted.

After adding the new parser, Glyph became significantly faster. This doesn't mean it's as fast as, say, RedCloth, but I it can be used to process long books in just a few seconds rather than minutes.

Macro Attributes

Glyph now supports named attributes as well as positional parameters. This is particularly handy when you want to create macros with a lot of optional arguments: in this case, positional parameters are not great. As a result, for example, the section macro now takes an optional title and id attributes, rather than two parameters

Attributes look like macros, but they all start with a @ character. For example, see the the following image, showing this very section:

Full XML support

Once macro attributes became available at parser level, having Glyph to produce arbitrary XML code became extremely easy. By default, now if Glyph doesn't find a macro it assumes you're inputting an XML tag of some kind, so you can write:

p[This is a paragraph with some em[emphasized] text.]
img[
  @alt[Glyph Code]
  @width[50%]
  @height[50%]
  @src[glyph_code.png]
]

And get the following HTML code back:

<p>This is a paragraph with some <em>emphasized</em> text.</p>
<img 
  alt="Glyph Code"
  width="50%"
  height="60%"
  src="glyph_code.png"  
/>

...and none of the macros used in the previosu Glyph code snippet are actually defined in Glyph. Among other things, this means that you don't have to use Textile or Markup within your Glyph code unless you absolutely need to (e.g. for lists, which would be a bit verbose to create using just Glyph markup).

Improved `include` macro and "safe mode"

The include macro now must take an path to a file relative to the text/ directory of your project, or it can also be used to include (and evaluate) ruby code within your lib/ directory. Moreover, you can now use the include macro even when compiling single Glyph files.

Now, while evaluating Ruby code in an external file can be quite handy, is also quite insecure. For this reason, it is now possible to use Glyph programmatically in "safe mode", thereby forbidding the usage of certain unsafe macros.

What's next?

Sooner or later I'll have to implement support for generating multiple files in output. This would make it possible to make the Glyph book available online as a collection of separate HTML file, for example, or, later on, maybe even compiled into a (ugh!) CHM file.

Additionally, HTML5 support is also on the horizon: given the current Glyph architecture, it will be relatively easy to have Glyph macros to produce HTML5 code instead of XHTML. LaTeX support, on the other hand, is a completely different game, mainly because I'm not familiar with it, so if anyone feels creative and would like an easier way to produce reusable LaTeX code, get forking and contact me!

Glyph 0.2.0 Released

h3rald@h3rald.com — Sun, 09 May 2010 15:00:00 -0000

I am very pleased to announce the second release of the Glyph Document Authoring Framework. For those who don’t know, Glyph is a pure-Ruby, extensible solution to author documents like books or articles using a simple, fully-customizable markup language.

Since the first release, came out, last month, a lot happened. Plenty of bugs were fixed and new features implemented, as shown by the changelog. Here’s a brief rundown of the most notable changes.

What Glyph code looks like

Earlier this week I blogged about my new Glyph vim syntax file. I’ve been using it for a while, and all I can say is that it really helps! Here’s what it looks like:

I’m sorry for the Emacs and TextMate folks, but I only use Vim, so I only made a Vim syntax file. Anyhow, Glyph grammar is very simple, so rolling out your own syntax file for your favorite editor shouldn’t be too hard.

Notable features

Single-file compilation

Perhaps the most life-changing feature in this release is the possibility of compiling a single Glyph source file into an HTML or PDF file. This means you no longer need to create a full-blown project for writing a short article: just create a file anywhere and run glyph compile filename.glyphon it!

The good thing is that with this new release you can also define snippets, configuration settings, and even macros right into your Glyph files, so you can do almost anything without having to create a project or fiddle with YAML files.

Programmatic usage

The second most notable feature is the possibility to use Glyph as a Ruby library, i.e. as you’d use a filter like RedCloth or MarkDown. Additionally, it is also possible to compile single files programmatically, so you can, for example, create PDF files for your articles from the same source file. Don’t believe me? Feel free to click the Download PDF and View Source links on this very page to see for yourself…

For those of you using the awesome nanoc static site generator, here’s a few source files you may want to take a look at:

lib/glyph-data.rb — How to update configuration settings.
lib/glyph-data.rb — a simple Glyph filter.
Rules — a rule using the Glyph#compile method to generate PDF files.

Auto-regeneration

Another very interesting feature is the possibility to auto-regenerate your output files automatically whenever a source file is changed. Just run glyph compile --auto and you’re away. I’d like to thank Sebastian Staudt for proposing, implementing, and testing this feature.

Conditional macros

Finally, although it may worry some, I added the possibility to evaluate conditional expressions directly in Glyph. The syntax is a bit verbose due to the extreme simplicity of Glyph parser, but it does the job:

?[and[ eq[$[document.output]|pdf]| eq[$[tools.pdf_generator]|prince] ]| style[pagination.css]]

The snippet above can be used to include the pagination.css stylesheet only when generating a PDF file with Prince XML.

What’s next?

Release 0.3.0 is currently being planned, and so are its features. For now, I’d like to thank the following individuals for contributing to Glyph:

Jamie Atkinson (Jabbslad), for spotting and fixing some bugs and providing feedback.
Sebastian Staudt (koraktor), for spotting and fixing some bugs, proposing and implementing new features.

In particular, Sebastian is working on bibliogaphy support for Glyph, looking forward to it!

Although still in its infancy, Glyph is becoming more and more usable everyday. If you are interested, you can contribute in many different ways to the project, such as:

By participating to discussions on the user group (it’s a bit quiet of there for now…)
By spreading the word on Twitter, on your blog, or wherever you like.
By installing it, using it, reporting bugs and proposing new features (it’s just a gem install glyph away!).
By actually contributing to its development (it’s easy!).

Additionally, if you don’t like coding:

feedback on the current documentation and on the Glyph book is appreciated
if you are good with CSS, I’m looking for some nice new CSS styles to include in the standard Glyph distribution.
if you’re good with graphics, Glyph needs a good-looking logo…

Any form of contribution will be credited in some way, e.g. by links and tweets.

Introducing Glyph

h3rald@h3rald.com — Fri, 09 Apr 2010 17:30:39 -0000

I’ve been writing technical documents for a living for the past four years, and I can tell you: there is no easy way to go about it.

For example, you can use:

a Word Processor like MS Word, for example — anyone can do that, right? Sure, but no, thanks: I strongly believe that Word Processors should not be used for writing technical documents as I firmly don’t believe GUIs are suitable for doing this at a professional level.
a Document Authoring Software like Adobe Framemaker, Robohelp, etc. Still GUIs, only more complicated to use.
XML, like DITA or DocBook, or other markups, like ReStructuredText. Better, but still not easily extensible and flexible enough.
your company’s tools, if you have them. That’s great if they are usable enough and the result makes your boss happy.
LaTeX, and that’s probably your best option, if you know what you’re doing.
XHTML and CSS3, in conjunction with a PDF renderer like Prince XML — that’s great if you know HTML and CSS, and you don’t mind hand-crafting the structure of the document.

Lightweight markups

I love Textile and Markdown. When people aren’t looking, I even use them at work to generate HTML code, because it’s just so much faster. Textile in particular can be used as a drop-in replacement for HTML (and a bit of LaTeX, too), as it can produce most inline HTML tags effortlessly and some block-level tags, too.

For things like <div> tags and <tables> though, Textile is not the best thing in the world, so you normally end up falling back to HTML.

Another “problem” is that Textile or other similar lightweight markups cannot be extended easily, simply because they were not meant to be extended in the first place.

Moreover, if you are producing a book, Textile can’t help you if you want to generate things like a Table of Contents automatically or validate links: those things are simply not part of Textile’s job.

How Glyph can help

There are a few projects on the Internet that tackle structured document generation. One of them is Kitabu, which looks promising and is able to produce pretty documents using Textile and Prince for PDF rendering… but again, it’s not extensible because it relies too much on Textile and Markdown.

Glyph is different. For one, it is much younger than any other, therefore it is most likely full of bugs.

Jokes aside, Glyph follows a much more radical approach, which consists in using a macro language on top of Textile or Markdown. The good thing about it is that this macro language is very simple to learn and — most importantly — very easy to extend.

Here’s an example:

section[header[Something about Glyph]
You can use Glyph macros in conjunction
 with _Textile_ or _Markdown_ to
produce HTML files effortlessly.
  section[header[What about PDFs?|pdf]
Once you have a single, well-formatted HTML 
file, converting it to PDF is
extremely easy with a 3rd-party 
renderer like =>[http://www.princexml.com|Prince].
  ]   
]

Which translates to:

&lt;div class="section"&gt;
  &lt;h2 id="h_1"&gt;Something about Glyph&lt;/h2&gt;
  &lt;p&gt;You can use Glyph macros in conjunction with 
     &lt;em&gt;Textile&lt;/em&gt; or &lt;em&gt;Markdown&lt;/em&gt; to
     produce HTML files effortlessly.&lt;/p&gt;
  &lt;div class="section"&gt;
   &lt;h3 id="pdf"&gt;What about PDFs?&lt;/h3&gt;
   &lt;p&gt;Once you have a single, well-formatted HTML 
      file, converting it to PDF is
      extremely easy with a 3rd-party renderer 
      like &lt;a href="http://www.princexml.com"&gt;Prince&lt;/a&gt;.&lt;/p&gt;
  &lt;/div&gt;
&lt;/div&gt;

Glyph macros can be used to:

Generate block-level HTML tags not commonly managed by lightweight markups, like head, body, div and table.
Create and validate internal and external links.
Include and validate images and figures.
Automatically determine header levels based on the document structure.
Automatically generate a Table of Contents based on the document structure.
Store common snippets of text in a single YAML file and use them anywhere in your document, as many times as you need.
Store configuration settings in a YAML file and use them anywhere in your document, as many times as you need.
Evaluate Ruby code within your document.
Call macros from other macros (including snippets), carefully avoiding mutual calls.
Include text files in other text files.
Include the contents of configuration settings (author, title) in the document.
Filter input explicitly or implicitly, based on file extensions when including files.
Manage comments and todo items.

An example Glyph project? Sure, Glyph’s own guide (source — PDF output).

Technical Details

Glyph is built on top of the following Ruby Gems:

gli — For the high-level command line interface.
rake — For the mid-level interdependent task layer.
treetop — For parsing Glyph Language, whose grammar is ridiculously simple, but it seems to work so far.
extlib — Because I can’t leave without it.

Disclaimer

Glyph is alpha software (hence the 0.1.0 version number) — handle with care and be aware that everything could change tomorrow. If you want to keep up-to-date and/or provide feedback, feel free to join Glyph’s User Group.

For more information…

…head over to Glyph’s homepage.

Book Review: Refactoring - Ruby Edition

h3rald@h3rald.com — Fri, 22 Jan 2010 14:40:36 -0000

Refactoring, like testing, is an activity that should be very familiar to all programmers, especially Rubyists. Actually, programs written in Ruby don’t need as many refactorings as, say, Java programs. However Rubyists are traditionally more TDD oriented and they like writing clear and elegant code.

Refactoring: Ruby Edition is actually a rewrite of the more revolutionary — at the time — Refactoring: Improving the Design of Existing Code, written by Martin Fowler & others to teach Java programmers about refactoring. Jay Fields and others decided to port this historical title to Ruby to fill a gap: there was no authoritative book about refactoring for this language, so what’s better than translating the Bible on the subject?

If you already own the Java book you shouldn’t buy this one. This is not my personal opinion (I never read the original), it’s actually written in the Preface of the book itself. I really like honest authors, and luckily this seems to have become a trend, lately: programmers don’t like reading bullshit after all. By the authors’ own admission, this book contains roughly the same material and the same examples of the original Java book, plus some slightly more Ruby-specific content.

Getting started

The first chapter, Refactoring, a first example, is not a first chapter. Well, it is in a literal sense, but it doesn’t look like one: no theory, no padding, you’re immediately thrown in the middle of the battle, dealing with a small program in desperate need of refactoring. It literally contains quite a lot of code: the same program is rewritten over and over with changes in bold to teach you what refactoring means. The most intimidating thing is reading names of refactoring techniques capitalized and used in a natural way, like if the reader was supposed to know them already. In all fairness though, they are self-explanatory most of the time, e.g. Replace Array with Object.

What makes this chapter even more unusual is the clever usage of white space: before and after code snippets are shown on separate page, which makes it much more immediate to see the changes in code (but it won’t work very well if you bought the ebook instead of the hardback).

By contrast, the second chapter Principles in Refactoring is all about theory: it should have been the first chapter, but it’s better this way. Here you’ll learn the basics: a bit of history, when to refactor and when not to, and so on. I bet it was taken almost verbatim from the Java book; see for example: “[…] If your building APIs for outsid consumption, as Sun does […]”.

Chapter 3, Bad Smells in Code, is probably the most important and useful chapter in the entire book. It’s somethig you should read over and over until you can spot a code smell right after coding.

“You should use this chapter and the table on the inside back cover as a way to give you inspiration whn you’re not sure what refactorings to do.”

Precisely what you have to do. Except that there is no table on the inside back cover, so I guess this one will have to do. Pity.

Chapter 4, Building Tests, is the usual, compulsory chapter about unit testing, i.e. the usual intro to Test::Unit. As I said, it’s essential for the book to make sense, but you can safely skip it if you know how to test already.

Finally, chapter 5 (Toward a Catalog of Refactoring) is a 2.5 page intro to the bulk of the book, nothing more than glue to ease the transition. I would have removed it completely, but that’s because I’m a merciless technical writer I guess.

Diving in

From chapter 6 onwards, specific refactoring techniques are described. Each chapter starts with a brief overview of the following sections (which should have been a list, but I’m just being pedantic now), so you know what to expect.

Each technique described has a very meaningful and immediate name that reflects its purpose, like Extract Method or Split Temporary Variable. A code example introduces the code smell and the proposed refactoring, followed by a Mechanics section with a list of actions to perform and an explanatory Motivation section.

Tipically, each refactoring has its own, self-contained code snippets. Depending on the complexity of the refactoring technique examined, the authors may spend half to five or six pages just to show all code iterations to get to the result. When things get too complicated, UML diagrams are used to make the technique easier to understand, but only when it’s strictly necessary.

Even if the original techniques were though for Java, the authors (in particlar Jay Fields, I guess) do a great job making sure that the Ruby code doensn’t look like Java code in disguise: the result of the refactoring always follows Ruby’s philosophy and idioms. I particularly liked the following:

Replace Dynamic Receptor with Dynamic Method Definition (Chapter 6), a nice example of metaprogramming.
Decompose Conditional/Recompose Conditional (Chapter 9), very useful and very common
Replace Nested Conditional with Guard Clause (Chapter 9), another way to deal with a very common problem with conditionals
Extract Module (Chapter 11), very Rubyesque way to tidy up busy classes

This doesn’t mean that every refactoring described in the book is a programmer’s epiphany, some of the techniques are indeed pretty obvious and some portion of code in need of refactoring indeed smell very, very bad! E.g.:

Inline Class (Chapter 7): Who on Earth would ever create a class containing a single method returning a telephone number?
Replace Magic Number with Symbolic Constant (Chapter 8): Why would you use integers for constants? Didn’t Matz give us Symbols to avoid just that?

The big picture

By the end of chapter 11 you should be familiar with nearly all the best possible way to get rid of code smells. That’s all good, but what happens if the entire program stinks? Chapter 12 (Big Refactorings) claims to have some answers to some common pitfalls. The techniques defined in this chapter are by no means sufficient to solve all problems caused by bad design, but they can help especially to rewrite legacy code, or programs developed by Ruby newbies:

Tease Apart Inheritance
Convert procedural design to objects
Separate domain from presentation
Extract hierarchy

They are basically all about reducing bloat and unnecessary complexity, and — to me, that is — they all sounded pretty obvious. Of course I’m going to separate domain from presentation! Didn’t Rails teach us anything at all? I must say I was somehow disappointed by this chapter. I was going to bet there was something slightly more advanced, maybe something about replacing traditional object instantiation with an internal DSL? Nope, sorry.

Chapter 13, on the other hand, is an excellent conclusion to the book: it really helps the reader to understand when to refactor and how to do so, depending on the situation.

Conclusion

This and Design Patterns in Ruby are now my favorite Ruby books. I believe they complete each other: Russ Olsen’s book is more about designing your programs properly from the start, while Refactoring: Ruby Edition can help to make things better at a lower level.
Ruby developers don’t need to refactor as much as Java developers, mainly because of Ruby itself, nevertheless, this is an excellent read for anyone who wants to get serious about programming in Ruby, and is determined to do so by following the Ruby Way.

I’ll definitely keep this book near me when I’m coding: I do believe it is much more helpful when you start using it as a reference, when you already read about all the refactoring techniques and want to put them in practice. Also, I’ll probably re-read chapter 3 on a regular basis, to get accustomed to recognize code smells, and deal with them accordingly.

Book Review: The Merb Way

h3rald@h3rald.com — Tue, 17 Nov 2009 10:15:36 -0000

When I first picked up this book I was surprised by its length. Somehow, after reading The Rails Way, I got stuck in my mind that The Merb Way had to be almost equally voluminous. Instead, this book is about 300 page long, roughly as long as the sum of the chapters devoted to ActiveRecord in Obie Fernandez’s acclaimed Rails bible.

Apparently it only takes 300 pages to describe a web framework nowadays! I couldn’t help but feeling a bit skeptical at first. Even in the foreword, Obie Fernandez presents the book – and the whole Merb framework – with some initial skepticism: isn’t Ruby on Rails enough? Why do we need yet another Ruby web framework? And above all, seeing that Merb is going to eventually be merged into Rails 3, why on Earth do we need a book about Merb, now?

Needless to say, Foy Savas proved that both Merb and its book cannot be dismissed just like that.

Getting started

The book starts with the original Merb Pastie, a single page of Ruby code able to sort out HTTP requests, dispatch them to the appropriate controllers and render a web page. This piece of code is enough to convey what Merb is: a new breed of web framework, almost as simple as it can get but very poweful and flexible at the same time.

As you start diving in through the first chapter, you realize you’re reading about a Hacker’s Web Framework. That’s precisely what Merb is: a very versatile tool to get the job done, in the simplest way possible. Similarly, The Merb Way immediately feels like a Hacker’s Handbook rather than an ordinary guide on how to develop web applications. You won’t learn what MVC is by reading this book, and don’t expect to be taught what a mixin is; you are reading a book about a Ruby web framework that was born after the Rails Revolution, so it is safe (for the author) to assume that:

You know the Ruby programming language
You know what Ruby on Rails is and you tried it out, at the very least

The first few chapters are about the core functionalities provided by an an MVC framework: after a comprehensive first chapter about Merb’s fundamentals (from the layout of a Merb application to an overview of Merb internals) you are quite abruptly “introduced” to routing, controllers, views and models. These chapters do not aim to provide a comprehensive description of each component, they simply tell you: here’s how Merb does this.

Out of the first five chapters, favorite is definitely the one about Models. Although Merb is ORM-agnostic, DataMapper is the de facto standard for Merb applications, and it fully embrace the framework’s design and extreme flexibility without being in the way of your code.
Foy does an excellent job in this chapter by strategically describing DataMapper’s code from the top to the very bottom, from the highest abstractions to raw SQL code, using a plethora of snippets taken from the actual Merb code.

It’s about how Merb works, not how to work with Merb

After reading the Models chapter I decided to go back and re-examine the previous chapters. I didn’t notice until then, but the author sneakily smuggled a consistent amount of Merb source code into this book. This is rather unusual for books about web frameworks: they normally tell you how to use the framework, not how it was built! While this can be disappointing for people used to read Rails books, it came as a very pleasant surprise to me.

About 40-50% of this entire book (and I’m not exaggerating) is Ruby source code. In a good way, it feels like a collection of strategically-positioned code snippets glued together with explanations of the most tricky bits and digressions on how the framework was designed. In other words, it probably contains just enough text to make sure that the average reader understands the code, but remember that the average reader of this book must know Ruby failry well.

There is no pointless prose in this book, no explanations of obvious methods, no fancy words, no useless boasting on how cool the framework is: just an objective description of how Merb works and of the key design decisions behind it. If I may, the only thing that doesn’t feel quite right with this book is its title: Merb Internals would have been a better choice. Once you realize this, the book suddenly makes sense, and can even make you a better Ruby programmer.

The Merb Way does an excellent job in describing how to design a web framework, or any real-world Ruby application for that matter. It teaches you that modularity is the key to flexibility by showing how the Merb stack is organized. Sure, it doesn’t teach you how to create a blog in five minutes, but perhaps a thorough explanation of how anthentication is implemented (Chapter 9) will actually be useful in two months time, when you’ll have to create your own Merb plugin from scratch.

Some constructive criticism

The idea behind this book is clever but a bit dangerous. I flipped through the pages in front of my wife and asked her what was wrong with it. “There’s too much code!” she said, without hesitation. Precisely.

It is damn good Ruby code, but sometimes you wish there was more text describing how to use it in practice. Or maybe some code examples on using the framework on a real-world application. Not a chance. Of all that holy code, there’s not much featuring something other than Merb itself. Basically the exact opposite of all the other books about Rails or other web frameworks!

Even accepting the fact that you are not reading a book about developing web applications, there are two more things which could be improved:

Merb’s design is very intriguing, and you grasp the essentials by reading this book, but a few diagrams here and there and more in-depth digressions on the subjects would have been nice.
Besides DataMapper, what I really wanted to read about were Slices and Parts – unfortunately the chapters about them are far too short and shallow. The reasoning behind this is that their future may be uncertain due to the Rails 3 merge. Pity.

Conclusion

The death of Merb has been greatly exaggerated. Too bad I gave up web frameworks altogether for my site, because after reading this book I would have gone for Merb today rather than waiting to see the wonders of Rails 3 tomorrow. Even a book with this title could have been written in a very different way, I would still recommend it if you want to become a better Ruby programmer by learning from the best: Merb code really stands out, even compared to Rails, and Foy Savas does a great job presenting and describing it.

Take back your site, with nanoc!

h3rald@h3rald.com — Tue, 15 Sep 2009 11:32:51 -0000

Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly knew HTML and CSS, nevermind server-side languages, so I remember creating a pseudo-template for the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change in all the pages of the site – the whole eight of them.

Five years later, after rebuilding this web site seven times using different backends (PHP + CakePHP, Ruby + Rails + Typo, etc.), I decided to make it static again, this time with a twist. It all started when I read a post by Tom Preston-Warner (GitHub co-founder) that I finally decided to give it a try. Today, the 8th release of this web site is 100% static: if you load any page, there’s no server-side interpretation going on, you’re just browsing a plain HTML page, at most with a few AJAX calls. But let’s start from the beginning…

Why I don’t need a blog platform

There’s nothing inherently wrong with blog platforms like Wordpress: they allow anyone to publish content on the web using a user-friendly administration area. They were built with one thing in mind: make publishing content on the web something as simple as possible, even for people who don’t know anything about HTML, let alone server-side scripting.

What about people who do know about web development though? Do they still need a blog platform? Depends. If you are comfortable with editing files using a text editor, if you enjoy using the command-line on a daily basis, if you like programming and hacking a little bit, if you don’t really care about fancy and user-friendly administration backends… then you probably don’t.

All you need is a system to transform a bunch of source files into a web site. The good news is that such system exists – and you’re also spoiled for choices!

Introducing site compilers

The first site compiler I discovered was Webby:

[…] Webby works by combining the contents of a page with a layout to produce HTML. The layout contains everything common to all the pages — HTML headers, navigation menu, footer, etc. — and the page contains just the information for that page. You can use your favorite markup language to write your pages; Webby supports quite a few.

There are quite a few applications like Webby, such as:

There are probably even more, with different features, but they all try to solve the same problem: provide a way to generate static web sites in an automated way.

I spent some time reading about each one of them, evaluating the pros and cons and in the end I decided to go for nanoc, simply because it was the only one that seemed to fit all my needs.

A quick overview of nanoc

nanoc is a nifty tool written in Ruby suitable for […] building small to medium-sized websites. In other words, anything which doesn’t involve some fancy user interaction. For what concerns blogs, the only user interaction is comments – but that’s fine, because there’s more than one web service for that, such as Disqus or IntenseDebate.

Some details on the project

Compared to the alternatives, nanoc is one of the most mature and most maintained, having hit just a few weeks ago its 3.0 release. Its creator, Denis Defreyne, uses it for his own web site and is involved with the project on a daily basis, both coding and offering support to nanoc users like myself who regularly ask questions on the nanoc user group.

Denis also seems very concerned about keeping documentation up-to-date – something that really impressed me from a technical writer’s point of view. The tutorial he put together will get you started in no time, and the manual will explain everything else you may possibly want to know. When release 3.0 came out he even put together a migration guide. If this is still not enough and you don’t mind spending some time extending the system, nanoc’s RDoc documentation is very comprehensive compared to other Ruby projects.

Sites, Items and data sources

nanoc ships with a really neat command line tool that can do most of the work for you. Nanoc3 create_site h3rald will create a new web site in a folder called h3rald. The contents of this folder are laid out according to a particular logic (convention over configuration, remember?) So:

content – your articles, pages, stylesheets, images, …all the site content and assets.
layouts – the site layouts (and partial layouts)
lib – place your custom ruby code and vendor libraries here
output – your “compiled” site, ready to be deployed
config.yaml – your site’s configuration file. The only one (and it’s just a few lines)
Rakefile – place any custom Rake task here
Rules – defines the rules for compilation, layout and routing

Here’s the default config.yaml file:

---
data_sources: 
- items_root: /
  layouts_root: /
  type: filesystem_compact
  output_dir: output

A data source in nanoc defines where data is retrieved from to create the web site. By default, the filesystem_compact data source requires that you create two files in the /content folder for each article or page of your web page:

One containing the actual content of the page
Another for the page’s arbitrary metadata

By personal preference, I chose the filesystem_combined data source, which allows you to combine the content and the metadata of a page in a single file.

The source code for this very article, for example, starts like this:

-----
type: article
tags:
- website
- ruby
- programming
- writing
date: 2009-09-15 13:32:51.049000 +02:00
permalink: take-back-your-site-with-nanoc
title: "Take back your site, with nanoc!"
toc: true
-----
Back in 2004, when I bought the h3rald.com domain, this site was static. At the time I hardly 
knew HTML and CSS, nevermind server-side languages, so I remember creating a _pseudo-template_ for
 the web site layout and using it whenever I wanted to create a new page, to preserve the overall look-and-feel. 
This was a crude and inefficient strategy, of course: whenever I changed the layout I had to replicate the change
 in all the pages of the site &ndash; the whole eight of them.

At run time, the content goes through a Textile filter and the metadata is used in layouts, to generate tag links automatically, for example.

Layouts, filters, and helpers

Layouts in nanoc are similar to layouts and views in Rails, but much simpler. The same applies to helpers. Here’s a snippet from my default layout:

        <div id="container">
          <!-- CONTENT START -->
          <div id="content" class="clearfix<%= (@item[:permalink] == 'home') ? ' home' : ' standard' %>">
            <h2><%= @item[:title] %></h2>
            <%   case @item[:type]
                when 'article' then%>
                <div id="content-header">
                  <%= render 'article_meta', :article => @item %>
                </div>
              <% end %>
              <hr />
              <div id="content-body">
                <%= yield %>
              </div>
              <div id="content-footer">
                <div class="share">
                  <script type="text/javascript" src="http://w.sharethis.com/button/sharethis.js#publisher=6e34d60c-b14e-4c19-9b2f-7c35a9f0ab09&amp;type=website&amp;linkfg=%23a4282d"></script>
                  <% if @item[:feed] then %>
                  <a href="<% @item[:feed_url] || @item[:feed]+"rss/" %>" type="application/rss+xml" rel="alternate"><img src="/images/theme/feed-icon-14x14.png" alt="#"/>H3RALD - <%= @item[:feed_title]%></a>
                  <% end %>
                </div>
                <%= render 'article_buttons' if @item[:type] == 'article' %>
              </div>
            </div>

This source code snippet shows quite a few features of nanoc’s layouts:

You can access the metadata of the page which is being rendered using the @item, so @item[:title] returns the page’s title, for example.
Layouts can be nested, and behave like Rails’s partials. The render takes a string parameter (the name of the layout to render) and an optional hash parameter to pass variables to the layout.
The yield method is used to include the content of a page.
Layouts support any kind of filter, like ERB for example. Go crazy.

Helpers can be used in layouts to perform common tasks, like creating links, feeds, navigation elements and so on. Check the source code docs for more info, and of course feel free to create your own as you see fit.

Finally, filters are used to filter content markup. nanoc ships with almost everything you need, from Textile to Haml to RDoc, but nobody forbids you to create your own, and it’s dead easy.

Rules and tasks

While tasks (as in Rake tasks) do not constitute a huge part of nanoc (but as usual, you may need to create your own to perform custom operations), Rules became, as of version 3, one of the key concepts to grasp in order to make everything work. Rules are stored in the Rules file of your nanoc site, they can be used to:

Define routes, i.e. where pages are deployed in the output folder.
Define how pages are compiled, which filters to apply to a particular set of pages, which layouts to use, etc.
Define how layout are handled, which filters to apply to a particular layout, etc.

You can find more information in the manual, along with other important information, but for now, let’s say you should be familiar with most of nanoc’s jargon and how it works. Let’s see what you can do with it, in practice.

Migrating from your blog platform

As of version 7, h3rald.com has been powered by the Typo blog platform. If you are not familiar with it, let’s just say it’s a sort of Wordpress built on top of Rails: database backend, pretty admin front-end, tags, comments, and all sort of things a blog may need. While Typo is pleasant enough to use, it has all the inherent disadvantages of any other similar platform:

It relies on a database
It relies on server-side scripting to render pages
It uses a complex caching mechanism to produce, ultimately, semi-static pages
It may be subject to exploits, attacks, high server loads, and similar
You can’t really customize it beyond a certain point
You have to upgrade your backend frequently, and often is not as painless as you may expect
You can’t use versioning tools like git for your content, as it’s stored in a database

I’m not claiming that nanoc is blogging’s silver bullet (it was not created for that), but for sure:

It does not rely on a database
It does not rely on server-side scripting to render pages (not in real-time, anyway)
It does not need a complex caching mechanism simply because it produces static pages
It is definitely less prone to nasty things
It’s extremely flexible and hackable with very little effort
You don’t have to upgrade all the time, but it is really painless if you decide to
You can use git and similar: your content is in plain old text files

Rants are beside the point, suffice to say I recently convinced myself that switching from Typo to nanoc was a good thing, so let’s see how it worked out.

Posts, pages and comments

Out of Typo’s MySQL database, I just wanted to get the following data:

Pages and posts
Tags
Comments

Following the approach used by Jekyll, I decided to use the simple and powerful Sequel gem. I’m sorry to disappoint you, but the whole migration process can be summarize with the following Rake task:

  task :migrate, :db, :usr, :pwd, :host do |t, args|
    raise RuntimeError, "Please provide :db, :usr, :pass" unless args[:db] && args[:usr] && args[:pwd]
    db = Sequel.mysql args[:db], :user => args[:usr], :password => args[:pwd], :host => args[:host] || 'localhost'
    # Remove all existing pages!
    dir = Pathname.new(Dir.pwd/'content')
    dir.rmtree if dir.exist?
    dir.mkpath
    # Prepare page data
    dataset = db[:contents].where("state = 'published' || type = 'Page'")
    total = dataset.count 
    c = 1
    total_tags = []
    dataset.each do |a|
      puts "Migrating [#{c}/#{total}]: '#{a[:title]}'..."
      meta = {}
      meta['tags'] = get_tags a[:keywords]
      meta['comments'] = get_comments db, a[:id]
      meta['permalink'] = a[:permalink] || a[:name]
      meta['title'] = a[:title]
      meta['type'] = a[:type].downcase
      meta['date'] = a[:published_at]
      meta['toc'] = true
      meta['filters_pre'], extension = get_filter db, a[:text_filter_id]
      contents = convert_code_blocks meta, a[:body]+a[:extended].to_s
      write_page meta, contents, extension
      c = c+1
    end
  end

That’s it. Well, almost: you can find the get_comments, get_tags and get_filter methods in a separate utility file. Nothing special really, just a few convenience methods wrapping queries or simply processing data. Note how all information, including tags and legacy comments, is saved in each page’s metadata. The write_page method simply creates a file in the /contents folder.

Filters and highlighters

On my old site, I used mainly Textile and Markdown to write posts. However, some of my really old articles used BBCode, whose corresponding filter is not available in nanoc. No worries, I soon found out that creating a new nanoc filter came down to this:

require 'rubygems'
require 'bb-ruby'

class BbcodeFilter < Nanoc3::Filter
  identifier :bbcode

  def run(content, args)
    content.bbcode_to_html
  end

end

Yes, that’s it. Granted, the bb-ruby gem does all the work, but notice how easy it is to just plug in new Ruby code into nanoc’s architecture!

The next big challange was code highlighting. After a quick research, I found at least a half dozen of possible solutions to highlight source code. Some were javascript based, others were based on a server-side language like PHP, Ruby or Python. Again, I looked at Jekyll for inspiration and discovered they integrated the Pygments Python library. Why use a Python library for code highlighting in a Ruby-based project? Because there’s nothing to stop you (if you can run Python on your server, that is), because it looks very neat and because it supports a lot of different programming languages.

Lazy as I am, I more or less dropped Chris Wanstrath’s Ruby wrapper into my /lib folder (I just used Open3 instead of Open4 for Windows compatibility), and monkey-patched nanoc’s filtering helper as follows:

module Nanoc3::Helpers::Filtering

  def highlight(syntax, &block)
    # Seamlessly ripped off from the filter method...
    # Capture block
    data = capture(&block)
    # Reconvert 
    data.gsub! /<%/, ''
    # Filter captured data
    filtered_data = "\n<notextile>"+Albino.colorize(data, syntax)+"</notextile>\n" rescue data 
    # Append filtered data to buffer
    buffer = eval('_erbout', block.binding)
    buffer << filtered_data
  end

end

include Nanoc3::Helpers::Filtering

There you go, another thing sorted.

Tags and Feeds

Adding tagging support was a tiny bit more tricky. nanoc supports content tagging out-of-the-box though metadata and a simple helper, but I wanted to create tag pages (with feeds). Nothing too difficult though, it all came down to a simple Rake task:

  task :tags do
    site = Nanoc3::Site.new('.')
    site.load_data
    dir = Pathname(Dir.pwd)/'content/tags'
    dir.rmtree if dir.exist?
    dir.mkpath
    tags = {}
    # Collect tag and page data
    site.items.each do |p|
      next unless p.attributes[:tags]
      p.attributes[:tags].each do |t|
        if tags[t]
          tags[t] = tags[t]+1
        else
          tags[t] = 1 
        end
      end
    end
    # Write pages
    tags.each_pair do |k, v|
      write_tag_page dir, k, v
      write_tag_feed_page dir, k, 'RSS'
      write_tag_feed_page dir, k, 'Atom'
    end
  end

Again, you can find all the other simple utility methods in my utility file.

When it came to feeds, I decided to create a new method for the Blogging helper to create RSS feeds, although nanoc does come with an Atom feed generator:

  def rss_feed(params={})
    require 'builder'
    require 'time'
    prepare_feed params
    # Create builder
    buffer = ''
    xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
    # Build feed
    xml.instruct!
    xml.rss(:version => '2.0') do
      xml.channel do
        xml.title @item[:title]
        xml.language 'en-us'
        xml.lastBuildDate @item[:last][:date].rfc822
        xml.ttl '40'
        xml.link @site.config[:base_url]
        xml.description
        @item[:articles].each do |a|
          xml.item do
            xml.title a[:title]
            xml.description @item[:content_proc].call(a)
            xml.pubDate a[:date].rfc822
            xml.guid url_for(a)
            xml.link url_for(a)
            xml.author @site.config[:author_email]
            xml.comments url_for(a)+'#comments'
            a[:tags].each do |t|
              xml.category t
            end
          end
        end
      end
      buffer
    end
  end

Nothing too daunting, once you get used to Ruby’s XML builder. I followed a similar approach for my monthly archives

3rd-party services

Finally, the interactive bits. I basically turned to third-party services and a bit of jQuery for everything which required user-interaction or pulling data from other web sites. Here’s a list of services and APIs I currently use:

IntenseDebate, for comments.
Google AJAX Search API for internal site-wide search.
Twitter JSON API to fetch tweets.
Delicious JSON API to fetch delicious bookmarks.
BackType JSON API to fetch comments from other sites.
GitHub JSON API to fetch GitHub commits for most of my projects

If you want to know how I integrated them, check out my /js folder, it was very simple, really.

Conclusion

I was very happy of switching to nanoc. It didn’t take me long, and I spent most of the time with non-nanoc issues (brushing up jQuery, CSS, graphics, etc.). Of course knowing the Ruby programming language helps, and if you’re not comfortable with hacking your way a little bit, then maybe it’s not for you.

Personally, I’ve been waiting for something like nanoc for a long time: its simple and yet powerful architecture makes you able to do virtually anything with it. For the first time in a long time, I feel like I’m in complete control of my web site, I know every bits of it and if I want to change the way it works or looks I only have to touch a few files.

nanoc’s metadata is mindblowing for its simplicity and power: although you’re not dealing with a database, you can query your content in the easiest ways possible. Whenever I needed a way to easily access pages, filter them, add extra logic to them, I just added metadata. If you forget something, you don’t have to change your database tables, create new relationships or anything of the sort, you simply add metadata to pages.

Be warned that tweaking nanoc gets addictive very quickly: you soon end up creating silly little tasks for making things just the way you want. For me, adding a new article to my blog now just means this:

$ rake site:article name=take-back-your-site-with-nanoc
$ vim content/articles/take-back-your-site-with-nanoc
... write & close the file ...
$ Nanoc3 compile

…Exactly what I need. Nothing more, nothing less.

Personal Log - June 2009

h3rald@h3rald.com — Mon, 29 Jun 2009 00:24:00 -0000

Welcome to yet another of my extremely boring, excessively fragmented personal log posts. I’m seriously thinking of dropping the whole series in favor of more frequent (and shorter) blog posts, starting from next year. This means you’ll probably have to read another six of these priceless gems, until december 2009.
As usual, feel free to skim through as each of the following sections is almost completely unrelated to the others.

H3RALD Web Site v8.0

It’s the time of the year, again. It doesn’t happen every year but it’s definitely a trend (hence the high version number): I’m going to redesign & redevelop my web site.

This time is not the usual “Let’s pick another language and another framework and start from scratch”, but a rather more radical shift, and yet at the same time less painful. The idea is to transform H3RALD.com into a 100% static web site, without losing anything in functionality (gaining, if anything!).

Tom Preston-Werner is definitely not the first person to blog like a hacker, and his very own Jekyll is definitely not the first static web site generator our there, nevertheless, he inspired me to embrace what seems to be one of the latest trend in developer’s blogs.

The idea is simple: turn all the blog posts and pages into static content, and rely on third party web services for things like comments, search etc. For a rather extreme by very interesting example, see Tagaholic.

The advantages of this approach are many:

Free yourself from a database.
Free yourself from a resource-hungry, server-side app (Typo, in this case).
Increase speed and reliability, without using caching or similar artifacts.
Keep everything under version control.
Don’t worry about breaking things when upgrading (even if the static content generator changes, it shouldn’t really break things).
Unleash the power of client-side scripting (namely, JQuery).

For now, I’m just brainstorming a little bit on GitHub, feel free to participate. The first step is obviously choosing a static content generator, and atm Jekyll seems to be slightly ahead of Webby. Opinions?

Glyph

Did you ever want to write a short manual or a book, or even a long article? If so, chances are you gave LaTeX a shot and either fully embraced its philosophy or totally refused it. Sadly, I belong to the second category: I believe sequential documents like manuals or books should be easier to create simply by using HTML.

Whever I have a chance to actually start working on it, Glyph will become a document authoring framework, i.e. a way to create visually appealing documents in a simple way. All the ingredients are there, it’s only necessary to glue them together in a pretty form:

Textile (and RedCloth) to produce clean HTML code from a human-readable markup
CSS3 to specify page rules
A few rake scripts to produce a standalone HTML file, TOC, Index etc.
An internal DSL for the document structure and metadata
Liquid for control flow, snippets and filters
PrinceXML to generate a PDF from HTML

This project is still in planning stage, feel free to have a look at the issues/features page on GitHub. Feedback is appreciated, as usual.

Vim files & the Stash

If you read the previous two sections of this post, you may have noticed that I’m growing more and more fond of git (and GitHub). Besides the repositories I already mentioned earlier on, I also created a personal stash, which I’m using mainly to store some of my Linux dotfiles, article drafts and …Vim customizations.

If you’re looking for a color scheme for Vim, check out my very own herald.vim, and tell me what you think.

Getting ready for the Big Step

This will probably be my last post as a free man, as I’m getting married (civilly) on July 2nd and (religiously) on July 11th.
Luckily the photographer agreed to give us a CD with all the pictures taken on the big day, with no copyright restrictions attached to it (believe it or not, some photographers don’t allow you to republish your own photos unless you ask them first), so I’ll probably write a long post with pictures when we come back from our (half) honeymoon.

Everything is pretty much organized. We had troubles with the waistcoats we got from eBay: they were cut almost randomly to resamble waistcoats, but they weren’t so we had to re-order another lot of 7 sets (waistcoat, cravat and shirt this time) from another seller, this time UK-based. I seriously hope to get them in time.

On the 24th we’re having a party at our house. If you were invited, feel free to drop by, otherwise be prepared to be thrown out of the window (4th floor) by one of our ushers (Roxanne’s big brother). It’s probalby going to be about 30-40 people in the end, mainly because most of my office can’t come due to holidays they booked in advance.

What’s left to do now? Well:

Send the bomboniere over to Ireland
Make sure my dad actually ships the 96 specially-bottled bottles of our own wine to uncle John, in Ireland.
Make sure uncle John doesn’t drink all the 96 bottles of wine before the wedding reception.
Make sure my best man understood that the speech he has do make must be in English, at least 3 minutes long and not too offensive to the groom.
Pay a huge, colossal heap of money for the whole thing. It’s going to cost us (and my dad) quite a bit, in the end. But it’s a once-in-a-lifetime experience, after all (getting totally trashed in a fancy hotel with all your family, including 2nd and 3rd grade cousins).

Personal Log - April 2009

h3rald@h3rald.com — Tue, 28 Apr 2009 04:11:00 -0000

April is tratidionally a rather busy month: Easter, public holidays, and — always — some deadline to meet at work. Moreover, my birthday is also in April which makes it even more busy! Let’s see what happened this year…h3. Using Ruby in a corporate environment

I’ve been using Ruby at work for a while now. I started off writing some automation script for my own needs, then someone noticed it and asked me if by chance I could develop some scripts for them, for automating part of their own job, and so on. My boss ultimately noticed it, and she liked the idea of me investing a small portion of my time to make other people save huge amount of their time, so now I am officially in charge of workflow improvements and automation (it’s even in my job description!).

This month a colleague of mine and I had to figure out a way to write some documents once in XML format and then produce different kind of outputs (other XML files, PDFs, etc.) using the DITA Open Toolkit. Originally we thought the toolkit would do most of the job, but we soon realized we needed to tweak and change a lot more than what we usually expected.

We ended up hacking together a system using:

Microsoft Infopath as XML editor for the end users (the company buys it by default, so no worries there)
A Ruby program to parse and manipulate the original XML and produce DITA-compatible XML files.
Some Apache Ant tasks available in the open toolkit to produce an XSL-FO file
Apache FOP to produce the PDF from the XSL-FO file…

The thing seems to work fine (after a lot of tweaking), and I really enjoyed creating the Ruby program to glue everything together. I even got a chance to introduce my colleagues to the wonderful world of Textile (they are so happy that they don’t want to use WYSIWYG editors anymore!).

Easter in London

As usual, Roxanne and I spent our Easter holidays in London, at her brother’s place. This year we actually had 9 days to go around ~~squandering money~~ spending wisely in food, books, clothes and entertainment.

Most notably, I managed to drag Roxanne to Foyles and I got myself a copy of The Pragmatic Programmer, which I’m reading avidly. If it was up to me I was going to buy half of the computing section, but Roxanne kindly pointed out that I could get all of them from Amazon for half the price.
And she was right: for my birthday I preordered a copy of Programming Language Pragmatics, 3rd Ed., which should be shipped soon.

Wedding planning

My spreadsheets for the wedding guests, wedding expenses (!) and …suit sizes are getting bigger and bigger. We managed to book a lot of flights to Ireland to my parents, us, relatives etc., but there are still quite a few things to do for the wedding. The most urgent thing to do right now is sending the invites: we had them printed with the words RSVP within May on them, so they have to be out in one or two weeks at most.

The other thing which must be sorted soon are the suits. According to English (and Irish) tradition, the groom, the bestman, the father of the groom, the father of the bride and the ushers have to wear the same type of suit, with minor differences (the color of the waistcoats?). In my case, this means getting 7 (SEVEN) morning suits off eBay, in the right sizes! Hopefully I’ll be able to get them by the end of next week (if my bestman manages to let me know his sizes).

XBox 360 Gaming

Now that our new XBox 360 finally came through, Roxanne and I have a lot of hours of hard core week end gaming ahead of us! This, added to the physiological increase of stress due to the wedding, may result in a temporary slowdown of my coding and writing activities.
Right now we’re playing Mirror’s Edge, Mass Effect, and Unreal Tournment III. The last one was a special surprise present from Roxanne (“…so we can kill each other!” — she’s really lovely at times!).

Other tech-related tidbits

I can’t wait to go to the cinema to watch Star Trek XI
I started using Shelfari
I started using Star.io as my personal, bare-bones start page.
I recently released Concatenative 0.2.0.
I’m currently evaluating the possibility to create a Ruby-based Document Authoring Framework. Stay tuned.

Concatenative 0.2.0 released

h3rald@h3rald.com — Sun, 19 Apr 2009 07:42:00 -0000

Version 0.2.0. of the Concatenative DSL has been released.

Here are some highlights from the changelog:

Implemented new combinators:
- binrec
- split
- twodip
- threedip
Performance improvements:
- Stack is never copied.
- No symbol/string conversion when processing words.
Pseudo-namespace support (e.g. :kernel/:while and :math/:factorial)
~ and <= operators to unquote and define words, respectively.
No more uppercase words!

Oddly enough, I realized that it is possible to defined methods named after reserved words like “while” or “if”, so now all the concatenative words (combinators) in kernel.rb are now defined without a leading undersore. Similarly, there’s no real need to use UPPERCASE symbols, so as a result, method lookup is significantly faster and will use less resources.

Here’s how the lookup works. Say you have the following program:

[[1,2,3], [4.5.6], :concat]

If :concat has been defined by the user (:concat <= [...]), that definition will be used, otherwise the Concatenative::Kernel combinator concat will be called. If you want to use the corresponding Ruby method, all you have to do is specifying the arity explicitly using the | operator.

To remove any ambiguity, it is now possible to specify the namespace of a word explicitly, e.g. :kernel/:concat or :ruby/concat. The / operator simply concatenates the two symbols together (:"kernel/concat") and sets the namespace (:kernel) and name (:concat) of the new symbol. :kernel and :ruby are not meant to be used when defining new words, but you can use anything else you like, for example :math/:factorial or :local/:a, etc.

As I pointed out in the first article about concatenative, even with the new performance improvement a concatenative program still runs slower than a standard Ruby program, but at least now you won’t run out of stack space (the Ruby stack, in this case) too soon.

If you have any issues to report, feature requests, etc., feel free to use GitHub to do so.

Personal Log - March 2009

h3rald@h3rald.com — Mon, 30 Mar 2009 04:04:00 -0000

Another month without the Internet at home. This is getting really annoying, and I decided to change provider, again, hoping that I’ll eventually get my broadband back, someday. Luckily I can still go online at work, but of course it’s not the same thing: my time on Twitter and Facebook is now basically limited to weekends only, when Roxanne and I go down to Tuscany to stay with her parents.

Concatenative programming

For some weird reason I became fond of the Concatenative programming paradigm. I started reading about Joy and then started to work on a Ruby DSL able to do the similar things: Concatenative. Another pet project — as if I didn’t have enough things to do already!

Some people seemed pleased about it, especially on Reddit and dzone. The downside of it is that it’s still fairly slow if compared to Ruby code (which is not exactly fast, either!), so if I had some spare time I should really try to implement it as a C extension, maybe.

Learning new programming languages?

Incidentally, I’m still fighting with myself on whether to learn another programming language or not. At this point, learning Factor could turn out to be more natural than months ago. However, I would only learn new programming languages as a hobby, as I don’t need to do so for profit: luckily I’m still a happy technical writer and I enjoy my job.

I admit, I’m still looking for the perfect programming language which is fun to learn (not easy: fun), elegant, minimalist, fast, general purpose and cross platform (meaning Linux, Windows, and Windows Mobile as well). Of course there is no such thing out there and there will never be, so I’m still evaluating the current alternatives. Possible candidates are Haskell, Factor, some dialect of Lisp or C.
Why C? Well, because I didn’t do much with it since my first year at uni, and it could still be useful to write Ruby extensions or implement something at a lower level. After so much time getting spoiled by high level languages, I kinda miss the low level stuff. Ahhh where are all the pointers gone?!

On the other hand, I’m getting married soon, and I should use these months to help my wife-to-be a bit more with wedding planning (see next section). After all, I can always learn a new programming language after getting married, right? …right?!

Wedding planning

Roxanne and I are slowly getting more and more things done for the wedding. Every attempt I made to introduce her to GTD failed miserably so far, or better, it worked too well: she is now getting used to make lists and deciding on our next actions for the weekend.
This weekend we booked our flights to Ireland, looked at cottages and hotels for the three days after the wedding (not the honeymoon yet, we’ll have a late honeymoon in autumn), chose the waistcoats for me, my bestman and the ushers, and …booked the wedding car!
Now, this turned out to be good fun! Take a look at Ruby (yes, yes, I know… ), a Silver Cloud II 1961 Rolls Royce which will be ours for (less than) one day!

Other tech-related tidbits

I successfully migrated to Ubuntu 9.0.4 Jaunty. Everything works, except the flash plugin for Firefox.
I’m now using TweetDeck as my main Twitter client on both Windows and Linux.
I’m thinking of buying (after the wedding) an Eee PC (no Macs: Ubuntu is sleek and powerful enough &emdash;and free, too).
We finally got an XBox 360 from eBay, this time it came through the post.
Roxanne is thinking of buying a big LCD TV to go with it &emdash; I’m politely (and sadly) postponing till after the wedding.
After listening a FLOSS Weekly episode featuring it, I think I’ll get myself an Arduino Board for my birthday.

Concatenative programming in Ruby

h3rald@h3rald.com — Sat, 28 Mar 2009 06:24:00 -0000

A while ago, I sat down examining a few alternative programming languages I might decide to learn someday. Each of those languages has its own peculiarities, and I didn’t choose them randomly, I chose them based on their popularity, power, paradigm and how actively they are developed.

I included Factor as the only representative for concatenative programming, an interesting way to write programs, but seldom used in “recent” languages (except for Factor and a few others).

The Joy of concatenative programming

If you have absolutely no clue on what I’m talking about, you should consider looking at the home page for the Joy Programming Language, or maybe just the overview: it should be enough to tikle your curiosity.

Joy is often considered the canonical concatenative programming language: a basic —but working— implementation of a simple programming language to illustrate the fundamentals of concatenative programming. Joy looks like this:

2 3 + dup *

This simple programs computes the sum of 2 and 3, pushes it on the stack, duplicates it (using the dup combinator) and then multiplies the two values, obtaining 25 as a result.

Let’s slow down a second. Here’s what happens, exactly:

Element entered	Stack contents
2	²
3	[2 3]
+	⁵
dup	[5 5]
*	²⁵

Got it? Let’s take it one step further. When you enter dup and then *, you are effectively computing the square of a number, so we can define the function square simply as:

square == dup *

In Ruby, this would be:

def square(x)
  x*x
end

What’s unusual here? — Simple, there are no variables involved. Joy doesn’t need any explicit variable or formal parameters of any sort.

There’s more. Take the following code:

[1 2 3 4] [dup *] map

The map combinator expects a list and a quoted program (the same one used to compute the square) and produces a new list containing the result of that program applied to each element of the original list. Basically the equivalent of:

[1,2,3,4].map { |e| e*e }

Do you notice anything different? — Yes, Joy doesn’t need blocks or lambdas either, it uses quoted programs instead, which are nothing but slightly fancier lists (or arrays, as you like).

Let’s recap then, Joy doesn’t need of:

lambda functions or blocks (quotation does the trick)
explicit parameters (everything you need is on the stack)
variable assignments (same as above)
explicit recursion (provided you can use combinators like linrec, primrec, binrec, etc.)

I would consider this one of the best examples of programming minimalism: an incredibly simple syntax, a very small set of rules, but a good deal of power.

Ruby objects on the stack

After reading about Joy, I realized that implementing something similar in Ruby would be an interesting mini-project (let’s say a week of lunch breaks) to understand more about concatenative programming. It would also be pointless, too: a stack-based programming language implemented on top of one of the most high-level programming languages you can find isn’t going to be fast, is it? Nevertheless, it would still be interesting.

Ruby offers everything you need to build a Joy-like DSL:

You can use arrays as …arrays, but also as quoted programs, and to model the stack itself.
You can use integers, strings, etc. as themselves
You can use Symbols as functions (we’ll get to this in a minute)

If you think about the following expression in postfix notation:

2 2 +

We could translate it into infix notation (2 + 2), because Ruby supports it, but it’s not general enough. What you could do is this though:

2.send(:+, 2)

Message sending. I can see all the SmallTalk sympathizers drooling already. Well yes, In Ruby, everything is an object, so everything has a receiver and maybe some parameters. In other words, every method call can be reduced to the following syntax:

receiver.send(method, *params)

In this way, it is safe to assume that everything has a receiver, which could be understood as a function parameter, and may have 0 or more parameters. Take the following then:

[2, 2, :+]

It’s not too different from Joy, and it’s still Ruby code. All you have to do is use something to do the following:

Take an array, and examine each item:
- If it’s an object (non-Symbol), then push it on top of the stack.
- If it’s a Symbol, then do something different, i.e.:
  - Find its receiver and its parameters and call a method.
  - Manipulate something on the stack.

In this case, we have to find :+’s receiver and its parameter and we’re sorted.

Unfortunately Ruby’s arity method isn’t that reliable. For example: "test".instance_method(:sub).arity returns -1, while it should return “2” to be useful. So we have no choice but find a way to pass the method’s arity explicitly, in some cases.

For example like this:

["Ciao, Fabio", /Ciao/, "Hello", :sub|2]

If we define a | operator for the Symbol class, it’s not too bad after all. It’s heavy, but in this way we can use any Ruby method in postfix notation.

Introducing the Concatenative Ruby DSL

Concatenative is a simple Ruby DSL for concatenative programming. You can write concatenative programs inside ordinary Ruby arrays and execute them by calling either Array#execute or Kernel#concatenate, like this:

require 'concatenative'

concatenate(
  10,
  [0, :==],
  [1, :+],
  [:dup, 1, :-],
  [:*],
  :linrec
 )

This simple program calculates the factorial of 10. As you can see, no matter how unusual it may look, it is perfectly valid Ruby code and it is equivalent to the following Joy code:

10 [0 =] [1 +] [dup 1 -] [*] linrec

Granted, Joy looks better, but that’s the tradeoff for not writing a parser for Joy syntax, after all.
Looking at the code above, there are a few things to keep in mind when programming with Concatenative:

You are using Ruby arrays, so you have to use commas, at least
functions, operators and combinators (let’s just call them words) are available as Ruby symbols
The arity of all Ruby infix operators has been already set to “1” by concatenative using the set_arity method (which simply stores the arity of a particular symbol in a constant hash)
You can specify explicit arities using the | operator (:gsub|2, or :join|1)
Unless the arity has been specified, an arity of 0 is assumed.
You can define your own concatenative functions using the Symbol#<= method, which expects a quoted concatenative program.

Performance issues

In its current form, Concatenative can be very slow, as show the “benchmarks” provided in the /examples folder, especially if you use recursive combinators. This is understandable because everything is implemented in pure Ruby, which is totally unsuitable for low level stuff.

If you are interested, you are more than welcome to submit patches and suggestions to improve Concatenative’s performance, or, if you feel brave enough, you could help me create a C extension instead: things would become much faster then.

At any rate, feel free to play with it. You can get the source from GitHub, you can get the gem from RubyForge and you can submit ticket through GitHub as well.

Real-world Rawline usage

h3rald@h3rald.com — Sat, 07 Mar 2009 03:54:00 -0000

So I finally decided to update RawLine last week, and I added a more Readline-like API. When I first started the project, I was determined not to do that, because the current Readline wrapper shipped with Ruby is not very Ruby-ish: it’s a wrapper, after all!

The good thing of having a new API compatible with Readline is that now people can use RawLine in their Readline-powered scripts, with very minor modifications.

Let’s have a look at some examples (they are also shipped with Rawline v0.3.1):
h3. Rush

Rush is an excellent gem which provides a cross-platform shell environment, entirely written in Ruby.
Being a shell, it obviously uses Readline for tab completion, and that does the job on Linux. On Windows though, things aren’t that easy:

text gets garbled if you write long lines
you can’t type certain characters if they use some key modifiers like , etc.

RawLine doesn’t have these problems (that’s the very reason why I created it), so here’s a simple script which launches a Rawline-enabled Rush shell:

require 'rubygems'
require 'rush'
require 'rawline'

class RawlineRush < Rush::Shell

	def initialize
		Rawline.basic_word_break_characters = "" 
		Rawline.completion_proc = completion_proc
		super
	end

	def run
		loop do
			cmd = Rawline.readline('rawline_rush> ')
			finish if cmd.nil? or cmd == 'exit'
			next if cmd == ""
			Rawline::HISTORY.push(cmd)
			execute(cmd)
		end
	end
end

shell = RawlineRush.new.run

What happens here? Nothing much really, all I had to do was:

Derive a new class from Rush::Shell
Set Rawline.basic_word_break_characters to the same value used in the original Rush code
Set Rawline.completion_proc to the same completion Proc used in the original Rush code
Rewrite the original run replacing Readline with Rawline

And it works as it was intended to, i.e. typing root['b<TAB> will expand to root['bin/, etc.
Note that I didn’t write the completion Proc from scratch: it was already there.

IRB

After trying out Rush, the next logical step was trying IRB itself: I could never use it properly on Windows, and that was really frustrating.
After a few minutes trying to figure out how to start IRB programmatically, I quickly came up with a similar example:

require 'irb'
require 'irb/completion'
require 'rubygems'
require 'rawline'

Rawline.basic_word_break_characters= " \t\n\"\\'`><;|&{(" 
Rawline.completion_append_character = nil
Rawline.completion_proc = IRB::InputCompletor::CompletionProc

class RawlineInputMethod < IRB::ReadlineInputMethod
	include Rawline
	def gets
		if l = readline(@prompt, false)
			HISTORY.push(l) if !l.empty?
			@line[@line_no += 1] = l + "\n"
		else
			@eof = true
			l
		end
	end
end

module IRB
	@CONF[:SCRIPT] = RawlineInputMethod.new
end
IRB.start

In this case, Rawline is included in the RawlineInputMethod class, derived from the original ReadlineInputMethod class, i.e. the class IRB uses to define (guess…) how to input characters.
Again, all I had to do was set a few Rawline variables to match the ones used in Readline, and then redefine the function used to get characters. All done.

It works as expected (only with inline completion, of course): typing "test".ma<TAB> will give you "test".map, "test".match, etc.

You also get all Rawline key mappings for free (CTRL-K to clear the line, CTRL-U and CTRL-R to undo and redo, etc.), and you can define your own.

RawLine 0.3.0 released — now with Readline emulation

h3rald@h3rald.com — Sun, 01 Mar 2009 06:47:00 -0000

RawLine 0.3.0 has been released. This new milestones fixes some minor bugs and adds some new functionalities, must notably:

Ruby 1.9 support
A filename completion function
A new API very similar to the one exposed by the Ruby wrapper for GNU Readline

Some of you asked for Readline compatibility/emulation and that was actually not too difficult to implement: all the bricks were already there, I just had to put them together in the right place.

The RawLine module (you can spell it “Rawline” as well, if you wish) now behaves like Readline. This means that you can now use RawLine like this (taken from examples/readline_emulation.rb):

include Rawline

puts "*** Readline Emulation Test Shell ***"
puts " * Press CTRL+X to exit"
puts " * Press <TAB> for file completion"

Rawline.editor.bind(:ctrl_x) { puts; puts "Exiting..."; exit }

Dir.chdir '..'

loop do
	puts "You typed: [#{readline("=> ", true).chomp!}]"
end

Basically you get a readline method, a HISTORY constant like the one exposed by Readline (Rawline’s is a RawLine::HistoryBuffer object though — much more manageable), and a FILENAME_COMPLETION_PROC constant, which provides basic filename completion. Here it is:

	def filename_completion_proc
			lambda do |word|
				dirs = @line.text.split('/')
					path = @line.text.match(/^\/|[a-zA-Z]:\//) ? "/" : Dir.pwd+"/"
				if dirs.length == 0 then # starting directory
					dir = path
				else
					dirs.delete(dirs.last) unless File.directory?(path+dirs.join('/'))
					dir = path+dirs.join('/')
				end
				Dir.entries(dir).select { |e| (e =~ /^\./ && @match_hidden_files && word == '') || (e =~ /^#{word}/ && e !~ /^\./) }
			end
		end

You can find this function as part of the RawLine::Editor class. The result is not exactly the same Readline, because completion matches are not displayed underneath the line but inline and can be cycled through — which is one of Readline’s completion modes anyway.

A few methods of the RawLine::Editor class can now be accessed directly from the RawLine module, like with Readline:

Rawline.completion_proc — the Proc object used for TAB completion (defaults to FILENAME_COMPLETION_PROC).
Rawline.completion_matches — an array of completion matches.
Rawline.completion_append_char — a character to append after a successful completion.
Rawline.basic_word_break_characters — a String listing all the characters used as word separators.
Rawline.completer_word_break_characters — same as above.
Rawline.library_version — the current version of the Rawline library.
Rawline.clear_history — to clear the current history.
Rawline.match_hidden_files — whether FILENAME_COMPLETION_PROC matches hidden files and folders or not.

I bet you didn’t know these methods were even in the Readline wrapper, did you? Probably because of lack of documentation.
Anyhow, another very important difference beween Rawline and Readline is Rawline.editor, i.e. the default instance of RawLine::Editor used by the Rawline module itself.

This makes things easier if you want more control over the line which is being edited and the previously-edited lines. Sure, Readline#completion_proc exposes the current word being typed before hitting tab, and so does Rawline#completion_proc the difference is that if you access Rawline.editor.line you get a RawLine::Line object with all the information you could possibly need about the current line: the position of the cursor, the text, the order the characters were entered, etc. etc.
Now you can imagine why it took me a few minutes to write the filename_completion_proc method (and why it will take you even less time to write your own similar method if you wanna do something different): you can access not only the last word being typed but also the current and previous lines (through Rawline.editor.history or just Rawline::HISTORY)!

It must be said, as usual, that Rawline is not a complete replacement for the Readline library yet (and it will probably never be, as Readline is huge!), but it’s a good cross-platform, more Ruby-esque alternative to what’s currently available by the Readline wrapper for Ruby.

It’s not as fast, of course, especially when completing long words, but it’s quite usable. The following libraries are not required but recommended:

win32console (on Windows)
termios (on *nix)

They basically make Rawline faster. If you don’t use them, Rawline will fall back on its pure-Ruby implementation to move left and right (i.e. printing backspaces and spaces character codes instead of ASCII escape codes).

Unfortunately, there’s no vi_editing_mode or emacs_editing_mode yet (for time constraints: they can be implemented!) but patches are very welcome. Also, if you need more features, all you have to do is ask :-)

P.S.: Check out the new Project Page and especially its Resources section!

Personal Log - February 2009

h3rald@h3rald.com — Fri, 27 Feb 2009 12:09:00 -0000

This has been a rather busy month, hence the lack of general Internet activity. I really wanted to post some more articles to my site, but for one reason or another I had to procrastinate more and more, and here we are at the end of the month again.

Recession time!

I’ve always considered the current economic downturn as something happening somewhere else: USA, England, Ireland… but not in Italy, really: our country never boomed, we don’t go mental with loans and mortgages (or at least we didn’t use to), so there’s no real reason for a full-on recession period.

It turns out I was wrong. Other than the fact that our industries are more or less non-existant or already in debt, I didn’t consider that:

Italians tend to panic a lot.
We have an awful lot of foreign business going on, a lot of multi-national companies opened up through the years lured by cheap workers and acceptable craftmanship.
Our government already ~~wastes~~ invests a lot of money regularly, every year, to fuel a colossal, nepotistic, pointless bureaucratic machine they insist on calling “State”.

Result: the recession is starting to hit properly over here too. People are saving money, they don’t go out buying pointless crap, they are scared to ask for a raise at work… the usual. I work for a foreign company which has been, as were most, forced to save some money to compensate some not-so-good First Quarter’s revenues. This means less unnecessary expenses, less training, less travelling and less outsourcing, which didn’t help improving the daily work experiece. Personally, I’m not that affected by all this, nevertheless it made me bless the day my fiancée persuaded me to stop uni after my Bachelor’s Degree to get a very rewarding, not-so-stressful job.

No ’Net @ Home

The most annoying thing of the month was (and still is) the lack of Internet access at our house. Let’s do a quick recap:

After spending one year with Telecom Italia, Roxanne and I decided to change provider to save a bit of money and get more speed.
On December 24th we requested a contract with Wind, after they assured that we’d have the Internet back on in just a few days, tops.
On January 5th Telecom disconnected us.
On January 12th Wind sent me a mail telling me that there was going to be a 15-day delay in the activation — well, at least they told us so! We waited.
On February 2nd I call Wind Customer Care hassling them to get a move on — just some minor delays, it will only take a few days, tops. We waited.

Our new Internet line has been in the process of being activated ever since January 5th. Why? Because being a customer sucks, in Italy, and you can’t do much about it.
Let me quote one of the 13 phone calls I made:

… 5 minutes on hold, stupid music in the background …
[Operator]: Good Evening Sir, I’m , how can I help you?
[Me]: Hello, I’m enquiring about the status of my Internet connection: I’ve been disconnected since the 5th of January…
[Operator]: Phone Number please?
[Me]: *** ******
… 2 minutes on old …
[Operator]: Name plase?
[Me]: Fabio Cevasco
[Operator]: Let me check…
… 6 minutes on hold, stupid music in the background …
[Me]: Any luck?
[Operator]: One moment please…
… 2 minutes on hold, stupid music in the background …
[Operator]: Sir, it says here that you are in the process of being activated
[Me]: (you stupid idiot, I can check that on the Net in less than a minute) Yes, I know what, but why, exactly? It has been over a month…
[Operator]: Let me check…
… 3 minutes on hold, stupid music in the background …
[Operator]: There are some technical difficulties.
[Me]: What kind of technical difficulties?
[Operator]: I… I don’t think you can understand Sir, it’s technical…
[Me]: (!!!) I have a degree in IT Engineering, so yes, I think I can understand enough.
[Operator]: …well, there’s nothing I can do… it says we’re in the process of connecting you, it should be just…
[Me]: …a matter of a couple of days, yes, I know: it has been over a month though!
[Operator]: Sir, really, I can’t really do much about it, you’ll just have to wait
[Me]: Can you let me speak with the Technical Department?
[Operator]: No, sir, I can’t: you see, your ADSL line is not yet activated, they can’t do anything about it.
[Me]: Excuse me, but I’d like to know what the problem is, and how long it will take to activate the line.
[Operator]: Sorry sir, we don’t have this information, and we can’t commit to a specific date.
[Me]: (!!!) May I speak to someone who knows this? May I speak to your superior?
[Operator] No, you can’t speak to my superior. You’ll just have to wait, I’m sorry.
[Me]: Well, it has been over a month, and I don’t know if you realize that you were supposed to connect me in just a few days and…
[Operator]: Thank you for calling sir, have a good day.

That barely conveys the frustration I felt and I’m still feeling now. I can’t even sue them: I could get 100 Euro at most after spending at least a couple of thousands in lawyer. So much for the land of sunshine huh?

Programming in Ruby, again

Some of you may be pleased to know I’m back coding in Ruby after slacking for months. It’s just the time of the year, I guess.
I’m also evangelizing the language quite a bit at work: after I wrote a few scripts on demand, I slowly lured one of my colleagues to Vim, the Texile markup and then finally the Ruby language. He’s going through the Humble Little Ruby Book and he’s loving it, so far. He’ll hopefully be fully assimilated in a few weeks at most, and after that there will be no going back!

This inspired me to start a full rewrite of RedBook, my little Ruby daily logger. It will feature a SQLite backend and Merb’s Datamapper to take care of the dirty work.
Unfortunately, even if the new sources are already available on GitHub, it will take me approximately a few more weeks to complete all the plugins and more to finish the RDoc documentation and — hopefully — a fully-fledged user manual. It’s the pet project, after all…

On the other hand, it will take me considerably less time (a few days?) to release the next version of my RawLine library, featuring:

Ruby 1.9 support
A handy little function for filename completion
Readline emulation, i.e. just include Rawline and use it as if it was GNU Readline

Of course this doesn’t mean RawLine is a complete, 100% Ruby port of the GNU Readline library, but it is definitely more Ruby-ish, more cross platform (try using Readline with Ruby on Windows…), and usable enough for most of the normal things, like:

tab completion
line editing (but no vi or emacs mode yet, sorry)
history
quick and easy key bindings

Once this comes out, I’ll be implementing features on-demand, as GNU Readline is huge and offers way too many things anyone would ever need. Patches and contributions are of course more than welcome, though.

For all my open source Ruby projects, after pondering the alternatives, I decided to go with the following setup:

My own site for the home pages of the projects
RubyForge for gem support and for RDoc documentation
GitHub as source code repository
LightHouse for issue tracking

I hope it works out…

Italian translation of Ruby-Lang.org finally available!

h3rald@h3rald.com — Sat, 15 Nov 2008 13:48:00 -0000

[Vai alla versione italiana]

I am very pleased to announce that the official site of the Ruby programming language is now available in Italian:

www.ruby-lang.org/it/

In the beginning…

It all started in July 2007, when after a closer look at the site I discovered that apparently it was not available in Italian! How could it be? There were a lot of translations available, such as French, Spanish, Japanese, Korean… but no Italian.
I immediately emailed the webmaster and within a few hours Curt Hibbs (hell yes, that Curt Hibbs!) mailed me the instructions to get me started:

“[…] Providing a translation of the Ruby web site would have two parts: 1) the initial translation of the current content, and 2) the ongoing maintenance of the Italian version as new content and news items are added.

This effort will be much more sustainable over the long term if you put together a team of at least three people who would commit to translating and maintaining the site. […]"

…Why three people to translate “a few pages”? That’s what bugged me at the time: it honestly seemed just a few days work for one person at most. Later on I understood why.
I wasn’t the first to volunteer for the Italian translation, actually: Raul Parolari was indeed the first, but he was waiting for another two team members to start, of course.

We eventually persuaded Curt that we could handle it even without a third team member, so we started right away. As a matter of fact, we did manage to translate a lot of stuff within the first week.

Translating is easy, right?

Translating feels easy when you are mother tongue in the language you’re translating into (Italian), and you know fairly well the language you’re translating from (English): it can’t possibly hard, right? Nah, a piece of cake.
Most of the time it’s fairly easy and fast, too, but things can get a bit more complicated when you stumble upon idioms and tech jargon.

Personlly, I never surf the web in Italian. That’s a personal choice (I love the English language to an extreme extent), and I’ve learnt to live with it no matter what people think. I admit that it was hard for me to translate some of the things on the Ruby web site: not because they were hard for me to understand, but because in some cases a translation would simply not do justice to the original text.

Some of the text may sound weird in Italian, especially in the code examples. In the end we choose to translate every bit of code, e.g. puts sentence became puts frase and other equally horrid things. Sometimes I wonder whether we should have just left the original code as it was, but we wanted to make things easier for people who don’t speak much English at all.

Stagnation

Things went quite after the initial excitement, I admit. Both Raul and me more or less stopped translating as time went on, and I am truly and deeply sorry for that. You know how it is: you start off really enthusiastic and then you lose interest, you get involved in other projects, work, family, etc. etc.

Davide D’Agostino came to our rescue in December 2007. He’s arguably the “most Italian” of the group and he came out with some interesting solutions for some particularly difficult bits of the translation.
Believe it or not, the 80% of the site was translated by the beginning of 2008: only a few bits were left, but then… erhm, things went quiet again. I put the translation of the site on my todo list, and I knew it was there all along: “Oh, yes, I should have a look at Ruby-Lang.org again” I repeated to myself from time to time.

About two weeks ago I got so pissed off with myself about this that I decided to finally “get things done” and translate the few remaining bits, reviewed the lot, got rid of some rough edges, did some minor proofreading and here it is, ready to be browsed by Italians, finally.

The most ironic thing? It took literally a few hours of “work” to sort things out… but nearly a year to finally find the will to do it.

What now?

Now the site is live and we’ll keep it up-to-date from now on. I sincerely hope it will help bringing more and more Italians closer to the Ruby world. I’m sure there are plenty of people out there who would have done a much better job than we did, and definitely in a much shorter timeframe… but hey, we finally did it, after all!

I would like to thank again Raul Parolari and Davide D’Agostino for helping translating the site: I now finally understand why Curt wanted three people on the translation team!

One last thing: if you find any mistake (and there are plenty, I’m sure) or if you have any suggestion to improve the current translation, don’t hesitate to contact me: I’ll try to fix things as soon as possible.

Enjoy Ruby, now finally in Italian too!

È finalmente disponibile la traduzione italiana di Ruby-Lang.org

Sono veramente contento di annunciare che il sito ufficiale del linguaggio di programmazione Ruby è ora disponibile anche in Italiano:

www.ruby-lang.org/it/

In principio…

Tutto incominciò nel luglio del 2007, quando dopo un’occhiata più da vicino al sito mi accorsi che apparentemente non era disponibile in italiano! Com’era possibile? Era già tradotto in molte lingue tra cui francese, spagnolo, giapponese, coreano… ma niente italiano.

Mandai immediatamente un’email al webmaster, e in poche ore Curt Hibbs (già, proprio quel Curt Hibbs!) mi inviò le istruzioni su come iniziare a tradurre:

“[…] La traduzione del sito di Ruby è articolata in due parti: 1) la traduzione iniziale degli attuali contenuti e 2) il continuo aggiornamento della versione italiana ogniqualvolta vengono create nuove pagine.

Questo sforzo è molto più sostenibile nel lungo termine se riesci a mettere insieme una squadra di almeno tre persone dedite a tradurre e ad aggiornare il sito. […]"

…Perchè tre persone per tradurre “solo poche pagine”? Questo quello che mi chiesi in quel momento: sembrava veramente essere una questione di pochi giorni, e sicuramente una persona sarebbe stata più che sufficiente. Successivamente capii perchè tre persone erano necessarie.

Comunque, non ero il primo ad offrirmi volontario per la traduzione italiana: Raul Parolari si era già fatto avanti, ma stava ancora aspettando altre due persone per poter iniziare, ovviamente.

Alla fine, riuscimmo comunque a persuadere Curt che ce la potevamo fare, anche senza una tersa persona ad aiutarci. Incominciammo a tradurre quindi di buona lena, e di fatto riuscimmo a tradurre molto durante la prima settimana.

Tradurre è facile, non è così?

Tradurre dall’inglese all’italiano sembra facile se sei madrelingua e conosci bene l’inglese: non può essere difficile, giusto? Facilissimo, ovvio.
Per la maggior parte è così, di fatto: facile e veloce. Ma le cose tendono a complicarsi un pochettino quando hai a che fare con modi di dire e linguaggio un po’ più tecnico.

Personalmente, non vado mai su siti italiani. È una mia scelta personale (mi piace tantissimo la lingua inglese), e ho imparato a non fare caso a quello che gli altri pensano di questa scelta. Devo ammettere che è stato difficile per me tradurre alcune parti del sito di Ruby: non perchè fossero difficili da capire, ma perchè in qualche caso una traduzione non è semplicemente in grado di rendere giustizia al testo originale.

Alcuni pezzi della traduzione, per questa ragione, potrebbero suonare un po’ strani alle orecchie di Italiani d.o.c., specialmente per quanto riguarda gli esempi di codice. Alla fine abbiamo deciso di tradurre la maggior parte del codice (ove possibile, ovviamente): puts sentence è quindi diventato puts frase, e altri simili orrori. Qualche volta mi chiedo se non avessimo fatto meglio a lasciare il codice originale così com’era, ma d’altra parta abbiamo cercato di fare il possibile per rendere le cose più semplici anche per persone che non sanno una parola di inglese.

Stagnazione

Col tempo, l’iniziale interesse nella traduzione è andato affievolendosi, lo ammetto. Sia io che Raul abbiamo praticamente interrotto la traduzione ad un certo punto, e mi dispiace veramente tanto. Sapete com’è: incominci entusiasta e poi piano piano inizi a perdere interesse, ti dedichi ad altri progetti, il lavoro, la famiglia, eccetera.

Davide D’Agostino venne in nostro aiuto nel Dicembre 2007. Penso che sia quello “più italiano” del gruppo, tanto da essere in grado di proporre soluzioni interessanti per alcuni pezzi particolarmente difficili da tradurre. Che ci crediate oppure no, l’80% del sito era pronto e tradotto all’inizio del 2008: rimanevano solamente alcune piccole parti ancora da tradurre, e poi… beh, abbiamo un po’ lasciato perdere, di nuovo. La traduzione del sito era tra le mie cose da fare, c’è sempre stata: “Sì, certo, dovrei dare un’occhiata a Ruby-Lang.org”… mi sono ripetuto questa frase periodicamente, senza di fatto fare nulla.

Poi, finalmente, due settimane fa mi sono deciso a finire il lavoro traducendo le poche pagine rimaste, revisionando il tutto, facendo un po’ di pulizie qua e là, ed ecco qui: il sito può ora essere visitato da tutti gli italiani che lo desiderano.

La cosa più ironica? Sono bastate solo poche oro di “lavoro” per mettere le cose a posto, ma quasi un anno per trovare finalmente la forza di volontà per farlo…

E adesso?

Ora il sito è accessibile e lo terremo aggiornato d’ora in avanti.
Spero sinceramente che possa contribuire ad avvicinare sempre più italiani al mondo di Ruby, anche se sono sicuro che ci sono moltissime altre persone là fuori che avrebbero fatto un lavoro più ben fatto del nostro, e sicuramente in tempi molto più brevi… ma dopotutto, alla fine ce l’abbiamo fatta, no?

Vorrei spendere ancora due parole per ringraziare nuovamente Raul Parolari e Davide D’Agostino per avermi aiutato a tradurre questo sito. Finalmente ora capisco perchè Curt voleva tre persone nel gruppo di traduzione!

Un’ultima cosa: se qualcuno di voi trova un errore (e ce ne saranno molti, ne sono sicuro), o se ha un suggerimento per migliorare l’attuale traduzione, può contattarmi: cercherò di correggere il sito quanto prima possibile.

E ora, divertitevi con Ruby, ora anche in italiano!

Where does your Ruby code live?

h3rald@h3rald.com — Sat, 08 Nov 2008 12:34:00 -0000

Back when I wrote my 10 reasons to learn Ruby article, I mentioned RubyGems in Reason #1 as one of they key features of the Ruby programming languages.
Indeed, gems make getting Ruby programs as easy as typing gem install <something> from the command line. When you want to distribute something new in Ruby, there’s no need to give people download links, zip files or setup programs, just tell them to get the gem. That’s perfectly normal, and extremely cool.

Gems are normally stored on RubyForge, so all you have to do is uploading your gem there, and it will be available to the rest of the universe. It’s a nice feeling. I remember when I first uploaded RawLine and then tried gem install rawline just for the hell of it: it downloaded and installed the gem, as expected.

Back in the day, if you wanted to find something written in Ruby, all you had to do is search through RubyForge, and you’d eventually find it, with a bit of luck.

Can we just have git, please?

RubyForge had, until recently, one major problem: it only allowed CVS and SVN repositories, and you had to make your choice when creating the project, once and for all. So when the cool guys at GitHub rolled out their social code hosting web site, most of the créme de la créme of RubyForge flocked there in mass migration: Rails, Merb, RSpec… you name it.
Once the big guys made the switch, a lot jumped on the GitHub bandwagon of course. Result: we have a lot of projects still on RubyForge, but quite a few (and important ones) on GitHub.

Why did people move there? Well, at first it was because they wanted a sleek-looking git host, and RubyForge didn’t offer git at the time. But git is now available on RubyForge, so why don’t people use it?
I’d like to know how many people use git on RubyForge. Apparently you can have your old SVN repository manually migrated to git, if you ask nicely (and RubyForge people are very helpful always, anyway). Still, I don’t think many people use git there, and hardly anyone (if any) moved back from GitHub.

What’s so special about this new “social code hosting” site then? I guess just a few key features:

Fast and reliable git hosting
The ability to “watch” other people’s repositories and interact with them “the git way”, also by forking.
There’s a whole new and fresh community feeling to it: you can follow people, message them, etc.
The interface is much more neat than RubyForge’s (OK, granted, it doesn’t take much)
Really cool stats and graphs
A basic, but functional, wiki

…oh, and bug tracking, too!

GitHub has no bug tracking features. It tracks an awful lot of stuff about your repositories and people working on them, but “batteries are sold separately”. You can get batteries here, for example. Apparently, GitHub and LightHouse are seamlessly integrated.

So now you can sign up to two cool brand new web applications with neat interfaces instead of sticking with the old-looking RubyForge (which comes with “batteries included”, after all).
Personally I’m very confused now. Fortunately I don’t have any extremely cool projects used by thousands of people, so jumping from one source code hosting solution from another is not really an issue for me, but I imagine it would be for others! Correct?

So, as far as I know, if you are a Rubyist, here’s what you can do:

Stick with RubyForge: it’s not so bad after all.
Embrace GitHub (and Lighthouse): it’s extremely nice to use. Some people are not too convinced that this is the best choice though.
Go for something in between, like Assembla, which actually has an impressive list of features and is powered by Rails too, so you’ll feel at home. Google Code used to be another common choice, but sadly they don’t offer git yet.
Do-it-yourself, maybe using something like Gitorius and some open source bug tracking/project management solution.

So… what choice did you make or are you planning to make?

Moving houses

There’s one simple issue to consider when moving your code to a new place: what happens to your old place. If have a relatively popular project, a lot of people may have bookmarked your project page on RubyForge, or the RubyForge subdomain which you may have used as the “home page” for your project (in truth, most of the ones who moved away still use it).

You may setup a redirection to the new home page or put a notice saying that the project moved somewhere else and point visitors to GitHub and LightHouse, or to another web site, if you wish. When Rails moved to GitHub, that wasn’t much of a problem as Rails has its own web site.

What may become a problem is your old repository. In Rails’ case, they left the old SVN repository available on sourceforge for a while and then removed it altogether. Other project owners have just abandoned their old repositories, occasionally resulting in someone else deciding to leave a note as their last SVN commit.

These solutions all work (you eventually drive people to the new home of your project), but it’s not very nice, that’s all. What happens if someone comes up with something cooler than GitHub? In all honesty, you may end up moving house over and over again.

Don’t forget the gems!

One thing I liked about RubyForge, as I wrote at the beginning, was that if you uploaded a gem there, it was immediately available to everyone typing gem install <something>.
Luckily, GitHub supports gems, too! We’re saved. The page they put up is utterly awful, but it does the job: you can have your gems hosted on GitHub.

Good! So surely I can get Rails now, right? Yup: gem install rails will get the latest version of Rails for you, straight from GitHub.

Actually, no. It doesn’t seem to work that way: sure you can get the latest rails in that way, but it will actually be downloaded from RubyForge (go check the downloads, you’ll see it there).
So even if technically you got Rails, you got it from RubyForge. If you want to get gem from GitHub, you have to add it as gem source first (that’s an una tantum operation, luckily): gem sources -a http://gems.github.com.

So, yes, you can move to GitHub and you’ll also get gem support: but please remind the users that they have to add GitHub as gem source. Or, better, you should always remember to upload your latest gems to GitHub and to RubyForge as well.

The present

To sum up:

If you want, you can stay on RubyForge. It has git, it has gems, it’s probably not nearly as prettier than competitors and is not as social, but it works.
You can opt for GitHub+LightHouse, have a slick interface, plenty of features and your project will be scattered in 2 different places + your home page, and you’ll also have to keep uploading your gems to RubyForge.
At this point, you may even go for something completely different, like Assembla or your own setup, but still upload your gems to RubyForge.

The obvious solutions at this point would be that the folks who craft rubygems (the gem which makes the gems, to be clear) add GitHub as default source. Sure as hell when that happens other people will want that too (hey, I’ll have gems.h3rald.com setup by then!). Is this the future? I hope not.

The future?

You know there’s a domain called www.rubygems.org? It’s where the gem manuals are!
As much as I love documentation, there’s nothing wrong in moving all those documents and books to something like docs.rubygems.org, right?
Then they could make RubyGems.org the only official gem server and tell people they should upload their gems there if they want to distribute them efficiently (after manual approval, if necessary, like there is on RubyForge).

In this way:

You wouldn’t have to upload stuff to RubyForge anymore
You could have the clever folks at GitHub to create a simple script to automate the upload
You’d have virtually all the gems in one place
You’d put a good domain name (currently almost forgotten) to good use

While they are at it, the clever folks at RubyGems.org could also setup a proper gem directory with a proper search. I’m sure there would be plenty of people who could help, too!

It’s not impossible, right? They said that making Rails/Ruby/RSpec documentation more accurate and accessible was impossible, but now there’s APIdock, correct?

Personally I’d like it to be a collaborative effort of the Ruby community (like ruby-lang.org), rather than one private company showing off, but I think everyone will be happy as long as it works.
I’m sure people will contribute, I would try at least (after finishing the Italian translation of ruby-lang.org, that is… erhm, well, that’s another story…).

Thoughts?

Rails-powered Open Source Killer Apps, Anyone?

h3rald@h3rald.com — Sun, 02 Nov 2008 09:41:00 -0000

Lately I’ve been meandering around the web to find a good CMS for a family site I’d like to set up.
Why a CMS? Well, for a few simple reasons:

I don’t have enough free time to fiddle with Rails and make my own (I’m an Hobbyist Programmer™: I code for fun and enlightment, not for money)
Even if I had the time, I’m sure there are plenty of CMSes out there which suits my needs.

It turns out that reason #2 is not really applicable in this case, especially if we restrict the field to Ruby + Rails/Merb/<insert cool DRY framework here>.h3. Rails-powered CMSes

Name a Rails-powered CMS, quick!

Easy: Radiant.

Hmm, no. As much as I do like Radiant, it really cannot be considered a general-purpose CMS, can it? When it comes to build nearly-static sites in a clean and neat way I’d pick it any day, but it lacks quite a lot of community features like comments, ability to create forums, etc. etc. It does, however, support multilingual content in a rudimentary, yet effective way: create each translated page manually and use consistent URL conventions (/en/about, /it/about, etc.).

I’m not saying that there aren’t enough CMSes built on Rails, just that there’s no “killer app” in the pack. A “killer” CMS would be something as powerful as Drupal, but easier to use and more modular.

Here’s an incomplete list of the Rails CMSes I’m currently aware of:

Name	First Impressions/Comments
Radiant	Mature, suitable for administering static sites
Typo	Mature, one of the best blogging engines out there (my opinion is slightly biased though)
Mephisto	Mature, blogging engine
Rubricks	Under development, basic features if compared to other non-Rails solutions
Slate	Missing a lot of features if compared to competitors
Beast	Forum engine, extremely ligtweight
RailFrog	Not sure if it’s still being updated, not so many features
Zena	Alpha, looks promising although it doesn’t offer many features
simplelog	Yet another blogging engine. Simple and easy to use
oooopen rcms	Early development stage (dead?), minimal feature set
Geego	Multilingual, not so many out-of-the-box features

[Psst, if you know any other Rails CMS I missed out, mention it in a comment and I’ll update this table!]

Developing Proprietary Web Applications with Rails

What’s wrong with all of these? Normally one of three things: either they are mature, production-ready but focused on only one particular function (blog, forum, etc.), or they are still too new to be used seriously or they are slowly heading towards oblivion.

What’s going on here? Rails is a damn fine framework which offers all the modularity and power you need to build sites! Why isn’t there a fully fledged CMS to rival Drupal?
I think that part of the problem is that Rails is too good. Why build a CMS from scratch when you can develop a web site from scratch much more easily, tailored to your customer?

Rails has been used to build a few “mainstream” sites like Twitter (no bashing please!), Basecamp, GitHub and many more. What do these sites have in common? They are not open source. You cannot deploy your own Twitter on your server (You can with Laconica, though), you cannot deploy your own Basecamp to your server (you can with ProjectPier, an open source fork of ActiveCollab).

It feels like that even though Rails itself is open source, there aren’t that many open source Rails-powered projects after all. Maybe there are, but they do not really compare with similar alternatives offered in other languages. This is the reason why, despite its utter ugliness, PHP is still the Open Source King of the Web, and that’s very, very sad in my opinion.

Dreams on Rails

The annoying thing is that Rails is suitable to build CMSes, and good ones, too! Take Radiant and Typo, for example: they both excel in their own ways, in their own worlds.
Theorethically speaking, there’s no reason why someone couldn’t develop a modular system to glue different components together: you’d need common user administration and common workflow, a few hooks, and a solid set of conventions on how to build third-party components.
Hell guys, the folks at Drupal developed a huge (and successful) product with a million different ways to extend it in PHP. Even without using OOP! Every damn hook in the core is a function.

What does it take to do something like this using Rails, o Merb, or whatever else you like? You already have a very solid and consistent framework to build on (Rails), a way to automate tasks (Rake) and a language which lets you do everything you want, in a very elegant and organized way.

Rails lacks successful open source projects, in particular CMSes. I wish someone could fix this: not by coding the n^th^ CMS with the only two or three features you need, but by developing an high level application framework to build complex, dynamic and interactive web sites. Don’t even develop the whole damn thing: just come up with a set of conventions on how to extend a very basic core, and tell people how they can contribute, or even integrate existing applications into it.

The community will do the rest, hopefully… Or maybe are you too busy trying to roll out your newest, closed source startup?

If someone decides to develop such a powerful, high-level framework and is determined to keep it user-friendly and open source, I hereby promise to write the documentation for it, articles, and books. And I’m not kidding.

[UPDATED] A Glimpse of Hope

A few of the commenters of this article brought up a few interesting points and actually gave me a little bit of hope. Luigi Montanez pointed out that Rails was built to help developers build web sites. For now, Rails deployment isn’t as seamless as end users would like it, so there’s no point creating a killer app for such users if they can’t even get it to run on their $2/month shared hosting environment.
Nevertheless, there seems to be at least three different open source “social network engines” powered by Rails:

These are not CMSes in the early 2000’s sense, obviously, but they do provide the basis to effectively build a late Web 2.0-ish community web site. Each one of these project seems stable and mature enough to be used in production, but surely not as well-known as many other PHP-based solutions.

On the other hand, Priit Tamboom mentioned adva cms, a project still in alpha stage which aims to be more traditional and site-agnostic:

“[…] Different from other Rails applications the all-engines approach of adva cms allows you to build your own applications on top of it. It also makes it very flexible and extensible: our plan is to make it possible to only pick those engines/features that you really need for your application and omit the rest. As they are still all designed to work together seemlessly and reuse each others functionality the whole plattform feels much more consistent to a collection of similar but separate Rails applications. […]”

This sounds exactly like what I was hoping would come out from the Rails community: something in between a web development framework and an high-level CMS.
I’m definitely going to try it out (it’s an ideal weekend project) and I’ll report back once I know more about it.

Rails-Doc.org - A First Look

h3rald@h3rald.com — Thu, 19 Jun 2008 05:30:00 -0000

When you decided to learn Ruby on Rails (if you did, that is), chances are that you bought a book. I did, too, actually: there are a lot of very interesting and fairly comprehensive books out there after all.

I actually never bought a book to learn PHP, in the past though. Why’s that? Well, for two simple reasons:

The PHP manual can easily be searched and provides enough documentation, in most cases.
When the documentation is not enough, there’s always plenty of comments by experienced developers to save your day.

That being said, PHP is still an awfully disorganized language, but believe it or not, coming from PHP I didn’t find Rails documentation useful enough simply because it didn’t have these two simple but very powerful features.

Sure, there’s the Rails Documentation Project which provides more organized docs, and Noobkit does a nice job with its search-as-you-type feature… but still is not quite enough: you’d expect something much better than that for something like Rails!h3. Introducing Rails-Doc.org

Rails-Doc.org focuses on providing a better interface to Rails documentation by offering two key features:

A powerful, fast and useful document search
The possibility to add notes to Rails documentation

When the app went live, I immediately registered (it’s free of course) and started playing with it…

Search as you type…

The first thing I did was trying the search features, of course. I started typing “rout” for Routing, and I was immediately shown a list of matches:

It took a small fraction of a second to load the matches, which makes me think that definitely they have all the names indexed somewhere. Nevertheless, it was a pleasant surprise: normally, these search-as-you-type utilities are not that refined!

All you need to do is start typing at least three letters, and you get results, if any.
if you press ENTER, you get automatically redirected to the first result. This can be good, but maybe it would have been nicer to load a “traditional” list of results, but it depends on your taste, really.

…or browse through the namespaces

Alternatively, it is possible to browse the docs in the more traditional way, i.e. according to their class or module: the Browse page does just that: it lists all Rails classes and modules, regardless of the nesting. But there’s more: a little roundy icon precedes each class name, to indicate whether the documentation is present, and to what degree:

This is an interesting concept: in this way, in theory, people should contribute to the documentation where it’s more needed.

Each reference page is very neatly re-formatted: you can hardly imagine it’s actually the same content included in Rails’ RDoc pages!

Finally, another nice addition is the Related column, which lists links to other items which are related to the current topic:

Contribute, contribute, contribute!

You have to register for something, don’t you? Yes. If you register, you can post notes to any document. Simple enough, all you have to do is to click the Add Note button and a form will slide down for you to fill in:

As you start typing, you’ll notice that a preview of the note is displayed instantly: as you can use SimpleMarkup to write notes, exactly like in RDoc, this feature can be very handy:

What if there’s no documentation for a particular class or method? You’ll get a warning like this one:

The idea behind this is that, if you provide some useful insights, they’ll eventually end up in Rails core documentation.

An Short Interview with Mikael Roos, from Nodeta

Before the application went live, I was lucky enough to get Mikael Roos to answer to some of my questions. Here’s the full interview…

What are you actually trying to do on Rails-Doc.org?

The initial goal of the project is to provide the existing documentation in a more accessible way, most importantly to provide a lightning fast search feature that gives weighted results based on the
quality and amount of documentation. This we have already accomplished, and all remaining issues are related to browser compatibility. Another initial goal is to present a smooth interface for creating inline notes to
the documentation so that Rails developers can post notes about certain methods etc. for themselves and others to draw knowledge from.

Our longer-term goal (N.B. we are an agile project, so long-term means, say, three months) is to provide a way for the active members of the Rails community to improve the existing documentation based on the posted notes
to create an extended documentation that could optimally even be made in to a patch and would find its way back into the actual Rails source.

Another clear and obvious goal is to keep improving the service steadily as we progress toward the goals that I mentioned above.

Could you spend a few words on the “development process” followed by your company to develop this app? Did I read the word “Scrum” somewhere? Am I correct?

Yes, our development process of choice is Scrum. The core team is only three members, one backend developer, one backed/frontend develope and one frontend developer/UI specialist. I feel the team is optimal in many ways.
The team also has a few more experienced developers who are primarily active in other projects to ask questions from, one of whom is also the acting product owner on the Rails-doc project (that’s me!).

Did you develop it in three months, or…?

The first release was developed in three SPRINTS, not months – so what I’m saying is the first release was developed in five weeks (first sprint was mostly introductory and lasted a week, the next two sprints, first
development and then stabilization, were two weeks each). However, it is a FIRST RELEASE, which means the app is by all means not complete, but since we make software in a very agile way, it’a all about “Ship, ship, ship!”.

What is Nodeta, exactly? My Finnish is a bit rusty nowadays…

Nodeta is a software development company that focuses on web software. We employ a highly agile and effective process. We have worked both on light independent projects and in the environment of large global enterprises.
There are currently 10 Nodetans.

Rails-Doc.org is a pilot project for your new shiny app, ApiDock. Is it an open source app?

Unfortunately, I cannot go into details about APIdoc yet. What I can tell is that it is developed with Rails and that it won’t be open source, but rather it would optimally be offered as a service, which after all is what
the word “app” on the web means these days. Open source projects could however use it for free, sort of in the spirit of GitHub.

It will also most likely be separately targeted to larger companies.

Can you give me more technical details about the way keyword search is performed? Are you indexing/tagging documentation beforehand?

There will probably be a blog post on the Nodeta blog about the search and how it works after the first release comes out.

What about the social side of it: you’re hoping people will contribute with notes, which will then be collected and integrated in the documentation correct? Do you have any moderation or anti-spam precaution?

The quality of notes is judged in a social way. Notes can be thanked by other users and notes that get many thanks are showed in a more prominent way. Registration will be required in order to post notes and the registration will feature a captcha.

Will contributors be credited somehow? Who can contribute and at what level?

Anybody can post notes and good notes get thanks and thus so do their posters. Users that get lots of thanks will be later asked to become core users that can alter the extended documentation (not in the first
release.)

You want to blow out competition and that you don’t want to fail: sounds a good plan! How is Rails-Docs different from other similar apps?

We think that our app is the first that is serious about making things happen. We think about users first and above all at this stage our search feature is frankly unparallelled.

Do you have DHH’s seal of approval? Will you? Is there any copyright issue with your domain name?

Time will tell what DHH thinks. We did contact him just a few days ago to ask what his thoughts about all this are and are waiting for his comments. I doubt there is any wrinkles with copyright as Rails-doc itself is a completely non-profit project.

What about doing something similar for the whole Ruby language? Ruby docs may also be easier, in a way…

It is possible that we might do just that but right now it’s all about Rails.

The Bottom Line

Rails-Doc.org is definitely an interesting project, which has all the potential to become a powerful, Rails-powered service. Sure, it’s not open source and this can be a bit of a letdown for some: but after all people flocked to GitHub when it opened, didn’t they?

The search capabilities of Rails-Doc.org are definitely a very important step forward in making Rails documentation more accessible and easier to use, but the killer feature is definitely the possibility to add notes, if used wisely.

I’ll be watching this project closely and I’ll pay particular attention on what happens to the community’s contributions: will it really be useful? Will it really help creating documentation patches to Rails core? Only time will tell, of course.

Book Review: Design Patterns in Ruby

h3rald@h3rald.com — Fri, 11 Apr 2008 03:41:00 -0000

I finally got my hands on a shiny new copy of Design Patterns in Ruby¹. The book itself is not brand new and it was already widely praised by many different people online, so I wanted to take a look for myself.

To my surprise, the book is a hardcover edition, which makes it look more professional and more durable than the average programming book². It’s also smaller and shorter than the average programming book² (340 pages), which makes it much easier to carry around and less intimidating to read. It’s also not meant to be a reference book, so it is actually pleasant an easy to read all in one go, as you’ll soon find out.

What is it about? — well, design patters in the Ruby language of course. But it’s not the usual brainwash of programming theory you would expect by a typical book on patters, it has plenty of examples of real code. When I say real code I don’t mean the usual Dog/Cat/Horse/<insert animal here> classes or juke-box simulations which don’t work at all etc. etc., I mean actual snippets from well known Ruby applications, like RubyGems, FXRuby and, of course, Rails.
OK well, there’s an exception perhaps: Russ did include a few wild life simulations (ponds with frogs and similar), but it’s only for your own good, and for the sake of tradition.

Anyhow, let’s start from the beginning…

Part I: Patters and Ruby

The first part of the book serves as a general introduction to the other two parts. If you know the basics of both design patterns and Ruby, you can safely skip this as you won’t find anything of overwhelming interest here.

Personally I really liked Chapter 1 though, “Building better Programs with Patterns”, in which Russ does a great job in summarizing the original GoF book³ into four points:

Separate our the things that change from those that stay the same.
Program to an interface, not an implementation.
Prefer composition over inheritance.
Delegate, delegate, delegate.

Also, although it does not come from the Design Patterns book but from building real systems, the author adds the YAGNI (You Ain’t Gonna Need It) principle⁴ as a reminder to resist the temptation of implementing things which may be needed later on, even if they are not needed right now.
The chapter ends with an outline of the patterns which will be presented throughout the book: 14 out of the original 23 patterns by the Gand of Four will be discussed in Part II and 3 bonus “Ruby-only” patterns will be examined in Part III, as a special treat.

Chapter 2 (Getting started with Ruby) feels perhaps a bit out of place. As others pointed out⁵, why does a book on advanced Ruby programming techniques include a 35-page-long introduction on the Ruby language? The answer was given by Russ himself in an interview⁶:

“The reason that I included the introductory chapter about Ruby in there was to make the book accessible to folks with little or no Ruby background.
Now honestly, I don’t think that you could come to my book with no background in Ruby and walk away from it an expert Ruby programmer — it’s not really that kind of introductory book.
But I do think that someone with experience in other languages could read my book and come away knowing about Ruby, understanding what all the shouting is about.”

I admit, I skipped this chapter during my first reading because I was eager to move on to the main part of the book, but I did read it afterwards (I had to write this review after all!). It’s quite a nice introduction aimed at the average .NET/Java developer: Russ provides a step-by-step presentation of the main features of the language while holding the reader by hand when something weird or scary comes about:

The slightly strange-looking syntax in this code is actually a tip-off something deep and important: In Ruby, everythng — and I mean everything — is an object.

Of course Chapter 2 won’t turn you into a Ruby guru, but it definitely fulfills one of the author’s goals: bringing developers of other languages closer to Ruby, and give them a tiny taste of how Ruby can be wickedly powerful.

Part II: Patterns in Ruby

Part II constitutes the bulk of the book, describing 14 GoF patterns in 220 pages. The patterns covered are the following:

Template Method
Strategy
Observer
Composite
Iterator
Command
Adapter
Proxy
Decorator
Singleton
Factory Method
Abstract Factory Method
Builder
Interpreter

Why not covering all 23? Well, because to be honest, they are rarely used in Ruby. Furthermore, in some cases some of the ones examined in the book may feel a bit unnatural to the average Rubyist: how many times did you ever think about using an External Iterator when each is normally available as default internal iterator for any Array-like class?

Each chapter in this part is devoted to a particular pattern and it is organized in more or less the same way, as outlined in the following sections.

Introduction and Personal Anecdotes

Most chapters start with a personal anecdote involving the author: it may be a memory related to his first job at the local grocery store (Chapter 8), or about the day he decided to buy his son a bike (Chapter 14):

“I remember the day we bought my son his first bike.” […] I spent hours trying to pull together a minor junkiard of parts according to instructions that would have baffled the entire National Security Agency. As it turned out, picking the bike was the easy part: putting it together was the real challenge.

This was used to introduce the Builder pattern, and how to use it to configure objects which include different logical parts.
Personally I find this technique particularly useful to introduce a particular problem from a different, more mundane prospective instead of starting off with an abstract theorethical description of the pattern itself.
The anecdote is then followed by the description of the actual programming problem for which the specific pattern will be used.

Description of the Pattern and Initial Implementation

An initial implementation of the pattern in Ruby will be provided more or less immediately after the introduction of each chapter, often accompanied by a simple UML diagram.
This implementation normally has quite a few conceptual flaws, which are then examined and corrected step-by-step the chapter to obtain a more “Ruby-friendly” solution.

A More Rubyfied Version of the Pattern

The final implementation of each pattern is often very different from the initial attempt, and it may contain quite a lot of Ruby-specific code. The author does an excellent job in suggesting pattern implementations which often use blocks, Proc objects or method redefinitions when needed, to make the code more succint and more readable at the same time, as all Ruby code should be.

By doing so, even people who are still learning Ruby will understand how to use some very useful Ruby idioms which can be a bit difficult to grasp otherwise.

Using and Abusing <Pattern>

Patterns are often overused and misused, and some people normally end up wondering if they should be used at all, after all. This section (present as a matter of fact in every chapter of part II an III) examines the pitfalls of the pattern and the most common mistakes developer make when applying it.
It is by far the most useful section of each chapter, and that’s what I’ll be reading and re-reading every time I’m thinking about using a particular pattern in my code. As a matter of fact, these sections make you realize that every pattern has its own inherent flaws and dangers, and that it is far from being a Silver Bullet. Even when you’re supposed to use a pattern to accomplish something, be aware that something nasty can happen unless you’re extra careful: this, perhaps, is the true Golden Rule conveyed throughout the whole book.

<Pattern>s in the Wild

This is another very interesting section which is included in every chapter of part II and III. After describing what a pattern does, how it can be used and how it should be used, you’ll finally find some interesting examples taken from real world applications.
By “real world application” I mean something like ActiveRecord⁷ (Observer, Command, Adapter, …), DRb⁸ (Proxy) or FXRuby⁹ (Composite), for example, i.e. important programs and libraries which are used in production environments.
Personally, I was really glad to find such examples in this book: it definitely helps you feeling design patterns as something more practical and useful than pure software architecture theories.

Wrapping it Up

“Wrapping it Up” is the title of the last section of each chapter of Part II and III. It’s basically a summary of the whole chapter and thus a useful way to recap the most important concepts. I found this section particularly useful when using the book as a design pattern reference, after reading it for the first time: this section provides a quick and essential overview of each pattern — and the most important DOs and DON’Ts, too.

Part III: Patterns for Ruby

By the time you get to Part III you’ll definitely feel that Ruby can do more_. Some of the Ruby implementation of certain patterns described in the book make extensive use of blocks and Proc objects, and the @methodmissing@ method (although potentially dangerous unless extra care is taken) gives us a more immediate way to obtain delegation, for example when creating Proxies.
Also the fact that objects can be modified at runtime by adding and removing methods “as needed” seems quite an underused feature in traditional patterns, simply because those patterns were first conceived for languages which are very different from Ruby and are perhaps less liberal than Ruby when it comes to dynamic features¹⁰.

These particular Ruby features can be used (and abused, of course) to implement more Ruby-esque patterns, such as the ones included in this part of the book:

Internal Domain-Specific Languages
Meta-Programming
Convention Over Configuration

These are just examples, of course some may complain because the Active Record or ORM pattern are missing, but this is understandable as it may be considered too specific compared to the others.
Each pattern is examined in detail, and I particularly like way the DSL pattern was described: Chapter 16 explains how to develop a simple but effective Ruby DSL from scratch for creating file backups. This can be particularly useful for people who never tried creating DSLs before, but also for developers who tried, but want to improve their skills.

Chapter 18 (Convention Over Configuration) is sufficiently clear and detailed, perhaps even too much if you already know how Rails was developed (and all the hype which follwed).

On the other hand, I was a bit disappointed by Chapter 17 (Meta-Programming). Maybe it’s because I built up extremely high expectations about it while reading the rest of the book, but it just felt too short and not detailed enough for my liking. If I had to write such a chapter (which would have been actually very hard), I would have started from an excellent post by Ola Bini¹¹ which introduces eleven meta-programming techniques, and built up content and examples from there. The only reason why — I think — Russ didn’t do it in his book was length/balance constraint: a properly detailed chapter about meta-programming in Ruby could easily take up over forty pages!

The Verdict

As I said in the beginning: this is not meant to be a complete, in-depth, reference book on everything you may want to know about design patterns in Ruby. That’s why, as a matter of fact, you can actually read this book all the way through without getting utterly bored. Russ uses an informal, yet appropriate style to turn potentially complex, theorethical computer science principles into easy-to-understand, useful tools which can truly improve the way you code.

The whole book flows very very nicely. I actually recommend reading this book in sequence, without skipping chapters, because each pattern is described in a way that is somehow linked to the following ones, so that you can understand and learn about the pros and cons of each one in a more natural and useful way.

OK, I would have loved to see Part III as long as Part II, probably, but overall I’m very, very satisfied of what the book taught me. The only problem is that it also made me suddenly realize all the naive design mistakes I’ve been making when coding in Ruby, so I’ll now feel compelled to fix at least some of them…

Definitely a worthwhile read, I just hope to see more books like this, or even a second edition of this one soon!

Notes

¹ Design Patterns in Ruby by Russ Olsen, Addison Wesley Professional, 2007.

² Think of Programming Ruby: The Pragmatic Programmer’s Guide, 2nd Ed. by Dave Thomas with Chad Fowler and Andy Hunt, Pragmatic Programmers, 2004.

³ Design Patterns: Elements of Reusable Object-Oriented Software, by By Erich Gamma, Richard Helm, Ralph Johnson, John M. Vlissides (a.k.a. the Gang of Four), Addison Wesley Professional, 1994.

⁴ For more information on the YAGNI principle, visit You’re NOT gonna need it, Ronald E Jeffries.

⁵ See Design Patterns in Ruby, a review, On Rubyblog.

⁶ See Russ Olsen Interview, On Rubyblog.

⁷ ActiveRecord is an implementation of the Object-Relational Mapping (ORM) pattern used by the Ruby on Rails framework.

⁸ Distributed Ruby, see Intro to DRb by Chad Fowler.

⁹ FXRuby, a graphical toolkit written in Ruby.

¹⁰ This can be a good or bad thing depending on the way you look at it, and what you want to use the language for. The fact that Ruby is dynamically typed makes it easier to do things which are totally impossible in C++ or Java, but it also introduces a whole new set of potential dangers.

¹¹ Ruby Metaprogramming Techniques, Ola Bini: Programming Language Synchronicity.

New Release: RawLine 0.2.0

h3rald@h3rald.com — Wed, 02 Apr 2008 03:33:00 -0000

~~InLine~~ RawLine 0.2.0 is out!

*Raw*Line is the new name for InLine, in case you didn’t guess. The name was changed to avoid name collision problems with the RubyInline project.

Here’s what’s new:

Added /examples and /test directory to gem.
Escape codes can now be used in prompt.
It is now possible to use bind(key, &block) with a String as key, even if the corresponding escape sequence is not defined.
Added Editor#write_line(string) to print a any string (and “hit return”).
Library name changed to “RawLine” to avoid name collision issues (Bug 18879).
Provided alternative implementation for left and right arrows if terminal
supports escape sequences (on Windows, it requires the Win32Console gem).

In particular, I decided to provide an “optimized implementation” for the left and right arrows using escape sequences rather than shameful hacks. This is now possible because the Win32Console gem now enables ANSI escape sequences on Windows as well (weehee!).

So:

If you’re on *nix all good, your terminal is smart and can understand escape sequences => the new implementation will be used.
If you’re on Windows and you installed Win32Console, your termnal is smart and can understand escape sequences => the new implementation will be used.
If you’re on Windows and you didn’t install Win32Console, then your terminal is stupid and it doesn’t understand escape sequences, so the old implementation will be used.

The new implementation is significantly faster than the old one, on Windows at least, and the cursor now blinks properly when left or right arrows are pressed.

I re-emplemented only cursor movement because I’m still having some problems in getting the delete/insert escapes to work properly (or better: how I want them to work!).

InLine name change: what's your opinion?

h3rald@h3rald.com — Thu, 27 Mar 2008 05:30:00 -0000

I’ve been kindly asked by the lead developer of RubyInLine to change the name of my InLine project, due to potential confusion and conflicts.

This makes sense, and I’m ready to change the name of my project, although I’m not that good at choosing original and smart names, so well, any suggestion is more than welcome!

I was thinking of something like:

RawLine
EditLine
RawInput
RubyInput
RubyLine

I personally think that RawLine is probably the best option, but please, if have any better idea just speak up!

P.S.: “RedLine” is taken, unfortunately, otherwise it would have been my first choice since the beginning.

RawLine - a 100% Ruby solution for console inline editing

h3rald@h3rald.com — Mon, 10 Mar 2008 05:59:00 -0000

One of the many things I like about Ruby is its cross-platform nature: as a general rule, Ruby code runs on everything which supports Ruby, regardless of its architecture and platform (yes, there are quite a few exceptions, but let’s accept this generalization for now).

More specifically, I liked the fact that I could use the GNU Readline library with Ruby seamlessly on both Windows and Linux.
Readline offers quite a lot of features which are useful for those people like me who enjoy creating command-line scripts, in a nutshell, it provides:

File/Word completion
History support
Custom key bindings which can be modified via .inputrc
Emacs and Vi edit modes

Basically it makes your command-line interface fast and powerful, and that’s not an overstatement. Ruby’s own IRB can be enhanced by enabling readline and completion, and it works great — at least on *nix systems.

For some weird reason, some people had problems with Readline on Windows: in particular, things get nasty when you start editing long lines. Text gets garbled, the cursor goes up one or two lines and doesn’t come back, and other similar leprechaun’s tricks, which are not that funny after a while.

Apparently there’s no alternative to Readline in the Ruby world. If you wan’t tab completion that’s it, you’re stuck. Would it be difficult to implement some of Readline functionality natively in Ruby? Maybe, but the problem is that for some reason the Ruby Standard Library doesn’t have low level methods to operate on keystrokes…

…but luckily, the HighLine gem does! James Edward Gray II keeps pointing out here and here that HighLine’s own get_character method does just that: it returns the corresponding character code(s) right when a key is pressed, unlike IO#gets() which waits for the user to press ENTER.

Believe it or not, that tiny method can do wonders…h2. Reverse-engineering escape codes

So here’s a little script which uses get_character() in an endless loop, diligently printing the character codes corresponding to a keystroke:

#!/usr/local/bin/ruby -w

require 'rubygems'
require 'highline/system_extensions'

include HighLine::SystemExtensions

puts "Press a key to view the corresponding ASCII code(s) (or CTRL-X to exit)."

loop do

	print "=> "
	char = get_character
	case char
	when ?\C-x: print "Exiting..."; exit;
	else puts "#{char.chr} [#{char}] (hex: #{char.to_s(16)})";
	end
	
end

A pretty harmless little thing. Try to run it and press some keys, and see what you get:

Press a key to view the corresponding ASCII code(s) (or CTRL-X to exit).
=> a 96 (hex: 61)
=> 1 49 (hex: 31)
=> Q 81 (hex: 51)
=> α 224 (hex: e0)
=> K 75 (hex: 4b)

Hang on, what are the last two codes? A left arrow key on Windows, apparently.

Welcome to the wonderful world of input escape sequences!

To cut a long story short, both Windows and *nix system “terminals” translate special keystrokes into sequences of two or more codes. This applies to things like DEL, INSERT, arrows, etc. etc.
For some ideas, check out:

Windows Scancodes (Thanks Huff)
VT220 Terminal Input Sequences (Thanks James)

Let’s now assume that we’re smart and we can write a program which can parse keystroke properly, including handling different input escape sequences according to the OS, what can it be used for?
Well:

For normal characters, just print them back to the screen (get_character doesn’t print anything, it “steals” the keystroke)
For special characters, do something nice!

We could setup TAB to auto-complete the current word according to an array of matches, or bind the up arrow to load the last line typed in by the user, for example, that’s basically something Readline does, right?

RawLine: how it works and what it does

I created a small project on RubyForge called RawLine (not to be confused with RubyInline, a completely different thing altogether, sorry about that) to play around with the possibilities offered by the get_character method. The library is just a preview of things which can be done, but it’s already usable, provided that you’re brave enough to try it out, that is.

The basic idea behind RawLine is to be able to parse keystrokes properly on different platforms and re-bind them to a set of predefined, cross-platform actions or a user-defined code block.

Basic line-editing operations

The first challenge was to re-invent the wheel, i.e. re-bind keystrokes to their typical actions: a left arrow moves the cursor left, a backspace deletes the character at the left of the cursor and so on. Yes, because get_characters gives you the right character codes at the price of cancelling their normal effects, which is a great thing, as you’ll soon find out.

Printing a character on the screen was one of the easiest tasks (at first). IO#putc does the job pretty well: it prints a character out.
What about moving left? Easy: print a non-descructive backspace (\b) and hope it is really not destructive. I did some tests and it seems to do as it’s told and move the cursor back by one position.

Moving right was a little trickier: the easiest thing I found was to re-print the character under the cursor, which will then move the cursor forward (as naive as it may seem, it does the job!). If there’s nothing under the cursor, then we must be at the end of the line and it shouldn’t move anywhere, so there we go.

What if I move left a bit and then start typing normal characters? Well, everything is rewritten of course: this will be our “character replace mode”. Unfortunately users don’t like this behavior that much, so what I did was this:

Copy all characters from the one at the left of the cursor till the end of the line
Print the character to be inserted
Re-print the previously-copied characters
Move the cursor back at the right place

Again, a primitive solution which works seamlessly on all platforms, and yes, it’s fast enough that you don’t notice the difference.

As you may have guessed, this of course means that I always had to keep track of:

The cursor position within the line
The text currently printed to the screen

Backspace and delete were implemented in a similar way, you can figure it out yourself or look at the source code: I won’t bore you any further!

History management

The next step was to implement a history for both the characters inputted by the user (to allow undoing and redoing operations) and for the whole lines. This was just an ordinary programming exercise: a simple buffer with some extra controls here and there, nothing too scary.

So every “modification” to the current line being typed is saved in a line history buffer and all the lines entered are saved in another history buffer. All is left is to allow users to navigate through these buffers back and forth.
Nothing impossible: all I had to do was keeping track of the current element of the history being retrieved and then overwrite the current line with a new line stored in the buffer? How’s this line overwriting done? Same old:

Move the cursor to the beginnig of the line
Print X spaces, where X is the line length, so that the characters are no longer displayed in the console
Move the cursor back to the beginning of the line
Print the new line.

Easy and naive, as usual. But again, it works well enough.

Word completion

The other challange was word completion. The current implementation can be summarized as follows:

If TAB (or another character, if you wish) is pressed, call a user-defined completion_proc method which returns an array and show the first element of the array (in this case I actually used a cyclic RawLine::HistoryBuffer, not an array)
If the user presses TAB again, show another match, and so ad infinitum if the user keeps pressing TAB.
If the user presses another key, accept the default completion and move on.

Obviously this means that:

RawLine has to keep track of the current “word”. A word is everything separated by a user defined word_separator, which can obviously modified at runtime, with care.
Regarding the completion_proc, typically you may want to return only the elements matching the word which is currently being written, so that’s given as default parameter for your proc. Exactly like with ReadLine, the only difference is that you can access other things like the whole line and the whole history in real time, which can be really handy at times!

Here’s a simple example:

editor.completion_proc = lambda do |word|
	if word
		['select', 'update', 'delete', 'debug', 'destroy'].find_all	{ |e| e.match(/^#{Regexp.escape(word)}/) }
	end
end

Custom key bindings

All these pretty things are obviously bound to some keystrokes. If the key corresponds to only one code, everything is fine, but because special keys typically aren’t so it was necessary to implement a mechanism to track an escape key (e.g. 0xE0 and 0 on Windows and \e on Linux) and listen to further characters, in case a known sequence is found. Anyhow, the final result of the method used for character binding is the following:

bind(key, &block)

Where key can be:

A Fixnum corresponding to a single character code
An Array of one or more character codes
A String corresponding to an escape sequence
A Symbol corresponding to a known escape sequence or key
A Hash to define a new key or escape sequences

So, in the end you can do things like this:

editor.bind(:left_arrow) { editor.move_left }
editor.bind("\etest") { editor.overwrite_line("Test!!") }
editor.bind(?\C-z) { editor.undo }
editor.bind([24]) { exit }

Which, for Rubyists, it’s far sexier and more flexible than editing an .inputrc file.

How do I use it, anyway?

A code example is better than a thousand words, right? So here you are:

#!/usr/local/bin/ruby -w

require 'rubygems'
require 'rawline'

puts "*** Inline Editor Test Shell ***"
puts " * Press CTRL+X to exit"
puts " * Press CTRL+C to clear command history"
puts " * Press CTRL+D for line-related information"
puts " * Press CTRL+E to view command history"

editor = RawLine::Editor.new

editor.bind(:ctrl_c) { editor.clear_history }
editor.bind(:ctrl_d) { editor.debug_line }
editor.bind(:ctrl_e) { editor.show_history }
editor.bind(:ctrl_x) { puts; puts "Exiting..."; exit }

editor.completion_proc = lambda do |word|
	if word
		['select', 'update', 'delete', 'debug', 'destroy'].find_all	{ |e| e.match(/^#{Regexp.escape(word)}/) }
	end
end

loop do
	puts "You typed: [#{editor.read("=> ").chomp!}]"
end

This example can be found in examples/rawline_shell.rb within the RawLine source code or gem package.

Current status and availability

I currently released RawLine 0.1.0 on SourceForge, and it can be installed via:

gem install -r rawline

The RDoc documentation is available here.

Feel free to try it out. First of all try the rawline_shell.rb example, and see if it works on your machine. If it doesn’t than maybe you try re-binding some keys (use key_tester.rb to “reverse-engineer” your terminal’s input escape sequences), and let me know!

Status information and limitations:

It has been tested on Windows (XP, using the usual command prompt) and on Linux (ZenWalk, using XFCE Terminal).
It can handle lines no longer than the maximum terminal width – 2. This is to ensure that the cursor never “falls down” to the next line.
On Windows, the cursor doesn’t blink immedialy when moving left, but it moves, don’t worry.
On Linux, you should really consider installing the Termios library for a faster experience (otherwise get_character won’t parse characters correctly if you press and hold a key, and that, trust me, is a real mess!).
RawLine is very far from being a complete replacement for the ReadLine library, and it is currently in alpha stage.
Release 0.1.0 has been created after 2 weeks of sporadic coding during lunch breaks and week-ends.

For any ideas on where to go from here, comments and feedback, just reply below or send an email to my usual email address.

Book Review: Writing Efficient Ruby Code

h3rald@h3rald.com — Mon, 21 Jan 2008 04:47:00 -0000

The second shortcut from Addison-Wesley Professional series I’m going to review is called Writing Efficient Ruby Code. A very promising title, especially considering that this book is only 50 pages long.

As usual, this shortcut can be intended as a sort of programmer-friendly detailed cheatsheet: like the other ones in this series it sports a monitor-friendly landscape layout and does not go to deep into the details unless strictly necessary to understand a particular concept.

The Author

Dr. Stefan Kaes, the author, contributed a lot to improve Ruby on Rails’ performance by refactoring portions of its core and try to “get maximum speed out of performance-critical sections of code”. This short but interesting shortcut groups together a lot of performance tweaks, tips and tricks but also some “anti-patterns” Kaes was able to identify through his career as programming teacher Ruby software consultant and key Rails contributor.

The Contents

Like with the previously-covered Mongrel shortcut, Writing Efficient Ruby Code always goes straight to the point when it comes to identify problems. The first one mentioned is of course that the Ruby Interpreter is Slow, most people are aware of that, due to their direct experience or because this argument is normally used by non-Rubyists to argue the language’s usability in commercial projects. What you may not know is why that is so, and that’s where the first part of this book comes into play.

“Ruby is a highly dynamic language: Almost all language entities are first-class citizens in that they can be created, changed, and destroyed at runtime. This comprises classes, modules, methods, constants, and class and instance variables. Only local variables are second-class citizens in Ruby: Whether a name refers to a local variable is determined at parse time.

This makes Ruby extremely flexible, but also more complex. Whever you use a name to refer to an object, Ruby has to search for the object it refers to, and this costs in terms of processing time.

As a matter of fact, one of the most recurring tips in the book to improve code performance is the following:

Method calls are expensive, use variables directly when possible.

Keep this in mind: self.something is not the same as @something. The end result is the same, but the first way costs more in terms of performance because Ruby has to look up the method name.
Similarly, local variables should be introduced as a way to “cache” the result of method calls. Often you may feel “guilty” to introduce a new variable and keep calling the same method over and over: this should definitely be avoided.

Other useful tips include, for example:

Use syntax constructs (e.g. assignments) as expressinons. Use evaluation precedences.
Use interpolated strings "... #{string_variable}" (there’s also no performance difference if constant strings are used between " or ')
Use operators which update the data structure without copying it (when possible). Use update or merge to update hashes.
Iterating using for a in A is slightly faster than performing the same iteration using each, (it is the opposite in Ruby 1.9 though)
do not use return unless you have to
test in order of expected case frequency
Use parallel assignment (a, b = 5, 6) where applicable
If a module gets included in only one other class (or module), it’s preferable to open the class instead.

I deliberately chose not to elaborate any further on the tips listed above because otherwise I’ll give a big chunk of the contents of the book itself. If you know Ruby enough, you may already know why such reccommendations make sense, but if you don’t, Writing Efficient Ruby Code can be a short but very interesting read.

The Good

For each of the 30 “coding patterns” (and consequent anti-patterns) described in the book, the author does a great job explaining the reasons of doing something in a particular way, also through examples and benchmarks, where possible.

Furthermore, this shortcut can really be useful to grasp a few difference between Ruby 1.8.5, 1.8.6 and 1.9 in terms of performance: not all the patters apply to all Ruby implementations, and when that’s the case it is clearly stated.

The Bad

My only complaint about the book is probably the lack of details and more “specialized” patterns. Everything (except for a few Rails-specific tips) normally apply to Ruby as a whole, without going deeply to analyze specific libraries or third-party gems. As a result, once you get the general idea, some of the patters may seem pretty obvious or a logic consequence of others.

It is also true that this is meant to be a shortcut, not a comprehensive analysis on code optimization techniques which can be applied to specific cases: something like this would require much more than 50 pages!

The Bottom Line

Read it, re-read a few bits of it to make sure you grasp the most important concepts, and keep its table of contents in front of you as a reminder when refactoring your code!

Announcement: RedBook v0.5.0 released

h3rald@h3rald.com — Sun, 16 Dec 2007 07:07:00 -0000

This new beta release of RedBook introduces quite a few changes when it comes to configuration and setup. Here’s some highlights…h3. Regexp changes

It is now necessary to enter “proper” regular expressions for :select. Proper means between slashes, like the following:

/Work Day/
/mail/i

I changed this in order to support case-insensitive searches using the i switch. This makes queries much more powerful.

Variables

A new, interesting feature I decided to introduce in this release is variables. For now you define them inside your rbconfig.yml file, like this:

:var_monday_morning: "monday at 8 am"

:var_friday_evening: "friday at 8 pm"

:var_week_report: ":select :duration :from :%monday_morning :to :%friday_evening"

In this way, every time you type in :%week_report in RedBook, it will expand to: :select :duration :from monday at 8 am :to friday at 8 pm. By the way, completion is supported, so you’ll only have to type in something like :%we and hit .

It is possible to define variables as :var_<something> in the rbconfig.yml file and then used them inside RedBook as :%<something>.

New Operations

Five new operations have been added:

:blank

This will blank your current log after asking you if you really want to do so.

:restore

This operation will overwrite your current log with the last saved backup. Like with the :blank operation, you’re asked if you really want to proceed or not.

:archive

By typing :archive, the current log file will be archived to your :archives_folder: directory specified in the rbconfig.yml file (similarly, it is now possible to specify a :backups_folder: for your logs’ backup files).

:dataset

A simple operation to display the messages inthe current dataset.

:dump

This operation will dump the output of the last :select operation to a text file. Useful for saving the average, total time and duration of a set of activities.

Portable edition

Some Windows users will definitely love this. I finally found an easy way to run RedBook confined within the current directory, by using a simple start.bat batch file to set the INPUTRC and HOME variables temporarily to the path to the .inputrc file and the directory of RedBook executable. This makes RedBook 100% portable and suitable to be used on USB sticks &similar.

Get RedBook Portable

New Development Page

I decided to move the primary RedBook repository from Assembla to Google Code. Why? Well, nothing wrong with Assembla per se, I still think it’s an excellent free service to host your public and private projects, but Google Code is faster and offers only the features I need:

Public SVN repository access
Simple-to-use issue tracker
Very nicely developed downloads section, with download counts, and “normal” filenames.

So here’s the new RedBook Development Home:

http://code.google.com/p/redbook/

Additionally I also setup a RedBook Support Google Group, so if you have any question concerning the program, you know where to go!

Book Review: Mongrel Digital Shortcut

h3rald@h3rald.com — Sat, 15 Dec 2007 02:42:00 -0000

If you ever considered about developing an deploying a Rails application in the last year or so, you must have heard of Mongrel before. If you didn’t, I’d recommend you learn more about it because up to now it proved to be one of the few essential ingredients for deploying scalable Rails applications.

Mongrel is a creation of Zed Shaw who started writing a replacement for FastCGI to use with Rails, and ended up creating a brand new, HTTP web server who turned out to be one of the best things the Rails community ever saw happening.

It was created to be simple to use and configure, nevertheless it does require some skill to set it up and tune it. Documentation is there, along with plenty of blog posts, but there’s also an interesting book from Addison Wesley Professional which is definetely worth a read.

“Mongrel: Serving, Deploying, and Extending Your Ruby Applications” – that’s the title of the book. A Digital Shortcut, 100-odd pages long, in landscape format to make it easier to read on a computer, straight to the point with no added sugar for just 15$ (PDF only). I must say Addison Wesley got it right: the book’s format is, as a matter of fact, optimized for web developers, especially those who can’t afford to read a 500-pages book covering everything about a subject just to find that one thing they don’t know about.
This shortcut can be seen, essentially, as an expanded cheatsheet which will teach you the basics about Mongrel and also give you plenty of advice on how to learn more about it.

Let’s have a closer look at it.

Overview, Introduction & Getting Started

The first three ~~chapters~~ sections (there are no chapters, just sections) of the book are meant to be a gentle introduction to Mongrel and its world. The main author is Matt Pelletier, but Zed Show’s contributions are definitely one of the book’s best selling points.
Zed’s thoughts are scattered here and there in many sidebars throughout the book (there’s at least one in each section): you’ll see an odd-looking face (Zed’s self-caricature) with some text next to it; when you read it, you’ll notice that they are actually Zed’s own thoughts, straight from his mind, with no editorial filter whatsoever in-between.
Be warned: the text included within the Zed Sez sidebars is highly opinionated, that’s precisely what Zed feels to say about something, and he’ll just say it: just the plain, simple thoughts of an experienced programmer. As the author explains in Section 1: “[…] You may not agree with everything he says, but you probably should.”

Section 2 is a general introduction about Mongrel. It explains what it is, when and why it was made, and how it works. There’s nothing new to learn if you already used Mongrel before, probably, but it’s definitely the first thing to show to someone who’s new to Mongrel and its world, and possibly a bit skeptical about it.
The last subsection “What can Mongrel do for me” is an attempt to ~~brainwash~~ persuade you to fully embrace Mongrel and its philosophy, whether you are a developer, a sysadmin or even a manager: assertions like “Mongrel is pretty damned secure.” and “Mongrel’s license is capitalist-friendly.” will definitaly make some of you (managers) happy.

Section 3 is slightly more juicy than the previous one, as it explains how to install and use Mongrel. Basically that’s what everyone who ever used it already knows, but it’s still necessary for the book’s consistency, after all. After reading this section, you’ll probably have your first Mongrel up and running and serving your little Rails application’s pages, and you’ll begin to wonder why the hell you need to keep reading this book now that everything seems to work already…

Section 4: Configurations

…aka “a truly useful Mongrel cheatsheet”. This section dives deep(er) into Mongrel’s configuration by explaining what each start parameter does in detail. The parameters are presented in tabular form in a very well-organized way. As you would expect from an high-quality cheatsheet.

Then the author will explore a few commonly used deployment scenarios, in particular:

Standalone – The simplest configuration possible, with just one Mongrel instance serving both static and dynamic pages.
mongrel_cluster – How to use “a pack of mongrels” together to handle more traffic.
Behind a static web server – The most common (and most scalable) option, used to serve static content faster using a front-end server and use Mongrel only to handle Ruby pages.

Towards the end of the section, for the developer’s delight, the author will discuss two common, useful scenarios where Mongrel can be used:

Apache 2 + mod_proxy_balancer + mongrel_cluster
Nginx + mongrel_cluster

The difference here is that detailed instructions are provided on how to setup and configure each server, including example file sources. This can be particularly useful for the Nginx example, as most of the documentation for this fantastic, lightweight Mongrel fron-end is scattered around the web (or written in Russian in a well known place).

Section 5: Production Deployment

This section introduces one of the most important part of the life cycle of a Rails application: the deployment on a production server. The author is pretty honest about the whole subject:

“You will not do this in a day. If you are expecting to code until 1 minute before your deadline and then simply point and click and have an instant server then you need to take some kind of
medication because you are violently hallucinating. You will need at least a week of 8 hours days to make sure your first deployment works and to have the time to do it right.”

Sounds terribly true. Especially for larger projects demanding good performance under heavy traffic. Scared? Probably, if you never deployed a Rails application “properly” before, but at least the book comes to the rescue by providing an overview of what you need to perform a deployment and why it is such a complex and delicate process.

Not only this, but also a “Best Practices Rubric” is also provided for the developer’s own private enjoyement. It’s written as a list of questions like:

11. Do you have a shared location where you can document the deployment, such as a Wiki or CMS?
12. Do you know how to use httperf or ab and know what the statistics mean?

After these 13 questions, the author provides the key to give a meaning to your answers:

"For each question you answer with “NO”, add 10 hours to your time estimate for completion. This may seem unrealistic, since saying “NO” to everything means it’ll take 190 hours (about one
month), but this estimate is actually low according to most first deployment experiences."

If you answered “NO” too many times to these questions, you may want to read on through the next subsection which states 17 “worst practices”: an invaluable read for beginners!

But after all this section is not only about stating the obvious (…right?): a full example scenario is describedand examined throughly to give you an idea of how a deployment should be made, using three different machines:

One for Apache (as a front-end to Mongrel)
One for the Mongrel cluster and the Rails application
One for the database

Maybe something you’ll never do if you just want to run your grandma’s site on Rails, but certainly something you may want to start looking at if your grandma becomes really popular and your small server gets grounded by several thousands of visitors per day.

The last part of the section will give you a brief introduction on monitoring your applications and on which tools you should be using, although it does not discuss the subject in detail at all, it’s just meant to point you to the right direction.

Section 6: Extending Mongrel

This section digs deeper into the software code internals and describes how to teach new tricks to your Mongrel, i.e. how to extend its functionality.

Before you begin, though, don’t forget what Zed himself has to say about Mongrel’s simplicity:

“I’ve always had a different aesthetic sense when I write my software. I value simplicity and directness and try to write software that follows this approach. I jokingly call it the Shibumi School of Software Structure. All I do is apply this rule: When given two possible designs with equal end results, pick the simpler one. I then ruthlessly strip the solution down to its finest elements, but no more.”

Mongrel’s architecture is not that complex, and this section is sufficient to get you started by providing an overview of the main classes involved (HttpServer, HttpRequest, HttpResponse, HttpHandler, URIClassifier), and how they work together.
Note that the book won’t describe anything about the APIs of these classes. but after all, the project’s RDoc documentation should cover all the details you need.

The rest of the section focuses on how to extend Mongrel, by:

Writing custom handlers in Ruby
Creating custom filters to perform security checks, clean up requests and preliminary file processing
Creating plugins and distributing them as rubygems

Two working examples are also provided:

An example handler to deflate content (if the browser supports deflate)
An example “duck” plugin, to make Mongrel quack like a duck when it’s started (not the most useful thing in the world, but serves the purpose)

Debugging, Performance & Security

The last three sections deals with other important aspects concerning the deployment of your application, how to debug, how to improve performance and how to secure your application.

Section 7 introduces two debugging modes:

Dash-Bee logging (-B)
USR1 logging (lighter)

And also gives you an idea on what to look for when debugging an application. Nothing too detailed, granted, but enough to make sure you are pointed in the right direction.

Again, Zed’s wisdom and wit are remarkable:

“These people’s problem is they suffer from Potpourri Turd Syndrome—a belief that their you-know-what don’t stink and smells like fine dew on freshly cut grass. Whenever there’s a bug, they go
running like kids in a candy store to other people’s code trying to find fault and just assume that it’s nothing they wrote.
[…]
When you run into a problem with your application, always assume it’s your fault first. Mongrel’s not perfect, but its code is minuscule compared to the size of Rails and most likely even your own appli-cation code. Mongrel also powers many large and medium deployments without any problems. If there’s an error, the evidence already says it’s in your code, so bite the bullet and start investigating it as if it’s your problem.”

Similarly, Section 8 is a short but useful overview on performance tips and tricks and deployment tuning. The most useful thing is probably the checklist of the “tuning process”, which illustrates the simple steps to take to tune your application.

Finally, Section 9 addresses some common security concerns and clarifies how Mongrel deals with them. The answer is normally “Mongrel strictly does this” or “Mongrel doesn’t support this feature”. After all, you should have understood by now that Mongrel is an example of simplicity and that it deliberately does not aim to offer all the feature you’d expect by a server like Apache:

"As you probably see, Mongrel say, “No” in many places where most Web servers say, “Yes, OK.” Sometimes this is because no one using Mongrel has needed it yet, sometimes it’s because there’s a
better, simpler way to accomplish the same goal. Mongrel is a different kind of Web server, and frequently you can solve your problem with a different solution."

Conclusion

If Mongrel is opinionated software, this is definitely an opinionated book which fully embraces the project’s philosopy of simplicity above everything else. It’s an interesting read and it won’t bore you to death by deliberately skipping long and potentially tedious subjects and adding interesting insights instead (like the Zed Sez sidebars). Perhaps it is a bit too direct towards certain people, who may get even get offended (as planned) by some of the author’s assertions.

Despite being a 100-pages book, this shortcut covers pretty much everything you need to know about Mongrel. It will not teach you everything about deployment, security, performance tweaks and debugging though: as the authors often state throughout the book, a lot of (big) books are available on those subject, and it wouldn’t make sense to even attempt to discuss them in this shortcut.

Similarly, you won’t find complex examples either, but that’s acceptable because simple examples are often the only thing you need to grasp the basics of a concept or feature, and then use them as a “scaffold” for your own code.

Globally, the book is well balanced and optimized for its size: lightweight introductory sections at first, then the “real juice” in the middle, and a few overview sections on advanced topics towards the end. You can read it easily in a few hours, perhaps less, and whenever you need to look something up in a hurry it will be fairly easy to locate.

A good read, and a must for everyone who wants to learn more about Mongrel or Rails deployment.

Announcement: RedBook v0.4.0 released

h3rald@h3rald.com — Wed, 28 Nov 2007 07:34:00 -0000

I’m pleased to announce a new release of the RedBook daily logging and time tracking script. This release introduces two new operations, four stats-related directives and a brand new Windows Installer able to setup RedBook in a blink, with (almost) no configuration at all.

Let’s have a closer look…h2. New Operations

Suppose that you just logged a message and you noticed one of these two things happened:

You didn’t really wanted to log it
You made a silly typo in the message or in the tags

What can you do about it? Up to RedBook 0.3, the only solution was to open the YAML file and correct the mistake manually. From now on there’s also another simpler way to operate in such situations: using the :update and :delete operations!

:update

This operation can be used to update the message and or the tags of a previously-logged activity. The usage is simple: load a dataset first, and then execute an :update command like:

:update 4 :message My updated message :with new_tag1 new_tag2

This will update the 4th message of the dataset modifying its message and tags. Of course you can update either of the two things or both; the timestamp of the activity will not be changed.

:delete

The delete operation can be used to completely delete a message from the log. Just load a dataset using a :select operation and then execute a :delete command, e.g.:

:delete 1 (will delete the first activity)
:delete 4 2 7 9 (will delete activity #2, #4, #7 and #9)
:delete (will delete the entire dataset)

A confirmation message will appear before deleting the message(s).

IMPORTANT
Due to the architecture of the application, whenever an :update or :delete occurs the log file will be reloaded in memory and completely overwritten. This doesn’t cause problems, although for big log files (10,000+ activities) this may take a few seconds.

Statistics

Another important new feature introduced by this release is time tracking. It was actually already there, kind of: the :calc operation was already able to calculate the time elapsed between two activities… however, this is not really practical.

Since last release, it is possible to log the completion of an activity using the :finish command. This will basically re-log the same activity prepending [COMPLETED] to its message.
If you started using the :finish command to complete your activities, RedBook can now calculate the following stats for you:

Count the number of messages in a dataset
Calculate the average time spent for the completed activities in a dataset
Calculate the total time spent for the completed activities in a dataset
Calculate the duration of each completed activity in a dataset

Each of these calculations is performed by adding special directive to a :select command, as explained in the following sections.

:count

This directive can be added to a :select command to return just the number of message of the loaded dataset.
In other words, executing the following:

:select :count :with mail !work

…will return the number of activities tagged with mail but not with personal, without listing all the activities.

:avg

The :avg directive can be used to calculate the average time spent on activities matching certain criteria, for example:

:select Status Meeting :avg :with meeting

…will return the average time spent on activities whose messages matches /Status Meeting/ and are tagged with meeting.

:total

Similarly, :total can be used to return the total time spent on activities matching certain criteria, e.g.:

:select :total :with mail work

…will return the total time spent on activities tagged with mail and work.

:duration

Lastly, :duration will print each completed task along with its duration. The syntax is similar to the others:

:select :duration :with break

This will print each completed activity tagged with break along with its duration.

:nodiff and _concurrent

The logic behind the above-mentioned directives may seem trivial to implement, but it is not. The fun part was telling RedBook to subtract the duration of each sub-activity contained in another activity… a feature I considered necessary for time tracking purpose. However, if you start your work day with a Working Day activity and you complete that activity using the :finish command, when calculating the duration of the working day RedBook will subtract the duration of all the completed sub-activities from the duration of Working Day. This is not OK, so I added the directive :nodiff which can be used to prevent RedBook from calculating the difference between the parent activity’s duration and the duration of each of its child activity.

What if you’re doing two things at once? use the special _concurrent tag, and that activity will be considered symultaneous to its parent activity for time tracking purposes.

Activity Status Filters

RedBook is now fully aware of the “status” of each activity, so it is possible to display only activities in a certain status using the following directives:

:plain

Executing :select :plain :from today will return all the activities logged today, omitting their completions (if any), i.e. any activity beginning with [COMPLETED].

:pending

Executing :select :pending :from today will return all the activities logged today which have not been completed yet. Again, this was not too trivial to implement, but it seems to work (it also smart enough to detect if the same activity has been relogged etc. etc.).

WARNING:
Using this directive with a large dataset may cause RedBook to take some time before delivering the result, due to the amount of iterations to perform. Use with care.

:completed

Executing :select :completed :from today will return all the activities logged today which have been completed.

Windows Installer

I decided to spend some time (half an hour) and create a proper setup file for Windows using InnoSetup. The setup will take care of almost everything for you, so you have no excuse not to try RedBook because it’s not user-friendly to install!

Check out the manual for more details.

RubyForge Project

Finally, I registered a new RubyForge Project for RedBook, which include a public SVN repository updated every week (Assembla doesn’t allow anonymous checkouts, unfortunately).
This project will also host the official RedBook Gem, scheduled for the 1.0 release.

DOWNLOAD | MANUAL

Announcement: RedBook v0.3.0 released

h3rald@h3rald.com — Thu, 25 Oct 2007 05:18:00 -0000

It’s time for a new beta release of RedBook. This was actually going to be a fairly modest release in terms of features, but I actually ended up implementing a lot more than expected, even things which were planned for the first production release 1.0. So, let’s see what’s new

New operation names (which break compatibility with previous versions)

I had a look at the names I choose for the operations and I noticed that they were either not intuitive enough or too verbose. So I decided to change a fair few of them (thus breaking compatibility with previous versions, but after all that’s what beta releases are for, right?):

OLD	NEW
:complete	:finish
:load	:select
:load_config	:config
:load_log	:refresh
:timecalc	:calc
:stop	:quit

New Manual/Home Page

A while ago I discovered TiddlyWiki, but as a matter of fact I never used it for anything practical. From last week though, I started using it a work for taking notes and create short memos, and then I thought of using it to replace RedBook’s standard README file (which was made in a hurry and was kinda cryptical). Now a brand new “manual.html” ships with RedBook — 308 KB (30 of actual docs and 278 of Javascript/HTML/CSS magic) with everything you need to know about it. Additionally, an online version is available at the following address:

redbook.h3rald.com

Removed Win32::Console Library

OK this is not good news for people (like me) who use RedBook on Windows, but I promise you’ll forgive me when you read about the other new features below. I discovered by chance that the Win32::Console library (which was used to get colors working on Windows) seems not to handle international characters properly and also seems to be conflicting in some way with the Readline library I decided to include (see below). I don’t know whether this is a problem of the actual library or just of the gem used to pack it.

rbconfig.yml

The config.yml file has been renamed to rbconfig.yml. Additionally, if you place a file with this name in your $HOME directory it will override the one in your RedBook folder (This was done in preparation for the RedBook RubyGem).

New operations

The following new operations are available:

:relog — Re-logs a previously-logged message (keeping the same tags and updating the timestamp)
:clear — Clears the screen.
:ruby — Evaluates arbitrary Ruby code outputting the result (use with care…)

Auto-completion

Some Mac users originally complained that the backspace key wasn’t working in RedBook (and it didn’t in Linux either). Fortunately the solution to this was easy enough: include the GNU Readline library.
Readline is now being used in RedBook to:

Provide basic (Emacs-style) bindings
Auto-completion for keywords and tags
Allow the user to automatically customize key bindings via an .inputrc file placed in their $HOME directory (on Windows you’ll have to define a HOME environment variable pointing to a directory of your choice). An example .inputrc file is distributed with RedBook with some specific key bindings.

Support for international characters

Finally, I decided to implement another feature which was originally planned for the 1.0 release: international characters support. This is possible using the Iconv Ruby extension (requires GNU libiconv) which can convert strings between different character sets. The character sets needs to be configured via the rbconfig.yml file.

For more information, check out the ChangeLog

Download RedBook

Announcement: RedBook v0.2.0 released

h3rald@h3rald.com — Mon, 08 Oct 2007 03:05:00 -0000

“Release Early, Release Often”

— Eric S. Raymond, The Cathedral and the Bazaar

In other words, time for another (early) release of RedBook. There are quite a few new features which are worth examining, in particular:

Regexp search for messages

This was actually already available before, just if you inputted a search string which was not a regexp, you’d get an unhandled exception (more or less). This exception is now handled propertly so you get a pretty message instead, if an error occurs when parsing the search string.

Log Backup

A new :backup keyword is available to quickly backup your log file. Here’s what it does:

Loads all messages silently
Writes them to a file in the same directory as the original log file named <log-alias>.bkp.yml.

Handy, especially if there was a similar keyword to restore the last backup, which is planned for later on.

Support for multiple log files

This is perhaps the most important feature introduced by this release. It is now possible to configure more than one log file by adding any number of :data_<alias>: settings inside your config.yml file, where alias is the name of your log file. So, for example, if your config.yml file contains the following:

:data_test: “testlog.yml”

You can load the “test” log by typing

:use test

(:use is a shorthand for :load_log). Similarly, another new keyword :dest has been introduced to be able to log a message to a different log file without loading it into memory, like this:

:log This message will be saved to testlog.yml :dest test

Finally, a :refresh keyword has been introduced as an alias to reloading the current log.

(Almost) automatic log of completed activities

Right when I was coding the :timecalc operation, I thought it would be nice to be able to log the start and end of a task without having to type it twice. Now this is possible using the :complete keyword:

:log Testing feature X in product Y

:complete

:complete will re-log the last message prepended with [COMPLETED]:

4 Mon Oct 08 2007 – 10:47:45 AM Testing feature X in product Y 5 Mon Oct 08 2007 – 10:54:31 AM [COMPLETED] Testing feature X in product Y

What if I start another task before completing the first one? No problem, it is sufficient to load the last activities using a :load command and then issuing :complete <number> where <number> is the index of the loaded activity.
This nifty little feature will become more and more important when (starting from release 0.4) I’ll implement more time tracking functions, and it will be possible to track completed tasks in a specific timeframe and/or marked with a specific tag.

Easy integration with launchers like Launchy and QuickSilver

To conclude, as someone pointed out that it would be cool to use RedBook from launchers like Launchy or Quicksilver, I made another standalone script (redbooklet.rb or redbooklet.exe) which is just able to parse a log command and write a message to the specified log file.
To use it with Launchy, for example, all you have to do is the following:

Create a shortcut to redbooklet.exe (or to a way to execute the corresponding ruby script) named “log”.
Copy the “log” shortcut anywhere in your start menu
Bring up launchy (ALT+SPACE) and type in “log”
Hit tab
Type in your log message, optionally with the any :tags or :dest keywords.
The message will be logged to your default log file or to the log you specified using the :dest keyword. If an error occurs, it will appear in a command line window for 15 seconds before the program is closed.

That’s all folks! As usual, if you have any comment or suggestion feel free to reply to this post or email me. For a list of the planned features and releases, check out the Milestones page.

DOWNLOAD HERE

Book Review: Humble Little Ruby Book

h3rald@h3rald.com — Wed, 03 Oct 2007 03:53:00 -0000

After reading the very first paragraph of Mr. Neighborly’s Humble Little Ruby Book (HLRB for short, from now on) it was very clear to me that it was going to be quite an unconventional read:

“Yes, there is a Chapter 0. There is a little bit of introductory stuff we need to talk about before
we set you loose on Ruby. You wouldn’t want to get psyched about a new gadget, get it home,
and then figure out you need batteries, a grapefruit, and the ability to speak three languages to
even open the box would you?”

That reminded me immediately of Why’s Poignant Guide to Ruby. without a doubt. I don’t know how it is possible that two witty, crazy, and very inventive guys grew fond of the same programming language. Anyhow, to reassure a few of you, you won’t find any foxes or chunky bacon cartoons in HLRB, just some very well made (although still pretty unconventional) diagrams like this one:

Got the picture? Good. Let’s move on…h3. Chapter 0: What’chu talkin’ ’bout, mister?

Chapter 0 is like an introduction to the book and a place to put all the boring stuff you have to talk about in a book about a programming language:

What is Ruby?
Installation procedure (on Windows, Mac OS X and Linux)
Hello, World!

Yes, you can skip this one safely without losing too much, unless of course you still need to install Ruby on your machine.

Chapter 1: Welcome to Ruby.

“This section aims to introduce the syntactic sugar and linguistic misfortunes of Ruby in the
quickest manner that will still allow for a full education on the subject.”

As the first two lines of this chapter say, it’s time to learn the basics of Ruby. You’ll be quickly guided through strings, numbers, collections and variables. Every section with tons of code examples for your to play with. You won’t find a full list of all the 876 methods of the String class, but you’ll certainly learn the 10 most common ones at least (numbers are random, so no, don’t count them).
Sure, yes, right, whatever… if you really want you can skip this chapter too, but if you are already a Ruby Guru there’s probably no need for you to read books about Ruby, right? Beginners need to read this chapter. It’s compulsory, really, and pretty enjoyable, too.

Chapter 2: Break it down now!

Or “learn how to segment your code” using methods, and… blocks & Proc objects! Gosh. Our poor newbies will probably have a heart attack if they never heard about blocks and closures before. I almost got scared myself, because this is normally regarded as a pretty tough topic. Despite, at page 25 of the book you’ll have to face your fears and dive into it. You’ll survive, anyway.

Purist Warning: Please be aware that sometimes the author may decide to use certain terms and construct which may not sound 100% right to your ears. Just move on, beginners will understand more things like “Think of Proc objects as blocks that are pushed into variables.” than anything else, guaranteed.

After this section you’ll finally be introduced to Ruby classes. Now, this can piss someone off, no doubt. Ruby is a fully OO language, so people must learn about classes before anything else. I must admit I was a bit confused by the ordering of the topics at first, but if someone comes from a non-OO background he’ll probably find this particular order more suitable.
This section will cover class and object basics in Ruby like defining classes, instantiating objects, access control, methods, attributes, scope, duck typing. Finally, you’ll briefly look into modules as well.

Chapter 3: Hustle and flow (control)

Finally, the author will deal with flow control. So things like if, case, conditional operators, loops and statement modifiers. In my opinion this section is truly excellent: it introduces all the control structures in a very simple and crystal clear way, often using flowcharts. A great chance even for absolute beginners to understand these basic but powerful concepts.
Towards the end of the chapter, you’ll also learn how exceptions work: a clever way to tell people “you have to learn how to use exceptions from the very beginning”. Really nicely done.

Chapter 4: The system beneath…

Here comes the juicy stuff. Up to now you learnt the usual boring things you need to know when learning a new programming language, now finally you learn how to do real things. The chapter is full of complete and meaningful code snippets which will answer nearly all the questions you may have (at this time):

How do I read and write to a file?
How do I handle threads and processes?
How do command-line parameters and environment variables work?
How can I perform specific Windows-only operations, like reading and writing to the Registry? What about OLE automation?

Some of the big books out there will not spend too much time talking about Windows-only libraries, but I found HLRB gives quite a comprehensive introduction about them.

Chapter 5: Looking beyond home

More juicy stuff. If you are looking for a tutorial to learn the basics about networking, from from sockets to FTP to POP and web services, look no further: this chapter does a very remarkable job introducing various network-related libraries, with the usual well written code examples.
If that’s still not enough, you’ll also have a chance to explore the wonderful world of distributed Ruby and of databases. Granted, this chapter won’t tell you about the 1567 methods available in ActiveRecord (buy a copy of Agile Web Development with Rails for this), but will tell you enough to get started.

Chapter 6: It’s a Library!

The final chapter will go more in depth on some more advanced topics, like:

Strings
Regexp
Date & Time
Hashing and Cryptography
Unit Testing

Everything with more and more useful code snippets.

The Appendices

Last but not least, a HUGE collection of links and resources to learn more about Ruby, and a quick digression on C/C++ extensions… not much, but enough to wet your appetite.

The bottom line

HLRB is not the only book you need to read about Ruby. It’s better to make this clear otherwise I’ll be hunted forever by Dave Thomas, Chad Fowler, DHH and all the other excellent Ruby hackers who also wrote very successful books (which I bought as well). HLRB is LITTLE and HUMBLE, after all: it doesn’t aim at becoming the official Ruby Bible anytime soon (although a bird told me it may get updated someday and include more stuff), but it is still a worthwhile reading.

And of course I came to the very end of this review without mentioning the most important thing: this little wonder is free. All you need is to register to InfoQ (for free) and grab your free copy. If you want you can buy a printed copy for just $9.95, if you feel in a good mood (please do).

The most obvious strengths of this book are the abundance of code examples and very useful working snippets, and the unconventional style which makes it very readable and not boring at all. If I were to name some of its weaknesses (but only if you force me to), I’d say some parts should be expanded and more info on other libraries should be provided… but you never know what the future will bring us!

Well done, Mr. Neighborly!

RedBook - A simple Ruby program for your daily logging needs

h3rald@h3rald.com — Sat, 29 Sep 2007 12:05:00 -0000

Logging your daily activities is important. If you don’t believe me you’d better check at least these three posts on LifeHacker, which feature different scripts and applications:

I had a look at each one of them, and I believe they are quite useful, although I didn’t really find what I was looking for. Why? Well, for example:

I don’t believe a GUI is necessary — you’d better off with just a shortcut key or command to run from Launchy or QuickSilver, that’s much faster.
They just log timestamped messages on a file, there’s no real way to search through them and display them except by using a test editor
They are Windows only — not that it matters for me, but others may not be happy about it.

That’s why I thought I’d roll out my own: meet RedBook.
Let me say it’s nothing fancy: I’m not a full-time programmer but I do like playing with Ruby during my lunch breaks at work, so that’s why RedBook is just a humble, tiny Ruby script. This automatically makes it cross-platform: you can install Ruby very easily on Linux & alikes, Mac OS X and Windows. Furthermore, if you are on Windows and for some weird reason you don’t want to install Ruby, you can just try out the packed EXE file (made with RubyScript2Exe) — it’s about 2MB, but you won’t need anything else.

How It Works

The program uses two YAML files, one for configuration, which must reside in the same directory as redbook.rb (or redboo.exe) and one for the log itself, which you can place anywhere, provided that you edit the configuration file accordingly. For information on how to install RedBook and how to configure it, you can check the manual.html (powered by TiddlyWiki) file provided with the program or browse it online.

When started, RedBook will load both the configuration file (config.yml) and the whole log file into memory — it’s not a big deal, considering that they are only text files after all. I did a test with a log of quite a few MBs, and it was fine.

You can then start input commands right away, following a few sample rules. RedBook has a (very) rudimentary parser which is able to detect keywords, i.e. alphabetic strings prepended with a colon. RedBook commands look like this:

:log This message will be logger :tags tag1 tag2
:select :last 15 :since January
:save /home/h3rald/backup.yml

If everything goes OK, RedBook will reply with some sort of response, an acknowledgement, a list of messages, etc.

Simple.

Here’s basically what the program can do:

Log any message to the main log file. Messages can be tagged with one or more tags and will be automatically timestamped.
Load/display a list of logged messages on the screen. It is possible to filter messages by specifying a time span, a string to search in the message text, or a list of tags.
Dump loaded messages to a TXT, CSV or YAML file (you can even backup your log saving it to another YAML file in this way).
Calculate the time elapsed between two or more tasks. Time will be displayed in years, months, weeks, days, hours, minutes and/or seconds as necessary.

How? Here’s a short tutorial…

A Quick RedBook Tutorial

Let’s assume you are able to run RedBook on your system by now (if you can’t find some of the gems which are required for it, you can download them packed in a ZIP file from here).

Here’s what happens when you start the program:

Good. Let’s start logging something then. Just use the :log keyword, followed by a message, and then you can also add the :tags keyword followed by space-separated tags, like this:

RedBook >> :log My first message :tags test
>> Logged.
RedBook >> :log This is another message
>> Logged.
RedBook >> :log This is another message :tags test another_test
>> Logged.

Try waiting a few seconds between each message. These three messages will be appended to the log file. You could open it in an editor, but it’s normally easier to display them directly inside RedBook, like this:

RedBook >> :select
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]
2 Sat Sep 29 2007 – 09:10:51 PM This is another message
3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]
>> 3 messages loaded.

Easy. What if you have hundreds of messages? Well, the :select operation can take an optional search string, or you can tell RedBook to load only those messages tagged with one or more specific tags, like this:

RedBook >> :select :tags test
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]
3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]
>> 2 messages loaded.

Or you can use the :from and/or :to keywords to specify a certain time frame, like this:

:select :tags test :from ten minutes ago

:select :from last week :to 2 days ago

RedBook includes a very nice “natural language date/time parser”, Chronic which is able to convert sentences like the following into Ruby Time objects:

6 in the morning
friday 1pm
sat 7 in the evening
today
yesterday at 4:00

It’s not perfect (and it’s in pre-alpha as well), but it does the job, for what I can see, and it makes it very easy and fast to specify timeframes.

After executing a :select command, two other operations can be performed on the loaded messages: :calc and :save.

:calc calculates the exact amount of time elapsed between two or more tasks. Do you remember the numbers on the far left of each message? Think them as temporary IDs for the actual messages, and you can use them to select specific tasks when executing the :calc operation:

RedBook >> :calc 1 3
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]
- 2 minutes and 13 seconds.
3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]

Similarly, if no IDs are specified, :calc calculates the time difference between each message and the previous:

RedBook >> :calc
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]

- 1 minute and 19 seconds.

2 Sat Sep 29 2007 – 09:10:51 PM This is another message

- 54 seconds.

3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]

Finally, you can save loaded messages to a TXT, YAML or CSV file, as follows:

RedBook >> :save log.txt
>> Saving…
>> Saved dataset to “log.txt”

h
If you want to backup your log, you can load all messages and then save them to a YAML file. Maybe in this case you want to append the :silent keyword to the :select command, so that messages won’t be displayed on the screen.

Conclusion

RedBook is just a simple program: it suits my needs for now, but of course there’s roo for improvement. If you have some useful suggestions, or you want to contribute in some way, feel free to contact me!

Home Page | Development | Download

Introducing RedBook (and the new Code section)

h3rald@h3rald.com — Sat, 29 Sep 2007 00:12:00 -0000

I’m somehow pleased to announce the opening of a new section on this site. Nothing too big actually, it’s just a page with a few (one for now) brief descriptions of open source programs and scripts I made and I’d like to share with my readers.

Don’t expect fancy stuff: (luckily) I don’t code for a living, I code for pleasure and I code small things. Lately I’ve been trying to write a small Ruby program able to log my daily activities and also display them in a pleasant enough way, so I started using my lunch breaks at work more constructively and I came up with RedBook an interactive command-line program written in Ruby.

Main features:

Log timestamped and tagged messages to a single YAML file
Load and display messages containing a certain string, or certain tags or within a time frame.
Calculate the time elapsed between two or more tasks.
Export loaded messages to YAML, TXT or CSV format.

All done via command line via simple commands:

:log This is a test message :tags test

:load :last 30 :from last week

:timecalc 2 5

:save test.txt

Thanks to the wonderful Chronic library, you can specify your time frames using natural language expressions like “8 in the morning”, “this tuesday”, “last month” and so on…

Here’s a screenshot showing RedBook in action:

RedBook is of course free, open source software licensed under the terms of the BSD license. It can be installed on any machine able to run Ruby and there’s also an EXE version for the lazy windows folks who don’t want to install Ruby, packed with RubyScript2Exe. A more in-depth article explaining how RedBook works ~~will hopefully be completed soon~~ is available :here

Simply On Rails - Part 4: Quick and Easy Default Data Migrations

h3rald@h3rald.com — Sat, 15 Sep 2007 11:10:00 -0000

In the last post of this series I tried to find a DRY solution to deal with tables storing “ancillary” data, i.e. names of user roles, predefined categories, page state names and other similar things.
I personally chose to put this kind of data to make my application more dynamic, although I could have decided to use ENUMs or simply ordinary varchar fields — that would have been easier, but less flexible. For now, I’m sticking with my original choice.

The data in these tables is kind of a prerequisite for the application to run: I must be able to have a status to assign to a user when creating it, and the same applies to roles. Sure, I could spend 20 minutes populating these tables manually, but it would be nice if there was a less tedious way, wouldn’t it?

There is indeed. The inspiration came from a technique described in the book (which I highly recommend) Agile Web Development With Rails, in which the author outlines how it would be possible to use Rails’ fixtures and migrations to load data in the database automatically from YAML files.
All you have to do is create a migration to load the specified YAML files and you’re all set.

I wanted to take a little step further, allowing the migration to load data from all YAML files in a specific directory, automatically.Let’s start creating the YAML files then and place them all in one directory of the application like /db/migrate/defaults. Here’s the one I used for user roles, for example:

visitor:
	id: 1
	name: Visitor
	level: 0

user:
	id: 2
	name: User
	level: 10

contributor:
	id: 3
	name: Contributor
	level: 20

provider:
	id: 4
	name: Provider
	level: 50

operator:
	id: 5
	name: Operator
	level: 100

administrator:
	id: 6
	name: Administrator
	level: 500

webmaster:
	id: 7
	name: Webmaster
	level: 1000

The important thing to remember is to provide a unique string to identify each record, before specifying each fiels. The other files look similar, so I won’t bother listing them here.

And here’s the simple code for the migration:

require 'active_record/fixtures'

class LoadDefaults < ActiveRecord::Migration

	def self.up
		down
		models = self.default_models
		models.each do |m|   
			Fixtures.create_fixtures(self.default_directory, m)
		end
	end

	def self.down
		models = self.default_models
		models.each do |m|
			eval("#{m.singularize.capitalize}.delete_all")
		end
	end

	def self.default_directory
		File.join(File.dirname(__FILE__), "defaults" )
	end

	def self.default_models
		files, names = Dir.glob("#{self.default_directory}/*.yml"), []
		unless files.blank?
			files.each { |f| names << File.basename(f, '.yml') }
			names
		else
			[]
		end
	end

end

Basically the migration will look in a directory named “defaults” for some YAML files named after a particular database table, and it will attempt to load all the records defined in each one of them.
The down method of the migration deletes all the data in the specified tables, so use with care…

10 Reasons to Learn Ruby

h3rald@h3rald.com — Wed, 05 Sep 2007 10:40:00 -0000

Preamble

I discovered Ruby fairly recently, through the excellent Ruby on Rails framework¹. Although I don’t consider myself a Ruby expert by any means, I read the PickAxe², I’ve coded a few utilities for my personal use in Ruby and I’m currently developing with Rails during my free time.

Ruby is currently my programming language of choice; I started off with Turbo Pascal in high school, discovered C and C++ at university, did my thesis in Java and learned PHP from scratch because I wanted to learn how to make websites quickly and easily. I guess I feel compelled to code sometimes, more as a form of entertainment than anything else. Rather dissatisfied with what I tried language-wise, I was determined to start learning either Python or Ruby. I chose the latter because I didn’t want incorrect indentation to break my code³, and here I am, heaping praise upon it.

There are plenty⁴ of introductions, tutorials, articles and essays of different sorts which aim to guide the novice and advise the guru on how to get the most out of Ruby. This article, however, is not one of them.

It’s more of a modest, humble, and incomplete list of a few reasons which may (or may not) entice you to use Ruby or at least play with it a bit. A word of caution: if you are using another programming language for work or whatever, don’t complain to me if you don’t want to use it anymore – that’s exactly what happened to me, but luckily, it didn’t matter. Ruby is a very beautiful and elegant language, but like all things of this sort, it may well poison your mind and corrupt your soul…

You have been warned.
h3. Why learn Ruby?

#1 – You get all the treats without the tricks

Ruby borrows from all the best programming languages out there, from smalltalk to Java, Perl to Python⁵. Basically, here’s the features and functionalities Ruby gives you which you may have seen elsewhere:

Exceptions: Believe it or not, exceptions are one of the most important things to master when developing any kind of application. PHP4 programmers probably won’t know anything about them and they’ll tell you to just print stuff on the screen or use their “extremely advanced” class for error handling. Please, ignore them. Fortunately for all of us, Ruby comes with try/catch (or better, begin/rescue) blocks and a series of predefined, extensible Exceptions to handle errors properly.
Namespaces: Ruby modules make excellent and easy-to-use namespaces, for the joy of Java and C++ enthusiasts.
Built-in Regular Expressions: For all the Perl monkeys, you can put something between slashes and it will become a regular expression, ready to be matched with a =~ operator.
Overloadable operators: Ruby lets you define operators like +, -, etc., for any of your classes.
Packages: Called “gems”, they really are solid and precious indeed…and they work! Packages support dependencies, and they can be either cross-platform or platform-dependent.
Interactive Shell: the Interactive Ruby Shell can be used to test Ruby code instantly, similar to the Python console.
Unit Testing: The Test::Unit module makes things so easy that you really don’t have any excuse not to test your code.

#2 – You’ll love the little things

Ruby is elegant. Why’s that? Because it doesn’t focus on making code concise so much as readable and usable. Here are some tips to help you out:

You can use both if and unless in condition statements. Of course you can just use if and negate the condition, but unless can be less error-prone at times. Furthermore, you can use both operators as conditional modifiers, after a statement rather than before: order.new unless order.exists.
You can use question marks and exclamation marks at the end of your methods. Although no convention is enforced, ? is added if the method should return true or false, while ! is used to clarify that the method does something forcefully, like destroying a database record, chopping off the last character of a string, etc.
You can use the alias directives to create an alias for a method already defined. In this way you can have an exist and an exists method at no additional cost or repetition.
You can use the attr_reader, attr_writer or attr_accessor directives to automatically generate getter and setter methods for specified class members.
Some naming conventions are enforced for your own sanity: constants, classes and modules are capitalized, methods and members must start with a lowercase letter; global variables are prepended by a $, instance variables by @ and class variables by @@; etc.
Parentheses are optional in method calls. You can therefore write File.open(“/home/h3rald/test.txt”) or simply File.open “/home/h3rald/test.txt”, which is particularly handy with methods that don’t take parameters.

#3 – You won’t ever use a semicolon again

You want to add another instruction? Just go on the next line. Hit and you’re done. In Ruby, like in Python, newlines matter and you don’t have to remember to end your instructions with a semicolon. Unfortunately this means that you won’t be able to write your whole program in a single line of code, like the C++ folks… that’s too bad, isn’t it?

UPDATE: Indeed you CAN use semicolons as line delimiters in Ruby as well, the point, however, is that you don’t have to.

#4 – Everything is an object, as it should be

When I studied Java they taught me that everything is an object.

- “So 14 and 374346.678 are objects then?”
- “No, silly, they are numbers!”

In Ruby, numbers, strings, Boolean values et al are objects. Really. This means you’ll write things like:

"YOU SHOULDN'T ALWAYS USE CAPITALS".downcase #=> outputs "you shouldn't always use capitals"
-12.abs #=> outputs 12

instead of something like:

# PHP Code

strtolower("YOU SHOULDN'T ALWAYS USE CAPITALS");
abs(-12);

You save time, you save brackets, and it just makes more sense.

#5 – Everything has a value

Or “you’ll hardly ever use return to return values”. In a nutshell, all Ruby instructions return a value, even variable assignments, so you don’t really need to use the “return” keyword at the end of a method; the value of the last assignment or any other expression will always be returned.

#6 – You can alter your environment in any way you like

The first time I saw this, it really freaked me out. Imagine a typical programming situation: you start using a system class or a class written by someone else and you notice that you’d like to have an additional method. At this point you have a few ways to handle this in ordinary programming languages:
s

You modify the developer’s source code, if you have access to it. This is normally not a good idea, and you shouldn’t do it.
You derive a new class from the original one, and you implement the new method there. This is a good idea, but it could be overkill for just one method, and you may have to update some of your other code accordingly.
You give up, and you just create the method outside the class, somewhere else. This can be done, but it is not very elegant and goes against Object Oriented Programming.

In Ruby, you can simply add the method to the original class, without having to hack the original source code, and even for system classes! You want to have a method to automatically convert a measurement from meters to feet? You can simply extend the Numeric class as follows:

class Numeric
  def feet
	self*3.2808399
  end
end

From now on, all your numbers will have a feet method, which can be used just like any other method that was originally defined for the class:

5.feet #=> Returns 16.4041995

Basically, Ruby classes are never closed and can be modified at any time from anywhere. Use with care, of course.

#7 You won’t get unicorns from birds and horses, but you’ll still get donkeys if you want

I distinctly remember my C++ professor at university using animals to illustrate key object-oriented concepts like classes and inheritance. Weird things came in when she tried to explain multiple inheritance to inherit a class Pegasus from a class Bird and a class Horse. It had methods like “fly” and “neigh”… crazy stuff, anyhow, Ruby does not offer multiple inheritance.
This seems to be the trend, after all, and of course it’s up to tastes. I don’t quite fancy multiple inheritances, as they may lead to unpredictable things. Nevertheless, it is possible to create “mix-ins” using Ruby modules, so that members and methods defined in a module will be added to a particular class if the module is included in it.

#8 You don’t really need XML

XML is a nice, general-purpose markup language which can be processed by every programming language and used everywhere. Unfortunately, it can also be quite verbose to write, very difficult to parse, and let’s be honest, it’s not really readable at first glance in many cases, unlike the following code snippet:

regexp: !ruby/regexp /a-zA-Z/
number: 4.7
string: a string

This is definitely easier and more readable than XML, isn’t it? Welcome to YAML, Ruby’s favorite markup (but not really⁶) language, which can be used to represent any Ruby object in a simple, clear and yet complete way.
Ruby can parse XML, but YAML’s simplicity convinced a lot of developers to use it as an alternative to XML for configuration files, for example (Rails does this).
The code snipped presented before was obtained by executing the following line of Ruby code:

{"string" => "a string", "number" => 4.7, "regexp" => /a-zA-Z/}.to_yaml

The to_yaml method is defined for the Object class, which is the father of all of the other classes, and thus it is available in all Ruby objects. This means that you can convert anything into YAML and re-convert anything back into Ruby objects, with total transparency for the developer. So much for parsing, huh?

#9 Lambda is much more than a Greek letter

Ruby borrows some magic from Lisp and Perl with Proc objects and blocks. Procs are _"blocks of code that have been bound to a set of local variables. Once bound, the code may be called in different contexts and still access those variables." _⁷ Consider the following:

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

   times3 = gen_times(3)
   times5 = gen_times(5)

   times3.call(12)               #=> 36
   times5.call(5)                #=> 25
   times3.call(times5.call(4))   #=> 60

I could have used the lambda method instead of Proc.new and gotten the same result. This should ring a bell for people who know Perl and Python (or Lisp)⁸. You can do the same thing in PHP as well, but most people don’t really use the function.⁹

Additionally, Ruby makes extensive use of blocks, sort of “unborn Procs”¹⁰, for example, to iterate the contents of an object and execute some code, like the each method available for the Array class:

[1, 2, 4, 6, 8].each {|c| puts c*2} #=> outputs each element multiplied by 2 in a new line.

Should the code in the block exceed one line, you’re advised (but not required) to include the block within do … end instead of using braces. Ruby folks don’t like braces much, really.

#10 – You can go on Rails

Last but not least, you can always use Ruby on Rails for developing web applications. Deployment may not be as easy as it is with PHP, but Rails was built in Ruby because Ruby has features no other language can offer.

Conclusion

Time’s up. You’ve probably made up your mind about Ruby already, and you are either playing with it already, or you’re totally ignoring it. However, the next time you’re frustrated because your code looks ugly and you think you could have done the same thing with half the code you got, don’t blame me!

Notes

¹ Ruby on Rails, MVC Web Development Framework.

² Programming Ruby, by Dave Thomas & others, Pragmatic Programmers, 2004

³ Not entirely correct, but sort of. For more information on Python’s indentation rules and myths, read Python: Myths about Indentation.

⁴ For a list of Ruby tutorials, refer to the Documentation section of the Official Ruby Website.

⁵ For more information on Ruby, and in particular on the similarities and differences with other languages, refer to Ruby from Other Languages.

⁶ YAML is Not a Markup Language.

⁷ Definition and example taken from the official Ruby documentation for class Proc.

⁸ For some example on lambda functions in Python, see Python: Lambda Functions.

⁹ For examples of “lambda functions” in PHP using create_function(), see this.

¹⁰ For more detailed information on Ruby’s Procs, blocks etc. refer to Understanding Ruby blocks, Procs and methods.

H3RALD - Tag 'ruby' (RSS Feed)

Glyph 0.4.0 Released

Web Output

HTML5 Output

Project Statistics

Custom tasks and commands

wkhtmltopdf

...and more to come!

Book Review: Distributed Programming with Ruby

Overview

Part I: Standard Library

Part II: Third-Party Frameworks and Libraries

Part III: Distributed Message Queues

Part IV: Distributed Programming with Ruby on Rails

Technical Analysis

Formatting and Readability

Style and Contents

Final Thoughts

Glyph 0.3.0 Released

New parser and performance improvements

Macro Attributes

Full XML support

Improved include macro and "safe mode"

What's next?

Glyph 0.2.0 Released

What Glyph code looks like

Notable features

Single-file compilation

Programmatic usage

Auto-regeneration

Conditional macros

What’s next?

Introducing Glyph

Lightweight markups

How Glyph can help

Technical Details

Disclaimer

For more information…

Book Review: Refactoring - Ruby Edition

Getting started

Diving in

The big picture

Conclusion

Book Review: The Merb Way

Getting started

It’s about how Merb works, not how to work with Merb

Some constructive criticism

Conclusion

Take back your site, with nanoc!

Why I don’t need a blog platform

Introducing site compilers

A quick overview of nanoc

Some details on the project

Sites, Items and data sources

Layouts, filters, and helpers

Rules and tasks

Migrating from your blog platform

Posts, pages and comments

Filters and highlighters

Tags and Feeds

3rd-party services

Conclusion

Personal Log - June 2009

H3RALD Web Site v8.0

Glyph

Vim files & the Stash

Getting ready for the Big Step

Personal Log - April 2009

Easter in London

Wedding planning

XBox 360 Gaming

Other tech-related tidbits

Concatenative 0.2.0 released

Personal Log - March 2009

Concatenative programming

Learning new programming languages?

Wedding planning

Other tech-related tidbits

Concatenative programming in Ruby

The Joy of concatenative programming

Improved `include` macro and "safe mode"