koremutake 0.1.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1:
+    Project started (2008-05-02)

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2008 Gunnar Wolf <gwolf@gwolf.org>
+
+The Koremutake project is hereby licensed under this license. This
+license is known as "The MIT License".
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,6 @@
+./Manifest.txt
+./CHANGELOG
+./LICENSE
+./README
+./lib/koremu.rb
+koremutake.gemspec

data/README

@@ -0,0 +1,72 @@
+= koremu.rb - Ruby implementation of the Koremutake Memorable Random Strings
+
+== SYNOPSIS
+ 
+  require 'koremu'
+
+  ks = KoremuString.new('KOREMUTAKE')
+  puts ks.to_ki              # 10610353957
+  puts ks.to_ka.join(',')    # 39,67,52,78,37
+
+  ki = KoremuFixnum.new(1248594)
+  puts ki.to_ks              # SUHITU
+  puts ki.to_ka .join(',')   # 76,26,82
+
+  ka = KoremuArray.new([50,15,20,13])
+  puts ka.to_ks              # MIFOGIFE
+  puts ka.to_ki              # 105105933
+
+== DESCRIPTION
+
+For us humans, it's always easier to remember a pronounceable string,
+even if it is meaningless, than to remember a long number. Koremutake
+is a system you can use to translate any number (of course,
+particularly suited at long numbers) to a sequence of
+syllables. Typical uses of Koremutake strings are auto-generated user
+passwords or URLs.
+
+This module is based in Leon Brocard's String::Koremutake Perl
+module, available at
+http://search.cpan.org/dist/String-Koremutake/lib/String/Koremutake.pm
+which is, in turn, based upon Shorl
+(http://shorl.com/koremutake.php). Koremutake is a «way to express
+any large number as a sequence of syllables», and the general idea
+is based in Sean B. Palmer's «Memorable Random String» term,
+http://infomesh.net/2001/07/MeRS/ 
+
+== WHAT IS VALID KOREMUTAKE?
+
+Koremutake consists of 128 valid syllables. They do not, of course,
+represent all of the valid syllables in any random human language -
+They are meanly <i>meant to encode integers</i>, not to transform
+text into strings. If you try to transform regular text, <i>lots of
+information will be lost in the process</i>
+
+All of the syllables end with a vowel. The valid vowels are A, E, I,
+O, U and Y. The consonant particles are B, D, F, G, H, J, K, L, M,
+N, P, R, S, T, V, BR, DR, FR, GR, PR, ST and TR (TR has only TRA and
+TRE).
+
+Koremutake is represented with uppercase letters (and that's what it
+returns), but will recognize lowercase as well.
+
+== AUTHOR
+
+This module was written by Gunnar Wolf <gwolf@gwolf.org>, Instituto
+de Investigaciones Económicas, UNAM.
+
+Copyright (c) 2008 Gunnar Wolf <gwolf@gwolf.org>
+
+== LICENSING INFORMATION
+
+This module is under a MIT license. For further information, please
+check the LICENSE file.
+ 
+= Getting the code
+
+The module project's home page can be found at
+http://rubyforge.org/projects/koremutake/ 
+
+The project's Git repository can be anonymously cloned from:
+ 
+git clone git://rubyforge.org/koremutake.git

data/lib/koremu.rb

@@ -0,0 +1,295 @@
+require 'delegate'
+
+module Koremutake #:nodoc:
+  Vowels = %W(A E I O U Y)
+  Phonemes = %W(BA BE BI BO BU BY DA DE DI DO DU DY FA FE FI
+    FO FU FY GA GE GI GO GU GY HA HE HI HO HU HY JA JE JI JO JU JY KA KE
+    KI KO KU KY LA LE LI LO LU LY MA ME MI MO MU MY NA NE NI NO NU NY PA
+    PE PI PO PU PY RA RE RI RO RU RY SA SE SI SO SU SY TA TE TI TO TU TY
+    VA VE VI VO VU VY BRA BRE BRI BRO BRU BRY DRA DRE DRI DRO DRU DRY FRA
+    FRE FRI FRO FRU FRY GRA GRE GRI GRO GRU GRY PRA PRE PRI PRO PRU PRY
+    STA STE STI STO STU STY TRA TRE)
+
+  protected
+  def nums_to_phonemes
+    unless @nums_to_phonemes
+      @nums_to_phonemes = {}
+      num = 0
+      Phonemes.each {|phon| @nums_to_phonemes[num] = phon; num += 1}
+    end
+    @nums_to_phonemes
+  end
+
+  def phonemes_to_nums
+    unless @phonemes_to_nums
+      @phonemes_to_nums = {}
+      nums_to_phonemes.map {|k,v| @phonemes_to_nums[v] = k}
+    end
+    @phonemes_to_nums
+  end
+end
+
+# = KoremuStringFunctions
+#
+# The following functions are either available through the
+# KoremuString class, or can be included in other classes. For
+# example, maybe the most natural use would be by including them in
+# the String class. You can include them by typing this in your
+# initialization:
+#
+#   class String; include KoremuStringFunctions; end
+#
+# This way, any arbitrary string can be treated as a KoremuString:
+# 
+#   puts 'fefifofu'.to_ki    # 27494288
+#   puts 'fefifofu'.to_ka    # [13, 14, 15, 16]
+#
+# If you choose not to extend String, you can use KoremuString as a
+# regular class, initializing it with the string in question:
+#
+#   ks = KoremuString.new('fefifofu')
+#
+module KoremuStringFunctions 
+  include Koremutake
+  # Returns an array (<b>not</b> a KoremuArray - A regular Array)
+  # where each of the elements is one of the tokens of the
+  # string. When tokenizing, any particle which does not conform a
+  # Koremutake syllable <i>will be dropped</i> (with a warning being
+  # issued), thus:
+  #
+  #   irb(main):017:0> Koremutake.new('KoremuFixnum').tokenize
+  #   Invalid Koremutake phoneme 'XNU'
+  #   => ["KO", "RE", "MU", "FI"]
+  #
+  # Please refer to the WHAT IS VALID KOREMUTAKE section in the
+  # general documentation for koremu.rb for further information.
+  def tokenize
+    str = self || ''
+    rel = phonemes_to_nums
+    buf = ''
+    res = []
+
+    str.upcase.split(//).each do |chr|
+      buf << chr
+      next unless Vowels.include?(chr)
+      if Phonemes.include?(buf)
+        res << buf
+      else
+        warn "Invalid Koremutake phoneme '#{buf}'" 
+      end
+      buf = ''
+    end
+
+    if str.size > 0 and ! Vowels.include?(str[-1,1].upcase)
+      warn "The received string does not end in a valid syllable: #{str[-1,1].upcase}" 
+    end
+        
+    if res[0] == Phonemes[0] and res.size > 1
+      warn "Dropping leading zero (#{Phonemes[0]}) syllables from #{res} (#{res.size})"
+      res.shift while res[0] == Phonemes[0]
+    end
+    res
+  end
+
+  # Check if the given KoremuString is valid, returning true or
+  # false. If it is <i>not</i> valid, it can still be used -
+  # Non-recognized characters will just be dropped, so:
+  #
+  #   puts KoremuString.new('Koremu Take').to_ki         # 10610353957
+  #   puts KoremuString.new('Koremu Take').to_ki.to_ks   # KOREMUTAKE
+  # 
+  # However, a syllable should be atomic - It should not be split:
+  #
+  #   puts KoremuString.new('Korem Utake').to_ki.to_ks  # KORETAKE
+  # 
+  # Note that the 'BA' particle has a particularity - If it is at the
+  # beginning of the string, it should be dropped, as it means 0. Keep
+  # in mind Koremutake is mainly a way to represent numbers.
+  # i. e. 'BABABABABABE' == 1 == 'BE'. Therefore, a string starting
+  # with 'BA' and with more characters is considered valid.
+  def valid?
+    return false if self.upcase[0,2] == 'BA' and self.size > 2
+    self.tokenize.join == self.upcase
+  end
+
+  # Returns the numeric representation of the KoremuString as a
+  # KoremuFixnum (why <tt>to_ki</tt>? as an analogy to Ruby's own
+  # <tt>to_i</tt>, which returns a Fixnum)
+  def to_ki
+    self.to_ka.to_ki
+  end
+
+  # Returns the KoremuArray representation of the KoremuString.
+  def to_ka
+    rel = phonemes_to_nums
+    arr = self.tokenize.map { |phoneme| rel[phoneme] }
+    arr = [0] if arr.empty?
+
+    KoremuArray.new(arr)
+  end
+end
+
+# = KoremuFixnumFunctions
+# 
+# The following functions are either available through the
+# KoremuFixnum class, or can be included in other classes. For
+# example, maybe the most natural use would be by including them in
+# the Fixnum class. You can include them by typing this in your
+# initialization:
+#
+#   class Fixnum; include KoremuFixnumFunctions; end
+#
+# This way, any arbitrary string can be treated as a KoremuString:
+# 
+#   puts 27494288.to_ks    # FEFIFOFU
+#   puts 27494288.to_ka    # [13, 14, 15, 16]
+#
+# If you choose not to extend Fixnum, you can use KoremuFixnum as a
+# regular class, initializing it with the number in question:
+#
+#   ks = KoremuFixnum.new(1024**4 + 1024**3 + 1024**2 + 1024) # JIBUBAPUDIBA
+# 
+module KoremuFixnumFunctions 
+  include Koremutake
+  def initialize(val) #:nodoc:
+    raise InvalidKoremutake, 'Negative values not defined' if val < 0
+    val = val.to_i || 0
+    super(val)
+  end
+
+  # Returns the KoremuArray representation of the KoremuFixmum
+  def to_ka
+    raise InvalidKoremutake, 'Negative values not defined' if self < 0
+    return KoremuArray.new([0]) if self == 0
+    res = KoremuArray.new
+    num = self
+    while num > 0
+      res.unshift num%128
+      num = KoremuFixnum.new(num/128)
+    end
+    res
+  end
+
+  # Returns the KoremuString representatiion of the KoremuFixnum
+  def to_ks
+    self.to_ka.to_ks
+  end
+end
+
+# = KoremuArrayFunctions
+# 
+# The following functions are either available through the
+# KoremuArray class, or can be included in other classes. For
+# example, maybe the most natural use would be by including them in
+# the Array class. You can include them by typing this in your
+# initialization:
+#
+#   class Array; include KoremuArrayFunctions; end
+#
+# This way, any arbitrary array can be treated as a KoremuArray:
+# 
+#   puts [10,50,120,3].to_ks   # DUMISTABO
+#   puts [10,50,120,3].to_ki   # 21806083
+#
+# If a KoremuArray includes any invalid element, it will be ignored
+# and skipped - The elements should all be integers between 0 and 128:
+#
+#   irb(main):004:0> KoremuArray.new([1,2,10,100,1000]).to_ks.to_ka
+#   Invalid Koremutake element '1000'
+#   => [1, 2, 10, 100]
+#
+# If you choose not to extend Array, you can use KoremuArray as a
+# regular class:
+#
+#   ks = KoremuArray.new([39, 67, 52, 78, 37]) # KOREMUTAKE
+# 
+# Notice the array should be given as the first element in the
+# initialization. This is to keep consistency with the built-in Array
+# behaviour.
+module KoremuArrayFunctions
+  include Koremutake
+  # Check if the given KoremuArray is valid, returning true or
+  # false. If it is <i>not</i> valid, it can still be used -
+  # Non-recognized elements will just be dropped, so:
+  #
+  #   puts KoremuArray.new([39, 67, 52, 200, 78, 37]).to_ki   # 10610353957
+  #   puts KoremuArray.new([39, 67, 52, 78, 37]).to_ki        # 10610353957
+  # 
+  #   puts KoremuArray.new([39, 67, 52, 200, 78, 37]).to_ks   # KOREMUTAKE
+  #   puts KoremuArray.new([39, 67, 52, 78, 37]).to_ks        # KOREMUTAKE
+  # 
+  # In both cases, the '200' is dropped (and a warning issued, of
+  # course).
+  #
+  # Remember that Koremutake is a way to represent numbers - Thus,
+  # although zeros are valid, they would be collapsed at the beginning
+  # - i.e. [0, 0, 0, 0, 1] would become [1]. So, as there is
+  # potentially information loss, 0 is not valid as a first element. 
+  def valid?
+    self.each do |elem|
+      return false unless valid_elem?(elem)
+    end
+    return false if self[0] == 0
+    true
+  end
+
+  # Returns the KoremuString representation of the KoremuArray
+  def to_ks
+    rel = nums_to_phonemes
+    ks = KoremuString.new('')
+
+    # Drop any stream of leading zeroes. However, be consistent: We
+    # are representing values. Return a 0 if we have no value yet
+    self.shift while self[0] == 0
+    self << 0 if self.empty?
+
+    self.each do |num| 
+      unless valid_elem?(num)
+        warn "Invalid Koremutake element '#{num}'"
+        next
+      end
+      ks << rel[num] 
+    end
+    ks
+  end
+
+  # Returns the KoremuFixnum representation of the KoremuArray
+  def to_ki
+    res = 0
+    self.each do |num|
+      unless valid_elem?(num)
+        warn "Invalid Koremutake element '#{num}'"
+        next
+      end
+      res *= 128
+      res += num
+    end
+    KoremuFixnum.new(res)
+  end
+
+  private
+  def valid_elem?(elem) #:nodoc:
+    return false unless elem.is_a? Fixnum
+    return false if elem < 0 or elem > 127
+    true
+  end
+end
+
+# Please refer to the KoremuStringFunctions for documentation
+class KoremuString < String
+  include KoremuStringFunctions
+end
+
+# Please refer to the KoremuArrayFunctions for documentation
+class KoremuArray < Array
+  include KoremuArrayFunctions
+end
+
+# Please refer to the KoremuFixnumFunctions for documentation
+class KoremuFixnum < DelegateClass(Fixnum)
+  include KoremuFixnumFunctions
+end
+
+# Just an exception class, nothing to see here, move on...
+class InvalidKoremutake < Exception
+end

data/test/koremutake_conversions_test.rb

@@ -0,0 +1,80 @@
+require 'koremu'
+require 'test/unit'
+
+class KoremutakeConversionsTest < Test::Unit::TestCase
+  def test_basic_definitions
+    assert Koremutake::Phonemes.size == 128
+  end
+
+  def test_array_validations
+    # KoremuArrays should only accept as valid integer (Fixnum)
+    # elements between 0 and 127. 0 should not be the first value.
+    assert(! KoremuArray.new([5, 10, -5]).valid?,
+           "Negative values passed as valid")
+    assert(! KoremuArray.new([0, 15, 130]).valid?,
+           "Array started with 0 passed as valid")
+    assert(! KoremuArray.new([17, 20, 85, :foo]).valid?,
+           "Array with non-fixnum value passed as valid")
+    assert(! KoremuArray.new([120, 125, 128, 127]).valid?,
+           "Array with values over 127 passed as valid")
+    assert(KoremuArray.new([10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 
+                            120, 127]).valid?,
+           "Perfectly valid array reported as invalid")
+  end
+
+#   def test_tokenizer
+    
+#   end
+
+#   def test_zero_handling
+#     # Are empty/zero values correctly and consistently handled?
+#     arr = KoremuArray.new()
+#     str = KoremuString.new('')
+#     num = KoremuFixnum.new(0)
+
+#     assert num.to_ka == arr, "Zero not correctly converted to empty array"
+#     assert num.to_ks == str
+
+#     assert str.to_ki == num
+#     assert str.to_ka == arr
+
+#     assert arr.to_ki == num
+#     assert arr.to_ks == str
+#   end
+
+  def test_from_random_fixnum
+    100.times do
+      num = KoremuFixnum.new rand(100000)
+      assert(num == num.to_ka.to_ki, 
+             "Fixnum #{num} unsuccessfully converted back from Array")
+      assert(num == num.to_ks.to_ki,
+             "Fixnum #{num} unsuccessfully converted back from String")
+    end
+  end
+
+  def test_from_random_array
+    100.times do
+      arr = KoremuArray.new
+      # Ensure we don't even try to work with empty arrays
+      (1+rand(5)).times {arr << rand(127)}
+
+      # 0 as a first element is not valid
+      arr.shift while arr[0] == 0 and arr.size > 1
+      assert(arr == arr.to_ki.to_ka,
+             "Array #{arr.join('-')} unsuccessfully converted back from Fixnum")
+      assert(arr == arr.to_ks.to_ka,
+             "Array #{arr.join('-')} unsuccessfully converted back from String")
+    end
+  end
+
+  def test_from_random_string
+    100.times do
+      str = KoremuString.new
+      rand(10).times {str << Koremutake::Phonemes[rand(Koremutake::Phonemes.size)]}
+      assert(str = str.to_ki.to_ks,
+             "String #{str} unsuccessfully converted back from Fixnum")
+      assert(str = str.to_ka.to_ks,
+             "String #{str} unsuccessfully converted back from Array")
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: koremutake
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Gunnar Wolf
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-05-21 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: "For us humans, it's always easier to remember a pronounceable string, even if it is meaningless, than to remember a long number. Koremutake is a system you can use to translate any number (of course, particularly suited at long numbers) to a sequence of syllables. Typical uses of Koremutake strings are auto-generated user passwords or URLs.  This module is based in Leon Brocard's String::Koremutake Perl module,  available at  http://search.cpan.org/dist/String-Koremutake/lib/String/Koremutake.pm which is, in turn, based upon Shorl (http://shorl.com/koremutake.php).  Koremutake is a \xC2\xABway to express any large number as a sequence of syllables\xC2\xBB, and the general idea is based in Sean B. Palmer's \xC2\xABMemorable Random String\xC2\xBB  term, http://infomesh.net/2001/07/MeRS/"
+email: gwolf@gwolf.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- test/koremutake_conversions_test.rb
+- lib/koremu.rb
+- Manifest.txt
+- LICENSE
+- README
+- CHANGELOG
+has_rdoc: true
+homepage: http://koremutake.rubyforge.org/
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- charset
+- utf-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: koremutake
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby implementation of the Koremutake Memorable Random Strings
+test_files: []
+