.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "Biber 3pm"
.TH Biber 3pm 2023-07-25 "perl v5.38.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 \- main module for biber, a bibtex replacement for users of biblatex
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&    use Biber;
\&    my $biber = Biber\->new();
\&    $biber\->parse_ctrlfile("example.bcf");
\&    $biber\->prepare;
.Ve
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    Initialize the Biber object, optionally passing named options as arguments.
.Ve
.SS display_end
.IX Subsection "display_end"
.Vb 1
\&   Output summary of warnings/errors/misc before exit
.Ve
.SS biber_tempdir
.IX Subsection "biber_tempdir"
.Vb 1
\&    Returns a File::Temp directory object for use in various things
.Ve
.SS biber_tempdir_name
.IX Subsection "biber_tempdir_name"
.Vb 1
\&    Returns the directory name of the File::Temp directory object
.Ve
.SS sections
.IX Subsection "sections"
.Vb 1
\&    my $sections= $biber\->sections
\&
\&    Returns a Biber::Sections object describing the bibliography sections
.Ve
.SS add_sections
.IX Subsection "add_sections"
.Vb 1
\&    Adds a Biber::Sections object. Used externally from, e.g. biber
.Ve
.SS datalists
.IX Subsection "datalists"
.Vb 1
\&    my $datalists = $biber\->datalists
\&
\&    Returns a Biber::DataLists object describing the bibliography sorting lists
.Ve
.SS langtags
.IX Subsection "langtags"
.Vb 1
\&    Returns a Biber::LangTags object containing a parser for BCP47 tags
.Ve
.SS set_output_obj
.IX Subsection "set_output_obj"
.Vb 2
\&    Sets the object used to output final results
\&    Must be a subclass of Biber::Output::base
.Ve
.SS get_preamble
.IX Subsection "get_preamble"
.Vb 1
\&    Returns the current preamble as an array ref
.Ve
.SS get_output_obj
.IX Subsection "get_output_obj"
.Vb 1
\&    Returns the object used to output final results
.Ve
.SS set_current_section
.IX Subsection "set_current_section"
.Vb 1
\&    Sets the current section number that we are working on to a section number
.Ve
.SS get_current_section
.IX Subsection "get_current_section"
.Vb 1
\&    Gets the current section number that we are working on
.Ve
.SS tool_mode_setup
.IX Subsection "tool_mode_setup"
.Vb 1
\&  Fakes parts of the control file for tool mode
.Ve
.SS parse_ctrlfile
.IX Subsection "parse_ctrlfile"
.Vb 3
\&    This method reads the control file
\&    generated by biblatex to work out the various biblatex options.
\&    See Constants.pm for defaults and example of the data structure being built here.
.Ve
.SS process_setup
.IX Subsection "process_setup"
.Vb 1
\&   Place to put misc pre\-processing things needed later
.Ve
.SS process_setup_tool
.IX Subsection "process_setup_tool"
.Vb 1
\&   Place to put misc pre\-processing things needed later for tool mode
.Ve
.SS resolve_alias_refs
.IX Subsection "resolve_alias_refs"
.Vb 1
\&  Resolve aliases in xref/crossref/xdata which take keys as values to their real keys
\&
\&  We use set_datafield as we are overriding the alias in the datasource
.Ve
.SS process_citekey_aliases
.IX Subsection "process_citekey_aliases"
.Vb 2
\& Remove citekey aliases from citekeys as they don\*(Aqt point to real
\& entries.
.Ve
.SS instantiate_dynamic
.IX Subsection "instantiate_dynamic"
.Vb 5
\&    This instantiates any dynamic entries so that they are available
\&    for processing later on. This has to be done before most all other
\&    processing so that when we call $section\->bibentry($key), as we
\&    do many times in the code, we don\*(Aqt die because there is a key but
\&    no Entry object.
.Ve
.SS resolve_xdata
.IX Subsection "resolve_xdata"
.Vb 1
\&    Resolve xdata
.Ve
.SS cite_setmembers
.IX Subsection "cite_setmembers"
.Vb 1
\&    Promotes set member to cited status
.Ve
.SS preprocess_sets
.IX Subsection "preprocess_sets"
.Vb 1
\&    $biber\->preprocess_sets
\&
\&    This records the set information for use later
.Ve
.SS calculate_interentry
.IX Subsection "calculate_interentry"
.Vb 1
\&    $biber\->calculate_interentry
\&
\&    Ensures that crossrefs/xrefs that are directly cited or cross\-referenced
\&    at least mincrossrefs/minxrefs times are included in the bibliography.
.Ve
.SS process_interentry
.IX Subsection "process_interentry"
.Vb 1
\&    $biber\->process_interentry
\&
\&    Ensures proper inheritance of data from cross\-references.
.Ve
.SS validate_datamodel
.IX Subsection "validate_datamodel"
.Vb 5
\&  Validate bib data according to a datamodel
\&  Note that we are validating the internal Biber::Entries
\&  after they have been created from the datasources so this is
\&  datasource neutral, as it should be. It is here to enforce
\&  adherence to what biblatex expects.
.Ve
.SS process_namedis
.IX Subsection "process_namedis"
.Vb 3
\&    Generate name strings and disambiguation schema. Has to be in the context
\&    of a data list (reference context) because uniquenametemplate can be specified
\&    per\-list/context
.Ve
.SS postprocess_sets
.IX Subsection "postprocess_sets"
.Vb 1
\&  Adds required per\-entry options etc. to sets
.Ve
.SS process_entries_static
.IX Subsection "process_entries_static"
.Vb 2
\&  Processing of entries which is not list\-specific and which can therefore
\&  insert data directly into entries
.Ve
.SS process_entries_pre
.IX Subsection "process_entries_pre"
.Vb 3
\&    Main processing operations, to generate metadata and entry information
\&    This method is automatically called by C<prepare>.
\&    Runs prior to uniqueness processing
.Ve
.SS process_entries_post
.IX Subsection "process_entries_post"
.Vb 3
\&    More processing operations, to generate things which require uniqueness
\&    information like namehash
\&    Runs after uniqueness processing
.Ve
.SS process_entries_final
.IX Subsection "process_entries_final"
.Vb 1
\&    Final processing operations which depend on all previous processing
.Ve
.SS process_uniqueprimaryauthor
.IX Subsection "process_uniqueprimaryauthor"
.Vb 1
\&    Track seen primary author base names for generation of uniqueprimaryauthor
.Ve
.SS process_workuniqueness
.IX Subsection "process_workuniqueness"
.Vb 2
\&    Track seen work combination for generation of singletitle, uniquetitle, uniquebaretitle and
\&    uniquework
.Ve
.SS process_extradate
.IX Subsection "process_extradate"
.Vb 1
\&    Track labelname/labeltitle+date parts combination for generation of extradate
.Ve
.SS process_extraname
.IX Subsection "process_extraname"
.Vb 1
\&    Track labelname only for generation of extraname
.Ve
.SS process_extratitle
.IX Subsection "process_extratitle"
.Vb 1
\&    Track labelname/labeltitle combination for generation of extratitle
.Ve
.SS process_extratitleyear
.IX Subsection "process_extratitleyear"
.Vb 1
\&    Track labeltitle/labelyear combination for generation of extratitleyear
.Ve
.SS process_sets
.IX Subsection "process_sets"
.Vb 1
\&    Postprocess set entries
\&
\&    Checks for common set errors and enforces "dataonly" options for set members.
\&    It\*(Aqs not necessary to set skipbib, skipbiblist in the OPTIONS field for
\&    the set members as these are automatically set by biblatex due to the \einset
.Ve
.SS process_nocite
.IX Subsection "process_nocite"
.Vb 1
\&    Generate nocite information
.Ve
.SS process_labelname
.IX Subsection "process_labelname"
.Vb 1
\&    Generate labelname information.
.Ve
.SS process_labeldate
.IX Subsection "process_labeldate"
.Vb 1
\&    Generate labeldate information, including times
.Ve
.SS process_labeltitle
.IX Subsection "process_labeltitle"
.Vb 1
\&  Generate labeltitle
\&
\&  Note that this is not conditionalised on the biblatex "labeltitle"
\&  as labeltitle should always be output since all standard styles need it.
\&  Only extratitle is conditionalised on the biblatex "labeltitle" option.
.Ve
.SS process_fullhash
.IX Subsection "process_fullhash"
.Vb 1
\&    Generate fullhash
.Ve
.SS process_namehash
.IX Subsection "process_namehash"
.Vb 1
\&    Generate namehash
.Ve
.SS process_pername_hashes
.IX Subsection "process_pername_hashes"
.Vb 1
\&    Generate per_name_hashes
.Ve
.SS process_visible_names
.IX Subsection "process_visible_names"
.Vb 2
\&    Generate the visible name information.
\&    This is used in various places and it is useful to have it generated in one place.
.Ve
.SS process_labelalpha
.IX Subsection "process_labelalpha"
.Vb 1
\&    Generate the labelalpha and also the variant for sorting
.Ve
.SS process_extraalpha
.IX Subsection "process_extraalpha"
.Vb 1
\&    Generate the extraalpha information
.Ve
.SS process_presort
.IX Subsection "process_presort"
.Vb 3
\&    Put presort fields for an entry into the main Biber bltx state
\&    so that it is all available in the same place since this can be
\&    set per\-type and globally too.
.Ve
.SS process_lists
.IX Subsection "process_lists"
.Vb 1
\&    Process a bibliography list
.Ve
.SS check_list_filter
.IX Subsection "check_list_filter"
.Vb 1
\&    Run an entry through a list filter. Returns a boolean.
.Ve
.SS generate_sortdataschema
.IX Subsection "generate_sortdataschema"
.Vb 1
\&    Generate sort data schema for Sort::Key from sort spec like this:
\&
\&  spec   => [
\&              [undef, { presort => {} }],
\&              [{ final => 1 }, { sortkey => {} }],
\&              [
\&                {\*(Aqsort_direction\*(Aq  => \*(Aqdescending\*(Aq},
\&                { sortname => {} },
\&                { author => {} },
\&                { editor => {} },
\&                { translator => {} },
\&                { sorttitle => {} },
\&                { title => {} },
\&              ],
\&              [undef, { sortyear => {} }, { year => {} }],
\&              [undef, { sorttitle => {} }, { title => {} }],
\&              [undef, { volume => {} }, { "0000" => {} }],
\&            ],
.Ve
.SS generate_sortinfo
.IX Subsection "generate_sortinfo"
.Vb 1
\&    Generate information for sorting
.Ve
.SS uniqueness
.IX Subsection "uniqueness"
.Vb 1
\&    Generate the uniqueness information needed when creating .bbl
.Ve
.SS create_uniquename_info
.IX Subsection "create_uniquename_info"
.Vb 1
\&    Gather the uniquename information as we look through the names
\&
\&    What is happening in here is the following: We are registering the
\&    number of occurrences of each name, name+init and fullname within a
\&    specific context. For example, the context is "global" with uniquename
\&    < mininit and "name list" for uniquename=mininit or minfull. The keys
\&    we store to count this are the most specific information for the
\&    context, so, for uniquename < mininit, this is the full name and for
\&    uniquename=mininit or minfull, this is the complete list of full names.
\&    These keys have values in a hash which are ignored. They serve only to
\&    accumulate repeated occurrences with the context and we don\*(Aqt care
\&    about this and so the values are a useful sinkhole for such repetition.
\&
\&    For example, if we find in the global context a base name "Smith" in two different entries
\&    under the same form "Alan Smith", the data structure will look like:
\&
\&    {Smith}\->{global}\->{Alan Smith} = 2
\&
\&    We don\*(Aqt care about the value as this means that there are 2 "Alan Smith"s in the global
\&    context which need disambiguating identically anyway. So, we just count the keys for the
\&    base name "Smith" in the global context to see how ambiguous the base name itself is. This
\&    would be "1" and so "Alan Smith" would get uniquename=false because it\*(Aqs unambiguous as just
\&    "Smith".
\&
\&    The same goes for "minimal" list context disambiguation for uniquename=mininit or minfull.
\&    For example, if we had the base name "Smith" to disambiguate in two entries with labelname
\&    "John Smith and Alan Jones", the data structure would look like:
\&
\&    {Smith}\->{Smith+Jones}\->{John Smith+Alan Jones} = 2
\&
\&    Again, counting the keys of the context for the base name gives us "1" which means we
\&    have uniquename=false for "John Smith" in both entries because it\*(Aqs the same list. This also
\&    works for repeated names in the same list "John Smith and Bert Smith". Disambiguating
\&    "Smith" in this:
\&
\&    {Smith}\->{Smith+Smith}\->{John Smith+Bert Smith} = 2
\&
\&    So both "John Smith" and "Bert Smith" in this entry get
\&    uniquename=false (of course, as long as there are no other "X Smith and
\&    Y Smith" entries where X != "John" or Y != "Bert").
\&
\&    The values from biblatex.sty:
\&
\&    false   = 0
\&    init    = 1
\&    true    = 2
\&    full    = 2
\&    allinit = 3
\&    allfull = 4
\&    mininit = 5
\&    minfull = 6
.Ve
.SS generate_uniquename
.IX Subsection "generate_uniquename"
.Vb 2
\&   Generate the per\-name uniquename values using the information
\&   harvested by create_uniquename_info()
.Ve
.SS create_uniquelist_info
.IX Subsection "create_uniquelist_info"
.Vb 1
\&    Gather the uniquelist information as we look through the names
.Ve
.SS generate_uniquelist
.IX Subsection "generate_uniquelist"
.Vb 2
\&   Generate the per\-namelist uniquelist values using the information
\&   harvested by create_uniquelist_info()
.Ve
.SS generate_contextdata
.IX Subsection "generate_contextdata"
.Vb 1
\&    Generate information for data which may changes per datalist
.Ve
.SS generate_singletitle
.IX Subsection "generate_singletitle"
.Vb 2
\&    Generate the singletitle field, if requested. The information for generating
\&    this is gathered in process_workuniqueness()
.Ve
.SS generate_uniquetitle
.IX Subsection "generate_uniquetitle"
.Vb 2
\&    Generate the uniquetitle field, if requested. The information for generating
\&    this is gathered in process_workuniqueness()
.Ve
.SS generate_uniquebaretitle
.IX Subsection "generate_uniquebaretitle"
.Vb 2
\&    Generate the uniquebaretitle field, if requested. The information for generating
\&    this is gathered in process_workuniqueness()
.Ve
.SS generate_uniquework
.IX Subsection "generate_uniquework"
.Vb 2
\&    Generate the uniquework field, if requested. The information for generating
\&    this is gathered in process_workuniqueness()
.Ve
.SS generate_uniquepa
.IX Subsection "generate_uniquepa"
.Vb 2
\&    Generate the uniqueprimaryauthor field, if requested. The information for generating
\&    this is gathered in create_uniquename_info()
.Ve
.SS sort_list
.IX Subsection "sort_list"
.Vb 2
\&    Sort a list using information in entries according to a certain sorting template.
\&    Use a flag to skip info messages on first pass
.Ve
.SS preprocess_options
.IX Subsection "preprocess_options"
.Vb 2
\&   Preprocessing for options. Used primarily to perform process\-intensive
\&   operations which can be done once instead of inside dense loops later.
.Ve
.SS prepare
.IX Subsection "prepare"
.Vb 2
\&    Do the main work.
\&    Process and sort all entries before writing the output.
.Ve
.SS prepare_tool
.IX Subsection "prepare_tool"
.Vb 1
\&    Do the main work for tool mode
.Ve
.SS fetch_data
.IX Subsection "fetch_data"
.Vb 2
\&    Fetch citekey and dependents data from section datasources
\&    Expects to find datasource packages named:
\&
\&    Biber::Input::<type>::<datatype>
\&
\&    and one defined subroutine called:
\&
\&    Biber::Input::<type>::<datatype>::extract_entries
\&
\&    which takes args:
\&
\&    1: Biber object
\&    2: Datasource name
\&    3: Reference to an array of cite keys to look for
\&
\&    and returns an array of the cite keys it did not find in the datasource
.Ve
.SS get_dependents
.IX Subsection "get_dependents"
.Vb 2
\&  Get dependents of the entries for a given list of citekeys. Is called recursively
\&  until there are no more dependents to look for.
.Ve
.SS remove_undef_dependent
.IX Subsection "remove_undef_dependent"
.Vb 2
\&    Remove undefined dependent keys from an entry using a map of
\&    dependent keys to entries
.Ve
.SS _parse_sort
.IX Subsection "_parse_sort"
.Vb 2
\&   Convenience sub to parse a .bcf sorting section and return nice
\&   sorting object
.Ve
.SS "_filedump and _stringdump"
.IX Subsection "_filedump and _stringdump"
.Vb 1
\&    Dump the biber object with Data::Dump for debugging
.Ve
.SH AUTHORS
.IX Header "AUTHORS"
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 2009\-2012 François Charette and Philip Kime, all rights reserved.
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.