Parse:...natures(3pm)

✨ Parse::Method::Signatures — the whole vibe ✨

okay so bestie, welcome to Parse:...natures(3pm) 💖 — that's the page title, and it lives in the User Contributed Perl Documentation collection. It's a lil' module called Parse::Method::Signatures, and it does exactly one iconic thing: it parses Perl6-ish method signatures. No cap. 🎀

---

🌸 NAME 🌸

Parse::Method::Signatures — a Perl6-like method signature parser. She's beauty, she's grace, she reads your (Str $foo) and understands it. 💅

---

🦋 DESCRIPTION 🦋

So this whole thing was inspired by Perl6::Signature, but it got streamlined — she's on a diet, she only supports the subset of signature syntax that was deemed useful for TryCatch and MooseX::Method::Signatures. That's it. That's the girl. She does one job and she does it slay. ✨

---

💀 TODO 💀

the to-do list. she's got goals. manifesting. 🙈

• Document the parameter return types. (not me writing a manpage that doesn't document stuff 😭)
• Probably lots of other things. (fr fr, iconic vagueness)

---

👑 METHODS 👑

There are only two public methods on this module, bestie. Both of them get called as class methods. And both of them accept either:

• a single (non-ref) scalar, which becomes the value of the "input" attribute, or
• normal new-style arguments — a hash or a hash-ref.

pick your fighter. 🫶

💖 signature

my $sig = Parse::Method::Signatures->signature( '(Str $foo)' )

Attempts to parse the (bracketed) method signature. Returns a value, or croaks on error. So if you feed her garbage, she's gonna yell. 💅

🌈 param

my $param = Parse::Method::Signatures->param( 'Str $foo where { length($_) < 10 }')

Attempts to parse the spec for a single parameter. Returns value, or croaks on error. Same energy. Same drama.

---

🎀 ATTRIBUTES 🎀

okay so heads up: all the attributes on this class are read-only. Look, don't touch. 👑

🍓 input

• Type: Str

The string to parse. That's the whole thing. That's her food. 🍽️

🧚 offset

• Type: Int

Offset into "input" at which to start parsing. Useful for using with Devel::Declare linestring. Basically "start reading here, bestie." ✨

💜 signature_class

• Default: Parse::Method::Signatures::Sig
• Type: Str (loaded on demand class name)

The class that gets loaded up when she needs to build a signature object. on-demand, like my motivation. 😭

🌸 param_class

• Default: Parse::Method::Signatures::Param
• Type: Str (loaded on demand class name)

Same deal, but for individual params. also loaded on demand. 💅

⭐ type_constraint_class

• Default: Parse::Method::Signatures::TypeConstraint
• Type: Str (loaded on demand class name)

This is the class that's used to turn the parsed type constraint into an actual Moose::Meta::TypeConstraint object. She takes the vibe and makes it real. 🔥

🦋 from_namespace

• Type: ClassName

This one lets the module know which package it's parsing signatures from. It's entirely optional, and the only effect it has is on parsing type constraints. (lowkey just a little hint, a whisper, a nudge 🌬️)

If this attribute is set, it gets passed to "type_constraint_class", which can use it to introspect the package — commonly for MooseX::Types exported types. See "find_registered_constraint" in Parse::Method::Signature::TypeConstraints for more details. iykyk. 👀

🌈 type_constraint_callback

• Type: CodeRef

Passed to the constructor of "type_constraint_class". The default implementation of this callback just asks Moose for a type constraint matching the name that was passed in. Easy. Chill. ✨

But if you have more complex requirements — like, say, parsing types created by MooseX::Types — then you're gonna want a callback similar to this one:

# my $target_package defined elsewhere.
my $tc_cb = sub {
  my ($pms_tc, $name) = @_;
  my $code = $target_package->can($name);
  $code ? eval { $code->() }
        : $pms_tc->find_registered_constraint($name);
}

and note that the example above is better provided by just setting the "from_namespace" attribute instead. so like… do that. 💅

---

🫶 CAVEATS 🫶

okay bestie this is the part where we're honest. 🫠

Just like Perl6::Signature, the parsing of certain constructs is currently only a 'best effort' — specifically default values and where code blocks might not successfully parse for certain complex cases. Patches and failing tests are welcome! come thru. 🎀

Additionally, default value specifications are not evaluated, which means no such lexical or similar errors will be produced by this module. (not me dodging all the errors 💀) Constant folding will also not be performed.

There are certain constructs that are simply too much hassle to avoid when the workaround is simple. Currently the only cases known to parse wrong are when using anonymous variables (i.e. just sigils) in unpacked arrays. Take the following example:

method foo (ArrayRef [$, $], $some_value_we_care_about) {

In this case, the $] is treated as one of Perl's magic variables — specifically, the patch level of the Perl interpreter — rather than as a $ followed by a ], as was almost certainly intended. 💀

The workaround for this is simple: introduce a space between the characters:

method foo (ArrayRef [ $, $ ], $some_value_we_care_about) {

boom. fixed. you're welcome. 🫶

The same applies.

---

💖 AUTHOR 💖

• Ash Berlin <ash@cpan.org>. 🎀
• Thanks to Florian Ragwitz <rafl@debian.org>. 🌸
• Many thanks to Piers Cawley for showing me the way to refactor my spaghetti code into something more manageable. (🍝 → ✨, the glow-up is real)

---

⭐ SEE ALSO ⭐

• Devel::Declare — which is used by most modules that use this (currently by all modules known to the author). 👑
• <http://github.com/ashb/trycatch/tree>. 🦋

---

🌈 LICENSE 🌈

Licensed under the same terms as Perl itself. 💜

This distribution copyright 2008-2009, Ash Berlin <ash@cpan.org>.

---

and that's the whole page, bestie 🫶 this was perl v5.34.0, dated 2022-06-16, and it's filed under Parse:...natures(3pm) in the User Contributed Perl Documentation. mwah 💅✨