Data Model and Database Operations

class BibDatabase:
    """
    Bibliographic database object that follows the data structure of a BibTeX file.
    
    Acts as the primary container for all bibliographic elements including
    entries, comments, preambles, and string definitions.
    """
    
    def __init__(self):
        """
        Initialize an empty bibliographic database.
        
        Attributes:
        - entries (list): List of entry dictionaries (books, articles, etc.)
        - comments (list): List of comment strings
        - strings (OrderedDict): Dictionary of string definitions
        - preambles (list): List of preamble strings
        """

def load_common_strings(self) -> None:
    """
    Load common string definitions like month abbreviations.
    
    Adds standard month abbreviations (jan, feb, mar, etc.) to the
    strings dictionary for use in string interpolation.
    """

def expand_string(self, name: str) -> str:
    """
    Expand a string definition by name.
    
    Parameters:
    - name (str): Name of the string to expand
    
    Returns:
    str: Expanded string value
    
    Raises:
    UndefinedString: If the string name is not defined
    """

def get_entry_list(self) -> list:
    """
    Get a list of BibTeX entries.
    
    Returns:
    list: List of entry dictionaries
    
    Note: Deprecated since v0.5.6, use entries attribute directly
    """

def get_entry_dict(self) -> dict:
    """
    Return a dictionary of BibTeX entries keyed by entry ID.
    
    Creates a new dictionary mapping entry IDs to entry objects.
    Note: This method recreates the dict on each call.
    
    Returns:
    dict: Dictionary mapping entry IDs to entry dictionaries
    """

@property
def entries_dict(self) -> dict:
    """
    Property that returns entry dictionary (calls get_entry_dict).
    
    Returns:
    dict: Dictionary mapping entry IDs to entry dictionaries
    """

def add_missing_from_crossref(self) -> None:
    """
    Resolve crossrefs and update entries with missing fields from referenced entries.
    
    Processes all entries with '_crossref' fields, merging fields from the
    referenced entry that are not already present in the referencing entry.
    Handles circular dependencies and missing references gracefully.
    """

@staticmethod
def entry_sort_key(entry: dict, fields: tuple) -> tuple:
    """
    Generate a sort key for an entry based on specified fields.
    
    Parameters:
    - entry (dict): Entry dictionary to generate key for
    - fields (tuple): Field names to use for sorting
    
    Returns:
    tuple: Sort key tuple with string values from specified fields
    """

class BibDataString:
    """
    Represents a BibTeX string definition.
    
    Enables maintaining string expressions as references to other strings
    with lazy evaluation and dependency tracking.
    """
    
    def __init__(self, bibdatabase: BibDatabase, name: str):
        """
        Create a string reference.
        
        Parameters:
        - bibdatabase (BibDatabase): Database containing string definitions
        - name (str): Name of the string (case-insensitive)
        """
    
    def get_value(self) -> str:
        """
        Get the expanded value of the string.
        
        Returns:
        str: Expanded string value from the database
        
        Raises:
        UndefinedString: If string is not defined in database
        """
    
    @staticmethod
    def expand_string(string_or_bibdatastring):
        """
        Expand a string or BibDataString to its value.
        
        Parameters:
        - string_or_bibdatastring: String or BibDataString to expand
        
        Returns:
        str: Expanded string value
        """

class BibDataStringExpression:
    """
    Represents a BibTeX string expression (concatenation of strings).
    
    String expressions are sequences of regular strings and BibTeX strings
    that can be concatenated together, commonly used in BibTeX for
    combining month abbreviations with years or other string values.
    """
    
    def __init__(self, expression: list):
        """
        Create a string expression.
        
        Parameters:
        - expression (list): List of strings and BibDataString objects
        """
    
    def get_value(self) -> str:
        """
        Get the expanded value by concatenating all expression components.
        
        Returns:
        str: Concatenated and expanded string value
        """
    
    def apply_on_strings(self, fun: callable) -> None:
        """
        Apply a function to all regular strings in the expression.
        
        Parameters:
        - fun (callable): Function to apply to string components
        """
    
    @staticmethod
    def expand_if_expression(string_or_expression):
        """
        Expand a string or expression to its value.
        
        Parameters:
        - string_or_expression: String or BibDataStringExpression to expand
        
        Returns:
        str: Expanded string value
        """
    
    @staticmethod
    def expression_if_needed(tokens: list):
        """
        Create expression only if tokens represent a complex expression.
        
        Parameters:
        - tokens (list): List of parsed tokens
        
        Returns:
        str or BibDataStringExpression: Simple string or complex expression
        """

def as_text(text_string_or_expression) -> str:
    """
    Convert text, string, or expression to plain text.
    
    Parameters:
    - text_string_or_expression: Text, BibDataString, or BibDataStringExpression
    
    Returns:
    str: Plain text representation
    """

STANDARD_TYPES: set
# Standard BibTeX entry types: article, book, booklet, conference, inbook,
# incollection, inproceedings, manual, mastersthesis, misc, phdthesis,
# proceedings, techreport, unpublished

COMMON_STRINGS: dict
# Common month abbreviations: jan->January, feb->February, etc.

class UndefinedString(KeyError):
    """
    Exception raised when attempting to expand an undefined string.
    
    Inherits from KeyError for compatibility with dictionary-like access patterns.
    """
    pass

from bibtexparser.bibdatabase import BibDatabase

# Create a new database
db = BibDatabase()

# Add entries
db.entries.append({
    'ENTRYTYPE': 'article',
    'ID': 'example2023',
    'title': 'Example Article',
    'author': 'John Doe',
    'year': '2023'
})

# Add comments and preambles
db.comments.append('This is a comment')
db.preambles.append('This bibliography was generated automatically')

# Access entries
print(f"Database contains {len(db.entries)} entries")
for entry in db.entries:
    print(f"{entry['ID']}: {entry.get('title', 'No title')}")

from bibtexparser.bibdatabase import BibDatabase

db = BibDatabase()

# Load common month abbreviations
db.load_common_strings()

# Add custom string definitions
db.strings['myjournal'] = 'Journal of Example Research'
db.strings['myvolume'] = '42'

# Expand strings
print(db.expand_string('jan'))  # Output: January
print(db.expand_string('myjournal'))  # Output: Journal of Example Research

# Access all strings
for name, value in db.strings.items():
    print(f"{name} = {value}")

# Create entries with cross-references
db.entries = [
    {
        'ENTRYTYPE': 'inproceedings',
        'ID': 'paper1',
        'title': 'Example Paper',
        'author': 'Jane Smith',
        '_crossref': 'conf2023'  # Reference to conference
    },
    {
        'ENTRYTYPE': 'proceedings',
        'ID': 'conf2023',
        'title': 'Proceedings of Example Conference',
        'year': '2023',
        'publisher': 'Example Publisher'
    }
]

# Resolve cross-references
db.add_missing_from_crossref()

# The paper1 entry now has year and publisher from conf2023
paper = db.get_entry_dict()['paper1']
print(paper['year'])  # Output: 2023
print(paper['publisher'])  # Output: Example Publisher
print(paper['_FROM_CROSSREF'])  # Fields added from crossref

# Access entries by ID
entries_dict = db.get_entry_dict()
specific_entry = entries_dict.get('example2023')

if specific_entry:
    print(f"Found entry: {specific_entry['title']}")

# Or use the property
entry = db.entries_dict['example2023']

from bibtexparser.bibdatabase import BibDataString, BibDataStringExpression

# Create string references
month_ref = BibDataString(db, 'jan')
year_string = '2023'

# Create expression combining month and year
expression = BibDataStringExpression([month_ref, ' ', year_string])
print(expression.get_value())  # Output: January 2023

# Apply transformations to strings only
expression.apply_on_strings(str.upper)
print(expression.get_value())  # Output: January 2023 (month ref unchanged)