NAME

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

VERSION

version 1.100860

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;

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.

METHODS

get_props

Get a list of names of the value's properties.

del_props(LIST)

Deletes one or more properties from the value. This is different than setting the property value to zero.

del_all_props

Deletes all of the value's properties.

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.

length

Returns the result of the built-in length function applied to the value.

size

Same as length().

reverse

Returns the reverse string of the value.

uc

Returns the result of the built-in function uc() applied to the value.

ucfirst

Returns the result of the built-in function ucfirst() applied to the value.

lc

Returns the result of the built-in function lc() applied to the value.

lcfirst

Returns the result of the built-in function lcfirst() applied to the value.

hex

Returns the result of the built-in function hex() applied to the value.

oct

Returns the result of the built-in function oct() applied to the value.

concat(EXPR)

Returns the result of the argument expression appended to the value.

append(EXPR)

Same as concat(EXPR).

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.

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)

Return the (overloaded) boolean value of the eq string comparison. This method also overloads that operators.

ne(EXPR)

Return the (overloaded) boolean value of the ne string comparison. This method also overloads that operators.

lt(EXPR)

Return the (overloaded) boolean value of the lt string comparison. This method also overloads that operators.

gt(EXPR)

Return the (overloaded) boolean value of the gt string comparison. This method also overloads that operators.

le(EXPR)

Return the (overloaded) boolean value of the le string comparison. This method also overloads that operators.

ge(EXPR)

Return the (overloaded) boolean value of the ge string comparison. This method also overloads that operators.

eqi

Same as eq(), but is case-insensitive.

nei>

Same as ne(), but is case-insensitive.

lti

Same as lt(), but is case-insensitive.

gti

Same as gt(), but is case-insensitive.

lei

Same as le(), but is case-insensitive.

gei

Same as ge(), but is case-insensitive.

is_true

Returns whether the (overloaded) boolean status of the value is true.

is_false

Returns whether the (overloaded) boolean status of the value is false.

create

FIXME

del_prop

FIXME

do_downto

FIXME

do_downto_step

FIXME

do_upto

FIXME

do_upto_step

FIXME

false

FIXME

gen_meth

FIXME

handle

FIXME

times_do

FIXME

true

FIXME

value

FIXME

FUNCTIONS

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. This function is exported automatically.

passed_on(STRING)

Tests whether a property is passed on and returns a boolean value. This function is exported automatically.

get_pass_on

Returns a list of names of properties that are passed on. This function is exported automatically.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=Scalar-Properties.

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://search.cpan.org/dist/Scalar-Properties/.

The development version lives at http://github.com/hanekomu/Scalar-Properties/. Instead of sending patches, please fork this project using the standard git and github infrastructure.

AUTHOR

Marcel Gruenauer <marcel@cpan.org>

COPYRIGHT AND LICENSE

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

To install Scalar::Properties, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Scalar::Properties

CPAN shell

perl -MCPAN -e shell
install Scalar::Properties

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

get_props

del_props(LIST)

del_all_props

plus(EXPR)

minus(EXPR)

times(EXPR)

divide(EXPR)

modulo(EXPR)

exp(EXPR)

abs

zero

length

size

reverse

uc

ucfirst

lc

lcfirst

hex

oct

concat(EXPR)

append(EXPR)

swapcase

split /PATTERN/, LIMIT

numcmp(EXPR)

cmp(EXPR)

eq(EXPR)

ne(EXPR)

lt(EXPR)

gt(EXPR)

le(EXPR)

ge(EXPR)

eqi

nei>

lti

gti

lei

gei

is_true

is_false

create

del_prop

do_downto

do_downto_step

do_upto

do_upto_step

false

gen_meth

handle

times_do

true

value

FUNCTIONS

pass_on(LIST)

passed_on(STRING)

get_pass_on

INSTALLATION

BUGS AND LIMITATIONS

AVAILABILITY

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions