.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Biber::Utils 3pm"
.TH Biber::Utils 3pm "2023-08-27" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Biber::Utils \- Various utility subs used in Biber
.SH "EXPORT"
.IX Header "EXPORT"
All functions are exported by default.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "glob_data_file"
.IX Subsection "glob_data_file"
.Vb 1
\&  Expands a data file glob to a list of filenames
.Ve
.SS "slurp_switchr"
.IX Subsection "slurp_switchr"
.Vb 2
\&  Use different read encoding/slurp interfaces for Windows due to its
\&  horrible legacy codepage system
.Ve
.SS "slurp_switchw"
.IX Subsection "slurp_switchw"
.Vb 2
\&  Use different write encoding/slurp interfaces for Windows due to its
\&  horrible legacy codepage system
.Ve
.SS "locate_data_file"
.IX Subsection "locate_data_file"
.Vb 1
\&  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
.Ve
.SS ""
.IX Subsection ""
.Vb 2
\&  Check existence of NFC/NFD file variants and return correct one.
\&  Account for windows file encodings
.Ve
.SS "check_empty"
.IX Subsection "check_empty"
.Vb 1
\&    Wrapper around empty check to deal with Win32 Unicode filenames
.Ve
.SS "check_exists"
.IX Subsection "check_exists"
.Vb 1
\&    Wrapper around exists check to deal with Win32 Unicode filenames
.Ve
.SS "biber_warn"
.IX Subsection "biber_warn"
.Vb 2
\&    Wrapper around various warnings bits and pieces.
\&    Add warning to the list of .bbl warnings and the master list of warnings
.Ve
.SS "biber_error"
.IX Subsection "biber_error"
.Vb 2
\&    Wrapper around error logging
\&    Forces an exit.
.Ve
.SS "makenamesid"
.IX Subsection "makenamesid"
Given a Biber::Names object, return an underscore normalised
concatenation of all of the full name strings.
.SS "makenameid"
.IX Subsection "makenameid"
Given a Biber::Name object, return an underscore normalised
concatenation of the full name strings.
.SS "latex_recode_output"
.IX Subsection "latex_recode_output"
.Vb 1
\&  Tries to convert UTF\-8 to TeX macros in passed string
.Ve
.SS "strip_noinit"
.IX Subsection "strip_noinit"
.Vb 2
\&  Removes elements which are not to be considered during initials generation
\&  in names
.Ve
.SS "strip_nosort"
.IX Subsection "strip_nosort"
.Vb 1
\&  Removes elements which are not to be used in sorting a name from a string
.Ve
.SS "strip_nonamestring"
.IX Subsection "strip_nonamestring"
.Vb 1
\&  Removes elements which are not to be used in certain name\-related operations like:
\&
\&  * fullhash generation
\&  * uniquename generation
\&
\& from a name
.Ve
.SS "normalise_string_label"
.IX Subsection "normalise_string_label"
Remove some things from a string for label generation. Don't strip \ep{Dash}
as this is needed to process compound names or label generation.
.SS "normalise_string_sort"
.IX Subsection "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 as they are completely ignorable in \s-1DUCET\s0
.SS "normalise_string_bblxml"
.IX Subsection "normalise_string_bblxml"
Some string normalisation for bblxml output
.SS "normalise_string"
.IX Subsection "normalise_string"
Removes LaTeX macros, and all punctuation, symbols, separators and control characters,
as well as leading and trailing whitespace for sorting strings.
Only decodes LaTeX character macros into Unicode if output is \s-1UTF\-8\s0
.SS "normalise_string_common"
.IX Subsection "normalise_string_common"
.Vb 1
\&  Common bit for normalisation
.Ve
.SS "normalise_string_hash"
.IX Subsection "normalise_string_hash"
.Vb 2
\&  Normalise strings used for hashes. We collapse LaTeX macros into a vestige
\&  so that hashes are unique between things like:
\&
\&  Smith
\&  {\ev S}mith
\&
\&  we replace macros like this to preserve their vestiges:
\&
\&  \ev S \-> v:
\&  \e" \-> 34:
.Ve
.SS "normalise_string_underscore"
.IX Subsection "normalise_string_underscore"
.Vb 1
\&  Like normalise_string, but also substitutes ~ and whitespace with underscore.
.Ve
.SS "escape_label"
.IX Subsection "escape_label"
.Vb 1
\&  Escapes a few special character which might be used in labels
.Ve
.SS "unescape_label"
.IX Subsection "unescape_label"
.Vb 2
\&  Unscapes a few special character which might be used in label but which need
\&  sorting without escapes
.Ve
.SS "reduce_array"
.IX Subsection "reduce_array"
reduce_array(\e@a, \e@b) returns all elements in \f(CW@a\fR that are not in \f(CW@b\fR
.SS "remove_outer"
.IX Subsection "remove_outer"
.Vb 4
\&    Remove surrounding curly brackets:
\&        \*(Aq{string}\*(Aq \-> \*(Aqstring\*(Aq
\&    but not
\&        \*(Aq{string} {string}\*(Aq \-> \*(Aqstring} {string\*(Aq
\&
\&    Return (boolean if stripped, string)
.Ve
.SS "has_outer"
.IX Subsection "has_outer"
.Vb 1
\&    Return (boolean if surrounded in braces
.Ve
.SS "add_outer"
.IX Subsection "add_outer"
.Vb 2
\&    Add surrounding curly brackets:
\&        \*(Aqstring\*(Aq \-> \*(Aq{string}\*(Aq
.Ve
.SS "ucinit"
.IX Subsection "ucinit"
.Vb 1
\&    upper case of initial letters in a string
.Ve
.SS "is_undef"
.IX Subsection "is_undef"
.Vb 6
\&    Checks for undefness of arbitrary things, including
\&    composite method chain calls which don\*(Aqt 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()
.Ve
.SS "is_def"
.IX Subsection "is_def"
.Vb 1
\&    Checks for definedness in the same way as is_undef()
.Ve
.SS "is_undef_or_null"
.IX Subsection "is_undef_or_null"
.Vb 1
\&    Checks for undef or nullness (see is_undef() above)
.Ve
.SS "is_def_and_notnull"
.IX Subsection "is_def_and_notnull"
.Vb 1
\&    Checks for def and unnullness (see is_undef() above)
.Ve
.SS "is_def_and_null"
.IX Subsection "is_def_and_null"
.Vb 1
\&    Checks for def and nullness (see is_undef() above)
.Ve
.SS "is_null"
.IX Subsection "is_null"
.Vb 1
\&    Checks for nullness
.Ve
.SS "is_notnull"
.IX Subsection "is_notnull"
.Vb 1
\&    Checks for notnullness
.Ve
.SS "is_notnull_scalar"
.IX Subsection "is_notnull_scalar"
.Vb 1
\&    Checks for notnullness of a scalar
.Ve
.SS "is_notnull_array"
.IX Subsection "is_notnull_array"
.Vb 1
\&    Checks for notnullness of an array (passed by ref)
.Ve
.SS "is_notnull_hash"
.IX Subsection "is_notnull_hash"
.Vb 1
\&    Checks for notnullness of an hash (passed by ref)
.Ve
.SS "is_notnull_object"
.IX Subsection "is_notnull_object"
.Vb 1
\&    Checks for notnullness of an object (passed by ref)
.Ve
.SS "stringify_hash"
.IX Subsection "stringify_hash"
.Vb 1
\&    Turns a hash into a string of keys and values
.Ve
.SS "normalise_utf8"
.IX Subsection "normalise_utf8"
.Vb 2
\&  Normalise any UTF\-8 encoding string immediately to exactly what we want
\&  We want the strict perl utf8 "UTF\-8"
.Ve
.SS "inits"
.IX Subsection "inits"
.Vb 4
\&   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\*(Aqt 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.
.Ve
.SS "join_name"
.IX Subsection "join_name"
.Vb 2
\&  Replace all join typsetting elements in a name part (space, ties) with BibLaTeX macros
\&  so that typesetting decisions are made in BibLaTeX, not hard\-coded in Biber
.Ve
.SS "filter_entry_options"
.IX Subsection "filter_entry_options"
.Vb 1
\&    Process any per_entry option transformations which are necessary on output
.Ve
.SS "imatch"
.IX Subsection "imatch"
.Vb 3
\&    Do an interpolating (neg)match using a match RE and a string passed in as variables
\&    Using /g on matches so that $1,$2 etc. can be populated from repeated matches of
\&    same capture group as well as different groups
.Ve
.SS "ireplace"
.IX Subsection "ireplace"
.Vb 2
\&    Do an interpolating match/replace using a match RE, replacement RE
\&    and string passed in as variables
.Ve
.SS "validate_biber_xml"
.IX Subsection "validate_biber_xml"
.Vb 1
\&  Validate a biber/biblatex XML metadata file against an RNG XML schema
.Ve
.SS "map_boolean"
.IX Subsection "map_boolean"
.Vb 2
\&    Convert booleans between strings and numbers. Because standard XML "boolean"
\&    datatype considers "true" and "1" the same etc.
.Ve
.SS "process_entry_options"
.IX Subsection "process_entry_options"
.Vb 1
\&    Set per\-entry options
.Ve
.SS "merge_entry_options"
.IX Subsection "merge_entry_options"
.Vb 1
\&    Merge entry options, dealing with conflicts
.Ve
.SS "expand_option_input"
.IX Subsection "expand_option_input"
.Vb 1
\&    Expand options such as meta\-options coming from biblatex
.Ve
.SS "parse_date_range"
.IX Subsection "parse_date_range"
.Vb 1
\&  Parse of ISO8601 date range
.Ve
.SS "parse_date_unspecified"
.IX Subsection "parse_date_unspecified"
.Vb 2
\&  Parse of ISO8601\-2:2016 4.3 unspecified format into date range
\&  Returns range plus specification of granularity of unspecified
.Ve
.SS "parse_date_start"
.IX Subsection "parse_date_start"
.Vb 1
\&  Convenience wrapper
.Ve
.SS "parse_date_end"
.IX Subsection "parse_date_end"
.Vb 1
\&  Convenience wrapper
.Ve
.SS "parse_date"
.IX Subsection "parse_date"
.Vb 1
\&  Parse of iso8601\-2 dates
.Ve
.SS "date_monthday"
.IX Subsection "date_monthday"
.Vb 1
\&  Force month/day to ISO8601\-2:2016 format with leading zero
.Ve
.SS "biber_decode_utf8"
.IX Subsection "biber_decode_utf8"
.Vb 2
\&    Perform NFD form conversion as well as UTF\-8 conversion. Used to normalize
\&    bibtex input as the T::B interface doesn\*(Aqt allow a neat whole file slurping.
.Ve
.SS "out"
.IX Subsection "out"
.Vb 1
\&  Output to target. Outputs NFC UTF\-8 if output is UTF\-8
.Ve
.SS "process_comment"
.IX Subsection "process_comment"
.Vb 1
\&  Fix up some problems with comments after being processed by btparse
.Ve
.SS "locale2bcp47"
.IX Subsection "locale2bcp47"
.Vb 2
\&  Map babel/polyglossia language options to a sensible CLDR (bcp47) locale default
\&  Return input string if there is no mapping
.Ve
.SS "bcp472locale"
.IX Subsection "bcp472locale"
.Vb 2
\&  Map CLDR (bcp47) locale to a babel/polyglossia locale
\&  Return input string if there is no mapping
.Ve
.SS "rangelen"
.IX Subsection "rangelen"
.Vb 4
\&  Calculate 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 be empty for open\-ended range or undef
\&  Deals with Unicode and ASCII roman numerals via the magic of Unicode NFKD form
\&
\&  m\-n \-> [m, n]
\&  m   \-> [m, undef]
\&  m\-  \-> [m, \*(Aq\*(Aq]
\&  \-n  \-> [\*(Aq\*(Aq, n]
\&  \-   \-> [\*(Aq\*(Aq, undef]
.Ve
.SS "match_indices"
.IX Subsection "match_indices"
.Vb 2
\&  Return array ref of array refs of matches and start indices of matches
\&  for provided array of compiled regexps into string
.Ve
.SS "parse_range"
.IX Subsection "parse_range"
.Vb 4
\&  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\*(Aqs up to surrounding code to interpret this
\&  Ranges can be single figures which is shorthand for 1\-x
.Ve
.SS "strip_annotation"
.IX Subsection "strip_annotation"
.Vb 1
\&  Removes annotation marker from a field name
.Ve
.SS "parse_range_alt"
.IX Subsection "parse_range_alt"
.Vb 2
\&  Parses a range of values into a two\-value array ref.
\&  Either start or end can be undef and it\*(Aqs up to surrounding code to interpret this
.Ve
.SS "maploopreplace"
.IX Subsection "maploopreplace"
.Vb 1
\&  Replace loop markers with values.
.Ve
.SS "get_transliterator"
.IX Subsection "get_transliterator"
.Vb 3
\&  Get a ref to a transliterator for the given from/to
\&  We are abstracting this in this way because it is not clear what the future
\&  of the transliteration library is. We want to be able to switch.
.Ve
.SS "call_transliterator"
.IX Subsection "call_transliterator"
.Vb 2
\&  Run a transliterator on passed text. Hides call semantics of transliterator
\&  so we can switch engine in the future.
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Philip Kime \f(CW\*(C`<philip at kime.org.uk>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests on our Github tracker at
<https://github.com/plk/biber/issues>.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2012\-2023 Philip Kime, all rights reserved.
.PP
This module is free software.  You can redistribute it and/or
modify it under the terms of the Artistic License 2.0.
.PP
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.