[vienna.pm] [ANNOUNCE] Scalar::Properties 0.10

[Marcel Grunauer]

* * * vienna-pm-list * * *


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.

BUGS
    None known so far. If you find any bugs or oddities, please do inform
    the authors.

AUTHORS
    James A. Duncan <jduncan at fotango.com>

    Marcel Grunauer, <marcel at codewerk.com>

COPYRIGHT
    Copyright 2001 Marcel Grunauer, James A. Duncan. All rights reserved.

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

SEE ALSO
    perl(1), overload(3pm), Perl 6's properties.


Marcel

-- 
We are Perl. Your table will be assimilated. Your waiter will adapt to
service us. Surrender your beer. Resistance is futile.
 -- London.pm strategy aka "embrace and extend" aka "mark and sweep"
###
You are subscribed to vienna-pm-list as Marcel Grunauer <marcel at codewerk.com>
http://www.fff.at/fff/vienna.pm/