axlsx_rad 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 834382ebf19e94d28b67e1b8fdf27036cef2c31e
+  data.tar.gz: 4deb68fde5206dd7292903386aa30e8d8c61689d
+SHA512:
+  metadata.gz: c8d48310cb59052aab604e80bc6b56efc499b9fea63eb16792e64f0c647adc10a4689543565cbc2c8465ad983c8839bc3f4cd8004a966cb04fde5079e1c6eacf
+  data.tar.gz: e328b22d9cc7f3431717d7a70cc33bf510a7caafbdf9ce469c23c8d742718c582f619ce68e7090cff9b6b8d997f7e53c5870fa30f8ebf412da9f5d8f31c1f97b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+CHANGELOG
+---------
+
+- **2014-03-21**: 0.0.1
+  - Initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2014 John Wang
+ 
+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,150 @@
+AxlsxRad - Rapid XLSX Writer for Customized Spreadsheets
+========================================================
+
+Synopsis
+--------
+
+AxlsxRad provides a rapid capability to generate styled spreadsheets of JSON
+objects to enable the creation of reports with both per-row and per-cell
+highlighting.
+
+This is accomplished by leveraging JsonDoc's encapsulation of JSON objects
+with easy retrieval of property names and values as arrays that are used by
+AxlsxRad to populate XLSX spreadsheets. This is done by simply providing an
+array of JSON property keys and then adding JsonDoc objects to the worksheet.
+
+Axlsx additionally supports rapid styling of spreadsheets by accepting a
+set of styles and rules for applying those styles to each row. Both a header
+row and data rows can be styled with both default background styles for the
+entire row and custom styles on a per cell basis. Per-cell styles are assigned
+by JsonDoc property key so there is no need to create arrays of styles per
+row and to remember which column is located in which array index - it is all
+done automatically.
+
+Customization consists of:
+
+* a list of JSON property keys that are used as columns
+* a dictionary of styles by style key
+* overridable header and row methods tto provide custom styling rules
+
+Finally, Axlsx provides full access to the Axlsx package, workbook and
+worksheet objects so fast customization can be supported in addition to 
+standard access.
+
+Installing
+----------
+
+Download and install axlsx_rad with the following:
+
+    gem install axlsx_rad
+
+#Examples
+---------
+
+    require 'axlsx_rad'
+
+    # Create an AxlsxRad::Config object, often per-worksheet
+    # Define worksheet columns. These keys should exist in JsonDoc
+    # object / subclass properties.
+    columns = [ :first_name, :last_name, :email_address, :github_username ]
+
+    # Define styles
+    styles     =  {
+      :blue    => { :bg_color => '00CCFF' },
+      :green   => { :bg_color => '00FF99' },
+      :ltgreen => { :bg_color => '99FF99' },
+      :yellow  => { :bg_color => 'FFFF99' },
+      :orange  => { :bg_color => 'FFCC66' },
+      :white   => { :bg_color => 'FFFFFF' },
+      :head    => { :bg_color => '00FFFF', :b => true}
+    }
+
+    # Subclass AxlsxRad::Config object. This object has attributes: oColumns
+    # and dStylesCfg. It doesn't matter how they are set but they should be
+    # set before instantiating a AxlsxRad::Worksheet object. Additionally,
+    # the #getStylesForHeader() and #getStylesForDocument( document ) methods
+    # should be overridden to return a style hash as shown below:
+    #
+    # The contract contains: @aColumns, @dStylesCfg, #getStylesForHeader, and
+    # #getStylesForDocument( JsonDoc::Document ).
+    #
+    # The style names used in the reponse hash should correspond to the style
+    # keys used in the styles configuration hash above.
+
+    class MyWorksheetConfig < AxlsxRad::Config
+      def initialize(columns=[],styles={})
+        @aColumns   = columns
+        @dStylesCfg = styles
+      end
+      def getStylesForHeader()
+        return { :bgstyle => :head }
+      end
+      def getStylesForDocument( oDocument=nil )
+        dStyles = { :bgstyle => :white, :properties => {} }
+        if oDocument.getProp(:github_username)
+          dStyles[:bgstyle] = :green
+          dstyles[:properties][:github_username] = :yellow
+        elsif oDocument.getProp(:email_address)
+          dStyles[:bgstyle] = :blue
+          dstyles[:properties][:email_address] = :yellow
+        end
+        return dStyles
+      end
+    end
+
+    # Instantiate a config object
+    config    = MyWorksheetConfig.new( columns, styles )
+
+    # Instantiate a workbook
+    workbook  = AxlsxRad::Workbook.new
+
+    # Instantiate a worksheet with name and config
+    worksheet = workbook.addWorksheet( "Users", config )
+
+    # Add documents where user is a JsonDoc::Document subclass
+    # with properties matching those tested against in Axlsx::Config
+    # subclass.
+
+    users.each do |user|
+      worksheet.addDocument( user )
+    end
+
+    # Write XLSX spreadsheet
+    workbook.oAxlsx.serialize('example_users.xlsx')
+
+#Documentation
+--------------
+
+This gem is 100% documented with YARD, an exceptional documentation library. To see documentation for this, and all the gems installed on your system use:
+
+    $ gem install yard
+    $ yard server -g
+
+#Change Log
+-----------
+
+- **2014-03-20**: 0.0.1
+  - Initial release
+
+#Links
+------
+
+Axlsx
+
+https://rubygems.org/gems/axlsx
+
+JsonDoc
+
+https://rubygems.org/gems/jsondoc
+
+#Copyright and License
+----------------------
+
+AxlsxRad &copy; 2014 by [John Wang](mailto:johncwang@gmail.com).
+
+AxlsxRad is licensed under the MIT license. Please see the LICENSE document for more information.
+
+Warranty
+--------
+
+This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the library.'
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = false
+end
+
+desc 'Generate YARD documentation.'
+task :gendoc do
+  #puts 'yard doc generation disabled until JRuby build native extensions for redcarpet or yard removes the dependency.'
+  system "yardoc"
+  system "yard stats --list-undoc"
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/axlsx_rad/config.rb

@@ -0,0 +1,21 @@
+module AxlsxRad
+  class Config
+    attr_accessor :aColumns
+    attr_accessor :dStylesCfg
+    def initialize(aColumns=[],dStylesCfg={})
+      @aColumns   = aColumns
+      @dStylesCfg = dStylesCfg
+    end
+    # Override this method with rules to return style key
+    def getStylesForHeader()
+      return { :bgstyle => :head }
+    end
+    def getStylesForDocument(oJsondoc=nil)
+      dStyles = { :bgstyle => nil, :properties => {} }
+      unless oJsondoc.is_a?(JsonDoc::Document)
+        raise ArgumentError, 'E_NOT_JSONDOC'
+      end
+      return dStyles
+    end
+  end
+end

data/lib/axlsx_rad/workbook.rb

@@ -0,0 +1,149 @@
+require 'axlsx'
+
+module AxlsxRad
+  class Workbook
+    attr_accessor :oAxlsx
+
+    def initialize(oAxlsx=nil)
+      @oAxlsx      = oAxlsx || Axlsx::Package.new
+      @dWorksheets = {}
+    end
+
+    def addWorksheet(sWorksheetName=nil,oWsConfig=nil)
+      if @dWorksheets.has_key?(sWorksheetName)
+        raise RuntimeError, "E_WORKSHEET_EXISTS [#{sWorksheetName}]"
+      end
+      oAwsWorksheet = AxlsxRad::Worksheet.new(@oAxlsx,sWorksheetName,oWsConfig)
+      @dWorksheets[ sWorksheetName ] = oAwsWorksheet
+      return oAwsWorksheet
+    end
+
+    def addWorksheetDocument(sWorksheetName=nil,oJsondoc=nil)
+      if sWorksheetName.nil? || ! sWorksheetName.kind_of?(String)
+        raise ArgumentError, 'E_BAD_WORKSHEET_NAME'
+      elsif ! @dWorksheets.has_key?( sWorksheetName )
+        raise ArgumentError, 'E_WORKSHEET_DOES_NOT_EXIST'
+      end
+      @dWorksheets[ sWorksheetName ].addDocument( oJsondoc )
+    end
+
+  end
+end
+
+module AxlsxRad
+  class Worksheet
+    attr_accessor :oAxlsx
+    attr_accessor :oAxlsxWorksheet
+
+    def initialize(oAxlsx=nil,sName=nil,oWsConfig=nil)
+      @oAxlsx          = oAxlsx
+      unless oWsConfig.is_a?(AxlsxRad::Config)
+        raise ArgumentError, 'E_NO_AXLSX_RAD_WORKSHEET_CONFIG'
+      end
+      @oAxlsxWorksheet = @oAxlsx.workbook.add_worksheet(:name => sName)
+      @oWsConfig       = oWsConfig
+      self.loadWsConfig( oWsConfig )
+      @bHasHead        = false
+    end
+
+    def loadWsConfig(oWsConfig=nil)
+      @aColumns       = oWsConfig.aColumns || []
+      @dStylesCfg     = oWsConfig.dStylesCfg.is_a?(Hash) ? oWsConfig.dStylesCfg : {}
+      @dStylesAxlsx   = getStylesAxlsx( @oAxlsxWorksheet, @dStylesCfg )
+      @dStylesColumns = getStylesColumns( @dStylesAxlsx, @aColumns )
+    end
+
+    def addDocument(oJsondoc=nil)
+      unless @bHasHead
+        aStyles = getStylesForHeader
+        aValues = oJsondoc.getDescArrayForProperties( @aColumns )
+        if aStyles.is_a?(Fixnum) || aStyles.is_a?(Array)
+          @oAxlsxWorksheet.add_row aValues, :style => aStyles
+        else
+          @oAxlsxWorksheet.add_row aValues
+        end
+        @bHasHead = true
+      end
+      aValues = oJsondoc.getValArrayForProperties( @aColumns )
+      aStyles = getStylesForDocument( oJsondoc )
+      if aStyles.is_a?(Fixnum) || aStyles.is_a?(Array)
+        @oAxlsxWorksheet.add_row aValues, :style => aStyles         
+      else
+        @oAxlsxWorksheet.add_row aValues
+      end
+    end
+
+    private
+
+    def symbolizeArray(aAny=[])
+      (0..aAny.length-1).each do |i|
+        aAny[i] = aAny[i].to_sym if aAny[i].is_a?(String)
+      end
+      return aAny
+    end
+
+    def getStylesAxlsx(oAxlsxWorksheet=nil,dStylesCfg=nil)
+      dStylesAxlsx = {}
+      dStylesCfg.keys.each do |yStyle|
+        dStylesAxlsx[ yStyle ] = oAxlsxWorksheet.styles.add_style( @dStylesCfg[ yStyle ] )
+      end
+      return dStylesAxlsx
+    end
+
+    def getStylesColumns(dStylesAxlsx=nil,aColumns=nil)
+      dStylesColumns = {}
+      dStylesAxlsx.keys.each do |yStyle|
+        dStylesColumns[yStyle] ||= []
+        oStyleAxlsx = dStylesAxlsx[yStyle]
+        (0..aColumns.length-1).each do |i|
+          dStylesColumns[yStyle].push( oStyleAxlsx )
+        end
+      end
+      return dStylesColumns
+    end
+
+    def getStylesForHeader()
+      aStyles = nil
+      if @oWsConfig.is_a?(AxlsxRad::Config)
+        dStyles = @oWsConfig.getStylesForHeader
+        aStyles = getStylesArrayForHash( dStyles )
+      end
+      return aStyles
+    end
+
+    def getStylesForDocument(oJsondoc=nil)
+      aStyle = nil
+      if @oWsConfig.is_a?(AxlsxRad::Config)
+        dStyle = @oWsConfig.getStylesForDocument(oJsondoc)
+        aStyle = getStylesArrayForHash( dStyle )
+      end
+      return aStyle
+    end
+
+    def getStylesArrayForHash(dStyles={})
+      yStyleBg = dStyles.has_key?(:bgstyle) ? dStyles[:bgstyle] : nil
+      yStyleBg = yStyleBg.to_sym if yStyleBg.is_a?(String)
+      aStyles  = []
+      if dStyles.has_key?(:properties) && dStyles[:properties].is_a?(Hash) \
+      && dStyles[:properties].keys.length > 0
+        @aColumns.each do |yColumn|
+          if dStyles[:properties].has_key?(yColumn)
+            yStyleCell = dStyles[:properties][yColumn]
+            yStyleCell = yStyleCell.to_sym if yStyleCell.is_a?(String)
+            aStyles.push( @dStylesAxlsx[ yStyleCell ] )
+          elsif yStyleBg
+            aStyles.push( @dStylesAxlsx[ yStyleBg ] ) 
+          else
+            aStyles.push( nil )
+          end
+        end
+      elsif yStyleBg
+        aStyles = @dStylesColumns[yStyleBg]
+      else
+        aStyles = nil
+      end
+      return aStyles
+    end
+
+  end
+end

data/lib/axlsx_rad.rb

@@ -0,0 +1,4 @@
+module AxlsxRad
+  require 'axlsx_rad/workbook'
+  require 'axlsx_rad/config'
+end

data/test/test_setup.rb

@@ -0,0 +1,16 @@
+require 'test/unit'
+require 'axlsx_rad'
+
+class AxlsxRadTest < Test::Unit::TestCase
+  def testSetup
+
+    config    = AxlsxRad::Config.new
+    workbook  = AxlsxRad::Workbook.new
+    worksheet = workbook.addWorksheet("My Sheet",config)
+
+    assert_equal 'AxlsxRad::Config',    config.class.name
+    assert_equal 'AxlsxRad::Workbook',  workbook.class.name
+    assert_equal 'AxlsxRad::Worksheet', worksheet.class.name
+
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: axlsx_rad
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- John Wang
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: axlsx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.5
+description: Efficiently create styled spreadsheets using JsonDoc::Document objects
+email: john@johnwang.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- lib/axlsx_rad.rb
+- lib/axlsx_rad/config.rb
+- lib/axlsx_rad/workbook.rb
+- test/test_setup.rb
+homepage: http://johnwang.com/
+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.2.1
+signing_key: 
+specification_version: 4
+summary: AxlsxRad - Rapid XLSX Writer for Customized Spreadsheets
+test_files: []