trusty 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 396691c71380d978d8119d8bcb3f0d32491f1888
-  data.tar.gz: 2b29a3e6491960ed1f96630e7ca213305dbda6f4
+  metadata.gz: d7f6a8980814e0ac15c4f5cacc0590d44c1f571d
+  data.tar.gz: 02c63e4b122e0a2e6593f1310494d37d6eb59185
 SHA512:
-  metadata.gz: bb6b586a37a1060600fbeca34fa3fea9826f020cae310be08cda2f77b4e3da74554728cf3c9ade77e2586b24c26e4a934c9124eaf4d6528452f7e545773843ef
-  data.tar.gz: d39b0d14db882904031780ae22a5e2f02284a620c9003090b8b1dd0d8c7397e895ec469ea28ab655582cf25659a5a8bffa677c32ab1992f4c3f11053b47cc0de
+  metadata.gz: 600db5f18e699ece7fe625e77ef13159726ddc13d3276ec126db0acf49e81ab27ec61e2499fbabbacceaf145c0a132119e1ce008374f1790e9291ec04080b2ad
+  data.tar.gz: fd053f427ab015f0cc2fc003d3d1bc02ae20aec2256f438d42a1520db5044123758aff6d477ae24a81d1c0f824a152a5f5c1d88747abb4cd974190d4feb7d4b5

data/README.md

@@ -18,7 +18,139 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Trusty is a library of a bunch of useful utilities.
+
+### Environment Variables
+
+Use `Trusty::Environment` (or the shorthand `Vars`) to access environment variables. 
+What's handy is that it will load up environment variables from a `env.yml` file and merge it with `ENV`. 
+By default, it loads the section of the YAML file based on the current `ENV['RAILS_ENV']` and `ENV['RACK_ENV']`. 
+You can customize the section to load by setting `ENV['ENV_SECTION']` to a custom name.
+
+```Ruby
+# See what the default section name is that will be pulled from env.yml
+section_name = Vars.default_env_section
+
+# The following are equivalent
+api_key = Vars['API_KEY']
+api_key = Vars.env['API_KEY']
+api_key = Vars.env.api_key
+
+# You can load any YAML file into a Vars property dynamically (should return a Hash).
+# Files will be loaded from Rails' "config" directory by default. These are equivalent:
+custom_config = Vars.custom_config # loads config/custom_config.yml as a Hashie::Mash
+custom_config = Vars.config.custom_config
+
+# add paths to find YAML files in other locations (especially if not using Rails)
+paths = [
+  Rails.root.join('config'),        # added by default
+  Rails.root,                       # search in the root
+  Rails.root.join('custom', 'folder') # look in custom/folder/* inside Rails app
+]
+
+Vars.paths += paths
+
+# This will find the another_config.yml file under the custom path
+another_config = Vars.another_config # loads custom/folder/another_config.yml as a Hashie::Mash
+another_config = Vars.config.another_config
+
+# To access a list of all YAML files that have been loaded
+hash_of_configs = Vars.config
+```
+
+### Omniauth
+
+To easily map Omniauth data to your `User` and/or `Idenity` models with a `User#identities` relationship, use the `Trusty::Omniauth::ProviderMapper` class. Both ActiveRecord and Mongoid are supported.
+
+Add this line to your application's Gemfile:
+
+    gem 'trusty', require: 'trusty/omniauth'
+
+Just pass in the Omniauth `Hash` provided in the environment variable to the [`ProviderMapper`](lib/trusty/omniauth/provider_mapper.rb) and you can use the helper methods to populate your models. Check out  for more options.
+
+```Ruby
+omniauth = request.env['omniauth.auth']
+
+# these are some default options that you can override
+options = {
+  user_model: User,
+  user_attributes_names: User.column_names,
+  identity_model: Identity,
+  identity_attribute_names: Identity.column_names
+}
+
+# Here is a class that you can use to deal with your model instances, 
+# whether finding a user based on their identity or adding a new identity to a user, 
+# or even creating a new user with the identity.
+mapper = Trusty::Omniauth::ProviderMapper.new(omniauth, options)
+```
+
+### YAML
+
+Use `Trusty::Utilities::Yaml` to load a file or content. 
+An instance of `Trusty::Utilities::YamlContext` is used for rendering YAML and is used as the context. 
+If you pass a block to the method where you pass in the file or content, you can include modules and so on in the context if necessary.
+
+```Ruby
+# load a file
+relative_path = "yaml/filename.yml"
+
+# optional: pass in an array of paths where to search for the file
+optional_paths = [ Rails.root, Rails.root.join('config') ]
+
+# Render YAML and any ERB blocks
+result = Trusty::Utilities::Yaml.load_file(relative_path, optional_paths) do |context|
+  # optionally use a block to modify the context (YamlContext instance)
+end
+```
+
+You can use `YamlContext` directly:
+
+```Ruby
+# load the content from the file
+content = File.read Trusty::Utilities::PathFinder.find(relative_path, optional_paths)
+
+# render the YAML as a Ruby object
+result = Trusty::Utilities::YamlContext.render content do |context|
+  # optionally use a block to modify the context (YamlContext instance)
+end
+```
+
+### `method_missing` Helpers
+
+If you want to dynamically add boolean methods to a class, use `Trusty::Utilities::MethodName`. 
+It will allow you to return a boolean for a method that ends with '?'. 
+It will also dynamically define the methods for you with a simple module to extend your class called `Trusty::Utilities::MethodNameExtensions`. 
+
+If you want more control over what happens in your `method_missing` method, you can use [`MethodName`](lib/trusty/utilities/method_name.rb) instances to give you information about the method name you are handling.
+
+```Ruby
+target      = MyModel.new
+method_name = "confirmed_at?"
+
+# get info about the method name inside method_missing
+method_info = Trusty::Utilities::MethodName.new(method_name)
+
+# see if it's a boolean method
+method_info.boolean? # true
+
+# if you want to see what the value is for the method name without the '?'
+method_name.base_value_for target # "2013-10-30 19:41:40 UTC"
+
+# get the boolean value
+method_name.method_value_for target # true
+
+# define the helper method on the target (if it isn't already on there)
+method_name.define_for target # true
+```
+
+Make this functionality automatic by including the `Trusty::Utilities::MethodNameExtensions` module in your class.
+
+```Ruby
+class MyModel
+  include Trusty::Utilities::MethodNameExtensions
+end
+```
 
 ## Contributing
 

data/lib/trusty/environment.rb

@@ -48,7 +48,7 @@ module Trusty
       end
       
       def default_env_section
-        @default_env_section ||= ENV['ENV_SECTION'] || Rails.env
+        @default_env_section ||= ENV['ENV_SECTION'] || ENV['RAILS_ENV'] || ENV['RACK_ENV']
       end
       
       def config(default_value = nil)
@@ -59,7 +59,7 @@ module Trusty
       end
       
       def paths
-        @paths ||= [ Rails.root.join("config").to_s ]
+        @paths ||= defined?(Rails) ? [ Rails.root.join("config").to_s ] : []
       end
       
       # dynamically add methods that forward to config
@@ -96,4 +96,7 @@ module Trusty
     # create class methods
     extend ClassMethods
   end
-end
+end
+
+# copy out of namespace
+Vars = Trusty::Environment

data/lib/trusty/omniauth/mapping_helpers.rb

@@ -0,0 +1,15 @@
+module Trusty
+  module Omniauth
+    module MappingHelpers
+      def clean(value, *filters, &default_value)
+        default_value ||= lambda{ nil }
+        
+        filters.each do |method_name|
+          value = value.to_s.send(method_name)
+        end
+        
+        value.blank? ? default_value.call : value
+      end
+    end
+  end
+end

data/lib/trusty/omniauth/model_mapper.rb

@@ -0,0 +1,49 @@
+module Trusty
+  module Omniauth
+    class ModelImporter
+      include MappingHelpers
+      
+      def initialize(provider, options = {})
+        @provider = provider
+        @options  = options
+      end
+      
+      def model
+        @options[:model]
+      end
+      
+      def attribute_names
+        @attribute_names ||= @options[:attribute_names] || column_names
+      end
+      
+      def attributes(*filter_attribute_names)
+        @attributes ||= @provider.attributes(*attribute_names).merge!(@options[:attributes])
+        
+        if filter_attribute_names.any?
+          @attributes.slice(*filter_attribute_names)
+        else
+          @attributes.dup
+        end
+      end
+      
+      def build_record
+        model.new(attributes, :without_protection => true)
+      end
+      
+      def update_record!(record)
+        record.update_attributes!(attributes, :without_protection => true)
+      end
+      
+      def column_names
+        @column_names ||= if model.respond_to? :column_names
+          model.column_names.map(&:to_sym)
+        elsif model.respond_to? :fields
+          model.fields.map{|c| c[1].name.to_sym}
+        else
+          []
+        end
+      end
+      
+    end
+  end
+end

data/lib/trusty/omniauth/provider_mapper.rb

@@ -0,0 +1,155 @@
+module Trusty
+  module Omniauth
+    class ProviderMapper
+      include MappingHelpers
+      
+      attr_reader :provider_name, :provider_attributes, :options
+      attr_reader :provider_identity, :provider_user
+      
+      # provider_attributes = OmniAuth data
+      # options = 
+      # - :user_model = User model
+      # - :user_attributes = Hash of attributes to merge into user_attributes
+      # - :user_attributes_names = Array of attribute names to copy from Omniauth data (default: User.column_names)
+      # - :identity_model = Identity model
+      # - :identity_attributes = Hash of attributes to merge into identity_attributes
+      # - :identity_attribute_names = Array of attribute names to copy from Omniauth data (default: Identity.column_names)
+      # - :skip_raw_info (default: false) = Boolean whether to exclude OmniAuth "extra" data in identity_attributes[:raw_info]
+      # - :skip_nils (default: true) = Boolean whether to remove attributes with nil values
+      def initialize(provider_attributes, options = {})
+        @provider_attributes  = provider_attributes.with_indifferent_access
+        @provider_name        = provider_attributes['provider']
+        @options              = {
+          :user_attributes      => {},
+          :identity_attributes  => {},
+          :skip_raw_info        => false,
+          :skip_nils            => true
+        }.merge(options)
+        
+        @provider_identity = ModelMapper.new(self,
+          :model            => @options[:identity_model] || Identity,
+          :attributes       => @options[:identity_attributes],
+          :attribute_names  => @options[:identity_attribute_names]
+        )
+        @provider_user = ModelMapper.new(self,
+          :model            => @options[:user_model] || User,
+          :attributes       => @options[:user_attributes],
+          :attribute_names  => @options[:user_attribute_names]
+        )
+      end
+      
+      # Query existing
+      
+      def user
+        # first try to find the user based on provider/uid combo
+        @user ||= find_user_by_identity
+        # find the user by email if not found by identity
+        @user ||= find_user_by_email
+      end
+      
+      def identity
+        @identity ||= find_identity_by_user
+      end
+      
+      def user_exists?
+        !user.nil?
+      end
+      
+      def identity_exists?
+        !identity.nil?
+      end
+      
+      # USER
+      
+      def build_user
+        @provider_user.build_record
+      end
+      
+      # IDENTITY
+      
+      def build_identity
+        @provider_identity.build_record
+      end
+      
+      def build_identity_for_user(user)
+        build_identity.tap do |identity|
+          # this assumes there is an inverse relationship automatically created
+          # such as user.identities would now contain this identity for the user
+          identity.user = user
+        end
+      end
+      
+      def update_existing_identity!
+        raise "Identity doesn't exist!" unless identity
+        
+        @provider_identity.update_record!(identity)
+      end
+      
+      ###### General ######
+      
+      def attributes(*filter_attribute_names)
+        unless @attributes
+          info            = provider_attributes.fetch('info', {})
+          credentials     = provider_attributes['credentials']
+          
+          name            = clean(info['name'])       { [info['first_name'], info['last_name']].join(" ").strip }
+          first_name      = clean(info['first_name']) { name.split(/\s+/, 2).first }
+          last_name       = clean(info['last_name'])  { name.split(/\s+/, 2).last }
+          
+          @attributes = {
+            :provider       => provider_name,
+            :uid            => clean(provider_attributes['uid']),
+            :name           => name,
+            :email          => clean(info['email'], :downcase, :strip),
+            :verified       => provider_attributes['extra']['raw_info']['verified_email'] == true,
+            :username       => clean(info['nickname']),
+            :first_name     => first_name,
+            :middle_name    => clean(info['middle_name']),
+            :last_name      => last_name,
+            :phone          => clean(info['phone']),
+            :image_url      => info['image'],
+            :profile_url    => info.fetch('urls', {})['public_profile'],
+            :token          => clean(credentials['token']),
+            :secret         => clean(credentials['secret']),
+            :refresh_token  => clean(credentials['refresh_token']),
+            :expires        => credentials['expires'] == true,
+            :expires_at     => (Time.at(credentials['expires_at']) rescue nil),
+            :raw_info       => provider_attributes['extra'].except('access_token').as_json,
+            # extra
+            :time_zone      => Time.zone.name
+          }.with_indifferent_access
+          
+          @attributes.reject!{|_,value| value.nil?} if options[:skip_nils]
+          @attributes.delete(:raw_info) if options[:skip_raw_info]
+        end
+        
+        if filter_attribute_names.any?
+          @attributes.slice(*filter_attribute_names)
+        else
+          @attributes.dup
+        end
+      end
+      
+      private
+      
+      def find_user_by_identity
+        if defined?(Mongoid::Document) && @provider_user.model.include?(Mongoid::Document)
+          @provider_user.model.elem_match(:identities => @provider_identity.attributes(:provider, :uid)).first
+        else
+          @provider_user.model.where(
+            :id => @provider_identity.model.where( @provider_identity.attributes(:provider, :uid) ).select(:user_id)
+          ).first
+        end
+      end
+      
+      def find_user_by_email
+        @provider_user.model.where( @provider_identity.attributes(:email) ).first
+      end
+      
+      def find_identity_by_user
+        user && user.identities.where( @provider_identity.attributes(:provider, :uid) ).first
+      end
+      
+    end
+  end
+end

data/lib/trusty/omniauth.rb

@@ -0,0 +1,3 @@
+require_relative 'omniauth/mapping_helpers'
+require_relative 'omniauth/model_mapper'
+require_relative 'omniauth/provider_mapper'

data/lib/trusty/utilities/yaml.rb

@@ -2,15 +2,16 @@ module Trusty
   module Utilities
     module Yaml
       module ClassMethods
-        def load_file(filename, paths = [])
+        def load_file(filename, paths = [], &block)
           # allow multiple filenames and use the first one that exists
           if path = PathFinder.find(filename, paths)
-            source = File.read(path)
-            source = ERB.new(source).result
-            
-            YAML.load(source)
+            load_content(File.read(path), &block)
           end
         end
+        
+        def load_content(content, &block)
+          YamlContext.render(content, &block)
+        end
       end
       
       extend ClassMethods

data/lib/trusty/utilities/yaml_context.rb

@@ -0,0 +1,19 @@
+module Trusty
+  module Utilities
+    class YamlContext
+      def self.render(content, &block)
+        new(content, &block).render
+      end
+      
+      def initialize(content, &block)
+        @content = content
+        
+        yield(self) if block_given?
+      end
+      
+      def render
+        YAML.load ERB.new(@content).result(binding)
+      end
+    end
+  end
+end

data/lib/trusty/utilities.rb

@@ -2,9 +2,4 @@ require_relative "utilities/method_name"
 require_relative "utilities/method_name_extensions"
 require_relative "utilities/path_finder"
 require_relative "utilities/yaml"
-
-module Trusty
-  module Utilities
-    
-  end
-end
+require_relative "utilities/yaml_context"

data/lib/trusty/version.rb

@@ -1,3 +1,3 @@
 module Trusty
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/trusty.rb

@@ -1,9 +1,2 @@
 require "trusty/version"
 require "trusty/environment"
-
-module Trusty
-  
-end
-
-# copy out of namespace
-Vars = Trusty::Environment

data/trusty.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["joel@joelvanhorn.com"]
   spec.description   = %q{Trusty is a configuration and utilities library.}
   spec.summary       = %q{Trusty allows you to manage environment variables and other common configuration challenges.}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/joelvh/trusty"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)
@@ -20,6 +20,9 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "omniauth"
+  spec.add_development_dependency "rails"
   
   spec.add_dependency "dotenv", ">= 0.9.0"
+  spec.add_dependency "hashie", ">= 2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trusty
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Joel Van Horn
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-20 00:00:00.000000000 Z
+date: 2013-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,34 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  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: rails
+  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: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +80,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Trusty is a configuration and utilities library.
 email:
 - joel@joelvanhorn.com
@@ -67,14 +109,19 @@ files:
 - lib/trusty.rb
 - lib/trusty/environment.rb
 - lib/trusty/environment/dot_file_parser.rb
+- lib/trusty/omniauth.rb
+- lib/trusty/omniauth/mapping_helpers.rb
+- lib/trusty/omniauth/model_mapper.rb
+- lib/trusty/omniauth/provider_mapper.rb
 - lib/trusty/utilities.rb
 - lib/trusty/utilities/method_name.rb
 - lib/trusty/utilities/method_name_extensions.rb
 - lib/trusty/utilities/path_finder.rb
 - lib/trusty/utilities/yaml.rb
+- lib/trusty/utilities/yaml_context.rb
 - lib/trusty/version.rb
 - trusty.gemspec
-homepage: ''
+homepage: https://github.com/joelvh/trusty
 licenses:
 - MIT
 metadata: {}