Mason:...spatch(3pm)

💖 Mason::Manual::RequestDispatch 💖

okay so bestie, this is the Mason::Manual::RequestDispatch page from the User Contributed Perl Documentation (section 3pm, iykyk) — and it's literally the map of how a request path turns into a page component. buckle up 🎀

---

✨ NAME ✨

Mason::Manual::RequestDispatch — the whole ~how request paths get mapped to page components~ situation 💅

---

🌸 DESCRIPTION 🌸

okay so imagine the request path is this:

/news/sports/hockey

Mason is gonna go hunting for components in this exact order, and it sets $m->path_info like I noted next to each one:

/news/sports/hockey.{mp,mc}
/news/sports/hockey/index.{mp,mc}
/news/sports/hockey/dhandler.{mp,mc}
/news/sports/dhandler.{mp,mc}  # $m->path_info = hockey
/news/sports.{mp,mc}           # $m->path_info = hockey (but see next section)
/news/dhandler.{mp,mc}         # $m->path_info = sports/hockey
/news.{mp,mc}                  # $m->path_info = sports/hockey (but see next section)
/dhandler.{mp,mc}              # $m->path_info = news/sports/hockey

and where you see ".{mp,mc}", that's just shorthand meaning either ".mp" (which means a pure-perl component) or ".mc" (which means a top-level component). slay 💅

the sections below break all these elements down in more detail, no cap.

🦋 Autoextended path 🦋

the request path gets ".mp" and ".mc" stuck on the end of it, which is how it gets translated into a component path.

/news/sports/hockey.{mp,mc}

🎀 Index 🎀

an index matches its exact directory — nothing underneath it, periodt.

/news/sports/hockey/index.{mp,mc}

🌈 Dhandlers 🌈

a dhandler matches its directory and anything underneath it too, and it sets "$m->path_info" to whatever's left over (the remainder).

/news/sports/hockey/dhandler.{mp,mc}
/news/sports/dhandler.{mp,mc}  # $m->path_info = hockey
/news/dhandler.{mp,mc}         # $m->path_info = sports/hockey
/dhandler.{mp,mc}              # $m->path_info = news/sports/hockey

🧚 Partial paths 🧚

a component can match just an initial part of the URL, setting "$m->path_info" to the remainder:

/news/sports.{mp,mc}           # $m->path_info = hockey
/news.{mp,mc}                  # $m->path_info = sports/hockey

but lowkey, since this isn't always the behavior you want, it has to be explicitly enabled for the component. Mason will call the method "allow_path_info" on the component class, and it'll only allow the match if that method returns true:

<%class>
method allow_path_info { 1 }
</%class>

the default "allow_path_info" returns false. 🫶

also important: "allow_path_info" is not checked on dhandlers, because honestly the entire point of a dhandler is to match partial paths. it's giving main character energy.

💜 Trailing slash 💜

if the request URL has a trailing slash (like, it ends with "/"), Mason removes it before the match process even starts, and adds it onto the "$m->path_info". any component that should match in that case has to have "allow_path_info" return true.

for example:

## request URL /news/
/news/index.{mp,mc}     # $m->path_info = / if index.{mp,mc} has
                        # allow_path_info => true
/news/dhandler.{mp,mc}  # $m->path_info = /
/news.{mp,mc}           # $m->path_info = / if news.{mp,mc} has
                        # allow_path_info => true

## request URL /news/sports/
/news/sports/index.{mp,mc}     # $m->path_info = / if index.{mp,mc} has
                               # allow_path_info => true
/news/sports/dhandler.{mp,mc}  # $m->path_info = /
/news/sports.{mp,mc}           # $m->path_info = / if sports.{mp,mc}
                               # has allow_path_info => true
/news/dhandler.{mp,mc}         # $m->path_info = sports/
/news.{mp,mc}                  # $m->path_info = /sports/ if news.{mp,mc}
                               # has allow_path_info => true

⭐ Routes ⭐

you can use route syntax to more elegantly parse "$m->path_info" for dhandlers and partial paths, like:

<%class>
route "{year:[0-9]+}/{month:[0-9]{2}}";
</%class>

see Mason::Plugin::RouterSimple — she's iconic. 👑

---

👀 SEE ALSO 👀

• Mason

---

💖 AUTHOR 💖

Jonathan Swartz <swartz@pobox.com>

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2012 by Jonathan Swartz.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt 💅

---

and that's the whole page bestie!! 🫶 this was Mason:...spatch(3pm) — yes that's the truncated little header name, it's really Mason::Manual::RequestDispatch — generated with perl v5.34.0 on 2022-05-27. go forth and route, you're doing amazing 🌸✨🎀