Liquid Development

Intent-0.3 is out on RubyForge, and it also includes the latest version of Proze.  You can get it here.

In this version I have cleaned up things a bit and I have also included a sample intent.

Let me give you an overview of how it works.

I will assume you already have a project and some ruby files in it.  You can now write an intent file for one of your files.
Let's assume that your project is redefining mathematics and you have a mathematics.rb file.  Then you need to create an intent_of_mathematics.rb file.

Well, all you really need is to have the file to start with "intent_of", but I hope to exploit this convention in future developments to create links between code and its intents.

The first thing you do in your intent file is to import the intent definitions:

require 'intent/all'

Then you start declaring a number of intents about what your mathematical code should do.  In this example I am just parroting ruby's arithmetics.

intent_of("Adding One") {

...

}

intent_of("Commutative Property of Addition") {

...

}

Then you flesh out those intents by specifying concrete expectations:

intent_of("Adding One") {

    (0 + 1).should_be 1

    (1 + 1).should_be 2

    (2 + 1).should_be 3

}

intent_of("Commutative Property of Addition") {

    (2 + 1).should_be_equal_to(1 + 2)

    (2 + 3).should_be_equal_to(3 + 2)

}

You can even simply state that you expect something to be true or false:

intent_of("Comparison - Lesser Than") {

    expect 0 < 1

    expect 1 < 2

    dont_expect 2 < 1

}

You can even specify that in certain instances you expect an exception to be raised:

intent_of("Recognising Illegal Operations"){

    expect_exception(ZeroDivisionError){

        #when trying to calculate

        5 / 0

    }

}

I made the comment a bit verbose for the purposes of Proze.

Proze is a program used by Intent to produce readable documents from the intents.

Finally you can specify Stories or Use Cases, that describe the cumulative effects of a number of operations, usually as seen by the user as a unit-sized interaction.

story("Calculating the Area of a Triangle"){

    base   = 10

    height = 5

    area   = base * height / 2

   

    expect 25, as=area

}

Now we can run a Reality Check on our expectations by simply running the program.  You just press F5 on most IDEs.
What you get is:

---------- Reality checking Adding One ----------
Consistent intent: ..1..
Consistent intent: ..2..
Consistent intent: ..3..
---------- Reality checking Commutative Property of Addition ----------
Consistent intent: ..3..
Consistent intent: ..5..
---------- Reality checking Comparison - Lesser Than ----------
Consistent intent: ..true..
Consistent intent: ..true..
Consistent intent: ..false..
---------- Reality checking Recognising Illegal Operations ----------
Consistent intent: ..'expected exception'..
---------- Reality checking Calculating the Area of a Triangle ----------
Consistent intent: ..25..
---------- Reality checking Calculating the Volume of a Prism ----------
Consistent intent: ..500..

---------------------------------------------------------
Broken Expectations
---------------------------------------------------------
---------------------------------------------------------

----------------
Reality Checking
---------------------------------------------------------
intents: 6                 expectations: 11
---------------------------------------------------------
passed intents: 6/6        passed expectations: 11/11
broken intents: 0/6        broken expectations: 0/11
---------------------------------------------------------
expectations per intent: 1.8
---------------------------------------------------------

We get information on every intent, story and expectation that we have run, also producing a summary detailing the broken intents and expectations and the ratio between expectations and intents.  This ratio gives you a feeling for the granularity of your intents.

You can also create a reality-check file that can handle several intent files.  You can write a reality-check.rb file (another convention) as:

require 'intent/all'

reality_check 'intent/demo'

intent/demo is the directory containing my intent file.  All intent files in that directory get reality checked and prozed.

A prozed file gets massaged to make it more legible.  The previously described intent file becomes: prose_of_intent_of_mathematics.txt

require 'intent/all'

intent of "Adding One" 

     0 + 1  should be 1

     1 + 1  should be 2

     2 + 1  should be 3

intent of "Commutative Property of Addition" 

     2 + 1  should be equal to 1 + 2

     2 + 3  should be equal to 3 + 2

intent of "Comparison - Lesser Than" 

    expect 0 < 1

    expect 1 < 2

    dont expect 2 < 1

intent of "Recognising Illegal Operations"

    expect exception ZeroDivisionError

        when trying to calculate

        5 / 0  

story "Calculating the Area of a Triangle"

    base   = 10

    height = 5

    area   = base * height / 2

   

    expect 25, as area

story "Calculating the Volume of a Prism"

    base        = 10

    base height = 5

    height      = 20

   

    base area = base * base height / 2

    volume    = base area * height   

   

    expect 500, as volume