1Biber::Utils(3) User Contributed Perl Documentation Biber::Utils(3)
2
6 Biber::Utils - Various utility subs used in Biber
7
9 All functions are exported by default.
10
12 glob_data_file
13 Expands a data file glob to a list of filenames
14 slurp_switchr
16 Use different read encoding/slurp interfaces for Windows due to its
17 horrible legacy codepage system
18 slurp_switchw
20 Use different write encoding/slurp interfaces for Windows due to its
21 horrible legacy codepage system
22 locate_data_file
24 Searches for a data file by
25 The exact path if the filename is absolute
27 In the input_directory, if defined
28 In the output_directory, if defined
29 Relative to the current directory
30 In the same directory as the control file
31 Using kpsewhich, if available
32 Check existence of NFC/NFD file variants and return correct one.
35 Account for windows file encodings
36 check_empty
38 Wrapper around empty check to deal with Win32 Unicode filenames
39 check_exists
41 Wrapper around exists check to deal with Win32 Unicode filenames
42 biber_warn
44 Wrapper around various warnings bits and pieces.
45 Add warning to the list of .bbl warnings and the master list of warnings
46 biber_error
48 Wrapper around error logging
49 Forces an exit.
50 makenamesid
52 Given a Biber::Names object, return an underscore normalised
53 concatenation of all of the full name strings.
54 makenameid
56 Given a Biber::Name object, return an underscore normalised
57 concatenation of the full name strings.
58 latex_recode_output
60 Tries to convert UTF-8 to TeX macros in passed string
61 strip_noinit
63 Removes elements which are not to be considered during initials generation
64 in names
65 strip_nosort
67 Removes elements which are not to be used in sorting a name from a string
68 strip_nonamestring
70 Removes elements which are not to be used in certain name-related operations like:
71 * fullhash generation
73 * uniquename generation
74 from a name
76 normalise_string_label
78 Remove some things from a string for label generation. Don't strip
79 \p{Dash} as this is needed to process compound names or label
80 generation.
81 normalise_string_sort
83 Removes LaTeX macros, and all punctuation, symbols, separators as well
84 as leading and trailing whitespace for sorting strings. Control chars
85 don't need to be stripped as they are completely ignorable in DUCET
86 normalise_string_bblxml
88 Some string normalisation for bblxml output
89 normalise_string
91 Removes LaTeX macros, and all punctuation, symbols, separators and
92 control characters, as well as leading and trailing whitespace for
93 sorting strings. Only decodes LaTeX character macros into Unicode if
94 output is UTF-8
95 normalise_string_common
97 Common bit for normalisation
98 normalise_string_hash
100 Normalise strings used for hashes. We collapse LaTeX macros into a vestige
101 so that hashes are unique between things like:
102 Smith
104 {\v S}mith
105 we replace macros like this to preserve their vestiges:
107 \v S -> v:
109 \" -> 34:
110 normalise_string_underscore
112 Like normalise_string, but also substitutes ~ and whitespace with underscore.
113 escape_label
115 Escapes a few special character which might be used in labels
116 unescape_label
118 Unscapes a few special character which might be used in label but which need
119 sorting without escapes
120 reduce_array
122 reduce_array(\@a, \@b) returns all elements in @a that are not in @b
123 remove_outer
125 Remove surrounding curly brackets:
126 '{string}' -> 'string'
127 but not
128 '{string} {string}' -> 'string} {string'
129 Return (boolean if stripped, string)
131 has_outer
133 Return (boolean if surrounded in braces
134 add_outer
136 Add surrounding curly brackets:
137 'string' -> '{string}'
138 ucinit
140 upper case of initial letters in a string
141 is_undef
143 Checks for undefness of arbitrary things, including
144 composite method chain calls which don't reliably work
145 with defined() (see perldoc for defined())
146 This works because we are just testing the value passed
147 to this sub. So, for example, this is randomly unreliable
148 even if the resulting value of the arg to defined() is "undef":
149 defined($thing->method($arg)->method)
151 whereas:
153 is_undef($thing->method($arg)->method)
155 works since we only test the return value of all the methods
157 with defined()
158 is_def
160 Checks for definedness in the same way as is_undef()
161 is_undef_or_null
163 Checks for undef or nullness (see is_undef() above)
164 is_def_and_notnull
166 Checks for def and unnullness (see is_undef() above)
167 is_def_and_null
169 Checks for def and nullness (see is_undef() above)
170 is_null
172 Checks for nullness
173 is_notnull
175 Checks for notnullness
176 is_notnull_scalar
178 Checks for notnullness of a scalar
179 is_notnull_array
181 Checks for notnullness of an array (passed by ref)
182 is_notnull_hash
184 Checks for notnullness of an hash (passed by ref)
185 is_notnull_object
187 Checks for notnullness of an object (passed by ref)
188 stringify_hash
190 Turns a hash into a string of keys and values
191 normalise_utf8
193 Normalise any UTF-8 encoding string immediately to exactly what we want
194 We want the strict perl utf8 "UTF-8"
195 inits
197 We turn the initials into an array so we can be flexible with them later
198 The tie here is used only so we know what to split on. We don't want to make
199 any typesetting decisions in Biber, like what to use to join initials so on
200 output to the .bbl, we only use BibLaTeX macros.
201 join_name
203 Replace all join typsetting elements in a name part (space, ties) with BibLaTeX macros
204 so that typesetting decisions are made in BibLaTeX, not hard-coded in Biber
205 filter_entry_options
207 Process any per_entry option transformations which are necessary on output
208 imatch
210 Do an interpolating (neg)match using a match RE and a string passed in as variables
211 Using /g on matches so that $1,$2 etc. can be populated from repeated matches of
212 same capture group as well as different groups
213 ireplace
215 Do an interpolating match/replace using a match RE, replacement RE
216 and string passed in as variables
217 validate_biber_xml
219 Validate a biber/biblatex XML metadata file against an RNG XML schema
220 map_boolean
222 Convert booleans between strings and numbers. Because standard XML "boolean"
223 datatype considers "true" and "1" the same etc.
224 process_entry_options
226 Set per-entry options
227 merge_entry_options
229 Merge entry options, dealing with conflicts
230 expand_option_input
232 Expand options such as meta-options coming from biblatex
233 parse_date_range
235 Parse of ISO8601 date range
236 parse_date_unspecified
238 Parse of ISO8601-2:2016 4.3 unspecified format into date range
239 Returns range plus specification of granularity of unspecified
240 parse_date_start
242 Convenience wrapper
243 parse_date_end
245 Convenience wrapper
246 parse_date
248 Parse of EDTF dates
249 date_monthday
251 Force month/day to ISO8601-2:2016 format with leading zero
252 biber_decode_utf8
254 Perform NFD form conversion as well as UTF-8 conversion. Used to normalize
255 bibtex input as the T::B interface doesn't allow a neat whole file slurping.
256 out
258 Output to target. Outputs NFC UTF-8 if output is UTF-8
259 process_comment
261 Fix up some problems with comments after being processed by btparse
262 locale2bcp47
264 Map babel/polyglossia language options to a sensible CLDR (bcp47) locale default
265 Return input string if there is no mapping
266 bcp472locale
268 Map CLDR (bcp47) locale to a babel/polyglossia locale
269 Return input string if there is no mapping
270 rangelen
272 Calculate the length of a range field
273 Range fields are an array ref of two-element array refs [range_start, range_end]
274 range_end can be be empty for open-ended range or undef
275 Deals with Unicode and ASCII roman numerals via the magic of Unicode NFKD form
276 m-n -> [m, n]
278 m -> [m, undef]
279 m- -> [m, '']
280 -n -> ['', n]
281 - -> ['', undef]
282 match_indices
284 Return array ref of array refs of matches and start indices of matches
285 for provided array of compiled regexps into string
286 parse_range
288 Parses a range of values into a two-value array ref.
289 Ranges with no starting value default to "1"
290 Ranges can be open-ended and it's up to surrounding code to interpret this
291 Ranges can be single figures which is shorthand for 1-x
292 strip_annotation
294 Removes annotation marker from a field name
295 parse_range_alt
297 Parses a range of values into a two-value array ref.
298 Either start or end can be undef and it's up to surrounding code to interpret this
299 maploopreplace
301 Replace loop markers with values.
302 get_transliterator
304 Get a ref to a transliterator for the given from/to
305 We are abstracting this in this way because it is not clear what the future
306 of the transliteration library is. We want to be able to switch.
307 call_transliterator
309 Run a transliterator on passed text. Hides call semantics of transliterator
310 so we can switch engine in the future.
311
313 Philip Kime "<philip at kime.org.uk>"
314
316 Please report any bugs or feature requests on our Github tracker at
317 <https://github.com/plk/biber/issues>.
318
320 Copyright 2012-2022 Philip Kime, all rights reserved.
321 This module is free software. You can redistribute it and/or modify it
323 under the terms of the Artistic License 2.0.
324 This program is distributed in the hope that it will be useful, but
326 without any warranty; without even the implied warranty of
327 merchantability or fitness for a particular purpose.
328perl v5.36.0 2022-07-20 Biber::Utils(3)