ToRRential Card processor

• INTRODUCTION
• INSTALLATION
  • PIP
  • MANUAL_INSTALLATION
• USAGE
• CONFIG_FILE
• LOCATIONS
• OPTIONS
• FAQ
• CHANGELOG
• CONTRIBUTION

INTRODUCTION

ToRRential Card processor(trrc) is a command-line unix-like program to create anki cards using AnkiConnect plugin.(Think a yt-dlp, but this program is for adding cards into Anki.)

I intent to make it as a Unix-like program. Therefore it leverages a lot of Unix concepts.

• It supports a standard input, PIPE, redirection. Therefore, you can add bulk cards after mangling your cards with your favorite text editors. With the benefit of unix-like program, you can make a convenient script yourself with your favorite text editors like Vim, Emacs, VScode and so on. See Usage

• It has shell completions(Zsh, Bash).

• It adds multiple cards at once using --file or PIPE and so on. See Usage

• It also supports options for ip, port and apikey. So even some environments you don't want to install Anki, you can add cards if your Anki is running in your home or somewhere, boundlessly.

• It also supports a rc(config) file with a alias to reuse options you uses frequently.

• you can sync Anki with option --sync of trrc with or without soon after adding cards.

• It's user-friendly. In well-known cases, trrc provides solutions. If you mistake deck name, it will print all deck name available. If your field is wrong, it will print field of the card type used.

# default card type is 'Basic'
$trrc --field 'fron:bakc:tags' 'What is GPL?	The GNU General Public License is a free, copyleft license for software and other kinds of works.	LICENSE::GPL'
#### Kinds of failures: 1
trrc Tip: --field 'Front:Back:Tags'

You don't have to use all those fields.
For example, if all field of a type is 'Front:Back:Source:Sound:Tags',
you can use only some of them. e.g.: 'Front:Back:Tags'.
####
Total cards: 1 Total fails: 1

See Youtube demonstration video of the author

if you decide to use this app, I highly recommend to turn apikey option in your AnkiConnect to prevent malicious attack. (It's not a fault of this app nor AnkiConnect. If the port of AnkiConnect opens without an apikey, anybody can modify your anki deck.) See also AnkiConnect Configure

INSTALLATION

pip

pip install trrc

Manual installation

pip install -r requirements.txt

pip install .

Install AnkiConnect addon in Anki.

USAGE

To solve common mistakes, I wrote a lot of examples.

Standard Input

# the blank characters except a spacebar in 'Korean Conversation' is a tab.
# the default IFS is a tab.
trrc '안녕	Hello	Korean Conversation'
          # ^         ^
          #tab character

# -F is --IFS. It sets a Internal Field Separator. Mobile devices may not
#support a tab character in their keyboard. In that case, you should use --IFS
#options. (e.g.:-F@)
trrc "back\ttestfront\tvim" -F '\t'

# you can set whatever character you want.
trrc --IFS % '안녕%Hello%Korean'
trrc -F @ '안녕@Hello@Korean'

# you can choose only part of the fields of the card type.
# you can change order of the fields.
trrc --field 'Arbitrary4thField:Arbitrary2ndFieldName:tags' 'FourthContent\tsecondContent\ttag'

# to send your card to other computer(e.g.: ip is 192.168.1.230, port is 4832).
trrc --ip 192.168.1.230 --port 4832 --file Korean_English_conversation.txt

# To use '\t' as a tab character in an standard input argument, you need to use '$' in front of the string.

trrc $'안녕\tHello\tKorean'
      ^

See also How to use '\t' in a card content?

PIPE

To use PIPE, put - in the argument.

echo 'basic_type_front_normal_tab with option	basic_type_back	basic_type_tag' | trrc -

# bash: \t
echo -e 'basic_type_front_normal_tab with option\tbasic_type_back\tbasic_type_tag' | trrc - -t 'Basic (and reversed card)' --field 'Front:Back:tag'

# bash: using a tab
echo 'basic_type_front_normal_tab with option	basic_type_back	basic_type_tag' | trrc - -t 'Basic (and reversed card)' --field 'Front:Back:tag'

# zsh: \t
echo 'basic_type_front_normal_tab with option\tbasic_type_back\tbasic_type_tag' | trrc - -t 'Basic (and reversed card)' --field 'Front:Back:tag'

# bash: using a tab
echo 'basic_type_front_normal_tab with option	basic_type_back	basic_type_tag' | trrc - -t 'Basic (and reversed card)' --field 'Front:Back:tag'

# zsh: using a tab
echo 'basic_type_front_normal_tab with option	basic_type_back	basic_type_tag' | trrc - -t 'Basic (and reversed card)' --field 'Front:Back:tag'

PIPE with cat

example_file_IFS_default.txt

If you use ' '(a tab) as a IFS like a below,

#example_file_IFS_deafult.txt
front	back	test
front2	back	test

then you don't have to use --IFS option.

cat example_file_IFS_deafult.txt | trrc -

example_file_IFS_backslash_t.txt

If you use '\t' as a IFS like a below,

#example_file_IFS_backslash_t.txt
front\tback\ttest
front2\tback\ttest

then use a command like this.

cat example_file_IFS_backslash_t.txt | trrc - --IFS '\t'

HEREDOC Standard Input

trrc --IFS '\t' - <<EOF
front	back	test
front2	back	test
EOF

HEREDOC PIPE

cat <<EOF | trrc - --IFS '\t'
front	back	test
front2	back	test
EOF

Config File

trrc's config file extension is .trrc.

See LOCATIONS and How to create a trrc config file

Locations

By default, trrc searches for rc(config) files in directories of the below. It means if you wrote the config file(only .trrc, without any file name.) there, trrc import the setting in the files if they exists in order.

macOS, Linux:

• ${HOME}/.trrc # e.g. : ~/.trrc

• ./.trrc # working directory.

Locations: macOS e.g.

• /Users/username/.trrc

• If you are in /Users/username/study/english/, then also, /Users/username/study/english/.trrc

Locations: Linux e.g.

• /home/username/.trrc

• If you are in /home/username/study/english/, then also, /home/username/study/english/.trrc

Options

usage: trrc [-h] [-D DECK] [-t CARDTYPE] [-i IP] [-p PORT] [-f [FILE ...]]
            [-c FILE] [--alias SECTION] [-F IFS]
            [--field COLON:DELIMITER-SEPARATED:FIELDS]
            [--cloze-field COLON:DELIMITER-SEPARATED:FIELDS]
            [--cloze-type CLOZE_TYPE] [--toml-generate] [--toml-write FILE]
            [--toml-section SECTION] [-H] [--apikey APIKEY] [--sync]
            [--force-add] [--dry-run] [--read-file-in-a-content] [-v]
            [--debug [FILE]] [-V]
            [cardContents ...]

A command-line program to create Anki cards using AnkiConnect API.

positional arguments:
  cardContents          a string divided by IFS. the default IFS is a tab
                        character. instead of a string, It can also take a
                        file consists of strings without '--FILE' option.

options:
  -h, --help            show this help message and exit
  -D DECK, --deck DECK  set a Deck. the default is 'default'.
  -t CARDTYPE, --type CARDTYPE
                        set a card type. the default is 'Basic'.
  -i IP, --ip IP        set a ip that AnkiConnect specified. the default is
                        '127.0.0.1'.
  -p PORT, --port PORT  set a port number that AnkiConnect specified. the
                        default is '8765'.
  -f [FILE ...], --file [FILE ...]
                        set a file that contains card contents.
  -c FILE, --config FILE
                        set a config file to import config options. without
                        this option, this program searches '~/.trrc'.
  --alias SECTION       set a section of a config file to apply options.
                        without this argument, the default is 'default'.
  -F IFS, --IFS IFS     set a delimiter of card contents to use any character
                        other than a tab character. the default is a tab
                        character.
  --field COLON:DELIMITER-SEPARATED:FIELDS
                        set a card field corresponding to the cardContents.
                        the default is 'Front:Back:Tags'.
  --cloze-field COLON:DELIMITER-SEPARATED:FIELDS
                        set a cloze type card field corresponding to the
                        cardContents. The default is 'Text:Back Extra:Tags'.
  --cloze-type CLOZE_TYPE
                        set a type of a fallback for a cloze type. the default
                        is 'cloze'. if user set --field option, then the
                        default won't work. even a string contains cloze, the
                        program will process as a field unless user set
                        --cloze-type
  --toml-generate       print toml configs with current arguments. to set a
                        section of it, use it with '--toml-section' option.
  --toml-write FILE     write a config file with options used. to set a
                        section, use '--toml-section'.
  --toml-section SECTION
                        set a toml section. the default is 'untitled'.
  -H, --render-HTML     set to allow to render a HTML tag. the default doesn't
                        allow render a HTML tag, therefore <br> won't be a new
                        line.
  --apikey APIKEY       set an api key for AnkiConnect. if it is specified,
                        --debug options will mask it because of security
                        concern.
  --sync                sync Anki. if there is a card to process, trrc syncs
                        after adding the card. the default i