natural_born_slugger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c53161bfaee3307f0789e14966a1cef3def933f3
+  data.tar.gz: b0d8d1d8e94fae0798e5ad1b6411d21ff50a18c0
+SHA512:
+  metadata.gz: 4847802082fabbcb6f537d607f8cabf918fda7a258966c4ac0b43e9a7fe7a89794f1880a2b1a9918c800a80c1d9ab23c3fb15d2f0fca151b32eb6a5e1d443390
+  data.tar.gz: b93c87ae94fec058f6dac6e6027cc5dde19ab2880a7d292dfd89f5eeca71cada422cc8fbc326a3acfb3755789c5469716190bc7ac0167d943ad2d063ead921fc

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.yardopts

@@ -0,0 +1 @@
+- LICENSE.md

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in natural-born-slugger.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,24 @@
+MIT License
+===========
+
+Copyright (c) 2013 Christopher Keele
+------------------------------------
+
+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.md

@@ -0,0 +1,182 @@
+Natural Born Slugger
+====================
+
+A gem for managing composite attributes, especially natural keys and url slugs.
+
+Supports automatically-updated natural keys/slugs. Has ORM and Rack extensions.
+
+
+
+Installation
+------------
+
+Using bundler, add to your `Gemfile`:
+
+    gem 'natural_born_slugger'
+
+Otherwise:
+
+    gem install natural_born_slugger
+
+and load it:
+
+    require 'natural_born_slugger'
+
+
+
+Usage
+-----
+
+### Composing Attributes
+
+At its core, `NaturalBornSlugger` is a simple, well-tested DSL to compose dynamic attributes dependent on other fields:
+
+    Person = Struct.new(:first_name, :middle_name, :last_name) do
+      include NaturalBornSlugger
+      has_slug first_name: nil, middle_name: nil, last_name: nil
+    end
+
+    bambino = Person.new('George', 'Herman', 'Ruth')
+
+    bambino.slug #=> "GeorgeHermanRuth"
+
+    bambino.first_name, bambino.middle_name = 'Babe', nil
+
+    bambino.slug #=> "BabeRuth"
+
+
+### Setting Transformations
+
+`NaturalBornSlugger` also lets you set tranformations on each dependency:
+
+    Person = Struct.new(:id, :name) do
+      include NaturalBornSlugger
+      has_natural_key name: :dashify, id: :hashify, join_with: '-'
+    end
+
+    buster = Person.new(23, 'Lou Gehrig')
+
+    buster.natural_key #=> "lou-gehrig-37693cf"
+
+    buster.name = 'The Iron Horse'
+
+    buster.natural_key #=> "the-iron-horse-37693cf"
+
+`NaturalBornSlugger` interprets many objects as valid transformations:
+
+##### Symbols:
+  - Converts dependency to string and sends the symbol tranformation to the `String` instance.
+  - `NaturalBornSlugger` extends `String` with two methods:
+    1. `hashify` - an alias for [ActiveSupports's parameterize method](http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize)
+    2. `dashify` - convert string to an MD5 hash and use the first 7 digits
+  - Examples: `:hashify`, `:dashify`, `:capitalize`, `:chomp`, `:downcase`, `:reverse`, `:squeeze`, `:strip`, `:upcase`, etc
+
+##### Strings:
+  - Attempts to use the string tranformation as a [format string](http://apidock.com/ruby/Kernel/sprintf) for the dependency.
+  - If the string tranformation isn't a format string, it will replace the dependency in the slug, which probably isn't what you want.
+  - Examples: `id: "%05d"`, `cost: "$%.02f"`
+
+##### Regexps:
+  - Scans the dependency using the regex tranformation and joins all matches.
+  - Joins matches with the same `join_with` used in the rest of the slug.
+  - Examples: Can't think of any uses
+
+##### Procs:
+  - Passes the dependency into the provided `lambda` or `Proc`.
+  - Allows custom tranformations. The `Proc` must accept one parameter and return a string or nil.
+  - Examples: compacting arrays of related objects, ie: `followers: ->(followers){ "%05d" % followers.count }`
+
+##### nil, false, or anything else:
+  - Convert dependency to string and leave untouched.
+  - `nil` is preferred.
+
+
+### Composed Attribute Options
+
+After including `NaturalBornSlugger` into your class, you can define an composite attribute through one of three methods:
+
+- `has_slug`
+- `has_natural_key`
+- `has_composed_attribute`
+
+Each of these methods accepts the same arguments: a name and a hash of options. `has_slug` and `has_natural_key` will use default names of `'slug'` and `'natural_key'` respectively if you do not supply one. `has_composed_attribute` requires the name.
+
+The options hash is where you define the attribute's dependencies. It also uses special keys to customize the attribute's behavior:
+
+##### `:join_with`
+  - String to use for joining dependencies.
+  - Default: ""
+  - Example:
+
+```
+    Person = Struct.new(:first_name, :middle_name, :last_name) do
+      include NaturalBornSlugger
+      has_slug first_name: nil, middle_name: nil, last_name: nil, join_with: '-'
+    end
+
+    bambino = Person.new('Babe', nil, 'Ruth')
+    bambino.slug #=> "Babe-Ruth"
+```
+
+##### `:compact`
+  - Removes nil dependencies before joining.
+  - Default: true
+  - Example: Notice the extra dash in the example below:
+
+```
+    Person = Struct.new(:first_name, :middle_name, :last_name) do
+      include NaturalBornSlugger
+      has_slug first_name: nil, middle_name: nil, last_name: nil, compact: false, join_with: '-'
+    end
+
+    bambino = Person.new('Babe', nil, 'Ruth')
+    bambino.slug #=> "Babe--Ruth"
+```
+
+##### `:require_all`
+  - Checks to make sure all attributes exist before composing attribute.
+  - Makes attribute return nil until all dependencies exist.
+  - Default: false
+  - Example:
+
+```
+    Person = Struct.new(:first_name, :middle_name, :last_name) do
+      include NaturalBornSlugger
+      has_slug first_name: nil, middle_name: nil, last_name: nil, require_all: true
+    end
+
+    bambino = Person.new('Babe', nil, 'Ruth')
+    bambino.slug #=> nil
+
+    bambino.first_name, bambino.middle_name = 'George', 'Herman'
+    bambino.slug #=> "George-Herman-Ruth"
+```
+
+##### `:track`
+  - Provides a callback function `#{attribute_name}_change` to allow you to persist old slugs as you please.
+  - Default: false
+  - Example:
+
+```
+    Person = Struct.new(:first_name, :middle_name, :last_name) do
+      include NaturalBornSlugger
+      has_slug first_name: nil, middle_name: nil, last_name: nil, track: true
+
+      attr_accessor :formerly_known_as
+      def slug_change(old_slug, new_slug)
+        @formerly_known_as ||= []
+        @formerly_known_as << old_slug
+      end
+    end
+
+    bambino = Person.new('George', 'Herman', 'Ruth')
+    bambino.slug #=> "GeorgeHermanRuth"
+
+    bambino.first_name, bambino.middle_name = 'Babe', nil
+    bambino.slug #=> "BabeRuth"
+    bambino.formerly_known_as #=> ["GeorgeHermanRuth"]
+```
+
+##### _Note:_
+
+If you happen to have methods or attributes called `join_with`, `compact`, `require_all`, or `track`, you can still build composite attributes out of them. Just use a string instead of a symbol when declaring your attribute's dependencies. `NaturalBornSlugger` only looks for symbols when reading your dependencies for these settings.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/natural_born_slugger/class_methods.rb

@@ -0,0 +1,101 @@
+module NaturalBornSlugger
+  module ClassMethods
+
+    ##
+    # Adds a slug to the class. Name is optional.
+    #
+    def has_slug(name, options={})
+      # Use default name if not provided
+      name, options = 'slug', name if name.is_a?(Hash)
+      dependencies, options = extract_composite_dependencies(name, options)
+      build_composite_attribute(name.to_s, dependencies, options)
+    end
+
+    ##
+    # Adds a natural key to the class. Name is optional.
+    #
+    def has_natural_key(name, options={})
+      # Use default name if not provided
+      name, options = 'natural_key', name if name.is_a?(Hash)
+      dependencies, options = extract_composite_dependencies(name, options)
+      build_composite_attribute(name.to_s, dependencies, options)
+    end
+
+    ##
+    # Adds a generic composite attribute to the class. Name is required.
+    #
+    def has_composite_attribute(name, options={})
+      dependencies, options = extract_composite_dependencies(name, options)
+      build_composite_attribute(name.to_s, dependencies, options)
+    end
+
+  private
+
+    ##
+    # Pulls method behavior options out of general options. The remaining options
+    #  are assumed to be the dependent attributes that compose this one.
+    #
+    def extract_composite_dependencies(name, options={})
+      dependencies, options = options, {}
+
+      options[:compact_dependencies] =  dependencies.delete(:compact)       || true
+      options[:require_dependencies] =  dependencies.delete(:require_all)   || false
+      options[:track_changes] =         dependencies.delete(:track)         || false
+      options[:joiner] =                dependencies.delete(:join_with)     || ''
+
+      raise ConfigurationError.new(self.name, name, "no dependent attributes were specified") if dependencies.empty?
+
+      [dependencies, options]
+    end
+
+    ##
+    # Adds a composite attribute to the class,
+    #  with a getter and updater method.
+    # Also adds a setter that either calls the updater
+    #  or throws an error, depending on configuration.
+    #
+    def build_composite_attribute(name, dependencies, options)
+
+      # Define instance attribute getter
+      define_method name do
+        self.send "update_#{name}"
+      end
+
+      # Define instance attribute setter: ignores assignment and just triggers an update
+      define_method "#{name}=" do |value|
+        if NaturalBornSlugger.configuration.ignore_attribute_setters
+          # TODO: Log discarded value warning
+          self.send "update_#{name}"
+        else
+          raise IllegalOperationError.new(self.class.name, "#{name}=", 'you cannot set composite attributes directly')
+        end
+      end
+
+      # Update instance attribute
+      define_method "update_#{name}" do
+        # Check existence of all attribute dependencies if `require_dependencies` is true
+        resolved_dependencies = dependencies.map do |dependency, strategy|
+          [resolve_dependency(dependency), strategy]
+        end
+        if options[:require_dependencies] ? resolved_dependencies.map(&:first).all? : true
+          new_value = self.compose_attribute(resolved_dependencies, options)
+          if options[:track_changes]
+            old_value = self.instance_variable_get("@#{name}")
+            unless old_value == new_value
+              self.send("#{name}_change".to_sym, old_value, new_value)
+            end
+          end
+          self.instance_variable_set("@#{name}", new_value)
+        end
+      end
+
+      if [:track_changes]
+        define_method "#{name}_change" do |old_value, new_value|
+
+        end
+      end
+
+    end
+
+  end
+end

data/lib/natural_born_slugger/configuration.rb

@@ -0,0 +1,12 @@
+module NaturalBornSlugger
+  class Configuration
+
+    attr_accessor :ignore_attribute_setters, :hashified_length
+
+    def initialize
+      @ignore_attribute_setters = true
+      @hashified_length = 7
+    end
+
+  end
+end

data/lib/natural_born_slugger/exceptions.rb

@@ -0,0 +1,29 @@
+module NaturalBornSlugger
+
+  class NaturalBornError < StandardError; end
+
+  class IllegalOperationError < NaturalBornError
+    def initialize(class_name, method_name, context = nil)
+      @class_name = class_name
+      @method_name = method_name
+      @context = context
+      @message = "Cannot call `#{class_name}.#{method_name}"
+    end
+    def to_s
+      [@message, @context].compact.join(': ')+'.'
+    end
+  end
+
+  class ConfigurationError < NaturalBornError
+    def initialize(class_name, attribute, context = nil)
+      @class_name = class_name
+      @attribute = attribute
+      @context = context
+      @message = "Composite attribute `#{attribute}` of #{class_name} has not been configured properly"
+    end
+    def to_s
+      [@message, @context].compact.join(': ')+'.'
+    end
+  end
+
+end

data/lib/natural_born_slugger/extensions/string.rb

@@ -0,0 +1,10 @@
+require 'active_support/inflector/transliterate'
+class String
+
+  alias_method :dashify, :parameterize
+
+  def hashify
+    Digest::MD5.hexdigest(self).slice(0, NaturalBornSlugger.configuration.hashified_length)
+  end
+
+end

data/lib/natural_born_slugger/instance_methods.rb

@@ -0,0 +1,33 @@
+module NaturalBornSlugger
+
+  def resolve_dependency(dependency)
+    object = self
+    dependency_chain = dependency.to_s.split('.')
+    dependency_chain.each do |method|
+      object = object.try :send, method
+      break unless object
+    end
+    object
+  end
+
+  def compose_attribute(resolved_dependencies, options)
+    resolved_dependencies.map do |resolved_dependency, strategy|
+      case strategy
+      when Symbol # Symbols represent string methods to call on the resolved dependency
+        resolved_dependency.to_s.send(strategy)
+      when String # Strings represent formats to fit the resolved dependency into
+        strategy % resolved_dependency
+      when Regexp # Regexps represent patterns to pull out of the resolved dependency and join
+        resolved_dependency.scan(strategy).join(options[:joiner])
+      when Proc   # Procs should take one parameter and return a string or nil
+        strategy.call(resolved_dependency)
+      else        # If no strategy provided, use resolved dependency as is
+        resolved_dependency.to_s
+      end
+    # Remove nil components if `compact_dependencies` is true
+    end.tap do |components|
+      components.compact! if options[:compact_dependencies]
+    end.join(options[:joiner])
+  end
+
+end

data/lib/natural_born_slugger/version.rb

@@ -0,0 +1,3 @@
+module NaturalBornSlugger
+  VERSION = "0.1.0"
+end

data/lib/natural_born_slugger.rb

@@ -0,0 +1,33 @@
+require 'active_support/core_ext/module/attribute_accessors'
+
+require "natural_born_slugger/exceptions"
+require "natural_born_slugger/configuration"
+
+module NaturalBornSlugger
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+
+    yield(configuration) if block_given?
+
+    require "natural_born_slugger/class_methods"
+    require "natural_born_slugger/instance_methods"
+
+    configuration
+  end
+
+  def self.logger
+    @logger ||= configuration.logger
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+end
+
+require "natural_born_slugger/extensions/string"
+require "natural_born_slugger/version"

data/natural_born_slugger.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'natural_born_slugger/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "natural_born_slugger"
+  spec.version       = NaturalBornSlugger::VERSION
+  spec.authors       = ["Christopher Keele"]
+  spec.email         = ["dev@chriskeele.com"]
+  spec.description   = %q{A gem for managing composed attributes, especially natural keys and url slugs.}
+  spec.summary       = %q{Easily define automatically-updated composed attributes. Includes ORM helpers and a Rack-based URL redirector.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler",    "~> 1.3"
+  spec.add_development_dependency "rake",       "~> 10.0"
+  spec.add_development_dependency "yard",       "~> 0.8"
+  spec.add_development_dependency "redcarpet",  "~> 2.2"
+  spec.add_development_dependency "rspec",      "~> 2.13"
+
+  spec.add_dependency 'activesupport',          '~> 3.1'
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: natural_born_slugger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Christopher Keele
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: A gem for managing composed attributes, especially natural keys and url
+  slugs.
+email:
+- dev@chriskeele.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/natural_born_slugger.rb
+- lib/natural_born_slugger/class_methods.rb
+- lib/natural_born_slugger/configuration.rb
+- lib/natural_born_slugger/exceptions.rb
+- lib/natural_born_slugger/extensions/string.rb
+- lib/natural_born_slugger/instance_methods.rb
+- lib/natural_born_slugger/version.rb
+- natural_born_slugger.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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.0
+signing_key: 
+specification_version: 4
+summary: Easily define automatically-updated composed attributes. Includes ORM helpers
+  and a Rack-based URL redirector.
+test_files: []
+has_rdoc: