========
Tutorial
========

Step 0: Vocabulary
==================

* An **entry** designates for example `@book{...}`, `@article{...}`, etc.
* A **comment** is written as `@comment{...}`.
* A **preamble** is a `@preamble{...}` block.
* A **string** is `@string{...}`.

In an entry, you can find

* an **entry type** like `article`, `book`, etc.
* **entry keys** or **keys** such as `author`, `title`, `year`...
* and also **records**, which designates the values of those keys.


Step 1: Prepare a BibTeX file
=============================

First, we prepare a BibTeX sample file. This is just for the purpose of illustration:

.. code-block:: python

    bibtex = """@ARTICLE{Cesar2013,
      author = {Jean César},
      title = {An amazing title},
      year = {2013},
      volume = {12},
      pages = {12--23},
      journal = {Nice Journal},
      abstract = {This is an abstract. This line should be long enough to test
    	 multilines...},
      comments = {A comment},
      keywords = {keyword1, keyword2}
    }
    """

    with open('bibtex.bib', 'w') as bibfile:
        bibfile.write(bibtex)

Step 2: Parse it!
=================

Simplest call
-------------

OK. Everything is in place. Let's parse the BibTeX file.

.. code-block:: python

    import bibtexparser

    with open('bibtex.bib') as bibtex_file:
        bib_database = bibtexparser.load(bibtex_file)

    print(bib_database.entries)


It prints a list of dictionaries for reference entries, for example books, articles:

.. code-block:: python

    [{'journal': 'Nice Journal',
      'comments': 'A comment',
      'pages': '12--23',
      'abstract': 'This is an abstract. This line should be long enough to test\nmultilines...',
      'title': 'An amazing title',
      'year': '2013',
      'volume': '12',
      'ID': 'Cesar2013',
      'author': 'Jean César',
      'keyword': 'keyword1, keyword2',
      'ENTRYTYPE': 'article'}]

Note that, by convention, uppercase keys (ID, ENTRYTYPE) are data generated by the parser, while lowercase keys come from the original bibtex file.

You can also print comments, preambles and string:

.. code-block:: python

    print(bib_database.comments)
    print(bib_database.preambles)
    print(bib_database.strings)

.. note::
  If your bibtex contains months defined as strings such as :code:`month = jan`, you will need to parse it with the :code:`common_strings` option:
  :code:`bib_database = bibtexparser.bparser.BibTexParser(common_strings=True).parse_file(bibtex_file)`. (More in `Using bibtex strings`_.)


Parse a string
--------------

If for some reason, you prefer to parse a string, that's also possible:

.. code-block:: python

    import bibtexparser

    with open('bibtex.bib') as bibtex_file:
        bibtex_str = bibtex_file.read()

    bib_database = bibtexparser.loads(bibtex_str)


Tune parser's options
---------------------

In the previous snippet, several default options are used.
You can tweak them as you wish.

.. code-block:: python

   import bibtexparser
   from bibtexparser.bparser import BibTexParser

   parser = BibTexParser(common_strings=False)
   parser.ignore_nonstandard_types = False
   parser.homogenise_fields = False

   bib_database = bibtexparser.loads(bibtex_str, parser)

.. note::
   The :code:`common_strings` option needs to be set when the parser object is created and has no effect if changed afterwards.

Step 3: Export
==============

Once you worked on your parsed database, you may want to export the result. This library provides some functions to help on that. However, you can write your own functions if you have specific requirements.

Create a BibTeX file or string
--------------------------------

The bibliographic data can be converted back into a string :

.. code-block:: python

    import bibtexparser

    bibtex_str = bibtexparser.dumps(bib_database)

or a BibTeX file like this:

.. code-block:: python

    import bibtexparser

    with open('bibtex.bib', 'w') as bibtex_file:
        bibtexparser.dump(bibtex_database, bibtex_file)


Call the writer
---------------

In the first section we prepared a BibTeX sample file, we can prepare the same file using pure python and the ``BibTexWriter`` class.

.. code-block:: python

    from bibtexparser.bwriter import BibTexWriter
    from bibtexparser.bibdatabase import BibDatabase

    db = BibDatabase()
    db.entries = [
        {'journal': 'Nice Journal',
         'comments': 'A comment',
         'pages': '12--23',
         'month': 'jan',
         'abstract': 'This is an abstract. This line should be long enough to test\nmultilines...',
         'title': 'An amazing title',
         'year': '2013',
         'volume': '12',
         'ID': 'Cesar2013',
         'author': 'Jean César',
         'keyword': 'keyword1, keyword2',
         'ENTRYTYPE': 'article'}]

    writer = BibTexWriter()
    with open('bibtex.bib', 'w') as bibfile:
        bibfile.write(writer.write(db))

This code generates the following file:

.. code-block:: latex

    @article{Cesar2013,
     abstract = {This is an abstract. This line should be long enough to test
    multilines...},
     author = {Jean César},
     comments = {A comment},
     journal = {Nice Journal},
     keyword = {keyword1, keyword2},
     month = {jan},
     pages = {12--23},
     title = {An amazing title},
     volume = {12},
     year = {2013}
    }

The writer also has several flags that can be enabled to customize the output file.
For example we can use ``indent`` and ``comma_first`` to customize the previous entry, first the code:

.. code-block:: python

    from bibtexparser.bwriter import BibTexWriter
    from bibtexparser.bibdatabase import BibDatabase

    db = BibDatabase()
    db.entries = [
        {'journal': 'Nice Journal',
         'comments': 'A comment',
         'pages': '12--23',
         'month': 'jan',
         'abstract': 'This is an abstract. This line should be long enough to test\nmultilines...',
         'title': 'An amazing title',
         'year': '2013',
         'volume': '12',
         'ID': 'Cesar2013',
         'author': 'Jean César',
         'keyword': 'keyword1, keyword2',
         'ENTRYTYPE': 'article'}]

    writer = BibTexWriter()
    writer.indent = '    '     # indent entries with 4 spaces instead of one
    writer.comma_first = True  # place the comma at the beginning of the line
    with open('bibtex.bib', 'w') as bibfile:
        bibfile.write(writer.write(db))

This code results in the following, customized, file:

.. code-block:: latex

    @article{Cesar2013
    ,    abstract = {This is an abstract. This line should be long enough to test
    multilines...}
    ,    author = {Jean César}
    ,    comments = {A comment}
    ,    journal = {Nice Journal}
    ,    keyword = {keyword1, keyword2}
    ,    month = {jan}
    ,    pages = {12--23}
    ,    title = {An amazing title}
    ,    volume = {12}
    ,    year = {2013}
    }


Flags to the writer object can modify not only how an entry is printed but how several BibTeX entries are sorted and separated.
See the :ref:`API <bibtexparser_api>` for the full list of flags.


Step 4: Add salt and pepper
===========================

In this section, we discuss about some customizations and details.

Customizations
--------------

By default, the parser does not alter the content of each field and keeps it as a simple string. There are many cases
where this is not desired. For example, instead of a string with a multiple of authors, it could be parsed as a list.

To modify field values during parsing, a callback function can be supplied to the parser which can be used to modify
BibTeX entries. The library includes several functions which may be used. Alternatively, you can read them to create
your own functions.

.. code-block:: python

    import bibtexparser
    from bibtexparser.bparser import BibTexParser
    from bibtexparser.customization import *

    # Let's define a function to customize our entries.
    # It takes a record and return this record.
    def customizations(record):
        """Use some functions delivered by the library

        :param record: a record
        :returns: -- customized record
        """
        record = type(record)
        record = author(record)
        record = editor(record)
        record = journal(record)
        record = keyword(record)
        record = link(record)
        record = page_double_hyphen(record)
        record = doi(record)
        return record

    with open('bibtex.bib') as bibtex_file:
        parser = BibTexParser()
        parser.customization = customizations
        bib_database = bibtexparser.load(bibtex_file, parser=parser)
        print(bib_database.entries)


If you think that you have a customization which could be useful to others, please share with us!


Accents and weird characters
----------------------------

Your bibtex may contain accents and specific characters.
They are sometimes coded like this ``\'{e}`` but this is not the correct way, ``{\'e}`` is preferred. Moreover, you may want to manipulate ``é``. There is different situations:

* Case 1: you plan to use this library to work with latex and you assume that the original bibtex is clean. You have nothing to do.

* Case 2: you plan to use this library to work with latex but your bibtex is not really clean.

.. code-block:: python

    import bibtexparser
    from bibtexparser.bparser import BibTexParser
    from bibtexparser.customization import homogenize_latex_encoding

    with open('bibtex.bib') as bibtex_file:
        parser = BibTexParser()
        parser.customization = homogenize_latex_encoding
        bib_database = bibtexparser.load(bibtex_file, parser=parser)
        print(bib_database.entries)


* Case 3: you plan to use this library to work with something different and your bibtex is not really clean.
  Then, you probably want to use unicode.

.. code-block:: python

    import bibtexparser
    from bibtexparser.bparser import BibTexParser
    from bibtexparser.customization import convert_to_unicode

    with open('bibtex.bib') as bibtex_file:
        parser = BibTexParser()
        parser.customization = convert_to_unicode
        bib_database = bibtexparser.load(bibtex_file, parser=parser)
        print(bib_database.entries)


.. Note::

    If you want to mix different customization functions, you can write your own function.


Using bibtex strings
--------------------

.. Warning:: support for bibtex strings representation is still an experimental feature; the way strings are represented is likely to change in future releases.

Bibtex strings and string expressions are expanded by default into the value they represent.
This behavior is controlled by the ``interpolate_string`` argument of the BibTexParser. It defaults to ``True`` but can be set to ``False``, in which case bibtex strings and string expressions from input files are represented with the :class:`bibdatabase.BibDataString` and :class:`bibdatabase.BibDataStringExpression` from the :mod:`bibdatabase` module. Both classes retain the intrinsic structure of the string or expression so that they can be written to a new file, the same way. Each instance provides a :func:`get_value` method to interpolate the string or expression and the module also provide an :func:`bibdatabase.as_text` helper to expand a string or an expression when needed.

Using the code would yield the following output.

.. code-block:: python

    from bibtexparser.bparser import BibTexParser
    from bibtexparser.bibdatabase import as_text


    bibtex = """@STRING{ jean = "Jean"}
    
    @ARTICLE{Cesar2013,
      author = jean # { César},
      title = {An amazing title},
      year = {2013},
      month = jan,
      volume = {12},
      pages = {12--23},
      journal = {Nice Journal},
    }
    """

    bp = BibTexParser(interpolate_strings=False)
    bib_database = bp.parse(bibtex)
    bib_database.entries[0]
    as_text(bd.entries[0]['author'])

.. code-block:: python

    {'ENTRYTYPE': 'article',
     'ID': 'Cesar2013',
     'author': BibDataStringExpression([BibDataString('jean'), ' César']),
     'journal': 'Nice Journal',
     'month': BibDataStringExpression([BibDataString('jan')]),
     'pages': '12--23',
     'title': 'An amazing title',
     }
    'Jean César'