qbxml 0.1.3

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/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+gemspec
+
+# test
+gem 'pry'
+gem 'pry-nav'
+gem 'rspec'
+gem 'simplecov', require: false, group: :test
+
+# backwards compatibility tests
+gem 'quickbooks_api', path: '../old/quickbooks_api'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Alex Skryl
+
+MIT License
+
+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,95 @@
+# Qbxml
+
+Qbxml is a QBXML parser and validation tool.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'qbxml'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install qbxml
+
+## Usage
+
+### Initialization
+
+The parser can be initialized to either Quickbooks (:qb) or Quickbooks Point of
+Sale (:qbpos)
+
+```ruby
+q = Qbxml.new(:qb)
+```
+
+### API Introspection
+
+Return all types defined in the schema
+
+```ruby
+q.types
+```
+
+Return all types matching a certain pattern
+
+```ruby
+q.types('Customer')
+
+q.types(/Customer/)
+```
+
+Print the xml template for a specific type
+
+```ruby
+puts q.describe('CustomerModRq')
+```
+
+### QBXML To Ruby
+
+Convert valid QBXML to a ruby hash
+
+```ruby
+q.from_qbxml(xml)
+```
+
+### Ruby To QBXML
+
+Convert a ruby hash to QBXML, skipping validation
+
+```ruby
+q.to_qbxml(hsh)
+```
+
+Convert a ruby hash to QBXML and validate all types
+
+```ruby
+q.to_qbxml(hsh, validate: true)
+```
+
+## Caveats
+
+Correct case conversion depends on the following ActiveSupport inflection
+settings. Correct behaviour cannot be guaranteed if any of the following
+inflections are modified.
+
+```ruby
+ACRONYMS = ['AP', 'AR', 'COGS', 'COM', 'UOM', 'QBXML', 'UI', 'AVS', 'ID',
+            'PIN', 'SSN', 'COM', 'CLSID', 'FOB', 'EIN', 'UOM', 'PO', 'PIN', 'QB']
+
+ActiveSupport::Inflector.inflections do |inflect|
+  ACRONYMS.each { |a| inflect.acronym a }
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

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

data/TODO.md

@@ -0,0 +1,3 @@
+stupid backwards compatibility
+- rename :xml_attributes to __attributes__
+- remove empty xml_attributes hashes

data/lib/qbxml.rb

@@ -0,0 +1,12 @@
+require "qbxml/version"
+
+require 'nokogiri'
+require 'active_support/builder'
+require 'active_support/inflections'
+require 'active_support/core_ext/string'
+
+class Qbxml; end
+
+require_relative 'qbxml/types.rb'
+require_relative 'qbxml/qbxml.rb'
+require_relative 'qbxml/hash.rb'

data/lib/qbxml/hash.rb

@@ -0,0 +1,148 @@
+# XML Conversion References
+#
+# https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/hash/conversions.rb
+# https://github.com/rails/rails/blob/master/activesupport/lib/active_support/xml_mini/nokogiri.rb
+#
+#
+class Qbxml::Hash < ::Hash
+  include Qbxml::Types
+
+  CONTENT_ROOT = '__content__'.freeze
+  ATTR_ROOT    = 'xml_attributes'.freeze
+  IGNORED_KEYS = [ATTR_ROOT]
+
+  
+  def self.from_hash(hash, opts = {}, &block)
+    key_proc = \
+      if opts[:camelize]
+        lambda { |k| k.camelize } 
+      elsif opts[:underscore]
+        lambda { |k| k.underscore } 
+      end
+
+    deep_convert(hash, opts, &key_proc)
+  end
+
+  def to_xml(opts = {})
+    hash = self.class.to_xml(self, opts)
+  end
+
+  def self.to_xml(hash, opts = {})
+    opts[:root], hash = hash.first
+    opts[:attributes] = hash.delete(ATTR_ROOT)
+    hash_to_xml(hash, opts)
+  end
+
+  def self.from_xml(xml, opts = {})
+    from_hash(
+      xml_to_hash(Nokogiri::XML(xml).root, {}, opts), opts)
+  end
+
+private
+
+  def self.hash_to_xml(hash, opts = {})
+    opts = opts.dup
+    opts[:indent]          ||= 2
+    opts[:root]            ||= :hash
+    opts[:attributes]      ||= (hash.delete(ATTR_ROOT) || {})
+    opts[:xml_directive]   ||= [:xml, {}]
+    opts[:builder]         ||= Builder::XmlMarkup.new(indent: opts[:indent])
+    opts[:skip_types]      = true unless opts.key?(:skip_types) 
+    opts[:skip_instruct]   = false unless opts.key?(:skip_instruct)
+    builder = opts[:builder]
+    
+    unless opts.delete(:skip_instruct)
+      builder.instruct!(opts[:xml_directive].first, opts[:xml_directive].last)
+    end
+
+    builder.tag!(opts[:root], opts.delete(:attributes)) do
+      hash.each do |key, val| 
+        case val
+        when Hash
+          self.hash_to_xml(val, opts.merge({root: key, skip_instruct: true}))
+        when Array
+          val.map { |i| self.hash_to_xml(i, opts.merge({root: key, skip_instruct: true})) }
+        else
+          builder.tag!(key, val, {})
+        end
+      end
+
+      yield builder if block_given?
+    end
+  end
+  
+  def self.xml_to_hash(node, hash = {}, opts = {})
+    node_hash = {CONTENT_ROOT => '', ATTR_ROOT => {}}
+    name = node.name
+    schema = opts[:schema]
+
+    # Insert node hash into parent hash correctly.
+    case hash[name]
+    when Array then hash[name] << node_hash
+    when Hash  then hash[name] = [hash[name], node_hash]
+    else hash[name] = node_hash
+    end
+
+    # Handle child elements
+    node.children.each do |c|
+      if c.element?
+        xml_to_hash(c, node_hash, opts)
+      elsif c.text? || c.cdata?
+        node_hash[CONTENT_ROOT] << c.content
+      end
+    end
+
+    # Handle attributes
+    node.attribute_nodes.each { |a| node_hash[ATTR_ROOT][a.node_name] = a.value }
+
+    # TODO: Strip text
+    # node_hash[CONTENT_ROOT].strip!
+
+    # Format node
+    if node_hash.size > 2 || node_hash[ATTR_ROOT].present?
+      node_hash.delete(CONTENT_ROOT)
+    elsif node_hash[CONTENT_ROOT].present?
+      node_hash.delete(ATTR_ROOT)
+      hash[name] = \
+        if schema
+          typecast(schema, node.path, node_hash[CONTENT_ROOT])
+        else
+          node_hash[CONTENT_ROOT]
+        end
+    else
+      hash[name] = node_hash[CONTENT_ROOT]
+    end
+
+    hash
+  end
+
+
+private
+
+  def self.typecast(schema, xpath, value)
+    type_path = xpath.gsub(/\[\d+\]/,'')
+    type_proc = Qbxml::TYPE_MAP[schema.xpath(type_path).first.try(:text)]
+    raise "#{xpath} is not a valid type" unless type_proc
+    type_proc[value]
+  end
+
+  def self.deep_convert(hash, opts = {}, &block)
+    hash.inject(self.new) do |h, (k,v)|
+      ignored = IGNORED_KEYS.include?(k) 
+      if ignored
+        h[k] = v
+      else
+        key = block_given? ? yield(k.to_s) : k
+        h[key] = \
+          case v
+          when Hash
+            deep_convert(v, &block)
+          when Array
+            v.map { |i| i.is_a?(Hash) ? deep_convert(i, &block) : i }
+          else v
+          end
+      end; h
+    end
+  end
+
+end

data/lib/qbxml/qbxml.rb

@@ -0,0 +1,102 @@
+class Qbxml
+  include Types
+
+  SCHEMA_PATH = File.expand_path('../../../schema', __FILE__)
+
+  SCHEMAS = {
+    qb:    "#{SCHEMA_PATH}/qbxmlops70.xml",
+    qbpos: "#{SCHEMA_PATH}/qbposxmlops30.xml" 
+  }.freeze
+
+  HIDE_IVARS = [:@doc].freeze
+
+  def initialize(key = :qb)
+    @schema = key
+    @doc    = parse_schema(key)
+  end
+
+  # returns all xml nodes matching a specified pattern
+  #
+  def types(pattern = nil)
+    @types ||= @doc.xpath("//*").map { |e| e.name }.uniq
+
+    pattern ?
+      @types.select { |t| t =~ Regexp.new(pattern) } :
+      @types
+  end
+
+  # returns the xml node for the specified type
+  #
+  def describe(type)
+    @doc.xpath("//#{type}").first
+  end
+
+  # converts a hash to qbxml with optional validation
+  #
+  def to_qbxml(hash, opts = {})
+    hash = Qbxml::Hash.from_hash(hash, camelize: true)
+    hash = namespace_qbxml_hash(hash) unless opts[:no_namespace] 
+    validate_qbxml_hash(hash) if opts[:validate]
+
+    Qbxml::Hash.to_xml(hash, xml_directive: XML_DIRECTIVES[@schema])
+  end
+
+  # converts qbxml to a hash
+  #
+  def from_qbxml(xml, opts = {})
+    hash = Qbxml::Hash.from_xml(xml, underscore: true, schema: @doc)
+
+    opts[:no_namespace] ? hash : namespace_qbxml_hash(hash)
+  end
+
+  # making this more sane so that it doesn't dump the whole schema doc to stdout
+  # every time
+  #
+  def inspect
+    prefix = "#<#{self.class}:0x#{self.__id__.to_s(16)} "
+
+    (instance_variables - HIDE_IVARS).each do |var|
+      prefix << "#{var}=#{instance_variable_get(var).inspect}"
+    end
+
+    return "#{prefix}>"
+  end
+
+# private
+
+  def parse_schema(key)
+    File.open(select_schema(key)) { |f| Nokogiri::XML(f) }
+  end
+
+  def select_schema(schema_key)
+    SCHEMAS[schema_key] || raise("invalid schema, must be one of #{SCHEMA.keys.inspect}")
+  end
+
+# hash to qbxml
+
+  def namespace_qbxml_hash(hash)
+    node = describe(hash.keys.first)
+    return hash unless node
+
+    path = node.path.split('/')[1...-1].reverse
+    path.inject(hash) { |h,p| Qbxml::Hash[ p => h ] }
+  end
+
+  def validate_qbxml_hash(hash, path = [])
+    hash.each do |k,v|
+      next if k == Qbxml::HASH::ATTR_ROOT
+      key_path = path.dup << k
+      if v.is_a?(Hash)
+        validate_qbxml_hash(v, key_path)
+      else
+        validate_xpath(key_path)
+      end
+    end
+  end
+
+  def validate_xpath(path)
+    xpath = "/#{path.join('/')}"
+    raise "#{xpath} is not a valid type" if @doc.xpath(xpath).empty?
+  end
+
+end

data/lib/qbxml/types.rb

@@ -0,0 +1,39 @@
+module Qbxml::Types
+
+  XML_DIRECTIVES = { 
+    :qb => [:qbxml, { version: '7.0' }],
+    :qbpos => [:qbposxml, { version: '3.0' }]
+  }.freeze
+
+  FLOAT_CAST = Proc.new {|d| d ? Float(d) : 0.0}
+  BOOL_CAST  = Proc.new {|d| d ? (d == 'True' ? true : false) : false }
+  DATE_CAST  = Proc.new {|d| d ? Date.parse(d).strftime("%Y-%m-%d") : Date.today.strftime("%Y-%m-%d") }
+  TIME_CAST  = Proc.new {|d| d ? Time.parse(d).xmlschema : Time.now.xmlschema }
+  INT_CAST   = Proc.new {|d| d ? Integer(d.to_i) : 0 }
+  STR_CAST   = Proc.new {|d| d ? String(d) : ''}
+
+  TYPE_MAP= {
+    "AMTTYPE"          => FLOAT_CAST,
+    "BOOLTYPE"         => BOOL_CAST,
+    "DATETIMETYPE"     => TIME_CAST,
+    "DATETYPE"         => DATE_CAST,
+    "ENUMTYPE"         => STR_CAST,
+    "FLOATTYPE"        => FLOAT_CAST,
+    "GUIDTYPE"         => STR_CAST,
+    "IDTYPE"           => STR_CAST,
+    "INTTYPE"          => INT_CAST,
+    "PERCENTTYPE"      => FLOAT_CAST,
+    "PRICETYPE"        => FLOAT_CAST,
+    "QUANTYPE"         => INT_CAST,
+    "STRTYPE"          => STR_CAST,
+    "TIMEINTERVALTYPE" => STR_CAST
+  }
+
+  ACRONYMS = ['AP', 'AR', 'COGS', 'COM', 'UOM', 'QBXML', 'UI', 'AVS', 'ID',
+              'PIN', 'SSN', 'COM', 'CLSID', 'FOB', 'EIN', 'UOM', 'PO', 'PIN', 'QB']
+
+  ActiveSupport::Inflector.inflections do |inflect|
+    ACRONYMS.each { |a| inflect.acronym a }
+  end
+
+end