sun

README

= sun
Bas Bossink <bas.bossink@gmail.com>
:toc:

Stand-Up Notebook (`sun` for short), is a very simple note taking command-line application to save you from drawing a blank during stand-up meetings.
The idea behind this application is to have a place to put short notes that are to short to track in a TODO list application but are still worth mentioning during the next stand-up meeting.

== Installation

=== From a GitHub release

Find the appropriate zip file for your platform and architecture on the GitHub https://github.com/basbossink/sun/releases[releases] page, download it, unzip it, and put the unpacked binary file in your `PATH`.

=== From sources

Installing sun from sources requires https://golang.org/[Go] to be installed. Once you have Go installed you can run:

[source,sh,subs="attributes+"]
----
go install github.com/basbossink/sun@{version}
----

== Usage 

=== Adding a note

When adding a note you write a short sentence describing something you might want to mention during the next stand-up meeting.

....
> sun Review PR from Alice @pr1234
....
[TIP]
Depending on the shell you are using the `@` character might mean something special to the shell, so if applicable use the correct escape character for your shell to prevent processing by your shell.

=== Viewing notes

....
> sun
 | Fri | 2021-11-19 | 11:29:04 | pr125 mca | review pr from Alice           |
 | --- | ---------- | -------- |           |                                |
 | Mon | 2021-11-15 | 15:02:55 | pr124     | ask Alice to review pr124      |
 | Mon | 2021-11-15 | 11:02:27 |           | discuss failing build with Bob |
....

sun outputs a table of as many entries there are until it sees a second day boundary in the time-stamps reading from the last added note.

That's it. There is nothing to configure/tweak, there aren't any interesting command-line options. You can use `sun -v` or `sun -version` to see the installed version.


== Storage

sun stores it's data in the `.sun.d` sub-directory of whatever is returned by the https://pkg.go.dev/os#UserHomeDir[os.UserHomeDir] function. The data files use the current year as their base-name and have a `.sun` file extension. To keep things simple no special care is given to year rollover apart from the fact that if no file exists for the current year, last year's file is read. Adding a note always creates a file for the current year if it does not exist yet.

== Internals 

Some care was taken to ensure sun can run in constant time. Entries are appended to the current years data file when writing, and read in reverse order from the end of the file. The file has a binary format, using a combination of https://pkg.go.dev/encoding/gob[encoding/gob] and https://pkg.go.dev/encoding/binary[encoding/binary]. This strategy was used for performance, currently sun can add and show notes in about 5ms on an old ThinkPad T440p laptop.

[svgbob]
....
 <~~~~ earlier part of file ~~+~~ gob encoded entry struct ~~+~~ binary encoded form of N ~~+      end of file
                              |                              |                              |           |
                              v                              v                              v           v
 <----------------------------+---+------------------+-------+---+------------------+-------+-----------+
             ...              | 0 |       ...        | N - 1 | 0 |       ...        | M - 1 | value of  |
                              |   |                  |       |   |                  |       | M as byte |
 <----------------------------+---+------------------+-------+---+------------------+-------+-----------+
                              ^                                                                         ^
                              |                                                                         |
                              +~~~~~~~~~~~~~~ block for each entry struct in the file ~~~~~~~~~~~~~~~~~~+
....

== License

This software is provided under a "BSD 2-Clause License" see the link:LICENSE[LICENSE] for details.