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
 25## Installation
 26
 27```bash
 28go build ./cmd/bibel.go
 29```
 30
 31## Usage
 32
 33```bash
 34./bibel
 35```
 36
 37By default, the verses the program picks are done by:
 381. Calculating today's date and day of year
 392. Determining Bible position: day of year * 12 verses
 403. Find corresponding verses in the Gospels
 41
 42### Usage Examples
 43
 44```bash
 45# Default TUI mode with interactive display
 46./bibel
 47
 48# Plain text output
 49./bibel --plain
 50
 51# Formatted output with ANSI colours
 52./bibel --formatted
 53
 54# Numbered verses (each verse on its own line with verse number)
 55./bibel --numbered
 56
 57# Paragraph mode (pilcrows render as blank lines)
 58./bibel --paragraphs
 59
 60# Combine numbered and paragraph modes
 61./bibel --numbered --paragraphs
 62
 63# Plain output with numbered verses
 64./bibel --plain --numbered
 65
 66# Generate configuration file
 67./bibel --generate-config
 68```
 69
 70This is default behaviour. Alternative configurations are available (see
 71below).
 72
 73## Configuration
 74
 75`bibel` supports configuration via a TOML file located at
 76`$XDG_CONFIG_HOME/bibel/config.toml` (default: `~/.config/bibel/config.toml`).
 77Default macOS and Windows paths are also supported.
 78
 79### Configuration Options
 80
 81- **reading_mode**: Reading mode: "evangelion" (four Gospels; *default*),
 82"new_testament", "old_testament", "bible" (default: "evangelion")
 83- **output_mode**: Output mode: "tui" (interactive terminal UI), "formatted"
 84(ANSI-coloured text), or "plain" (plain text)
 85- **bible_path**: Path to Bible data file (default: "books/pol_nbg.json")
 86
 87#### TUI Settings (`[tui]` section)
 88- **show_quit_message**: Whether to show "Press q to quit..." message (default:
 89true)
 90- **border_style**: Box border style: "rounded", "double", "single", or
 91"hidden" (default: "rounded")
 92- **border_colour**: Box border colour (hex or named colour, empty for
 93adaptive)
 94- **header_colour**: Header text colour (empty for adaptive)
 95- **text_colour**: Bible text colour (empty for adaptive)
 96- **quit_colour**: Quit message colour (empty for adaptive)
 97
 98#### Formatter Settings (`[formatter]` section)
 99- **use_colours**: Whether to use ANSI colours in formatted output (default:
100true)
101- **header_format**: Header format template with variables: {book}, {chapter},
102{first_verse}, {second_verse}
103- **numbered**: Whether to print each verse on a numbered line corresponding to
104the verse number (default: false)
105- **paragraphs**: Whether to render pilcrows (¶) as blank lines instead of
106ignoring them (default: false)
107
108#### Date Progression Settings (`[date_progression]` section)
109- **verses_per_day**: Number of verses to read per day (default: 12)
110- **start_date**: Start date for yearly progression (format: "1 January", empty
111for current year)
112
113### Example Configuration
114
115See `configs/config.example.toml` in the project directory for a complete example.
116
117### Generating Configuration
118
119Generate a default configuration file:
120
121```bash
122./bibel --generate-config
123```
124
125### Command Line Arguments
126
127Command line arguments override configuration file settings:
128
129- `-r, --reading`: "evangelion" (four Gospels; *default*), "new_testament",
130"old_testament", "bible" (default: "evangelion")
131- `-p, --plain`: Output plain text without formatting or TUI
132- `-f, --formatted`: Output formatted text with ANSI colours (no TUI)
133- `-g, --generate-config`: Generate a default configuration file and exit
134- `-c, --config`: Path to configuration file (not yet implemented)
135- `-n, --numbered`: Print each verse on a numbered line corresponding to the verse number
136- `-g, --paragraphs`: Render pilcrows (¶) as blank lines instead of ignoring them
137
138## Data Format
139
140The Bible data is in JSON format (see `books/pol_nbg.json`) with the following
141structure:
142```json
143{
144  "metadata": { ... },
145  "verses": [
146    {
147      "book_name": "Mateusza",
148      "book": 40,
149      "chapter": 1,
150      "verse": 1,
151      "text": "¶ KSIĘGA początku Jezusa Chrystusa..."
152    },
153    ...
154  ]
155}
156```
157
158Books 40-43 correspond to the four Gospels:
159- 40: Matthew (Mateusza)
160- 41: Mark (Marek)
161- 42: Luke (Łukasz)
162- 43: John (Jana)
163
164## Date-Based Algorithm
165
166The program calculates reading position as follows:
167
1681. **Day of Year**: Get current day number (1-366)
1692. **Verse Offset**: Multiply by 12 verses per day: `offset = (day_of_year - 1)
170   × 12`
1713. **Modulo Wrap**: Apply modulo with total Gospel verses (3779) to cycle
172   yearly
1734. **Position Mapping**: Walk through Gospels to find corresponding verses
1745. **Lookahead Rule**: Extend to chapter end if less than 12 verses remain
175
176## Project Structure
177
178```
179.
180├── cmd/bibel.go             # Main CLI entry point
181├── configs/                 # Default configuration files
182│   └── config.example.toml  # The default configuration file
183├── internal/
184│   ├── config.go            # Reading and writing to config
185│   ├── dateprogression.go   # Date-based position calculation
186│   ├── verse.go             # Data structures
187│   ├── loader.go            # JSON loading and indexing
188│   ├── formatter.go         # Output formatting
189│   └── tui/                 # Terminal User Interface
190│       └── model.go         # bubbletea TUI model and styling
191├── books/pol_nbg.json       # Bible data
192├── go.mod                   # Go module dependencies
193└── go.sum                   # Go dependency checksums
194```
195
196## Examples
197
198- **1 January**: Matthew 1:1-12
199- **2 January**: Matthew 1:13-25 (extends to end of chapter)
200- **16 April**: Mark 5:41-43
201- **31 December**: Matthew 18:7-18 (year wraps around)
202
203## Development
204
205```bash
206# Build
207go build ./cmd/bibel.go
208
209# Run
210./bibel
211```