NAME

Array::Autojoin -- arrayrefs that stringify as join(", ", @$it)

SYNOPSIS

  use Array::Autojoin;
  my $headword = "biscocho";
  my $gloss = mkarray("cookie", "biscuit");
  print "$headword\: $gloss.\n";
  
   # Prints "biscocho: cookie, biscuit.\n";

DESCRIPTION

This extremely short and simple module provides one exported function, mkarray( ...items... ), which makes an arrayref (containing those items) belonging to a class that does nothing other than specifying to Perl that when you want the string value of that arrayref, instead of giving something like "ARRAY(0x171568f)", it returns a happy string consisting of join(', ', @$arrayref).

Also, rather incidentally:

* In boolean context (like print "Yow!" if $arrayref), the boolean value is true iff the reference is to an array containing at least one boolean-true value. So:

  mkarray()            is boolean-false -- no values at all
  mkarray('','','','') is boolean-false -- no values are true
  mkarray('',0,undef ) is boolean-false -- no values are true
  mkarray('', 123    ) is boolean-true -- there's a true value (123)
  mkarray("PIE"      ) is boolean-true -- there's a true value ("PIE")

* In numeric scalar context -- where join(', ', @$arrayref) would be unhelpful -- you get the numeric value of the first item (or zero if there's no items):

  my $z = mkarray(3,7,19,63,30);
  print 39 + $z;   # numeric $z yields 3, so this prints 42

* ".=" is overloaded to append to the last element (or in the case of an empty array, to create a new element):

  my $headword = "biscocho";
  my $gloss = mkarray("cookie", "biscuit");
  $headword .= "!";
  $gloss    .= "!";
  
  print "$headword\: $gloss\n";
   # Prints "biscocho!: cookie, biscuit!\n"

  push @$gloss, "hooboy";
   # see, can still treat it like a normal array ref

  printf "Count of glosses: %d\n", scalar(@$gloss);
   # Prints:  Count of glosses: 3

  print "Gloss bits: ", map("<$_> ", @$gloss), "\n";
   # Prints:  Gloss bits: <cookie> <biscuit!> <hooboy> 

NOTES

* If you want to know how this class works, look at its source, and cf. the "overload" man page.

* If you want a class that works sort of like this one, but different, then feel free to make your own, using this class as a model.

* Remember, once you stringify something, it's not an object anymore!

  use strict;
  my $gloss = mkarray("cookie", "biscuit");
  $gloss = "<" . $gloss . ">";
   # and shazam, it's stringified, and the string gotten from
   #  putting "<" and ">" around it, is put back into $gloss,
   #  replacing the arrayref.
  print "It's $gloss!\n";
   # It's <cookie, biscuit>!
  printf "Count of glosses: %d\n", scalar(@$gloss);
   # DIES with:  Can't use string ("<cookie, biscuit>") as an ARRAY
   #              ref while "strict refs" in use [at ...]

SEE ALSO

overload, Data::MultiValuedHash

COPYRIGHT

Copyright 2001 Sean M. Burke.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Sean M. Burke, <sburke@cpan.org>