randomexp 0.1.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4ed76ede990b9650d5c9331fe59588474d2cde7e0db2c6d2498419141addcb6
+  data.tar.gz: 68521de0cdd541576301d925caa1f96d5cd880ec5450ee36d2ae1a6bd39a3f47
+SHA512:
+  metadata.gz: '081fcebdacd959ddefc4efa2f4cef6bb33bc90bc7d1ce9fc0eced2125ca2d8452936ee3ec46af276d3b44a8c2e88e4be68479c17c2e7d1b56b8af5ae3ed8f469'
+  data.tar.gz: 3ee83fbb22614b931d84efbbad75330543dd5392f9823f55bd1bd0767aafaf0979e2d79320ab8cbd636a16c9a5c210309599396111a0edbf2e17709baa3b71c7

data/.gitignore

@@ -0,0 +1,9 @@
+coverage/*
+pkg/*
+rdoc/*
+gbin
+vendor
+.bundle
+Gemfile.lock
+.rvmrc
+

data/CHANGELOG

@@ -0,0 +1,20 @@
+== 0.1.4 "Wally Wisoky" 2008-10-08
+* Added realistic name generation (Matt Aimonetti)
+* Fixed loadpath issues (Gerrit Kaiser)
+
+== 0.1.3 "Oological" 2008-07-08
+* Randgen.word should not return a string that does not match /^\w+$/
+
+== 0.1.2 "I'm Not Saying It's Not Beta"
+* Changed rand to Kernel#rand to avoid conflicting with rails (thanks agile!)
+
+== 0.1.1 "Still Quite Beta" 2008-07-20
+* Added Range#of method.
+* Heavy refactoring of the Parser.parse method.
+* Fixed the /\./ bug.
+
+== 0.1.0 "Very Beta" 2008-07-08
+* Initial version of randomexp!
+* Has support for very simple regular expressions.
+* Randgen has limited methods.
+* Dictionary is reading from the local words file.

data/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+group :test do
+  gem 'rspec'
+  gem 'rake'
+  gem 'simplecov'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2021-2022 Naresh Sekar
+
+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/README

@@ -0,0 +1,82 @@
+Randomexp
+    by Naresh Sekar
+    http://github.com/nareshnavinash/randomexp
+
+== DESCRIPTION:
+
+andexp makes it easy to generate random string from most regular expressions.
+
+== REQUIREMENTS:
+ 
+* none!
+ 
+== INSTALL:
+ 
+  $ sudo gem install randomexp
+
+== USAGE:
+
+Randomexp adds the #generate (or #gen, for short) method to the Regexp class,
+which generates a 'random' string that will match your regular expression.
+
+  /abc|def/.gen
+    # => "def"
+
+== Valid Regexp's
+
+Randomexp can only generate matching string from simple regular expression.
+Except for a few circumstances, wildcards are generally not allowed in the
+regular expression.  is pretty domain specific, so trying to guess when to
+terminate a random pattern would produce unhelpful data:
+
+  >> /Aa{3}h*!/.gen
+      # => RuntimeError: Sorry, "h*" is too vague, try setting a range: "h{0,3}"
+  >> /Aa{3}h{3,15}!/.gen
+      => "Aaaahhhhh!"
+
+  >> /(never gonna (give you up|let you down), )*/.gen
+      => RuntimeError: Sorry, "(...)*" is too vague, try setting a range: "(...){0, 3}"
+  >> /(never gonna (give you up|let you down), ){3,5}/.gen
+      => "never gonna give you up, never gonna let you down, never gonna give you up, never gonna give you up, "
+
+The exception being word characters (\w), which generate a random word from the Dictionary class.
+
+  >> /\w+/.gen
+      => "groveling"
+
+= Primitives & Complex matches
+
+The single character matchers supported are words(\w), whitespace(\s), and digits(\d).
+
+  >> /\d{50}/.gen
+      => "50315410741096763188525493528315906035878741451037"
+
+When a multiplicity constraint is placed on a word character, a word with the valid length is generated.
+
+  >> /\w{10}/.gen  # a word with 10 letters
+      => "Chaucerism"
+
+  >> /\w{5,15}/.gen
+      => "cabalistic"
+
+Complex matchers use the [:...:] syntax within the regular expression.
+
+  >> /[:sentence:]/.gen
+      => "Nonhearer demetricize toppiece filicic possessedness rhodizite zoomagnetism earwigginess steady"
+
+Complex matchers can also be added by extending the Randgen class.
+
+  class Randgen
+    def self.serial_number(options = {})
+      /XX\d{4}-\w-\d{5}/.gen
+    end
+  end
+
+  >> /[:serial_number:]/.gen
+      => "XX3770-M-33114"
+
+= Dictionary
+
+The Dictionary loads the local users' words file, allowing randomly generated words to be chosen from
+thousands of entries to the words file.  Words are mapped by their length to allow words to be randomly
+chosen based on size.

data/Rakefile

@@ -0,0 +1,76 @@
+require 'rubygems/package_task'
+require 'rubygems/specification'
+require 'date'
+require 'rspec/core/rake_task'
+
+PROJECT_NAME = "randomexp"
+GEM = "randomexp"
+GEM_VERSION = "0.1.6"
+AUTHOR = "Naresh Sekar"
+EMAIL = "nareshnavinash@gmail.com"
+HOMEPAGE = "http://github.com/nareshnavinash/randomexp"
+TITLE = "Randomexp Gem"
+SUMMARY = "Library for generating random strings."
+FILES = %w(LICENSE README Rakefile TODO CHANGELOG) + Dir.glob("{lib,spec}/**/*") + Dir.glob("wordlists/**/*")
+RDOC_FILES = %w(LICENSE README Rakefile TODO CHANGELOG) + Dir.glob("lib/**/*")
+
+task :default => :specs
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+
+  s.require_path = 'lib'
+  s.autorequire = GEM
+  s.files = FILES
+end
+
+Gem::PackageTask.new(spec) do |package|
+  package.gem_spec = spec
+  package.need_zip = true
+  package.need_tar = true
+end
+
+desc "install the gem locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+##############################################################################
+# rSpec & rcov
+##############################################################################
+desc "Run all unit specs"
+RSpec::Core::RakeTask.new("specs:unit") do |t|
+  t.rspec_opts = ["--format", "documentation", "--colour"]
+  t.pattern = "spec/unit/**/*_spec.rb"
+  t.rcov_opts = %w[--sort coverage --sort-reverse]
+  t.rcov_opts << '--only-uncovered'
+  t.rcov_opts << '--output coverage/unit'
+
+end
+
+desc "Run all regression specs"
+RSpec::Core::RakeTask.new("specs:regression") do |t|
+  t.rspec_opts = ["--format", "documentation", "--colour"]
+  t.pattern = "spec/regression/**/*_spec.rb"
+  t.rcov_opts = %w[--sort coverage --sort-reverse]
+  t.rcov_opts << '--only-uncovered'
+  t.rcov_opts << '--output coverage/integration'
+end
+
+task :specs => ['specs:unit', 'specs:regression']

data/TODO

@@ -0,0 +1,4 @@
+== Todo list
+* add a ~/.randomexp dir for configuration
+* add [] syntax: /[aeiou]{4}/.gen
+* more generators for Randgen

data/lib/randomexp/core_ext/array.rb

@@ -0,0 +1,5 @@
+class Array
+  def pick_rand_value
+    at Kernel.rand(size)
+  end
+end

data/lib/randomexp/core_ext/integer.rb

@@ -0,0 +1,5 @@
+class Integer
+  def of
+    (1..self).to_a.map { yield }
+  end
+end

data/lib/randomexp/core_ext/range.rb

@@ -0,0 +1,9 @@
+class Range
+  def pick_rand_value
+    to_a.pick_rand_value
+  end
+
+  def of
+    pick_rand_value.of { yield }
+  end
+end

data/lib/randomexp/core_ext/regexp.rb

@@ -0,0 +1,7 @@
+class Regexp
+  def generate
+    Randomexp.new(source).reduce
+  end
+
+  alias_method :gen, :generate
+end

data/lib/randomexp/core_ext.rb

@@ -0,0 +1,6 @@
+dir = File.dirname(__FILE__)
+
+require dir + '/core_ext/array'
+require dir + '/core_ext/integer'
+require dir + '/core_ext/range'
+require dir + '/core_ext/regexp'

data/lib/randomexp/dictionary.rb

@@ -0,0 +1,32 @@
+class Randomexp::Dictionary
+  def self.file_paths
+    @dictionary_path ||= %w[/usr/share/dict/words /usr/dict/words ~/.dict/words]
+  end
+
+  def self.register(path)
+    file_paths.unshift(path)
+  end
+
+  def self.load_dictionary
+    if path = file_paths.detect {|path| File.exists?(File.expand_path(path)) }
+      File.read(path).split
+    else
+      raise "Words file not found. Check if it is installed in (/usr/share/dict/words or /usr/dict/words) "
+    end
+  end
+
+  def self.words(options = {})
+    if options.has_key?(:length)
+      words_by_length[options[:length]]
+    else
+      @@words ||= load_dictionary
+    end
+  end
+
+  def self.words_by_length
+    @@words_by_length ||= begin
+      hash = Hash.new {|h,k| h[k] = [] }
+      words.inject(hash) {|h, w| h[w.size] << w; h }
+    end
+  end
+end

data/lib/randomexp/parser.rb

@@ -0,0 +1,97 @@
+class Randomexp
+  class Parser
+    def self.parse(source)
+      case
+      when source =~ /^(.*)(\*|\*\?|\+|\+\?|\?)$/ && balanced?($1, $2)
+        parse_quantified($1, $2.to_sym)                                 # ends with *, +, or ?: /(..)?/
+      when source =~ /^(.*)\{(\d+)\,(\d+)\}$/ && balanced?($1, $2)
+        parse_quantified($1, ($2.to_i)..($3.to_i))                      #ends with a range: /(..){..,..}/
+      when source =~ /^(.*)\{(\d+)\}$/ && balanced?($1, $2)
+        parse_quantified($1, $2.to_i)                                   #ends with a range: /..(..){..}/
+      when source =~ /^\((.*)\)\((.*)\)$/ && balanced?($1, $2)
+        union(parse($1), parse($2))                                     #balanced union: /(..)(..)/
+      when source =~ /^(\(.*\))\|(\(.*\))$/ && balanced?($1, $2)
+        intersection(parse($1), parse($2))                              #balanced intersection: /(..)|(..)/
+      when source =~ /^(.*)\|(.*)$/ && balanced?($1, $2)
+        intersection(parse($1), parse($2))                              #implied intersection: /..|../
+      when source =~ /^(.*)\|\((\(.*\))\)$/ && balanced?($1, $2)
+        intersection(parse($1), parse($2))                              #unbalanced intersection: /(..)|((...))/
+      when source =~ /^(.+)(\(.*\))$/ && balanced?($1, $2)
+        union(parse($1), parse($2))                                     #unbalanced union: /...(...)/
+      when source =~ /^\((.*)\)$/ && balanced?($1)
+        union(parse($1))                                                #explicit group: /(..)/
+      when source =~ /^([^()]*)(\(.*\))$/ && balanced?($1, $2)
+        union(parse($1), parse($2))                                     #implied group: /..(..)/
+      when source =~ /^(.*)\[\:(.*)\:\]$/
+        union(parse($1), random($2))                                    #custom random: /[:word:]/
+      when source =~ /^(.*)\\([wsdc])$/
+        union(parse($1), random($2))                                    #reserved random: /..\w/
+      when source =~ /^(.*)\\(.)$/ || source =~ /(.*)(.|\s)$/
+        union(parse($1), literal($2))                                   #end with literal or space: /... /
+      else
+        nil
+      end
+    end
+
+    def self.parse_quantified(source, multiplicity)
+      case source
+      when /^[^()]*$/     then quantify_rhs(parse(source), multiplicity)    #implied union: /...+/
+      when /^(\(.*\))$/   then quantify(parse(source), multiplicity)        #group: /(...)?/
+      when /^(.*\))$/     then quantify_rhs(parse(source), multiplicity)    #implied union: /...(...)?/
+      when /^(.*[^)]+)$/  then quantify_rhs(parse(source), multiplicity)    #implied union: /...(...)...?/
+      else quantify(parse(source), multiplicity)
+      end
+    end
+
+    class << self
+      alias_method :[], :parse
+    end
+
+    def self.balanced?(*args)
+      args.all? {|s| s.count('(') == s.count(')')}
+    end
+
+    def self.quantify_rhs(sexp, multiplicity)
+      case sexp.first
+      when :union
+        rhs = sexp.pop
+        sexp << quantify(rhs, multiplicity)
+      else
+        quantify(sexp, multiplicity)
+      end
+    end
+
+    def self.quantify(lhs, sym)
+      [:quantify, lhs, sym]
+    end
+
+    def self.union(lhs, *rhs)
+      if lhs.nil?
+        union(*rhs)
+      elsif rhs.empty?
+        lhs
+      elsif lhs.first == :union
+        rhs.each {|s| lhs << s}
+        lhs
+      else
+        [:union, lhs, *rhs]
+      end
+    end
+
+    def self.intersection(lhs, rhs)
+      if rhs.first == :intersection
+        [:intersection, lhs] + rhs[1..-1]
+      else
+        [:intersection, lhs, rhs]
+      end
+    end
+
+    def self.random(char)
+      [:random, char.to_sym]
+    end
+
+    def self.literal(word)
+      [:literal, word]
+    end
+  end
+end

data/lib/randomexp/randgen.rb

@@ -0,0 +1,78 @@
+class Randgen
+  WORDS_PER_SENTENCE = 3..20
+  SENTENCES_PER_PARAGRAPH = 3..8
+
+  def self.bool(options = {})
+    ['true', 'false'].pick_rand_value
+  end
+
+  def self.lchar(options = {})
+    ('a'..'z').to_a.pick_rand_value
+  end
+
+  def self.uchar(options = {})
+    ('A'..'Z').to_a.pick_rand_value
+  end
+
+  def self.char(options = {})
+    [lchar, uchar].pick_rand_value
+  end
+
+  def self.whitespace(options = {})
+    ["\t", "\n", "\r", "\f"].pick_rand_value
+  end
+
+  def self.digit(options = {})
+    ('0'..'9').to_a.pick_rand_value
+  end
+
+  def self.alpha_numeric(options = {})
+    [char, digit].pick_rand_value
+  end
+
+  def self.word(options = {})
+    begin
+      word = Randomexp::Dictionary.words(options).pick_rand_value
+      word ||= options[:length].of { alpha_numeric }.join
+    end until word =~ /^\w+$/
+
+    word
+  end
+
+  def self.first_name(options = {})
+    RealName.first_names(options).pick_rand_value
+  end
+
+  def self.surname(options = {})
+    RealName.surnames(options).pick_rand_value
+  end
+
+  class << self
+    alias_method :last_name, :surname
+  end
+
+  def self.name(options = {})
+    "#{first_name(options)} #{surname(options)}"
+  end
+
+  def self.email(options = {})
+    domain = options.fetch(:domain, "#{word(options)}.example.org")
+    "#{word(options)}@#{domain}"
+  end
+
+  def self.sentence(options = {})
+    ((options[:length] || WORDS_PER_SENTENCE.pick_rand_value).of { word } * " ").capitalize
+  end
+
+  def self.paragraph(options = {})
+    ((options[:length] || SENTENCES_PER_PARAGRAPH.pick_rand_value).of { sentence } * ".  ") + "."
+  end
+
+  def self.phone_number(options = {})
+    case options[:length]
+    when 7  then  /\d{3}-\d{4}/.gen
+    when 10 then  /\d{3}-\d{3}-\d{4}/.gen
+    else          /(\d{3}-)?\d{3}-\d{4}/.gen
+    end
+  end
+end

data/lib/randomexp/reducer.rb

@@ -0,0 +1,102 @@
+class Randomexp
+  class Reducer
+    def self.reduce(sexp, quantity = nil)
+      send(sexp.first, sexp[1..-1], quantity)
+    end
+
+    class << self
+      alias_method :[], :reduce
+    end
+
+    def self.quantify(sexp, old_quantity)
+      reduce(*sexp)
+    end
+
+    def self.random(sexpish, quantity)
+      case s = sexpish.first
+      when :w then char(quantity)
+      when :s then whitespace(quantity)
+      when :d then digit(quantity)
+      else randgen(s, quantity)
+      end
+    end
+
+    def self.literal(cell, quantity = nil)
+      case quantity
+      when :'?'         then ([''] + cell).pick_rand_value
+      when :+, :'+?'    then raise "Sorry, \"#{cell * ''}+\" is too vague, try setting a range: \"#{cell * ''}{1,3}\""
+      when :*, :'*?'    then raise "Sorry, \"#{cell * ''}*\" is too vague, try setting a range: \"#{cell * ''}{0,3}\""
+      when Range        then quantity.pick_rand_value.of { cell * '' } * ''
+      when Integer      then quantity.of { cell * '' } * ''
+      when nil          then cell * ''
+      end
+    end
+
+    def self.intersection(cell, quantity)
+      case quantity
+      when :'?'       then ['', cell.map {|s| reduce(s)}.pick_rand_value].pick_rand_value
+      when :+, :'+?'  then raise "Sorry, \"((...)|(...))+\" is too vague, try setting a range: \"((...)|(...)){1, 3}\""
+      when :*, :'*?'  then raise "Sorry, \"((...)|(...))*\" is too vague, try setting a range: \"((...)|(...)){0, 3}\""
+      when Range      then quantity.pick_rand_value.of { cell.map {|s| reduce(s)}.pick_rand_value } * ''
+      when Integer    then quantity.of { cell.map {|s| reduce(s)}.pick_rand_value } * ''
+      when nil        then cell.map {|s| reduce(s)}.pick_rand_value
+      end
+    end
+
+    def self.union(cell, quantity)
+      case quantity
+      when :'?'       then ['', cell.map {|s| reduce(s)} * ''].pick_rand_value
+      when :+, :'+?'  then raise "Sorry, \"(...)+\" is too vague, try setting a range: \"(...){1, 3}\""
+      when :*, :'*?'  then raise "Sorry, \"(...)*\" is too vague, try setting a range: \"(...){0, 3}\""
+      when Range      then quantity.pick_rand_value.of { cell.map {|s| reduce(s)} * '' } * ''
+      when Integer    then quantity.of { cell.map {|s| reduce(s)} * '' } * ''
+      when nil        then cell.map {|s| reduce(s)} * ''
+      end
+    end
+
+    def self.char(quantity)
+      case quantity
+      when :'?'       then ['', Randgen.char].pick_rand_value
+      when :+, :'+?'  then Randgen.word
+      when :*, :'*?'  then ['', Randgen.word].pick_rand_value
+      when Range      then Randgen.word(:length => quantity.pick_rand_value)
+      when 1, nil     then Randgen.char
+      when Integer    then Randgen.word(:length => quantity)
+      end
+    end
+
+    def self.whitespace(quantity)
+      case quantity
+      when :'?'       then ['', Randgen.whitespace].pick_rand_value
+      when :+, :'+?'  then raise "Sorry, \"\\s+\" is too vague, try setting a range: \"\\s{1, 5}\""
+      when :*, :'*?'  then raise "Sorry, \"\\s*\" is too vague, try setting a range: \"\\s{0, 5}\""
+      when Range      then quantity.pick_rand_value.of { Randgen.whitespace } * ''
+      when Integer    then quantity.of { Randgen.whitespace } * ''
+      when nil        then Randgen.whitespace
+      end
+    end
+
+    def self.digit(quantity)
+      case quantity
+      when :'?'       then ['', Randgen.digit].pick_rand_value
+      when :+, :'+?'  then raise "Sorry, \"\\d+\" is too vague, try setting a range: \"\\d{1, 5}\""
+      when :*, :'*?'  then raise "Sorry, \"\\d*\" is too vague, try setting a range: \"\\d{0, 5}\""
+      when Range      then quantity.pick_rand_value.of { Randgen.digit } * ''
+      when Integer    then quantity.of { Randgen.digit } * ''
+      when nil        then Randgen.digit
+      end
+    end
+
+    def self.randgen(args, quantity)
+      method_name, _ = *args
+      case quantity
+      when :'?'       then ['', Randgen.send(method_name, :length => 1)].pick_rand_value
+      when :+, :'+?'  then Randgen.send(method_name)
+      when :*, :'*?'  then ['', Randgen.send(method_name)].pick_rand_value
+      when Range      then Randgen.send(method_name, :length => quantity.pick_rand_value)
+      when 1, nil     then Randgen.send(method_name)
+      when Integer    then Randgen.send(method_name, :length => quantity)
+      end
+    end
+  end
+end

data/lib/randomexp/version.rb

@@ -0,0 +1,3 @@
+class Randomexp
+  VERSION = "0.1.7"
+end

data/lib/randomexp/wordlists/female_names.rb

@@ -0,0 +1,25 @@
+class RealName
+
+  def self.load_female_first_names
+    dir = File.dirname(__FILE__)
+    if File.exists?("#{dir}/../../../wordlists/female_names")
+      File.read("#{dir}/../../../wordlists/female_names").split
+    else
+      raise "words file not found"
+    end
+  end
+
+  def self.female_first_names(options = {})
+    if options.has_key?(:length)
+      female_first_names_by_length[options[:length]]
+    else
+      @@female_first_names ||= load_female_first_names
+    end
+  end
+
+  def self.female_first_names_by_length
+    @@female_first_names_by_length ||= begin
+      female_first_names.inject(Hash.new {|h,k| h[k] = [] }) {|h, w| (h[w.size] ||= []) << w; h }
+    end
+  end
+end

data/lib/randomexp/wordlists/male_names.rb

@@ -0,0 +1,25 @@
+class RealName
+
+  def self.load_male_first_names
+    dir = File.dirname(__FILE__)
+    if File.exists?("#{dir}/../../../wordlists/male_names")
+      File.read("#{dir}/../../../wordlists/male_names").split
+    else
+      raise "words file not found"
+    end
+  end
+
+  def self.male_first_names(options = {})
+    if options.has_key?(:length)
+      male_first_names_by_length[options[:length]]
+    else
+      @@male_first_names ||= load_male_first_names
+    end
+  end
+
+  def self.male_first_names_by_length
+    @@male_first_names_by_length ||= begin
+      male_first_names.inject(Hash.new {|h,k| h[k] = [] }) {|h, w| (h[w.size] ||= []) << w; h }
+    end
+  end
+end

data/lib/randomexp/wordlists/real_name.rb

@@ -0,0 +1,35 @@
+class RealName
+  def self.load_surnames
+    dir = File.dirname(__FILE__)
+    if File.exists?("#{dir}/../../../wordlists/surnames")
+      File.read("#{dir}/../../../wordlists/surnames").split
+    else
+      raise "words file not found"
+    end
+  end
+
+  def self.surnames(options = {})
+    if options.has_key?(:length)
+      surnames_by_length[options[:length]]
+    else
+      @@surnames ||= load_surnames
+    end
+  end
+
+  def self.surnames_by_length
+    @@surnames_by_length ||= begin
+      surnames.inject(Hash.new {|h,k| h[k] = [] }) {|h, w| (h[w.size] ||= []) << w; h }
+    end
+  end
+
+  def self.first_names(options)
+    case options[:gender].to_s
+    when /^male/i
+      male_first_names(options)
+    when /^female/i
+      female_first_names(options)
+    else
+      [male_first_names(options), female_first_names(options)].pick_rand_value
+    end
+  end
+end