usernamegen 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6470180a69432a0dbe28897cffeb5e623c5d9709
-  data.tar.gz: 3885e1ed4209b76453d412fd8e9b16819126b3c5
+  metadata.gz: 9f0ca1cfb4a4ddf8b04cd0e9db2a5822ac8044e7
+  data.tar.gz: f86c87036862f9562c317beea6963058a1315320
 SHA512:
-  metadata.gz: 4320a755335eeb1ce9872eab670a0291c88e054248583eb3e1406d89de3c708922e1d1a814416e6121606a2a75a190f40959b289e974707033512ab5ae642367
-  data.tar.gz: b92cce25e590fcd6306b6151949cc003c9cc30fdd324d8896c77aab0e3ff00e3d5070277c390247eac70d31b3365e22b924d2a653d0a6371613dad4d83704bb4
+  metadata.gz: 1d84ace35ce78f6b9a7c626406701c4f4f127c17d5f7a3f55a0b975178e4aa963c44c6823741aa29675920d3c417fac1a0c70bde638d7631811848c7872a617c
+  data.tar.gz: cfc47f6d92bba727d15718772fbef456172fc8950072bc1c105bdc6b9c6e4cfcc6d7794cb56d4c86465d1e1f820a9ff5cac74c6d5ee68c5b53a6d70efe2043d2

data/README.md

@@ -18,6 +18,7 @@ This gem uses two lists (descriptive words and nouns) and multiplies them with e
   * Chemical Rabbit
   * [surprise me](https://de.gamesplanet.com/namegen)
 
+
 ## Installation
 
 Requires Ruby >= 1.9.3
@@ -30,21 +31,88 @@ Or list in your Gemfile
 
     gem 'usernamegen'
 
+
 ## Usage
 
-You can use the generator class like so:
+You can use the generator class like so (also see Caching/Benchmark):
+
+```ruby
+# Assembles whole list each time (yielding more than 1 million strings, cache them!)
+Usernamegen.all
+
+# Samples one item from both lists and assembles them (fast)
+Usernamegen.one
+
+# Uses multiple `#one` calls to give you an array of names without having to take a subset of `#all`.
+# You may get duplicate names! This is just a shorthand as simple as `AMOUNT.times.map{ one }`.
+Usernamegen.some(10)
+
+# Assembles a list for a given thing (huge result set)
+Usernamegen.all_for_thing("thing")
+
+# Assembles a list for a given description (huge result set)
+Usernamegen.all_for_desc("description")
+```
+
+Initiating the class will instantly load the two text files into memory (as array). You can also use the instance approach if you have multiple calls to the generator.
+
+```ruby
+generator = Usernamegen.new(opts = {}, &formatter)
+generator.one
+generator.all_for_thing
+```
+
+## Custom format
+
+You can return usernames in your custom format at all methods. Just pass a block, e.g.:
+
+```ruby
+Usernamegen.one { |combination| combination.join("-").downcase }
+=> "able-action"
+```
 
-    # load files and assembles list each time (yielding more than 1 million strings, cache them!)
-    Usernamegen.all
+If you use the instance approach you may also want to redefine the default format.
 
-    # same as #all but returns random entry
-    Usernamegen.one
+```ruby
+generator = Usernamegen.new format: ->(combination){ combination.join("-").downcase }
 
+# or sugar version
+generator = Usernamegen.new { |combination| combination.join("-").downcase }
 
-You can find an example ActiveRecord model + rake import tasks in the following gist.
+generator.one
+=> "malicious-expert"
+```
 
+
+## Options
+
+The generator class has a few options but except for the format option there is little reason for you to change them.
+
+```ruby
+Usernamegen.new({
+  # The default format (note that passing a block to #new will overwrite the hash option)
+  format: ->(combination){ combination.join(" ").titleize },
+
+  # This option only exists for testing
+  rng: ::SecureRandom.urlsafe_base64(128),
+
+  # You could point to different word lists here
+  descriptions: "#{ROOT}/lib/usernamegen/descriptions.txt",
+  things: "#{ROOT}/lib/usernamegen/things.txt",
+})
+```
+
+
+## Caching / Benchmark
+
+While the `#one` and `#some` methods are quite fast it's still advised to import the combinations to your database in a batch fashion opposed to generate single names on the fly.
+
+We suggest a separate _Codename_ model and assign a free name to a user when he needs one (usually upon registration or first post). You can find an example ActiveRecord model + rake import tasks in the following gist.
+
+  * [» Benchmarks](https://gist.github.com/2called-chaos/a0ea619fdc7ef245719d)
   * [» ActiveRecord model example and rake import task](https://gist.github.com/2called-chaos/46705324d913e4f9cc6b)
 
+
 ## Testing
 
 Just `bundle` and invoke `rake`.

data/Rakefile

@@ -1,5 +1,4 @@
 require "bundler/gem_tasks"
-
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
@@ -7,3 +6,196 @@ Rake::TestTask.new do |t|
 end
 
 task :default => [:test]
+
+desc "Gives you 10 random names (5 with default/5 with custom format)"
+task :example do
+  require 'usernamegen'
+  instance = Usernamegen.new
+  5.times { puts instance.one }
+  instance = Usernamegen.new {|a| a.join("-").downcase }
+  puts instance.some(5)
+end
+
+desc "Gives you ALL names"
+task :all_names do
+  require 'usernamegen'
+  Usernamegen.new.all.each{|n| puts n }
+end
+
+desc "Run performance benchmarks with benchmark-ips tests"
+task :benchmark do
+  require 'usernamegen'
+  require 'benchmark'
+  require 'benchmark/ips'
+
+  # initial load
+  instance = nil
+  Benchmark.benchmark do |x|
+    x.report("initial load") { instance = Usernamegen.new }
+  end
+
+  # misc
+  Benchmark.ips do |x|
+    x.time = 5
+    x.warmup = 2
+
+    # loading files (cached since we loaded already once)
+    x.report("::new") do |times|
+      i = 0
+      while i < times
+        Usernamegen.new
+        i += 1
+      end
+    end
+  end ; puts
+
+  # one
+  Benchmark.ips do |x|
+    x.time = 5
+    x.warmup = 2
+
+    x.report("::one") do |times|
+      i = 0
+      while i < times
+        Usernamegen.one
+        i += 1
+      end
+    end
+
+    x.report("#one") do |times|
+      i = 0
+      while i < times
+        instance.one
+        i += 1
+      end
+    end
+
+    x.compare!
+  end ; puts
+
+  # instance compare
+  Benchmark.ips do |x|
+    x.time = 5
+    x.warmup = 2
+
+    x.report("#one") do |times|
+      i = 0
+      while i < times
+        instance.one
+        i += 1
+      end
+    end
+
+    x.report("#some(1)") do |times|
+      i = 0
+      while i < times
+        instance.some(1)
+        i += 1
+      end
+    end
+
+    x.report("#some(10)") do |times|
+      i = 0
+      while i < times
+        instance.some(10)
+        i += 1
+      end
+    end
+
+    x.report("#all") do |times|
+      i = 0
+      while i < times
+        instance.all
+        i += 1
+      end
+    end
+
+    x.report("#all_for_thing") do |times|
+      i = 0
+      while i < times
+        instance.all_for_thing("foo")
+        i += 1
+      end
+    end
+
+    x.report("#all_for_desc") do |times|
+      i = 0
+      while i < times
+        instance.all_for_desc("bar")
+        i += 1
+      end
+    end
+
+    x.compare!
+  end ; puts
+end
+
+
+desc "test benchmark (for while developing)"
+task :testbench do
+  require 'usernamegen'
+  require 'benchmark'
+  require 'benchmark/ips'
+
+  # initial load
+  Benchmark.ips do |x|
+    x.time = 5
+    x.warmup = 2
+    instance = Usernamegen.new
+
+    x.report("#one") do |times|
+      i = 0
+      while i < times
+        instance.one
+        i += 1
+      end
+    end
+
+    x.report("#some(1)") do |times|
+      i = 0
+      while i < times
+        instance.some(1)
+        i += 1
+      end
+    end
+
+    x.report("#some(10)") do |times|
+      i = 0
+      while i < times
+        instance.some(10)
+        i += 1
+      end
+    end
+
+    x.compare!
+  end ; puts
+end
+
+
+desc "test benchmark (for while developing)"
+task :testbench do
+  require 'usernamegen'
+  require 'benchmark'
+  require 'benchmark/ips'
+
+  # initial load
+  instance = nil
+  Benchmark.benchmark do |x|
+    x.report("initial load") { instance = Usernamegen.new }
+  end
+
+  Benchmark.ips do |x|
+    x.time = 5
+    x.warmup = 2
+
+    x.report("???") do |times|
+      i = 0
+      while i < times
+        ###
+        i += 1
+      end
+    end
+
+    x.compare!
+  end
+end

data/lib/usernamegen/version.rb

@@ -1,3 +1,3 @@
 class Usernamegen
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/usernamegen.rb

@@ -6,27 +6,32 @@ require "active_support/core_ext"
 class Usernamegen
   ROOT = File.expand_path("../..", __FILE__)
 
-  def self.one opts = {}
-    new(opts).one
+  def self.one(opts = {}, &block)
+    new(opts).one(&block)
   end
 
-  def self.all opts = {}
-    new(opts).all
+  def self.some(amount, opts = {}, &block)
+    new(opts).some(amount, &block)
   end
 
-  def self.all_for_thing thing, opts = {}
-    new(opts).all_for_thing(thing)
+  def self.all(opts = {}, &block)
+    new(opts).all(&block)
   end
 
-  def self.all_for_desc desc, opts = {}
-    new(opts).all_for_desc(desc)
+  def self.all_for_thing(thing, opts = {}, &block)
+    new(opts).all_for_thing(thing, &block)
   end
 
-  def initialize opts = {}
+  def self.all_for_desc(desc, opts = {}, &block)
+    new(opts).all_for_desc(desc, &block)
+  end
+
+  def initialize opts = {}, &block
     @opts = opts.reverse_merge({
       descriptions: "#{ROOT}/lib/usernamegen/descriptions.txt",
       things: "#{ROOT}/lib/usernamegen/things.txt",
       rng: ::SecureRandom.urlsafe_base64(128),
+      format: block || ->(combination){ combination.join(" ").titleize },
     })
     @descriptions = load_file @opts[:descriptions]
     @things = load_file @opts[:things]
@@ -36,19 +41,24 @@ class Usernamegen
     File.read(file).split("\n").map(&:strip).reject(&:blank?)
   end
 
-  def one
-    [@descriptions.sample(1, random: @opts[:rng]), @things.sample(1, random: @opts[:rng])].join(" ").titleize
+  def one &block
+    combination = [@descriptions.sample(1, random: @opts[:rng]), @things.sample(1, random: @opts[:rng])]
+    (block || @opts[:format]).call(combination)
+  end
+
+  def some amount, &block
+    amount.times.map{ one(&block) }
   end
 
-  def all
-    @descriptions.product(@things).map{|combination| combination.join(" ").titleize }
+  def all &block
+    @descriptions.product(@things).map(&(block || @opts[:format]))
   end
 
-  def all_for_thing thing
-    @descriptions.product([thing]).map{|combination| combination.join(" ").titleize }
+  def all_for_thing thing, &block
+    @descriptions.product([thing]).map(&(block || @opts[:format]))
   end
 
-  def all_for_desc desc
-    [desc].product(@things).map{|combination| combination.join(" ").titleize }
+  def all_for_desc desc, &block
+    [desc].product(@things).map(&(block || @opts[:format]))
   end
 end

data/test/usernamegen_test.rb

@@ -10,6 +10,15 @@ class TestUsernamegen < Minitest::Test
     end
   end
 
+  def test_default_format
+    assert_match /^([A-Z][a-z]*((\s)))+[A-Z][a-z]*$/, Usernamegen.one
+  end
+
+  def test_custom_format
+    username = Usernamegen.one { |username| username.join("-").downcase }
+    assert_match /^([a-z]*((-)))+[a-z]*$/, username
+  end
+
   def test_amount_of_names
     # don't forget to update README as well!
     assert_equal Usernamegen.all.count, 1_367_631

data/usernamegen.gemspec

@@ -23,4 +23,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "minitest"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "benchmark-ips"
 end

metadata

@@ -1,69 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: usernamegen
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Sven Pachnit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-21 00:00:00.000000000 Z
+date: 2015-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.3.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.3.8
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: This gem uses two lists (descriptive words and nouns) and multiplies
@@ -75,8 +89,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -97,17 +111,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Usernamegen - a not so serious name generator