Devel:...Parser(3pm)

📦
version 0.021 · 5 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ Devel:...Parser(3pm) ✨

User Contributed Perl Documentation · Devel:...Parser(3pm)

okay bestie, buckle up, this one's a whole journey 💅

💖 NAME 💖

Devel::Declare::Parser — Higher level interface to Devel-Declare

🦋 DESCRIPTION 🦋

So like. Devel-Declare-Parser is a higher-level API that sits right on top of Devel::Declare. It's the glow-up layer, the little lift, the extra sparkle ✨

And who uses it? Devel::Declare::Exporter, that's who — it leans on Parser to make exporting Devel::Declare magic wayyy simpler than it has any right to be.

Here's the tea though: writing your own custom parsers is usually not that deep. Like, most of the time you just subclass this module, override a couple of methods, and boom — you're done. Iconic behaviour, honestly. 👑

🌈 DOCUMENTATION 🌈

  • Devel::Declare::Interface — this is the primary interface for anyone who wants to use Devel-Declare-Parser magic and does not want to mess with Exporter-Declare. It's giving "just give me the powers, thanks" 🫶
  • Devel::Declare::Parser — and this doc right here? This is the API reference for Devel::Declare::Parser itself. Super handy when you're writing or modifying a custom parser, iykyk 📖

⭐ SYNOPSIS ⭐

package Devel::Declare::Parser::MyParser;
use strict;
use warnings;

use base 'Devel::Declare::Parser';
use Devel::Declare::Interface;

# Create an accessor (See INTERNALS WARNING below)
__PACKAGE__->add_accessor( 'my_accessor' );

# Register the parser for use.
Devel::Declare::Interface::register_parser( 'myparser' );

# Override the rewrite() method to take the parsed bits (parts) and put the
# ones you want into new_parts.
sub rewrite {
    my $self = shift;

    my $parts = $self->parts;

    $new_parts = $self->process_parts( $parts );

    $self->new_parts( $new_parts );
    1;
}

1;
psst — see that (See INTERNALS WARNING below) comment in there? It's pointing at a section that lives further down in this doc, so don't go looking for it in this part, bestie 🙈

👑 OVERVIEW 👑

A quick lil tour of how a parser actually gets used, because the vibe is: know the flow, slay the flow 💫

🎀 WORKFLOW 🎀

  1. Parser is constructed — Name, Declarator, and Offset are provided by Devel::Declare.
  2. The process() method is called — process calls all of the following in sequence. And here's the catch: if any of them returns false, process() will return. No further steps, it just dips. 🚪💨
    • pre_parse() — check if we even want to process the line at all. Vibe check first, always.
    • parse() — turn the line into 'parts' (more on that below).
    • post_parse() — a hook. Currently does nothing. It's just standing there, being a hook. 💀
    • rewrite() — a hook, and it currently takes all the arguments between the declarator and the codeblock/semicolon (which have been turned into 'parts' structures in the parts() attribute) and puts them into the new_parts() attribute.
this is usually the method you want to override. Like, if you only read one line of this whole doc, it's this one, fr fr 🔥
  • write_line() — opens, fills in, and closes the line as a string, then rewrites the actual line using Devel::Declare. Very "assembly line but make it cute" 🏭✨
  • edit_line() — another hook. Also currently does nothing. Two hooks, zero jobs. 😭

🧚 "PARTS" 🧚

'Parts' are data structures created by the parse() method. Every argument on the line (space separated) up until an opening curly brace ({) or a semicolon (;) gets turned into a part. Here's what you should expect to see:

A part will either be a plain string, or an arrayref containing a string plus the quote character that was used to define the string. So: "String" or [ "String", '"' ]. Variables and operators (except for the ones that contain only string characters) are typically the only parts left hanging around in plain-string form.

And if you want an easy way to get what you need out of a 'part' data structure? Go look at the format_parts() method. It's there for you, bestie 🫶

🌸 Bareword or Package Name 🌸

A bareword name is anything that starts with [a-zA-z] and contains only alphanumerics plus underscore. It's also not quoted. Examples include my_name, something5, etc.

The structure will be an arrayref: first element is the string form of the bareword name, second element is undef.

Examples:

# my_keyword My::Package;
$part = [
    'My::Package',
    undef,
];

# my_keyword some_name;
$part = [
    "some_name",
    undef,
];

🍓 Quoted or Enclosed Element 🍓

A quoted or enclosed element covers strings quoted with single or double quotes, plus text contained within opening and closing brackets, braces or parens — and heads up, that's excluding the curly brace '{'.

Example structures:

# my_keyword "double quoted string";
$part = [
    'double quoted string',
    '"',
];

# my_keyword 'single quoted string';
$part = [
    'double quoted string',
    '"',
];

# my_keyword ... ( a => 'b', c => 'd' );
$part = [
    " a => 'b', c => 'd' ",
    "(",
];

💜 Variable or Operator 💜

Anything starting with a non-alphanumeric, non-quoting character gets placed as-is (not interpolated) into a string. This catches most variables and most operators — the exception being alpha-numeric operators like 'eq', 'gt', 'cmp', etc.

And the author's note on that: eventually there's a plan to add logic to catch all operators, but it looks like they'll have to hard-code them. So, you know. Future plans. 🛠️

# my_keyword $variable
$part = '$variable';

# my_keyword <=>
$part = '<=>';

🌟 EVENTUAL OUTPUT 🌟

Parser is designed so that it will transform any and all uses of your keyword into proper function calls. That's the whole point. That's the assignment. 💅

So this:

function x { ... }

Will become this:

function( 'x', sub { ... });
important note: Parser does not read in the entire codeblock. Instead it injects a statement into the start of the block that uses a callback to attach the ');' to the end of the statement. That's per the documentation of Devel::Declare. And reading in the entire sub is not a desirable scenario — so like, don't do that, bestie 😭🚫

🔮 DEVEL-DECLARE-PARSER API 🔮

🚨 INTERNALS WARNING 🚨

okay bestie, sit down for this one because it matters 💅

  • Parser objects are blessed arrays, not hashrefs. ikr. arrays. not hashes. this is not a drill.
  • If you want to create a new accessor, use the add_accessor() class method. It will take care of assigning an unused array element to the attribute, and it will create a read/write accessor sub for you. so you literally don't have to do it yourself. king behavior fr fr.
__PACKAGE__->add_accessor( 'my_accessor' );
  • There are many public and private methods on the parser base class. Only the public methods are fully documented. Be sure to refer often to the list of private methods at the end of this document — accidently overriding a private method could have devastating consequences 😭 like not even joking, that's the actual wording, it's that serious.

📦 CLASS METHODS 📦

  • $class->new( $name, $declarator, $offset ) — The constructor. And the docs literally scream "DO NOT OVERRIDE THIS!" at you, so like. don't. 🙈
  • $class->DEBUG($bool) — Turn debugging on/off. This will output the line after it has been modified, as well as some context information. it's giving ✨insight✨
NOTE: This has a global effect — all parsers will start debugging. every single one. so use it with intention, bestie.

🧰 UTILITY METHODS 🧰

  • bail( @messages ) — Like croak, dies providing you context information. Since any death occurs inside the parser, carp provides useless information. so bail is the glow-up version 💀
  • diag( @message ) — Like carp, warns providing you context information. Since the warn occurs inside the parser carp provides useless information. same energy, but for warnings.
  • end_quote($start_char) — Find the end-character for the provided starting quote character. As in '{' returns '}' and '(' returns ')'. If there is no counter-part, the start character is returned: "'" returns "'". matched sets only, no cap.
  • filename() — Filename the rewrite is occurring against.
  • linenum() — Linenum the rewrite is occurring on.
  • format_part() — Returns the stringified form of a part datastructure. For variables and operators that is just the item itself as a string. For barewords or package names it is the item itself with single quotes wrapped around it. For quoted items it is the string wrapped in its proper quoting characters. If a second parameter is provided (and true) no single quotes will be added to barewords. it's the little formatting fairy of your dreams 🧚

🔑 ACCESSORS 🔑

These are the read/write accessors used by Parser. Not all of these act on an array element — some will directly alter the current line. messy? maybe. iconic? absolutely.

  • line() — This will retrieve the current line from Devel-Declare. If given a value, that value will be set as the current line using Devel-Declare.
  • name() — Name of the declarator as provided via the parser.
  • declarator() — Name of the declarator as provided via the Devel-Declare.
  • original_offset() — Offset on the line when the parsing was started.
  • offset() — Current line offset.
  • parts() — Arrayref of parts (may be undef)
  • new_parts() — Arrayref of new parts (may be undef)
  • end_char() — Will be set to the character just after the completely parsed line (usually '{' or ';')
  • prototype() — Used internally for prototype tracking.
  • contained() — True if the parser determined this was a contained call. This means your keyword was followed by an opening paren, and the statement ended with a closing paren and semicolon. By default Parser will not modify such lines.

🦋 OVERRIDABLE METHODS 🦋

These are methods you can, should, or may override in your baseclass. your moment to shine, bestie.

  • quote_chars() — Specify the starting characters for quoted strings. (returns a list)
  • end_chars() — Characters to recognise as end of statement characters (';' and '{') (returns a list)
  • inject() — Code to inject into functions enhanced by this parser.
  • pre_parse() — Check if we want to process the line at all.
  • parse() — Turn the line into 'parts'.
  • post_parse() — Hook, currently does nothing.
  • rewrite() — Hook, currently takes all the arguments between the declarator and the codeblock/semicolon (which have been turned into 'parts' structures in the parts() attribute) and puts them into the new_parts() attribute.

This is usually the method you want to override. 👑 yes, THIS one. the main character method.

  • write_line() — Opens, fills in, and closes the line as a string, then rewrites the actual line using Devel::Declare.
  • edit_line() — Hook, currently does nothing.
  • open_line() — Usually returns '('. This is how to start a line following your keyword
  • close_line() — End the line, this means either re-inserting the opening '{' on the codeblock, along with any injections, or returning ');'

📍 POSITION TRACKING 📍

  • advance( $num_chars ) — Advances the offset by $num_chars.
  • skip_declarator() — Skips the declarator at the start of the line.
  • skipspace() — Advances the offset past any whitespace.

🔍 LINE EXAMINATION (NON-MODIFYING) 🔍

These are used by pre_parse() to examine the line prior to any modification. looking, not touching 💅

  • is_contained() — True if the line is of the format:
keyword( ... );
  • is_arrow_contained() — True if the line is of the format:
keyword word_or_string => ( ... );
  • is_defenition() — True if the line matches the regex m/sub[\s\n]+$name/sm

🧩 PART EXAMINATION 🧩

These are methods that let you investigate the parts already parsed and placed in the parts() attribute.

  • has_non_string_or_quote_parts() — Returns a list of parts that are not strings, quotes, or barewords.
  • has_string_or_quote_parts() — Returns a list of parts that are strings, quotes, or barewords.
  • has_keyword( $word ) — Check for a keyword in the parts
  • has_comma()
  • has_fat_comma()

✂️ LINE EXAMINATION (MODIFYING) ✂️

This examines the line returning part structures and removing elements from the line each time they are called. it's giving chaotic and we love that for it.

  • strip_item()
  • strip_length()
  • strip_remaining_items()

👀 LOOKING AHEAD 👀

These methods help the parser determine what comes next in a line. In most cases these are non-modifying. manifesting the future of your line ✨

  • peek_is_block()
  • peek_is_end()
  • peek_is_other()
  • peek_is_quote()
  • peek_is_word()
  • peek_item()
  • peek_item_type()
  • peek_num_chars()
  • peek_other()
  • peek_quote()
  • peek_remaining()
  • peek_word()

🙈 PRIVATE METHODS 🙈

Do not use these, and definitely do not override them in a subclass. like fr fr do NOT.

  • _block_end_injection()
  • _debug()
  • _edit_block_end()
  • _item_via_()
  • _linestr_offset_from_dd()
  • _move_via_()
  • _peek_is_package()
  • _peek_is_word()
  • _quoted_from_dd()
  • _scope_end()
  • _stash()
  • _unstash()

🌈 FENNEC PROJECT 🌈

This module is part of the Fennec project. See Fennec for more details. Fennec is a project to develop an extendable and powerful testing framework. Together the tools that make up the Fennec framework provide a potent testing environment.

The tools provided by Fennec are also useful on their own. Sometimes a tool created for Fennec is useful outside the greator framework. Such tools are turned into their own projects. This is one such project. 🦋

  • Fennec - The core framework — The primary Fennec project that ties them all together.

💖 AUTHORS 💖

Chad Granum exodist7@gmail.com

Copyright (C) 2010 Chad Granum

Devel-Declare-Parser is free software; Standard perl licence.

Devel-Declare-Parser is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.

okay that's the whole thing, bestie 🫶 you made it to the end, slay. this page is from perl v5.36.0 and it's dated 2023-10-26 — so if you're reading this, hi from the archive, hope your parser is behaving 💜
📦 where this page comes from