StdlibDoc::Status::Report (Class)

In: StdlibDoc/Status/Report.rb
Parent: Object

This class contains several class methods that take an array of Record and return a report. It is thus an external responsibility to select the items for reporting. These methods just format their outputs in different ways.

It also contains an array of canned report types, complete with label, heading, target method, and filter proc. You can execute a report with the execute method.

TODO: move canned reports to separate module? TODO: allow for different output types (text, HTML, …) with the same 

      report names.  This means different classes for different output
      formats.  The canned report types are independent of output format.

Methods

execute   full   reports   summary   types  

Constants

CannedReport = Struct.new( :label, :heading, # Description for user (1). :description, # Description for user (2). :report_type, # :summary, :full, etc. :filter # proc: [Record] -> [Record]; filter and sort.
  A canned report defines a filter/sorter on a list of Records. It has a name and a couple of descriptions so that people can select them. This probably belongs elsewhere.

Public Class methods

reports()

[Source]

# File StdlibDoc/Status/Report.rb, line 114
    def Report.reports
      @@reports
    end
types()

Return a list of the valid report method names. TODO: generate this instead of hardcoding it.

[Source]

# File StdlibDoc/Status/Report.rb, line 122
    def Report.types
      [:full, :summary]
    end
execute(n, records, options)

Input:

n:the report number
records:list of Record to be reported on
options:override the type of report (e.g. full)

Important options:

  • report_type, to override the default (e.g. :full)
  • color, to force color output on the terminal

The report number is used to select a canned report which defines a filter on the set of Records and a default target.

The output of the report is returned (should be a String).

[Source]

# File StdlibDoc/Status/Report.rb, line 141
    def Report.execute(n, records, options)
      rpt = @@reports[n]
      rtype = options.report_type || rpt.report_type
      raise "Non-existent report: #{n.inspect}" if rpt.nil?
      Report.send(rtype, rpt.filter[records], options)
    end
summary(records, options=nil)

Return a basic report on all the records. Display the fields path, priority, status, score, owner, and comment. Comment is abbreviated so we can fit on one line. TODO: introduce highlighting

[Source]

# File StdlibDoc/Status/Report.rb, line 155
    def Report.summary(records, options=nil)
      display = proc { |record, field|
        data = record.send(field)
        case field
        when :priority
          data || " "
        when :status
          { :open => 'Open', :done => 'Done', :in_progress => 'In_P',
            :ignore => ' Ig ', :obsolete => ' Ob ', :noncore => ' nc ' }[data]
        when :comment
          if data.size < 32
            data
          else
            data[0...29] + "..."
          end
        end
      }

      s = StringIO.new("")
      s.puts %{
        Path                     |Pri|Status|Score|Owner| Comment
        -------------------------+---+------+-----+-----+---------------------------------
      }.trim.tabto(0)
      format = "%-24s | %s | %4s | %3s | %-3s | %-32s\n"
      records.each do |r|
        s.printf(format, r.path.to_s[0...24], display[r, :priority],
          display[r, :status], r.score, r.owner.to_s[0...3],
          display[r, :comment])
      end
      s.string
    end
full(records, options=nil)

Return a full report on all the records. Each file takes a few lines to get through everything. TODO: introduce highlighting

[Source]

# File StdlibDoc/Status/Report.rb, line 192
    def Report.full(records, options=nil)
      display = proc { |record, field|
        data = record.send(field)
        return "-" if data.nil?
        return "-" if data.respond_to? :empty? and data.empty?
        case field
        when :priority then { :L => "low", :M => "medium", :H => "high" }[data]
        when :loc
          total, cmts = data.values_at(:total, :comments)
          pct = (cmts.to_f / total * 100).round rescue 0
          sprintf "%-5d (comments: %2d%%)", total, pct
        when :contributors then data.join(", ")
        when :comment then data.wrap(78)
        else; data
        end
      }

      s = StringIO.new("")
      records.each do |r|
        priority, loc     = display[r, :priority], display[r, :loc]
        score, committed  = display[r, :score], display[r, :committed]
        contributors      = display[r, :contributors]
        owner, comment    = display[r, :owner], display[r, :comment]

        s.printf "\n"
        s.printf "Path:  %-30s Pri: %-7s Stat: %s\n", r.path, priority, r.status
        s.printf "LOC:   %-30s Score: %-5s Committed: %s\n", loc, score, committed
        s.printf "Owner: %-5s Contrib: %s\n", owner, contributors
        s.printf "Comment:\n%s\n", comment.tabto(2)
        s.printf "\n"
      end
      s.string
    end

[Validate]