thinreports 0.7.7 → 0.8.0

data/lib/thinreports/layout/configuration.rb

@@ -1,27 +1,29 @@
 # coding: utf-8
 
-module ThinReports
+module Thinreports
   module Layout
-    
+
+    # @deprecated This class will be removed in the next major version.
     class Configuration
       include Core::Shape::Manager::Target
-      
-      undef_method :items, :values
-      
-      # @param [ThinReports::Layout::Base] layout
+
+      # @param [Thinreports::Layout::Base] layout
       def initialize(layout)
         initialize_manager(layout.format) do |f|
           Core::Shape::Configuration(f.type).new
         end
       end
-      
+
       # @param [String, Symbol] shape_id
       # @return [Object, nil]
-      # @private
       def activate(shape_id)
         (config = manager.shapes[shape_id.to_sym]) && config.copy
       end
+
+      def values
+        raise NoMethodError
+      end
     end
-    
+
   end
 end

data/lib/thinreports/layout/format.rb

@@ -2,40 +2,39 @@
 
 require 'digest/sha1'
 
-module ThinReports
+module Thinreports
   module Layout
-    
-    # @private
+
     class Format < Core::Shape::Manager::Format
-      config_reader :last_version        => %w( version )
-      config_reader :report_title        => %w( config title )
-      config_reader :page_paper_type     => %w( config page paper-type ),
-                    :page_width          => %w( config page width ),
-                    :page_height         => %w( config page height ),
-                    :page_orientation    => %w( config page orientation )
-      
-      config_checker 'user', :user_paper_type => %w( config page paper-type )
-      
+      config_reader last_version: %w( version )
+      config_reader report_title: %w( config title )
+      config_reader page_paper_type: %w( config page paper-type ),
+                    page_width: %w( config page width ),
+                    page_height: %w( config page height ),
+                    page_orientation: %w( config page orientation )
+
+      config_checker 'user', user_paper_type: %w( config page paper-type )
+
       class << self
-        
+
       private
-        
+
         # @param [String] filename
         # @param [Hash] options
         # @option options [Boolean] :force (false)
         def build_internal(filename, options = {})
           build_once(filename, options[:force]) do |content, id|
             raw_format = parse_json(content)
-            
+
             # Check the compatibility of specified layout file.
-            unless ThinReports::Layout::Version.compatible?(raw_format['version'])
+            unless Thinreports::Layout::Version.compatible?(raw_format['version'])
               info = [filename, raw_format['version'],
-                      ThinReports::Layout::Version.inspect_required_rules]
-              raise ThinReports::Errors::IncompatibleLayoutFormat.new(*info)
+                      Thinreports::Layout::Version.inspect_required_rules]
+              raise Thinreports::Errors::IncompatibleLayoutFormat.new(*info)
             end
-            
+
             compact_format!(raw_format)
-            
+
             # Build and initialize format.
             new(raw_format, id) do |f|
               build_layout(f) do |type, shape_format|
@@ -45,17 +44,17 @@ module ThinReports
             end
           end
         end
-        
+
         # @param [Hash] raw_format A parsed json.
         def compact_format!(raw_format)
           %w( finger-print state version ).each {|attr| raw_format.delete(attr) }
         end
-        
+
         # @param [String] filename
         # @param [Boolean] force (false)
         def build_once(filename, force = false, &block)
           content = read_format_file(filename)
-          
+
           if force
             block.call(content, nil)
           else
@@ -63,19 +62,19 @@ module ThinReports
             built_format_registry[id] ||= block.call(content, id)
           end
         end
-        
+
         # @param [String] filename
         # @return [String]
         def read_format_file(filename)
           File.open(filename, 'r:UTF-8') {|f| f.read }
         end
-        
+
         # @return [Hash]
         def built_format_registry
           @built_format_registry ||= {}
-        end        
+        end
       end
     end
-    
+
   end
 end

data/lib/thinreports/layout/version.rb

@@ -1,18 +1,17 @@
 # coding: utf-8
 
-module ThinReports
+module Thinreports
   module Layout
-    
-    # @private
+
     module Version
-      REQUIRED_RULES = ['>= 0.6.0.pre3', '< 0.8.0']
-      
+      REQUIRED_RULES = ['>= 0.7.7.0', '< 1.0.0']
+
       # @param [String] version
       # @return [Boolean]
       def self.compatible?(version)
         compare(version, *REQUIRED_RULES)
       end
-      
+
       # @param [String] base
       # @param [Array<String>] rules
       # @return [Boolean]
@@ -22,12 +21,12 @@ module ThinReports
           comparable_version(base).send(op.to_sym, comparable_version(ver))
         end
       end
-      
+
       # @return [String]
       def self.inspect_required_rules
         '(' + REQUIRED_RULES.join(' and ') + ')'
       end
-      
+
       # @param [String] version
       # @return [String]
       def self.comparable_version(version)
@@ -38,6 +37,6 @@ module ThinReports
         end
       end
     end
-    
+
   end
 end

data/lib/thinreports/report.rb

@@ -1,31 +1,27 @@
 # coding: utf-8
 
-module ThinReports
-  
+module Thinreports
+
   module Report
-    # @see ThinReports::Report::Base#initialize
+    # @see Thinreports::Report::Base#initialize
     def self.new(*args)
       Base.new(*args)
     end
-    
-    # @see ThinReports::Report::Base#create
+
+    # @see Thinreports::Report::Base#create
     def self.create(*args, &block)
       Base.create(*args, &block)
     end
-    
-    # @see ThinReports::Report::Base#generate
+
+    # @see Thinreports::Report::Base#generate
     def self.generate(*args, &block)
       Base.generate(*args, &block)
     end
-    
-    # @see ThinReports::Report::Base#generate_file
-    def self.generate_file(*args, &block)
-      Base.generate_file(*args, &block)
-    end
   end
-  
+
 end
 
 require 'thinreports/report/base'
 require 'thinreports/report/internal'
-require 'thinreports/report/events'
+require 'thinreports/report/events'
+require 'thinreports/report/page'

data/lib/thinreports/report/base.rb

@@ -1,33 +1,29 @@
 # coding: utf-8
 
-module ThinReports
+module Thinreports
   module Report
-  
+
     class Base
-      # @return [ThinReports::Report::Internal]
-      # @private
-      attr_reader :internal
+      extend  Forwardable
+      include Utils
 
-      # @return [Integer]
-      attr_reader :start_page_number
-      
       class << self
         # @param options (see #initialize)
         # @option options (see #initialize)
         # @yield [report]
-        # @yieldparam [ThinReports::Report::Base] report
-        # @return [ThinReports::Report::Base]
+        # @yieldparam [Thinreports::Report::Base] report
+        # @return [Thinreports::Report::Base]
         def create(options = {}, &block)
           unless block_given?
             raise ArgumentError, '#create requires a block'
           end
           report = new(options)
-          block_exec_on(report, &block)
+          call_block_in(report, &block)
           report.finalize
-          
+
           report
         end
-        
+
         # @overload generate(type, options = {}, &block)
         #   @param [Symbol] type
         #   @param [Hash] options
@@ -42,41 +38,22 @@ module ThinReports
         # @return [String]
         def generate(*args, &block)
           raise ArgumentError, '#generate requires a block' unless block_given?
-          
+
           report_opts, generator_opts = extract_options!(args)
-          
+
           report = create(report_opts, &block)
           report.generate(*args.push(generator_opts))
         end
-        
-        # @overload generate_file(type, filename, options = {}, &block)
-        # @overload generate_file(filename, options = {}, &block)
-        # @param filename (see #generate_file)
-        # @yield (see .create)
-        # @yieldparam (see .create)
-        # @see .generate
-        # @deprecated Please use the #generate method with :filename option instead.
-        # @return [void]
-        def generate_file(*args, &block)
-          raise ArgumentError, '#generate_file requires a block' unless block_given?
 
-          report_opts, generator_opts = extract_options!(args)
-          
-          report = create(report_opts, &block)
-          report.generate_file(*args.push(generator_opts))
-        end
-        
-      private
-        
         # @param [Array] args
         # @return [Array<Hash>]
         def extract_options!(args)
           if args.last.is_a?(::Hash)
             options = args.pop
-          
+
             generator = options.delete(:generator) || {}
             report    = options.delete(:report) || {}
-            
+
             if options.key?(:layout)
               report[:layout] = options.delete(:layout)
             end
@@ -86,150 +63,151 @@ module ThinReports
           end
         end
       end
-      
+
+      # @return [Thinreports::Report::Internal]
+      attr_reader :internal
+
+      # @return [Integer]
+      attr_reader :start_page_number
+
+      # @return [Thinreports::Report::Page]
+      def_delegator :internal, :page
+
+      # @return [Integer]
+      def_delegator :internal, :page_count
+
+      # @return [Array<Thinreports::Report::Page>]
+      def_delegator :internal, :pages
+
+      # @return [Thinreports::Layout::Base]
+      def_delegator :internal, :default_layout
+
       # @param [Hash] options
       # @option options [String, nil] :layout (nil)
       def initialize(options = {})
         @internal = Report::Internal.new(self, options)
         @start_page_number = 1
+
+        @page_create_handler = nil
+        @generate_handler = nil
+      end
+
+      # @yield [page]
+      # @yieldparam [Thinreports::Report::Page] page
+      # @example
+      #   report.on_page_create do |page|
+      #     page.item(:header_title).value = 'Title'
+      #   end
+      def on_page_create(&block)
+        internal.page_create_handler = block
       end
 
       # @param [Integer] page_number
       def start_page_number_from(page_number)
         @start_page_number = page_number
       end
-      
-      # @param [String] layout path to layout-file.
+
+      # @param [String] layout filename of layout file
       # @param [Hash] options
       # @option options [Boolean] :default (true)
       # @option options [Symbol] :id (nil)
       # @yield [config]
-      # @yieldparam [ThinReports::Layout::Configuration] config
-      # @return [void]
+      # @yieldparam [Thinreports::Layout::Configuration] config
+      # @example
+      #   report.use_layout '/path/to/default_layout.tlf' # Default layout
+      #   report.use_layout '/path/to/default_layout.tlf', default: true
+      #   report.use_layout '/path/to/other_layout', id: :other_layout
       def use_layout(layout, options = {}, &block)
         internal.register_layout(layout, options, &block)
       end
-      
+
+      # @example
+      #   page = report.start_new_page
+      #
+      #   report.start_new_page do |page|
+      #     page.item(:text).value = 'value'
+      #   end
+      #
+      #   report.use_layout 'foo.tlf', default: true
+      #   report.use_layout 'bar.tlf', id: :bar
+      #
+      #   report.start_new_page                   # Use 'foo.tlf'
+      #   report.start_new_page layout: :bar      # Use 'bar.tlf'
+      #   report.start_new_page layout: 'boo.tlf' # Use 'boo.tlf'
       # @param [Hash] options
       # @option options [String, Symbol] :layout (nil)
       # @option options [Boolean] :count (true)
       # @yield [page]
-      # @yieldparam [ThinReports::Core::Page] page
-      # @return [ThinReports::Core::Page]
+      # @yieldparam [Thinreports::Report::Page] page
+      # @return [Thinreports::Report::Page]
       def start_new_page(options = {}, &block)
         unless layout = internal.load_layout(options.delete(:layout))
-          raise ThinReports::Errors::NoRegisteredLayoutFound
+          raise Thinreports::Errors::NoRegisteredLayoutFound
         end
-        
-        page = internal.add_page(layout.init_new_page(self, options))
-        block_exec_on(page, &block)
+
+        page = internal.add_page(layout.new_page(self, options))
+        call_block_in(page, &block)
       end
-      
+
       # @param [Hash] options
       # @option options [Boolean] :count (true)
-      # @return [ThinReports::Core::BlankPage]
+      # @return [Thinreports::Report::BlankPage]
       def add_blank_page(options = {})
-        internal.add_page(Core::BlankPage.new(options[:count]))
+        internal.add_page(Report::BlankPage.new(options[:count]))
       end
       alias_method :blank_page, :add_blank_page
-      
-      # @param [Symbol, nil] id Return the default layout
-      #   if nil (see #default_layout).
-      # @return [ThinReports::Layout::Base]
+
+      # @param [Symbol, nil] id
+      # @return [Thinreports::Layout::Base]
       def layout(id = nil)
         if id
           internal.layout_registry[id] ||
-            raise(ThinReports::Errors::UnknownLayoutId)
+            raise(Thinreports::Errors::UnknownLayoutId)
         else
           internal.default_layout
         end
       end
-      
-      # @return [ThinReports::Layout::Base]
-      def default_layout
-        internal.default_layout
-      end
-      
-      # @overload generate(type, options = {})
-      #   Specify the generator type.
-      #   @param [Symbol] type
-      #   @return [String]
+
       # @overload generate(options = {})
-      #   Using the default generator type.
       #   @param [Hash] options ({})
       #   @return [String]
-      # @example Generate the PDF data
-      #   report.generate(:pdf) #=> "%PDF-1.4...."
-      #
-      #   # Or, you can omit the type of generator
-      #   report.generate
-      # @example Create the PDF file (Since v0.8)
-      #   report.generate(:pdf, :filename => 'foo.pdf')
+      # @overload generate(type, options = {})
+      #   This way has been DEPRECATED. Use instead #generate(options = {}).
+      #   @param [Symbol] type
+      #   @return [String]
+      # @example Generate PDF data
+      #   report.generate # => "%PDF-1.4...."
+      # @example Create a PDF file
+      #   report.generate(filename: 'foo.pdf')
       def generate(*args)
         options = args.last.is_a?(::Hash) ? args.pop : {}
-        type = args.first || ThinReports.config.generator.default
+        type = args.first || Thinreports.config.generator.default
         filename = options.delete(:filename)
-        generator = ThinReports::Generator.new(type, self, options)
+        generator = Thinreports::Generator.new(type, self, options)
 
-        if filename
-          generator.generate_file(filename)
-        else
-          generator.generate
-        end
+        generator.generate(filename)
       end
-      
-      # @overload generate_file(type, filename, options = {})
-      #   @param type (#generate)
-      #   @return [void]
-      # @overload generate_file(filename, options = {})
-      #   @param [String] filename
-      #   @param options (see #generate)
-      #   @return [void]
-      # @deprecated Please use the #generate method with :filename option instead.
-      def generate_file(*args)
-        warn '[DEPRECATION] The #generate_file method is deprecated. ' +
-             'Please use the #generate(:filename => "filename") instead.'
 
-        options = args.last.is_a?(::Hash) ? args.pop : {}
-        args.unshift(ThinReports.config.generator.default) if args.size == 1
-        type, filename = args
-
-        generate(type, options.merge(:filename => filename))
-      end
-      
-      # @see ThinReports::Core::Shape::Manager::Target#list
+      # @see Thinreports::Core::Shape::Manager::Target#list
       def list(id = nil, &block)
         start_new_page if page.nil? || page.finalized?
         page.list(id, &block)
       end
-      
-      # @return [ThinReports::Report::Events]
+
+      # @return [Thinreports::Report::Events]
+      # @deprecated
+      #   `Report::Base#events` will be removed in the next major version.
+      #   Please use #on_page_create callbacks instead.
+      #   See also https://github.com/thinreports/thinreports-generator/blob/master/examples/report_callbacks/report_callbacks.rb.
       def events
+        warn '[DEPRECATION] `Report::Base#events` will be removed in the next major version. ' +
+             'Please use #on_page_create callbacks instead. ' +
+             'See also https://github.com/thinreports/thinreports-generator/blob/master/examples/report_callbacks/report_callbacks.rb.'
         internal.events
       end
-      
-      # @return [ThinReports::Core::Page, nil]
-      def page
-        internal.page
-      end
-      
-      # @return [Integer]
-      def page_count
-        internal.page_count
-      end
-      
-      # @return [void]
-      # @private
-      def finalize
-        internal.finalize
-      end
-      
-      # @return [Boolean]
-      # @private
-      def finalized?
-        internal.finalized?
-      end
+
+      def_delegators :internal, :finalize, :finalized?
     end
-  
+
   end
 end