lexdrill 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c02d9aa7303198e675b647958c287d690303a54e62891a52da016a094ab061e
-  data.tar.gz: 4eb14a5d4f5803b7da36df2f3dc273609f36e61f1477c6bb53aa891959be9d67
+  metadata.gz: 694f430036d22f39f5ee347a6220a8e977e726edb54db9f5c99d3f57bfcb8161
+  data.tar.gz: 9deb40864be7ded7ed8eb1aff88e25e20a412acf0a678526ff5d3f84f50ad69b
 SHA512:
-  metadata.gz: 365127d5d9aa2829ccbb570e200504da60064e188b27327d5a25de815e51581f4714d683d5d7866ac060dbc8e96d60c50b3c27ae5cc5e22e0c62af7a99302d72
-  data.tar.gz: cf8292e88bce78b4bf4d3db8d5bb5e39643b5a22b255148b3232071022e1274355305ceec5775270b541f394c89ca7544402f81985229f59c95c9ab61c02c8fe
+  metadata.gz: 49b05b7ac7dda95a4fd9c34b9de6fbe29486e8a8e84285d8fbb0fe0a211785a9a7870551c3a80566725d4884dee317117c85781a313251c9094fa927a4ff857c
+  data.tar.gz: 201a4d5c23a232a4cbb1ca5b2d294e629a9984e1196133511d62262e3c8ae3c238386278735f91d184db4b7214578304861caa70b641c6f0b77988cc2f4ef00f

data/README.md

@@ -1,5 +1,109 @@
 # lexdrill
-rubygems_2b77e405d9e5e8b74a8f60a79a57b5a7b3d4a44702507687
-mkdir -p ~/.gem
-printf -- '---\n:rubygems_api_key: rubygems_2b77e405d9e5e8b74a8f60a79a57b5a7b3d4a44702507687\n' > ~/.gem/credentials
-chmod 0600 ~/.gem/credentials
+
+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
+
+```bash
+gem install lexdrill
+```
+
+### `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:
+
+**bash**
+```bash
+echo "export PATH=\"$(ruby -e 'puts Gem.bindir'):\$PATH\"" >> ~/.bashrc
+source ~/.bashrc
+```
+
+**zsh**
+```zsh
+echo "export PATH=\"$(ruby -e 'puts Gem.bindir'):\$PATH\"" >> ~/.zshrc
+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

@@ -6,23 +6,23 @@ Gem::Specification.new do |spec|
   spec.name = "lexdrill"
   spec.version = Lexdrill::VERSION
   spec.authors = ["Siarhei Kisliak"]
-  spec.email = ["siarhei.kisliak@airslate.com"]
+  spec.email = ["kislak7@gmail.com"]
 
   spec.summary = "Vocabulary drilling in your terminal."
   spec.description = "lexdrill prints a vocabulary word or phrase on demand, tracking how often " \
                      "each one has been shown."
-  spec.homepage = "https://github.com/skisliak/lexdrill"
+  spec.homepage = "https://github.com/kislak/lexdrill"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["rubygems_mfa_required"] = "false"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
     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

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
-# Subcommand dispatcher for the `lexdrill` executable.
 class Lexdrill::CLI
   COMMANDS = {
     print_version: %w[version --version -v],
-    print_help: %w[help --help -h]
+    print_help: %w[help --help -h],
+    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,17 +38,70 @@ 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
+        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
 
+  def run_next
+    word = Lexdrill::WordList.next
+    return print_no_words(Lexdrill::WordList::PATH) unless word
+
+    puts Lexdrill::Colorizer.paint(Lexdrill::LineFormatter.format(word))
+    0
+  end
+
+  def print_no_words(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/config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Lexdrill::Config
+  FILENAME = ".drill.txt"
+  COUNTER_FILENAME = ".drill.counter"
+
+  def self.dir_path
+    cwd = Dir.pwd
+    cwd if File.exist?(File.join(cwd, FILENAME))
+  end
+
+  def self.base_path
+    ENV.fetch("LEXDRILL_PATH", nil) || dir_path || Dir.home
+  end
+
+  DRILL_PATH = File.join(base_path, FILENAME)
+  COUNTER_PATH = File.join(base_path, COUNTER_FILENAME)
+end

data/lib/lexdrill/counter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Lexdrill::Counter
+  attr_reader :path
+
+  def initialize(path)
+    @path = path
+  end
+
+  def value
+    return 0 unless File.exist?(path)
+
+    File.read(path).strip.to_i
+  end
+
+  def increment
+    File.write(path, (value + 1).to_s)
+  end
+
+  def reset
+    File.write(path, "0")
+  end
+
+  # The current value, unless it's out of bounds for the given size, in
+  # which case it resets to 0 first.
+  def bounded_value(size)
+    current = value
+    return current if current < size
+
+    reset
+    0
+  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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/lexdrill/word_list.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Reads vocabulary words/phrases from a `.drill.txt` file, one per line, and
+# advances a persisted counter to show "the current word" each time.
+class Lexdrill::WordList
+  PATH = Lexdrill::Config::DRILL_PATH
+  COUNTER_PATH = Lexdrill::Config::COUNTER_PATH
+
+  def self.words
+    @words ||= File.exist?(PATH) && File.readlines(PATH).map(&:strip).reject(&:empty?)
+    @words ||= []
+  end
+
+  def self.next
+    return nil if words.empty?
+
+    words[take_index(words.size)]
+  end
+
+  def self.take_index(size)
+    counter = Lexdrill::Counter.new(COUNTER_PATH)
+    index = counter.bounded_value(size)
+    counter.increment
+    index
+  end
+end

data/lib/lexdrill.rb

@@ -1,4 +1,12 @@
 # frozen_string_literal: true
 
 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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Siarhei Kisliak
@@ -13,27 +13,35 @@ dependencies: []
 description: lexdrill prints a vocabulary word or phrase on demand, tracking how often
   each one has been shown.
 email:
-- siarhei.kisliak@airslate.com
+- 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
-homepage: https://github.com/skisliak/lexdrill
+- lib/lexdrill/word_list.rb
+homepage: https://github.com/kislak/lexdrill
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/skisliak/lexdrill
-  source_code_uri: https://github.com/skisliak/lexdrill
-  rubygems_mfa_required: 'false'
+  homepage_uri: https://github.com/kislak/lexdrill
+  source_code_uri: https://github.com/kislak/lexdrill
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: