thinreports 0.7.6 → 0.8.0

data/lib/thinreports/report/base.rb

@@ -1,30 +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
+
       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
@@ -39,40 +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
-        # @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
@@ -82,124 +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 [String] layout path to layout-file.
+
+      # @param [Integer] page_number
+      def start_page_number_from(page_number)
+        @start_page_number = page_number
+      end
+
+      # @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[:layout])
-          raise ThinReports::Errors::NoRegisteredLayoutFound
+        unless layout = internal.load_layout(options.delete(:layout))
+          raise Thinreports::Errors::NoRegisteredLayoutFound
         end
-        
-        page = internal.add_page(layout.init_new_page(self))
-        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]
+      # @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
-        ThinReports::Generator.new(type, self, options).generate
-      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]
-      def generate_file(*args)
-        options = args.last.is_a?(::Hash) ? args.pop : {}
-        args.unshift(ThinReports.config.generator.default) if args.size == 1
-        type, filename = args
-        ThinReports::Generator.new(type, self, options).generate_file(filename)
+        type = args.first || Thinreports.config.generator.default
+        filename = options.delete(:filename)
+        generator = Thinreports::Generator.new(type, self, options)
+
+        generator.generate(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

data/lib/thinreports/report/events.rb

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-module ThinReports
+module Thinreports
   module Report
     
     class Events < Core::Events
@@ -9,14 +9,14 @@ module ThinReports
               :generate)
       end
       
-      class Event < ThinReports::Core::Events::Event
-        # @return [ThinReports::Core::Page, nil]
+      class Event < Thinreports::Core::Events::Event
+        # @return [Thinreports::Report::Page, nil]
         attr_reader :page
         
-        # @return [Array<ThinReports::Core::Page>]
+        # @return [Array<Thinreports::Report::Page>]
         attr_reader :pages
         
-        # @return [ThinReports::Report::Base]
+        # @return [Thinreports::Report::Base]
         alias_method :report, :target
         
         def initialize(type, target, page = nil, pages = nil)

data/lib/thinreports/report/internal.rb

@@ -1,9 +1,8 @@
 # coding: utf-8
 
-module ThinReports
+module Thinreports
   module Report
-    
-    # @private
+
     class Internal
       attr_reader :pages
       attr_reader :page
@@ -11,9 +10,12 @@ module ThinReports
       attr_reader :default_layout
       attr_reader :layout_registry
       attr_reader :events
-      
-      # @param [ThinReports::Report::Base] report
-      # @param options (see ThinReports::Report::Base#initialize)
+
+      attr_accessor :page_create_handler
+      attr_accessor :generate_handler
+
+      # @param [Thinreports::Report::Base] report
+      # @param options (see Thinreports::Report::Base#initialize)
       def initialize(report, options)
         @report = report
         # Default layout
@@ -24,17 +26,20 @@ module ThinReports
         @pages      = []
         @page       = nil
         @page_count = 0
-        
+
+        @page_create_handler = nil
+        @generate_handler = nil
+
         @events = Report::Events.new
       end
-      
-      # @see ThinReports::Report::Base#use_layout
+
+      # @see Thinreports::Report::Base#use_layout
       def register_layout(layout, options = {}, &block)
         layout = if options.empty? || options[:default]
           @default_layout = init_layout(layout)
         else
           id = options[:id].to_sym
-          
+
           if layout_registry.key?(id)
             raise ArgumentError, "Id :#{id} is already in use."
           end
@@ -42,87 +47,92 @@ module ThinReports
         end
         layout.config(&block)
       end
-      
+
       def add_page(new_page)
         finalize_current_page
         insert_page(new_page)
       end
-      
+
       def copy_page
-        finalize_current_page(:at => :copy)
+        finalize_current_page(at: :copy)
         insert_page(page.copy)
       end
-      
+
       def finalize
         unless finalized?
           finalize_current_page
           @finalized = true
-          
-          # Dispatch event on before generate.
+
+          # [DEPRECATION] Please use Report::Base#on_generate callback instead.
           events.dispatch(Report::Events::Event.new(:generate,
                                                     @report, nil, pages))
+
+          @generate_handler.call(pages) if @generate_handler
         end
       end
-      
+
       def finalized?
         @finalized
       end
-      
-      def load_layout(layout)
-        return @default_layout if layout.nil?
-        
-        case layout
+
+      def load_layout(id_or_filename)
+        return @default_layout if id_or_filename.nil?
+
+        layout = case id_or_filename
         when Symbol
-          layout_registry[layout]
+          layout_registry[id_or_filename]
         when String
-          prepare_layout(layout)
+          prepare_layout(id_or_filename)
         else
           raise ArgumentError, 'Invalid argument for layout.'
         end
+        @default_layout = layout unless @default_layout
+        layout
       end
-      
+
     private
-      
+
       def insert_page(new_page)
         @pages << new_page
-        
+
         if new_page.count?
           @page_count += 1
           new_page.no = @page_count
         end
-        # Dispatch event on +before+ page create.
-        # But do not dispatch if page is blank-page.
+
         unless new_page.blank?
+          # [DEPRECATION] Please use #on_page_create callback instead.
           events.dispatch(Report::Events::Event.new(:page_create,
                                                     @report,
                                                     new_page))
+          @page_create_handler.call(new_page) if @page_create_handler
         end
         @page = new_page
       end
-      
-      # @param (see ThinReports::Core::Page#finalize)
+
+      # @param (see Thinreports::Report::Page#finalize)
       def finalize_current_page(options = {})
-        page.finalize(options) unless page.blank?        
+        page.finalize(options) unless page.nil? || page.blank?
       end
-      
+
       def prepare_layout(layout)
         return nil if layout.nil?
-        
+
         case layout
         when String
           init_layout(layout)
         # @note Currently not used. Since 0.6.0?
-        when ThinReports::Layout::Base
+        when Thinreports::Layout::Base
           layout
         else
           raise ArgumentError, 'Invalid argument for layout.'
         end
       end
-      
+
       def init_layout(filename, id = nil)
-        ThinReports::Layout.new(filename, :id => id)
+        Thinreports::Layout.new(filename, id: id)
       end
     end
-    
+
   end
 end

data/lib/thinreports/{core → report}/page.rb

@@ -1,91 +1,101 @@
 # coding: utf-8
 
-module ThinReports
-  module Core
-    
+module Thinreports
+  module Report
+
     class BlankPage
+      # @example
+      #   3.times do
+      #     page = report.start_new_page
+      #     puts page.no
+      #   end
+      #   # => 1, 2, 3
       # @return [Integer]
       attr_accessor :no
-      
+
       # @param [Boolean] count (nil)
       def initialize(count = nil)
         @count = count.nil? ? true : count
       end
-      
+
+      # @example
+      #   page = report.start_new_page
+      #   page.count? # => true
+      #
+      #   page = report.start_new_page count: false
+      #   page.count? # => false
       # @return [Boolean]
       def count?
         @count
       end
-      
+
       # @return [Boolean] (true)
       def blank?
         true
       end
     end
-    
+
     class Page < BlankPage
       include Core::Shape::Manager::Target
-      
-      # @return [ThinReports::Report::Base]
-      # @private
+
+      # @return [Thinreports::Report::Base]
       attr_reader :report
-      
-      # @return [ThinReports::Layout::Base]
+
+      # @return [Thinreports::Layout::Base]
       attr_reader :layout
-      
-      # @param [ThinReports::Report::Base] report
-      # @param [ThinReports::Layout::Base] layout
-      def initialize(report, layout)
-        super(true)
-        
+
+      # @param [Thinreports::Report::Base] report
+      # @param [Thinreports::Layout::Base] layout
+      # @param [Hash] options ({})
+      # @option options [Boolean] :count (true)
+      def initialize(report, layout, options = {})
+        super(options.key?(:count) ? options[:count] : true)
+
         @report    = report
         @layout    = layout
         @finalized = false
-        
+
         initialize_manager(layout.format) do |f|
           Core::Shape::Interface(self, f)
         end
       end
-      
+
       # @return [Boolean] (false)
       def blank?
         false
       end
-      
-      # @private
+
       def copy
-        new_page = self.class.new(report, layout)
-        
+        new_page = self.class.new(report, layout, count: count?)
+
         manager.shapes.each do |id, shape|
           new_shape = shape.copy(new_page)
           new_page.manager.shapes[id] = new_shape
-          
+
           if new_shape.internal.type_of?(:list)
             new_page.manager.lists[id] = new_shape
           end
         end
         new_page
       end
-      
+
       # @param [Hash] options
       # @option options [:create, :copy] :at (:create)
-      # @private
       def finalize(options = {})
         at = options[:at] || :create
-        
+
         # For list shapes.
         if at == :create
           manager.lists.values.each {|list| list.manager.finalize }
         end
-        
+
         @finalized = true
       end
-      
-      # @private
+
       def finalized?
         @finalized
       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'