Pandoc::Selector(3pm)

💖 Pandoc::Selector 💖

ok so bestie, this is a page from the User Contributed Perl Documentation for a module called Pandoc::Selector, and honestly? it ate. let's get into it 🫶

✨ NAME ✨

Pandoc::Selector — it's a whole document selector language for Pandoc. like, a language-language. not just a function. a vibe, a grammar, a lifestyle. 💅

---

🎀 SYNOPSIS 🎀

here's how you actually use it, no cap:

  my $selector = Pandoc::Selector->new('Code.perl|CodeBlock.perl');

  # check whether an element matches
  $selector->match($element);

  # use as element method
  $element->match('Code.perl|CodeBlock.perl')

so you spin up a selector object with new, you check if some element matches it with match, and — plot twist — you can also call match straight on an element as a method. convenient? iconic. 👑

---

🌸 DESCRIPTION 🌸

Pandoc::Selector hands you a language for selecting elements out of a Pandoc document. it's giving big "I borrowed my fits from my older cousins" energy: the ideas come from CSS Selectors (https://www.w3.org/TR/selectors-3/), XPath (https://www.w3.org/TR/xpath/), and other languages in that same family. slay.

and here's the tea — the language is still being developed together with this implementation. so they're growing up side by side. main character duo fr fr. 🦋

---

👑 EXAMPLES 👑

a lil taste test of what selectors look like:

  Header#main
  Code.perl
  Code.perl.raw
  :inline

that's it, that's the sampler platter. 😌

---

💅 SELECTOR GRAMMAR 💅

ok this is the part where we get technical, and lowkey it's the best part.

first up: whitespace between the parts of the syntax is optional, and it's not even represented in the grammar below. so breathe however you want, the grammar doesn't care.

a Selector is a list of one or more expression lists, separated by pipes (|). for instance, the selector Subscript|Superscript selects both Subscript elements and Superscript elements. two for one, we love a deal. 🍓

Selector        ::= ExpressionList ( '|' ExpressionList )*

an expression list is a list of one or more expressions:

ExpressionList  ::= Expression ( Expression )*

and an expression is any one of these four: a name expression, an id expression, a class expression, or a type expression.

Expression      ::= NameExpression
                    | IdExpression
                    | ClassExpression
                    | TypeExpression

NameExpression  ::= Name

Name            ::= [A-Za-z]+

IdExpression    ::= '#' [\p{L}\p{N}_-]+

ClassExpression ::= '.' [\p{L}\p{N}_-]+

TypeExpression  ::= ':' Name

so to recap the grammar in bestie terms: Name is letters only, ids start with a #, classes start with a ., types start with a :, and both ids and classes take letters, numbers, underscores and dashes (that's the \p{L}\p{N}_- situation right there). periodt. ✨

---

🌈 SEE ALSO 🌈

there's an example filter called select — go look at it if you wanna select parts of a document irl. that's the whole rec. iykyk. 🧚

---

fr fr, go read a manual page today. your future self will thank you. 💜

---

and that's a wrap, babe 🎀 — this page ships with perl v5.38.2, dated 2024-08-03, and it lives in Pandoc::Selector(3pm). love that for us. mwah. 💖 ✨ 🌸