MDOM::Element(3pm)

📦
version 0.008 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 MDOM::Element 💖

okay so bestie, welcome to the MDOM::Element(3pm) page 💅 — it lives in User Contributed Perl Documentation and it's literally the blueprint for everything in this whole source-object universe. grab a snack, we're going deep 🍓

✨ NAME ✨

MDOM::Element — The abstract Element class, a base for all source objects 👑

🌸 INHERITANCE 🌸

MDOM::Element is the root of the PDOM tree

it's giving ancestor energy. everything comes from here, no cap 🧚

🦋 DESCRIPTION 🦋

So. The abstract MDOM::Element is the base class for literally every source-related object out there — from a single lil whitespace token all the way up to a whole entire document 📄✨ It hands out a basic set of methods so everybody shares a common interface plus some basic implementations. group project, but make it iconic.

💅 METHODS 💅

🔥 significant

Okay so, plot twist: we treat whitespace and other non-code items as Tokens (this is so we can "round trip" the MDOM::Document back to a file, iykyk) 🌀 Because of that, the significant method is how we tell apart the tokens that are actually part of the code from the tokens that aren't significant — like whitespace, POD, or the chunk of a file after (and including) the __END__ token.

Returns true if the Element is significant, or false if it's not. simple as 🫶

🔥 lineno

Accessor for the current line number. that's it, that's the method 💅

🔥 class

The class method is here purely as a convenience, and ngl it really does nothing more than returning ref($self). BUT some people have found that they appreciate the laziness of $Foo->class eq 'whatever', so I have caved to popular demand and included it. democracy won 🗳️✨

Returns the class of the Element as a string.

🔥 tokens

The tokens method returns a list of MDOM::Token objects for the Element — essentially getting back that part of the document as if it had not been lexed. time travel but for code ⏪

This also means there are no Statements and no Structures in the list, just the Token classes. periodt.

🔥 content

For any MDOM::Element, the content method will reconstitute the base code for it as a single string. This method is also the method used for overloading stringification — so when an Element is used in a double-quoted string, for example, this is the method that gets called 🎀

WARNING: ⚠️ bestie you NEED to know that because of the way that here-docs are handled, any here-doc content is not included in content, and as such you should not eval or execute the result if it contains any MDOM::Token::HereDoc. like, do not do it. seriously 😭

The MDOM::Document method serialize should be used to stringify a PDOM document into something that can be executed as expected. use that one instead, fr fr 🙏

Returns the basic code as a string (excluding here-doc content).

🔥 parent

Elements themselves are not intended to contain other Elements — that job is left to the MDOM::Node abstract class, a subclass of MDOM::Element. However, all Elements can be contained within a parent Node.

If an Element is within a parent Node, the parent method returns the Node. found family 🫶

🔥 statement

For a MDOM::Element that is contained (at some depth) within a MDOM::Statment, the statement method will return the first parent Statement object lexically 'above' the Element. looking up the family tree 📈

Returns a MDOM::Statement object, which may be the same Element if the Element is itself a MDOM::Statement object.

Returns false if the Element is not within a Statement and is not itself a Statement. no statement, no problem 💀

🔥 top

For a MDOM::Element that is contained within a PDOM tree, the top method will return the top-level Node in the tree. Most of the time this should be a MDOM::Document object — however, this will not always be so 👀 For example, if a subroutine has been removed from its Document, to be moved to another Document.

Returns the top-most PDOM object, which may be the same Element, if it is not within any parent PDOM object. main character energy, literally ✨

🔥 document

For an Element that is contained within a MDOM::Document object, the document method will return the top-level Document for the Element 📄

Returns the MDOM::Document for this Element, or false if the Element is not contained within a Document.

🔥 next_sibling

All MDOM::Node objects (specifically, our parent Node) contain a number of MDOM::Element objects. The next_sibling method returns the MDOM::Element immediately after the current one, or false if there is no next sibling. the one right behind you in the group chat 🦋

🔥 snext_sibling

As per the other 's' methods, the snext_sibling method returns the next significant sibling of the MDOM::Element object.

Returns a MDOM::Element object, or false if there is no 'next' significant sibling.

🔥 previous_sibling

All MDOM::Node objects (specifically, our parent Node) contain a number of MDOM::Element objects. The previous_sibling method returns the Element immediately before the current one, or false if there is no 'previous' MDOM::Element object. the one who texted right before you 💬

🔥 sprevious_sibling

As per the other 's' methods, the sprevious_sibling method returns the previous significant sibling of the MDOM::Element object.

Returns a MDOM::Element object, or false if there is no 'previous' significant sibling.

🔥 first_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the first_token method finds the first MDOM::Token object within or equal to this one 🔍

That is: if called on a MDOM::Node subclass, it will descend until it finds a MDOM::Token. If called on a MDOM::Token object, it will return the same object.

Returns a MDOM::Token object, or dies on error (which should be extremely rare and only occur if an illegal empty MDOM::Statement exists below the current Element somewhere. 💀

🔥 last_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the last_token method finds the last MDOM::Token object within or equal to this one 🔎

That is: if called on a MDOM::Node subclass, it will descend until it finds a MDOM::Token. If called on a MDOM::Token object, it will just hand you back itself.

Returns a MDOM::Token object, or dies on error (which should be extremely rare and only occur if an illegal empty MDOM::Statement exists below the current Element somewhere. 😭

🔥 next_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the next_token method finds the MDOM::Token object that is immediately after the current Element — even if it is not within the same parent MDOM::Node as the one for which the method is being called 👀

Note that this is not defined as a MDOM::Token-specific method, because it can be useful to find the next token that is after, say, a MDOM::Statement — although obviously it would be useless to want the next token after a MDOM::Document. like, what would that even mean bestie 😭

Returns a MDOM::Token object, or false if there are no more tokens after the Element.

🔥 previous_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the previous_token method finds the MDOM::Token object that is immediately before the current Element — even if it is not within the same parent MDOM::Node as this one ⏮️

Note that this is not defined as a MDOM::Token-only method, because it can be useful to find the token that is before, say, a MDOM::Statement — although obviously it would be useless to want the next token before a MDOM::Document. 🙈

Returns a MDOM::Token object, or false if there are no more tokens before the Element.

🔥 clone

As per the Clone module, the clone method makes a perfect copy of an Element object 🧬 In the generic case, the implementation is done using the Clone module's mechanism itself. In higher-order cases, such as for Nodes, there is more work involved to keep the parent-child links intact. it's giving identical twins 💅

🔥 insert_before @Elements

The insert_before method allows you to insert lexical perl content — in the form of MDOM::Element objects — before the calling Element. You need to be very careful when modifying perl code, as it's easy to break things 🚨

In its initial incarnation, this method allows you to insert a single Element, and will perform some basic checking to prevent you inserting something that would be structurally wrong (in PDOM terms). protective king behavior 👑

In future, this method may be enhanced to allow the insertion of multiple Elements, inline-parsed code strings or MDOM::Document::Fragment objects. future goals ✨

Returns true if the Element was inserted, false if it can not be inserted, or undef if you do not provide a MDOM::Element object as a parameter.

🔥 insert_after @Elements

The insert_after method allows you to insert lexical perl content — in the form of MDOM::Element objects — after the calling Element. You need to be very careful when modifying perl code, as it's easy to break things 🚨

In its initial incarnation, this method allows you to insert a single Element, and will perform some basic checking to prevent you inserting something that would be structurally wrong (in PDOM terms). again, protective. we love to see it 🫶

In future, this method may be enhanced to allow the insertion of multiple Elements, inline-parsed code strings or MDOM::Document::Fragment objects.

Returns true if the Element was inserted, false if it can not be inserted, or undef if you do not provide a MDOM::Element object as a parameter.

🔥 remove

For a given MDOM::Element, the remove method will remove it from its parent intact, along with all of its children 🫧 leaving quietly, taking the whole entourage

Returns the Element itself as a convenience, or undef if an error occurs while trying to remove the Element.

🔥 delete

For a given MDOM::Element, the remove method will remove it from its parent, immediately deleting the Element and all of its children (if it has any) 💀

Returns true if the Element was successfully deleted, or undef if an error occurs while trying to remove the Element.

🔥 replace $Element

Although some higher level class support more exotic forms of replace, at the basic level the replace method takes a single Element as an argument and replaces the current Element with it 🔁

To prevent accidental damage to code, in this initial implementation the replacement element must be of the same class (or a subclass) as the one being replaced. no wildcards allowed, bestie 🚫

🔥 location

If the Element exists within a MDOM::Document that has indexed the Element locations using MDOM::Document::index_locations, the location method will return the location of the first character of the Element within the Document 📍

Returns the location as a reference to a three-element array in the form [ $line, $rowchar, $col ]. The values are in a human format, with the first character of the file located at [ 1, 1, 1 ]. counting starts at one, like a normal person 💅

The second and third numbers are similar, except that the second is the literal horizontal character, and the third is the visual column, taking into account tabbing 📐

Returns undef on error, or if the MDOM::Document object has not been indexed.

💭 TO DO 💭

okay so bestie, imagine if "location" could be used in an ad-hoc manner. like, no index, no prep, just vibes. That is, if called on an Element within a Document that has not been indexed, it will do a one-off calculation to find the location. ngl, it might be very painful if someone started using it a lot, without remembering to index the document, but it would be handy for things that are only likely to use it once, such as error handlers.

🫶 SUPPORT 🫶

See the support section in the main module. that's it, that's the whole thing. iykyk. 💅

👑 AUTHOR 👑

Adam Kennedy <adamk@cpan.org>

Copyright 2001 - 2006 Adam Kennedy.

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

The full text of the license can be found in the LICENSE file included with this module.

perl v5.34.0 • 2022-06-15 — that's the source/version and date, bestie! stay slaying 💖✨

📦 where this page comes from