package Filter::Interpolate;

use Filter::Simple;

FILTER {
	my($trynext, $parencount, @code)=(0, 0, split //);
	
	for(@code) {
		$trynext=1, next if $_ eq '$';
		if($trynext) {
			if($_ eq '(') {
				$parencount=1;
				$_='{\\scalar(';
			}
			
			$trynext=0;
		}
		elsif($parencount) {
			if($_ eq '(') {
				$parencount++;
			}
			elsif($_ eq ')') {
				$parencount--;
				$_=')}' unless $parencount;
			}
		}
	}
	
	$_=join '', @code;
	
	die "Filter::Interpolate: unbalanced parenthesis" if($parencount);
	
	($trynext, $parencount, @code)=(0, 0, split //);
	
	for(@code) {
		$trynext=1, next if $_ eq '@';
		if($trynext) {
			if($_ eq '(') {
				$parencount=1;
				$_='{[';
			}
			
			$trynext=0;
		}
		elsif($parencount) {
			if($_ eq '(') {
				$parencount++;
			}
			elsif($_ eq ')') {
				$parencount--;
				$_=']}' unless $parencount;
			}
		}
	}
	
	die "Filter::Interpolate: unbalanced parenthesis" if($parencount);
	
	$_=join '', @code;
};

=head1 NAME

Filter::Interpolate - Interpolated Function Calls

=head1 SYNOPSIS

	use Filter::Interpolate;
	
	sub Foo { '1' }
	sub Bar { 1..5 }
	sub Baz { @_ }
	sub Context { wantarray ? 'list' : 'scalar' }

	print "Foo: $(Foo)\n";				#prints Foo: 1
	print "Bar: @(Bar)\n";				#prints Bar: 1 2 3 4 5

	print "Baz: $(Baz('a', 'b'))";		#prints Baz: b
	print "Baz: @(Baz('a', 'b'))";		#prints Baz: a b

	print "$(Context)";					#prints scalar
	print "@(Context)";					#prints list

=head1 DESCRIPTION

Filter::Interpolate allows you to interpolate function calls into 
strings.  Because of Perl's contexts, Filter::Interpolate requires a 
sigil (a funny character--$ or @ in this case) to tell the function 
being called which context to use; thus, the syntax is 
C<$(>I<call>C<)> for scalar context or C<@(>I<call>C<)> for list 
context.  (This syntax is expected to be used for the same thing in 
Perl 6, too.)

Filter::Interpolate will work on both fuction and method calls.  It 
will work on parenthesized calls c<as long as the parenthesis are 
balanced>.  It even works outside quotes, where it can be used to
control context.  (This may be the only way to get a list context 
in some cases, for example.)

=head1 BUGS

=over 4

=item *
Filter::Interpolate doesn't really grok Perl that well, so it can't 
tell what you mean when you pass a parameter like C<')'>.  (It 
won't have any trouble if you put the other type of parenthesis in 
front of it, however; the best way to code around this problem is 
probably something like C<function_call(qw/( )/[1])>.)  It can also 
get confused when a parameter is '(', making it eat your entire 
program looking for a closing parenthesis.  I'm not sure how these 
problems could be fixed, but I'm looking into it.

=item *
As strange as it looks, the correct way to interpolate an 
expression like (Foo)[2] is @(Foo)[2].  This is a side effect of 
how the module works internally; I'll leave that as-is, since 
that's (probably) the way Perl 6 will be doing it anyway.

=item *
This code will look horrible if you try using B::Deparse on it.  
Y'see, when the module is used, your beautiful $(Foo) is butchered 
into ${\scalar(Foo)}.  Your also-beautiful @(Foo) fares only a 
little better, becoming @{[Foo]}.  (Yes, that's the at-brace-bracket 
hack.)  Just don't try it--you won't be terribly happy with the 
output's appearance.

=back

=head1 AUTHOR

Copyright (C) 2001 Brent Dax.  All rights reserved.

This module is free software. It may be used, redistributed and/or 
modified under the terms of the Perl Artistic License (see 
http://www.perl.com/perl/misc/Artistic.html).

=cut