# -*- encoding : utf-8 -*-
########################################################
## Thoughts from reading the ISO 32000-1:2008
## this file is part of the CombinePDF library and the code
## is subject to the same license.
########################################################

module CombinePDF
  # This module injects page editing methods into existing page objects and the PDFWriter objects.
  module Page_Methods
    include Renderer

    # holds the string that starts a PDF graphic state container - used for wrapping malformed PDF content streams.
    CONTENT_CONTAINER_START = 'q'.freeze
    # holds the string that ends a PDF graphic state container - used for wrapping malformed PDF content streams.
    CONTENT_CONTAINER_MIDDLE = "Q\nq".freeze
    # holds the string that ends a PDF graphic state container - used for wrapping malformed PDF content streams.
    CONTENT_CONTAINER_END = 'Q'.freeze

    # accessor (getter) for the secure_injection setting
    def secure_injection
      warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
      @secure_injection
    end

    # accessor (setter) for the secure_injection setting
    def secure_injection=(safe)
      warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
      @secure_injection = safe
    end

    # sets secure_injection to `true` and returns self, allowing for chaining methods
    def make_secure
      warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
      @secure_injection = true
      self
    end

    # sets secure_injection to `false` and returns self, allowing for chaining methods
    def make_unsecure
      warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
      @secure_injection = false
      self
    end

    # the injection method
    def <<(obj)
      inject_page obj, true
    end

    def >>(obj)
      inject_page obj, false
    end

    def inject_page(obj, top = true)
      raise TypeError, "couldn't inject data, expecting a PDF page (Hash type)" unless obj.is_a?(Page_Methods)

      obj = obj.copy(should_secure?(obj)) # obj.copy(secure_injection)

      # following the reference chain and assigning a pointer to the correct Resouces object.
      # (assignments of Strings, Arrays and Hashes are pointers in Ruby, unless the .dup method is called)

      # setup references to avoid method calls.
      local_res = resources
      local_val = nil
      # # setup references to avoid method calls.
      # remote_res = obj.resources
      # remote_val = nil

      # add each of the new resources in the uncoming Page to the local resource Hash
      obj.resources.each do |key, new_val|
        # keep CombinePDF structural data intact.
        next if PDF::PRIVATE_HASH_KEYS.include?(key)
        # review
        if local_res[key].nil?
          # no local data, adopt data from incoming page
          local_res[key] = new_val
          # go back to looping, no need to parse the rest of the Ruby
          next
        elsif (local_val = actual_object(local_res[key])).is_a?(Hash) && (new_val = actual_object(new_val)).is_a?(Hash)
          # marge data with priority to the incoming page's data
          new_val.update local_val # make sure the old values are respected
          local_val.update new_val # transfer old and new values to the injected page
        end # Do nothing if array or anything else
      end

      # concat the Annots array? (what good are named links if the names are in the unaccessible Page Catalog?)
      # if obj[:Annots]
      #   if (local_val = actual_object(self[:Annots])).nil?
      #     self[:Annots] = obj[:Annots]
      #   elsif local_val.is_a?(Array) && (remote_val = actual_object(obj[:Annots])).is_a?(Array)
      #     local_val.concat remote_val
      #   end
      # end

      # set ProcSet to recommended value
      resources[:ProcSet] = [:PDF, :Text, :ImageB, :ImageC, :ImageI] # this was recommended by the ISO. 32000-1:2008

      if top # if this is a stamp (overlay)
        insert_content CONTENT_CONTAINER_START, 0
        insert_content CONTENT_CONTAINER_MIDDLE
        self[:Contents].concat obj[:Contents]
        insert_content CONTENT_CONTAINER_END
      else # if this was a watermark (underlay? would be lost if the page was scanned, as white might not be transparent)
        insert_content CONTENT_CONTAINER_MIDDLE, 0
        insert_content CONTENT_CONTAINER_START, 0
        self[:Contents].insert 1, *obj[:Contents]
        insert_content CONTENT_CONTAINER_END
      end
      init_contents

      self
    end

    # accessor (setter) for the :MediaBox element of the page
    # dimensions:: an Array consisting of four numbers (can be floats) setting the size of the media box.
    def mediabox=(dimensions = [0.0, 0.0, 612.0, 792.0])
      self[:MediaBox] = dimensions
    end

    # accessor (getter) for the :MediaBox element of the page
    def mediabox
      actual_object self[:MediaBox]
    end

    # accessor (setter) for the :CropBox element of the page
    # dimensions:: an Array consisting of four numbers (can be floats) setting the size of the media box.
    def cropbox=(dimensions = [0.0, 0.0, 612.0, 792.0])
      self[:CropBox] = dimensions
    end

    # accessor (getter) for the :CropBox element of the page
    def cropbox
      actual_object self[:CropBox]
    end

    # get page size
    def page_size
      cropbox || mediabox
    end

    # accessor (getter) for the :Resources element of the page
    def resources
      self[:Resources] ||= {}
      self[:Resources][:referenced_object] || self[:Resources]
    end

    # This method adds a simple text box to the Page represented by the PDFWriter class.
    # This function takes two values:
    # text:: the text to potin the box.
    # properties:: a Hash of box properties.
    # the symbols and values in the properties Hash could be any or all of the following:
    # x:: the left position of the box.
    # y:: the BUTTOM position of the box.
    # width:: the width/length of the box. negative values will be computed from edge of page. defaults to 0 (end of page).
    # height:: the height of the box. negative values will be computed from edge of page. defaults to 0 (end of page).
    # text_align:: symbol for horizontal text alignment, can be ":center" (default), ":right", ":left"
    # text_valign:: symbol for vertical text alignment, can be ":center" (default), ":top", ":buttom"
    # text_padding:: a Float between 0 and 1, setting the padding for the text. defaults to 0.05 (5%).
    # font:: a registered font name or an Array of names. defaults to ":Helvetica". The 14 standard fonts names are:
    # - :"Times-Roman"
    # - :"Times-Bold"
    # - :"Times-Italic"
    # - :"Times-BoldItalic"
    # - :Helvetica
    # - :"Helvetica-Bold"
    # - :"Helvetica-BoldOblique"
    # - :"Helvetica- Oblique"
    # - :Courier
    # - :"Courier-Bold"
    # - :"Courier-Oblique"
    # - :"Courier-BoldOblique"
    # - :Symbol
    # - :ZapfDingbats
    # font_size:: an Integer for the font size, or :fit_text to fit the text in the box. defaults to ":fit_text"
    # max_font_size:: if font_size is set to :fit_text, this will be the maximum font size. defaults to nil (no maximum)
    # font_color:: text color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defaults to black.
    # stroke_color:: text stroke color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defounlts to nil (no stroke).
    # stroke_width:: text stroke width in PDF units. defaults to 0 (none).
    # box_color:: box fill color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defaults to nil (none).
    # border_color:: box border color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be "[0.5, 0.5, 0.5]"). defaults to nil (none).
    # border_width:: border width in PDF units. defaults to nil (none).
    # box_radius:: border radius in PDF units. defaults to 0 (no corner rounding).
    # opacity:: textbox opacity, a float between 0 (transparent) and 1 (opaque)
    # ctm:: A PDF complient CTM data array that will manipulate the axis and allow transformations. i.e. `[1,0,0,1,0,0]`
    def textbox(text, properties = {})
      options = {
        x: page_size[0],
        y: page_size[1],
        width: 0,
        height: -1,
        text_align: :center,
        text_valign: :center,
        text_padding: 0.1,
        font: nil,
        font_size: :fit_text,
        max_font_size: nil,
        font_color: [0, 0, 0],
        stroke_color: nil,
        stroke_width: 0,
        box_color: nil,
        border_color: nil,
        border_width: 0,
        box_radius: 0,
        opacity: 1,
        ctm: nil # ~= [1,0,0,1,0,0]
      }
      options.update properties
      # reset the length and height to meaningful values, if negative
      options[:width] = mediabox[2] - options[:x] + options[:width] if options[:width] <= 0
      options[:height] = mediabox[3] - options[:y] + options[:height] if options[:height] <= 0

      # reset the padding value
      options[:text_padding] = 0 if options[:text_padding].to_f >= 1

      # create box stream
      box_stream = ''
      # set graphic state for box
      if options[:box_color] || (options[:border_width].to_i > 0 && options[:border_color])
        # compute x and y position for text
        x = options[:x]
        y = options[:y]

        # set graphic state for the box
        box_stream << "q\n"
        box_stream << "#{options[:ctm].join ' '} cm\n" if options[:ctm]
        box_graphic_state = { ca: options[:opacity], CA: options[:opacity], LW: options[:border_width], LC: 0, LJ: 0, LD: 0 }
        if options[:box_radius] != 0 # if the text box has rounded corners
          box_graphic_state[:LC] = 2
          box_graphic_state[:LJ] = 1
        end
        box_graphic_state = graphic_state box_graphic_state # adds the graphic state to Resources and gets the reference
        box_stream << "#{object_to_pdf box_graphic_state} gs\n"

        # the following line was removed for Acrobat Reader compatability
        # box_stream << "DeviceRGB CS\nDeviceRGB cs\n"

        box_stream << "#{options[:box_color].join(' ')} rg\n" if options[:box_color]
        if options[:border_width].to_i > 0 && options[:border_color]
          box_stream << "#{options[:border_color].join(' ')} RG\n"
        end
        # create the path
        radius = options[:box_radius]
        half_radius = (radius.to_f / 2).round 4
        ## set starting point
        box_stream << "#{options[:x] + radius} #{options[:y]} m\n"
        ## buttom and right corner - first line and first corner
        box_stream << "#{options[:x] + options[:width] - radius} #{options[:y]} l\n" # buttom
        if options[:box_radius] != 0 # make first corner, if not straight.
          box_stream << "#{options[:x] + options[:width] - half_radius} #{options[:y]} "
          box_stream << "#{options[:x] + options[:width]} #{options[:y] + half_radius} "
          box_stream << "#{options[:x] + options[:width]} #{options[:y] + radius} c\n"
        end
        ## right and top-right corner
        box_stream << "#{options[:x] + options[:width]} #{options[:y] + options[:height] - radius} l\n"
        if options[:box_radius] != 0
          box_stream << "#{options[:x] + options[:width]} #{options[:y] + options[:height] - half_radius} "
          box_stream << "#{options[:x] + options[:width] - half_radius} #{options[:y] + options[:height]} "
          box_stream << "#{options[:x] + options[:width] - radius} #{options[:y] + options[:height]} c\n"
        end
        ## top and top-left corner
        box_stream << "#{options[:x] + radius} #{options[:y] + options[:height]} l\n"
        if options[:box_radius] != 0
          box_stream << "#{options[:x] + half_radius} #{options[:y] + options[:height]} "
          box_stream << "#{options[:x]} #{options[:y] + options[:height] - half_radius} "
          box_stream << "#{options[:x]} #{options[:y] + options[:height] - radius} c\n"
        end
        ## left and buttom-left corner
        box_stream << "#{options[:x]} #{options[:y] + radius} l\n"
        if options[:box_radius] != 0
          box_stream << "#{options[:x]} #{options[:y] + half_radius} "
          box_stream << "#{options[:x] + half_radius} #{options[:y]} "
          box_stream << "#{options[:x] + radius} #{options[:y]} c\n"
        end
        # fill / stroke path
        box_stream << "h\n"
        if options[:box_color] && options[:border_width].to_i > 0 && options[:border_color]
          box_stream << "B\n"
        elsif options[:box_color] # fill if fill color is set
          box_stream << "f\n"
        elsif options[:border_width].to_i > 0 && options[:border_color] # stroke if border is set
          box_stream << "S\n"
        end

        # exit graphic state for the box
        box_stream << "Q\n"
      end
      contents << box_stream

      # reset x,y by text alignment - x,y are calculated from the buttom left
      # each unit (1) is 1/72 Inch
      # create text stream
      text_stream = ''
      if !text.to_s.empty? && options[:font_size] != 0 && (options[:font_color] || options[:stroke_color])
        # compute x and y position for text
        x = options[:x] + (options[:width] * options[:text_padding])
        y = options[:y] + (options[:height] * options[:text_padding])

        # set the fonts (fonts array, with :Helvetica as fallback).
        fonts = [*options[:font], :Helvetica]
        # fit text in box, if requested
        font_size = options[:font_size]
        if options[:font_size] == :fit_text
          font_size = fit_text text, fonts, (options[:width] * (1 - options[:text_padding])), (options[:height] * (1 - options[:text_padding]))
          font_size = options[:max_font_size] if options[:max_font_size] && font_size > options[:max_font_size]
        end

        text_size = dimensions_of text, fonts, font_size

        if options[:text_align] == :center
          x = ((options[:width] * (1 - (2 * options[:text_padding]))) - text_size[0]) / 2 + x
        elsif options[:text_align] == :right
          x = ((options[:width] * (1 - (1.5 * options[:text_padding]))) - text_size[0]) + x
        end
        if options[:text_valign] == :center
          y = ((options[:height] * (1 - (2 * options[:text_padding]))) - text_size[1]) / 2 + y
        elsif options[:text_valign] == :top
          y = (options[:height] * (1 - (1.5 * options[:text_padding]))) - text_size[1] + y
        end

        # set graphic state for text
        text_stream << "q\n"
        text_stream << "#{options[:ctm].join ' '} cm\n" if options[:ctm]
        text_graphic_state = graphic_state(ca: options[:opacity], CA: options[:opacity], LW: options[:stroke_width].to_f, LC: 2, LJ: 1, LD: 0)
        text_stream << "#{object_to_pdf text_graphic_state} gs\n"

        # the following line was removed for Acrobat Reader compatability
        # text_stream << "DeviceRGB CS\nDeviceRGB cs\n"

        # set text render mode
        if options[:font_color]
          text_stream << "#{options[:font_color].join(' ')} rg\n"
        end
        if options[:stroke_width].to_i > 0 && options[:stroke_color]
          text_stream << "#{options[:stroke_color].join(' ')} RG\n"
          if options[:font_color]
            text_stream << "2 Tr\n"
          else
            final_stream << "1 Tr\n"
          end
        elsif options[:font_color]
          text_stream << "0 Tr\n"
        else
          text_stream << "3 Tr\n"
        end
        # format text object(s)
        # text_stream << "#{options[:font_color].join(' ')} rg\n" # sets the color state
        encode_text(text, fonts).each do |encoded|
          text_stream << "BT\n" # the Begine Text marker
          text_stream << format_name_to_pdf(set_font(encoded[0])) # Set font name
          text_stream << " #{font_size.round 3} Tf\n" # set font size and add font operator
          text_stream << "#{x.round 4} #{y.round 4} Td\n" # set location for text object
          text_stream << (encoded[1]) # insert the encoded string to the stream
          text_stream << " Tj\n" # the Text object operator and the End Text marker
          text_stream << "ET\n" # the Text object operator and the End Text marker
          x += encoded[2] / 1000 * font_size # update text starting point
          y -= encoded[3] / 1000 * font_size # update text starting point
        end
        # exit graphic state for text
        text_stream << "Q\n"
      end
      contents << text_stream

      self
    end

    # gets the dimentions (width and height) of the text, as it will be printed in the PDF.
    #
    # text:: the text to measure
    # font:: a font name or an Array of font names. Font names should be registered fonts. The 14 standard fonts are pre regitered with the font library.
    # size:: the size of the font (defaults to 1000 points).
    def dimensions_of(text, fonts, size = 1000)
      Fonts.dimensions_of text, fonts, size
    end

    # this method returns the size for which the text fits the requested metrices
    # the size is type Float and is rather exact
    # if the text cannot fit such a small place, returns zero (0).
    # maximum font size possible is set to 100,000 - which should be big enough for anything
    # text:: the text to fit
    # font:: the font name. @see font
    # length:: the length to fit
    # height:: the height to fit (optional - normally length is the issue)
    def fit_text(text, font, length, height = 10_000_000)
      size = 100_000
      size_array = [size]
      metrics = Fonts.dimensions_of text, font, size
      size_array << size * length / metrics[0] if metrics[0] > length
      size_array << size * height / metrics[1] if metrics[1] > height
      size_array.min
    end

    # This method moves the Page[:Rotate] property into the page's data stream, so that
    # "what you see is what you get".
    #
    # After using thie method, {#orientation} should return the absolute orientation rather than only the data's orientation (unless `:Rotate` is changed).
    #
    # This is usful in cases where there might be less control over the source PDF files,
    # and the user assums that the PDF page's data is the same as the PDF's pages
    # on screen display (Rotate rotates a page but leaves the data in the original orientation).
    #
    # The method returns the page object, thus allowing method chaining (i.e. `page[:Rotate] = 90; page.textbox('hello!').fix_rotation.textbox('hello!')`)
    def fix_rotation
      return self if self[:Rotate].to_f == 0.0 || mediabox.nil?
      # calculate the rotation
      r = (360.0 - self[:Rotate].to_f) * Math::PI / 180
      s = Math.sin(r).round 6
      c = Math.cos(r).round 6
      ctm = [c, s, -s, c]
      # calculate the translation (move the origin of x,y to the new origin).
      x = mediabox[2] - mediabox[0]
      y = mediabox[3] - mediabox[1]
      ctm.push(((x * c).abs - x * c + (y * s).abs + y * s) / 2, ((x * s).abs - x * s + (y * c).abs - y * c) / 2)

      # insert the rotation stream into the current content stream
      insert_content "q\n#{ctm.join ' '} cm\n", 0
      # close the rotation stream
      insert_content CONTENT_CONTAINER_END
      # reset the mediabox and cropbox values - THIS IS ONLY FOR ORIENTATION CHANGE...
      if (self[:Rotate].to_f / 90).to_i.odd?
        self[:MediaBox] = self[:MediaBox].values_at(1, 0, 3, 2)
        self[:CropBox] = self[:CropBox].values_at(1, 0, 3, 2) if self[:CropBox]
      end
      # reset the Rotate property
      delete :Rotate
      # disconnect the content stream, so that future inserts aren't rotated
      @contents = false # init_contents

      # always return self, for chaining.
      self
    end

    # resizes the page relative to it's current viewport (either the cropbox or the mediabox), setting the new viewport to the requested size.
    #
    # accepts:
    # new_size:: an Array with four elements: [X0, Y0, X_max, Y_max]. For example, A4: `[0, 0, 595, 842]`. It is important that the first two numbers are 0 unless a special effect is attempted. If the first two numbers change, the final result might not be the size requested, but the nearest possible transformation (calling the method again will allow a better resizing).
    # conserve_aspect_ratio:: whether to keep the current content in the same aspect ratio or to allow streaching. Defaults to true - so that although the content is resized, it might not fill the new size completely.
    def resize(new_size = nil, conserve_aspect_ratio = true)
      return page_size unless new_size
      c_mediabox = mediabox
      c_cropbox = cropbox
      c_size = c_cropbox || c_mediabox
      x_ratio = 1.0 * (new_size[2] - new_size[0]) / (c_size[2]) #-c_size[0])
      y_ratio = 1.0 * (new_size[3] - new_size[1]) / (c_size[3]) #-c_size[1])
      x_move = new_size[0] - c_size[0]
      y_move = new_size[1] - c_size[1]
      # puts "ctm will be: #{x_ratio.round(4)} 0 0 #{y_ratio.round(4)} #{x_move} #{y_move}"
      self[:MediaBox] = [(c_mediabox[0] + x_move), (c_mediabox[1] + y_move), ((c_mediabox[2] * x_ratio) + x_move), ((c_mediabox[3] * y_ratio) + y_move)]
      self[:CropBox] = [(c_cropbox[0] + x_move), (c_cropbox[1] + y_move), ((c_cropbox[2] * x_ratio) + x_move), ((c_cropbox[3] * y_ratio) + y_move)] if c_cropbox
      x_ratio = y_ratio = [x_ratio, y_ratio].min if conserve_aspect_ratio
      # insert the rotation stream into the current content stream
      # insert_content "q\n#{x_ratio.round(4).to_s} 0 0 #{y_ratio.round(4).to_s} 0 0 cm\n1 0 0 1 #{x_move} #{y_move} cm\n", 0
      insert_content "q\n#{x_ratio.round(4)} 0 0 #{y_ratio.round(4)} #{x_move} #{y_move} cm\n", 0
      # close the rotation stream
      insert_content CONTENT_CONTAINER_END
      # disconnect the content stream, so that future inserts aren't rotated
      @contents = false # init_contents

      # always return self, for chaining.
      self
    end

    # crops the page using a <b>relative</b> size.
    #
    # `crop` will crop the page by updating it's MediaBox property using a <b>relative</b> crop box. i.e.,
    # when cropping a page with {#page_size} of [10,10,900,900] to [5,5,500,500], the resulting page size should be [15, 15, 510, 510] - allowing you to ignore a page's initial XY starting point when cropping.
    #
    # for an absolute cropping, simpy use the {#mediabox=} or {#cropbox=} methods, setting their value to the new {page_size}.
    #
    # accepts:
    # new_size:: an Array with four elements: [X0, Y0, X_max, Y_max]. For example, inch4(width)x6(length): `[200, 200, 488, 632]`
    def crop(new_size = nil)
      # no crop box? clear any cropping.
      return page_size unless new_size
      # type safety
      raise TypeError, "pdf.page\#crop expeceted an Array (or nil)" unless Array === new_size

      # set the MediaBox to the existing page size
      self[:MediaBox] = page_size
      # clear the CropBox
      self[:CropBox] = nil
      # update X0
      self[:MediaBox][0] += new_size[0]
      # update Y0
      self[:MediaBox][1] += new_size[1]
      # update X max IF the value is smaller then the existing value
      self[:MediaBox][2] = (self[:MediaBox][0] + new_size[2] - new_size[0]) if (self[:MediaBox][0] + new_size[2] - new_size[0])  < self[:MediaBox][2]
      # update Y max IF the value is smaller then the existing value
      self[:MediaBox][3] = (self[:MediaBox][1] + new_size[3] - new_size[1]) if (self[:MediaBox][1] + new_size[3] - new_size[1])  < self[:MediaBox][3]
      # return self for chaining
      self
    end

    # rotate the page 90 degrees counter clockwise
    def rotate_left
      self[:Rotate] = (self[:Rotate].to_f() + 90)
      fix_rotation
    end

    # rotate the page 90 degrees clockwise
    def rotate_right
      self[:Rotate] = (self[:Rotate].to_f() - 90)
      fix_rotation
    end

    # rotate the page by 180 degrees
    def rotate_180
      self[:Rotate] = (self[:Rotate].to_f() + 180)
      fix_rotation
    end

    # get or set (by clockwise rotation) the page's data orientation.
    #
    # note that the data's orientation is the way data is oriented on the page.
    # The display orientati0n (which might different) is controlled by the `:Rotate` property. see {#fix_orientation} for more details.
    #
    # accepts one optional parameter:
    # force:: to get the orientation, pass nil. to set the orientatiom, set fource to either :portrait or :landscape. defaults to nil (get orientation).
    # clockwise:: sets the rotation directions. defaults to true (clockwise rotation).
    #
    # returns the current orientation (:portrait or :landscape) if used to get the orientation.
    # otherwise, if used to set the orientation, returns the page object to allow method chaining.
    #
    # * Notice: a square page always returns the :portrait value and is ignored when trying to set the orientation.
    def orientation(force = nil, clockwise = true)
      a = page_size
      return (a[2] - a[0] > a[3] - a[1]) ? :landscape : :portrait unless force
      unless orientation == force || (a[2] - a[0] == a[3] - a[1])
        self[:Rotate] = 0
        clockwise ? rotate_right : rotate_left
      end
      self
    end

    # Writes a table to the current page, removing(!) the written rows from the table_data Array.
    #
    # since the table_data Array is updated, it is possible to call this method a few times,
    # each time creating or moving to the next page, until table_data.empty? returns true.
    #
    # accepts a Hash with any of the following keys as well as any of the PDFWriter#textbox options:
    # headers:: an Array of strings with the headers (will be repeated every page).
    # table_data:: as Array of Arrays, each containing a string for each column. the first row sets the number of columns. extra columns will be ignored.
    # font:: a registered or standard font name (see PDFWriter). defaults to nil (:Helvetica).
    # header_font:: a registered or standard font name for the headers (see PDFWriter). defaults to nil (the font for all the table rows).
    # max_font_size:: the maximum font size. if the string doesn't fit, it will be resized. defaults to 14.
    # column_widths:: an array of relative column widths ([1,2] will display only the first two columns, the second twice as big as the first). defaults to nil (even widths).
    # header_color:: the header color. defaults to [0.8, 0.8, 0.8] (light gray).
    # main_color:: main row color. defaults to nil (transparent / white).
    # alternate_color:: alternate row color. defaults to [0.95, 0.95, 0.95] (very light gray).
    # font_color:: font color. defaults to [0,0,0] (black).
    # border_color:: border color. defaults to [0,0,0] (black).
    # border_width:: border width in PDF units. defaults to 1.
    # header_align:: the header text alignment within each column (:right, :left, :center). defaults to :center.
    # row_align:: the row text alignment within each column. defaults to :left (:right for RTL table).
    # direction:: the table's writing direction (:ltr or :rtl). this reffers to the direction of the columns and doesn't effect text (rtl text is automatically recognized). defaults to :ltr.
    # max_rows:: the maximum number of rows to actually draw, INCLUDING the header row. deafults to 25.
    # xy:: an Array specifying the top-left corner of the table. defaulte to [page_width*0.1, page_height*0.9].
    # size:: an Array specifying the height and the width of the table.  defaulte to [page_width*0.8, page_height*0.8].
    def write_table(options = {})
      defaults = {
        headers: nil,
        table_data: [[]],
        font: nil,
        header_font: nil,
        max_font_size: 14,
        column_widths: nil,
        header_color: [0.8, 0.8, 0.8],
        main_color: nil,
        alternate_color: [0.95, 0.95, 0.95],
        font_color: [0, 0, 0],
        border_color: [0, 0, 0],
        border_width: 1,
        header_align: :center,
        row_align: nil,
        direction: :ltr,
        max_rows: 25,
        xy: nil,
        size: nil
      }
      options = defaults.merge options
      raise 'method call error! not enough rows allowed to create table' if (options[:max_rows].to_i < 1 && options[:headers]) || (options[:max_rows].to_i <= 0)
      options[:header_font] ||= options[:font]
      options[:row_align] ||= ((options[:direction] == :rtl) ? :right : :left)
      options[:xy] ||= [((page_size[2] - page_size[0]) * 0.1), ((page_size[3] - page_size[1]) * 0.9)]
      options[:size] ||= [((page_size[2] - page_size[0]) * 0.8), ((page_size[3] - page_size[1]) * 0.8)]
      # assert table_data is an array of arrays
      return false unless (options[:table_data].select { |r| !r.is_a?(Array) }).empty?
      # compute sizes
      top = options[:xy][1]
      height = options[:size][1] / options[:max_rows]
      from_side = options[:xy][0]
      width = options[:size][0]
      columns = options[:table_data][0].length
      column_widths = []
      columns.times { |_i| column_widths << (width / columns) }
      if options[:column_widths]
        scale = 0
        options[:column_widths].each { |w| scale += w }
        column_widths = []
        options[:column_widths].each { |w| column_widths << (width * w / scale) }
      end
      column_widths = column_widths.reverse if options[:direction] == :rtl
      # set count and start writing the data
      row_number = 1

      until options[:table_data].empty? || row_number > options[:max_rows]
        # add headers
        if options[:headers] && row_number == 1
          x = from_side
          headers = options[:headers]
          headers = headers.reverse if options[:direction] == :rtl
          column_widths.each_index do |i|
            text = headers[i].to_s
            textbox text, { x: x, y: (top - (height * row_number)), width: column_widths[i], height: height, box_color: options[:header_color], text_align: options[:header_align] }.merge(options).merge(font: options[:header_font])
            x += column_widths[i]
          end
          row_number += 1
        end
        x = from_side
        row_data = options[:table_data].shift
        row_data = row_data.reverse if options[:direction] == :rtl
        column_widths.each_index do |i|
          text = row_data[i].to_s
          box_color = (options[:alternate_color] && ((row_number.odd? && options[:headers]) || row_number.even?)) ? options[:alternate_color] : options[:main_color]
          textbox text, { x: x, y: (top - (height * row_number)), width: column_widths[i], height: height, box_color: box_color, text_align: options[:row_align] }.merge(options)
          x += column_widths[i]
        end
        row_number += 1
      end
      self
    end

    # creates a copy of the page. if the :secure flag is set to true, the resource indentifiers (fonts etc') will be renamed in order to secure their uniqueness.
    def copy(secure = false)
      # since only the Content streams are modified (Resource hashes are created anew),
      # it should be safe (and a lot faster) to create a deep copy only for the content hashes and streams.
      delete :Parent
      prep_content_array
      page_copy = clone
      page_copy[:Contents] = page_copy[:Contents].map do |obj|
        obj = obj.dup
        obj[:referenced_object] = obj[:referenced_object].dup if obj[:referenced_object]
        obj[:referenced_object][:raw_stream_content] = obj[:referenced_object][:raw_stream_content].dup if obj[:referenced_object] && obj[:referenced_object][:raw_stream_content]
        obj
      end
      if page_copy[:Resources]
        page_res = page_copy[:Resources] = page_copy[:Resources].dup
        page_res = page_copy[:Resources][:referenced_object] = page_copy[:Resources][:referenced_object].dup if page_copy[:Resources][:referenced_object]
        page_res.each do |k, v|
          v = page_res[k] = v.dup if v.is_a?(Array) || v.is_a?(Hash)
          v = v[:referenced_object] = v[:referenced_object].dup if v.is_a?(Hash) && v[:referenced_object]
        end
      end
      page_copy.instance_exec(secure || @secure_injection) { |s| secure_for_copy if s; init_contents; self }
    end

    ###################################
    # protected methods

    protected

    # accessor (getter) for the stream in the :Contents element of the page
    # after getting the string object, you can operate on it but not replace it (use << or other String methods).
    def contents
      @contents ||= init_contents
    end

    # initializes the content stream in case it was not initialized before
    def init_contents
      self[:Contents] = self[:Contents][:referenced_object][:indirect_without_dictionary] if self[:Contents].is_a?(Hash) && self[:Contents][:referenced_object] && self[:Contents][:referenced_object].is_a?(Hash) && self[:Contents][:referenced_object][:indirect_without_dictionary]
      self[:Contents] = [self[:Contents]] unless self[:Contents].is_a?(Array)
      self[:Contents].delete(is_reference_only: true, referenced_object: { indirect_reference_id: 0, raw_stream_content: '' })
      # un-nest any referenced arrays
      self[:Contents].map! { |s| actual_value(s).is_a?(Array) ? actual_value(s) : s }
      self[:Contents].flatten!
      self[:Contents].compact!
      # wrap content streams
      insert_content 'q', 0
      insert_content 'Q'

      # Prep content
      @contents = ''
      insert_content @contents
      @contents
    end

    # adds a string or an object to the content stream, at the location indicated
    #
    # accepts:
    # object:: can be a string or a hash object
    # location:: can be any numeral related to the possition in the :Contents array. defaults to -1 == insert at the end.
    def insert_content(object, location = -1)
      object = { is_reference_only: true, referenced_object: { indirect_reference_id: 0, raw_stream_content: object } } if object.is_a?(String)
      raise TypeError, 'expected a String or Hash object.' unless object.is_a?(Hash)
      prep_content_array
      self[:Contents].insert location, object
      self[:Contents].flatten!
      self
    end

    def prep_content_array
      return self if self[:Contents].is_a?(Array)
      init_contents
      # self[:Contents] = self[:Contents][:referenced_object] if self[:Contents].is_a?(Hash) && self[:Contents][:referenced_object] && self[:Contents][:referenced_object].is_a?(Array)
      # self[:Contents] = self[:Contents][:indirect_without_dictionary] if self[:Contents].is_a?(Hash) && self[:Contents][:indirect_without_dictionary] && self[:Contents][:indirect_without_dictionary].is_a?(Array)
      # self[:Contents] = [self[:Contents]] unless self[:Contents].is_a?(Array)
      # self[:Contents].compact!
      self
    end

    # returns the basic font name used internally
    def base_font_name
      @base_font_name ||= 'Writer' + SecureRandom.hex(7) + 'PDF'
    end

    # creates a font object and adds the font to the resources dictionary
    # returns the name of the font for the content stream.
    # font:: a Symbol of one of the fonts registered in the library, or:
    # - :"Times-Roman"
    # - :"Times-Bold"
    # - :"Times-Italic"
    # - :"Times-BoldItalic"
    # - :Helvetica
    # - :"Helvetica-Bold"
    # - :"Helvetica-BoldOblique"
    # - :"Helvetica- Oblique"
    # - :Courier
    # - :"Courier-Bold"
    # - :"Courier-Oblique"
    # - :"Courier-BoldOblique"
    # - :Symbol
    # - :ZapfDingbats
    def set_font(font = :Helvetica)
      # if the font exists, return it's name
      resources[:Font] ||= {}
      fonts_res = resources[:Font][:referenced_object] || resources[:Font]
      fonts_res.each do |k, v|
        return k if v.is_a?(Fonts::Font) && v.name && v.name == font
      end
      # set a secure name for the font
      name = (base_font_name + (fonts_res.length + 1).to_s).to_sym
      # get font object
      font_object = Fonts.get_font(font)
      # return false if the font wan't found in the library.
      return false unless font_object
      # add object to reasource
      fonts_res[name] = font_object
      # return name
      name
    end

    # register or get a registered graphic state dictionary.
    # the method returns the name of the graphos state, for use in a content stream.
    def graphic_state(graphic_state_dictionary = {})
      # if the graphic state exists, return it's name
      resources[:ExtGState] ||= {}
      gs_res = resources[:ExtGState][:referenced_object] || resources[:ExtGState]
      gs_res.each do |k, v|
        return k if v.is_a?(Hash) && v == graphic_state_dictionary
      end
      # set graphic state type
      graphic_state_dictionary[:Type] = :ExtGState
      # set a secure name for the graphic state
      name = SecureRandom.hex(9).to_sym
      # add object to reasource
      gs_res[name] = graphic_state_dictionary
      # return name
      name
    end

    # encodes the text in an array of [:font_name, <PDFHexString>] for use in textbox
    def encode_text(text, fonts)
      # text must be a unicode string and fonts must be an array.
      # this is an internal method, don't perform tests.
      fonts_array = []
      fonts.each do |name|
        f = Fonts.get_font name
        fonts_array << f if f
      end

      # before starting, we should reorder any RTL content in the string
      text = reorder_rtl_content text

      out = []
      text.chars.each do |c|
        fonts_array.each_index do |i|
          next unless fonts_array[i].cmap.nil? || (fonts_array[i].cmap && fonts_array[i].cmap[c])
          # add to array
          if out.last.nil? || out.last[0] != fonts[i]
            out.last[1] << '>' unless out.last.nil?
            out << [fonts[i], '<', 0, 0]
          end
          out.last[1] << (fonts_array[i].cmap.nil? ? (c.unpack('H*')[0]) : fonts_array[i].cmap[c])
          if fonts_array[i].metrics[c]
            out.last[2] += fonts_array[i].metrics[c][:wx].to_f
            out.last[3] += fonts_array[i].metrics[c][:wy].to_f
          end
          break
        end
      end
      out.last[1] << '>' if out.last
      out
    end

    # a very primitive text reordering algorithm... I was lazy...
    # ...still, it works (I think).
    def reorder_rtl_content(text)
      rtl_characters = "\u05d0-\u05ea\u05f0-\u05f4\u0600-\u06ff\u0750-\u077f"
      rtl_replaces = { '(' => ')', ')' => '(',
                       '[' => ']', ']' => '[',
                       '{' => '}', '}' => '{',
                       '<' => '>', '>' => '<' }
      return text unless text =~ /[#{rtl_characters}]/

      out = []
      scanner = StringScanner.new text
      until scanner.eos?
        if scanner.scan(/[#{rtl_characters} ]/)
          out.unshift scanner.matched
        elsif scanner.scan(/[^#{rtl_characters}]+/)
          if out.empty? && scanner.matched.match(/[\s]$/) && !scanner.eos?
            white_space_to_move = scanner.matched.match(/[\s]+$/).to_s
            out.unshift scanner.matched[0..-1 - white_space_to_move.length]
            out.unshift white_space_to_move
          elsif scanner.matched =~ /^[\(\)\[\]\{\}\<\>]$/
            out.unshift rtl_replaces[scanner.matched]
          else
            out.unshift scanner.matched
          end
        end
      end
      out.join.strip
    end

    # copy_and_secure_for_injection(page)
    # - page is a page in the pages array, i.e.
    #   pdf.pages[0]
    # takes a page object and:
    #
    # makes a deep copy of the page (Ruby defaults to pointers, so this will copy the memory).
    #
    # then it will rewrite the content stream with renamed resources, so as to avoid name conflicts.
    def secure_for_copy
      # initiate dictionary from old names to new names
      names_dictionary = {}

      # travel every dictionary to pick up names (keys), change them and add them to the dictionary
      res = resources
      res.each do |k, v|
        next unless actual_value(v).is_a?(Hash)
        # if k == :XObject
        # 	self[:Resources][k] = v.dup
        # 	next
        # end
        new_dictionary = {}
        new_name = 'Combine' + SecureRandom.hex(7) + 'PDF'
        i = 1
        actual_value(v).each do |old_key, value|
          new_key = (new_name + i.to_s).to_sym
          names_dictionary[old_key] = new_key
          new_dictionary[new_key] = value
          i += 1
        end
        res[k] = new_dictionary
      end

      # now that we have replaced the names in the resources dictionaries,
      # it is time to replace the names inside the stream
      # we will need to make sure we have access to the stream injected
      # we will user PDFFilter.inflate_object
      self[:Contents].each do |c|
        stream = actual_value(c)
        PDFFilter.inflate_object stream
        names_dictionary.each do |old_key, new_key|
          stream[:raw_stream_content].gsub! object_to_pdf(old_key), object_to_pdf(new_key) ##### PRAY(!) that the parsed datawill be correctly reproduced!
        end
        # # # the following code isn't needed now that we wrap both the existing and incoming content streams.
        # # patch back to PDF defaults, for OCRed PDF files.
        # stream[:raw_stream_content] = "q\n0 0 0 rg\n0 0 0 RG\n0 Tr\n1 0 0 1 0 0 cm\n%s\nQ\n" % stream[:raw_stream_content]
      end
      self
    end

    # @return [true, false] returns true if there are two different resources sharing the same named reference.
    def should_secure?(page)
      # travel every dictionary to pick up names (keys), change them and add them to the dictionary
      res = actual_value(resources)
      foreign_res = actual_value(page.resources)
      tmp = nil
      res.each do |k, v|
        next unless (v = actual_value(v)).is_a?(Hash) && (tmp = actual_value(foreign_res[k])).is_a?(Hash)
        v.keys.each do |name|
          return true if tmp[name] && tmp[name] != v[name]
        end # else # Do nothing, this is taken care of elseware
      end
      false
    end
  end
end