qbfc 0.1.0-x86-mswin32-60

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jared E Morgan
+
+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

@@ -0,0 +1,41 @@
+==QBFC-Ruby
+
+QBFC-Ruby provides a wrapper around QuickBooks' QBFC COM object, while
+allowing more or less direct access to the actual COM object.
+
+Obviously, test before using on your production data...
+
+==Examples
+
+  # A very simple example, finding a single Customer by name
+  QBFC::session do | qb |
+    puts qb.customer('Customer Name').full_name
+  end
+  
+  # Find all Customer, then return the first in the Array
+  # Next, find the first Customer only
+  QBFC::session do | qb |
+    customers = qb.customers.find(:all)
+    puts customers[0].full_name
+    puts qb.customers.find(:first).full_name
+  end
+
+  # Same as previous, but not using a block  
+  sess = QBFC::Session.new
+  customers = QBFC::Customer.find(sess, :all)
+  puts customers[0].full_name
+  puts QBFC::Customer.find(sess, :first).full_name
+  sess.close
+
+  # Use a QBFC::Session object, but access the COM object
+  # more directly.
+  QBFC::session do | qb |
+    request_set = qb.CreateMsgSetRequest("US", 6, 0)
+    customer_query = request_set.AppendCustomerQueryRq	
+    response = qb.DoRequests(request_set)
+    customer_set = response.ResponseList[0]
+    first_customer = customer_set.Detail[0]
+    puts first_customer.full_name
+  end
+
+Copyright (c) 2008 Jared E. Morgan, released under the MIT license

data/Rakefile

@@ -0,0 +1,82 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+gem 'rspec'
+require 'spec/rake/spectask'
+
+QBFC_ROOT = File.dirname(__FILE__)
+
+task :default => :spec
+
+desc "Run all specs in spec/unit directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+  t.spec_files = FileList['spec/unit/**/*_spec.rb']
+end
+
+namespace :spec do
+  desc "Run all specs in spec/unit directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+    t.spec_files = FileList['spec/unit/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = lambda do
+      IO.readlines("#{QBFC_ROOT}/spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+    end
+  end
+  
+  desc "Run all specs in spec/integration directory"
+  Spec::Rake::SpecTask.new(:integration) do |t|
+    t.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+    t.spec_files = FileList['spec/integration/**/*_spec.rb']
+  end
+
+  desc "Run all specs in spec/integration directory with RCov"
+  Spec::Rake::SpecTask.new(:integration_rcov) do |t|
+    t.spec_opts = ['--options', "\"#{QBFC_ROOT}/spec/spec.opts\""]
+    t.spec_files = FileList['spec/integration/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = lambda do
+      IO.readlines("#{QBFC_ROOT}/spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
+    end
+  end
+  
+  desc "Print Specdoc for all specs"
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.spec_opts = ["--format", "specdoc", "--dry-run"]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+end
+
+desc 'Generate documentation for the qbfc library.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'QBFC-Ruby'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'rubygems'
+Gem::manage_gems
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s|
+  s.name = "qbfc"
+  s.version = "0.1.0"
+  s.author = "Jared Morgan"
+  s.email = "jmorgan@morgancreative.net"
+  s.homepage = "http://rubyforge.org/projects/qbfc/"
+  s.rubyforge_project = "qbfc"
+  s.platform = Gem::Platform::CURRENT
+  s.summary = "A wrapper around the QBFC COM object of the Quickbooks SDK"
+  s.files = FileList['lib/**/*.rb', 'bin/*', '[A-Z]*', 'spec/*.opts', 'spec/*.rb', 'spec/unit/**/*'].to_a
+  s.require_path = "lib"
+  s.test_files = Dir.glob('spec/unit/**/*_spec.rb')
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README"]
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end

data/lib/qbfc.rb

@@ -0,0 +1,39 @@
+require 'win32ole'
+require 'time'
+
+# ActiveSupport is used for camelize, singularize and similar String inflectors.
+unless Object.const_defined?(:ActiveSupport)
+  gem 'activesupport'
+  require 'active_support'
+end
+
+module QBFC
+  class << self
+  
+    # Opens and yields a QBFC::Session
+    def session(*args, &block)
+      QBFC::Session::open(*args, &block)
+    end
+  
+    # Generate classes.
+    # - +names+: Array of class names.
+    # - +superclass+: Superclass of classes to be generated.
+    # - +includes+: hash of Module => names of classes to include this module.
+    def generate(names, superclass, include_modules = {})
+      names.each do | class_name |
+        const_set(class_name, Class.new(superclass))
+      end
+      
+      include_modules.each do | mod, classes |
+        classes.each do | class_name |
+          const_get(class_name).__send__(:include, mod)
+        end
+      end
+    end
+    
+  end
+end
+
+%w{ ole_wrapper qbfc_const session request base element info qb_collection qb_types }.each do |file|
+  require File.dirname(__FILE__) + '/qbfc/' + file
+end

data/lib/qbfc/base.rb

@@ -0,0 +1,82 @@
+module QBFC
+  # Base is the...um..."base" class from which Element, Info, and
+  # Report inherit. It defines methods that the three share.
+  class Base
+    class << self
+        
+      # is_base_class? is used by Element and subclasses. It is included
+      # in Base because some Base methods may check for it.
+      def is_base_class? #:nodoc:
+        false
+      end
+      
+      # Element::find and Info::get receive optional arguments which can include
+      # a Request object and/or an options Hash. <tt>parse_find_args</tt>
+      # gets these arguments into a set that is easier to deal with.
+      def parse_find_args(*args)
+        request = args[0].kind_of?(QBFC::Request) ? args[0] : nil
+        options = args[-1].kind_of?(Hash) ? args[-1] : {}
+        
+        # base classes will need to pass a subset of options to
+        # the ChildClass.find . Also, the actually options to the
+        # BaseClass.find Request cannot include owner_id.
+        if is_base_class?
+          base_options = options.dup 
+          base_options.delete(:conditions)
+          options.delete(:owner_id)
+        else
+          base_options = nil
+        end
+        
+        return request, options, base_options
+      end
+      
+      # A convenience method for creating and returning
+      # a Query Request for this class.
+      def create_query(sess)
+        QBFC::Request.new(sess, "#{qb_name}Query")
+      end
+      
+      protected :parse_find_args, :create_query
+    
+      # The QuickBooks name for this Element or Report.
+      # It typically matches the last part of class name.
+      # Used in determining names of Requests and other
+      # OLE methods.
+      def qb_name
+        self.name.split('::').last
+      end
+    end
+    
+    # Create an instance of this Element or Report.
+    # - <tt>sess</tt>: An open QBFC::Session object that will recieve all requests
+    # - <tt>ole</tt>: An optional QBFC::OLEWrapper object representing
+    #   a response to a QueryRq. It is unlikely that this will be used directly.
+    def initialize(sess, ole = nil)
+      @sess, @ole = sess, ole    
+      @ole = QBFC::OLEWrapper.new(@ole) if @ole.kind_of?(WIN32OLE)    
+    end
+    
+    # List the methods of the OLE object
+    def ole_methods
+      @ole.ole_methods
+    end
+    
+    # Check if the OLE object responds to a given method
+    def respond_to_ole?(symbol)
+      @ole.respond_to_ole?(symbol)
+    end
+    
+    # Pass missing methods to OLEWrapper#qbfc_method_missing
+    # to handle checking if there is a related OLE method to run.
+    def method_missing(symbol, *params)
+      @ole.qbfc_method_missing(@sess, symbol, *params)
+    end
+    
+    # Name of the QuickBooks Element or Query represented by this class.
+    def qb_name
+      self.class.qb_name
+    end
+  end
+end
+

data/lib/qbfc/element.rb

@@ -0,0 +1,178 @@
+require File.dirname(__FILE__) + '/modifiable'
+
+module QBFC
+
+  # An Element is a Transaction or a List; that is any QuickBooks objects that can
+  # be created, edited (possibly), deleted and read. Contrast to a Report or Info
+  # which are read-only.
+  # 
+  # Inheritance from Element implies a set of shared methods, such as find, but the
+  # only shared implementation defined here is #custom, for getting custom field information.
+  class Element < Base
+
+    class << self
+      # Set that this is a "base class", one which is inherited,
+      # such as List, Transaction, Entity, or Terms.
+      # Base classes do not accept Add Requests, and their finders
+      # will return an instance of an inherited class.
+      def is_base_class
+        @is_base_class = true
+      end
+      
+      # Check if this is a "base class" (see is_base_class)
+      def is_base_class?
+        @is_base_class ? true : false
+      end
+      
+      # Find a QuickBooks record for the given session. 
+      # 
+      # session.[qb_name] aliases this functionality. The following
+      # pairs are equivalent:
+      # 
+      #   QBFC::Vendor.find(session, :first) <-> session.vendor
+      #   QBFC::Vendor.find(session, "Supply Shop") <-> session.vendor("Supply Shop")
+      #   QBFC::Vendor.find(session, :all) <-> session.vendors.find(:all)
+      # 
+      # Find requires a +session+ (representing a QBFC::Session) and
+      # a +what+ argument. +what+ can be one of:
+      # - <tt>:first</tt> - finds the first record fitting any given conditions.
+      # - <tt>:finds</tt> - finds all records fitting any given conditions.
+      # - An unique identifier, such as a ListID, FullName, RefNumber or TxnID
+      # 
+      # .find can also receive a optional Request object followed 
+      # by an optional options Hash. Valid argument sets are:
+      # 
+      #   QBFC::Vendor.find(session, :first)
+      #   QBFC::Vendor.find(session, :first, request)
+      #   QBFC::Vendor.find(session, :first, request, options)
+      #   QBFC::Vendor.find(session, :first, options)
+      # 
+      # The options hash accepts the following:
+      # - <tt>:owner_id</tt>: One or more OwnerIDs, used in accessing
+      #   custom fields (aka private data extensions).
+      # 
+      # Additional options are planned, but not really supported in this version.
+      # Passing a Request object is the current recommended way of applying
+      # Filters or other options to the Query Request.
+      def find(sess, what, *args)
+        
+        if what.kind_of?(String) # Single FullName or ListID
+          return find_by_unique_id(sess, what, *args)
+        end
+        
+        # Setup q, options and base_options arguments
+        q, options, base_options = parse_find_args(*args)
+        q ||= create_query(sess)
+        q.apply_options(options)
+        
+        # QuickBooks only needs to return one record if .find is
+        # only returning a single record.
+        if what == :first && q.filter_available?
+          q.filter.max_returned = 1
+        end
+        
+        # Send the query so far to base_class_find if this is
+        # a base class to handle special base class functionality.
+        return base_class_find(sess, what, q, base_options) if is_base_class?
+        
+        # Get response and return an Array, a QBFC::Element-inherited
+        # object, or nil, depending on <tt>what</tt> argument and whether
+        # the query returned any records.
+        list = q.response
+        
+        if list.nil?
+          (what == :all) ? [] : nil
+        elsif what == :all
+          (0..(list.Count - 1)).collect { |i|
+            new(sess, list.GetAt(i))
+          }
+        else
+          new(sess, list.GetAt(0))
+        end
+      end
+      
+      # Base classes can be used to find members of any of their
+      # inherited classes. Since QuickBooks has limited options
+      # for these type of queries (in particular, no custom fields
+      # are returned), an initial query is run which retrieves
+      # only IDs and the class type and then individual subsequent
+      # queries are run for each returned object.
+      def base_class_find(sess, what, q, options)
+        q.IncludeRetElementList.Add(self::ID_NAME)
+        list = q.response
+        
+        if list.nil?
+          (what == :all) ? [] : nil
+        else
+          ary = (0..(list.Count - 1)).collect { |i|
+            element = list.GetAt(i)
+            ret_name = element.ole_methods.detect{ |m| m.to_s =~ /(.*)Ret\Z/ }.to_s
+            ret_class = QBFC::const_get($1)
+            ret_class.find(sess, element.send(ret_name).send(ret_class::ID_NAME), options.dup)
+          }
+          
+          if what == :all
+            ary
+          else
+            ary[0]
+          end
+        end
+      end
+      
+      private :base_class_find
+
+    end
+    
+    is_base_class
+    
+    # Extends Base#initialize to allow for an Add Request if
+    # .new is called directly (instead of by .find)
+    def initialize(sess, ole_object = nil)
+      if self.class.is_base_class?
+        raise BaseClassNewError, "This is a base class which doesn't allow object initialization"
+      end
+      
+      super
+      
+      if @ole.nil?
+        add_rq = QBFC::Request.new(sess, "#{qb_name}Add")
+        @ole = QBFC::OLEWrapper.new(add_rq.ole_object)
+        @new_record = true
+        @setter = add_rq
+      end
+    end
+    
+    # Is this a new record, i.e. are we doing an Add Request?
+    def new_record?
+      @new_record ? true : false
+    end
+  
+    # Access information from a custom field.
+    def custom(field_name, owner_id = 0)
+      if @ole.DataExtRetList
+        @ole.data_ext.each do |field|
+          if field.data_ext_name == field_name && field.owner_id == owner_id
+            return field.data_ext_value
+          end
+        end
+      end
+      
+      return nil
+    end
+    
+    # Save (create or update) this record
+    def save
+      if @setter
+        @setter.submit
+      else
+        raise NotSavableError, "This record cannot be saved (Probably because it does not support Mod Requests)."
+      end
+    end
+    
+  end
+end
+
+# Require subclass files
+%w{ list transaction }.each do |file|
+  require File.dirname(__FILE__) + '/' + file
+end