view release on metacpan or  search on metacpan

lib/Math/Symbolic/Variable.pm  view on Meta::CPAN

      }
    );

=head1 DESCRIPTION

This class implements variables for Math::Symbolic trees.
The objects are overloaded in stringification context to
return their names.

=head2 EXPORT

None by default.

=cut

package Math::Symbolic::Variable;

use 5.006;
use strict;
use warnings;

use Math::Symbolic::ExportConstants qw/:all/;

use base 'Math::Symbolic::Base';

our $VERSION = '0.612';

=head1 METHODS

=head2 Constructor new

First argument is expected to be a hash reference of key-value
pairs which will be used as object attributes.

In particular, a variable is required to have a 'name'. Optional
arguments include a 'value', and a 'signature'. The value expected
for the signature key is a reference to an array of identifiers.

Special case: First argument is not a hash reference. In this
case, first argument is treated as variable name, second as value.
This special case disallows cloning of objects (when used as
object method).

Returns a Math::Symbolic::Variable.

=cut

sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;

    if (    @_ == 1
        and ref( $_[0] ) eq 'Math::Symbolic::Variable' )
    {
        return $_[0]->new();
    }
    elsif ( @_ and not ref( $_[0] ) eq 'HASH' ) {
        my $name  = shift;
        my $value = shift;
        return
          bless { name => $name, value => $value, signature => [@_] } => $class;
    }


    my $self = {
        value     => undef,
        name      => undef,
        signature => [],
        ( ref($proto) ? %$proto : () ),
        ((@_ and ref($_[0]) eq 'HASH') ? %{$_[0]} : ()),
    };

    bless $self => $class;
}

=head2 Method value

value() evaluates the Math::Symbolic tree to its numeric representation.

value() without arguments requires that every variable in the tree contains
a defined value attribute. Please note that this refers to every variable
I<object>, not just every named variable.

value() with one argument sets the object's value if you're dealing with
Variables or Constants. In case of operators, a call with one argument will
assume that the argument is a hash reference. (see next paragraph)

value() with named arguments (key/value pairs) associates variables in the tree
with the value-arguments if the corresponging key matches the variable name.
(Can one say this any more complicated?) Since version 0.132, an
equivalent and valid syntax is to pass a single hash reference instead of a
list.

Example: $tree->value(x => 1, y => 2, z => 3, t => 0) assigns the value 1 to
any occurrances of variables of the name "x", aso.

If a variable in the tree has no value set (and no argument of value sets
it temporarily), the call to value() returns undef.

=cut

sub value {
    my $self = shift;
    if ( @_ == 0 ) {
        return $self->{value};
    }
    elsif ( @_ == 1 and not ref( $_[0] ) eq 'HASH' ) {
        $self->{value} = shift;
        return $self->{value};
    }
    else {
        my $args = ( @_ == 1 ? $_[0] : +{@_} );
        if ( exists $args->{ $self->{name} } ) {
            return $args->{ $self->{name} };
        }
        else {
            return $self->{value};
        }
    }
    die "Sanity check in Math::Symbolic::Variable::value()";
}

=head2 Method name

Optional argument: sets the object's name.
Returns the object's name.

=cut

sub name {
    my $self = shift;
    $self->{name} = shift if @_;
    return $self->{name};