But the world is full of good and talented people!  Like the guys from 99soft. They created Maven Fluido Skin, and donated it to Apache Software Foundation. It’s built on top of Twitter’s Bootstrap and available from Maven central repository. In order to use it in your Maven project, all that you have to do is add the following settings into your src/site/site.xml:

<skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.2.1</version>
</skin>

Here’s a list of some projects using Maven Fluido Skin (hopefully, in the near future Apache Commons and other projects will adopt this skin as default too ):

• Maven Fluido Skin
• tap4j
• TestLink Java API

Regarding the Javadoc browsing, there’s a nice trick too: add class diagrams. I have seen a new Javadoc template in Apache Commons mailing list, but it was a work in progress, so for now I will stick with class diagrams. These diagrams are generated when you execute the javadoc or the site goals, using graphviz. And there is more. You can click on the diagram classes, as they have a link to the Java class that they reference to.

You can find instructions for setting up the diagram generation in Apache Maven web site, or looking at examples (I prefer the latter). But basically, you will need graphviz installed, and something like the following XML snippet in your project pom.xml.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.7</version>
    <configuration>
        <doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet>
        <docletArtifact>
            <groupId>gr.spinellis</groupId>
            <artifactId>UmlGraph</artifactId>
            <version>4.4</version>
        </docletArtifact>
        <additionalparam>
            -inferrel -inferdep -quiet -hide java.*
            -collpackages java.util.* -qualify
            -postfixpackage -nodefontsize 9
            -nodefontpackagesize 7
            -edgefontname "Trebuchet MS"
            -nodefontabstractname "Trebuchet MS"
            -nodefontclassabstractname
            "Trebuchet MS"
            -nodefontclassname "Trebuchet MS"
            -nodefontname
            "Trebuchet MS"
            -nodefontpackagename "Trebuchet MS"
            -nodefonttagname
            "Trebuchet MS"
        </additionalparam>
    </configuration>
</plugin>

Here’s how a diagram looks like (source: http://tap4j.org/apidocs/index.html):

Have fun! and remember to check if your CI machine has graphviz installed too, otherwise you will have 404 in your Javadoc pages

Cheers

• Apache Commons Functor has no Double or Float Range (yet)
• Apache Commons Functor IntegerRange and LongRange treat the low value as inclusive, and the high value as exclusive. How does that compare to other languages/APIs? (you will have to read to see some comparison)
• Perl has support for characters ranges, perhaps we could implement it in Functor too?
• In case we implemented a CharacterRange, it would have to be inclusive for both low and high limits. With ‘z’ being the last character, there wouldn’t have a way to include Z with the current approach. Or we would have to make the CharacterRange a special one. What would go against Liskov Substitution Principle.
• You can see a comparison table with Apache Commons Functor, other Java API’s and other programming languages for ranges clicking here.
• It would be nice to have a clear distinction in Functor documentation among a Sequence, a Generator and a Range. While I was gathering material for this post, I found places using range, others using sequence, and in Apache Commons Functor, an IntegerRange is a Generator.

Now, if you have some spare time or curiosity, keep reading

This post is about ranges in Apache Commons Functor but first let me explain the context. I am working on nebular, an open source fuzzy logic API. This API is written in pure Java, and has Matlab Fuzzy Toolbox as reference for the initial release. Nebular will use functional programming to let the user to model his/her membership functions. The API chosen for functional programming is Apache Commons Functor.

Yesterday I finished to port sigmf function to nebular, including some tests that compare nebular’s output to Matlab sigmf function. However, here comes the issue with ranges, sequences and generators. The idea is to plot a graph similar to the one below.

The x axis contains values from 0 to 10, increasing by 0.1. In Matlab, I would execute the following command to produce the x vector.

x = 0:0.1:10;

The : is the range operator in Matlab. It would create a vector with 101 elements. Yup, 101. That’s because in Matlab the low and high value used creating the range are inclusive. Now let’s look at how I create similar vector in Apache Commons Functor.

IntegerRange range = new IntegerRange(0, 11, 1 /* step */);

So now one can realize two things: there is no Double or Float Range, and the high value in the range is exclusive. It means that in order to create an array (I will use vector and array interchangeably here for simplicity) with Functor from 0 to 10, including both values, you have to create a range using 0 and 11.

Comparing with other Java functional programming API’s

There are other API’s to include functional programming features to Java code. In this comparison I will include Google Guava, fun4j, functionaljava, lambdaj and op4j (got the list from the fun4f project page).

Google Guava

Google Guava provides the Range and Ranges classes. The Ranges contains several static methods for creating Range’s, that can be used as collections. The Ranges class contains methods for creating Range’s with open, closed, openClosed and closedOpen intervals.

public static void main(String[] args) {
 Range<Integer> values = Ranges.closed(0, 10);
 System.out.print("[ ");
 for(Integer value : values.asSet(DiscreteDomains.integers())) {
 System.out.print(value + " ");
 }
 System.out.print("]");
 }

[ 0 1 2 3 4 5 6 7 8 9 10 ]

The Google Guava API does not provide a way to create ranges of floats. And I will have to find some time to read about the asSet method and on discrete domains. I am much more comfortable putting Apache Commons Functor API in my code for creating ranges. Specially since it makes the code more readable and easy to understand, helping to receive contributions in nebular from newcomers.

fun4j

fun4j contains classes to model functions, lambdas and bind LISP code to Java. However it has no objects for ranges.

functionaljava

Although there is the Seq class, I don’t know if that can be used for Ranges. So I will have to skip functionaljava

lambdaj

Couldn’t find a way to create ranges with lambdaj. Not sure if they support it or not.

op4j

Same as lambdaj, couldn’t find a way to create ranges with op4j. Not sure if they support it or not.

Comparing with other programming languages

So let’s see how we could generate a similar array using other programming languages.

Python

Python is one of my favorite languages, and has some functional programming features [1]. However it has no built-in mechanism for ranges with floats, only with integers. The functions that I know in Python use low value as inclusive, and high value as exclusive. The built in range functions in 2.7 looks like the following.

x = range(0, 11, 1) #inclusive/exclusive
print x;
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Or you could write something like (remember Perl’s motto, TIMTOWTDI [2])

x = [x * 0.1 for x in range(0, 101)]; #inclusive/exclusive
print len(x);
 print x;
101
 [0.0, 0.1, 0.2, 0.30000000000000004, 0.4, ..., 10.0]

There are API’s in Python too, like numpy, that has arange. However it is complicated specify a range to give similar array as the one produced by Matlab.

from numpy import arange;
x = arange(0, 10.1, .1); #inclusive/exclusive
print len(x);
 print x;
101
 [ 0. 0.1 0.2 ... 10.0]

Perl

As we mentioned Perl in last section, let’s see how it works in Perl. First of all, I won’t use many modules here. Probably Perl is the language with more modules, or at least with a plethora of modules in CPAN (wait to see CJAN . There are books on Perl and Functional programming [3], and Perl has a built in mechanism for ranges. I used Perl 5 built in range operator and List::Gen range function. Both use the low and high value inclusive. It’s important to point out that Larry Wall and the programmers behind Perl are always keeping an eye on usability, ease of use, and Larry’s laziness. So that’s why Perl is a good language for comparisons of this type.

#!/usr/bin/perl
use strict;
use warnings;
use feature 'say';
print "[ ";
for(0..10) { #inclusive/inclusive
 print $_, " ";
}
print " ]"

[ 0 1 2 3 4 5 6 7 8 9 10 ]

Or to use floats, we could use List::Gen module.

#!/usr/bin/perl
use strict;
use warnings;
use feature 'say';
use List::Gen;
my $range = range 0, 10, 0.1; #inclusive/inclusive
print "[ ";
print $_, " " for @$range;
print " ]"

[ 0 0.1 0.2 0.3 0.4 ... 10 ]

Perl also has support to range of characters. Look at the examples from Perldoc.

 @alphabet = ("A" .. "Z"); # inclusive/inclusive... how would it work if the last argument was not inclusive?

That would be cool if Functor had this feature too

Scala

Scala is a language that runs on the Java Virtual Machine, it has some functional programming features as anonymous functions, higher order functions, among others. It has a built in mechanism for ranges with integers or floats. It uses the low value as inclusive, and the high value as exclusive, however when using floats you may have trouble if you don’t pay attention to float precision.

object Test {
def main(args: Array[String]) {
var range = 0.0 until 10.0 by 0.1;
println(range);
}
}

NumericRange(0.0, 0.1, 0.2, ..., 9.99999999999998)

Matlab

Why, yes sir, we will compare Matlab too. It has built in operator for ranges, and both values, low and high, are inclusive.

x=0:0.1:10;
display(x);
x =
Columns 1 through 9
0 0.1000 ...
... 10.0000

PHP

Although famous for its web applications, PHP can be an interesting language for scripting or creating handy utilities. I may be wrong, but I believe the scm_bot in Jenkins project, that posts messages to JIRA when someone commits to a SCM with a special string, is written in PHP. It has a built in function for ranges in 5.3, and both values are inclusive.

$range = range(0, 10, 0.1);
 echo "[ ";
 foreach($range as $number) {
 echo $number . " ";
 }
 echo "]";
[ 0 0.1 0.2 0.3 ... 9.9 10 ]

Haskell

Haskell has gained more attention lately with web frameworks. It has features such as monads, functors and high order function. And also has a built-in range operator. Both, left and right values of the range are inclusive in Haskell’s range operator.

[0 .. 10]
=> [0,1,2,3,4,5,6,7,8,9,10]

Unfortunately I don’t know Haskell so well, and couldn’t make it work with floats, nor find out whether it is possible or not

lua

While lua has no built-in support to ranges, if you search for lua and range functions or operators, probably you will find an entry in lua’s Wiki with a range function, contributed by a user. The function implemented uses the low and high value inclusively and has support for both integer and floats.

-- http://lua-users.org/wiki/RangeIterator
function range(from, to, step)
 step = step or 1
 return function(_, lastvalue)
 local nextvalue = lastvalue + step
 if step > 0 and nextvalue <= to or step < 0 and nextvalue >= to or
 step == 0
 then
 return nextvalue
 end
 end, nil, from - step
end
function f() return 0, 10, 0.1 end
io.write("[ ");
for i in range(f()) do
 io.write(i, " ")
end
io.write("]");

[ 0 0.1 0.2 0.3 ...  9.9 10 ]

LISP

Lisp is probably one of the oldest programming languages with functional features. Every time I read something about functional programming and collections it reminds me of Lisp recursion with lists. In Lisp you can use loop to iterate over a range of integers or floats, and both values are included for integers, for float, there is some precision problem that I couldn’t overcome. For integers the following code would do.

>(loop for i from 0 to 10 do (print i))
0
1
2
...
10
NIL

And for floats.

>(loop for i from 0.0 to 10.0 by 0.1 do (print i))
0.0
0.1
0.2
...
9.900002
NIL

Again, issues with precision.

Clojure

Although Clojure is quite similar to LISP, I had some trouble setting up an example for this. My first try was with loop, but as it didn’t work, I used dorun. It uses the low value as inclusive, and the high value as exclusive. Strange, I thought it would have similar behavior to the loop in LISP. But I only know the very basics of each language, and the explanation is beyond my knowledge. Anyway, it’s interesting I guess.

(dorun (for [i (range 0 10 1)] (println i)))
0
1
...
9
nil

Comparison Table

To simplify the understanding, here is a comparison table.

That’s it, I will ping some guys from Apache dev-list to see what they think about the bullets in TL;DR. After writing this post I realized I need to change this blog’s layout to give more space for code and tables

Cheers

[1] http://docs.python.org/howto/functional.html

[2] http://c2.com/cgi/wiki?ThereIsMoreThanOneWayToDoIt

[3] http://perl.plover.com/yak/fp/

But you know what? Why not execute execute locally first to check if that’s working… moreover, why not use Jenkins TAP Plug-in and see what happens?

Here’s what is necessary.

• Jenkins (duh)
• tap plug-in
• git plug-in
• Bats git repository URL
• Baden Baden Red Ale beer (it’s Friday, almost new years’ eve, c’mon)

Install Jenkins, tap plug-in and git plug-in. Create a new free style build. Add Bats git repository url under SCM. This way Jenkins will retrieve Bats code from Github (you don’t need to install it if you don’t want to). Add a build step which executes the following shell code: ./bin/bats test/bats.bats > test.t

Before executing the build, you have to check the option to publish TAP results in the end of the configuration screen. That’s it. Execute your job, chug the remaining of your beer and now you can go to bed… or just refresh Hacker News and Reddit once more…

Bats is a very nice TAP producer for Shell. Haven’t had time to play with the other producers for Shell, or explore Bats thoroughly, but it looks very promising. Hope to see more people writing tests for shell code.

Cheers -B