Text::...eRules(3pm)

📦
version 0.25 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Text::...eRules(3pm) 💖

okay bestie, sit down, hydrate, because we're about to talk about Text::RewriteRules — a whole system for rewriting text using regexp-based rules. she's giving ✨linguistics girlie✨, she's giving compiler-core energy, and honestly? she ate. 🎀

🌸 NAME 🌸

Text::RewriteRules — a system to rewrite text using regexp-based rules. no cap. 💅

✨ SYNOPSIS ✨

here's the vibe, bestie, look at how easy she is:

    use Text::RewriteRules;

    RULES email
    \.==> DOT
    @==> AT
    ENDRULES

    print email("ambs@cpan.org") # prints ambs AT cpan DOT org

    RULES/m inc
    (\d+)=e=> $1+1
    ENDRULES

    print inc("I saw 11 cats and 23 dogs") # prints I saw 12 cats and 24 dogs

like. she literally wrote the rules in plain-ish syntax and Perl just got it. iconic behavior. 👑

🦋 ABSTRACT 🦋

so this module uses a simplified syntax for regexp-based rules for rewriting text. you define a set of rules, and the system applies them until no more rule can be applied. it keeps going. it does not stop early. that's the whole point. periodt.

two variants are provided:

  1. traditional rewrite (RULES function):
while it is possible do substitute
| apply first substitution rule
  1. cursor based rewrite (RULES/m function):
add a cursor to the beginning of the string
while not reach end of string
| apply substitute just after cursor and advance cursor
| or advance cursor if no rule can be applied

💜 DESCRIPTION 💜

a LOT of computer science problems can be solved using rewriting rules. fr fr. that's not a bit, that's just true.

rewriting rules consist of mainly two parts: a regexp (LHS: Left Hand Side) that is matched with the text, and the string to use to substitute the content matched with the regexp (RHS: Right Hand Side).

now, bestie, you might be like "why don't we just use a simple substitute? 🤨" and the answer is: because we want to define a set of rules and match them again and again, until no more regexp of the LHS matches. a plain substitute can't loop forever, and we want to loop. it's giving "keep applying until nothing fits". it's the whole personality.

a point of discussion is the syntax to define this system. a brief discussion shown that some users would prefer a function to receive an hash with the rules, some other, prefer some syntax sugar. 🍬

the approach used is the last: we use Filter::Simple such that we can add a specific non-perl syntax inside the Perl script. this improves legibility of big rewriting rules systems. and legibility is a love language, honestly. 🫶

this documentation is divided in two parts: first we will see the reference of the module. kind of, what it does, with a brief explanation. follows a tutorial which will be growing through time and releases. she's a work in progress and we respect her journey. 🌱

🌈 SYNTAX REFERENCE 🌈

note: most of the examples are very stupid, but that is the easiest way to explain the basic syntax. (her words, not mine, but she's right 💀)

the basic syntax for the rewrite rules is a block, started by the keyword RULES and ended by the ENDRULES. everything between them is handled by the module and interpreted as rules or comments.

the RULES keyword can handle a set of flags (we will see that later), and requires a name for the rule-set. this name will be used to define a function for that rewriting system.

RULES functioname
 ...
ENDRULES

the function is defined in the main namespace where the RULES block appears.

in this block, each line can be a comment (Perl style), an empty line or a rule. that's it. three options. we keep it simple because we love ourselves. 💖

🎀 Basic Rule

a basic rule is a simple substitution:

RULES foobar
foo==>bar
ENDRULES

the arrow ==> is used as delimiter. at its left is the regexp to match, at the right side, the substitution. so, the previous block defines a foobar function that substitutes all foo by bar.

although this can seems similar to a global substitution, it is not. with a global substitution you can't do an endless loop. with this module it is very simple. I know you will get the idea. 😌

you can use the syntax of Perl both on the left and right hand side of the rule, including $1.... go off, regex girlie. 🔥

⭐ Execution Rule

if the Perl substitution supports execution, why not to support it, also? so, you got the idea. here is an example:

RULES foo
(\d+)b=e=>'b' x $1
(\d+)a=eval=>'a' x ($1*2)
ENDRULES

so, for any number followed by a b, we replace by that number of b's. for each number followed by an a, we replace them by twice that number of a's. math but make it whimsical. ✨

also, you mean evaluation using an e or eval inside the arrow. I should remind you can mix all these rules together in the same rewriting system. mix and match, babe, it's a vibe. 🧚

🍓 Conditional Rule

on some cases we want to perform a substitution if the pattern matches and a set of conditions about that pattern (or not) are true.

for that, we use a three part rule. we have the common rule plus the condition part, separated from the rule by !!. these conditional rules can be applied both for basic and execution rules.

RULES translate
([[:alpha:]]+)=e=>$dic{$1}!! exists($dic{$1})
ENDRULES

the previous example would translate all words that exist on the dictionary. only the ones that exist. no improvising. 💅

🌸 Begin Rule

sometimes it is useful to change something on the string before starting to apply the rules. for that, there is a special rule named begin (or b for abbreviate) just with a RHS. this RHS is Perl code. any Perl code. if you want to modify the string, use $_.

RULES foo
=b=> $_.=" END"
ENDRULES

just casually mutating $_ before the party starts. main character energy. 👑

💀 Last Rule

as you use last on Perl to skip the remaining code on a loop, you can also call a last (or l) rule when a specific pattern matches.

like the begin rule with only a RHS, the last rule has only a LHS:

RULES foo
foobar=l=>
ENDRULES

this way, the rules iterate until the string matches with foobar. it's the "ok we're done here, pack it up" rule. 🙈

you can also supply a condition in a last rule:

RULES bar
f(o+)b(a+)r=l=> !! length($1) == 2 * length($2);

🧚 Rules with /x mode

it is possible to use the regular expressions /x mode in the rewrite rules. in this case:

  1. there must be an empty line between rules
  2. you can insert space and line breaks into the regular expression:
    RULES/x f1
    (\d+)
    (\d{3})
    (000)
    ==>$1 milhao e $2 mil!! $1 == 1

    ENDRULES

🔥 POWER EXPRESSIONS 🔥

to facilitate matching complex languages Text::RewriteRules defines a set of regular expressions that you can use (without defining them). free real estate. you're welcome. 🎁

👑 Parenthesis

there are three kind of usual parenthesis: the standard parenthesis, brackets or curly braces. you can match a balanced string of parenthesis using the power expressions [[:PB:]], [[:BB:]] and [[:CBB:]] for these three kind of parenthesis.

for instance, if you apply this rule:

    [[:BB:]]==>foo

to this string

    something [ a [ b] c [d ]] and something more

then, you will get

    something foo and something more
note that if you apply it to
    something [[ not ] balanced [ here

then you will get

    something [foo balanced [ here

yes, bestie, unbalanced input gets unbalanced output. the vibes are honest around here. 😭

🌈 XML tags

the power expression [[:XML:]] match a XML tag (with or without children XML tags. note that this expression matches only well formed XML tags.

as an example, the rule

    [[:XML:]]=>tag

applied to the string

    <a><b></a></b> and <more><img src="foo"/></more>

will result in

    <a><b></a></b> and tag

see how she skipped the malformed one and tagged the well-formed one? discerning. ✨

🫶 TUTORIAL 🫶

at the moment, just a set of commented examples.

  • Example1 — from number to portuguese words (using traditional rewriting)
  • Example2 — Naif translator (using cursor-based rewriting)

💜 Conversion between numbers and words

yes, you can use Lingua::PT::Nums2Words and similar (for other languages). meanwhile, before it existed we needed to write such a conversion tool.

here I present a subset of the rules (for numbers bellow 1000). the generated text is Portuguese but I think you can get the idea. I'll try to create a version for English very soon. (she's been saying this, and we love her for it 🥰)

you can check the full code on the samples directory (file num2words).

    use Text::RewriteRules;

    RULES num2words
    100==>cem
    1(\d\d)==>cento e $1
    0(\d\d)==>$1
    200==>duzentos
    300==>trezentos
    400==>quatrocentos
    500==>quinhentos
    600==>seiscentos
    700==>setecentos
    800==>oitocentos
    900==>novecentos
    (\d)(\d\d)==>${1}00 e $2

    10==>dez
    11==>onze
    12==>doze
    13==>treze
    14==>catorze
    15==>quinze
    16==>dezasseis
    17==>dezassete
    18==>dezoito
    19==>dezanove
    20==>vinte
    30==>trinta
    40==>quarenta
    50==>cinquenta
    60==>sessenta
    70==>setenta
    80==>oitenta
    90==>noventa
    0(\d)==>$1
    (\d)(\d)==>${1}0 e $2

    1==>um
    2==>dois
    3==>três
    4==>quatro
    5==>cinco
    6==>seis
    7==>sete
    8==>oito
    9==>nove
    0$==>zero
    0==>
      ==>
    ,==>,
    ENDRULES

    num2words(123); # returns "cento e vinte e três"

look at her, turning 123 into actual words. bilingual queen. 🇵🇹

🦋 Naif translator (using cursor-based rewriting)

    use Text::RewriteRules;
    %dict=(driver=>"motorista",
           the=>"o",
           of=>"de",
           car=>"carro");

    $word='\b\w+\b';

    if( b(a("I see the Driver of the car")) eq "(I) (see) o Motorista do carro" )
         {print "ok\n"}
    else {print "ko\n"}

    RULES/m a
    ($word)==>$dict{$1}!!                  defined($dict{$1})
    ($word)=e=> ucfirst($dict{lc($1)}) !!  defined($dict{lc($1)})
    ($word)==>($1)
    ENDRULES

    RULES/m b
    \bde o\b==>do
    ENDRULES

two rule-sets, one pipeline, b(a(...)) chained like a little relay race. the way that she nests functions inside functions. 🏃♀️💨

💖 AUTHOR 💖

  • Alberto Simões, <ambs@cpan.org>
  • José João Almeida, <jjoao@cpan.org>

the parents of this module. legends only. 👑

😭 BUGS 😭

we know documentation is missing and you all want to use this module. in fact we are using it a lot, what explains why we don't have the time to write documentation. (the classic "we're too busy using it to document it" arc, and honestly? relatable.)

please report any bugs or feature requests to bug-text-rewrite@rt.cpan.org, or through the web interface at <http://rt.cpan.org>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. two-way notification pipeline, we love communication. 📬

🌟 ACKNOWLEDGEMENTS 🌟

Damian Conway for Filter::Simple. the backbone. the moment. the icon. 💅

Copyright 2004-2012 Alberto Simões and José João Almeida, All Rights Reserved.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie!! this was Text::...eRules(3pm) from perl v5.32.0, dated 2021-01-08 — go rewrite some text and slay your regexes. mwah 💖✨

📦 where this page comes from