Biber::Utils(3pm)

📦

version 2.22 · 12 versions

2.22 · fedora 43, fedora 44 (latest)
2.14 · epel 9
2.20 · epel 10
2.21 · alpine 3.24
2.22 · ubuntu stonking
2.21 · fedora 43
2.17 · ubuntu jammy
2.21 · fedora 44
2.18 · debian bookworm
2.19 · ubuntu noble
2.21 · ubuntu resolute
2.20 · debian trixie, ubuntu questing

💖 Biber::Utils — the NAME bit 💖

okay so Biber::Utils is literally just a grab-bag of utility subs that Biber uses everywhere. bestie, it's the junk drawer but make it ✨organized✨. This is the User Contributed Perl Documentation for it, Biber::Utils(3pm).

🎀 EXPORT 🎀

every single function here is exported by default. no imports needed, no cap. they just show up. 💅

🌸 FUNCTIONS 🌸

`globU1`

basically glob, except it takes a Unicode string as its argument. that's it. that's the whole vibe. 🦋

`globU`

also like glob, but with two little twists: (1) it takes a Unicode string as its argument, and (2) it tries NFC and NFD variants of the pattern, which gives you a useful approximation of a normalization-insensitive glob. it works when filenames are known to be pure NFC or pure NFD. 🫶

this covers, among others:

Apple's HFS+ file system, where filenames are coerced to NFD, and filenames \addbibresource[glob] are NFC (which is natural for keyboard entry, with typical keyboard layouts).
similar situation on APFS where some (not all) programs made files with NFD names even when the user types in NFC.
related issues when transfer between OSs changes NF of filenames but not of contents of files, e.g., .tex files.

`glob_data_file`

expands a data file glob to a list of filenames. 💫

`slurp_switchr`

uses different read encoding/slurp interfaces for Windows because of its horrible legacy codepage system. windows, bestie. 😭

`slurp_switchw`

uses different write encoding/slurp interfaces for Windows, again because of that horrible legacy codepage system. same energy, write edition. 💀

`locate_data_file`

searches for a data file by:

the exact path, if the filename is absolute
in the input_directory, if defined
in the output_directory, if defined
relative to the current directory
in the same directory as the control file
using kpsewhich, if available

it also checks existence of NFC/NFD file variants and returns the correct one, and it accounts for windows file encodings. 🌈

`check_empty`

wrapper around an empty check, there specifically to deal with Win32 Unicode filenames. ✨

`check_exists`

wrapper around an exists check, also for Win32 Unicode filenames. 👑

`biber_warn`

wrapper around various warnings bits and pieces. adds the warning to the list of .bbl warnings and to the master list of warnings. 🎀

`biber_error`

wrapper around error logging. heads up: it forces an exit. dramatic but necessary. 🚨

`makenamesid`

given a Biber::Names object, return an underscore-normalised concatenation of all of the full name strings. 💜

`makenameid`

given a Biber::Name object, return an underscore-normalised concatenation of the full name strings. same idea, singular. 🦋

`latex_recode_output`

tries to convert UTF-8 to TeX macros in the passed string. 🔥

`strip_noinit`

removes elements which are not to be considered during initials generation in names. ✂️

`strip_nosort`

removes elements which are not to be used in sorting a name, from a string. 🧹

`strip_nonamestring`

removes elements which are not to be used in certain name-related operations like:

fullhash generation
uniquename generation

…from a name. 🫧

`normalise_string_label`

removes some things from a string for label generation. don't strip \p{Dash}, because that's needed to process compound names or label generation. 🌸

`normalise_string_sort`

removes LaTeX macros, and all punctuation, symbols, separators, as well as leading and trailing whitespace, for sorting strings. control chars don't need to be stripped because they are completely ignorable in DUCET. 💅

`normalise_string_bblxml`

some string normalisation for bblxml output. 🎀

`normalise_string`

removes LaTeX macros, and all punctuation, symbols, separators and control characters, as well as leading and trailing whitespace, for sorting strings. it only decodes LaTeX character macros into Unicode if output is UTF-8. 🌈

`normalise_string_common`

the common bit for normalisation. shared plumbing, iconic. 🛠️

`normalise_string_hash`

normalises strings used for hashes. it collapses LaTeX macros into a vestige so that hashes are unique between things like:

Smith
{\v S}mith

we replace macros like this to preserve their vestiges:

\v S -> v:
\" -> 34:

`normalise_string_underscore`

like normalise_string, but it also substitutes ~ and whitespace with underscore. 🫶

`escape_label`

escapes a few special characters which might be used in labels. 🛡️

`unescape_label`

unscapes (yes, unscapes, that's the word on the page 😭) a few special characters which might be used in a label but which need sorting without escapes. 🔓

`reduce_array`

reduce_array(\@a, \@b) returns all elements in @a that are not in @b. 💫

`remove_outer`

removes surrounding curly brackets:

'{string}' -> 'string'

but not:

'{string} {string}' -> 'string} {string'

return value is (boolean if stripped, string). ⭐

`has_outer`

returns (boolean if surrounded in braces. 🎀

`add_outer`

adds surrounding curly brackets:

'string' -> '{string}'

`ucinit`

upper case of initial letters in a string. 🔠

`is_undef`

checks for undefness of arbitrary things, including composite method chain calls which don't reliably work with defined() (see perldoc for defined()). this works because we are just testing the value passed to this sub. so, for example, this is randomly unreliable even if the resulting value of the arg to defined() is "undef":

defined($thing->method($arg)->method)

whereas:

is_undef($thing->method($arg)->method)

works, since we only test the return value of all the methods with defined(). 💀

`is_def`

checks for definedness in the same way as is_undef(). ✅

`is_undef_or_null`

checks for undef or nullness (see is_undef() above). 🤔

`is_def_and_notnull`

checks for def and unnullness (see is_undef() above). 🫶

`is_def_and_null`

checks for def and nullness (see is_undef() above). 🎀

`is_null`

checks for nullness. 🕳️

`is_notnull`

checks for notnullness. 💖

`is_notnull_scalar`

checks for notnullness of a scalar. 🦋

`is_notnull_array`

checks for notnullness of an array (passed by ref). 🌸

`is_notnull_hash`

checks for notnullness of a hash (passed by ref). 🌈

`is_notnull_object`

checks for notnullness of an object (passed by ref). 👑

`stringify_hash`

turns a hash into a string of keys and values. 🔤

`normalise_utf8`

normalises any UTF-8 encoding string immediately to exactly what we want — we want the strict perl utf8 "UTF-8". 💅

`inits`

we turn the initials into an array so we can be flexible with them later. the tie here is used only so we know what to split on. we don't want to make any typesetting decisions in Biber, like what to use to join initials, so on output to the .bbl, we only use BibLaTeX macros. 🎀

`join_name`

replaces all join typesetting elements in a name part (space, ties) with BibLaTeX macros, so that typesetting decisions are made in BibLaTeX, not hard-coded in Biber. 🫶

`filter_entry_options`

processes any per_entry option transformations which are necessary on output. 🧚

`imatch`

does an interpolating (neg)match using a match RE and a string passed in as variables. it uses /g on matches so that $1, $2 etc. can be populated from repeated matches of the same capture group as well as different groups. 🔍

`ireplace`

does a relatively safe interpolating match/replace using a match RE, replacement RE and string passed in as variables. 🛠️

`validate_biber_xml`

validates a biber/biblatex XML metadata file against an RNG XML schema. ✅

`map_boolean`

converts booleans between strings and numbers, because the standard XML "boolean" datatype considers "true" and "1" the same etc. 🙃

`process_entry_options`

sets per-entry options. ⚙️

`merge_entry_options`

merges entry options, dealing with conflicts. 🤝

`expand_option_input`

expands options such as meta-options coming from biblatex. 💥

`parse_date_range`

parses an ISO8601 date range. 📅

`parse_date_unspecified`

parses an ISO8601-2:2016 4.3 unspecified format into a date range. returns the range plus a specification of the granularity of unspecified. 🔎

`parse_date_start`

convenience wrapper. 🎁

`parse_date_end`

convenience wrapper. 🎁

`parse_date`

parses iso8601-2 dates. 🗓️

`date_monthday`

forces month/day to ISO8601-2:2016 format with a leading zero. 07 not 7, bestie. ✨

`biber_decode_utf8`

performs NFD form conversion as well as UTF-8 conversion. it's used to normalize bibtex input because the T::B interface doesn't allow a neat whole-file slurping. 😤

`out`

outputs to target. outputs NFC UTF-8 if output is UTF-8. 📤

`process_comment`

fixes up some problems with comments after being processed by btparse. 🩹

`locale2bcp47`

maps babel/polyglossia language options to a sensible CLDR (bcp47) locale default. returns the input string if there is no mapping. 🌍

`bcp472locale`

maps a CLDR (bcp47) locale to a babel/polyglossia locale. returns the input string if there is no mapping. 🗺️

`rangelen`

calculates the length of a range field. range fields are an array ref of two-element array refs [range_start, range_end]. range_end can be empty for an open-ended range, or undef. it deals with Unicode and ASCII roman numerals via the magic of Unicode NFKD form. 🔢

m-n -> [m, n]
m   -> [m, undef]
m-  -> [m, '']
-n  -> ['', n]
-   -> ['', undef]

`match_indices`

returns an array ref of array refs of matches and start indices of matches, for a provided array of compiled regexps into a string. 🎯

`parse_range`

parses a range of values into a two-value array ref. ranges with no starting value default to "1". ranges can be open-ended and it's up to surrounding code to interpret this. ranges can be single figures, which is shorthand for 1-x. 📏

`strip_annotation`

removes the annotation marker from a field name. ✂️

`parse_range_alt`

parses a range of values into a two-value array ref. either start or end can be undef and it's up to surrounding code to interpret this. 🫧

`maploopreplace`

replaces loop markers with values. 🔁

`get_transliterator`

gets a ref to a transliterator for the given from/to. we're abstracting it this way because it's not clear what the future of the transliteration library is — we want to be able to switch. 🔮

`call_transliterator`

runs a transliterator on passed text. it hides the call semantics of the transliterator so we can switch engines in the future. 🔄

👑 AUTHOR 👑

Philip Kime <philip at kime.org.uk> — the icon himself. 💜

🐛 BUGS 🐛

please report any bugs or feature requests on our Github tracker at <https://github.com/plk/biber/issues>. do it, bestie, they actually want to hear it. 🙈

📜 COPYRIGHT & LICENSE 📜

this module is free software. you can redistribute it and/or modify it under the terms of the Artistic License 2.0. 🎨

this program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. no promises, fr fr. 😭

and that's the whole thing! 🌟 this was Biber::Utils(3pm) from the User Contributed Perl Documentation, running on perl v5.42.3, dated 2026-08-14. slay, go normalise some strings. 💅✨🎀🦋

📦 where this page comes from

fedora 43: biber 2.22-1.fc43 · Artistic-2.0
fedora 44: biber 2.22-2.fc44 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms