personhood 0.1.2

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,19 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  # gem "rspec", "~> 2.11.0"
+  gem 'rspec-rails', '~> 2.11'
+  gem "rdoc", "~> 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "jeweler", "~> 1.8.4"
+  # gem "rcov", ">= 0"
+
+  # gem 'railties', '>= 3.1.0'
+  gem 'rails', '>= 3.1.0'
+  gem 'sqlite3'
+end

data/Gemfile.lock

@@ -0,0 +1,111 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.2.8)
+      actionpack (= 3.2.8)
+      mail (~> 2.4.4)
+    actionpack (3.2.8)
+      activemodel (= 3.2.8)
+      activesupport (= 3.2.8)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.4)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.3)
+    activemodel (3.2.8)
+      activesupport (= 3.2.8)
+      builder (~> 3.0.0)
+    activerecord (3.2.8)
+      activemodel (= 3.2.8)
+      activesupport (= 3.2.8)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.8)
+      activemodel (= 3.2.8)
+      activesupport (= 3.2.8)
+    activesupport (3.2.8)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    diff-lcs (1.1.3)
+    erubis (2.7.0)
+    git (1.2.5)
+    hike (1.2.1)
+    i18n (0.6.1)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    journey (1.0.4)
+    json (1.7.5)
+    mail (2.4.4)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.19)
+    multi_json (1.3.6)
+    polyglot (0.3.3)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (3.2.8)
+      actionmailer (= 3.2.8)
+      actionpack (= 3.2.8)
+      activerecord (= 3.2.8)
+      activeresource (= 3.2.8)
+      activesupport (= 3.2.8)
+      bundler (~> 1.0)
+      railties (= 3.2.8)
+    railties (3.2.8)
+      actionpack (= 3.2.8)
+      activesupport (= 3.2.8)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (>= 0.14.6, < 2.0)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+    rspec-rails (2.11.4)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec (~> 2.11.0)
+    sprockets (2.1.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.6)
+    thor (0.16.0)
+    tilt (1.3.3)
+    treetop (1.4.11)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.33)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.0)
+  jeweler (~> 1.8.4)
+  rails (>= 3.1.0)
+  rdoc (~> 3.12)
+  rspec-rails (~> 2.11)
+  sqlite3

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 caleon
+
+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.rdoc

@@ -0,0 +1,279 @@
+= Personhood
+
+When you are tired of coding the same kinds of things for your User model (or any other person-like model) with all its typical +first_name+, +full_name+, and other brouhaha, use the Personhood gem to clean up your code by getting rid of those pesky lines and instead focusing on the lines of code that *truly* set your app apart.
+
+This is a bit of an opinionated library, so the following assumptions are in place (although in the future this can be made more customizable):
+
+== Assumptions
+
+1. Your class is expected to have the following attributes:
+
+* email (string)
+* username (string)
+* first_name (string)
+* middle_name (string)
+* last_name (string)
+* birthdate (date)
+* sex (integer)
+
+2. All attributes listed above are +attr_accessible+ as +:admin+.
+
+3. All but the first two attributes (email/username) listed above are +attr_accessible+ under normal cases.
+
+4. Out of the box, +last_name+ and +first_name+ are required. They, along with +middle_name+ are allowed at most 255 characters.
+
+5. As a +before_save+ callback, whitespaces are stripped from each of +last_name+, +first_name+, and +middle_name+.
+
+6. A record without a +birthdate+ attribute set (or nil) is treated as one whose birthdate is today, hence +age+ would be 0.
+
+== Customizations
+
+Currently the only customization at the API level is with regard to overriding the +#to_param+ instance method. Under normal circumstances you would override this to be used as a URL slug (permalinking with strings instead of ID numerics), but the library goes further to set the return value of +#to_s+ to the value of +#to_param+.
+
+Typically, I would suggest you defining your custom +#to_param+ within your model, but if you need to customize +#to_param+ for your own needs but do not wish to have its value associated with +#to_s+, you can override that method instead.
+
+== Usage
+
+=== Installation
+
+Gemfile:
+
+    gem 'personhood', github: 'caleon/personhood'
+
+Model class file (i.e. +app/models/user.rb+):
+
+    class User
+      include Juscribe::Personhood
+      # ..
+    end
+
+The include statement does not necessarily have to be at the very top of the class definition, but just be aware that upon inclusion, the module also writes a +composed_of+ statement, +validates+ defaults, and the aforementioned +attr_accessible+ rules.
+
+=== API
+
+Once your model is properly set up, these are the methods available to you:
+
+    # Given:
+    user = User.new({
+        email:        'john@doe.com',
+        username:     'johnDoe'
+        first_name:   'john',
+        last_name:    'doe',
+        middle_name:  'quincy',
+        sex:          1,
+        birthdate:    Date.new(1970, 1, 1)
+      }, as: :admin)
+
+Getting back on track, here are the _basic_ methods:
+
+    user.to_param
+    # => "johnDoe"
+
+    user.to_s
+    # => "johnDoe"
+
+    user.full_name
+    # => "john q. doe"
+
+    user.first_and_last_name
+    # => "john doe"
+
+    user.email_address
+    # => "john doe <john@doe.com>"
+
+    user.sex
+    # => "m"
+
+    user.sex(:full)
+    # => "male"
+
+    user.male?
+    # => true
+
+    user.female?
+    # => false
+
+    user.androgynous?
+    # => false
+
+    # Indeterminate sex:
+    andro = User.new
+
+    andro.sex
+    # => "?"
+
+    andro.sex(:full)
+    # => "(unknown)"
+
+    andro.androgynous?
+    # => true
+
+    user.age
+    # returns whatever the age happens to be for someone born on 1990/1/1
+
+    andro.age
+    # => 0
+
+The following are available due to the underlying Juscribe::Name method. You are free to interact with the Juscribe::Name class if you'd like, but the intent is to be hidden from your code and interacted only via the Juscribe::Personhood module which gets included in your class.
+
+    user.name
+    # => "john quincy doe"
+
+    user.name.class
+    # => Juscribe::Name
+
+    user.name.to_s
+    # => "john q. doe"
+
+    user.name.first
+    # => "john"
+
+    user.name.middle
+    # => "quincy"
+
+    user.name.middle_initial
+    # => "q."
+
+    user.name.last
+    # => "doe"
+
+    user.name.full
+    # => "john q. doe"
+
+    user.name.complete
+    # => "john quincy doe"
+
+The other byproduct of using this intermediary class is that it allows usage of +ActiveRecord+'s +composed_of+ statement:
+
+    user = User.create(name: 'Jane Zeta Doe') do |u|
+      # ..
+      # Assume other required attributes are set here
+      # ..
+    end
+
+    user.first_name
+    # => "Jane"
+
+    user.middle_name
+    # => "Zeta"
+
+    user.middle_initial
+    # => "Z."
+
+    user.last_name
+    # => "Doe"
+
+    name = Juscribe::Name.new('Jane', 'Zeta', 'Doe')
+    # or
+    name = Juscribe::Name.convert('Jane Zeta Doe')
+
+    User.where(name: name)
+    #     User Load (0.6ms)  SELECT `users`.* FROM `users` WHERE `users`.`first_name` = 'Jane' AND `users`.`middle_name` = 'Zeta' AND `users`.`last_name` = 'Doe'
+    # => [#<User id: ..>]
+
+    # Note: this means all mapped name parts must match exactly:
+    name = Juscribe::Name.convert('Jane Doe')
+    User.where(name: name)
+    #     User Load (0.6ms)  SELECT `users`.* FROM `users` WHERE `users`.`first_name` = 'Jane' AND `users`.`middle_name` IS NULL AND `users`.`last_name` = 'Doe'
+    # => []
+
+If you see yourself using Juscribe::Name a lot, you might want to consider aliasing it at the root level with:
+
+    Name = Juscribe::Name
+
+=== Sidenote
+
+Examples above were only using the +:admin+ role for demonstration. Ideally such account-level attributes should undergo more strenuous security checks in your controller. A simple way would be:
+
+    user = User.new(params[:user]) do |u|
+      u.email     = params[:user][:email]
+      u.username  = params[:user][:username]
+    end
+
+Values for +#sex+ are left lowercased because I'd argue capitalization should be handled at the CSS level with something like:
+
+    .user .sex { text-transform: capitalize; }
+
+=== Other modules included as a dependency
+
+==== Juscribe::Name
+
+The usage of this class is demonstrated above and its purpose is for abstraction and integration with +composed_of+.
+
+==== Juscribe::DisplayOptional
+
+This is used in the inner-workings of +Personhood+ to display a default "unknown" string if the actual value is blank.
+
+==== Juscribe::TosAcceptable
+
+This module is included in the gem now, but I'm considering taking it out, as it applies less to the "personhood" of an object but more to its "user-account-ness". For now, you may go on to use it in the following way:
+
+    # within app/models/user.rb
+    include Juscribe::TosAcceptable
+
+    # within migration
+    add_column :users, :tos_accepted_at, :datetime
+
+    # within your registration form
+    <%= form_for User.new do |f| %>
+      <%#= .. other form stuff %>
+
+      <%= f.label :tos_accepted do %>
+        <%= f.check_box :tos_accepted, value: '1' %>
+        I agree to the <%= link_to 'Terms of Use', terms_path %>.
+      <% end %>
+
+      <%= f.submit %>
+    <% end %>
+
+In the background, there is a faux-attribute-accessor for +:tos_accepted+ which, when asked to write a truthy form value, writes the timestamp when the form was submitted.
+
+Note that by including the Juscribe::TosAcceptable you are also adding the acceptance validation on that field (existing records without that field set will not validate).
+
+== Roadmap
+
+=== rex_validate
+
+If you looked in the source code you will find references to regexp validation commented out. As this gem was lifted from my other projects which typically use the rex_validate gem, I had to take out that aspect of the integration for the time being while I work out a cleaner way to integrate the two.
+
+=== More convenient Query parameters
+
+As in: "User.where(name: 'John Doe')"" instead of instantiating a new object of the Juscribe::Name class.
+
+=== Customizable column names
+
+Shouldn't be hard to do, and the aim is to not do +include Juscribe::Personhood+ and instead do:
+
+    class User < ActiveRecord::Base
+      claims_personhood columns: {
+                          first_name: :name1,
+                          # ..
+                          birthdate: :dob
+                        },
+                        defaults: {
+                          birthdate: Date.new(1900, 1, 1),
+                          age: nil
+                        }
+    end
+
+... although it might be simpler to +alias_attribute+ and override the +birthdate+ or +age+ methods in those options.
+
+=== General Direction
+
+While it might occur to some to include as options basic groups of functionality involving things like a person's address or profile information, the initial intent of the Personhood library was to contain just the bare minimum commonalities among typical projects. Furthermore, it should apply to non-user-related classes like +President+, for instance, which contains in its table a listing of all the presidents. In such a case, things like even +email_address+ are irrelevant and should not really apply. More fitting, perhaps, are extensions involving things like a person's biometrics (eye color, height, weight), birthplace or ethnicity.
+
+== Contributing to Personhood
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 caleon. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "personhood"
+  gem.homepage = "http://github.com/caleon/personhood"
+  gem.license = "MIT"
+  gem.summary = %Q{ActiveRecord abstraction for attributes pertaining to a person-like model}
+  gem.description = <<-DESC
+    When you are tired of coding the same kinds of things for your User model
+    (or any other person-like model) with all its typical `first_name`,
+    `full_name`, and other brouhaha, use the Personhood gem to clean up your
+    code by getting rid of those pesky lines and instead focusing on the lines of
+    code that *truly* set your app apart.
+  DESC
+  gem.email = "caleon@gmail.com"
+  gem.authors = ["caleon"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Personhood #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.2

data/lib/juscribe/display_optional.rb

@@ -0,0 +1,19 @@
+module Juscribe # :nodoc:
+  module DisplayOptional
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :unknown_label
+      self.unknown_label = 'unnamed'
+    end
+
+    def to_s
+      display_optional(to_param)
+    end
+
+    private
+    def display_optional(value)
+      value.blank? ? "(#{unknown_label})" : value
+    end
+  end
+end

data/lib/juscribe/name.rb

@@ -0,0 +1,42 @@
+module Juscribe
+  class Name
+    attr_reader :first, :middle, :last
+
+    class << self
+      def convert(input)
+        case input
+        when String
+          new(*input.split(/\s+/))
+        end
+      end
+    end
+
+    def initialize(first, *others, last)
+      @first, @middle, @last = first, others.first, last
+    end
+
+    def middle_initial
+      "#{middle.first}." if middle.present?
+    end
+
+    def first_and_last
+      [first, *last].join(' ')
+    end
+
+    def full
+      [first, *middle_initial, *last].join(' ')
+    end
+
+    def complete
+      [first, *middle, *last].join(' ')
+    end
+
+    def to_s
+      full
+    end
+
+    def inspect
+      %Q{"#{complete}"}
+    end
+  end
+end

data/lib/juscribe/personhood.rb

@@ -0,0 +1,93 @@
+module Juscribe # :nodoc:
+  module Personhood
+    extend ActiveSupport::Concern
+
+    included do
+      composed_of :name,  class_name:  'Juscribe::Name',
+                          converter: :convert,
+                          mapping: [%w(first_name  first),
+                                    %w(middle_name middle),
+                                    %w(last_name   last)]
+
+      # rex_validate :last_name, :first_name, :middle_name
+      with_options length: { maximum: 255 } do |x|
+        x.validates :last_name, :first_name,  presence: true
+        x.validates :middle_name
+      end
+
+      attr_accessible :last_name, :first_name, :middle_name, :name, :birthdate, :sex
+      attr_accessible :last_name, :first_name, :middle_name, :name, :birthdate, :sex, :email, :username, as: :admin
+    end
+
+    # ----------------------------------------
+    # :section: Basic Info
+    # ----------------------------------------
+
+    # Override the following to control what gets displayed on #to_s
+    def to_param
+      username
+    end
+
+    def middle_initial
+      display_optional name.middle_initial
+    end
+
+    ##
+    # Full name, unless empty, then shows "unnamed" variant.
+    def full_name
+      display_optional name.full
+    end
+
+    # Same as #full_name but omitting the middle_name.
+    def first_and_last_name
+      display_optional name.first_and_last
+    end
+
+    # Email, when the db field is nil, still returns an empty string,
+    # I suppose for Devise's sake.
+    def email_address
+      "#{first_and_last_name} <#{email}>" if email.present?
+    end
+
+    # Defaults to <tt>Date.today</tt> if +nil+.
+    def birthdate
+      read_attribute(:birthdate) || Date.today
+    end
+
+    def age
+      today, bday = Date.today, birthdate
+      years       = today.year - bday.year
+      years.tap { |yrs| yrs -= 1 if (bday + years.years) > today }
+      # is this logic even solid?
+    end
+
+    def sex(format = nil)
+      full_int = format == :full ? 1 : 0
+      if read_attribute(:sex)
+        %w(female male)[self[:sex]][0..full_int.send(:-@)]
+      else
+        %w{? (unknown)}[full_int]
+      end
+    end
+
+    def male?
+      sex == 'm'
+    end
+
+    def female?
+      sex == 'f'
+    end
+
+    def androgynous?
+      read_attribute(:sex).nil?
+    end
+
+    private
+    def strip_names!
+      %w(first_name middle_name last_name).each do |name_part|
+        send(name_part).strip! if send(:"#{name_part}_changed?")
+      end
+    end
+
+  end
+end

data/lib/juscribe/tos_acceptable.rb

@@ -0,0 +1,26 @@
+module Juscribe # :nodoc:
+  module TosAcceptable
+    extend ActiveSupport::Concern
+
+    included do
+      validates :terms_of_service, acceptance: { accept: true }
+
+      attr_accessor :tos_accepted, :tos_accepted_at
+    end
+
+    def tos_accepted=(val)
+      self.tos_accepted_at = Time.now
+    end
+
+    def tos_accepted_at=(timestamp)
+      write_attribute(:tos_accepted_at, timestamp) if has_attribute?(:tos_accepted_at)
+      @_tos_accepted_at = timestamp
+    end
+
+    def tos_accepted?
+      @_tos_accepted_at.try(:<, Time.now)
+    end
+    alias_method :tos_accepted,     :tos_accepted?
+    alias_method :terms_of_service, :tos_accepted?
+  end
+end

data/lib/personhood.rb

@@ -0,0 +1,10 @@
+require 'active_record'
+require 'active_support/concern'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/class/attribute'
+require 'juscribe/display_optional'
+require 'juscribe/name'
+require 'juscribe/personhood'
+require 'juscribe/tos_acceptable'
+
+ActiveRecord::Base.send(:include, Juscribe::DisplayOptional)