1# hascard 2[![Build Status](https://travis-ci.org/Yvee1/hascard.svg?branch=master)](https://travis-ci.org/Yvee1/hascard) [![GitHub tag](https://img.shields.io/github/tag/Yvee1/hascard.svg)](https://github.com/Yvee1/hascard/releases) [![AUR](https://img.shields.io/aur/version/hascard)](https://aur.archlinux.org/packages/hascard/) [![Hackage](https://img.shields.io/hackage/v/hascard.svg)](https://hackage.haskell.org/package/hascard) 3 4 5 6A minimal commandline utility for reviewing notes. 'Flashcards' can be written in markdown-like syntax. 7 8<p align="center"> 9<img alt="a recording of example usage of the hascard application" src="./recordings/recording.gif"> 10</p> 11 12## Contents 13- [Installation](#installation) 14- [Usage](#usage) 15- [Cards](#cards) 16 - [Definition](#definition) 17 - [Multiple choice](#multiple-choice) 18 - [Multiple answer](#multiple-answer) 19 - [Open question](#open-question) 20 - [Reorder question](#reorder-question) 21- [Miscellaneous info](#miscellaneous-info) 22 23## Installation 24Installation on Windows is not possible sadly, aside from WSL. This is because hascard depends on vty which only supports unix operating systems (this includes macOS). 25 26### Homebrew (for macOS) 27For macOS users an installation using homebrew is provided via a custom tap. You can run 28``` 29brew update 30brew install Yvee1/tools/hascard 31``` 32 33### Binary 34Ubuntu and macOS binaries are available under [releases](https://github.com/Yvee1/hascard/releases/). To be able to run it from any directory, it has to be added to the PATH. This can be done by copying it to e.g. the `/usr/local/bin` directory. 35 36### Arch Linux 37Thanks to [loki7990](https://github.com/loki7990), hascard is also on the AUR: https://aur.archlinux.org/packages/hascard/. 38 39### Snapcraft 40Hascard is also on [snapcraft](https://snapcraft.io/hascard). Installation instructions are on that site. If you already have snap installed you can just install hascard via `sudo snap install hascard`. By default snap applications are isolated from the system and run in a sandbox. This means that hascard does not have permission to read or write any files on the system aside from those under `%HOME/snap/hascard`. To be able to read cards also in other directories under the home directory, hascard makes use of the `home` interface which might need to be enabled manually using `sudo snap connect hascard:home :home`. 41 42**Note**: The installation with snapcraft does not work with all terminals, [known issues are with alacritty and st](https://github.com/Yvee1/hascard/issues/3), because of problems with terminfo that I do not know how to solve. With me, this did not happen with the other installation methods so try those if you have a somewhat non-standard terminal. If anyone knows what the problem might be, let me know! 43 44### Install from source 45Another option is to build hascard and install it from source. For this you can use the Haskell build tool called [stack](https://docs.haskellstack.org/en/stable/README/#how-to-install), or [nix](https://nixos.org/). Then for example clone this repository somewhere: 46``` 47git clone https://github.com/Yvee1/hascard.git 48cd hascard 49``` 50and do `stack install hascard` or `nix-build` respectively. 51 52## Usage 53Simply run `hascard` to open the main application. Menu navigation can be done with the arrow keys or with the 'j' and 'k' keys. The controls for the different cards can be found at the bottom of the screen by default. This, and a couple other things, can be changed in the settings menu. A deck of cards can be opened using the built-in filebrowser, and recently selected decks will appear in the selection menu. The application can also be run directly on a file by giving it as an argument. These decks of flashcards are written in plain text, this is explained in section [Cards](#cards). 54 55After finishing a deck, there is an option to create new decks from the correctly answered or incorrectly answered cards, or both. The correct cards of a file named `deck.txt` are stored in `deck+.txt` in the same folder, and the incorrect ones in the file `deck-.txt`. Make sure you do not have files of those names that you want to keep since these _will_ be overwritten. 56 57### CLI 58The CLI provides some options for running hascard; the most interesting are: 59``` 60 -a,--amount n Use the first n cards in the deck (most useful 61 combined with shuffle) 62 -c,--chunk i/n Split the deck into n chunks, and review the i'th 63 one. Counting starts at 1. 64 -s,--shuffle Randomize card order 65 ``` 66As an example, say you have a file `deck.txt` with lots of cards in it and you want to review 5 random ones, you can use `hascard deck -s -a 5`. Here `-s` shuffles the deck and `-a 5` specifies we only want to look at 5 of them. 67 68## Cards 69Decks of cards are written in `.txt` or `.md` files. Cards are seperated with a line containing three dashes `---`. For examples, see the [`/cards`](https://github.com/Yvee1/hascard/tree/master/cards) directory. In this section the 5 different types of cards are listed, with the syntax and how it is represented in the application. 70 71### Definition 72This is the simplest card, it simply has a title and can be flipped to show the contents. For example the following card 73``` 74# Word or question 75Explanation or definition of this word, or the answer to the question. 76``` 77will result in 78<p align="center"> 79 <img src="./recordings/definition.gif"></img> 80</p> 81 82### Multiple choice 83This is a typical multiple choice question. The question starts with a `#` and the choices follow. Only one answer is correct, and is indicated by a `*`, the other questions are preceded by a `-`. As an example, the following text 84 85``` 86# Multiple choice question, (only one answer is right) 87- Choice 1 88* Choice 2 (this is the correct answer) 89- Choice 3 90- Choice 4 91``` 92 93gets rendered as 94<p align="center"> 95 <img src="./recordings/multiple-choice.gif"></img> 96</p> 97 98### Multiple answer 99Multiple choice questions with multiple possible answers is also possible. Here again the question starts with `#` and the options follow. Preceding each option is a box `[ ]` that is filled with a `*` or a `x` if it is correct. For example 100 101``` 102# Multiple answer question 103[*] Option 1 (this is a correct answer) 104[ ] Option 2 105[*] Option 3 (this is a correct answer) 106[ ] Option 4 107``` 108results in 109<p align="center"> 110 <img src="./recordings/multiple-answer.gif"></img> 111</p> 112 113 114### Open question 115Open questions are also supported. The words that have to be filled in should be surrounded by underscores `_`. Underscores can also be escaped by `\_` if they are part of the text, like is done in [`cards/analysis3.txt`](https://github.com/Yvee1/hascard/blob/48b5c0751ac72df791402b88c033e05488c9350d/cards/analysis3.txt#L34-L37t). Multiple answer possibilities can also be given by seperating them with vertical bars `|`. As an example, the card 116 117``` 118# Fill in the gaps 119The symbol € is for the currency named _Euro_, and is used in the _EU|European Union_. 120``` 121behaves like this 122 123<p align="center"> 124 <img src="./recordings/gapped-question.gif"></img> 125</p> 126 127### Reorder question 128This is a question where you have to put the elements in the correct order. Each element is preceded by a number indicating their correct place. The elements are rendered in the same order as they are written. For example the card 129 130``` 131# Order the letters in alphabetical order 1324. u 1331. l 1342. p 1353. s 136``` 137will look like 138<p align="center"> 139 <img src="./recordings/reordering.gif"></img> 140</p> 141 142## Miscellaneous info 143Written in Haskell, UI built with [brick](https://github.com/jtdaugherty/brick) and parsing of cards done with [parsec](https://github.com/haskell/parsec). Recordings of the terminal were made using [terminalizer](https://github.com/faressoft/terminalizer). The filebrowser widget was mostly copied from the brick [filebrowser demo program](https://github.com/jtdaugherty/brick/blob/master/programs/FileBrowserDemo.hs). Homebrew and Travis configurations were made much easier by [the tutorial from Chris Penner](https://chrispenner.ca/posts/homebrew-haskell). 144