masked-identifier 0.0.2 → 0.0.3

data/README.markdown

@@ -0,0 +1,107 @@
+# Masked Identifier
+
+  Masked Identifier makes it easy to add a non-incrementing identifier to any ActiveRecord object.
+
+## Installation
+
+  Add ```gem 'masked-identifier'``` to your Rails project Gemfile.
+
+  Verified to work with Rails 3.1.0.rc5.  Let me know if you use it in older versions of Rails.
+
+## Usage
+
+  Add a column named 'masked_identifier' to the table of the ActiveRecord object that you want to
+be able to refer to using a masked identifier.  Also, don't forget to add an index for this new 
+column
+
+```ruby
+def change
+  add_column :users, :masked_identifier
+  add_index :users, :masked_identifier
+end
+```
+
+  Add ```has_masked_identifier``` to the ActiveRecord object
+
+```ruby
+class User < ActiveRecord::Base
+  has_masked_identifier
+end
+```
+
+  Create a new object and you'll see that a masked identifier has been added
+
+```ruby
+user = User.create!(name: 'Matt')
+user.masked_identifier
+=> "2xfYgm1pQ8"
+```
+
+  Lookup users based on the object's ```masked_identifier``` property
+
+```ruby
+user = User.find_by_masked_identifier("2xfYgm1pQ8")
+user.name
+=> "Matt"
+```
+
+  If you want ```User``` to automatically return ```masked_identifier``` instead of ```id``` when 
+```to_param``` is called, you can override ```to_param``` in the ```User``` class
+
+```ruby
+class User < ActiveRecord::Base
+  def to_param
+    self.masked_identifier
+  end
+end
+```
+
+## Options
+
+  Masked Identifier lets you edit a number of settings by including an options hash following 
+```has_masked_identifier```:
+
+```ruby
+class User < ActiveRecord::Base
+  has_masked_identifier length: 8, property: 'mid', charset: %w{ a b c d }, attempts: 10
+end
+```
+
+_Note: This is for example purposes only.  You should never use a charset this small.  You run the
+risk of running out of possible unique values and throwing a CodeGenerator::TooManyFailedAttempts
+error._
+
+* ```length``` - the number of characters to include in the masked identifier.  _Note: As the
+  length is increased, the number of possible unique masked identifiers also increases_
+
+* ```property``` - override the default ```masked_identifier``` property with a custom named
+  property.  _Don't forget you'll need to use this custom name in your database migration too_
+
+* ```charset``` - override the defailt character set used when generating masked identifiers 
+  (default character set includes a-z, A-Z, and 0-9).  _Note: As the size of the character set is
+  increased, the number of possible unique masked identifiers also increases_
+
+* ```attempts``` - override the number of attempts to identifiy a unique masked identifier.  Each
+  'attempt' requires one SELECT query on the database.  If you have a sufficiently large charset
+  and length >=10 chars, your app should rarely require more than one attempt
+
+## Exceptions
+
+  Make sure you handle the following possible exceptions in your applicaiton:
+
+* ```[YourActiveRecordObject]::InvalidProperty``` - if object does not have a 
+  ```masked_identifier``` property (or the custom property passed to the ```property``` option 
+    does not exist)
+
+* ```CodeGenerator::TooManyFailedAttempts``` - if unable to find a unique code to user as a masked
+  identifier
+
+* ```CodeGenerator::InvalidAttemptsValue``` - if the value provided to the ```attempts``` option 
+  is not an Integer or < 1
+
+* ```CodeGenerator::InvalidCodeLength``` - if the value provided to the ```length``` option is not 
+  an ```Integer``` or is < 1
+
+* ```CodeGenerator::InvalidCharset``` - if value provided to the ```charset``` is not an 
+  ```Array``` with a size >= 1
+

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: masked-identifier
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 0.0.2
+  hash: 25
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Matt Hodan
@@ -10,10 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-01 00:00:00 Z
+date: 2011-07-31 00:00:00 -07:00
+default_executable: 
 dependencies: []
 
-description: Automatically adds a masked identifier to an ActiveRecord object on create.  Default assumes the ActiveRecord object contains a property called 'masked_identifier', which should be added to your database migration.  Don't forget to add an index on this column!
+description: Automatically adds a masked identifier to an ActiveRecord object on create.  View the project GitHub page for more info.
 email: 
 - matthew.c.hodan@gmail.com
 executables: []
@@ -28,7 +34,7 @@ files:
 - lib/tasks/masked-identifier_tasks.rake
 - MIT-LICENSE
 - Rakefile
-- README.txt
+- README.markdown
 - test/dummy/app/assets/javascripts/application.js
 - test/dummy/app/assets/stylesheets/application.css
 - test/dummy/app/controllers/application_controller.rb
@@ -67,7 +73,8 @@ files:
 - test/dummy/test/unit/user_test.rb
 - test/masked-identifier_test.rb
 - test/test_helper.rb
-homepage: http://blog.matthodan.com/
+has_rdoc: true
+homepage: http://github.com/matthodan/masked-identifier
 licenses: []
 
 post_install_message: 
@@ -80,20 +87,26 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Use a masked identifier as a not-incrementing reference to an ActiveRecord object
+summary: Use a masked identifier as a non-incrementing reference to an ActiveRecord object
 test_files: 
 - test/dummy/app/assets/javascripts/application.js
 - test/dummy/app/assets/stylesheets/application.css

data/README.txt

@@ -1,53 +0,0 @@
-= MaskedIdentifier
-#
-# MASKED IDENTIFIER DOCUMENTATION
-# ===============================
-#
-# Automatically adds a masked identifier to an ActiveRecord object on create.  Default assumes the
-# ActiveRecord object contains a property called 'masked_identifier', which should be added to your
-# database migration.  Don't forget to add an index on this column!
-#
-# Usage:
-# class User < ActiveRecord::Base
-#   has_masked_identifier
-# end
-#
-# Or, with optional settings:
-# class User < ActiveRecord::Base
-#   has_masked_identifier property: 'mid', attempts: 10, length: 8, charset: %w{ a b c d e }
-# end
-#
-# Optional (options hash):
-# property: override default property name with a custom name (default is 'masked_identifier')
-# attempts: number of attempts to try to find a unique code (default is 20)
-# length: number of characters to include in masked identifier code (default is 10)
-# charset: character set to use when generating codes (default includes a-z, A-Z, and 0-9)
-#
-# Possible Errors:
-# [YourActiveRecordObject]::InvalidProperty if property does not exist
-# See CodeGenerator for additional errors
-#
-#
-# CODE GENERATOR DOCUMENTATION
-# ============================
-#
-# Generates a unique code based on a property of an ActiveRecord object
-#
-# Usage:
-# code = CodeGenerator.unique_code(klass, property, options = {})
-#
-# Required parameters:
-# klass = the ActiveRecord object
-# property = the name of the property to check for uniqueness
-#
-# Optional (options hash):
-# length: number of characters to include in code (default = 10)
-# charset: character set to use when generating codes (default = a-zA-Z0-9)
-# attempts: number of attempts to find a unique code (default = 20)
-#
-# Possible Errors:
-# CodeGenerator::TooManyFailedAttempts if unable to find a unique code
-# CodeGenerator::InvalidAttemptsValue if value provided is not an Integer or < 1
-# CodeGenerator::InvalidCodeLength if value provided is not an Integer or < 1
-# CodeGenerator::InvalidCharset if value provided is not an Array with size >= 1
-#