NAME

PerlMaple::Expression - Perl AST for arbitrary Maple expressions

VERSION

This document describes PerlMaple::Expression 0.02 released on December 19, 2005.

SYNOPSIS

use PerlMaple::Expression;

$expr = PerlMaple::Expression->new('x^3+2*x-1');
print $expr->expr;  # got: x^3+2*x-1
print $expr->type;  # got: `+`

@objs = $expr->ops;
@exps = map { $_->expr } @objs;
print "@exps";    # got: x^3 2*x -1

# $objs[0] is another PerlMaple::Expression obj
#    corresponding to 'x^3':
print $objs[0]->type;  # got: `^`
@exps = map { $_->expr } $objs[0]->ops;
print "@exps";    # got: x 3

# $objs[1] is yet another PerlMaple::Expression obj
#    corresponding to '2*x':
print $objs[1]->type;  # got: `*`
@exps = map { $_->expr } $objs[1]->ops;
print "@exps";    # got: 2 x

DESCRIPTION

This class represents an Abstract Syntactic Tree (AST) for any Maple expressions. It provides several very useful methods and attributes to manipulate Maple expressions effectively and cleanly.

Hey, there's no parser written in Perl! I used Maple's functions to import the ASTs. For example, functions like whattype, nops, and op. So, don't worry for the sanity of this library.

METHODS

->new($expr, ?$verified)

This is the constructor of the PerlMaple::Expression class. The first argument $expr is any Maple expression (not Maple statements though) from which the AST is constructed. The second argument $verified is optional. When it's set true, the expression will skip validity check in Maple's engine, otherwise the first argument will be evaluated by Maple to verify its sanity. If the second argument is absent, it is implied to be false. That's to say, verification will be performed by default.

->ops

In list context, the ops method returns the list of operands of the current Maple expression. Every element of the resulting list is still a PerlMaple::Expression object.

Observe the following code:

$ast = PerlMaple::Expression->new('[1,2,3]');
@ops = $ast->ops;  # a list of PerlMaple::Expression instances
@elems = map { $_->expr } @ops;  # we get a list of integers (1, 2, and 3)

We see, the array @ops will contain three PerlMaple::Expression objects corresponding to Maple expressions '1', '2', and '3', respectively. Therefore, the following tests will pass:

is $ops[0]->type, 'integer';
is $ops[1]->type, 'integer';
is $ops[2]->type, 'integer';

Internally, ->ops method calls Maple's op function to get the operands. For atomic expressions, such as integers and symbols, ->ops will simply return the expr itself.

When used in scalar context, this method will simply return the number of operands, calculated by Maple's nops function internally.

->expr

Returns the expression corresponding to the current PerlMaple::Expression object. Note that the string returned may be different from the one passed to the constructor. Because it will be evaluated in Maple to check the validity. Hence, the following tests will pass:

$ast = PerlMaple::Expression->new('2,        3,4');
is $ast->expr, '2, 3, 4';

However, when you pass a true value as the second argument to the constructor, the validity check will be skipped:

$ast = PerlMaple::Expression->new('2,        3,4', 1);
is $ast->expr, '2,        3,4';

->type

Get the type of the current Maple expression via Maple's whattype function. It is worth mentioning that the type of the expression is evaluated when the object is constructing, so there's no extra cost to invoke this method repeatedly.

->type($new_value)

Test whether the current Maple expression is of the specified type. Note that this method calls Maple's type function to test the type equality. So the following tests will happily pass:

$ast = PerlMaple::Expression->new('3.5');
ok $ast->type($ast, 'numeric');
ok $ast->type($ast, 'type');

When the expression is of type 'exprseq', this method won't use Maple's type function since it will croak on expression sequences. Instead, the ->type method will return true if and only if the given type is exactly the same as 'exprseq'.

CODE COVERAGE

I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover report on this module's test suite (version 0.02):

---------------------------- ------ ------ ------ ------ ------ ------ ------
File                           stmt   bran   cond    sub    pod   time  total
---------------------------- ------ ------ ------ ------ ------ ------ ------
blib/lib/PerlMaple.pm          94.8   86.4   66.7  100.0  100.0   98.1   93.2
...b/PerlMaple/Expression.pm  100.0   94.4   66.7  100.0  100.0    1.9   95.1
Total                          97.1   90.0   66.7  100.0  100.0  100.0   94.1
---------------------------- ------ ------ ------ ------ ------ ------ ------

AUTHOR

Agent Zhang, <agent2002@126.com>

SEE ALSO

PerlMaple