Learning Perl5i #3 revisted

I was somewhat uncomfortable that my solution to the combinatorics task, which involved a single, not very long routine, became so long with the addition of command line processing and POD  documentation. For one thing, while it had some information about how to invoke the routine, it did not have tests.

I still feel that a book on programming, say, should have a fully-implemented solution once a chapter, perhaps, to show the way things should be done. But that is too long for every single bit of code. Full documentation and sample implementations stretch on too long, compared to the few lines a snippet actually deserves.

Providing tests may still be appropriate. They take up less space than full documentation, yet explain how the various components work, by the very act of stress-testing those lines of code. Tests provide examples of how the code should be invoked.

Revising the combinatorics task into a module, this generates:

use perl5i::2;

# ----------------------------------------
# generate combinations of length $n consisting of characters
# from the sorted set @set, using each character once in a
# combination, with sorted strings in sorted order.
#
# Returns a list of array references, each containing one 
# combination.
#
func combine($n, @set) {
    return unless @set;
    return map { [ $_ ] } @set if $n == 1;

    my ($head) = shift @set;
    my @result = combine( $n-1, @set );
    for my $subarray ( @result ) {
$subarray->unshift( $head );
    }
    return ( @result, combine( $n, @set ) );
}

# ------------------------------------------------------------------
# Tests
#
func runtests() {
    eval { use Test::More }; # only include if testing

    test_no_set();
    test_length_zero();
    test_length_one();
    test_longer();
    done_testing();
}

func test_no_set() {
  is( combine( 1, () ), undef, 
      'set == empty list returns empty array' );
  is( combine( 1 ), undef, 
      'set not provided returns empty array' );
}

func test_length_zero() {
  is( combine( 0, 'a' ), undef, 'zero length returns empty array' );
}

func test_length_one() {
  my ( @results ) = combine( 1, 'a' );
  is_deeply( \@results, [['a']],
    'length 1 returns unary set as array element');

  @results = combine( 1, 'a', 'b', 'c' );
  is_deeply( \@results, [['a'], ['b'], ['c']],
    'length 1 returns larger set as array elements');
}
func test_longer() {
  my ( @results ) = combine( 2, 'a', 'b', 'c' );
  is_deeply( \@results, [['a', 'b'], ['a', 'c'], ['b', 'c']],
    'longer length generates list of  combinations');
}
# ------------------------------------------------------------------
# Run tests if invoked as a program, rather than in cluded as a 
# module.
#
runtests() unless caller();

Output from invoking the module as a program:

bash-3.2$ perl combinations.pli
ok 1 - set == empty list returns empty array
ok 2 - set not provided returns empty array
ok 3 - zero length returns empty array
ok 4 - length 1 returns unary set as array element
ok 5 - length 1 returns larger set as array elements
ok 6 - longer length generates list of  combinations
1..6