literate_maruku

→ ‘literate_maruku’

What

Literate Maruku is a literate programming libary for ruby based on the markdown libary maruku. This is basically what the name say, isn’t it?

Installing

sudo gem install literate_maruku

The basics

There are to possible accesses to the libary. A programming API and a command line interface. The first may be used to write better documented tests, for example. Just write a little bit of code in your test_helper and call Literate Maruku there and your markdown formatted tests will be executed.

The command line interface may the be used inside of a rake task for example to generate some html files out of your test files, that demonstrate their usage. We have used this approach in ContextR, so have a look there to get some input.

Demonstration of usage

The Markdown Syntax

Literate Maruku simply extends the functionality of Maruku and adds some methods to make standard use cases easier. You may find detailed information about maruku at their project page . They added some nice features to Markdown formatting , esp. the meta data syntax which made implementing literate maruku a charm.

Wanna see examples? Okay, here they are:

Markdown

This is a normal paragraph, followed by a plain old code block

    literate_maruku == maruku + ruby

And the following code block will not only be rendered, but also executed.

    def echo_block(string)
      (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")
    end
{: execute}

And, finally, the following block will be executed and its output will be 
rendered as well.

    echo_block("hallo")
{: execute attach_output}

This is how you may write your ruby code. And this is what will be generated out of it:

HTML

This is a normal paragraph, followed by a plain old code block

literate_maruku == maruku + ruby

And the following code block will not only be rendered, but also executed.

def echo_block(string)
  (0...(text.size)).map{|i| text[0..i]}.reverse.join(" ... ")
end

And, finally, the following block will be executed and its output will be rendered as well.

echo_block("hallo")
>> "hello ... hell ... hel ... he ... h"

The command line interface

Simply call literate_maruku filename.mkd to load your markdown formatted ruby files. This will execute the code but not generate any output. It basically works like a simpe ruby filename.rb call, but without all the command line parameters the ruby command supports.

If you like to generate some html files, append an additional parameter, which tells literate_maruku where to put the output. literate_maruku --output_path=test filename.mkd would file the output of filename.mkd to test/filename.html. That’s all, folks.

The programming interface

To use Literate Maruku in your own special way simply use the LiterateMaruku#require method.

require 'literate_maruku'

LiterateMaruku.require('filename.mkd') # or
LiterateMaruku.require('filename.mkd', :output => "test")

These will have the same result as the command line examples.

If you are unhappy with these little possibilities, no problem: You may still use the standard maruku interface to do with your markdown string, what you like after require’ing literate_maruku the maruku code base is extended for the literate programming style.

Other resources

• Mailing list
• RDoc

How to submit patches

Read the 8 steps for fixing other people’s code and for section 8b: Submit patch to Google Groups, use the Google Group above.

The trunk repository is svn://rubyforge.org/var/svn/rug-b/literate_maruku/trunk for anonymous access.

License

This code is free to use under the terms of the MIT license.

Contact

Comments are welcome. Send an email to Gregor Schmidt or via the mailing list

Gregor Schmidt, 30th September 2007
Theme extended from Paul Battley