No Description

Jesse Laprade e2544ac472 Added built executable 6 days ago
images 518214779b Added the new gif! 1 week ago
src 0e58d7d9c9 Moved makefile to current directory 6 days ago
LICENSE 8abe70562a Initial commit 3 weeks ago
Makefile 0e58d7d9c9 Moved makefile to current directory 6 days ago
README.md 518214779b Added the new gif! 1 week ago
fa e2544ac472 Added built executable 6 days ago

README.md

fa

A command-line agenda written in Fennel.

I wrote this because I spent quite a lot of time on the command line, and don't always think to open Thunderbird to check my calendar.

Screenshot

An animated GIF of a user adding and removing dates on the command line

Table of Contents

Requirements

Note: The fa executable may work on Lua5.1, and Lua5.2, but I haven't tested those versions with this yet.

Quick start

  1. Ensure Lua5.3 is installed
  2. git clone https://notabug.org/m455/fa
  3. cd fa
  4. ./fa help

Note: You can move the fa executable to a directory on your $PATH, such as /usr/local/bin, ~/.local/bin, or ~/bin. This allows your to run the fa command from anywhere on your system.

Downloading fa

fa's source code exists in a public git repository. This makes accessing the code convenient, because you don't need to sign in or register for an account to download it.

Downloading fa using git

You can use tools such as git to download fa's source code, which also contains a fa executable that you can move around your system.

To download fa using git

  1. Run git clone https://notabug.org/m455/fa

Note: This will create a fa directory in your current directory.

Installing fa

You can either install fa globally or locally on your system. A global installation allows all users on a machine to use fa, while a local installation only allows one user to use fa.

See the options below for installing fa:

Installing fa globally

This option will install fa into /usr/local/bin/.

This section assumes you have downloaded fa.

To install fa globally

  1. Run cd fa
  2. Run sudo make install-global

Installing fa locally

This option will install fa into ~/.local/bin/.

This section assumes you have downloaded fa.

To install fa locally

  1. Run cd fa
  2. Run sudo make install-local

Installing fa to a custom directory

If you wish to have fa exist elsewhere on your system, you can also build a single-file executable. Building a single-file executable allows you to place the executable in convenient places on your system, such as a directory on your $PATH.

This section assumes you have downloaded fa.

To install fa to a custom directory

Warning: You will have to manually uninstall custom installations

  1. Run cd fa
  2. Run make install-custom location=~/path/to/custom/location

Example: In step 2., you could run make install-custom location=~/bin/

Uninstalling fa

Depending on your installation method, you can uninstall a global or local installation of fa.

See the options below for uninstalling fa:

Uninstalling fa globally

This option will remove the fa executable from /usr/local/bin/.

This section assumes you have downloaded fa.

To uninstall fa globally

  1. Run cd fa
  2. Run sudo make uninstall-global

Uninstalling fa locally

This option will remove the fa executable from ~/.local/bin/.

This section assumes you have downloaded fa.

To uninstall fa locally

  1. Run cd fa
  2. Run sudo make uninstall-local

Compiling fa from source

This section describes how you can use Fennel to compile fa from a Fennel script into a Lua script. This is useful because the Lua script will run faster than the Fennel script.

Accessing the source

Fennel's source code can be found in the src/ directory after you have downloaded fa.

To access the source

  1. Run cd src

Building the source

Inside of the src directory you cded into in the previous section, there is a Makefile, which allows you to easily build from source.

To build from source

  1. Run make build

Note: This will create a portable Lua executable called fa that you can move around your system, or place in a directory on your $PATH.

Using fa

This section will teach you how to use fa's commands.

This section assumes you have installed fa.

Initializing fa

Before using fa, you will need to initialize it. This means fa will create a ~/.fa file.

To initialize fa

  1. Run fa init

Showing the help message

The help message will provide a list of available commands. This is list useful in case you forget the name of a command or how to use a command.

To show the help message

  1. Run fa help

Displaying your agenda

Displaying your agenda will allow you to view the dates you have added to your agenda.

Note: These dates are useful references for when you want to remove dates from your agenda. For more information, see the Removing a date from your agenda topic.

To display your agenda

  1. Run fa ls

Adding a date to your agenda

Adding a date to your agenda will save it to a text file to access later.

To add a date to your agenda

  1. Run fa add mmdd "Your event text here"

Where mm is two numbers representing a month and dd is two numbers representing a day.

Example: fa add 0112 "Some event on January the 12th"

To add the current date to your agenda

  1. Run fa add today "Your event text here"

Removing a date from your agenda

When removing a date from your agenda, you can reference the date numbers beside each agenda item when displaying your agenda. You can use these numbers when removing a date from your agenda.

To remove a date from your agenda

  1. Run fa rm mmdd

Where mm is two numbers representing a month and dd is two numbers representing a day.

Example: fa rm 0112

To remove the current date from your agenda

  1. Run fa rm today

Note: You may need to run fa ls first to see which numbers correspond with which date in your agenda.

Removing an event from your agenda

Each date contains a list of events. These events can be removed individually. This removes the need to recreate a date with multiple events when you only need remove one event.

To remove an event from your agenda

  1. Run fa rm mmdd n

Where mm is two numbers representing a month, dd is two numbers representing a day, and n is a number that correlates to an event.

Example: fa rm 1231 3

Note: You may need to run fa ls first to see which numbers correspond with which event in your agenda.

To remove an event on the current date from your agenda

  1. Run fa rm today n

Where n is a number that correlates to an event.

Note: You may need to run fa ls first to see which numbers correspond with which event in your agenda.

Example: fa rm today 3

List of commands

This section lists and describes fa's commands.

  • init - Creates your agenda.
  • add <mmdd|today> "Quoted text" - Adds an event to your agenda.
  • ls - Displays a list of dates and their events from your agenda.
  • notify - Checks if the current date matches a date in your agenda, and if it matches, then a "!" will be displayed.
  • today - The same as the notify command, but the event text will be displayed, instead of a "!".
  • rm <mmdd|today> [<n>] - Removes the given date from your agenda.

Usage examples

fa init

fa add 1231 "Sherry's birthday"

fa add today "Sherry's birthday"

fa ls

fa notify

fa today

fa rm 1231

fa rm 1231 3

fa rm today

fa rm today 3

Adding fa notifications to your tools

The fa notify command was intended to be placed in status bars or shell prompts.

The fa notify command will output a ! without a trailing newline character (\n).

Some examples of software that support this behaviour are:

  • tmux's status bar
  • i3's status bar
  • bash prompt
  • zsh's prompt
  • and many more

Adding notifications to your Bash prompt

This section provides an example of how you could add the fa notify command in a Bash prompt to check if the current date matches any of the dates in your agenda.

Note: This section assumes you have a fa executable in a directory on your $PATH.

To add notifications to your Bash prompt

  1. Add the following contents to your ~/.bashrc:
event () {
  fa notify | awk '{ print " " $1 }'
}

yellow="\[\e[1;33m\]"
reset="\[\e[0;39m\]"

export PS1="\w$yellow\$(event)$reset > "
  1. Open a new terminal.

How fa notifications look

The image below is an example of how the event notification looks if you followed the .bashrc example above.

A screenshot of a yellow exclamation displaying in someone's terminal