lexdrill 0.6.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cc865e919348867e13b05201ac159f40f7f7fce166f44d31b98cd92d0db757b
-  data.tar.gz: c3a93dc3474fe2cafcddb60d4cd25ee3350e66c4f487c8f99878a9d09e71f01f
+  metadata.gz: 160443af001778081e3f6599911f3f3ab828b19fae27606ab7e9d472d5af85f3
+  data.tar.gz: b5400da446623b84d04ab9f27df807c3bb52ff6e2c857af365407318aa4732a5
 SHA512:
-  metadata.gz: df405a270f001707c86ad9e9e0d3104bb822e3eb337c7ab6afb0ad3a320aaf4fece4b1f727ccabfaf09f3fc804903876012f1ef348dd613473aeb962b2a1cbd4
-  data.tar.gz: 6849d9d157bd2c634f5687b4ac194bf3d38b2357092d1344ebc38533708723009d52e93a4445988aafe36fcfa3a61b1ec589716588c925f9115fe9d0571f0ae0
+  metadata.gz: 7375919dc3b144de3feeb5f53ae8868b1aead949d85c5193833e12a428387b20e862e65ea2bc32caf176b2c0737ee5e5769b9e20998396cd1aba78f730802790
+  data.tar.gz: f588b965a909cb7c97e05dd22e4ce61a0170ce5e15803d386a942bfb39777f209038829fd43da4c585c51f99f79f5b836afb84928c150103648454e4d59f9867

data/README.md

@@ -48,14 +48,14 @@ Run `drill next` to print the current word and advance to the next one.
 There are two output styles (`drill format simple|full`, `simple` is the
 default):
 
-**simple** — the drill sign (always blue), a space, then the word (in a
-separately-picked random color), all on one line:
+**simple** — the drill sign (always blue), a space, then the word (colored
+by its show count — see "Mastery" below), all on one line:
 ```
 ⟳ apple
 ```
 
 **full** — `counter/total⟳[loop_start-loop_end]` on one line, the word on
-the next, in a randomly-picked color:
+the next, colored by the word's show count:
 ```
 1/6⟳[1-3]
 apple
@@ -151,14 +151,48 @@ There are also named shortcuts for common loop sizes, one word/phrase apart:
 `8` if you leave them off — `drill jazz` alone is `drill beat 5 8`, and
 `drill beat 4` alone is `drill beat 4 8`.
 
+### Frequency (`rand`)
+
+`next` fires on every single prompt by default via the shell hook, which can
+feel noisy in a busy session. `drill rand <n>` makes it actually show a word
+only approximately 1-in-`n` times instead:
+
+```bash
+drill rand 10   # roughly one in every ten calls
+drill rand 1    # back to every time (the default)
+```
+
+This is a **global** setting applied inside `drill next` itself — unlike
+`start`/`stop`, it affects *every* call, hook-triggered or manually typed.
+On a "skip", `next` silently does nothing (no output, nothing advances) and
+exits 0.
+
+### Mastery (color by show count)
+
+Every time `next` shows a word it's tracked in `.drill.stats` (see
+[`drill stats`](#commands) below). On an **odd** show count, the word's
+color follows a blue → red gradient, one step per 100 shows — so at a
+glance, blue words are fresh and red words are heavily drilled. On an
+**even** show count, it's a vivid random color instead, just for visual
+variety. Once a word hits 1200 shows it's considered mastered and `next`
+stops selecting it (it still appears in `drill list`/`drill stats`, just no
+longer comes up automatically). If every word in the list has been
+mastered, `next` reports that on stderr and exits 1 instead of showing
+anything.
+
 ### 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, toggle, and beat state |
+| `drill inspect` | Show the active `.drill.txt`/`.drill.counter`/`.drill.stats` paths, word count, counter value, toggle, beat, and rand state |
 | `drill hook zsh\|bash` | Print the shell integration snippet (used above) |
 | `drill beat <2-8> <repetitions>` / `drill beat none` | Set or disable the rhythm |
 | `drill polka\|waltz\|rock\|jazz\|jiga\|balkan\|samba <repetitions>` | Shorthand for a fixed loop size (see table above) |
 | `drill format simple\|full` | Set the output style (`simple` is the default) |
+| `drill add <text>` | Append a new item to the end of the list |
+| `drill list` | Print all items as `<count>\t<phrase>` (tab-separated), sorted by show count, highest first |
+| `drill open` | Open the list file in `$EDITOR`/`$VISUAL` (falls back to `vi`) |
+| `drill stats` | Show how many times each item has been shown, numbered |
+| `drill rand <n>` | Shell hook shows a word ~1-in-`n` times (`n=1` is every time, the default) |

data/lib/lexdrill/beat.rb

@@ -6,11 +6,15 @@ require "fileutils"
 # `repetitions` times before advancing to the next loop. Lives at
 # ~/.drill.beat, independent of whichever project's .drill.txt is active.
 # Disabled (plain word-by-word advance) unless explicitly configured.
+# `drill beat rand` selects a third mode (marked by the literal contents
+# "rand") where WordList.next ignores the counter/rhythm entirely and picks
+# a uniformly random word each time instead.
 module Lexdrill::Beat
   PATH = File.join(Dir.home, ".drill.beat")
   MIN_LOOP_SIZE = 2
   MAX_LOOP_SIZE = 8
   DEFAULT_REPETITIONS = 8
+  RAND_MARKER = "rand"
 
   ALIASES = {
     "polka" => 2,
@@ -28,13 +32,21 @@ module Lexdrill::Beat
   LoopInfo = Struct.new(:index, :chunk_start, :chunk_end, :loop_number, :total_loops, keyword_init: true)
 
   def self.configured?
-    File.exist?(PATH)
+    File.exist?(PATH) && !rand?
+  end
+
+  def self.rand?
+    File.exist?(PATH) && File.read(PATH).strip == RAND_MARKER
   end
 
   def self.set(loop_size, repetitions)
     File.write(PATH, "#{loop_size} #{repetitions}")
   end
 
+  def self.set_rand
+    File.write(PATH, RAND_MARKER)
+  end
+
   def self.clear
     FileUtils.rm_f(PATH)
   end

data/lib/lexdrill/cli.rb

@@ -11,7 +11,12 @@ class Lexdrill::CLI
     run_inspect: %w[inspect],
     run_beat: %w[beat],
     run_beat_alias: %w[polka waltz rock jazz jiga balkan samba],
-    run_format: %w[format]
+    run_format: %w[format],
+    run_add: %w[add],
+    run_list: %w[list],
+    run_open: %w[open],
+    run_stats: %w[stats],
+    run_rand: %w[rand]
   }.freeze
 
   def self.start(argv = ARGV)
@@ -53,26 +58,46 @@ class Lexdrill::CLI
         drill inspect   Show the active config/counter/toggle state
         drill beat <2-8> [repetitions]   Set the rhythm (repetitions defaults to 8)
         drill beat none                 Disable the rhythm
+        drill beat rand                 Ignore the counter/rhythm; show a random item each time
         drill polka|waltz|rock|jazz|jiga|balkan|samba [repetitions]
                         Shorthand for a fixed loop size (2 through 8, in order)
         drill format simple|full   Set the output style (simple is the default)
+        drill add <text>   Append a new item to the end of the list
+        drill list         Print items as <count>\t<phrase>, tab-separated, highest count first
+        drill open         Open the list file in $EDITOR/$VISUAL (falls back to vi)
+        drill stats        Show how many times each item has been shown
+        drill rand <n>     drill next shows a word ~1-in-n times (n=1 is every time)
     HELP
     0
   end
 
   def run_next
+    return 0 if Lexdrill::Rand.skip?
+
     word = Lexdrill::WordList.next
-    return print_no_words(Lexdrill::WordList::PATH) unless word
+    return print_next_failure unless word
 
     puts colored_line(word)
     0
   end
 
+  def print_next_failure
+    return print_no_words(Lexdrill::WordList::PATH) if Lexdrill::WordList.words.empty?
+
+    print_all_graduated
+  end
+
+  def print_all_graduated
+    warn "drill: every item has reached #{Lexdrill::Stats::GRADUATION_THRESHOLD} shows — nothing left to drill"
+    1
+  end
+
   def colored_line(word)
     text = Lexdrill::LineFormatter.format(word)
     return text if Lexdrill::Format.simple?
 
-    Lexdrill::Colorizer.paint(text)
+    count = Lexdrill::Stats.counts.fetch(word, 0)
+    Lexdrill::Colorizer.paint_by_count(text, count)
   end
 
   def print_no_words(path)
@@ -119,10 +144,16 @@ class Lexdrill::CLI
     arg = argv[1]
     return print_beat_usage unless arg
     return clear_beat if arg == "none"
+    return set_rand_beat if arg == "rand"
 
     set_beat(arg.to_i, Lexdrill::Beat.repetitions_or_default(argv[2]))
   end
 
+  def set_rand_beat
+    Lexdrill::Beat.set_rand
+    0
+  end
+
   def run_beat_alias
     loop_size = Lexdrill::Beat::ALIASES.fetch(argv.first)
     set_beat(loop_size, Lexdrill::Beat.repetitions_or_default(argv[1]))
@@ -143,7 +174,7 @@ class Lexdrill::CLI
 
   def print_beat_usage
     warn "usage: drill beat <#{Lexdrill::Beat::MIN_LOOP_SIZE}-#{Lexdrill::Beat::MAX_LOOP_SIZE}> " \
-         "<repetitions> | drill beat none"
+         "<repetitions> | drill beat none | drill beat rand"
     1
   end
 
@@ -170,6 +201,57 @@ class Lexdrill::CLI
     1
   end
 
+  def run_add
+    text = argv[1..].join(" ")
+    return print_add_usage if text.empty?
+
+    File.open(Lexdrill::WordList::PATH, "a", encoding: "UTF-8") { |file| file.puts(text) }
+    puts "added: #{text}"
+    0
+  end
+
+  def print_add_usage
+    warn "usage: drill add <text>"
+    1
+  end
+
+  def run_list
+    words = Lexdrill::WordList.words
+    return print_no_words(Lexdrill::WordList::PATH) if words.empty?
+
+    counts = Lexdrill::Stats.counts
+    pairs = words.map { |word| [counts.fetch(word, 0), word] }.sort_by { |count, _word| -count }
+    pairs.each { |count, word| puts "#{count}\t#{word}" }
+    0
+  end
+
+  def run_open
+    editor_cmd = (ENV["VISUAL"] || ENV["EDITOR"] || "vi").split
+    system(*editor_cmd, Lexdrill::WordList::PATH) ? 0 : 1
+  end
+
+  def run_stats
+    words = Lexdrill::WordList.words
+    return print_no_words(Lexdrill::WordList::PATH) if words.empty?
+
+    counts = Lexdrill::Stats.counts
+    words.each_with_index { |word, index| puts "#{index + 1}. #{word} (#{counts.fetch(word, 0)})" }
+    0
+  end
+
+  def run_rand
+    denominator = argv[1].to_s.to_i
+    return print_rand_usage unless denominator.positive?
+
+    Lexdrill::Rand.set(denominator)
+    0
+  end
+
+  def print_rand_usage
+    warn "usage: drill rand <n>   (drill next shows a word ~1-in-n times; n=1 is every time)"
+    1
+  end
+
   def print_unknown_command(command)
     warn "drill: unknown command #{command.inspect}"
     print_help

data/lib/lexdrill/colorizer.rb

@@ -1,18 +1,69 @@
 # frozen_string_literal: true
 
-# Wraps text in an ANSI color code.
+# Wraps text in an ANSI color code. `paint_by_count` maps a word's show
+# count onto a blue -> red truecolor gradient, one step per
+# Lexdrill::Stats::BUCKET_SIZE shows, so a word's color reflects how many
+# times it's been drilled — except on an even count, where a random vivid
+# color is used instead, for a bit of visual variety.
 module Lexdrill::Colorizer
-  CODES = [31, 32, 33, 34, 35, 36, 91, 92, 93, 94, 95, 96].freeze
   BLUE = 34
-
-  def self.paint(text)
-    wrap(text, CODES.sample)
-  end
+  GRADIENT_STEPS = Lexdrill::Stats::GRADUATION_THRESHOLD / Lexdrill::Stats::BUCKET_SIZE
+  HUE_DEGREES = 360
+  # Which of {peak, trough, 0} each RGB channel takes in each 60-degree hue
+  # sextant, walking red -> yellow -> green -> cyan -> blue -> magenta -> red.
+  SEXTANT_CHANNELS = [
+    %i[peak trough zero],
+    %i[trough peak zero],
+    %i[zero peak trough],
+    %i[zero trough peak],
+    %i[trough zero peak],
+    %i[peak zero trough]
+  ].freeze
 
   def self.paint_blue(text)
     wrap(text, BLUE)
   end
 
+  def self.paint_by_count(text, count)
+    code = count.even? ? random_code : gradient_code(count)
+    wrap(text, code)
+  end
+
+  def self.gradient_code(count)
+    last_bucket = GRADIENT_STEPS - 1
+    bucket = [count / Lexdrill::Stats::BUCKET_SIZE, last_bucket].min
+    fraction = bucket.fdiv(last_bucket)
+    red = (fraction * 255).round
+    blue = ((1 - fraction) * 255).round
+    "38;2;#{red};0;#{blue}"
+  end
+  private_class_method :gradient_code
+
+  def self.random_code
+    red, green, blue = hue_to_rgb(Kernel.rand(HUE_DEGREES))
+    "38;2;#{red};#{green};#{blue}"
+  end
+  private_class_method :random_code
+
+  # Full-saturation, full-value HSV -> RGB, for a vivid random color.
+  def self.hue_to_rgb(hue)
+    peak = 255
+    trough = hue_trough(hue, peak)
+    rgb_for_sextant(hue / 60, peak, trough)
+  end
+  private_class_method :hue_to_rgb
+
+  def self.hue_trough(hue, peak)
+    (peak * (1 - (((hue / 60.0) % 2) - 1).abs)).round
+  end
+  private_class_method :hue_trough
+
+  def self.rgb_for_sextant(sextant, peak, trough)
+    channel_values = { peak: peak, trough: trough, zero: 0 }
+    SEXTANT_CHANNELS[sextant % SEXTANT_CHANNELS.size].map { |channel| channel_values.fetch(channel) }
+  end
+  private_class_method :rgb_for_sextant
+
   def self.wrap(text, code)
     "\e[#{code}m#{text}\e[0m"
   end

data/lib/lexdrill/config.rb

@@ -3,6 +3,7 @@
 module Lexdrill::Config
   FILENAME = ".drill.txt"
   COUNTER_FILENAME = ".drill.counter"
+  STATS_FILENAME = ".drill.stats"
 
   def self.dir_path
     cwd = Dir.pwd
@@ -19,4 +20,5 @@ module Lexdrill::Config
 
   DRILL_PATH = File.join(base_path, FILENAME)
   COUNTER_PATH = File.join(base_path, COUNTER_FILENAME)
+  STATS_PATH = File.join(base_path, STATS_FILENAME)
 end

data/lib/lexdrill/inspector.rb

@@ -10,8 +10,10 @@ module Lexdrill::Inspector
 
       Words file:    #{Lexdrill::WordList::PATH} (#{words_summary})
       Counter file:  #{Lexdrill::WordList::COUNTER_PATH} (value: #{counter_value})
+      Stats file:    #{Lexdrill::Stats::PATH} (#{stats_summary})
       Toggle:        #{toggle_summary}
       Beat:          #{beat_summary}
+      Rand:          #{rand_summary}
       Format:        #{Lexdrill::Format.current}
       LEXDRILL_PATH: #{ENV.fetch('LEXDRILL_PATH', '(not set)')}
     REPORT
@@ -20,13 +22,24 @@ module Lexdrill::Inspector
   def self.words_summary
     return "missing" unless File.exist?(Lexdrill::WordList::PATH)
 
-    "#{Lexdrill::WordList.words.size} word(s)"
+    words = Lexdrill::WordList.words
+    total = words.size
+    graduated = words.count { |word| Lexdrill::Stats.graduated?(word) }
+    return "#{total} word(s)" if graduated.zero?
+
+    "#{total} word(s), #{graduated} graduated"
   end
 
   def self.counter_value
     Lexdrill::Counter.new(Lexdrill::WordList::COUNTER_PATH).value
   end
 
+  def self.stats_summary
+    return "no data yet" unless File.exist?(Lexdrill::Stats::PATH)
+
+    "#{Lexdrill::Stats.counts.size} item(s) tracked"
+  end
+
   def self.toggle_summary
     return "enabled" if Lexdrill::Toggle.enabled?
 
@@ -34,8 +47,16 @@ module Lexdrill::Inspector
   end
 
   def self.beat_summary
+    return "random (ignores rhythm/counter)" if Lexdrill::Beat.rand?
     return "not set (plain word-by-word)" unless Lexdrill::Beat.configured?
 
     "loop #{Lexdrill::Beat.loop_size}, repeat #{Lexdrill::Beat.repetitions}"
   end
+
+  def self.rand_summary
+    denominator = Lexdrill::Rand.value
+    return "every time (default)" if denominator == 1
+
+    "approximately 1-in-#{denominator}"
+  end
 end

data/lib/lexdrill/line_formatter.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Formats a shown word for display. In "simple" mode: the drill sign (in
-# blue), a space, then the word (in a separately-picked random color), all
-# on one line. In "full" mode (the default):
+# blue), a space, then the word (colored by its show count, blue -> red as
+# it's drilled more), all on one line. In "full" mode (the default):
 # "{counter}/{total}{SEPARATOR}[{loop_start}-{loop_end}]\n{word}" — counter
 # is the word's own 1-based position in the list, re-derived through
 # Lexdrill::Beat so it stays meaningful even when a rhythm repeats steps.
@@ -16,7 +16,8 @@ module Lexdrill::LineFormatter
   end
 
   def self.simple(word)
-    "#{Lexdrill::Colorizer.paint_blue(SEPARATOR)} #{Lexdrill::Colorizer.paint(word)}"
+    count = Lexdrill::Stats.counts.fetch(word, 0)
+    "#{Lexdrill::Colorizer.paint_blue(SEPARATOR)} #{Lexdrill::Colorizer.paint_by_count(word, count)}"
   end
 
   def self.full(word)

data/lib/lexdrill/rand.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Global "how often to actually show a word" setting, applied by
+# `drill next` itself (both automatic hook-triggered calls and manual
+# invocations respect it equally). Lives at ~/.drill.rand as a plain
+# integer; defaults to 1 (show every time).
+module Lexdrill::Rand
+  PATH = File.join(Dir.home, ".drill.rand")
+  DEFAULT = 1
+
+  def self.value
+    return DEFAULT unless File.exist?(PATH)
+
+    denominator = File.read(PATH).strip.to_i
+    denominator.positive? ? denominator : DEFAULT
+  end
+
+  def self.set(denominator)
+    File.write(PATH, denominator.to_s)
+  end
+
+  # True with probability (n-1)/n: "skip this show".
+  def self.skip?
+    denominator = value
+    return false if denominator <= 1
+
+    Kernel.rand(denominator) != 0
+  end
+end

data/lib/lexdrill/shell_snippet.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 # Generates the zsh/bash shell integration snippet for `drill hook`.
+# Show-frequency throttling (`drill rand <n>`) lives entirely in `drill
+# next` itself, not in these snippets, so it applies equally to
+# hook-triggered and manually-run calls.
 module Lexdrill::ShellSnippet
   ZSH = <<~SNIPPET
     drill_precmd() {

data/lib/lexdrill/stats.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Tracks how many times each word/phrase has been shown by `next`, persisted
+# as a word => count JSON object at `.drill.stats` (same base path as
+# `.drill.txt`/`.drill.counter`). Every BUCKET_SIZE shows moves a word into
+# the next display-color bucket (see Lexdrill::Colorizer); once a word
+# reaches GRADUATION_THRESHOLD shows it's considered mastered and `next`
+# stops selecting it.
+module Lexdrill::Stats
+  PATH = Lexdrill::Config::STATS_PATH
+  BUCKET_SIZE = 100
+  GRADUATION_THRESHOLD = 1200
+
+  def self.record(word)
+    data = load
+    data[word] = data.fetch(word, 0) + 1
+    save(data)
+  end
+
+  def self.counts
+    load
+  end
+
+  def self.graduated?(word)
+    counts.fetch(word, 0) >= GRADUATION_THRESHOLD
+  end
+
+  def self.load
+    return {} unless File.exist?(PATH)
+
+    JSON.parse(File.read(PATH, encoding: "UTF-8"))
+  rescue JSON::ParserError
+    {}
+  end
+  private_class_method :load
+
+  def self.save(data)
+    File.write(PATH, JSON.generate(data), encoding: "UTF-8")
+  end
+  private_class_method :save
+end

data/lib/lexdrill/version.rb

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

data/lib/lexdrill/word_list.rb

@@ -3,7 +3,9 @@
 # Reads vocabulary words/phrases from a `.drill.txt` file, one per line, and
 # advances a persisted counter to show "the current word" each time. On a
 # fresh install with no project-local or LEXDRILL_PATH-overridden list, seeds
-# ~/.drill.txt with a default starter list instead of coming up empty.
+# ~/.drill.txt with a default starter list instead of coming up empty. Words
+# that have graduated (see Lexdrill::Stats) are excluded from `.next` but
+# remain in `.words` for `list`/`stats` to report.
 class Lexdrill::WordList
   PATH = Lexdrill::Config::DRILL_PATH
   COUNTER_PATH = Lexdrill::Config::COUNTER_PATH
@@ -23,9 +25,16 @@ class Lexdrill::WordList
   private_class_method :seed_default_at_home
 
   def self.next
-    return nil if words.empty?
+    active = active_words
+    return nil if active.empty?
 
-    words[take_index(words.size)]
+    word = Lexdrill::Beat.rand? ? active.sample : active[take_index(active.size)]
+    Lexdrill::Stats.record(word)
+    word
+  end
+
+  def self.active_words
+    words.reject { |word| Lexdrill::Stats.graduated?(word) }
   end
 
   def self.take_index(size)

data/lib/lexdrill.rb

@@ -5,8 +5,10 @@ require_relative "lexdrill/config"
 require_relative "lexdrill/counter"
 require_relative "lexdrill/beat"
 require_relative "lexdrill/default_words"
+require_relative "lexdrill/stats"
 require_relative "lexdrill/word_list"
 require_relative "lexdrill/toggle"
+require_relative "lexdrill/rand"
 require_relative "lexdrill/shell_snippet"
 require_relative "lexdrill/inspector"
 require_relative "lexdrill/colorizer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lexdrill
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Siarhei Kisliak
@@ -34,7 +34,9 @@ files:
 - lib/lexdrill/format.rb
 - lib/lexdrill/inspector.rb
 - lib/lexdrill/line_formatter.rb
+- lib/lexdrill/rand.rb
 - lib/lexdrill/shell_snippet.rb
+- lib/lexdrill/stats.rb
 - lib/lexdrill/toggle.rb
 - lib/lexdrill/version.rb
 - lib/lexdrill/word_list.rb