WWW::F...Encoded(3pm)

🎀 NAME 🎀

WWW::Form::UrlEncoded is literally the parser and builder for application/x-www-form-urlencoded, no cap. This page is WWW::F...Encoded(3pm), from User Contributed Perl Documentation, and it’s here to help you slay your form data 💅

---

✨ SYNOPSIS ✨

Okay so first you import the functions, bestie:

use WWW::Form::UrlEncoded qw/parse_urlencoded build_urlencoded/;

my $query_string = "foo=bar&baz=param";
my @params = parse_urlencoded($query_string);
# ('foo','bar','baz','param')

my $query_string = build_urlencoded('foo','bar','baz','param');
# "foo=bar&baz=param";

---

💜 DESCRIPTION 💜

WWW::Form::UrlEncoded provides an application/x-www-form-urlencoded parser and builder. Its whole goal is compatibility with other CPAN modules, like HTTP::Body’s urlencoded parser 🫶

This module tries to use WWW::Form::UrlEncoded::XS by default, and if that fails, it uses WWW::Form::UrlEncoded::PP instead ✨

🧚 Parser rules 🧚

WWW::Form::UrlEncoded parses strings by these rules:

1. Split the application/x-www-form-urlencoded payload by & (U+0026) or ; (U+003B).
2. Make an empty array ready to store "name" and "value".
3. For each divided string, apply the next steps.
   1. If the first character of the string is ' ' (U+0020 SPACE), remove it.
   2. If the string has "=", let name be the substring from the start to the first "=", but excluding the first "=", and the rest becomes value. If there are no strings after the first "=", value is the empty string "". If the first "=" is the first character of the string, let key be the empty string "". If the string does not have any "=", all of the string becomes key and value becomes the empty string "".
   3. Replace all "+" (U+002B) with ' ' (U+0020 SPACE).
   4. Unescape name and value. Push them to the array.
4. Return the array.

🍓 Test data 🍓

Vibe check, these are the exact test mappings:

'a=b&c=d'     => ["a","b","c","d"]
'a=b;c=d'     => ["a","b","c","d"]
'a=1&b=2;c=3' => ["a","1","b","2","c","3"]
'a==b&c==d'   => ["a","=b","c","=d"]
'a=b& c=d'    => ["a","b","c","d"]
'a=b; c=d'    => ["a","b","c","d"]
'a=b; c =d'   => ["a","b","c ","d"]
'a=b;c= d '   => ["a","b","c"," d "]
'a=b&+c=d'    => ["a","b"," c","d"]
'a=b&+c+=d'   => ["a","b"," c ","d"]
'a=b&c=+d+'   => ["a","b","c"," d "]
'a=b&%20c=d'  => ["a","b"," c","d"]
'a=b&%20c%20=d' => ["a","b"," c ","d"]
'a=b&c=%20d%20' => ["a","b","c"," d "]
'a&c=d'       => ["a","","c","d"]
'a=b&=d'      => ["a","b","","d"]
'a=b&='       => ["a","b","",""]
'&'           => ["","","",""]
'='           => ["",""]
''            => []

---

🔥 FUNCTION 🔥

• @param = parse_urlencoded($str:String) — parse $str and return an Array that contains key-value pairs 💖
• $param:ArrayRef = parse_urlencoded_arrayref($str:String) — parse $str and return an ArrayRef that contains key-value pairs ✨

These are all the build_urlencoded signatures, bestie:

• $string = build_urlencoded(@param)
• $string = build_urlencoded(@param, $delim)
• $string = build_urlencoded(\@param)
• $string = build_urlencoded(\@param, $delim)
• $string = build_urlencoded(\%param)
• $string = build_urlencoded(\%param, $delim)

For all of those build_urlencoded signatures: build a urlencoded string from param. build_urlencoded accepts arrayref and hashref values 🎀

build_urlencoded( foo => 1, foo => 2);
build_urlencoded( foo => [1,2] );
build_urlencoded( [ foo => 1, foo => 2 ] );
build_urlencoded( [foo => [1,2]] );
build_urlencoded( {foo => [1,2]} );

If $delim is passed, this function uses it instead of using "&" 🦋

• $string = build_urlencoded_utf8(...) — this function is almost the same as "build_urlencoded". build_urlencoded_utf8 calls "utf8::encode" for all parameters 🌸

---

🌈 ENVIRONMENT VALUE 🌈

• WWW_FORM_URLENCODED_PP — if true, WWW::Form::UrlEncoded forces itself to load WWW::Form::UrlEncoded::PP 💅

---

👑 SEE ALSO 👑

CPAN already has some application/x-www-form-urlencoded parser modules, like these:

• URL::Encode
• URL::Encode::XS
• Text::QueryString

They’re not fully compatible with WWW::Form::UrlEncoded. The way they handle empty key-value and the separator characters they support are different 🦋

---

💖 LICENSE 💖

Copyright (C) Masahiro Nagano.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🌟 AUTHOR 🌟

Masahiro Nagano <kazeburo@gmail.com>

---

Signed, sealed, delivered with perl v5.42.0 on 2020-10-21, page WWW::F...Encoded(3pm) — mwah, bestie 💋🫶