mnemonicker 0.0.1

data/HISTORY.md

@@ -0,0 +1,5 @@
+# Mnemonicker History
+
+## 0.0.1 - 14 April 2013 (3feddee)
+
+* Initial release

data/README.md

@@ -0,0 +1,71 @@
+Mnemonicker
+===========
+
+An encoder and decoder for the [mnemonic major system][major-system] for
+remembering numbers.
+
+[major-system]: https://en.wikipedia.org/wiki/Mnemonic_major_system
+
+Usage
+-----
+
+```
+> gem install mnemonicker
+> mnemonicker
+
+Commands
+
+   encode [number] - Suggest words that can represent the number
+   decode [*words] - Convert words to numbers
+   update          - Download latest wordlist
+   help            - This output
+
+System
+
+   Each number maps to a group of similar sounds, which you can then make
+   a sentence out of that is easier to remember than the numbers themself.
+
+   # | Sound     | Way to remember
+   --+-----------+---------------------------
+   0 | s, z      | z is the first letter of zero
+   1 | t, th, t  | t & d have one downstroke
+   2 | n         | n has two downstrokes
+   3 | m         | m has three downstrokes
+   4 | r         | r is the last character of four
+   5 | l         | L is the roman numeral for 50
+   6 | sh, ch, j | I just remember this one
+   7 | k         | K contains two sevens back to back
+   8 | f, v      | Script f looks like an 8
+   9 | p, b      | p and b both very similar shape to 9
+
+   Any sounds not in this list (vowels, "w", "h", "x") are "free" and do not
+   represent anything.
+
+> mnemonicker encode 314
+emitter
+matter
+meter
+mother
+motor
+> mnemonicker decode mother
+314
+> mnemonicker decode a man a plan a canal panama
+32952725923
+```
+
+Known Issues
+------------
+
+Mnemonicker uses the [Double Metaphone][double-metaphone] phonetic encoding algorithm, which causes some limitations:
+
+* Does not decode long words correctly. For instance, "hindquarters" and
+  "manufacturing" are both a number of digits short.
+* Certain words with odd pronunciation (such as "enough") are incorrectly
+  decoded.
+
+Additionally, the current word list is somewhat anemic.
+
+That said, the goal of this project is to spark your imagination. Only you can
+combine words in a way that is memorable to you!
+
+[double-metaphone]: https://en.wikipedia.org/wiki/Metaphone

data/bin/mnemonicker

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'mnemonicker/cli'
+
+result = Mnemonicker::CLI.run(*ARGV)
+
+exit(1) unless result

data/lib/mnemonicker.rb

@@ -0,0 +1,2 @@
+require 'mnemonicker/major_system'
+require 'mnemonicker/word_list'

data/lib/mnemonicker/cli.rb

@@ -0,0 +1,100 @@
+require 'json'
+require 'fileutils'
+require 'net/http'
+
+require 'rubyfish'
+
+require 'mnemonicker/major_system'
+require 'mnemonicker/word_list'
+
+module Mnemonicker
+  class CLI
+    def self.run(*args)
+      cmd = args.shift
+      cmd ||= 'help'
+      cmd = cmd[0].upcase + cmd[1..-1]
+      handler = Commands.const_get(cmd)
+      handler.new.process(*args)
+    rescue NameError
+      Commands::Help.new.process
+    end
+  end
+
+  module Commands
+    class Update
+      def process
+        Mnemonicker::WordList.new('cli').update do |file, count|
+          puts "%s...%i words" % [file, count]
+        end
+      end
+    end
+
+    class Encode
+      def process(number)
+        tried = false
+        list = WordList.new('cli')
+        wordlist = begin
+          list.fetch
+        rescue WordList::ListNotFound
+          if tried
+            raise
+          else
+            tried = true
+            $stderr.puts "No word list found, downloading..."
+            list.update
+            retry
+          end
+        end
+
+        candidates = wordlist['words'][number]
+
+        puts candidates.sort if candidates
+        true
+      end
+    end
+
+    class Decode
+      def process(*words)
+        words.each do |word|
+          puts MajorSystem.word_to_number(word)
+        end
+      end
+    end
+
+    class Help
+      def process
+$stderr.puts <<-EOS
+
+Commands
+
+   encode [number] - Suggest words that can represent the number
+   decode [*words] - Convert words to numbers
+   update          - Download latest wordlist
+   help            - This output
+
+System
+
+   Each number maps to a group of similar sounds, which you can then make
+   a sentence out of that is easier to remember than the numbers themself.
+
+   # | Sound     | Way to remember
+   --+-----------+---------------------------
+   0 | s, z      | z is the first letter of zero
+   1 | t, th, t  | t & d have one downstroke
+   2 | n         | n has two downstrokes
+   3 | m         | m has three downstrokes
+   4 | r         | r is the last character of four
+   5 | l         | L is the roman numeral for 50
+   6 | sh, ch, j | I just remember this one
+   7 | k         | K contains two sevens back to back
+   8 | f, v      | Script f looks like an 8
+   9 | p, b      | p and b both very similar shape to 9
+
+   Any sounds not in this list (vowels, "w", "h", "x") are "free" and do not
+   represent anything.
+
+ EOS
+      end
+    end
+  end
+end

data/lib/mnemonicker/major_system.rb

@@ -0,0 +1,43 @@
+module Mnemonicker
+  class MajorSystem
+    MAPPINGS = {
+      'S' => 0,
+      '0' => 1,
+      'T' => 1,
+      'D' => 1,
+      'N' => 2,
+      'M' => 3,
+      'R' => 4,
+      'L' => 5,
+      'J' => 6,
+      'K' => 7,
+      'F' => 8,
+      'V' => 8,
+      'P' => 9,
+      'B' => 9,
+      'X' => 6,
+      'A' => nil,
+      'W' => nil,
+      'H' => nil
+    }
+
+    def self.word_to_number(word)
+      # Metaphone is insufficient since it has a maximum length of six, which
+      # does not work for long words like "hindquarters" or "manufacturing".
+      #
+      # Best phonetic algorithm I have found though.
+      metaphone = RubyFish::DoubleMetaphone.phonetic_code(word)[0]
+      metaphone.gsub!(/KS$/, "")    # fox    => FKS  => F
+      metaphone.gsub!(/RNK$/, "RK") # turing => TRNK => TRK
+      n = ""
+      metaphone.each_char do |c|
+        if MAPPINGS.has_key?(c)
+          n << MAPPINGS[c].to_s if MAPPINGS[c]
+        else
+          raise "No mapping for #{c}"
+        end
+      end
+      n
+    end
+  end
+end

data/lib/mnemonicker/version.rb

@@ -0,0 +1,3 @@
+module Mnemonicker
+  VERSION = '0.0.1'
+end

data/lib/mnemonicker/word_list.rb

@@ -0,0 +1,46 @@
+module Mnemonicker
+  class WordList < Struct.new(:key)
+    class ListNotFound < RuntimeError; end
+
+    def fetch
+      JSON.parse(File.read(cache_file))
+    rescue
+      raise ListNotFound
+    end
+
+    def update(&block)
+      wordlist = {
+        version:    1,
+        fetched_at: Time.now.utc,
+        'words' => {}
+      }
+      index = fetch_url('index.html')
+      index.lines.each do |line|
+        line = line.chomp
+        words = fetch_url(line)
+        words.lines.each do |word|
+          word = word.chomp
+          number = MajorSystem.word_to_number(word)
+          wordlist['words'][number] ||= []
+          wordlist['words'][number] << word
+        end
+        if block
+          block.call(line, words.lines.count)
+        end
+      end
+
+      FileUtils.mkdir_p(File.dirname(cache_file))
+      File.open(cache_file, "w") {|f| f.write wordlist.to_json }
+    end
+
+    private
+
+    def cache_file
+      File.expand_path("~/.mnemonicker/#{key}.json")
+    end
+
+    def fetch_url(file)
+      Net::HTTP.get('xaviershay.github.io', '/mnemonicker-wordlist/' + file)
+    end
+  end
+end

data/mnemonicker.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/mnemonicker/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Xavier Shay"]
+  gem.email         = ["contact@xaviershay.com"]
+  gem.description   =
+    %q{An aid for remembering numbers}
+  gem.summary       = %q{
+    Encoder and decoder for the mnemonic major system for remembering numbers.
+  }
+  gem.homepage      = "http://github.com/xaviershay/mnemonicker"
+
+  gem.executables   = []
+  gem.required_ruby_version = '>= 1.9.0'
+  gem.files         = Dir.glob("{test,lib}/**/*.rb") + %w(
+                        README.md
+                        HISTORY.md
+                        mnemonicker.gemspec
+                      )
+  gem.test_files    = Dir.glob("test/**/*.rb")
+  gem.name          = "mnemonicker"
+  gem.require_paths = ["lib"]
+  gem.bindir        = "bin"
+  gem.executables  << "mnemonicker"
+  gem.version       = Mnemonicker::VERSION
+  gem.has_rdoc      = false
+  gem.add_dependency 'rubyfish'
+end

data/test/major_system_test.rb

@@ -0,0 +1,29 @@
+require 'minitest/autorun'
+
+require 'mnemonicker/cli'
+
+class MajorSystemTest < MiniTest::Unit::TestCase
+  {
+    wikipedia: { # From https://en.wikipedia.org/wiki/Mnemonic_major_system
+      "action"  => '762',
+      "ghost"   => '701',
+      'missile' => '305',
+      'mossy'   => '30',
+      'sail'    => '05',
+    },
+    exceptions: {
+      "fox"    => '8',
+      "turing" => '147',
+    },
+    known_bugs: {
+      "enough"       => '27', # Should be 28
+      'hindquarters' => '217' # Should be 2174140
+    }
+  }.each do |label, examples|
+    examples.each do |word, number|
+      define_method("test_#{label}_#{word}") do
+        assert_equal number, Mnemonicker::MajorSystem.word_to_number(word)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: mnemonicker
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Xavier Shay
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubyfish
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: An aid for remembering numbers
+email:
+- contact@xaviershay.com
+executables:
+- mnemonicker
+extensions: []
+extra_rdoc_files: []
+files:
+- test/major_system_test.rb
+- lib/mnemonicker/cli.rb
+- lib/mnemonicker/major_system.rb
+- lib/mnemonicker/version.rb
+- lib/mnemonicker/word_list.rb
+- lib/mnemonicker.rb
+- README.md
+- HISTORY.md
+- mnemonicker.gemspec
+- bin/mnemonicker
+homepage: http://github.com/xaviershay/mnemonicker
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Encoder and decoder for the mnemonic major system for remembering numbers.
+test_files:
+- test/major_system_test.rb