Unicode::Casing(3)

💖 Unicode::Casing 💖

okay bestie, gather round, because this little Perl extension (Unicode::Casing, for the record, from the User Contributed Perl Documentation corner of the world) is about to let you override the system case changing functions and honestly? iconic behavior.

---

✨ NAME ✨

Unicode::Casing — a Perl extension to override system case changing functions. that's it, that's the vibe. 💅

---

🌸 SYNOPSIS 🌸

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

use Unicode::Casing
          uc => \&my_uc, lc => \&my_lc,
          ucfirst => \&my_ucfirst, lcfirst => \&my_lcfirst,
          fc => \&my_fc;
no Unicode::Casing;

package foo::bar;
  use Unicode::Casing -load;
  sub import {
      Unicode::Casing->import(
          uc      => \&_uc,
          lc      => \&_lc,
          ucfirst => \&_ucfirst,
          lcfirst => \&_lcfirst,
          fc => \&_fc,
      );
  }
  sub unimport {
      Unicode::Casing->unimport;
  }

---

🦋 DESCRIPTION 🦋

so this module lets you override the system-defined character case changing operations. any time something inside its lexical scope would normally call lc(), lcfirst(), uc(), ucfirst(), or fc(), your corresponding user-specified function gets called instead. and we're not just talking direct calls — it also covers calls even when they're prefaced by CORE::, plus all the indirect ones via the \L, \l, \U, \u, and \F escapes in double-quoted strings and regular expressions. yes bestie, the whole squad. 👑

each function gets handed a string whose case is to be changed, and it should return the case-changed version of that string. the crucial part: within the function's dynamic scope, references to the operation it's overriding use the non-overridden version. for example:

sub my_uc {
   my $string = shift;
   print "Debugging information\n";
   return uc($string);
}
use Unicode::Casing uc => \&my_uc;
uc($foo);

this gives you the standard upper-casing behavior, but prints "Debugging information" first. and it applies to the escapes too — so if you use, say, \U inside the override function for uc(), that's gonna call the non-overridden uc(). and because this works across the dynamic scope, if "my_uc" calls function "a" which calls "b" which calls "c" which calls "uc", that "uc" is the non-overridden version. otherwise you'd be looking at the possibility of infinite recursion, and we simply cannot be doing that. 🙈 it also just fits with the typical use of these functions — using the standard case change except for a few select characters, like the example below. slay.

it is an error to not specify at least one override in the "use" statement. ones you don't specify just use the standard operation. and it's also an error to specify more than one override for the same function. pick a lane, bestie. 💀

also, "use re 'eval'" is not needed to have the inline case-changing sequences work in regular expressions. good news, free of charge. ✨

here's an example of a real-life application, for Turkish, showing off context-sensitive case-changing. (because of bugs in earlier Perls, version v5.12 is required for this example to work properly.)

sub turkish_lc($) {
   my $string = shift;

   # Unless an I is before a dot_above, it turns into a dotless i (the
   # dot above being attached to the I, without an intervening other
   # Above mark; an intervening non-mark (ccc=0) would mean that the
   # dot above would be attached to that character and not the I)
   $string =~ s/I (?! [^\p{ccc=0}\p{ccc=Above}]* \x{0307} )/\x{131}/gx;

   # But when the I is followed by a dot_above, remove the dot_above so
   # the end result will be i.
   $string =~ s/I ([^\p{ccc=0}\p{ccc=Above}]* ) \x{0307}/i$1/gx;

   $string =~ s/\x{130}/i/g;

   return lc($string);
}

a potential problem with context-dependent case changing is that the routine may be passed insufficient context, especially with the in-line escapes like \L. like, it just doesn't know enough about what's around it. 😭

90turkish.t, which comes with the distribution, includes a full implementation of all the Turkish casing rules. she did the homework. 📚

heads up: there are problems with the standard case changing operation for characters whose code points are between 128 and 255. to get the correct Unicode behavior, the strings must be encoded in utf8 (which the override functions can force) or calls to the operations must be within the scope of "use feature 'unicode_strings'" (which is available starting in Perl version 5.12).

also, note that fc() and \F are available only in Perls starting with version v5.15.8. trying to override them on earlier versions will result in a fatal error. so like, know your Perl version before you come for them. 🫶

and one more thing — there can be problems installing this (at least on Windows) if you're using an old version of ExtUtils::Depends. to get around it, follow these steps:

1. upgrade ExtUtils::Depends
2. force install B::Hooks::OP::Check
3. force install B::Hooks::OP::PPAddr

see <http://perlmonks.org/?node_id=797851>.

---

💀 BUGS 💀

ngl, this module doesn't play well when there are other attempts to override the functions, such as "use subs qw(uc lc ...);" or "*CORE::GLOBAL::uc = sub { .... };". which thing gets called depends on the ordering of the calls, and scoping rules break down. it's giving chaos, not in a cute way. 😭

---

👑 AUTHOR 👑

Karl Williamson, "<khw@cpan.org>", with advice and guidance from various Perl 5 porters, including Paul Evans, Burak Gürsoy, Florian Ragwitz, Ricardo Signes, and Matt S. Trout. the whole friend group came through. 🫶

---

🌈 COPYRIGHT AND LICENSE 🌈

Copyright (C) 2011 by Karl Williamson

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

---

and that's a wrap, bestie 🎀 this page came to you courtesy of perl v5.42.0, dated 2025-07-25, filed under Unicode::Casing(3) — go forth and change some cases, you've got this 💖✨