Web::M...::Util(3pm)

📦
version 0.17 · 6 versions
, in debian bookworm, ubuntu noble

✨ Web::M...::Util(3pm) ✨

okay so bestie, we're looking at the manual page for Web::M...::Util, from the User Contributed Perl Documentation. pull up a chair, grab a strawberry 🍓, this one's short but there's lore.

💖 NAME 💖

Web::Machine::Util — the General Utility module. it does bits and bobs. that's the whole vibe.

🌸 VERSION 🌸

version 0.17

🎀 SYNOPSIS 🎀

  use Web::Machine::Util;

🦋 DESCRIPTION 🦋

so this is literally just a basic little utility module that Web::Machine uses internally, like behind the curtain, doing its little jobs. there are no real user serviceable parts in here, bestie. it's giving "staff only" door. 🚪✨

👑 FUNCTIONS 👑

  • "first" — this one gets imported from List::Util and then passed on here so it can be exported. it's a re-gift and honestly? we respect it. 💅
  • "pair_key"
  • "pair_value" — these two cuties fetch the key and the value out of a pair in the Web::Machine internals. a "pair" here is simply a HASH ref with exactly one key in it. one key, one vibe, no notes.
  • "inflate_headers( $request )" — this calls "inflate" on an instance of HTTP::Headers::ActionPack. yes, inflate. like a pool floatie but for headers. 🎈
  • "create_header( @args )" — this calls "create" on an instance of HTTP::Headers::ActionPack.
  • "create_date( $date_string | $time_peice )" — hand it either a $date_string or an instance of Time::Piece and it will inflate it into a HTTP::Headers::ActionPack::DateHeader object, suitable for use in the FSM. it's basically a glow-up for dates. ✨
  • "bind_path( $path_spec, $path )" — okay this one's the main character, let's talk. 🗣️

give it a $path_spec (described below, keep reading bestie) and a $path, and it will either bind the path to the spec and return an array of bound values, or it will return nothing. returning nothing = no match found. no match, no service. 💀

also, if you call this function in scalar context and there's only one match, it'll return that one item. otherwise it returns the array as normal. which makes this idiom super easy to use:

  if ( my $id = bind_path( '/:id', $request->path_info ) ) {
      # handle the case with an ID here
  }
  else {
      # handle other cases here
  }

now the $path_spec follows a pretty standard convention, fr fr:

  • literal path parts must match corresponding literal.
  • variable path parts are prefixed by a colon : and get captured for returning later.
  • if a question mark (?) prefixes the colon, that element is considered optional.
  • and lastly the "splat" operator (*) is supported, and it causes all the rest of the path segments to be returned. all of them. the whole rest of the aisle. 🛒

here are a few examples of this:

  spec                  path             result
  ------------------------------------------------------------
  /test/:foo/:bar       /test/1/2        ( 1, 2 )
  /test/:foo/:bar       /test/1/         undef #failure-case
  /test/*               /test/1/2/3      ( 1, 2, 3 )
  /user/:id/:action     /user/1/edit     ( 1, 'edit' )
  /?:id                 /201             ( 201 )
  /?:id                 /                ( )

this function is kept deliberately simple, and it's expected that you'll use "my" in the array form to assign multiple variables, like this:

  my ( $foo, $bar ) = bind_path( '/test/:foo/:bar', $path );

in the future we might add a "bind_path_hash" function which captures the variable names as well, but to be honest, if you feel you need that, you likely want one of the many excellent path dispatching modules available on CPAN. respectfully, go get those. 🫶

NOTE: some care should be taken when using path specs in which the only things are either optional parameters (prefixed with "?:") or the "splat" operator ("*") as they can return empty arrays, which in certain contexts can look like match failure. 🙈 in these cases you can test the match in scalar context to verify — a match failure will be "undef", whereas a match success (in which nothing was matched) will return 0 (indicating an array with zero size). so undef vs 0, that's the whole tea. 🍵

🌈 SUPPORT 🌈

bugs may be submitted through <https://github.com/houseabsolute/webmachine-perl/issues>. tell them everything, bestie, they want to know. 🐛

💜 AUTHORS 💜

  • Stevan Little <stevan@cpan.org>
  • Dave Rolsky <autarch@urth.org>

icons. legends. the way that they wrote this. 👑

this software is copyright (c) 2016 by Infinity Interactive, Inc.

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

and that's the whole page, no cap 🎀 this was Web::M...::Util(3pm), per perl v5.34.0, dated 2022-07-03. go forth and bind some paths, bestie. slay. 💅✨🦋

📦 where this page comes from