rodo/README.md

295 lines
9.2 KiB
Markdown
Raw Normal View History

2018-03-12 14:00:41 +00:00
# rodo
2021-03-09 23:32:52 +00:00
A todo-list program for the command line.
2019-07-11 02:21:54 +00:00
2021-02-25 00:21:16 +00:00
## Screenshot
2020-09-27 03:52:24 +00:00
2020-10-01 02:37:55 +00:00
![A screenshot of a user adding an removing items from their todo list in a terminal](images/screenshot.gif)
2020-09-27 03:52:24 +00:00
## Table of contents
<!-- vim-markdown-toc GFM -->
* [Disclaimer](#disclaimer)
* [Conventions used in this document](#conventions-used-in-this-document)
* [Platforms](#platforms)
* [Requirements](#requirements)
* [Quick start](#quick-start)
* [Downloading rodo](#downloading-rodo)
* [Downloading rodo using git](#downloading-rodo-using-git)
* [To download rodo using git](#to-download-rodo-using-git)
* [Installing rodo](#installing-rodo)
* [Installing rodo globally](#installing-rodo-globally)
* [To install rodo globally](#to-install-rodo-globally)
* [Installing rodo locally](#installing-rodo-locally)
* [To install rodo locally](#to-install-rodo-locally)
* [Installing rodo to a custom directory](#installing-rodo-to-a-custom-directory)
* [To install rodo to a custom directory](#to-install-rodo-to-a-custom-directory)
* [Uninstalling rodo](#uninstalling-rodo)
* [Uninstalling rodo globally](#uninstalling-rodo-globally)
* [To uninstall rodo globally](#to-uninstall-rodo-globally)
* [Uninstalling rodo locally](#uninstalling-rodo-locally)
* [To uninstall rodo locally](#to-uninstall-rodo-locally)
* [Using rodo](#using-rodo)
* [Initializing rodo](#initializing-rodo)
* [To initialize rodo](#to-initialize-rodo)
* [Showing the help message](#showing-the-help-message)
* [To show the help message](#to-show-the-help-message)
* [Displaying your list](#displaying-your-list)
* [To display your list](#to-display-your-list)
* [Adding an item to your list](#adding-an-item-to-your-list)
* [To add an item to your list](#to-add-an-item-to-your-list)
* [Removing an item from your list](#removing-an-item-from-your-list)
* [To remove an item from your list](#to-remove-an-item-from-your-list)
* [Changing the text of an item in your list](#changing-the-text-of-an-item-in-your-list)
* [To change the text of an item in your list](#to-change-the-text-of-an-item-in-your-list)
* [List of commands](#list-of-commands)
* [Usage examples](#usage-examples)
<!-- vim-markdown-toc -->
2019-04-30 01:35:44 +00:00
2021-02-25 00:21:16 +00:00
## Disclaimer
2020-06-06 23:25:51 +00:00
This is a hobby project I built for myself to keep track of todos
related to my hobbies.
2020-03-29 19:49:23 +00:00
2020-06-06 23:25:51 +00:00
I take no responsibility for anything that rodo deletes.
Backup anything you don't want deleted.
2019-11-11 19:00:50 +00:00
2021-02-25 00:21:16 +00:00
## Conventions used in this document
2019-11-11 19:00:50 +00:00
2020-05-09 20:08:02 +00:00
* **Note**: Notes signify additional information
2020-08-15 15:21:14 +00:00
* **Tip**: Tips signify an alternative procedure for completing a step
* **Warning**: Warnings signify that damage, such as data loss, may occur
2020-08-15 15:23:21 +00:00
* **Example**: Examples provide a reference of how a procedure would be performed in the real world
2020-05-09 20:08:02 +00:00
* `Inline code`: Inline code signifies package names, filenames, or commands
* ```Code block```: Code blocks signify file contents
2019-11-11 19:00:50 +00:00
2021-02-25 00:21:16 +00:00
## Platforms
2018-05-20 02:03:00 +00:00
2019-11-11 19:00:50 +00:00
Below is a list of platforms that rodo can run on:
2019-02-14 20:09:47 +00:00
* GNU/Linux
2020-06-06 23:25:51 +00:00
* Windows (Using Windows Subsystem for Linux)
* macOS (Using [Homebrew](https://brew.sh/))
2018-09-08 01:01:00 +00:00
2021-02-25 00:21:16 +00:00
## Requirements
2020-01-16 17:54:49 +00:00
The following items must be downloaded and installed before you can use rodo:
2018-09-08 01:01:00 +00:00
* Racket: [https://racket-lang.org/](https://racket-lang.org/)
* rodo's source code: [https://git.m455.casa/m455/rodo](https://git.m455.casa/m455/rodo)
2019-04-30 01:35:44 +00:00
2021-02-25 00:21:16 +00:00
## Quick start
2020-06-06 23:25:51 +00:00
This section is for users who are familiar with git, a Unix-like command line environment, or
scripting.
1. Make sure [Racket](https://racket-lang.org/) is installed
2020-10-01 02:34:21 +00:00
2. `git clone https://git.m455.casa/m455/rodo.git`
2020-06-06 23:25:51 +00:00
3. `cd rodo`
4. `sudo make install-global`
5. `rodo`
2020-06-06 23:25:51 +00:00
**Note**: To uninstall, run `sudo make uninstall-global`
2018-10-20 01:36:52 +00:00
2020-06-06 23:25:51 +00:00
* `rodo help` - Displays the help message
* `rodo add "your task here"` - Adds the message inside of quotation marks to your todo list
* `rodo ls` - Displays your todo list
* `rodo rm 2` - Removes the third item from your list. (The list starts at 0)
2020-06-06 23:25:51 +00:00
**Note**: You may need to run `rodo ls` to see which number corresponds to which item in your list before running `rodo rm <number>`
2019-01-31 14:46:14 +00:00
2021-02-25 00:21:16 +00:00
## Downloading rodo
2019-11-11 19:00:50 +00:00
2020-06-06 23:25:51 +00:00
rodo'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.
2019-11-11 19:00:50 +00:00
2021-02-25 00:21:16 +00:00
### Downloading rodo using git
2020-06-06 23:25:51 +00:00
You can use tools such as `git` to download rodo's source code. You
will need the source code to install rodo.
2021-02-25 00:21:16 +00:00
#### To download rodo using git
2019-01-31 14:46:14 +00:00
2020-10-01 02:34:21 +00:00
1. Run `git clone https://git.m455.casa/m455/rodo.git`
2019-01-31 14:46:14 +00:00
2020-06-06 23:25:51 +00:00
**Note**: This will create a `rodo` directory in your current directory.
2020-03-27 00:20:01 +00:00
2021-02-25 00:21:16 +00:00
## Installing rodo
2020-03-27 00:20:01 +00:00
2020-06-06 23:25:51 +00:00
You can either install rodo globally or locally on your system. A global installation allows all users on a machine to use rodo, while a local installation only allows one user to use rodo.
See the options below for installing rodo:
* [Installing rodo globally](#installing-rodo-globally)
* [Installing rodo locally](#installing-rodo-locally)
2020-07-07 15:45:05 +00:00
* [Installing rodo to a custom directory](#installing-rodo-to-a-custom-directory)
2020-06-06 23:25:51 +00:00
2021-02-25 00:21:16 +00:00
### Installing rodo globally
2020-06-06 23:25:51 +00:00
This option will install rodo into `/usr/local/bin/`.
This section assumes you have [downloaded rodo](#downloading-rodo).
2021-02-25 00:21:16 +00:00
#### To install rodo globally
2020-06-06 23:25:51 +00:00
1. Run `cd rodo`
2. Run `sudo make install-global`
2021-02-25 00:21:16 +00:00
### Installing rodo locally
2020-06-06 23:25:51 +00:00
This option will install rodo into `~/.local/bin/`.
This section assumes you have [downloaded rodo](#downloading-rodo).
2021-02-25 00:21:16 +00:00
#### To install rodo locally
2020-06-06 23:25:51 +00:00
1. Run `cd rodo`
2. Run `sudo make install-local`
2021-02-25 00:21:16 +00:00
### Installing rodo to a custom directory
2020-06-06 23:25:51 +00:00
If you wish to have rodo exist elsewhere on your system, you can also
2021-03-12 13:28:57 +00:00
compile a single-file executable. Compiling a single-file executable
2020-06-06 23:25:51 +00:00
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 rodo](#downloading-rodo).
2021-02-25 00:21:16 +00:00
#### To install rodo to a custom directory
2020-06-06 23:25:51 +00:00
**Warning**: You will have to manually uninstall custom installations
2020-06-06 23:25:51 +00:00
1. Run `cd rodo`
2020-07-11 22:52:03 +00:00
2. Run `make install-custom location=~/path/to/custom/location`
**Example**: In step 2., you could run `make install-custom location=~/bin/`
2020-06-06 23:25:51 +00:00
2021-02-25 00:21:16 +00:00
## Uninstalling rodo
2020-03-27 00:20:01 +00:00
2020-06-06 23:25:51 +00:00
Depending on your installation method, you can uninstall a global or local installation of rodo.
2020-03-27 00:20:01 +00:00
2020-06-06 23:25:51 +00:00
See the options below for uninstalling rodo:
2019-11-11 19:00:50 +00:00
2020-06-06 23:25:51 +00:00
* [Uninstalling rodo globally](#uninstalling-rodo-globally)
* [Uninstalling rodo locally](#uninstalling-rodo-locally)
2019-11-11 19:00:50 +00:00
2021-02-25 00:21:16 +00:00
### Uninstalling rodo globally
2019-01-31 14:46:14 +00:00
2020-06-06 23:25:51 +00:00
This option will remove the `rodo` executable from `/usr/local/bin/`.
2020-03-22 03:16:56 +00:00
2020-06-06 23:25:51 +00:00
This section assumes you have [downloaded rodo](#downloading-rodo).
2020-03-22 03:16:56 +00:00
2021-02-25 00:21:16 +00:00
#### To uninstall rodo globally
2020-03-22 03:16:56 +00:00
2020-06-06 23:25:51 +00:00
1. Run `cd rodo`
2. Run `sudo make uninstall-global`
2019-01-31 14:46:14 +00:00
2021-02-25 00:21:16 +00:00
### Uninstalling rodo locally
2018-11-12 02:56:10 +00:00
2020-06-06 23:25:51 +00:00
This option will remove the `rodo` executable from `~/.local/bin/`.
2019-11-11 19:00:50 +00:00
2020-06-06 23:25:51 +00:00
This section assumes you have [downloaded rodo](#downloading-rodo).
2019-11-11 19:00:50 +00:00
2021-02-25 00:21:16 +00:00
#### To uninstall rodo locally
2019-11-11 19:00:50 +00:00
2020-06-06 23:25:51 +00:00
1. Run `cd rodo`
2. Run `sudo make uninstall-local`
2019-11-11 19:00:50 +00:00
2021-02-25 00:21:16 +00:00
## Using rodo
2020-01-06 21:05:52 +00:00
2020-03-15 03:27:48 +00:00
This section will teach you how to use rodo's commands.
2020-03-15 03:24:25 +00:00
2020-06-06 23:25:51 +00:00
This section assumes you have [installed rodo](#installing-rodo).
2020-01-06 21:05:52 +00:00
2021-02-25 00:21:16 +00:00
### Initializing rodo
2020-07-23 03:35:15 +00:00
Before using rodo, you will need to initialize it. This means rodo will create a `~/.rodo` file.
2021-02-25 00:21:16 +00:00
#### To initialize rodo
1. Run `rodo init`
2. Choose `y`
2021-02-25 00:21:16 +00:00
### Showing the help message
2020-01-06 21:05:52 +00:00
2020-03-22 03:16:56 +00:00
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.
2020-01-06 21:05:52 +00:00
2021-02-25 00:21:16 +00:00
#### To show the help message
2020-01-06 21:05:52 +00:00
1. Run `rodo help`
2020-01-06 21:05:52 +00:00
2021-02-25 00:21:16 +00:00
### Displaying your list
2020-01-06 21:05:52 +00:00
2020-07-23 03:38:55 +00:00
Displaying your list will allow you to view the items you have added to your list.
2020-03-15 03:27:48 +00:00
You will notice numbers beside the items in your list.
**Note**: These numbers are useful references for when you want to remove items from your list. For
more information, see the [Removing an Item from Your List](#removing-an-item-from-your-list) topic.
2020-01-06 21:05:52 +00:00
2021-02-25 00:21:16 +00:00
#### To display your list
2020-01-06 21:05:52 +00:00
1. Run `rodo ls`
2021-02-25 00:21:16 +00:00
### Adding an item to your list
2020-01-06 21:05:52 +00:00
Adding an item to your list will save it to a text file to access later.
2021-02-25 00:21:16 +00:00
#### To add an item to your list
2020-01-06 21:05:52 +00:00
1. Run `rodo add "this is an example of an item using double quotation marks"`
2021-02-25 00:21:16 +00:00
### Removing an item from your list
2020-01-06 21:05:52 +00:00
2020-09-25 21:28:00 +00:00
When removing an item from your list, you can reference the numbers beside each item when
[Displaying Your List](#displaying-your-list). You can use these numbers when removing an item from
your list.
2020-01-06 21:05:52 +00:00
2021-02-25 00:21:16 +00:00
#### To remove an item from your list
2020-01-06 21:05:52 +00:00
1. Run `rodo rm 1`
**Note 2**: You may need to run `rodo ls` first to see which numbers correspond
with which item in your list.
### Changing the text of an item in your list
When changing an item in your list, you can reference the numbers beside each
item when [Displaying your list](#displaying-your-list).
#### To change the text of an item in your list
1. Run `rodo update 2 "This is new text"`
2020-01-06 21:05:52 +00:00
2020-05-09 20:08:02 +00:00
**Note 2**: You may need to run `rodo ls` first to see which numbers correspond
2020-01-06 21:05:52 +00:00
with which item in your list.
2021-02-25 00:21:16 +00:00
## List of commands
This section lists and describes rodo's commands.
2018-04-10 00:27:01 +00:00
2020-07-23 03:47:25 +00:00
* `init` intializes the `~/.rodo` file
* `help` displays the help message
* `ls` displays your list
* `add` adds an item to your list
* `rm` removes an item from your list
* `update` replaces the contents of an item with new text
2018-04-13 06:14:51 +00:00
2021-02-25 00:21:16 +00:00
## Usage examples
2018-04-10 00:27:01 +00:00
2020-07-23 03:47:25 +00:00
`rodo init`
`rodo help`
2019-03-13 03:43:15 +00:00
`rodo ls`
2018-09-08 04:30:28 +00:00
`rodo add "this is an item"`
2018-09-08 04:30:28 +00:00
2019-11-11 19:00:50 +00:00
`rodo rm 1`
`rodo update 1 "This is new text"`