Emacs Monkeytype

A typing game/tutor inspired by the open source and community driven monkeytype.com but for Emacs.

Table of Contents

• Usage
• Features
  • To come… (PRs welcome)
  • Tips
• How is the WPM calculated?
• Commands
  • Key bindings
  • Description
    • monkeytype-pause
    • monkeytype-resume
    • monkeytype-stop
    • monkeytype-repeat
    • monkeytype-region
    • monkeytype-fortune
    • monkeytype-buffer
    • monkeytype-mistyped-words
    • monkeytype-hard-transitions
    • monkeytype-save-mistyped-words
    • monkeytype-save-hard-transitions
    • monkeytype-load-text-from-file
    • monkeytype-load-words-from-file
    • monkeytype-region-as-words
    • monkeytype-most-mistyped-words
    • monkeytype-save-text-from-url
    • monkeytype-wpm-peek
    • monkeytype-toggle-mode-line
• Directory Structure
• Customisation
  • Options
  • Faces
• Log
• Install
• Changelog
  • 0.1.5
  • 0.1.4
  • 0.1.3
  • 0.1.2
  • 0.1.1
  • 0.1.0
• License

Usage

Use one of the functions to enter monkeytype mode (monkeytype-region, monkeytype-buffer, etc… see Commands section below).

(Note: You should bind these functions to anything you want in your .emacs.)

Once started, you can either monkeytype-pause (C-c C-c p) or monkeytype-stop (C-c C-c s) to finish typing. On pause, the buffer should look as follows:

It renders a scrollable overlay with information about the run’s performance and a re-render of the typed text highlighting corrections, mistypes, etc.

The mode-line section also shows information about the previous run. The fields breakdown is:

MT[N-WPM/G-WPM Accuracy Elapsed-time (words/corrections/errors)]

Then you can monkeytype-resume (C-c C-c r) to continue typing and either type all the way to the end or monkeytype-stop (C-c C-C s) to finish.

The buffer should then look as follows:

This Results buffer re-renders the typed text highlighting errors and either correct or incorrect corrections (highlighted with a different background and slightly different colour).

At this point you can either practice mistyped words with monkeytype-mistyped-words (C-c C-c m) or just troubling/hard transitions with monkeytype-hard-transitions (C-c C-c h). You can also save them with monkeytype-save-mistyped-words or monkeytype-save-hard-transitions and later on type/practice the most mistyped words in history with monkeytype-most-mistyped-words.

Features

;; - Type any text you want
;; - Practice mistyped words
;; - Optional mode-line live WPM
;; - Pause/Resume/Stop/Save functionality
;; - Visual representation of typed text including errors and
;;   retries/corrections
;; - Auto stop after 5 seconds of no input
;; - Optionally randomise practice words/transitions
;; - Optionally downcase practice words/transitions
;; - Optionally treat newlines as whitespace
;; - Optionally text auto-fill
;; - Optionally delete trailing whitespace
;; - Select a region of text and treat it as words for practice
;; - After a test, practice troubling/hard key combinations/transitions
;; - Mistyped words or hard transitions can be saved
;; - Saved mistyped/transitions/text can be loaded for practice
;; - Ability to type most (saved) mistyped words
;; - Text for typing can be saved in the `monkeytype-directory' allowing
;;   you to resume later on (even after quitting Emacs).
;; - Download web pages directly to monkeytype-directory directory.

To come… (PRs welcome)

• [ ] Save results / history
• [ ] Mode to allow text/character helping commands (e.g., snippets, smartparens, etc. see: issue: #2)
• [ ] Improve results rendering logic mostly on large texts.

Tips

• When using evil-mode it’s useful to automatically enable evil-insert (to start typing right away).
• When using evil-escape, evil-escape-mode has to be disabled in order to prevent double keystrokes getting registered.
• Installing =centered-cursor-mode= is useful for auto scrolling/paging in multi-page / long texts.

This can then be enabled in your .emacs with:

(defun my/monkeytype-mode-hook ()
  "Hooks for monkeytype-mode."
  (centered-cursor-mode)
  (evil-escape-mode -1)
  (evil-insert -1))
(add-hook 'monkeytype-mode-hook #'my/monkeytype-mode-hook)

How is the WPM calculated?

See: https://www.speedtypingonline.com/typing-equations

Note: Retyping characters (even when correctly) negatively affects your accuracy given the total number of characters increases and the words calculation is simply the total amount of character divided by five. So typing accuracy is king!

Commands

Key bindings

Key binding	Function
C-c C-c f	monkeytype-fortune
C-c C-c p	monkeytype-pause
C-c C-c r	monkeytype-resume
C-c C-c s	monkeytype-stop
C-c C-c t	monkeytype-repeat
C-c C-c m	monkeytype-mistyped-words
C-c C-c h	monkeytype-hard-transitions
C-c C-c a	monkeytype-save-mistyped-words
C-c C-c o	monkeytype-save-hard-transitions
C-c C-c l	monkeytype-toggle-mode-line
C-c C-c e	monkeytype-wpm-peek
	monkeytype-region
	monkeytype-buffer
	monkeytype-most-mistyped-words
	monkeytype-region-as-words
	monkeytype-load-words-from-file
	monkeytype-load-text-from-file
	monkeytype-save-text-from-url

Description

monkeytype-pause

Pause current run.

On text-file based monkeytypings run results will be saved.

monkeytype-resume

Resume current run.

monkeytype-stop

Stop current run.

Stop means to completely finished a run (unless it is a text-file based run) so Monkeytype will show the processed typed text and the WPM results for all the run(s) (if the user paused multiple times) for the typed text.

monkeytype-repeat

Repeat run with same text.

monkeytype-region

Monkeytype region.

monkeytype-fortune

Monkeytype the output of the fortune command.

monkeytype-buffer

Monkeytype the entire current buffer.

monkeytype-mistyped-words

On current run, Monkeytype all mistyped words.

monkeytype-hard-transitions

On current run, Monkeytype all mistyped transitions.

monkeytype-save-mistyped-words

Save current run’s mistyped words in monkeytype-directory’s words directory.

These words will be used to get the most mistyped words (See: monkeytype-most-mistyped-words)

monkeytype-save-hard-transitions

Save current run’s hard-transitions in monkeytype-directory’s ~transitions~ directory.

monkeytype-load-text-from-file

This command prompts user to enter the text-file to use for monkeytyping.

By default it will look for text-files in the monkeytype-directory directory.

If the text-file has already been used for monkeytyping it will resume from the last position on the last run.

Notice: if the file is too big results can take a long while.

monkeytype-load-words-from-file

This command prompts user to enter the (mistyped)-words to use for monkeytyping.

By default it will look for (mistyped)-words in the monkeytype-directory directory.

monkeytype-region-as-words

This command will use the words in the current region and will treat it them as words for typing so it will also apply the configurable options for words to them. See: monkeytype-randomize, monkeytype-downcase, monkeytype-words-auto-fill and monkeytype-remove-trailing-whitespace.

monkeytype-most-mistyped-words

This command will load for monkeytyping the top number (defined in monkeytype-most-mistyped-amount and defaults to 100) of most mistyped words.

monkeytype-save-text-from-url

This command allows to save a web page to the monkeytype-directory/text/ directory, converting it to plain text (using pandoc(1)) and, if the monkeytype-asciify option is set to true, will ASCII character encode the text (using iconv(1)).

monkeytype-wpm-peek

This command allows to hide or show the WPM results overlay.

monkeytype-toggle-mode-line

This command allows to hide or show the WPM results in the the mode-line.

Directory Structure

Other than on text-file based typing commands, results are not saved - only mistyped words or hard-transitions.

text-file based commands read and write files from ~/.monkeytype/text/, monkeytype expects a text file in that text/ directory as the source text to build the text for typing and will store meta data in a directory named with the exact same name without the file’s extension. The sub-directories are: json, transitions and words. text-file based commands store and read files from these directories.

Example directory structure:

$ tree ~/.monkeytype/
.
+-- text
|   +-- sample-text
|   |   +-- json
|   |   |   +-- tue-08-dec-2020-12-21-56.json
|   |   |   +-- tue-08-dec-2020-12-30-32.json
|   |   |   +-- tue-08-dec-2020-12-34-00.json
|   |   +-- transitions
|   |   |   +-- tue-08-dec-2020-12-34-15.txt
|   |   +-- words
|   |       +-- tue-08-dec-2020-10-35-28.txt
|   |       +-- tue-08-dec-2020-12-05-17.txt
|   +-- sample-text.txt
+-- transitions
|   +-- sat-21-nov-2020-08-02-55.txt
|   +-- sat-21-nov-2020-08-06-39.txt
+-- words
    +-- mon-07-dec-2020-22-14-30.txt
    +-- wed-02-dec-2020-10-38-01.txt

Customisation

Run M-x customize-group RET monkeytype RET or monkeytype-faces RET.

Or set the variables in your .emacs file:

Options

(setq
  ;; How often to update mode-line
  monkeytype-mode-line-interval-update 10
  ;; Use space instead or newline
  monkeytype-treat-newline-as-space t
  ;; Minimum amount of transitions for test
  ;; If not enough repeat them
  monkeytype-minimum-transitions 50
  ;; Inserts debugging log, this can take a while
  ;; if typing text is too long.
  monkeytype-insert-log nil
  ;; Default directory for saving Monkeytype data
  monkeytype-directory "~/.monkeytype"
  ;; Format for time-stamped files for saving.
  monkeytype-file-name "%a-%d-%b-%Y-%H-%M-%S"
  ;; Toggle randomise text
  monkeytype-randomize t
  ;; Toggle downcase text
  monkeytype-dowcase t
  ;; Amount of words for most mistyped words test
  monkeytype-most-mistyped-amount 100
  ;; Toggle auto-fill on typing text
  monkeytype-auto-fill nil
  ;; Toggle auto-fill on words related typing text
  monkeytype-words-auto-fill t
  ;; Toggle auto deletion of trailing white space
  monkeytype-delete-trailing-whitespace t
  ;; Regexp used to divide and extracts words
  monkeytype-excluded-chars-regexp "[^[:alnum:]']"
  ;; Toggle converting downloaded text to ASCII
  monkeytype-asciify t)

Faces

(custom-set-faces
 ;; custom-set-faces was added by Custom.
 ;; If you edit it by hand, you could mess it up, so be careful.
 ;; Your init file should contain only one such instance.
 ;; If there is more than one, they won't work right.
 '(monkeytype-default ((t (:inherit default :height 1.7 :width normal))))
 '(monkeytype-dimmed (...))
 '(monkeytype-notice (...))
 '(monkeytype-correct (...))
 '(monkeytype-error (...))
 '(monkeytype-correction-error (...))
 '(monkeytype-correction-correct (...))
 '(monkeytype-read-only (...))
 '(monkeytype-title (...))
 '(monkeytype-legend-1 (...))
 '(monkeytype-legend-2 (...))
 '(monkeytype-results-success (...))
 '(monkeytype-results-error (...))
 '(monkeytype-mode-line-success (...))
 '(monkeytype-mode-line-error (...))
 '(monkeytype-mode-line-normal (...))
 '(monkeytype-mode-line-info (...)))

Log

Logging can be enabled for debugging purposes (see monkeytype-insert-log customisation).

When enabled it should look as follows:

Install

From MELPA, M-x package-install RET monkeytype RET.

Or just drop monkeytype.el somewhere in your load-path and add it to your .emacs:

(add-to-list 'load-path "~/emacs.d/vendor")
(require 'monkeytype)

Changelog

0.1.5

Additions

• monkeytype-wpm-peek
• monketype-toggle-mode-line
• monkeytype-save-text-from-url
• Display results and typed text on pause
• Allow to toggle colour and non-colour mode-line

Changes

• Remove monkeytype-dummy-text

Internal

• Improve logic for getting previous runs entries
• Refactor monkeytype--init / rename function just monkeytype
• Add Travis CI integration

Fixes

• Word/Char count should include retypes

0.1.4

Additions

• monkeytype-load-text-from-file
• Disable already paused typed section (previous runs) from being able to retype it
• Add monkeytype-file-name-format custom var

Changes

• Rename monkeytype-word-regexp monkeytype-excluded-chars-regexp
• Remove face from faces (monkeytype-face- => monkeytype-)
• Process results asynchronously

Internal

• map and async lib requirements
• Several face related improvements
• Remove monkeytype--counter-entries

Fixes

• Simplify time idler
• Several code refactorings and reorganisation

0.1.3

Additions

• Available on MELPA
• monkeytype-most-mistyped-words
• Toggable option monkeytype-words-auto-fill
• Toggable option monkeytype-delete-trailing-whitespace

Changes -

Internal

• Init text processing rewrite

Fixes

• Fix for misindexing of chars to words

0.1.2

Additions

• monkeytype-load-words-from-file
• monkeytype-region-as-words
• Toggable option monkeytype-downcase
• Toggable option monkeytype-randomize
• monkeytype-word-regexp

Changes

• Rename option monkeytype-downcase-mistype to monkeytype-downcase
• Removed async lib

Internal

• Input processing logic rewrite
• Several renames and code reorganisation

Fixes

• Skipped text getting counters out of sync
• evil-escape double registering characters

0.1.1

Additions

• Allow to practice mistyped words.
• Allow to practice hard to type transitions.
• Allow to save mistyped words or transitions to ~/.monkeytype directory.
• Option to auto-fill typing region.

Changes

• Change monkeytype--mode-line-update-seconds option to monkeytype-mode-line>interval-update to have it work with typed entries (keystrokes) defaulting to 1 (update on each keystroke).

Internal

• Removed ht library requirement.
• Updated Emacs requirement to 25.1.
• Misc layout improvements.

Fixes

• Have local-idle-timer stop on paused or finished status.

0.1.0

Initial release.

License

GPLv3