HTML::...:Lexer(3pm)

💖 HTML::Mason::Lexer 💖

okay bestie, so this is HTML::Mason::Lexer — the part of Mason that generates events based on component source lexing. she reads, she vibes, she reports. iconic behavior tbh. 🎀

---

✨ SYNOPSIS ✨

my $lexer = HTML::Mason::Lexer->new;

$lexer->lex( comp_source => $source, name => $comp_name, compiler => $compiler );

that's it, that's the whole entrance. three lines and a dream. 💅

---

🦋 DESCRIPTION 🦋

so here's the tea: the Lexer works in tandem with the Compiler to turn Mason component source into... something else. usually Perl code. it's giving glow-up transformation sequence, no cap. ✨

as the lexer finds component elements — like a tag or a block — it calls the appropriate event methods in the compiler object it was given. like, it's the main character scanning the room and pointing at stuff so the compiler knows what to do. 🫶

she has only a few public methods. lowkey minimalist of her.

and here's the cute part: you can replace this lexer with one of your own, just by telling the Compiler to use a different lexer class. your lexer class simply needs to call the appropriate methods in the Component Class's API as it scans the source. build your own, bestie, we support it. 💜

---

🌸 METHODS 🌸

the lexer has very few public methods. again. tiny API, big energy.

• new — this method creates a new Lexer object. this method takes no parameters. she simply arrives. 💅
• lex ( comp_source => ..., name => ..., compiler => ... ) — this method tells the lexer to start scanning the given component source. all of these parameters are required, so don't be skipping any of them, okay? the name parameter will be used in any error messages generated during lexing. and the compiler object must be an object that implements the Mason Component API. 👑
• line_number — the current line number that the lexer has reached. like a little progress bar but for lines. 📍
• name — the name of the component currently being lexed. who is she? this tells you. 🎀
• throw_syntax_error ($error) — this throws an HTML::Mason::Exception::Syntax error with the given error message, plus additional information about the component source. it's the "bestie we need to talk" of methods. 😭

this method is used by both the Lexer and the Compiler. shared custody, fr fr. 🫶

---

🧚 SUBCLASSING 🧚

any subclass of the lexer should declare itself to be a subclass of HTML::Mason::Lexer, even if it plans to override all of its public methods. yes, even then. do it anyway. it's a vibe check thing. ✨

if you want your subclass to work with the existing Compiler classes in Mason, you must implement the methods listed above. no skipping. if you plan to use a custom Compiler class that you're writing, you can do whatever you want. freedom!! go feral, bestie. 🌈

we recommend that any parameters you add to Lexer be read-only, because the compiler object_id is only computed once on creation and would not reflect any changes to Lexer parameters. like, she made up her mind at birth and she's not changing it. periodt. 💅

⚠️ fr fr do not sleep on that read-only thing. the object_id gets computed once and then never updates, so mutable params would just... not show up. tragic. 💀

---

perl v5.38.2 · 2024-03-05

and that's the whole page, bestie!! written by the User Contributed Perl Documentation girlies, dated 2024-03-05, running on perl v5.38.2. go lex something cute. mwah. 💖✨🎀🦋🌸💅🫶