tchart 1.0.2

data/lib/tchart/process/chart_builder.rb

@@ -0,0 +1,63 @@
+module TChart
+  
+  #
+  # Responsible for constructing a Chart from a Layout and a collection
+  # of items (Separators and YItems).
+  #
+  class ChartBuilder
+    
+    def self.build(layout, items) # => Chart
+      ChartBuilder.new(layout, items).build
+    end
+    
+    def initialize(layout, items)
+      @layout = layout
+      @items = items
+      @elements = []
+    end
+    
+    def build # => Chart
+      build_frame
+      build_x_items
+      build_y_items
+      Chart.new(@elements)
+    end
+    
+  private
+  
+    def build_frame
+      @elements << new_frame_top
+      @elements << new_frame_bottom
+    end
+  
+    def new_frame_top # => GridLine
+      GridLine.new(xy(0, @layout.y_axis_length), xy(@layout.x_axis_length, @layout.y_axis_length))
+    end
+  
+    def new_frame_bottom # => GridLine
+      GridLine.new(xy(0, 0), xy(@layout.x_axis_length, 0))
+    end
+    
+    def build_x_items
+      @layout.x_axis_tick_dates.zip(@layout.x_axis_tick_x_coordinates).each do |date, x|
+        @elements << new_x_label(date.year, x) 
+        @elements << new_x_gridline(x)
+      end
+    end
+    
+    def new_x_label(year, x) # => Label
+      Label.build_xlabel(xy(x, @layout.x_axis_label_y_coordinate), @layout.x_axis_label_width, year.to_s) 
+    end
+    
+    def new_x_gridline(x) # => GridLine
+      GridLine.new(xy(x, 0), xy(x, @layout.y_axis_length))
+    end
+    
+    def build_y_items
+      @items.zip(@layout.y_axis_tick_y_coordinates).each do |item, y| 
+        @elements.concat item.build(@layout, y)
+      end
+    end
+      
+  end
+end

data/lib/tchart/process/command_line_parser.rb

@@ -0,0 +1,73 @@
+module TChart
+  
+  #
+  # Responsible for parsing command line options and arguments.
+  #
+  class CommandLineParser
+    
+    def self.parse(argv) # => [ CommandLineArgs, [] ] or [ nil, [ String, ... ] ]
+      CommandLineParser.new.parse(argv)
+    end
+    
+    def parse(argv) # => [ CommandLineArgs, [] ] or [ nil, [ String, ... ] ]
+      parse_options(argv)
+      [ parse_args(argv), [] ]
+    rescue TChartError => e
+      [ nil, [ e.message ] ]
+    end
+    
+  private
+  
+    def parse_options(argv)
+      argv.map { |arg| arg.strip.downcase }.each do |arg|
+        case
+        when arg == "-h" || arg == "--help"
+          raise_usage
+        when arg == "-v" || arg == "--version"
+          raise_version
+        when arg.start_with?("-")
+          raise_usage
+        end
+      end
+    end
+    
+    def parse_args(argv) # => CommandLineArgs
+      raise_usage unless argv.length == 2
+      data_filename, tex_filename = argv
+      raise_data_filename_not_found(data_filename) unless File.exists?(data_filename)
+      raise_data_filename_not_a_file(data_filename) unless File.file?(data_filename)
+      raise_tex_filename_not_a_file(tex_filename) if File.exists?(tex_filename) && ! File.file?(tex_filename)
+      raise_same_filename(data_filename, tex_filename) if same_file?(data_filename, tex_filename)
+      CommandLineArgs.new(data_filename, tex_filename)
+    end
+
+    def same_file?(filename1, filename2)
+      File.expand_path(filename1) == File.expand_path(filename2)
+    end
+    
+    def raise_version
+      raise TChartError, TChart::Version
+    end
+  
+    def raise_usage
+      raise TChartError, "Usage: tchart [ --version | --help | input-data-filename output-tikz-filename ]"
+    end
+    
+    def raise_data_filename_not_found(data_filename)
+      raise TChartError, "Error: input data file \"#{data_filename}\" not found."
+    end
+
+    def raise_data_filename_not_a_file(data_filename)
+      raise TChartError, "Error: input data file \"#{data_filename}\" is not a file."
+    end
+    
+    def raise_tex_filename_not_a_file(tex_filename)
+      raise TChartError, "Error: existing output data file \"#{tex_filename}\" is not a file."
+    end
+    
+    def raise_same_filename(data_filename, tex_filename)
+      raise TChartError, "Error: input \"#{data_filename}\" and output \"#{tex_filename}\" refer to the same file." 
+    end
+
+  end
+end

data/lib/tchart/process/data_parser.rb

@@ -0,0 +1,76 @@
+module TChart
+  
+  #
+  # Responsible for parsing source data.  Not responsible for 
+  # aquiring the source data, e.g. not responsible for reading
+  # the source data from an input file.
+  #
+  class DataParser
+    
+    #
+    # source_name is used in error messages; for example, if the
+    # source data was read from a file, then source_name would be
+    # the name of that file.
+    #
+    def self.parse(source_name, source_data) # => [ settings, items, errors ]
+      DataParser.new(source_name, source_data).parse
+    end
+    
+    def initialize(source_name, source_data)
+      @source_name = source_name
+      @source_data = source_data
+      @line_number = nil
+      @errors = []
+      @settings_parser = SettingsParser.new
+      @items_parser = ItemsParser.new
+    end
+    
+    def parse # => [ settings, items, errors ]
+      non_blank_source_lines.each { |line| parse_line(line) }
+      check_for_items if @errors.empty?
+      [ @settings_parser.settings, @items_parser.items, @errors ]
+    end
+    
+  private
+    
+    #
+    # Return source data lines that are not empty after
+    # comments have been removed.
+    #
+    def non_blank_source_lines # => Enumerator
+      Enumerator.new do |yielder|
+        @source_data.each_with_index do |line, index|
+          @line_number = index + 1
+          line = remove_comments(line).strip
+          yielder.yield line if line.length > 0
+        end
+      end
+    end
+    
+    #
+    # "item  # A comment."  => "item  "
+    # "# A comment."        => ""
+    # "C\#  # A coment."    => "C\#  "
+    #
+    def remove_comments(line) # => line
+      line.sub(/(?<!\\)#.*$/, '')
+    end
+    
+    def parse_line(line)
+      unless @settings_parser.parse?(line)
+        @items_parser.parse(line)
+      end
+    rescue TChartError => e
+      save_error "#{@source_name}, #{@line_number}: #{e.message}"
+    end
+
+    def check_for_items
+      save_error "#{@source_name}: no items found" if @items_parser.items.empty?
+    end
+    
+    def save_error(message)
+      @errors << message
+    end
+    
+  end
+end

data/lib/tchart/process/data_reader.rb

@@ -0,0 +1,14 @@
+module TChart
+  
+  #
+  # Responsible for reading source data from an input file
+  # and parsing it.
+  #
+  module DataReader
+    
+    def self.read(filename) # => [ settings, items, errors ]
+      File.open(filename) { |f| DataParser.parse(filename, f) }
+    end
+    
+  end
+end

data/lib/tchart/process/items_parser.rb

@@ -0,0 +1,156 @@
+require 'date'
+
+module TChart
+  
+  #
+  # Responsible for parsing a line of source data that contains either
+  # a separator or a data item.  Also responsible for accumulating 
+  # parsed items.
+  #
+  class ItemsParser
+   
+    #
+    # The collection of parsed items, where an item is either an instance
+    # of YItem or of Separator.  Starts empty and fills up with each 
+    # successive call to #parse.
+    #
+    attr_reader :items
+    
+    def initialize
+      @items = []
+    end
+    
+    def parse(line)
+      description, style, *date_range_strings = extract_fields(line)
+      raise_description_missing if description.nil?
+      raise_style_missing if style.nil? && date_range_strings.length > 0
+      if description.start_with?("---")
+        parse_separator
+      else
+        parse_y_item(description, style, date_range_strings)
+      end
+    end
+    
+  private
+    
+    def parse_y_item(description, style, date_range_strings)
+      date_ranges = parse_date_ranges(date_range_strings)
+      check_for_overlaps(date_ranges)
+      save_item YItem.new(description, style, date_ranges)
+    end
+    
+    def parse_separator
+      save_item Separator.new
+    end
+    
+    def save_item(item)
+      @items << item
+    end
+    
+    #
+    # 'a|b\|c|d | | e | \n' => [ 'a', 'b|c', 'd', nil, 'e' ]
+    #
+    def extract_fields(line) # => [ String, ... ]
+      line                                              # => 'a|b\|c|d | | e | ' + "\n"
+        .sub( /(\s|\|)+$/, '' )                         # => 'a|b\|c|d | | e'
+        .split( /(?<!\\)\|/ )                           # => [ 'a', 'b\|c', 'd ', ' ', ' e' ]
+        .map { |field| remove_escapes(field) }          # => [ 'a', 'b|c', 'd', ' ', 'e' ]
+        .map { |field| field.strip }                    # => [ 'a', 'b|c', 'd', '', 'e' ]
+        .map { |field| field.empty? ? nil : field }     # => [ 'a', 'b|c', 'd', nil, 'e' ]
+    end
+    
+    #
+    # '\a\\b' => 'a\b'
+    #
+    def remove_escapes(line) # => String
+      line.gsub(/\\(.)/, '\1')
+    end
+    
+    def parse_date_ranges(date_range_strings) # => [ Date..Date, ... ]
+      date_range_strings.map { |date_range_string| parse_date_range(date_range_string) }
+    end
+    
+    def parse_date_range(date_range_string) # => Date..Date
+      y1, m1, d1, y2, m2, d2 = fill_in_missing_date_elements( * match_date_range(date_range_string) )
+      date_begin = build_date(y1.to_i, m1.to_i, d1.to_i)
+      date_end = build_date(y2.to_i, m2.to_i, d2.to_i)
+      raise_date_range_reversed(date_begin, date_end) if date_end < date_begin
+      date_begin..date_end
+    end
+    
+    def build_date(year, month, day) # => Date
+      Date.new(year, month, day)
+    rescue ArgumentError => e
+      raise_invalid_date(year, month, day, e.message)
+    end
+    
+    #
+    # Matches d, d-d, or d - d, where d can be: y, y.m, or y.m.d
+    # Examples: 2000, 2000-2001, 2000-2001.8, 2000.4.17 - 2001
+    #
+    def match_date_range(date_range_string) # => y1, m1, d1, y2, m2, d2
+      m = /^(\d+)(\.(\d+)(\.(\d+))?)?(\s*-\s*(\d+)(\.(\d+)(\.(\d+))?)?)?$/.match(date_range_string)
+      raise_invalid_date_range(date_range_string) if not m
+      [ m[1], m[3], m[5], m[7], m[9], m[11] ]
+    end
+    
+    def fill_in_missing_date_elements(y1, m1, d1, y2, m2, d2) # => y1, m1, d1, y2, m2, d2
+      [ y1, m1 || 1, d1 || 1, 
+        y2 || y1, m2 || 12, d2 || -1 ]
+    end
+    
+    def check_for_overlaps(date_ranges)
+      first, *rest = date_ranges
+      return if rest.empty?
+      rest.each { |range| raise_date_ranges_overlap(first, range) if overlap?(first, range) }
+      check_for_overlaps(rest)
+    end
+    
+    def overlap?(range1, range2)
+      range1.include?(range2.first) or range2.include?(range1.first)
+    end
+    
+    def raise_description_missing
+      raise TChartError, "description is missing"
+    end
+
+    def raise_style_missing
+      raise TChartError, "style is missing"
+    end
+    
+    def raise_invalid_date(year, month, day, message)
+      raise TChartError, "#{year}.#{month}.#{day}: #{message}"
+    end
+    
+    def raise_invalid_date_range(date_range_as_string)
+      raise TChartError, "bad date range \"#{date_range_as_string}\"; expecting 2000.4.17-2001.7.21 | 2002.4-2003, etc."
+    end
+    
+    def raise_date_range_reversed(date_begin, date_end)
+      raise TChartError, "date range end #{d2s(date_end)} before start #{d2s(date_begin)}"
+    end
+    
+    def raise_date_ranges_overlap(range1, range2)
+      raise TChartError, "date range #{dr2s(range1)} overlaps #{dr2s(range2)}"
+    end
+    
+    #
+    # 'd2s' means 'date to string'
+    #
+    # 2001.3.17 => "2001.3.17"
+    #
+    def d2s(date) # => String
+      date.strftime('%Y.%-m.%-d')
+    end
+    
+    #
+    # 'dr2s' means 'date range to string'
+    #
+    # 2003.3.17..2007.11.2 => "2003.3.17-2007.11.2"
+    #
+    def dr2s(date_range) # => String
+      "#{d2s(date_range.begin)}-#{d2s(date_range.end)}"
+    end
+    
+  end
+end

data/lib/tchart/process/layout_builder.rb

@@ -0,0 +1,106 @@
+module TChart
+  
+  #
+  # Responsible for calculating chart metrics and storing them
+  # in an instance of Layout.  Metrics depend on chart settings
+  # and the number and dates ranges of the items being plotted.
+  #
+  class LayoutBuilder
+   
+    def self.build(settings, items) # => [ layout, errors ]
+      layout = build_layout(settings, items)
+      errors = check_layout(layout)
+      [ layout, errors ]
+    end
+
+  private
+  
+    def self.build_layout(settings, items) # => Layout
+      layout = Layout.new
+      layout.x_axis_tick_dates = calc_x_axis_tick_dates( *calc_items_date_range(items) )
+      layout.x_axis_length = calc_x_axis_length(settings)
+      layout.x_axis_tick_x_coordinates = calc_x_axis_tick_x_coordinates(layout.x_axis_tick_dates, layout.x_axis_length)
+      layout.y_axis_length = calc_y_axis_length(settings, items)
+      layout.y_axis_label_x_coordinate = calc_y_axis_label_x_coordinate(settings)
+      layout.y_axis_tick_y_coordinates = calc_y_axis_tick_y_coordinates(settings, items)
+      layout.x_axis_label_y_coordinate = settings.x_axis_label_y_coordinate
+      layout.x_axis_label_width = settings.x_axis_label_width
+      layout.y_axis_label_width = settings.y_axis_label_width
+      layout
+    end
+    
+    def self.check_layout(layout) # => [ String, String, ... ]
+      errors = []
+      errors << plot_area_too_narrow_error(layout.x_axis_length) if layout.x_axis_length < 1
+      errors
+    end
+    
+    def self.plot_area_too_narrow_error(x_axis_length)
+      "plot area is too narrow (#{x_axis_length}, min is 1); is chart_width too small, or x_axis_label_width or y_axis_label_width too large?"
+    end
+  
+    def self.calc_items_date_range(items) # [ Date, Date ]
+      earliest, latest = nil, nil
+      items.each do |item|
+        item.date_ranges.each do |date_range|
+          earliest = date_range.begin if earliest.nil? or date_range.begin < earliest
+          latest = date_range.end if latest.nil? or latest < date_range.end
+        end
+      end
+      current_year = Date.today.year
+      earliest ||= Date.new(current_year, 1, 1)
+      latest ||= Date.new(current_year, 12, 31)
+      [earliest, latest]
+    end
+  
+    def self.calc_x_axis_tick_dates(earliest, latest) # => [ Date, Date, ... ]
+      # if ten or fewer years to cover, create a tick every year
+      from_year = earliest.year                         # round down to Jan 1st of year
+      to_year = latest.year + 1                         # +1 to round up to Jan 1st of the following year
+      return make_tick_dates(from_year, to_year, 1) if to_year - from_year <= 10
+
+      # if fifty or fewer years to cover, create a tick every five years
+      from_year = (from_year / 5.0).floor * 5           # round down to nearest 1/2 decade
+      to_year = (to_year / 5.0).ceil * 5                # round up to nearest 1/2 decade
+      return make_tick_dates(from_year, to_year, 5) if to_year - from_year <= 50
+
+      # create a tick every ten years
+      from_year = (from_year / 10.0).floor * 10         # round down to nearest decade
+      to_year = (to_year / 10.0).ceil * 10              # round up to nearest decade
+      return make_tick_dates(from_year, to_year, 10)
+    end
+    
+    def self.make_tick_dates(from_year, to_year, interval) # => [ Date, Date, ... ]
+      (from_year..to_year).step(interval).map { |year| Date.new(year,1,1) }
+    end
+  
+    def self.calc_x_axis_tick_x_coordinates(x_axis_tick_dates, x_axis_length) # => [ Numeric, Numeric, ... ]
+      num_coords = x_axis_tick_dates.size
+      x_interval = x_axis_length / (num_coords - 1.0)
+      (0..x_axis_length).step(x_interval).to_a
+    end
+      
+    #
+    # 1/2 x_axis_label_width for the left margin, and 1/2 x_axis_label_width for the right margin
+    #
+    def self.calc_x_axis_length(settings) # => Numeric
+      settings.chart_width - settings.y_axis_label_width - settings.x_axis_label_width
+    end
+    
+    #
+    # +1 for top and bottom margins, each of which is half the line height
+    #
+    def self.calc_y_axis_length(settings, items) # => Numeric
+      (items.length + 1) * settings.line_height
+    end
+    
+    def self.calc_y_axis_label_x_coordinate(settings) # => Numeric
+      0 - ((settings.y_axis_label_width / 2.0) + (settings.x_axis_label_width / 2.0))
+    end
+    
+    def self.calc_y_axis_tick_y_coordinates(settings, items) # => [ Numeric, Numeric, ... ]
+      (settings.line_height * items.length).step(settings.line_height, -settings.line_height).to_a
+    end
+    
+  end
+end