stockor-core 0.2

data/lib/skr/concerns/attr_accessor_with_default.rb

@@ -0,0 +1,54 @@
+module Skr::Concerns
+
+    # @see ClassMethods
+    module AttrAccessorWithDefault
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+
+            # defines a attr_accessor with a default value
+            # @param name [ Symbol ] name of the attribute
+            # @param default [ Object, lambda, Proc ] if a value is given, be aware that it will be shared between instances
+            # @example
+            #
+            #     Shared = Struct.new(:str)
+            #     class AttrTestClass
+            #         include AttrAccessorWithDefault
+            #         attr_accessor_with_default :non_copying, ->{ Shared.new("a default string") }
+            #         attr_accessor_with_default :shared, Shared.new("a default string")
+            #     end
+            #     a = AttrTestClass.new
+            #     b = AttrTestClass.new
+            #     a.non_copying.str                   #=> "a default string"
+            #     a.non_copying.str  = "new_string"   #=> "new string"
+            #     b.non_copying.str                   #=> "a default string"
+            #
+            #     a.shared.str                   #=> "a default string"
+            #     b.shared.str                   #=> "a default string"
+            #     a.shared.str = "new string"    #=> "new string"
+            #     b.shared.str                   #=> "new string"
+
+            def attr_accessor_with_default( name, default )
+                attr_writer name
+                attr_reader_with_default( name, default )
+            end
+
+            def attr_reader_with_default( name, default )
+                module_eval do
+                    define_method( name ) do
+                        class << self; self; end.class_eval do
+                            attr_reader( name )
+                        end
+                        if instance_variables.include? "@#{name}"
+                            instance_variable_get( "@#{name}" )
+                        else
+                            instance_variable_set( "@#{name}", default.is_a?(Proc) ? default.call : default )
+                        end
+                    end
+                end
+            end
+        end
+    end
+
+
+end

data/lib/skr/concerns/code_identifier.rb

@@ -0,0 +1,43 @@
+module Skr
+    module Concerns
+
+        # @see ClassMethods
+        module CodeIdentifier
+
+            extend ActiveSupport::Concern
+
+            # ### Code Identifier Concern
+            # This adds the {#has_code_identifier} class method
+            module ClassMethods
+
+                # A 2-10 character string that identifies an entity, such as a Customer, Vendor, or SKU.
+                # The code is often assigned by the user, but may also
+                # be auto-generated by {Skr::Core::Strings.code_identifier}
+                #
+                # @param max_length [Integer] how long the code is allowed to be
+                # @param from [Symbol], method to call for a string to base the code upon
+                def has_code_identifier( from: nil, max_length: 10 )
+
+                    validates :code, :length=>2..max_length, :presence=>true, :uniqueness=>true
+
+                    alias_attribute :record_identifier, :code
+
+                    if from
+                        before_validation(:on=>:create) do
+                            source = self[from]
+                            unless source.blank?
+                                self.code ||= Skr::Core::Strings.code_identifier( source, length:max_length )
+                            end
+                        end
+                    end
+
+                    before_validation do
+                        self.code = self.code.upcase unless self.code.blank?
+                    end
+                end
+
+            end
+
+        end
+    end
+end

data/lib/skr/concerns/export_associations.rb

@@ -0,0 +1,52 @@
+module Skr::Concerns
+
+    # @see ClassMethods
+    module ExportAssociations
+        extend ActiveSupport::Concern
+
+        included do
+            class_attribute :exported_associations
+        end
+
+        module ClassMethods
+            # Mark associations as exported, meaning they can be quered against and optionally written to
+            # @param associations [list of Symbols]
+            # @option options [Boolean] :writable should the associations accept nested attributes
+            # @option options [Boolean] :mandatory should the association be included with it's parent at all times?
+            # @option options [Symbol referring to a method, lambda] :limit restrict to Users for whom true is returned
+            def export_associations( *associations )
+                self.exported_associations ||= {}
+                associations.flatten!
+                options = associations.extract_options!
+                associations.each do | assoc_name |
+                    self.exported_associations[ assoc_name.to_sym ] = options
+                    if options[:writable]
+                        accepts_nested_attributes_for( assoc_name, options.except(:writable, :optional) )
+                    end
+                    if false == options[:optional]
+                        self.export_methods( *assoc_name, { :optional=>false })
+                    end
+                end
+            end
+
+            # If the association is exported it may be queried against and it's data included
+            # along with the parent record.  It may not be written to unless the :writable flag
+            # was set, in which case it'll be allowed by has_exported_association?
+            def has_exported_association?( association, user )
+                self.exported_associations &&
+                    ( options = self.exported_associations[ association.to_sym ] ) &&
+                    evaluate_export_limit( user, :association, association, options[:limit] )
+            end
+
+            # Does the association allow writes?  True if the association has been exported
+            # and it accepts nested attributes
+            def has_exported_nested_attribute?( association, user )
+                self.nested_attributes_options[ association.to_sym ] &&
+                    self.has_exported_association?( association, user )
+            end
+
+        end
+
+    end
+
+end

data/lib/skr/concerns/export_join_tables.rb

@@ -0,0 +1,39 @@
+module Skr::Concerns
+
+    module ExportJoinTables
+
+        extend ActiveSupport::Concern
+
+        included do
+            class_attribute :exported_join_tables
+        end
+
+        module ClassMethods
+            # Mark a joined table as safe to be included in a query
+            # Primarily used for joining a model to a view for access to summarized data
+            def export_join_tables( *tables )
+                include ExportedLimitEvaluator
+                self.exported_join_tables ||= []
+                tables.flatten!
+                options = tables.extract_options!
+                tables.each do | join_name |
+                    self.exported_join_tables << {
+                        name: join_name,
+                        limit: options[:limit]
+                    }
+                end
+
+            end
+
+            # Has the join been marked as safe?
+            def has_exported_join_table?(name, user)
+                return true if name == 'details' # "details" is reserved for views and is always allowed
+                self.exported_join_tables && self.exported_join_tables.detect{ | join |
+                    join[:name] == name && evaluate_export_limit( user, :join, join[:name], join[:limit] )
+                }
+            end
+
+        end
+    end
+
+end

data/lib/skr/concerns/export_methods.rb

@@ -0,0 +1,104 @@
+module Skr::Concerns
+
+    # @see ClassMethods
+    module ExportMethods
+        extend ActiveSupport::Concern
+
+        included do
+
+            # methods that the model has exported.  Not intended for querying directly.
+            # The API and interested parties should call {#has_exported_method?}
+            class_attribute :exported_methods
+        end
+
+        module ClassMethods
+
+            # Called by a model to export methods to the API
+            # An exported method will be called and it's results returned along with the models
+            # JSON representation.
+            # @option options [Boolean] :optional if false, the method will always be called and included
+            # @option options [Symbol, Array of Symbols] :depends name(s) of associations that should
+            #     be pre-loaded before calling method. Intended to prevent N+1 queries
+            def export_methods( *method_names )
+                method_names.flatten!
+                options = method_names.extract_options!
+                self.exported_methods ||= {}
+                method_names.map do | name |
+                    exported_methods[ name.to_sym] = options
+                end
+            end
+
+            # Convenience method to create a Rails delegation and export the resulting method
+            # @example
+            #     class Foo < Skr::Model
+            #           belongs_to :bar
+            #           delegate_and_export :bar_name, :optional=>false
+            #     end
+            #
+            #     foo = Foo.new
+            #     foo.bar_name #=> calls foo.bar.name
+            #     Foo.has_exported_method?( :bar_name )  #=> true
+            #     skr_to_json( foo ) #=> will first load the bar association, then
+            #                            call foo.bar_name and include it's result in the JSON
+            def delegate_and_export( *names )
+                options = names.extract_options!
+                names.each do | name |
+                    target,field = name.to_s.split(/_(?=[^_]+(?: |$))| /)
+                    delegate_and_export_field( target, field, optional: options[:optional], limit: options[:limit] )
+                end
+            end
+
+            # For situations where the delegate_and_export method guesses wrong on the association and field names
+            # @param target [Association] association to delegate to
+            # @param field  [Symbol] method on Association to call
+            # @param optional [Boolean] should the method be called and results included all the time,
+            #                    or only if specifically requested
+            # @param limit [Symbol referring to a method, lambda] restrict to Users for whom true is returned
+            # @example
+            #     class PoLine < Skr::Model
+            #           belongs_to :purchase_order
+            #           delegate_and_export :purchase_order_visible_id
+            #     end
+            # would generate a method ``purchase_order_visible_id`` that would call ``purchase_order_visible.id``
+            # This would do the right thing:
+            #     class PoLine < Skr::Model
+            #           belongs_to :purchase_order
+            #           delegate_and_export_field :purchase_order, :visible_id
+            #     end
+            def delegate_and_export_field( target, field, optional: true, limit: nil )
+                delegate field, to: target, prefix: target, allow_nil: true
+                self.export_methods( "#{target}_#{field}", { depends: target.to_sym,
+                                                             optional: optional,
+                                                             limit: limit } )
+            end
+
+            # Check if the method can be called by user
+            def has_exported_method?( name, user )
+                if self.exported_methods && ( method_options = self.exported_methods[ name.to_sym ] )
+                    return evaluate_export_limit( user, :method, name, method_options[:limit] )
+                else
+                    return false
+                end
+            end
+
+            # Retrieve the list of dependent associations for the given methods
+            # Also includes methods that were exported as ``optional: false``
+            # @param requested_methods [Array] methods that the user has requested be executed and added to the JSON payload
+            # @return [Array] list of associations that should be included in query
+            def exported_method_dependancies( requested_methods )
+                requested_methods.map!(&:to_sym)
+                return [] if self.exported_methods.blank?
+                depends = self.exported_methods.each_with_object(Array.new) do | kv, result |
+                    ( export, options ) = kv
+                    if options[:depends] && ( false == options[:optional] || requested_methods.include?(export) )
+                        result << options[:depends]
+                    end
+                end
+                depends.uniq
+            end
+        end
+
+
+    end
+
+end

data/lib/skr/concerns/export_scope.rb

@@ -0,0 +1,66 @@
+require_relative 'exported_limit_evaluator'
+
+module Skr::Concerns
+
+    # @see ClassMethods
+    module ExportScope
+        extend ActiveSupport::Concern
+
+        included do
+            # scopes that the model has exported.  Not intended for querying directly.
+            # The API and interested parties should call {#has_exported_scope?}
+            class_attribute :exported_scopes
+            extend ExportedLimitEvaluator
+        end
+
+        # ### Mark a scope as "exportable"
+        #
+        # An exported scope is safe for querying by external clients over the API.
+        # The scope should always:
+        #
+        #  * Safely escape data *(should __ALWAYS__ do this anyway, but it bears mentioning again)*
+        #  * Be relatively simple and complete quickly.
+        #  * Provide value to the client that it cannot obtain by using normal query methods
+        module ClassMethods
+            def scope(name, body, options = {}, &block)
+                super(name, body, &block)
+                if (export = options[:export])
+                    export_scope(name, body, limit: (export == true ? nil : export[:limit]))
+                end
+            end
+
+            # Mark scope as query-able by the API.
+            # @param name [Symbol,String] Rails will create a class method with this name
+            # @param query [lambda] Arel query.  This is passed off to Rail's for setting up the scope.
+            # @param limit [Symbol referring to a Class method name, lambda]
+            # If given, this will be queried by the API to determining if a given user may call the scope
+            # @return nil
+            def export_scope(name, query, limit: nil)
+                include ExportedLimitEvaluator
+
+                self.exported_scopes ||= Hash.new
+                self.exported_scopes[name.to_sym] = {
+                    scope: scope(name, query),
+                    name: name,
+                    limit: limit
+                }
+                nil
+            end
+
+            # The api can query this to determine if the scope is safe to be called
+            # from the API by [user]
+            # @param name [Symbol,String] name of scope
+            # @param user [User] who is performing the request.
+            #   This is passed off to the method or lambda that was given as the limit  argument in {#export_scope}
+
+            def has_exported_scope?(name, user)
+                if self.exported_scopes && ( scope_options = self.exported_scopes[ name.to_sym ] )
+                    return evaluate_export_limit( user, :scope, name, scope_options[:limit] )
+                else
+                    return false
+                end
+            end
+
+        end
+    end
+end

data/lib/skr/concerns/exported_limit_evaluator.rb

@@ -0,0 +1,17 @@
+module Skr::Concerns
+
+    module ExportedLimitEvaluator
+
+        def evaluate_export_limit( user, type, name, limit )
+            if limit.nil?
+                true
+            elsif limit.is_a?(Symbol)
+                self.send( limit, user, type, name )
+            else
+                limit.call( user, type, name )
+            end
+        end
+
+    end
+
+end

data/lib/skr/concerns/gl_tran_extensions.rb

@@ -0,0 +1,18 @@
+module Skr
+    module Concerns
+
+        module GlTran
+
+            module Postings
+
+                def total
+                    total = BigDecimal.new('0')
+                    each{ |pst| total+=pst.amount }
+                    total
+                end
+
+            end
+
+        end
+    end
+end

data/lib/skr/concerns/has_gl_transaction.rb

@@ -0,0 +1,67 @@
+require 'active_record/validations'
+
+module Skr
+
+    class InvalidGlTransaction < ActiveRecord::RecordInvalid
+    end
+
+
+    module Concerns
+
+        module HasGlTransaction
+
+            extend ActiveSupport::Concern
+
+            module InstanceMethods
+
+                # N.B. We are overriding ActiveRecord::Base#save
+                # This is so we can wrap the save call inside a {GlTransaction.record} block
+                # which will collect any GlPostings and then collapse them down at the end of the block
+                # in order to prevent multiple postings to the same account.
+                def save(*)
+                    opts = options_for_gl_transaction
+                    # do nothing if the options specified an if clause and the method returns false
+                    if opts.present? and opts.has_key?(:if) and self.send( opts[:if] ) == false
+                        super
+                    else
+                        save_status = false
+                        # First we wrap it up in our transaction since we don't have the benefit of
+                        # save's rollback_active_record_state! block
+                        # I'm tempted to appropriate it's usage, but am not since it's not documented (that I've found)
+                        # and is thus likely to change
+                        GlTransaction.transaction( requires_new: true ) do
+                            # Enclose in GlTransaction#record block
+                            gl_transaction = GlTransaction.record do
+                                save_status = super # ActiveRecord::Base#save
+                                # If save was successfull, pass attributes back to GlTransaction#record.
+                                # Otherwise pass false back so it knows to not save the GlTransaction
+                                save_status ? { attributes: self.send( opts[:attributes] ) } : false
+                            end
+                            # if we saved successfully, but the GlTransaction did not;
+                            #   Copy the errors to the model and abort the transaction
+                            if save_status && gl_transaction.errors.any?
+                                self.errors[:gl_transaction] += gl_transaction.errors.full_messages
+                                save_status = false
+                                raise InvalidGlTransaction.new(gl_transaction)
+                            end
+                        end
+                        return save_status
+                    end
+                end
+
+            end
+
+            module ClassMethods
+
+                def has_gl_transaction( options={} )
+                    options.merge!( attributes: :attributes_for_gl_transaction )
+                    cattr_accessor :options_for_gl_transaction
+                    self.options_for_gl_transaction = options unless options.empty?
+                    self.send :include, InstanceMethods
+                end
+
+            end
+
+        end
+    end
+end