LUA-URI-_UTIL(3)

✨ lua-uri-_util — utility functions for the Lua URI library ✨

okay bestie, so this is the LUA-URI-_UTIL(3) page — the Lua uri._util module — and it's lowkey the backstage crew of the whole library. let's get into it 💅

---

🌸 Name 🌸

lua-uri-_util — utility functions for the Lua URI library. that's it, that's the name, she's simple and she serves 🫶

---

🎀 Description 🎀

So this module is basically a lil grab-bag of helper functions that the rest of the library uses. ngl, most of them are meant for internal use only, and they're subject to change in future versions — so don't build your whole personality around them, k? 🙈

But — and this is the iconic part — the URI encoding and decoding functions may be way more widely useful. those ones? those ones can be your bestie too 💖

On loading, the module returns a table containing the functions. But like all the modules in this library, it does NOT install itself into any global variables. no global jumpscares, we're respectful ✨

local Util = require "uri._util"

---

👑 Functions 👑

The following functions can be found in the table returned from require. okay let's go one by one, no skips, we're thorough here 💜

---

• uri_encode(text, pattern) — use URI encoding (a.k.a. 'percent encoding') to encode any unsafe characters in text. If pattern is specified then it should be part of a Lua pattern which can be enclosed in square brackets to make a character class. Usually it will start with "^" so that the rest of the characters will be considered the 'safe' ones — the ones we're <em>not</em> encoding, periodt. Any character matched by the pattern will be encoded.

print(Util.uri_encode("foo bar!"))
---> foo%20bar!
print(Util.uri_encode("foo bar!", "^A-Za-z0-9"))
---> foo%20bar%21

The default pattern is: "^A-Za-z0-9%-_.!~*'()"

• uri_decode(text, pattern) — decode any URI encoding in text. If pattern is nil then all encoded characters will be decoded. If a pattern is supplied then it should be in the same form as for uri_encode. Any character not matched by the pattern will be left encoded exactly as it was. no takebacks 💅

print(Util.uri_decode("foo%20bar%21"))
---> foo bar!
print(Util.uri_decode("foo%20bar%21", "^!"))
---> foo bar%21

• remove_dot_segments(path) — removes single and double dot segments from a URI path. this is the 'remove_dot_segments' algorithm from RFC 3986 section 5.2.4. The value of path is used as the input buffer, and the contents of the output buffer are returned. so clean, so tidy 🧚
• split(pattern, str, max) — split the string str wherever pattern matches it, returning the pieces as individual strings in an array. If max is not nil, then stop splitting after that many pieces have been created. she's done after that, respectfully ✋
• attempt_require(name) — calling this function is the same as calling Lua's built in require function, EXCEPT that if a module called name cannot be found, it returns nil instead of throwing an exception. If loading the module is successful then the result of require is returned. An exception is thrown if any error occurs loading the module other than it not being found. so: not found = chill 😌, other error = we're screaming 😭
• subclass_of(class, baseclass) — sets up the metatable and a few other things for the table class so that it will be a subclass of baseclass. This is used by the classes in this library to implement inheritance. it's giving family tree 🌈
• do_class_changing_change(uri, baseclass, changedesc, newvalue, changefunc) — this is used when a mutator method changes something about a URI which leads it to need to belong to a different class. Let's break it down bestie:
  • uri is the URI object to change
  • baseclass is the class to reset it to before making the change
  • changedesc is a description to be included in an error message if necessary
  • newvalue is the new value to be set (which must be a string, as it is also included in error messages)
  • and changefunc is a function which is called with a temporary URI object it should adjust and newvalue
• uri_part_not_allowed (class, method) — this should be called in scheme-specific classes where certain parts of URIs are not allowed to be present (e.g., the 'host' part in a URN). It will override the named method in the class with one which throws an exception if an attempt is made to set the part to anything other than nil. If the rest of the code for the scheme keeps objects internally consistent then the new method should always return nil — although when a URI is being validated during the init method's execution, it may return other things, which can be used to detect disallowed parts in a URI being parsed. sneaky but make it useful 💀

---

🫶 quick reminder bestie: most of these are internal, they're subject to change, so don't come for me when they shift in a future version. the encode/decode ones are the safe faves ✨

---

and that's the whole page!! version 1.1, dated 2012-00-00 — yeah she's a lil vintage, an elder icon, and honestly? she ate 👑💖 mwah, go forth and percent-encode responsibly 🎀🦋