The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Array-PseudoScalar-1.02
River stage zero No dependents
++
/ Array::PseudoScalar

NAME

Array::PseudoScalar - Arrays that behave like scalars

SYNOPSIS

  use Array::PseudoScalar;

  my $subclass      = Array::PseudoScalar->subclass(';');
  my $schizophrenic = $subclass->new(qw/this is a pseudoscalar/);

  use 5.010;  # just for "say" below
  say "i'm an array" if @$schizophrenic;            # treated as an arrayref
  say "i'm a scalar" if length $schizophrenic;      # treated as a scalar
  say "i'm a pseudo" if $schizophrenic =~ /pseudo/; # treated as a scalar
  say $schizophrenic;          # "this;is;a;pseudoscalar"
  say @$schizophrenic;         # "thisisapseudoscalar"

  @$schizophrenic = sort @$schizophrenic;            # still a blessed object
  say $schizophrenic;          # "a;is;pseudoscalar;this"

  $schizophrenic =~ s/pseudo/plain /;                # no longer an object
  !eval{@$schizophrenic} and say "see, i'm no longer an array";

DESCRIPTION

Motivation

Sometimes lists of values need to be alternatively treated as arrays or as scalars (joined by a separator character), depending on the context. This is often the case for example with parameters of an HTTP query, or with "varray" columns in a database. Code dealing with such data is usually full of calls to join or split.

The present module provides a uniform interface for treating the same data both as an arrayref and as a scalar, implicitly joined on some separator: usual array and string operations are both available.

Caveat

If a string modification is applied (regex substitution, .= operator, etc.), the result is a new string copy, which is no longer an object and can no longer be treated like an arrayref. On the contrary, array modifications can be applied (push, shift, splice, etc.), and do preserve the object status (see the sort example in the synopsis above).

Interaction with Template Toolkit

Pseudoscalars from this module are stored internally as blessed arrayrefs. Since they are objects, the Template Toolkit doesn't treat them as raw data, which in this case is rather inconvenient. Therefore, some proxy methods are imported from the Template Toolkit, so that our pseudoscalars can also be used as list or as scalars within templates :

  My name is [% schizophenic.replace("scalar", "array") %].
  [% FOREACH item IN schizophrenic %]
     Here is a member item : [% item %]
  [% END; # FOREACH %]

Interaction with JSON

Likewise, "to_json" in JSON only exports objects who possess a TO_JSON() method; so such a method is also implemented here. JSON is really reluctant to emit any object data, so some additional calls are needed to make it work :

  my $converter = JSON->new->allow_blessed->convert_blessed;
  print $converter->to_json($schizophrenic); # ["FOO","BAR","BUZ"]

PUBLIC METHODS

subclass

  my $subclass = Array::PseudoScalar->subclass(';');

Takes a separator string as argument, and automatically generates a new subclass of Array::PseudoScalar, for building objects with that separator string. If the subclass was already generated by a previous call, it merely returns the class name.

new

  my $pseudoscalar = $subclass->new(@array);

Pseudoscalar constructor, taking an initial array as argument. Calling the new method on the parent class Array::PseudoScalar is an error: you have to "subclass" first to tell which separator string will be used.

INTERNAL METHODS

_stringify

This is the internal implementation of the overloaded stringification operator '""'.

TO_JSON

Returns a copy of the internal array, so that it can be emitted by JSON.

as_list, replace, search, remove, etc.

Methods imported from Template::Stash, so that pseudoscalars can be naturally used within templates, both as scalars and arrays.

SEE ALSO

overload, Array::Autojoin.

AUTHOR

Laurent Dami, <dami at cpan.org>

BUGS

Please report any bugs or feature requests to bug-array-pseudoscalar at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Array-PseudoScalar. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Array::PseudoScalar

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2011, 2012 Laurent Dami.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.