organized code into Smr module

[smr.git] / gui / lib / smr_figures.rb

#
# This file is part of SMR.
#
# SMR is free software: you can redistribute it and/or modify it under the
# terms of the GNU General Public License as published by the Free Software
# Foundation, either version 3 of the License, or (at your option) any later
# version.
#
# SMR is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# SMR.  If not, see <http://www.gnu.org/licenses/>.
#

##
# Implements a mapping mechanism to keep track of the FigureData records of
# most recent relevance. Its most useful when inherited from the actual
# organization class.
class SmrFiguresDataMap

    def initialize
        @map = Hash.new{ |h,k| h[k] = Hash.new(&h.default_proc) }
        @last_figure_var = FigureVar.new
        @last_figure_data = FigureData.new
    end

    ##
    # Add a FigureData to the map, return code indicates whether this data is
    # already known (1), known and more recent (2) or not known at all (false).
    #
    # Map items are categorized into (:name, :year, :id, :period). This is a
    # multi-dimensional Hash, see
    # http://stackoverflow.com/questions/10253105/dynamically-creating-a-multi-dimensional-hash-in-ruby
    #
    # Unknown items will be map_added to the map. If a FigureData with the same
    # categorization is passed, the map uses :time to decide whether to update
    # or ignore it.
    #
    def map_add(figure_data)
        unless (figure_data.is_a?(FigureData) or figure_data.is_a?(SmrAutofigureData))
            raise ':figure_data must be of FigureData or SmrAutofigureData'
        end
        @last_figure_data = figure_data
        @last_figure_var = @last_figure_data.FigureVar

        # define locals to shorten the code below
        name = @last_figure_var.name
        id = @last_figure_var.id.to_i
        year = @last_figure_data.time.year.to_i
        period = @last_figure_data.period

        if not (@map.has_key?(name) and @map[name].has_key?(year) and @map[name][year].has_key?(id) and @map[name][year][id].has_key?(period)) then
            # we do not know this figure yet, map_add to map
            @map[name][year][id][period] = @last_figure_data.time
            return false
        else
            if (@map.has_key?(name) and @map[name].has_key?(year) and @map[name][year].has_key?(id) and @map[name][year][id].has_key?(period)) and @map[name][year][id][period] > figure_data.time then
                # known but older
                return 1
            else
                # known but more recent => update map
                @map[name][year][id][period] = figure_data.time
                return 2
            end
        end
    end

    ##
    # return name last FigureVar processed by map_add()
    def get_name
        @last_figure_var.name
    end

    ##
    # return FigureData id of the last item processed by map_add()
    def get_figure_data_id
        @last_figure_data.id
    end

    ##
    # return period of the last item processed by map_add()
    def get_period
        @last_figure_data.period
    end

    ##
    # return date as +Time+ of the last item processed by map_add()
    def get_date
        @last_figure_data.time
    end
end

##
# Builds FigureVar and FigureData objects into a form that is easy to process
# in views.
#
# Use add() to push FigureData records into the table. When done, tell the object
# to process all data by calling render(). Thereafter all data is available for
# display through the +get_*+ methods.
#
# Note that methods return false or raise an exception when used their proper
# mode.
#
class SmrFiguresDataTable < SmrFiguresDataMap
    def initialize
        super

        ##
        # mode of operation (input or display)
        #
        # The add() mgqethod is only active in input mode while all the +get_*+
        # methods are only available in display mode. You must call render()
        # before you can get any data out. A new object is in input mode.
        @input_mode = true

        # see add() and add_record()
            @most_recent_figures = Array.new

        # see add_record()a and update_data()
        @less_recent_figures = Hash.new{ |h,k| h[k] = Hash.new(&h.default_proc) }

        # the final table created by render()
        @table = Hash.new{ |h,k| h[k] = Hash.new(&h.default_proc) }

        # see get_class()
        @class = Array.new

        ##
        # CSS class string used for rows, altered by self.cycle_css_row()
        @cycle_css_row = 'row1'
    end

    ##
    # Process a FigureData while in input mode.
    def add(figure_data)
        raise 'add() only works in input mode, it stops working when render() was called' if not @input_mode

        case self.map_add(figure_data)
            when false then self.add_record(figure_data)
            when 1     then self.add_record(figure_data, {:less_recent=>true})
            when 2     then self.update_data(figure_data)
        end

        true
    end

    ##
    # End input mode and render all data ready for displaying
    #
    # NOTE: @table is a multi-dimensional array but we use only two dimensions,
    #       see http://stackoverflow.com/questions/10253105/dynamically-creating-a-multi-dimensional-hash-in-ruby
    #
    # Final table will look like when viewed by calling cell() on each
    # +row+,+col+ coordinate:
    #
    #    ______ ________________ ____________ ______________ _______________ _____
    #   |      |                | -  Year -  | - Quarter 1 -| - Quarter 2 - | ... |
    #   | year | FigureVar.name | FigureData |  FigureData  |   FigureData  | ... |
    #   |------|----------------|------------|--------------|---------------|-----|
    #     ...
    #
    # The text_table() method is very useful for debugging.
    #
    def render
        raise 'no data to render(), use add() first' if @most_recent_figures.empty?
        @input_mode = false
        @table.clear if @table.count > 0

        # create table head
        periods = FigureData.new.get_periods
        @table[0][0] = ''
        @table[0][1] = ''
        periods.each_index {|i| @table[0][i+2]=FigureData.new.translate_period(periods[i])}

        # add most recent FigureVar
        # - first: sort by FigureVar.time
        # - second: add by period index + offset (because of the table head)
        # ATTENTION: sorting by fd.FigureVar.name probably expensive, consider
        #            fs.id_figure_var as performant alternative
        @most_recent_figures.sort_by! { |fd| [fd.time.year, fd.FigureVar.name] }

        row=1
        @most_recent_figures.each do |fd|
            @table[row][0] = fd.time.year
            @table[row][1] = fd.FigureVar.name

            col = periods.index(fd.period) + 2
            @table[row][col] = fd
    
            row += 1
        end

        # consolidate rows by years and figure name (first two columns)
        prev_row = @table[1]
        prev_key = 1
        @table.each do |k, row|
            next if k == 0 # skip table head

            if row[0]==prev_row[0] and row[1]==prev_row[1] then
                # merge into prev_row since row is more recent, see sort_by above
                @table[k] = prev_row.merge(row)
                @table.delete(prev_key) if k > prev_key
            end
            prev_row = @table[k]
            prev_key = k
        end

        # re-index @table since rows(), columns() and cell() rely on
        # consecutive numbering
        tmp_table = Hash.new{ |h,k| h[k] = Hash.new(&h.default_proc) }
        i=0
        @table.each_key do |k|
            tmp_table[i] = @table[k]
            i += 1
        end
        @table = tmp_table
    end

    ##
    # print table in text format (for debugging only!)
    def text_table
        self.render
        format = Array.new(self.columns, '%12s').join('|')

        puts '----------- @table ------------'
        for r in 0...self.rows
            row = Array.new
            for c in 0...self.columns
                row[c] = self.cell(r, c)
            end
            puts(format % row)
        end
        puts '-------------------------------'
    end

    ##
    # Returns number of rows after render().
    def rows
        raise 'rows() only works after render() was called' if @input_mode
        @table.count
    end

    ##
    # Returns number of columns after render().
    # NOTE: the first row sets the number of columns of the table
    def columns
        raise 'columns() only works after render() was called' if @input_mode
        @table[0].count
    end

    ##
    # Returns content for a cell identified by row and col, nil if empty.
    def cell(row, col)
        raise 'cell() only works after render() was called' if @input_mode

        if c = self.raw_cell_content(row, col) then
            if c.is_a?(FigureData) or c.is_a?(SmrAutofigureData)
                c.value
            else
                # leftmost column is always a descriptive string, not to be
                # rounded, scaled, whatever ...
                if col==0 then c.to_s else c end
            end
        else
            nil
        end
    end

    ##
    # Returns unit of value in cell or nil if there is nothing.
    def cell_unit(row, col)
        raise 'cell_unit() only works after render() was called' if @input_mode

        if c = self.raw_cell_content(row, col) then
            if c.is_a?(FigureData) or c.is_a?(SmrAutofigureData)
                c.FigureVar.unit
            end
        end
    end

    ##
    # Return rowspanning information for given cell (row, col) or false if this
    # cell should not span at all
    #
    # rowspanning information for @datatable is stored in @rowspan and looks
    # this way:
    # - two-dimensional array: #row, #col
    # - a number indicates how many lines a cell should span down
    # - a dash ('-') indicates that a cell is covered by another cell that
    #   spans above it
    # - #row,#col coordinates are not set means the cell is not affected by
    #   rowspanning at all
    def rowspan(row, col)
        raise 'rowspan() only works after render() was called' if @input_mode
        false
    end

    ##
    # Return class information for given row or cell
    #
    # False is returned if there is no such information (the row or cell should
    # not have any class attribute set).
    #
    # The +col+ paramenter is optional, if given you ask for a specific cell,
    # if ommited (default) you ask for the entire row.
    #
    # CSS class information for @datatable is stored in @class and looks like
    # this:
    # - one-or-two-dimensional array: #row, #col
    # - contains a string of CSS class names that should be set on a given row
    #   and/or cell
    # - false means that there shouldn't be any class attribute set
    def class(row, col=false)
        raise 'class() only works after render() was called' if @input_mode
        false
    end

    ##
    # Return link to edit FigureVar of given field
    #
    # False is returned if that field is empty.
    def link(row, col)
        raise 'link() only works after render() was called' if @input_mode
        
        if c = self.raw_cell_content(row, col) then
           if c.is_a?(FigureData) then return('/figures/%i/edit' % c.id) end
        end
        
        false
    end

protected

    ##
    # add FigureData to internal @most_recent_figures or @less_recent_figures
    #
    # @less_recent_figures contains all those where a more recent counterpart
    # is available in @most_recent_figures. See get_summary() and
    # have_summary().
    #
    # @most_recent_figures is a regular +Array+
    #
    # @less_recent_figures is a multi-dimensional +Hash+ structured as
    # 
    #   @less_recent_figures[:year][:period][:id_figure_data] = Array.new
    #
    def add_record(figure_data, options={ :less_recent=>false })
        y  = figure_data.time.year
        p  = figure_data.period
        id = figure_data.id

        if options[:less_recent] then
            if @less_recent_figures.has_key?(y) and @less_recent_figures[y].has_key?(p) and @less_recent_figures[y][p].has_key?(id) then
               @less_recent_figures[y][p][id] << figure_data
            else
                @less_recent_figures[y][p][id] = [figure_data]
            end
        else
            @most_recent_figures << figure_data
        end

        true
    end

    ##
    # update FigureData item in @most_recent_figures, make sure the old data is
    # kept in @less_recent_figures.
    # FIXME: to be implemented!
    def update_data(figure_data)
        #@most_recent_figures.find(:id_figure_var=>figure_data.id_figure_var, ...)
        true
    end

    ##
    # Returns content for a cell identified by row and col.
    #
    # The content can be +nil+ if that cell is empty or whatever is there, ie.
    # a FigureData, a +String+, etc....
    def raw_cell_content(row, col)
        if @table.has_key?(row) and @table[row].has_key?(col) then
                @table[row][col]
        else nil end
    end
end

##
# creates many (!) SmrAutofigureData objects from a FigureVar record
#
# A SmrAutofigure is based on a FigureVar record with the :expression field
# containing a math expression. That is each FigureVar becomes a SmrAutofigure
# by setting the :expression field. It will return to being a ordinary
# FigureVar by emptying the the :expression field.
#
# Each SmrAutofigure will create as many SmrAutofigureData objects as possible,
# depending on the information available to solve the given :expression. It
# might be hundreds if there is input data for, say, 100 fiscal quarters.
#
class SmrAutofigure

    ##
    # Init with FigureVar and a list of variables contained in its :expression.
    # See SmrDaemonClient#parse_math_expressions.
    def initialize(figure_var, variables)
        raise 'figure_var must be a FigureVar object' unless figure_var.is_a?(FigureVar)
        raise 'figure_var must have :expression field set' if figure_var.expression.empty?
        @autofigure = figure_var
        @expression_vars = Hash.new

        # internally we work with FigureVar ids, not with their names
        FigureVar.select(:id, :name).where(:name=>variables).each do |v|
            @expression_vars[v.id]=v.name
        end

        # collects FigureData by year and period, to know what we have (=>
        # #add()) and still need (=> #get_missing_variables)
        @datamatrix = Hash.new

        # collects Time if most recent FigureData per row in @datamatrix,
        # necessary to know how to time the SmrAutofigureData objects
        @timematrix = Hash.new

        @id_stock = nil
    end

    ##
    # Add FigureData as input for solving the expression.
    #
    # Returns +true+ if it was added or +false+ if it did not help to fill this
    # expression.
    #
    # Note: data is overwritten. A FigureData of same +:year+ and +:period+
    # will overwrite the previously passed one. So mind the order.
    def add(figure_data)
        raise 'figure_data must be a FigureData object' unless figure_data.is_a?(FigureData)

        if @id_stock and @id_stock != figure_data.id_stock
            raise 'add()ing FigureData of another Stock should not happen, should it?'
        else
            @id_stock = figure_data.id_stock
        end

        i = '%s_%s' % [figure_data.time.year, figure_data.period ]
        if @expression_vars.keys.include?(figure_data.id_figure_var)
            newdata = { figure_data.id_figure_var=>figure_data.value }
            @datamatrix[i] = if @datamatrix[i] then @datamatrix[i].merge(newdata) else newdata end

            if not @timematrix[i] or @timematrix[i] < figure_data.time then
                @timematrix[i] = figure_data.time
            end

            return true
        end

        return false
    end

    ##
    # Tells whats missing to solve all expressions.
    def get_missing_variables
        missing = Array.new
        @datamatrix.each do |i,d|
            diff = @expression_vars.keys - d.keys
            if not diff.empty?
                missing << i.to_s + '_' + @expression_vars.select{|k,v| diff.include?(k) }.values.join('-')
            end
        end
        missing
    end

    ##
    # Returns collection of SmrAutofigureData objects with solvable
    # expressions. Objects with non-solvable expressions (missing data) are
    # skipped silently.
    def get
        @datamatrix.collect do |i,d|
            diff = @expression_vars.keys - d.keys
            if diff.empty?
                dn = Hash.new
                d.each{ |k,v|  dn[@expression_vars[k]]=v }
                SmrAutofigureData.new(@autofigure, dn, @id_stock, i.split('_').second, @timematrix[i])
            end
        end.compact
    end

end

##
# like a FigureData object without related database record
#
# A SmrAutofigureData object is ment to behave exactly like a FigureData
# object. Except that it can`t be saved or updated or trigger any other
# database operation. Its an entirely artificial record so to say.
class SmrAutofigureData
    # compatibility with FigureData, always +nil+
    attr_reader :id

    # compatibility with FigureData, empty
    attr_reader :analyst, :is_expected, :is_audited, :comment

    # where this autofigure was derived from
    attr_reader :id_figure_var, :id_stock, :period

    # unix timestamp when this autofigure was made, also see time()
    attr_reader :date

    # the Hash of data variables and values necessary for solving
    attr_reader :expression, :solving_data

    # result of the expression or +nil+ if not yet solved
    # Note: this must be calculated/set externaly
    attr_accessor :value

    ##
    # Give FigureVar out of which this SmrAutofigureData is derived and a Hash
    # of var=>value for solving the expression. +id_stock+ is to know what this
    # is for.
    def initialize(autofigure, values, id_stock, period, time)
        raise 'autofigure must be a FigureVar' unless autofigure.is_a?(FigureVar)
        raise 'values must be a Hash' unless values.is_a?(Hash)
        raise 'time must be of Time' unless time.is_a?(Time)
        @autofigure = autofigure
        @expression = autofigure.expression
        @solving_data = values

        # carry on meaningful fields
        @id_figure_var = autofigure.id
        @id_stock = id_stock
        @date = time.to_i
        @period = period
        @analyst = self.class
    end

    ##
    # Time when this autofigure was made
    def time
        Time.at(self.date)
    end

    ##
    # wrapper for compatibility with FigureData
    def get_periods
        FigureData.new.get_periods
    end

    ##
    # wrapper for compatibility with FigureData
    def translate_period(period=self.period)
        FigureData.new.translate_period(period)
    end

    ##
    # wrapper for compatibility with FigureData
    def FigureVar
        @autofigure
    end
end