path: root/README.md

# Soon

Soon is a minimalist, text file based, CLI calendar inspired by [When](https://www.lightandmatter.com/when/when.html). It has simple, concise syntax but supports recurring cases more complex than most calendars.

- Schedule events in a text file
- Concise syntax for recurring cases and date ranges
- Group, sort, comment, and columnize events to keep files neat
- Add multiple lines of details to events
- Archive events to remove them from your schedule (e.g. paid bill)
- Optionally keep events on calendar until dismissed (e.g. missed oil change)
- Todo list with upcoming deadlines
- Fun

In terms of features and complexity, Soon lies between [When](https://www.lightandmatter.com/when/when.html) and [Remind](https://dianne.skoll.ca/projects/remind/) but aims to be less verbose than either.

# Arguments

```
Usage: soon [options]

Options:
-a                 print agenda (default behavior if no options)
-c                 print reference calendar
-t                 print todos
-e                 open default calendar file in $EDITOR
-i                 open TUI in interactive mode to schedule/archive events
-w, -m, -y         print agenda for upcoming week, month, or year
-j                 print the modified julian day
-d                 print today's date
-p, --past=DAYS    days in past to print agenda (default: 1)
-f, --future=DAYS  days in future to print agenda (default: 14)
-h, --help         show this help
-v, --version      print version

Combine commands to get output in a certain order.
`soon -ca` prints a calendar followed by an agenda.
`soon -at` prints an agenda followed by todos.

Check the docs at https://codeberg.org/historia/soon
```

# .soon file syntax

```
# COMMENT
DATE, EVENT
- DETAILS
```

- Lines beginning with `#` are comments used to annotate or group events together.
- Lines beginning with `-` are additional details attached to the above event.
- Blank lines are ignored.

Otherwise, a line is an event. Everything before the first comma is interpreted as the date, which is a list of conditions separated by whitespace. Parameters can be written in any order. Short or long month and weekday names can be used.

## Example Syntax

```
# Common dates and recurrence

2025 Jul 17,  Hike Mt. Fuji
Jan 1,        New Year's Day  (Jan 1 every year)
Tue,          Taco night      (Every Tuesday)
1,            Mortgage due    (1st of every month)
,             Journal         (Every day)

# Times

2025 Jan 1 00:00-03:00,  Work party
2025 Jan 1 04:00,        Go to bed
20:00 Fri,               Friday Night Magic  (Every Friday at 8pm)
9am,                     Coffee              (Every day at 9am)

# Logic and Date Ranges

Mon Wed Fri,                Submit TPS Report (Every Mon, Wed, or Fri)
Fri !13,                    Every Friday except the 13th
July 7-13 2024,             Shark Week
(Jun 25 2025)-(Jul 4 2025), Japan Trip

# Uncommon recurrence patterns

J%3,    Every third day
Fri 1W, First Friday of the month

# Combine multiple features for complex recurrence

Jul 10-19 2025 J%3-2, This event repeats July 10, 13, 16, 19
```

## Adding details to events

Any line starting with a `+` is attached to the nearest above event. This can be used for details about an event if you don't want to put everything on one line.

```
2025 Jan 5 16:00, Doctor's Appointment
+ 123 Gentoo Road, San Francisco, CA 12345
+ Dr. Elias Berkins, +1 (555)-123-1234
```

## Date Groups

You can put a day, month, and optionally year in parentheses to treat it as a single date. This lets you use the date for ranges and with the `!` operator like you'd expect.

```
Sun !(Dec 25),               Every Sunday except Dec 25. The ! does NOT expand to !Dec !25.
(June 25 2025)-(Sep 1 2025), Summer vacation
(Jun 25)-(Sep 1) 2025,       Alternative summer vacation
```

## Ranges (`-`)

You can specify ranges with a dash for days, weekdays, months, years, and date groups.

```
Mon-Fri,                    Work every weekday
Jan 1-7 2025,               Las Vegas convention
(Jan 30 2025)-(Feb 3 2025), Ski trip
(Dec 25)-(Jan 2),           Christmas vacation every year
```

You can omit one end of a date range to mean before or after a certain date.

```
Fri -(Sep 12 2025),  Every Friday before (and including) Sep 12 2025
Fri (Sep 12 2025)-,  Every Friday after (and including) Sep 12 2025
```

## Logic (AND, OR, NOT)

The date string is a list of conditions. Each condition of a different type (day, month, etc.) has to met for days the event takes place.

If multiple conditions of the same type exist, any of them can be satisfied.

Prepend any condition with `!` to mean NOT.

```
Fri Jan,        Friday AND January (Every Fri in Jan)
1 15,           1st OR 15th
Fri !13,        Friday, NOT the 13th
Sun !(Dec 25),  Sunday, NOT December 25
2025 Aug 14,    2025 AND August AND the 14th
Sat Sun Aug,    Saturday OR Sundays, in August
```

## First/last week(s) of Month (`W`, `L`)

xW is the xth set of 7 days of a month\
xL is the xth-from-last set of 7 days of a month

This is mostly useful for certain holidays and is analogous to the 'a' and 'b' parameters in When.

```
May 2W Sun,   Mother's Day (Second Sunday of May)
May 1L Mon,   Memorial Day (Last Monday of May)
1W Fri,       First Friday (of every month)
```

## Time

You can express times in 24h format or AM/PM format like this. Your agenda will be sorted by the start time of events.

```
Fri 06:00,    With no am/pm, 24h time is assumed
Fri 12:00am,  Midnight
Fri 12pm,     Noon

# You can include ranges if you'd like
Fri 05:00-06:00,  Breakfast
Fri 12pm-1pm,     Lunch
```

## Modified Julian Day (`J%x+y`) - Repeat every N days

Soon supports using a Modified Julian Day as `J`. `J` is the number of full days since midnight November 17, 1858. This can be used along with the modulo operator `%` to create complex recurring events.

This condition returns **true** when the result is 0. This is the opposite of how When works! You are almost always hunting zeros with this function so it makes no sense to invert it every time.

```
J%3,       Every third day
J%14-5,    Every other Saturday
J%14+2,    Every other Saturday (on the other weeks)
Sat J%2,   Every other Saturday expressed in a different way

# You can use it for recurring reminders too
Jul 10-19 2025 J%3-2, This event repeats July 10, 13, 16, 19
```

Julian date modulus is definitely weird, but it's a concise way to express multiple uncommon recurring patterns without increasing program complexity and syntax vocabulary for features I virtually never use. Plus it's an homage to [When](https://www.lightandmatter.com/when/when.html), and I love When.

### Footnote for astronomers and time nerds

The actual MJD is based on UTC, so Soon technically uses a *rounded*, modified Julian Day because it counts days since 1858-11-17 in your local time zone. This doesn't matter in practice. It's just a number that goes up by 1 every day.

Soon's MJD is off by 1 from When. When starts counting from JD 1 while Soon more correctly starts counting from JD 0.

# Archive File

You can archive events in interactive mode with `soon i`. This lets you archive an event like "Pay rent" early so you know it's done.

- For recurring events with no end date, only the individual instance is archived.
- For events with one date, the event is removed from your calendar file.
- For events with an end date, it will only be removed from your calendar file if all occurences are archived.

`showPastArchivedEvents` and `showFutureArchivedEvents` determine if archived events are hidden from your agenda entirely or show up as (Archived).

## Keep events on calendar until manually archived

In soon.config, set `alwaysShowUnarchivedEvents=true` and old events will stick on your calendar until archived (regardless of the `past` setting). This means you will have to manually acknowledge every event. 

Soon checks for events starting from `startDate` so you don't get recurring events showing up from the 1970s. Basically, everything before this date is considered archived.

# Todo List

Lines in .soon files that start with `-` will show up on the todo list.

Lines starting with `+` are attached to the todo above it, similar to events.

If you add a line with `+ Due:` followed by a date, it will show up separately from your events in a list of upcoming deadlines.

```
- Wash car
- Clean room
- Give book back to Sally
  + Address: 555 Oak Street, Openville

- Finish TPS report
  + Due: Aug 7 2025
```

If you delete an event in interactive mode, it will be deleted from the .soon file.

# Why would I use this?

Soon was created as alternative to [When](https://www.lightandmatter.com/when/when.html) with nicer syntax and a few extra todo/scheduling features. It's for a small niche of people who mainly edit their schedule directly in a text file rather than a TUI. This group almost exclusively uses [Remind](https://dianne.skoll.ca/projects/remind/) or [Org Mode](https://orgmode.org).

Soon has a few benefits over similar text file calendars:

1. Soon has the most concise syntax. It minimizes special characters and simplifies ranges.

    **Soon**: `Jul 1-7 2025, Vacation!`\
    **When**: `m=Jul & d>=1 & d<=7 & y=2025, Vacation!`\
    **Remind**: `REM Jul 1 2025 THROUGH Jul 7 2025 MSG Vacation!`

2. Soon can archive instances of events early

Take the event "Pay quarterly bill", scheduled every 3 months. If I do that a week early, I can archive it so it's gone from my calendar. This won't affect other upcoming instances.

3. Soon can keep events around until you archive them

By setting `alwaysShowUnarchivedEvents=true`, Soon will keep every event on your calendar until you archive it. This mimics the behavior I used to have of keeping calendar reminders in my email inbox until they were done.

4. Soon can show a todo list and upcoming deadlines.

# Alternatives

- [When](https://www.lightandmatter.com/when/when.html) - The simplest text file calendar that's flexible enough for real world use.
- [Remind](https://dianne.skoll.ca/projects/remind/) - The most powerful, programmable calendar program ever made
    - [Better overview here.](https://blog.thechases.com/posts/remind/)
- [Org Mode](https://orgmode.org) - Expansive text file based productivity system but an endless time sink for tinkerers.

You might also be interested in these which are text based but have somewhat different workflows: [khal](https://github.com/pimutils/khal), [calcure](https://github.com/anufrievroman/calcure), [Calcurse](https://calcurse.org/), [Taskwarrior](https://taskwarrior.org/), [calendar.vim](https://github.com/itchyny/calendar.vim), [Emacs Diary](https://www.gnu.org/software/emacs/manual/html_node/emacs/Format-of-Diary-File.html), [Plain Text Personal Organizer](https://danlucraft.com/blog/2008/04/plain-text-organizer/), [Calendar.txt](https://terokarvinen.com/2021/calendar-txt/)

# Todo

- Todos
- Todos with deadlines
- TUI
- Calendar output
- Color
- Julian modulus calculator (`soon -j Jun 5 2025` > Outputs J and a table of common mod offsets)
- CalDAV/.ics export? - Numerous CLI programs store calendars with .ics files directly, so it doesn't make much sense to use Soon if you need to sync to a "main" calendar.
- Import?

# License

MIT