NAME

       Scalar::Properties - run-time properties on scalar variables

SYNOPSIS

         use Scalar::Properties;
         my $val = 0->true;
           if ($val && $val == 0) {
           print "yup, its true alright...\n";
         }

         my @text = (
           'hello world'->greeting(1),
           'forget it',
           'hi there'->greeting(1),
         );
         print grep { $_->is_greeting } @text;

         my $l =  'hello world'->length;

DESCRIPTION

       Scalar::Properties attempts to make Perl more object-oriented by taking an idea from Ruby:
       Everything you manipulate is an object, and the results of those manipulations are objects
       themselves.

         'hello world'->length
         (-1234)->abs
         "oh my god, it's full of properties"->index('g')

       The first example asks a string to calculate its length. The second example asks a number
       to calculate its absolute value. And the third example asks a string to find the index of
       the letter 'g'.

       Using this module you can have run-time properties on initialized scalar variables and
       literal values. The word 'properties' is used in the Perl 6 sense: out-of-band data,
       little sticky notes that are attached to the value. While attributes (as in Perl 5's
       attribute pragma, and see the "Attribute::*" family of modules) are handled at compile-
       time, properties are handled at run-time.

       Internally properties are implemented by making their values into objects with overloaded
       operators. The actual properties are then simply hash entries.

       Most properties are simply notes you attach to the value, but some may have deeper
       meaning. For example, the "true" and "false" properties plays a role in boolean context,
       as the first example of the Synopsis shows.

       Properties can also be propagated between values. For details, see the EXPORTS section
       below. Here is an example why this might be desirable:

         pass_on('approximate');
         my $pi = 3->approximate(1);
         my $circ = 2 * $rad * $pi;

         # now $circ->approximate indicates that this value was derived
         # from approximate values

       Please don't use properties whose name start with an underscore; these are reserved for
       internal use.

       You can set and query properties like this:

       "$var->myprop(1)"
           sets the property to a true value.

       "$var->myprop(0)"
           sets the property to a false value. Note that this doesn't delete the property (to do
           so, use the "del_props" method described below).

       "$var->is_myprop", "$var->has_myprop"
           returns a true value if the property is set (i.e., defined and has a true value). The
           two alternate interfaces are provided to make querying attributes sound more natural.
           For example:

             $foo->is_approximate;
             $bar->has_history;

METHODS

       Values thus made into objects also expose various utility methods.  All of those methods
       (unless noted otherwise) return the result as an overloaded value ready to take properties
       and method calls itself, and don't modify the original value.

   INTROSPECTIVE METHODS
       These methods help in managing a value's properties.

       "$var-"get_props>
           Get a list of names of the value's properties.

       "$var-"del_props(LIST)>
           Deletes one or more properties from the value. This is different than setting the
           property value to zero.

       "$var-"del_all_props>
           Deletes all of the value's properties.

   NUMERICAL METHODS
       "plus(EXPR)"
           Returns the value that is the sum of the value whose method has been called and the
           argument value. This method also overloads addition, so:

             $a = 7 + 2;
             $a = 7->plus(2);    # the same

       "minus(EXPR)"
           Returns the value that is the the value whose method has been called minus the
           argument value. This method also overloads subtraction.

       "times(EXPR)"
           Returns the value that is the the value whose method has been called times the
           argument value. This method also overloads multiplication.

       "divide(EXPR)"
           Returns the value that is the the value whose method has been called divided by the
           argument value. This method also overloads division.

       "modulo(EXPR)"
           Returns the value that is the the value whose method has been called modulo the
           argument value. This method also overloads the modulo operator.

       "exp(EXPR)"
           Returns the value that is the the value whose method has been called powered by the
           argument value. This method also overloads the exponentiation operator.

       "abs"
           Returns the absolute of the value.

       "zero"
           Returns a boolean value indicating whether the value is equal to 0.

   STRING METHODS
       "length", "size"
           Returns the result of the built-in "length" function applied to the value.

       "reverse"
           Returns the reverse string of the value.

       "uc", "ucfirst", "lc", "lcfirst", "hex", "oct"
           Return the result of the appropriate built-in function applied to the value.

       "concat(EXPR)", "append(EXPR)"
           Returns the result of the argument expression appended to the value.

       "swapcase"
           Returns a version of the value with every character's case reversed, i.e. a lowercase
           character becomes uppercase and vice versa.

       "split /PATTERN/, LIMIT"
           Returns a list of overloaded values that is the result of splitting (according to the
           built-in "split" function) the value along the pattern, into a number of values up to
           the limit.

   BOOLEAN METHODS
       "numcmp(EXPR)"
           Returns the (overloaded) value of the numerical three-way comparison.  This method
           also overloads the "<=>" operator.

       "cmp(EXPR)"
           Returns the (overloaded) value of the alphabetical three-way comparison.  This method
           also overloads the "cmp" operator.

       "eq(EXPR)", "ne(EXPR)", "lt(EXPR)", "gt(EXPR)", "le(EXPR)", "ge(EXPR)"
           Return the (overlaoded) boolean value of the appropriate string comparison. These
           methods also overload those operators.

       "eqi(EXPR)", "nei(EXPR)", "lti(EXPR)", "gti(EXPR)", "lei(EXPR)", "gei(EXPR)"
           These methods are case-insensitive versions of the above operators.

       "is_true", "is_false"
           Returns the (overloaded) boolean status of the value.

EXPORTS

       Three subroutines dealing with how properties are propagated are automatically exported.
       For an example of propagation, see the DESCRIPTION section above.

       "pass_on(LIST)"
           Sets (replaces) the list of properties that are passed on. There is only one such list
           for the whole mechanism. The whole property interface is experimental, but this one in
           particular is likely to change in the future.

       "passed_on(STRING)"
           Tests whether a property is passed on and returns a boolean value.

       "get_pass_on"
           Returns a list of names of properties that are passed on.

TAGS

       If you talk about this module in blogs, on del.icio.us or anywhere else, please use the
       "scalarproperties" tag.

BUGS AND LIMITATIONS

       No bugs have been reported.

       Please report any bugs or feature requests to "bug-scalar-properties@rt.cpan.org", or
       through the web interface at <http://rt.cpan.org>.

INSTALLATION

       See perlmodinstall for information and options on installing Perl modules.

AVAILABILITY

       The latest version of this module is available from the Comprehensive Perl Archive Network
       (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you. Or see
       <http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.

AUTHORS

       Marcel Gruenauer, "<marcel@cpan.org>"

       James A. Duncan "<jduncan@fotango.com>"

       Some contributions from David Cantrell, "<david@cantrell.org.uk>"

COPYRIGHT AND LICENSE

       Copyright 2001-2007 by Marcel Gruenauer

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