0
# Advanced Writing Configuration
1

2
Configurable writer with extensive formatting options for controlling BibTeX output format. The BibTexWriter class provides fine-grained control over indentation, alignment, field ordering, entry sorting, and various BibTeX syntax styles.
3

4
## Capabilities
5

6
### Writer Configuration
7

8
The BibTexWriter class provides comprehensive formatting control to generate BibTeX output that matches specific style requirements or personal preferences.
9

10
```python { .api }
11
class BibTexWriter:
12
    """
13
    Writer to convert a BibDatabase object to a BibTeX-formatted string or file.
14
    
15
    Provides extensive configuration options for controlling output formatting
16
    including field ordering, indentation, alignment, and entry sorting.
17
    """
18
    
19
    def __init__(self, write_common_strings: bool = False):
20
        """
21
        Create a configurable BibTeX writer.
22

23
        Parameters:
24
        - write_common_strings (bool): If True, include common string definitions in output
25

26
        Attributes that can be configured after initialization:
27
        - contents (list): Elements to write ['comments', 'preambles', 'strings', 'entries']
28
        - indent (str): Characters for indenting field-value pairs
29
        - align_values (bool|int): Align field values by padding with spaces
30
        - align_multiline_values (bool): Align continuation lines in multiline values
31
        - entry_separator (str): Characters separating entries
32
        - order_entries_by (tuple): Fields for sorting entries
33
        - display_order (list): Preferred field order within entries
34
        - display_order_sorting (SortingStrategy): How to sort unlisted fields
35
        - comma_first (bool): Use comma-first syntax
36
        - add_trailing_comma (bool): Add comma after last field
37
        """
38
```
39

40
### String Generation
41

42
Convert BibDatabase objects to formatted BibTeX strings with all configured formatting options applied.
43

44
```python { .api }
45
def write(self, bib_database: BibDatabase) -> str:
46
    """
47
    Convert a bibliographic database to a BibTeX-formatted string.
48

49
    Parameters:
50
    - bib_database (BibDatabase): Database to convert
51

52
    Returns:
53
    str: BibTeX-formatted string with all formatting options applied
54
    """
55
```
56

57
### Sorting Strategy
58

59
Enumeration defining different strategies for sorting fields not explicitly specified in display_order.
60

61
```python { .api }
62
class SortingStrategy(Enum):
63
    """Defines sorting strategies for fields not in display_order."""
64
    
65
    ALPHABETICAL_ASC = auto()  # Alphabetical sorting in ascending order
66
    ALPHABETICAL_DESC = auto()  # Alphabetical sorting in descending order  
67
    PRESERVE = auto()  # Preserve original field order
68
```
69

70
### Legacy Convenience Function
71

72
Backwards-compatible convenience function for simple writing tasks.
73

74
```python { .api }
75
def to_bibtex(parsed: BibDatabase) -> str:
76
    """
77
    Convenience function for backwards compatibility.
78
    
79
    Parameters:
80
    - parsed (BibDatabase): Database to convert
81
    
82
    Returns:
83
    str: BibTeX-formatted string using default writer settings
84
    """
85
```
86

87
## Configuration Options
88

89
### Content Selection
90

91
Control which elements are included in the output:
92

93
```python
94
from bibtexparser.bwriter import BibTexWriter
95

96
writer = BibTexWriter()
97

98
# Include all elements (default)
99
writer.contents = ['comments', 'preambles', 'strings', 'entries']
100

101
# Only include entries
102
writer.contents = ['entries']
103

104
# Custom order
105
writer.contents = ['preambles', 'entries', 'comments']
106
```
107

108
### Indentation and Alignment
109

110
Configure spacing and alignment for readable output:
111

112
```python
113
# Custom indentation (default is single space)
114
writer.indent = '  '  # Two spaces
115
writer.indent = '\t'  # Tab character
116

117
# Align field values
118
writer.align_values = True  # Auto-calculate alignment width
119
writer.align_values = 20    # Fixed alignment width
120
writer.align_values = False # No alignment (default)
121

122
# Align multiline values
123
writer.align_multiline_values = True
124
```
125

126
### Entry Sorting
127

128
Control the order in which entries appear in the output:
129

130
```python
131
# Sort by entry ID (default)
132
writer.order_entries_by = ('ID',)
133

134
# Sort by multiple fields
135
writer.order_entries_by = ('ENTRYTYPE', 'author', 'year')
136

137
# Disable sorting (preserve original order)
138
writer.order_entries_by = None
139
```
140

141
### Field Ordering
142

143
Control the order of fields within each entry:
144

145
```python
146
from bibtexparser.bwriter import SortingStrategy
147

148
# Specify preferred field order
149
writer.display_order = ['title', 'author', 'journal', 'year']
150

151
# Configure how unlisted fields are sorted
152
writer.display_order_sorting = SortingStrategy.ALPHABETICAL_ASC  # Default
153
writer.display_order_sorting = SortingStrategy.ALPHABETICAL_DESC
154
writer.display_order_sorting = SortingStrategy.PRESERVE
155
```
156

157
### Syntax Style
158

159
Configure BibTeX syntax variations:
160

161
```python
162
# Comma-first syntax (common in functional languages)
163
writer.comma_first = True  # Default is False
164

165
# Add trailing comma after last field
166
writer.add_trailing_comma = True  # Default is False
167

168
# Entry separator (default is newline)
169
writer.entry_separator = '\n\n'  # Double newline
170
```
171

172
## Usage Examples
173

174
### Clean Academic Format
175

176
```python
177
from bibtexparser.bwriter import BibTexWriter, SortingStrategy
178

179
writer = BibTexWriter()
180
writer.indent = '  '
181
writer.align_values = True
182
writer.order_entries_by = ('ENTRYTYPE', 'year', 'author')
183
writer.display_order = ['title', 'author', 'journal', 'volume', 'pages', 'year']
184
writer.display_order_sorting = SortingStrategy.ALPHABETICAL_ASC
185

186
bibtex_str = writer.write(bib_database)
187
```
188

189
### Compact Format
190

191
```python
192
writer = BibTexWriter()
193
writer.indent = ''
194
writer.align_values = False
195
writer.entry_separator = '\n'
196
writer.contents = ['entries']  # Only entries, no comments/preambles
197

198
bibtex_str = writer.write(bib_database)
199
```
200

201
### Comma-First Style
202

203
```python
204
writer = BibTexWriter()
205
writer.comma_first = True
206
writer.add_trailing_comma = True
207
writer.indent = '  '
208

209
# Output format:
210
# @article{key
211
#   , title = {Example}
212
#   , author = {Author}
213
#   ,
214
# }
215
```
216

217
### Custom Field Processing
218

219
```python
220
from bibtexparser.bwriter import BibTexWriter
221

222
class CustomBibTexWriter(BibTexWriter):
223
    def _entry_to_bibtex(self, entry):
224
        # Override to add custom processing
225
        # Process entry before writing
226
        processed_entry = entry.copy()
227
        
228
        # Custom field transformations
229
        if 'doi' in processed_entry:
230
            processed_entry['doi'] = f"https://doi.org/{processed_entry['doi']}"
231
            
232
        return super()._entry_to_bibtex(processed_entry)
233

234
writer = CustomBibTexWriter()
235
```
236

237
### Complete Configuration Example
238

239
```python
240
from bibtexparser.bwriter import BibTexWriter, SortingStrategy
241

242
writer = BibTexWriter(write_common_strings=False)
243

244
# Content and structure
245
writer.contents = ['preambles', 'strings', 'entries', 'comments']
246
writer.entry_separator = '\n\n'
247

248
# Formatting
249
writer.indent = '    '  # 4 spaces
250
writer.align_values = 25
251
writer.align_multiline_values = True
252

253
# Entry ordering
254
writer.order_entries_by = ('ENTRYTYPE', 'year', 'author')
255

256
# Field ordering
257
writer.display_order = [
258
    'title', 'author', 'editor', 'journal', 'booktitle',
259
    'volume', 'number', 'pages', 'year', 'publisher', 'address'
260
]
261
writer.display_order_sorting = SortingStrategy.ALPHABETICAL_ASC
262

263
# Syntax style
264
writer.comma_first = False
265
writer.add_trailing_comma = True
266

267
# Generate formatted output
268
formatted_bibtex = writer.write(bib_database)
269

270
# Save to file with custom writer
271
with open('formatted_output.bib', 'w') as f:
272
    f.write(formatted_bibtex)
273
```
274

275
### Writer for Different Output Contexts
276

277
```python
278
# Configuration for journal submission
279
journal_writer = BibTexWriter()
280
journal_writer.indent = ' '
281
journal_writer.align_values = False
282
journal_writer.order_entries_by = ('author', 'year')
283
journal_writer.display_order = ['author', 'title', 'journal', 'volume', 'pages', 'year']
284

285
# Configuration for personal reference management
286
personal_writer = BibTexWriter()
287
personal_writer.indent = '  '
288
personal_writer.align_values = True
289
personal_writer.order_entries_by = ('year', 'author')
290
personal_writer.contents = ['entries']  # No comments for cleaner output
291
```