File Coverage

blib/lib/Math/Symbolic/Custom/Pattern/Export.pm

Criterion	Covered	Total	%
statement	29	33	87.8
branch	5	14	35.7
condition	2	6	33.3
subroutine	9	9	100.0
pod	2	2	100.0
total	47	64	73.4

package Math::Symbolic::Custom::Pattern::Export;

use 5.006001;
use strict;
use warnings;
use Carp qw/cluck confess/;

use Math::Symbolic qw/parse_from_string/;
use Math::Symbolic::Custom::Base;
BEGIN {*import = \&Math::Symbolic::Custom::Base::aggregate_import}

our $VERSION = '2.01';

=encoding utf8

=head1 NAME

Math::Symbolic::Custom::Pattern::Export - Export method to MS::Custom

=head1 SYNOPSIS

  use Math::Symbolic::Custom::Pattern;

  # later:
  my $pattern = $tree->to_pattern();
  # and even later:
  $another_tree->is_of_form($pattern);

=head1 DESCRIPTION

This module is an extension to the Math::Symbolic module. A basic
familiarity with that module is required.

Please have a look at the Math::Symbolic::Custom::Pattern module first.
This is an internal module only. It manages to add two new methods to all
Math::Symbolic objects: C and C. It uses the
Math::Symbolic::Custom mechanism for that.

=head2 EXPORT

In a way, this module exports the C and C methods to
Math::Symbolic::Base. Please look at L.

=cut

our $Aggregate_Export = [qw/is_of_form to_pattern/];

=head2 Math::Symbolic method is_of_form

This method can be called on any Math::Symbolic tree. First argument must be
a pattern. Returns true if the pattern matches the tree and false if not.
As with the C method on Math::Symbolic::Custom::Pattern objects,
the true value returned reflects the way the pattern matched. Please see
L for details.

The pattern may either be a Math::Symbolic::Custom::Pattern object (fastest)
or a Math::Symbolic tree representing a pattern (decent speed, since only the
pattern object needs to be constructed) or a string to be parsed as a
Math::Symbolic tree (very slow since the string has to be parsed).

For details on patterns, please refer to the documentation of
Math::Symbolic::Custom::Pattern.

This method always throws fatal errors since returning a boolean is used for
valid, non-error return values. Therefore, if you plan to pass unvalidated
objects or strings to be parsed, consider wrapping calls to this method in
C blocks. (Note that C is the safer brother of
the much despised C. See L.)

=cut

sub is_of_form {
	my $self = shift;
	my $proto = shift;

	# argument checking
	confess("is_of_form() must be called on Math::Symbolic tree.")
	  if not ref($self) =~ /^Math::Symbolic/;
	confess("is_of_form() requires a Math::Symbolic tree, a string to be parsed as a tree, or a Math::Symbolic::Custom::Pattern as first argument.")
	  if ref($proto) and not ref($proto) =~ /^Math::Symbolic/;

	# parse as tree
	if (not ref($proto)) {
		$proto = parse_from_string($proto);
		confess("First argument to is_of_form() was treated as a string. That string could not be parsed as a Math::Symbolic tree.") if not defined $proto;
	}

	if (
		not UNIVERSAL::isa($proto, 'Math::Symbolic::Custom::Pattern')
		and ref($proto) =~ /^Math::Symbolic/
	) {
		$proto = Math::Symbolic::Custom::Pattern->new($proto);
		confess("Could not generate pattern from Math::Symbolic tree.")
		  if not defined $proto;
	}

	return $proto->match($self);
}

=head2 Math::Symbolic method to_pattern

Generates a Math::Symbolic::Custom::Pattern object from the Math::Symbolic
tree C is called on. The pattern can be used with the
C method or like any other Math::Symbolic::Custom::Pattern
object. (See that package for details on patterns.)

=cut

sub to_pattern {
	my $self = shift;
	# argument checking
	confess("to_pattern() must be called on Math::Symbolic tree.")
	  if not ref($self) =~ /^Math::Symbolic/;
	return Math::Symbolic::Custom::Pattern->new($self);
}

1;
__END__