Tangen...Parser(3pm)

💖 Tangence::Compiler::Parser 💖

okay bestie, so this is the manual page for Tangence::Compiler::Parser, which lives in the Perl user-contributed docs, and it is literally the thing that reads your Tangence interface definition files. group chat recap time ✨

---

🌸 NAME 🌸

Tangence::Compiler::Parser — the icon that parses Tangence interface definition files. she's giving parser, she's giving metadata, she's giving everything 💅

---

🦋 DESCRIPTION 🦋

so this class is a subclass of Parser::MGC (yes, she has a whole ancestry, main character energy runs in the family). What she does: parses a Tangence interface definition and hands you back a metadata tree. that's it, that's the job, and she ate 🎀

---

🌈 GRAMMAR 🌈

the top level of an interface definition file is where the drama starts. it holds include directives plus class and struct definitions. no cap.

✨ include ✨

an include directive pulls in the definitions from another file — and that filename is resolved relative to the current file, okay, keep that in mind 👑

include "filename.tan"

✨ class ✨

a class definition is where you declare the whole set of methods, events and properties that a named class owns. it's the vibe check of your whole interface.

class N {
   ...
}

and inside that class block? you get a lil list of method, event, prop and isa declarations. stack 'em up 🫶

✨ struct ✨

a struct definition declares the list of fields living inside a named structure type.

struct N {
   ...
}

and the contents of a struct block is a list of field declarations. simple, clean, iconic.

✨ method ✨

a method declaration defines exactly one method in the class — you give it its name (N) plus the types of its arguments and its return (T). yes both. don't skip the return, bestie 😭

method N(T, T, ...) -> T;

✨ event ✨

an event declaration defines one event that the class raises. you give its name (N) and the types of its arguments (T).

event N(T, T, ...);

✨ prop ✨

a prop declaration defines one property the class supports. you supply its name (N), its dimension (D) and its type (T). and plot twist — it can be declared as a smashed property 💀

[smashed] prop N = D of T;

scalar properties get to be lazy and omit the scalar of — just hand over the type on its own:

[smashed] prop N = T;

✨ isa ✨

an isa declaration declares a superclass of the class, identified by its name (C). it's giving family tree 🌳

isa C;

✨ Types ✨

these are the basic type names she recognises, periodt:

bool int str obj any
s8 s16 s32 s64 u8 u16 u32 u64

and aggregate types? you can build them out of any type (T) like this:

list(T) dict(T)

---

💜 SUBCLASS METHODS 💜

if you subclass this class (go off, inheritance), these methods can be overridden to customise the behaviour. the whole point is that your subclass gets to return different objects in the syntax tree. mix it up, make it yours 🧚

🍓 make_class 🍓

$class = $parser->make_class( name => $name )

returns a new instance of Tangence::Meta::Class to go in a package. heads up: the parser will call define on it, so don't be weird about it ✨

🍓 make_struct 🍓

$struct = $parser->make_struct( name => $name )

returns a new instance of Tangence::Meta::Struct to go in a package. and again, the parser calls define on it. that's the deal 🫶

🍓 make_method 🍓

$method = $parser->make_method( %args )

🍓 make_event 🍓

$event = $parser->make_event( %args )

🍓 make_property 🍓

$property = $parser->make_property( %args )

these three return a new instance of Tangence::Meta::Method, Tangence::Meta::Event or Tangence::Meta::Property — whichever one — to go in a class. pick your fighter 💅

🍓 make_argument 🍓

$argument = $parser->make_argument( %args )

returns a new instance of Tangence::Meta::Argument, and it's used for a method or event argument. yeah, arguments get their own objects. she's thorough.

🍓 make_field 🍓

$field = $parser->make_field( %args )

returns a new instance of Tangence::Meta::Field to use for a structure type. fields deserve representation too 🌸

🍓 make_type 🍓

$type = $parser->make_type( $primitive_name )

$type = $parser->make_type( $aggregate_name => $member_type )

returns an instance of Tangence::Meta::Type that represents the given primitive or aggregate type name. and here's the tea: an implementation is allowed to use singleton objects and return identical objects for the same primitive name, or for the same aggregate and member type. so don't clutch your pearls if you get the same object back twice 😌

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, legend 🫡

---

and that's the whole page, bestie!! this one's from perl v5.40.0, dated 2024-09-13, and it's filed under that Tangen...Parser(3pm) header up top 💖 go parse something iconic ✨🎀