lexdrill 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ee9e8bd1de6b7fc437375184394a0ce42d61d9648320e6a31e83bf575cfc885
-  data.tar.gz: 27836a51638dbd08eb53a1d6f6808d94a0fb27c8e4b93cd831e96c2f5b0abe64
+  metadata.gz: 694f430036d22f39f5ee347a6220a8e977e726edb54db9f5c99d3f57bfcb8161
+  data.tar.gz: 9deb40864be7ded7ed8eb1aff88e25e20a412acf0a678526ff5d3f84f50ad69b
 SHA512:
-  metadata.gz: cb860ea6fb40050205abbbdc2078d1a3e5b4f624629bb1b769a33c7bd1de3e22452d65265017cd0e7597bde5d934b04c568e96ab8f2643678392dfe86a8e2dc6
-  data.tar.gz: edbe4b9f27ced36534b9f3816840feb9216728288077af785292b12015d765db0c96170a0f8f79dc9182926323b3404517abd237ff51b47747901fb4e93632a7
+  metadata.gz: 49b05b7ac7dda95a4fd9c34b9de6fbe29486e8a8e84285d8fbb0fe0a211785a9a7870551c3a80566725d4884dee317117c85781a313251c9094fa927a4ff857c
+  data.tar.gz: 201a4d5c23a232a4cbb1ca5b2d294e629a9984e1196133511d62262e3c8ae3c238386278735f91d184db4b7214578304861caa70b641c6f0b77988cc2f4ef00f

data/README.md

@@ -1,6 +1,7 @@
 # lexdrill
 
-lexdrill prints a vocabulary word or phrase on demand, tracking how often each one has been shown.
+The `lexdrill` gem installs a `drill` command that prints a vocabulary word or
+phrase on demand, tracking how often each one has been shown.
 
 ## Installation
 
@@ -8,7 +9,7 @@ lexdrill prints a vocabulary word or phrase on demand, tracking how often each o
 gem install lexdrill
 ```
 
-### `lexdrill: command not found` after install?
+### `drill: command not found` after install?
 
 This happens when the gem's executable directory isn't on your `PATH` — common with a
 plain system Ruby (no rbenv/rvm). Fix it in one step:
@@ -27,3 +28,82 @@ source ~/.zshrc
 
 Using an rbenv-managed Ruby? Run `rbenv rehash` instead. Using rvm? You shouldn't hit
 this — rvm keeps gem executable directories on `PATH` automatically.
+
+## Usage
+
+Create a `.drill.txt` file — one word or phrase per line — in your home directory,
+or in a specific project directory to give that project its own list:
+
+```
+apple
+banana
+cherry
+```
+
+Run `drill next` to print the current word and advance to the next one. Each
+line is printed as `current/total:` followed by a tab and the word, in a
+randomly-picked color, e.g.:
+
+```
+1/3:	apple
+2/3:	banana
+3/3:	cherry
+1/3:	apple
+```
+
+### Shell integration (one-time setup)
+
+Add one line to your shell's rc file so the current word prints automatically
+before each prompt. This is a **one-time step** — the line stays in your rc file
+and takes effect in every new shell session from then on; you never need to run it
+again by hand.
+
+Add it near the **end** of the file, after anything that sets up your `PATH`
+(rvm/rbenv init, Homebrew, etc.) — otherwise the shell may not know where
+`drill` lives yet when this line runs. Guarding it with `command -v` also
+means it never errors, even on a machine/session where `drill` isn't on
+`PATH` for some reason.
+
+**zsh** — add to `~/.zshrc`:
+```zsh
+if command -v drill >/dev/null 2>&1; then
+  eval "$(drill hook zsh)"
+fi
+```
+
+**bash** — add to `~/.bashrc`:
+```bash
+if command -v drill >/dev/null 2>&1; then
+  eval "$(drill hook bash)"
+fi
+```
+
+Then open a new shell (or `source ~/.zshrc` / `source ~/.bashrc`) to pick it up.
+
+#### Hook not firing in new terminal windows/tabs (rvm users)?
+
+Run `drill inspect` first — if it shows `Toggle: enabled` and a valid words
+file, the tool itself is fine and the problem is that the hook function never
+got registered in that session.
+
+A common cause with rvm: rvm's installer sometimes puts its actual
+PATH-loading line (`[[ -s "$HOME/.rvm/scripts/rvm" ]] && source
+"$HOME/.rvm/scripts/rvm"`) in `~/.zlogin` (zsh) or `~/.bash_profile` (bash).
+Those files only run for **login shells** — but many terminal emulators
+(e.g. kitty) open new windows/tabs as **non-login** interactive shells, which
+only source `~/.zshrc`/`~/.bashrc`. So rvm's gemset `bin/` directory (where
+`drill` lives) never makes it onto `PATH` in those sessions, even though
+everything looks correctly configured.
+
+**Fix:** move that line into `~/.zshrc` / `~/.bashrc` (before the `drill`
+hook block above, so it runs first) instead of relying on it only being in
+`~/.zlogin` / `~/.bash_profile`. It's safe to leave it in both places.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `drill next` | Print the current word and advance |
+| `drill start` / `drill stop` | Pause/resume the automatic per-prompt hook (doesn't affect manual `next`) |
+| `drill inspect` | Show the active `.drill.txt`/`.drill.counter` paths, word count, counter value, and toggle state |
+| `drill hook zsh\|bash` | Print the shell integration snippet (used above) |

data/lexdrill.gemspec

@@ -23,6 +23,6 @@ Gem::Specification.new do |spec|
     Dir["lib/**/*.rb"] + Dir["bin/*"] + %w[README.md LICENSE.txt lexdrill.gemspec Gemfile]
   end
   spec.bindir = "bin"
-  spec.executables = ["lexdrill"]
+  spec.executables = ["drill"]
   spec.require_paths = ["lib"]
 end

data/lib/lexdrill/cli.rb

@@ -4,7 +4,11 @@ class Lexdrill::CLI
   COMMANDS = {
     print_version: %w[version --version -v],
     print_help: %w[help --help -h],
-    run_next: %w[next]
+    run_next: %w[next],
+    run_hook: %w[hook],
+    run_start: %w[start],
+    run_stop: %w[stop],
+    run_inspect: %w[inspect]
   }.freeze
 
   def self.start(argv = ARGV)
@@ -34,12 +38,16 @@ class Lexdrill::CLI
 
   def print_help
     puts <<~HELP
-      lexdrill #{Lexdrill::VERSION} — vocabulary drilling in your terminal
+      drill #{Lexdrill::VERSION} — vocabulary drilling in your terminal
 
       Usage:
-        lexdrill version   Print the gem version
-        lexdrill help      Show this help
-        lexdrill next      Print the current word and advance
+        drill version   Print the gem version
+        drill help      Show this help
+        drill next      Print the current word and advance
+        drill hook <zsh|bash>   Print the shell integration snippet
+        drill start     Resume drilling (undoes stop)
+        drill stop      Pause drilling everywhere until `start`
+        drill inspect   Show the active config/counter/toggle state
     HELP
     0
   end
@@ -48,17 +56,52 @@ class Lexdrill::CLI
     word = Lexdrill::WordList.next
     return print_no_words(Lexdrill::WordList::PATH) unless word
 
-    puts word
+    puts Lexdrill::Colorizer.paint(Lexdrill::LineFormatter.format(word))
     0
   end
 
   def print_no_words(path)
-    warn "lexdrill: no words found in #{path}"
+    warn "drill: no words found in #{path}"
     1
   end
 
+  def run_hook
+    shell = argv[1]
+    return print_hook_usage unless shell
+
+    print_hook_snippet(shell)
+  end
+
+  def print_hook_usage
+    warn "usage: drill hook <zsh|bash>"
+    1
+  end
+
+  def print_hook_snippet(shell)
+    puts Lexdrill::ShellSnippet.for(shell)
+    0
+  rescue ArgumentError => error
+    warn "drill: #{error.message}"
+    1
+  end
+
+  def run_start
+    Lexdrill::Toggle.start
+    0
+  end
+
+  def run_stop
+    Lexdrill::Toggle.stop
+    0
+  end
+
+  def run_inspect
+    puts Lexdrill::Inspector.report
+    0
+  end
+
   def print_unknown_command(command)
-    warn "lexdrill: unknown command #{command.inspect}"
+    warn "drill: unknown command #{command.inspect}"
     print_help
     1
   end

data/lib/lexdrill/colorizer.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Wraps text in a randomly-picked ANSI color code from a fixed palette.
+module Lexdrill::Colorizer
+  CODES = [31, 32, 33, 34, 35, 36, 91, 92, 93, 94, 95, 96].freeze
+
+  def self.paint(text)
+    "\e[#{CODES.sample}m#{text}\e[0m"
+  end
+end

data/lib/lexdrill/inspector.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Builds a human-readable snapshot of lexdrill's current config/state, for
+# `drill inspect` — which files are active, how many words, the counter
+# value, and whether drilling is currently stopped.
+module Lexdrill::Inspector
+  def self.report
+    <<~REPORT
+      drill #{Lexdrill::VERSION}
+
+      Words file:    #{Lexdrill::WordList::PATH} (#{words_summary})
+      Counter file:  #{Lexdrill::WordList::COUNTER_PATH} (value: #{counter_value})
+      Toggle:        #{toggle_summary}
+      LEXDRILL_PATH: #{ENV.fetch('LEXDRILL_PATH', '(not set)')}
+    REPORT
+  end
+
+  def self.words_summary
+    return "missing" unless File.exist?(Lexdrill::WordList::PATH)
+
+    "#{Lexdrill::WordList.words.size} word(s)"
+  end
+
+  def self.counter_value
+    Lexdrill::Counter.new(Lexdrill::WordList::COUNTER_PATH).value
+  end
+
+  def self.toggle_summary
+    return "enabled" if Lexdrill::Toggle.enabled?
+
+    "stopped (#{Lexdrill::Toggle::PATH})"
+  end
+end

data/lib/lexdrill/line_formatter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Formats a shown word as "{line_number}/{total}:\t{word}". The just-advanced
+# counter value equals the 1-based position of the word that was shown.
+module Lexdrill::LineFormatter
+  def self.format(word)
+    total = Lexdrill::WordList.words.size
+    line_number = Lexdrill::Counter.new(Lexdrill::WordList::COUNTER_PATH).value
+    "#{line_number}/#{total}:\t#{word}"
+  end
+end

data/lib/lexdrill/shell_snippet.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Generates the zsh/bash shell integration snippet for `drill hook`.
+module Lexdrill::ShellSnippet
+  ZSH = <<~SNIPPET
+    drill_precmd() {
+      [[ -f "$HOME/.drill.disabled" ]] && return
+      command drill next 2>/dev/null
+    }
+    if [[ -z "${precmd_functions[(r)drill_precmd]}" ]]; then
+      precmd_functions+=(drill_precmd)
+    fi
+  SNIPPET
+
+  BASH = <<~SNIPPET
+    drill_precmd() {
+      [ -f "$HOME/.drill.disabled" ] && return
+      command drill next 2>/dev/null
+    }
+    case ";${PROMPT_COMMAND:-};" in
+      *";drill_precmd;"*) ;;
+      *) PROMPT_COMMAND="drill_precmd;${PROMPT_COMMAND}" ;;
+    esac
+  SNIPPET
+
+  def self.for(shell_name)
+    case shell_name.to_s
+    when "zsh" then ZSH
+    when "bash" then BASH
+    else
+      raise ArgumentError, "unsupported shell #{shell_name.inspect} (expected \"zsh\" or \"bash\")"
+    end
+  end
+end

data/lib/lexdrill/toggle.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+# Global pause/resume switch for the shell hook, independent of which
+# project's .drill.txt is active. Enabled by default; the marker file's
+# presence means stopped.
+module Lexdrill::Toggle
+  PATH = File.join(Dir.home, ".drill.disabled")
+
+  def self.enabled?
+    !File.exist?(PATH)
+  end
+
+  def self.start
+    FileUtils.rm_f(PATH)
+  end
+
+  def self.stop
+    File.write(PATH, "")
+  end
+end

data/lib/lexdrill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lexdrill
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/lexdrill.rb

@@ -4,4 +4,9 @@ require_relative "lexdrill/version"
 require_relative "lexdrill/config"
 require_relative "lexdrill/counter"
 require_relative "lexdrill/word_list"
+require_relative "lexdrill/toggle"
+require_relative "lexdrill/shell_snippet"
+require_relative "lexdrill/inspector"
+require_relative "lexdrill/colorizer"
+require_relative "lexdrill/line_formatter"
 require_relative "lexdrill/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lexdrill
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Siarhei Kisliak
@@ -15,19 +15,24 @@ description: lexdrill prints a vocabulary word or phrase on demand, tracking how
 email:
 - kislak7@gmail.com
 executables:
-- lexdrill
+- drill
 extensions: []
 extra_rdoc_files: []
 files:
 - Gemfile
 - LICENSE.txt
 - README.md
-- bin/lexdrill
+- bin/drill
 - lexdrill.gemspec
 - lib/lexdrill.rb
 - lib/lexdrill/cli.rb
+- lib/lexdrill/colorizer.rb
 - lib/lexdrill/config.rb
 - lib/lexdrill/counter.rb
+- lib/lexdrill/inspector.rb
+- lib/lexdrill/line_formatter.rb
+- lib/lexdrill/shell_snippet.rb
+- lib/lexdrill/toggle.rb
 - lib/lexdrill/version.rb
 - lib/lexdrill/word_list.rb
 homepage: https://github.com/kislak/lexdrill