You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

13 KiB

fa

A command-line agenda written in Fennel.

Screenshot

A screenshot of a user adding and removing agenda items in a terminal

Table of Contents

About this document

This document assumes you have basic command line skills in a Unix-like environment.

Disclaimer

This is a hobby project I built for myself to keep track of friends' and family members' birthdays, appointments, etc.

As mentioned in the AGPL3, I take no responsibility, and am not liable for anything that fa deletes.

Backup anything you don't want deleted.

Conventions used in this document

  • Note: Notes signify additional information.
  • Tip: Tips signify an alternative procedure for completing a step.
  • Warning: Warnings signify that damage, such as data loss, may occur.
  • Example: Examples provide a reference of how a procedure would be performed in the real world.
  • inline code and code blocks: signifies package names, filenames, file contents, or commands.

Platforms

Below is a list of platforms that fa can run on:

  • Linux
    • Debian 10 (Tested)
    • Alpine Linux (Tested)
  • Windows (Untested)
  • Windows Subsystem for Linux (Tested)
  • macOS (Untested)

Requirements

  • Fennel - To compile a fa.lua script.
  • Lua5.3 - To compile a fa binary or run the fa.lua script.

Downloading fa

Before using fa, you will need to download fa. This section will guide you through downloading the fa.lua script, the fa binary, the fa source code.

This section consists of the following sections:

Downloading the fa script

The fa script is a Lua file you can move around your system or place in a directory on you $PATH. This allows you to use fa from anywhere on your system.

To download the fa script

  1. Run curl https://git.m455.casa/m455/fa/raw/branch/main/dists/fa.lua -o fa && chmod u+x fa

Note: You can move the fa script anywhere on your system or move it into a directory on your $PATH, such as /usr/local/bin.

Downloading the fa binary

The fa binary is a file you can move around your system or place in a directory on your $PATH. This allows you to use fa from anywhere on your system.

To download the fa binary

  1. Run curl https://git.m455.casa/m455/fa/raw/branch/main/dists/fa-bin -o fa && chmod u+x fa

Note: You can move the fa binary anywhere on your system or move it into a directory on your $PATH, such as /usr/local/bin.

Downloading the fa source code

The fa source code can be downloaded for people who want to compile from source. This method also makes installation easier, if you want to run fa from anywhere on your system.

To download the fa source code

  1. git clone https://git.m455.casa/m455/fa.git

Compiling from source

This section will guide you through using the Makefile to compile the fa source code into a Lua script called fa.lua or a binary called fa.

Before continuing, ensure you have all of the requirements.

This section consists of the following sections:

Compiling fa into a Lua script

This method will create a dists/fa.lua script.

To compile fa into a Lua script

  1. make compile-lua

Compiling fa into a binary

This method will create a dists/fa binary.

To compile fa into a binary

  1. make compile-bin

Installing fa

You can install the fa script or the fa binary included in the dists directory in this repository.

This section consists of the following sections:

Note: This section assumes you have downloaded the fa source code.

Installing the fa script

You can install the fa script using the make command. This will allow you to run fa from anywhere on your system.

To install the fa script

  1. sudo make install-lua

Installing the fa binary

You can install the fa binary using the make command. This will allow you to run fa from anywhere on your system.

To install the fa binary

  1. sudo make install-bin

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

Displaying events from a specific date

fa allows you to only list events from a specific date. This removes the need to parse long agendas.

To display events on a specific date

  1. Run fa ls mmdd

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

Example: fa ls 0112.

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.
  • rm <mmdd|today> [<n>] - Removes the given date from your agenda.
  • ls [<mmdd|today>] - The same as the notify command, but the event text will be displayed, instead of a "!".
  • ls - Displays a list of dates and their events from your agenda.
  • notify - Returns a "!" if there is an event today.
  • version - Prints the current version of fa.

Usage examples

  • fa init
  • fa add 1231 "Sherry's birthday"
  • fa add today "Sherry's birthday"
  • fa rm 1231
  • fa rm 1231 3
  • fa rm today
  • fa rm today 3
  • fa ls today
  • fa ls 1231
  • fa ls
  • fa notify
  • fa version

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).

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 > "
    
  2. Open a new terminal.

Here's what it looks like:

A screenshot of a bash prompt with an exclamation mark to signify that an event is happening on the current date

Contributions

This section provides information related to contributions.

This section consists of the following sections:

How we collaborate

So far, to keep things portable, we avoid using a centralized wiki or issues system, and aim to discuss the project in Markdown files, IRC, or by email.

For patches, git-send-email can be used, which is sometimes available as a git-email package on other systems.

Another way to create patches is by using the git show HEAD > patch.txt command, and then sending the patch.txt file (or whatever you named it) over email, IRC, etc.

Collaboration files

Contributors