1# `bibel` - Bible Verse CLI/TUI Utility
  2
  3A Go utility for displaying Bible verses with interactive terminal interface.
  4This tool shows Bible verses based on the current date, displaying 12 verses
  5per day through the four Gospels.
  6
  7## Features
  8
  9- **Interactive TUI**: Terminal User Interface using `bubbletea` with styled
 10boxes
 11- **Date-Based Progression**: Automatically calculates position based on day of
 12year (1 January = Matthew 1:1-12)
 13- **Smart Sizing**: Default snippet size is 12 verses, extends to end of
 14chapter if less than 12 verses remain
 15- **Adaptive Styling**: Terminal-adaptive colours and borders using `lipgloss`
 16- **Interactive Controls**: Press `q` to quit (MOTD-like behaviour)
 17- **Yearly Cycle**: Progresses through all four Gospels each year, restarting
 18on 1 January
 19- **Multiple Output Modes**: Interactive TUI, formatted ANSI, or plain text
 20- **Verse Numbering**: Option to print each verse on a numbered line with verse
 21numbers
 22- **Paragraph Handling**: Option to render pilcrows (¶) in source JSON Bible
 23file as paragraph breaks with blank lines
 24- **Easter Progress Bar**: Fancy progress bar showing time until Easter with
 25visual progress indication (default: Eastern Orthodox; Catholic with `-l` flag)
 26
 27## Installation
 28
 29```bash
 30go build ./cmd/bibel.go
 31```
 32
 33## Usage
 34
 35```bash
 36./bibel
 37```
 38
 39By default, the verses the program picks are done by:
 401. Calculating today's date and day of year
 412. Determining Bible position: day of year * 12 verses
 423. Find corresponding verses in the Gospels
 43
 44### Usage Examples
 45
 46```bash
 47# Default TUI mode with interactive display (shows Orthodox Easter progress)
 48./bibel
 49
 50# Roman Catholic Easter progress bar instead of Orthodox
 51./bibel --latin
 52
 53# Plain text output
 54./bibel --plain
 55
 56# Formatted output with ANSI colours
 57./bibel --formatted
 58
 59# Numbered verses (each verse on its own line with verse number)
 60./bibel --numbered
 61
 62# Paragraph mode (pilcrows render as blank lines)
 63./bibel --paragraphs
 64
 65# Combine numbered and paragraph modes
 66./bibel --numbered --paragraphs
 67
 68# Plain output with numbered verses
 69./bibel --plain --numbered
 70
 71# Generate configuration file
 72./bibel --generate-config
 73```
 74
 75This is default behaviour. Alternative configurations are available (see
 76below).
 77
 78## Configuration
 79
 80`bibel` supports configuration via a TOML file located at
 81`$XDG_CONFIG_HOME/bibel/config.toml` (default: `~/.config/bibel/config.toml`).
 82Default macOS and Windows paths are also supported.
 83
 84### Configuration Options
 85
 86- **reading_mode**: Reading mode: "evangelion" (four Gospels; *default*),
 87"new_testament", "old_testament", "bible" (default: "evangelion")
 88- **output_mode**: Output mode: "tui" (interactive terminal UI), "formatted"
 89(ANSI-coloured text), or "plain" (plain text)
 90- **bible_path**: Path to Bible data file (default: "books/pol_nbg.json")
 91
 92#### TUI Settings (`[tui]` section)
 93- **show_quit_message**: Whether to show "Press q to quit..." message (default:
 94true)
 95- **border_style**: Box border style: "rounded", "double", "single", or
 96"hidden" (default: "rounded")
 97- **border_colour**: Box border colour (hex or named colour, empty for
 98adaptive)
 99- **header_colour**: Header text colour (empty for adaptive)
100- **text_colour**: Bible text colour (empty for adaptive)
101- **quit_colour**: Quit message colour (empty for adaptive)
102
103#### Formatter Settings (`[formatter]` section)
104- **use_colours**: Whether to use ANSI colours in formatted output (default:
105true)
106- **header_format**: Header format template with variables: {book}, {chapter},
107{first_verse}, {second_verse}
108- **numbered**: Whether to print each verse on a numbered line corresponding to
109the verse number (default: false)
110- **paragraphs**: Whether to render pilcrows (¶) as blank lines instead of
111ignoring them (default: false)
112
113#### Date Progression Settings (`[date_progression]` section)
114- **verses_per_day**: Number of verses to read per day (default: 12)
115- **start_date**: Start date for yearly progression (format: "1 January", empty
116for current year)
117
118#### Easter Settings
119- **easter_type**: Easter calculation type: "orthodox" (default) or "latin"
120
121### Example Configuration
122
123See `configs/config.example.toml` in the project directory for a complete example.
124
125### Generating Configuration
126
127Generate a default configuration file:
128
129```bash
130./bibel --generate-config
131```
132
133### Command Line Arguments
134
135Command line arguments override configuration file settings:
136
137- `-r, --reading`: "evangelion" (four Gospels; *default*), "new_testament",
138"old_testament", "bible" (default: "evangelion")
139- `-p, --plain`: Output plain text without formatting or TUI
140- `-f, --formatted`: Output formatted text with ANSI colours (no TUI)
141- `-g, --generate-config`: Generate a default configuration file and exit
142- `-c, --config`: Path to configuration file (not yet implemented)
143- `-n, --numbered`: Print each verse on a numbered line corresponding to the verse number
144- `-g, --paragraphs`: Render pilcrows (¶) as blank lines instead of ignoring them
145- `-l, --latin`: Use Roman Catholic Easter instead of Eastern Orthodox (shows in TUI progress bar)
146
147## Data Format
148
149The Bible data is in JSON format (see `books/pol_nbg.json`) with the following
150structure:
151```json
152{
153  "metadata": { ... },
154  "verses": [
155    {
156      "book_name": "Mateusza",
157      "book": 40,
158      "chapter": 1,
159      "verse": 1,
160      "text": "¶ KSIĘGA początku Jezusa Chrystusa..."
161    },
162    ...
163  ]
164}
165```
166
167Books 40-43 correspond to the four Gospels:
168- 40: Matthew (Mateusza)
169- 41: Mark (Marek)
170- 42: Luke (Łukasz)
171- 43: John (Jana)
172
173## Date-Based Algorithm
174
175The program calculates reading position as follows:
176
1771. **Day of Year**: Get current day number (1-366)
1782. **Verse Offset**: Multiply by 12 verses per day: `offset = (day_of_year - 1)
179   × 12`
1803. **Modulo Wrap**: Apply modulo with total Gospel verses (3779) to cycle
181   yearly
1824. **Position Mapping**: Walk through Gospels to find corresponding verses
1835. **Lookahead Rule**: Extend to chapter end if less than 12 verses remain
184
185## Easter Progress Bar
186
187The TUI features a progress bar showing time until the next Easter:
188
189### Easter Type Selection
190- **Default**: Eastern Orthodox Easter (calculated via Meeus Julian algorithm)
191- **Catholic**: Roman Catholic Easter via `-l/--latin` flag (Delambre and Butcher's algorithm)
192
193### Progress Bar Features
194- **Visual Progress**: Filled segments (█) showing annual cycle percentage between consecutive Easters
195- **Time Display**: Shows exact days, hours, and minutes until next Easter
196- **Styling**: Uses `lipgloss` with green-filled segments and adaptive terminal colours
197- **Configuration**: Easter type configurable via `easter_type` field in TOML configuration
198
199### Easter Calculations
200- **Orthodox Easter**: Uses Meeus Julian algorithm (accurate for years > 325)
201- **Catholic Easter**: Uses Delambre and Butcher's algorithm (Gregorian calendar)
202- **Annual Cycle Progress**: Calculated as time elapsed between consecutive Easters
203- **Real-time Updates**: Progress updates continuously while TUI is running
204
205## Project Structure
206
207```
208.
209├── cmd/bibel.go             # Main CLI entry point
210├── configs/                 # Default configuration files
211│   └── config.example.toml  # The default configuration file
212├── internal/
213│   ├── config.go            # Reading and writing to config
214│   ├── dateprogression.go   # Date-based position calculation
215│   ├── easterprogression.go # Easter date and progress calculation
216│   ├── verse.go             # Data structures
217│   ├── loader.go            # JSON loading and indexing
218│   ├── formatter.go         # Output formatting
219│   └── tui/                 # Terminal User Interface
220│       └── model.go         # bubbletea TUI model and styling
221├── pkg/
222│   └── eastertime.go        # Easter date calculation algorithms (Orthodox/Catholic)
223├── books/pol_nbg.json       # Bible data
224├── go.mod                   # Go module dependencies
225└── go.sum                   # Go dependency checksums
226```
227
228## Examples
229
230- **1 January**: Matthew 1:1-12
231- **2 January**: Matthew 1:13-25 (extends to end of chapter)
232- **16 April**: Mark 5:41-43
233- **31 December**: Matthew 18:7-18 (year wraps around)
234
235## Development
236
237```bash
238# Build
239go build ./cmd/bibel.go
240
241# Run
242./bibel
243```