NAME
PerlX::QuoteOperator - Create new quote-like operators in Perl
VERSION
Version 0.05
SYNOPSIS
Create a quote-like operator which convert text to uppercase:
use PerlX::QuoteOperator quc => {
-emulate => 'q',
-with => sub ($) { uc $_[0] },
};
say quc/do i have to $hout/;
# => DO I HAVE TO $HOUT
DESCRIPTION
QUOTE-LIKE OPERATORS
Perl comes with some very handy Quote-Like Operators http://perldoc.perl.org/perlop.html#Quote-Like-Operators :)
But what it doesn't come with is some easy method to create your own quote-like operators :(
This is where PerlX::QuoteOperator comes in. Using the fiendish Devel::Declare under its hood it "tricks", sorry "helps!" the perl parser to provide new first class quote-like operators.
HOW DOES IT DO IT?
The subterfuge doesn't go that deep. If we take a look at the SYNOPSIS example:
say quc/do i have to $hout/;
Then all PerlX::QuoteOperator actually does is convert this to the following before perl compiles it:
say quc q/do i have to $hout/;
Where 'quc' is a defined sub expecting one argument (ie, sub ($) { uc $_[0] } ).
This approach allows PerlX::QuoteOperator to perform the very basic keyhole surgery on the code, ie. just put in the emulated quote-like operator between keyword & argument.
However this approach does have caveats especially when qw// is being used!. See CAVEATS. There is an alternative parser when can be invoked, see -parser Export parameter.
WHY?
Bit like climbing Mount Everest... because we can! ;-)
Is really having something like:
say quc/do i have to $hout/;
so much better than:
say uc 'do i have to $hout';
or more apt this:
say uc('do i have to $hout');
Probably not... at least in the example shown. But things like this are certainly eye catching:
use PerlX::QuoteOperator::URL 'qh';
my $content = qh( http://transfixedbutnotdead.com ); # does HTTP request
NOTICE - As for version 0.05 (23rd Feb 2015), PerlX::QuoteOperator::URL was moved to its own distribution.
And this:
use PerlX::QuoteOperator qwHash => {
-emulate => 'qw',
-with => sub (@) { my $n; map { $_ => ++$n } @_ },
};
my %months = qwHash/Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec/;
Certainly give the code aesthetic a good pause for thought.
EXPORT
By default nothing is exported:
use PerlX::QuoteOperator; # => imports nothing
Quote operator is imported when passed a name and options like so:
use PerlX::QuoteOperator quote_operator_name_i_want_to_use => { }
A hashref is used to pass the options.
PARAMETERS
-emulate
Which Perl quote-like operator required to emulate. q, qq & qw have all been tested.
Default: emulates qq
-with
Your quote-like operator code reference / anon subroutine goes here.
Remember to use subroutine prototype (if not using -parser option):
-with => sub ($) { uc $_[0] },
This is a mandatory parameter.
-parser
If set then alternative parser kicks in. This parser currenly works on single line of code only and must open/close quote with (), {}, [], <> or must have same delimeter for beginning and end of quote:
-parser => 1
When invoked this parser will take this:
quc/do i have to $hout/;
And by finding the end of the quote will then encapulate it like so:
quc(q/do i have to $hout/);
Default: Not using alternative parsing.
-debug
If set then prints (warn) the transmogrified line so that you can see what PerlX::QuoteOperator has done!
-debug => 1
Default: No debug.
FUNCTIONS
import
Module import sub.
parser
When keyword (defined quote operator) is triggered then this sub uses Devel::Declare to provide necessary keyhole surgery/butchery on the code to make it valid Perl code (think Macro here!).
_closing_delim
Internal subroutine used in -parser option.
CAVEATS
Performing a method call or dereference using -> like below will not work:
use PerlX::QuoteOperator qurl => {
-emulate => 'q',
-with => sub ($) { require URI; URI->new($_[0]) },
};
qurl(http://www.google.com/)->authority; # Throws an error
Because the parsed qurl line becomes this...
qurl q(http://www.google.com/)->authority;
... so throwing an error trying to call authority
on a string. See "HOW DOES IT DO IT" for more info.
A workaround is to use the alternative parser and the line would now be parsed like this:
qurl(q(http://www.google.com/))->authority;
See -parser option for more information.
Also see examples/qw.pl for some more issues with creating qw based quote-like operators. NB. The alternative parser will get around some of these problems but then (potentially) introduces a few new ones! (see TODO)
Recommendation: Stick with Perl parser and all will be fine!
SEE ALSO
CONTRIBUTORS
Toby Inkster (https://metacpan.org/author/TOBYINK) for Text::Balanced patch to the alternative parser at 0.04
AUTHOR
Barry Walsh, <draegtun at cpan.org>
BUGS
Please report any bugs or feature requests to bug-perlx-quoteoperator at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PerlX-QuoteOperator. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc PerlX::QuoteOperator
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=PerlX-QuoteOperator
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
From here to oblivion!: http://transfixedbutnotdead.com/2009/12/16/url-develdeclare-and-no-strings-attached/
And a round of drinks for the mad genius of MST for creating Devel::Declare in the first place!
DISCLAIMER
This is (near) beta software. I'll strive to make it better each and every day!
However I accept no liability whatsoever should this software do what you expected ;-)
COPYRIGHT & LICENSE
Copyright 2009-2015 Barry Walsh (Draegtun Systems Ltd | http://www.draegtun.com), all rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.