reportinator 0.1.0 → 0.2.0

data/docs/0_first_report.md

@@ -0,0 +1,267 @@
+# Creating my First Report
+Let's start by considering what we want our output to be.
+Say we want a multiplication table, like such:
+| nx1 | nx2 | nx3 | nx4 | nx5 |
+|-----|-----|-----|-----|-----|
+|   1 |   2 |   3 |   4 |   5 |
+|   2 |   4 |   6 |   8 |  10 |
+|   3 |   6 |   9 |  12 |  15 |
+|   4 |   8 |  12 |  16 |  20 |
+|   5 |  10 |  15 |  20 |  25 |
+
+Make a new file in your `app/reports` directory.
+Name it `multiplication.report.json`
+
+Set it's type to ":preset". The ":preset" type takes one parameter, "data",
+and returns any values passed inside it, but with their values parsed.
+We put a colon in front of the word "preset", such that the value parser
+knows to turn it into a symbol.
+
+```
+{
+  "type": ":preset"
+}
+```
+
+Next we need to give it parameters to be passed into the report.
+":preset" only accepts the "data" parameter.
+Add "data" to a "params" object, and set it to be an empty array.
+
+```
+{
+  "type": ":preset",
+  "params": {
+    "data": []   
+  }
+}
+```
+
+You can now try running this report:
+
+```
+> Reportinator.report("multiplication")
+=> []
+```
+
+If all went to plan, you should have gotten an empty array.
+Let's now add some data to this bad boy.
+
+```
+{
+  "type": ":preset",
+  "params": {
+    "data": ["nx1","nx2","nx3","nx4","nx5"]
+  }
+}
+```
+```
+> Reportinator.report("multiplication")
+=> [["nx1", "nx2", "nx3", "nx4", "nx5"]]
+```
+
+Now we could add the other rows ourselves, by adding more rows to "data":
+
+```
+{
+  "type": ":preset",
+  "params": {
+    "data": [
+      ["nx1","nx2","nx3","nx4","nx5"],
+      [1, 2, 3, 4, 5],
+      [2, 4, 6, 8, 10],
+      [3, 6, 9, 12, 15],
+      [4, 8, 12, 16, 20],
+      [5, 10, 15, 20, 25]
+    ]   
+  }
+}
+```
+```
+> Reportinator.report("multiplication")
+=> 
+[
+  ["nx1", "nx2", "nx3", "nx4", "nx5"],
+  [1, 2, 3, 4, 5],
+  [2, 4, 6, 8, 10],
+  [3, 6, 9, 12, 15],
+  [4, 8, 12, 16, 20],
+  [5, 10, 15, 20, 25]
+]
+```
+
+However, there is a cleaner way of doing this.
+Move your entire report object inside of an array.
+This allows us to string reports together in the same template.
+
+```
+[
+  {
+    "type": ":preset",
+    "params": {
+      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+    }
+  }
+]
+```
+
+Add a new report object underneath the first.
+This time, the type will be ":model".
+
+":model" reports take two parameters:
+  1. "target"
+  2. "method_list"
+
+Add both these keys to the "params" of the second report object.
+Set both to be an empty array.
+
+```
+[
+  {
+    "type": ":preset",
+    "params": {
+      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+    }
+  },
+  {
+    "type": ":model",
+    "params": {
+      "target": [],
+      "method_list": []
+    }
+  }
+]
+```
+
+Model reports take a target, as specified in "target", and run methods against it,
+specified in "method_list", saving the outputs of each to the row.
+
+If the target is enumerable, said methods will run on each enumeration of the target,
+each enumeration adding a new row to the report.
+
+A method is specified by either a symbol, array or hash.
+Lets take the string "100" as our target.
+
+If our method was to be `":reverse"`, it would be the same as running"
+
+```
+> "100".reverse
+=> "001"
+```
+
+We can chain methods using an array. For example: `[":reverse", ":to_i"]`
+
+```
+> "100".reverse.to_i
+=> 1
+```
+
+Methods inside a hash allow for parameters to be passed to the method.
+The value of the hash are passed as the parameters, and an array is passed
+as multiple parameters.
+
+Eg. `{"gsub": ["0", "1"]}`
+
+```
+> "100".gsub("0", "1")
+=> "111"
+```
+
+In Ruby, it turns out the multiplication "*" sign is a method.
+Using this, we can write a much smarter report.
+
+```
+[
+  {
+    "type": ":preset",
+    "params": {
+      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+    }
+  },
+  {
+    "type": ":model",
+    "params": {
+      "target": [1, 2, 3, 4, 5],
+      "method_list": [{"*": 1},{"*": 2},{"*": 3},{"*": 4},{"*": 5}]
+    }
+  }
+]
+```
+
+The "*" is behaving exactly the same way as our "gsub" example earlier.
+
+If we run our report again:
+
+```
+> Reportinator.report("multiplication")
+=> 
+[
+  ["nx1", "nx2", "nx3", "nx4", "nx5"],
+  [1, 2, 3, 4, 5],
+  [2, 4, 6, 8, 10],
+  [3, 6, 9, 12, 15],
+  [4, 8, 12, 16, 20],
+  [5, 10, 15, 20, 25]
+]
+```
+
+The result should be exactly the same.
+
+This is pretty good, but we can do better!
+Notice how the "target" was an array? As it is enumerable,
+we could run our methods against each element within it.
+
+But what if we wanted to have 10 rows? Or 50? Soon our array is going to get pretty long.
+
+This is where a range would be perfect. Set the start value to 1, the end to whatever number we need,
+and then we go from there.
+
+Unfortunately, we can't use a range in JSON.
+
+... or can we?
+
+Reportinator has a bunch of handy built in functions, for converting strings.
+We have already seen ":symbol" to make a string into a symbol.
+
+We won't explore all the functions now, but we will explore "!r".
+Or more specifically, "!rn", which auto converts strings into numbers as well.
+
+We can make a range simply by writing "!rn 1,5". It takes the number before the comma,
+as the start of the range, and the one after as the end.
+
+We can test this with the actual parse method:
+
+```
+> Reportinator.parse("!rn 1, 5")
+=> (1..5)
+```
+
+Let's add this now as the target of our report:
+
+```
+[
+  {
+    "type": ":preset",
+    "params": {
+      "data": ["nx1","nx2","nx3","nx4","nx5"]
+    }
+  },
+  {
+    "type": ":model",
+    "params": {
+      "target": "!rn 1,5",
+      "method_list": [{"*": 1},{"*": 2},{"*": 3},{"*": 4},{"*": 5}]
+    }
+  }
+]
+```
+
+Finally, rather than peering at the console to see if it worked,
+lets put it into a csv.
+
+```
+> Reportinator.output("multiplication.csv","multiplication")
+=> "multiplication.csv"
+```
+
+Open the csv up in your spreadsheet viewer of choice, and revel
+in your brand new report!

data/lib/reportinator/base.rb

@@ -0,0 +1,24 @@
+module Reportinator
+  class Base
+    include ActiveModel::API
+    include ActiveModel::Attributes
+
+    require_rel "."
+
+    def self.config
+      Reportinator.config
+    end
+
+    def config
+      self.class.config
+    end
+
+    def self.logger
+      Reportinator.logger
+    end
+
+    def logger
+      self.class.logger
+    end
+  end
+end

data/lib/reportinator/config.rb

@@ -6,10 +6,25 @@ module Reportinator
     }
     DEFAULT_REPORT_DIRS = ["reports", "app/reports"]
     DEFAULT_REPORT_SUFFIXES = ["report.json", "json"]
+    DEFAULT_FUNCTIONS = [
+      "Reportinator::HelperArrayFunction",
+      "Reportinator::JoinArrayFunction",
+      "Reportinator::MethodArrayFunction",
+      "Reportinator::AdditionStringFunction",
+      "Reportinator::ConstantStringFunction",
+      "Reportinator::DateStringFunction",
+      "Reportinator::JoinStringFunction",
+      "Reportinator::LogicalStringFunction",
+      "Reportinator::NumberStringFunction",
+      "Reportinator::RangeStringFunction",
+      "Reportinator::SymbolStringFunction",
+      "Reportinator::VariableStringFunction"
+    ]
 
     attribute :report_directories, default: []
     attribute :report_suffixes, default: []
     attribute :report_types, default: {}
+    attribute :parser_functions, default: []
     attribute :output_directory, default: "reports"
 
     def configured_directories
@@ -24,5 +39,10 @@ module Reportinator
       types = DEFAULT_TYPES
       types.merge(report_types)
     end
+
+    def configured_functions
+      functions = DEFAULT_FUNCTIONS + parser_functions
+      functions.map { |function| function.constantize }
+    end
   end
 end

data/lib/reportinator/function.rb

@@ -0,0 +1,33 @@
+module Reportinator
+  class Function < Base
+    attribute :element
+    attribute :variables, default: {}
+
+    def self.parse(element, variables = {})
+      new(element: element, variables: variables).get
+    end
+
+    def parse_value(value)
+      ValueParser.parse(value, variables)
+    end
+
+    def parse_and_execute_value(target, value)
+      ValueParser.parse_and_execute(target, value, variables)
+    end
+
+    def prefixes
+      self.class::PREFIXES
+    end
+
+    private
+
+    def get_prefix(value)
+      raise "Value is not a string" unless value.instance_of? String
+      sorted_prefixes = prefixes.sort.reverse
+      sorted_prefixes.each do |prefix|
+        return prefix if value.start_with? prefix
+      end
+      raise "Value #{value} is incompatible with this function!"
+    end
+  end
+end

data/lib/reportinator/functions/array/helper.rb

@@ -0,0 +1,71 @@
+module Reportinator
+  class HelperArrayFunction < ArrayFunction
+    PREFIXES = [">strf", ">offset", ">title"]
+
+    INTERVALS = {
+      days: {start: "at_beginning_of_day", end: "at_end_of_day"},
+      weeks: {start: "at_beginning_of_week", end: "at_end_of_week"},
+      months: {start: "at_beginning_of_month", end: "at_end_of_month"},
+      years: {start: "at_beginning_of_year", end: "at_end_of_year"}
+    }
+
+    attr_writer :parsed_target, :parsed_values
+
+    def output
+      return parse_strftime if prefix == ">strf"
+      return parse_offset if prefix == ">offset"
+      return parse_title if prefix == ">title"
+      element
+    end
+
+    def target_to_time
+      parsed_target.to_s.to_time
+    end
+
+    def parse_strftime
+      time = target_to_time
+      return "Invalid Time" if time.nil?
+      return "Invalid Format" unless parsed_values[0].instance_of? String
+      time.strftime parsed_values[0]
+    end
+
+    def parse_offset
+      time = target_to_time
+      return "Invalid Time" if time.nil?
+      offset = parsed_values[0]
+      return "Missing Offset" unless offset.present?
+      interval = parsed_values[1]
+      snap = parsed_values[2]
+      calculate_offset(time, offset, interval, snap)
+    end
+
+    def calculate_offset(time, offset, interval, snap)
+      interval = (interval.present? ? interval : :months)
+      interval = interval.to_s.pluralize.to_sym
+      return "Invalid Interval" unless INTERVALS.include? interval
+      interval_data = INTERVALS[interval]
+      snap = false unless interval_data.include? snap
+      output = time.advance({interval => offset})
+      output = output.send(interval_data[snap]) if snap.present?
+      output
+    end
+
+    def parse_title
+      to_join = [parsed_target] + parsed_values
+      to_join.join(" ").titleize
+    end
+
+    def parsed_target
+      @parsed_target ||= parse_target
+    end
+
+    def parse_target
+      formatted_target = (target.instance_of?(String) ? target.strip : target)
+      parse_value(formatted_target)
+    end
+
+    def parsed_values
+      @parsed_values ||= values.map { |value| parse_value(value) }
+    end
+  end
+end

data/lib/reportinator/functions/array/join.rb

@@ -0,0 +1,11 @@
+module Reportinator
+  class JoinArrayFunction < ArrayFunction
+    PREFIXES = [">join"]
+
+    def output
+      joiner = ValueParser.parse(target, variables)
+      joiner = (joiner.instance_of?(String) ? joiner : target)
+      values.map { |value| parse_value(value) }.join(joiner)
+    end
+  end
+end

data/lib/reportinator/functions/array/method.rb

@@ -0,0 +1,9 @@
+module Reportinator
+  class MethodArrayFunction < ArrayFunction
+    PREFIXES = ["#"]
+
+    def output
+      parse_and_execute_value(target, values)
+    end
+  end
+end

data/lib/reportinator/functions/array.rb

@@ -0,0 +1,43 @@
+module Reportinator
+  class ArrayFunction < Function
+    PREFIXES = []
+
+    attribute :prefix
+    attribute :target
+    attribute :values
+
+    def self.accepts? input
+      return false unless input.instance_of? Array
+      return false if self::PREFIXES.empty?
+      return false unless input[0].instance_of? String
+      self::PREFIXES.each do |prefix|
+        return true if input[0].start_with? prefix
+      end
+      false
+    end
+
+    def get
+      raise "Function missing output!" unless respond_to? :output
+      if set_attributes
+        output
+      else
+        element
+      end
+    end
+
+    def set_attributes
+      array = element
+      prefix = get_prefix(array[0])
+      target_value = array.delete_at(0).sub(prefix, "")
+      target_value = array.delete_at(0) if target_value.empty?
+      if target_value.to_s.empty?
+        false
+      else
+        self.prefix = prefix
+        self.target = target_value
+        self.values = array
+        true
+      end
+    end
+  end
+end

data/lib/reportinator/functions/string/addition.rb

@@ -0,0 +1,11 @@
+module Reportinator
+  class AdditionStringFunction < StringFunction
+    PREFIXES = ["!a"]
+
+    def output
+      values = body.split(",").map { |value| parse_value(value.strip) }
+      values.map! { |subvalue| NumberStringFunction.parse("!n #{subvalue}") }
+      values.sum(0)
+    end
+  end
+end

data/lib/reportinator/functions/string/constant.rb

@@ -0,0 +1,9 @@
+module Reportinator
+  class ConstantStringFunction < StringFunction
+    PREFIXES = ["&"]
+
+    def output
+      body.constantize
+    end
+  end
+end

data/lib/reportinator/functions/string/date.rb

@@ -0,0 +1,9 @@
+module Reportinator
+  class DateStringFunction < StringFunction
+    PREFIXES = ["!d"]
+
+    def output
+      Time.parse(body)
+    end
+  end
+end

data/lib/reportinator/functions/string/join.rb

@@ -0,0 +1,10 @@
+module Reportinator
+  class JoinStringFunction < StringFunction
+    PREFIXES = ["!j"]
+
+    def output
+      values = body.split(",").map { |value| parse_value(value.strip) }
+      values.join(" ")
+    end
+  end
+end

data/lib/reportinator/functions/string/logical.rb

@@ -0,0 +1,14 @@
+module Reportinator
+  class LogicalStringFunction < StringFunction
+    PREFIXES = ["@true", "@false", "@nil", "@null"]
+
+    def output
+      case prefix
+      when "@true" then true
+      when "@false" then false
+      when "@nil", "@null" then nil
+      else element
+      end
+    end
+  end
+end

data/lib/reportinator/functions/string/number.rb

@@ -0,0 +1,11 @@
+module Reportinator
+  class NumberStringFunction < StringFunction
+    PREFIXES = ["!n"]
+
+    def output
+      float = (body =~ /\d\.\d/)
+      return body.to_f if float.present?
+      body.to_i
+    end
+  end
+end

data/lib/reportinator/functions/string/range.rb

@@ -0,0 +1,14 @@
+module Reportinator
+  class RangeStringFunction < StringFunction
+    PREFIXES = ["!r", "!rd", "!rn"]
+
+    def output
+      values = body.split(",").map { |value| parse_value(value.strip) }
+      case prefix
+      when "!rn" then values.map! { |subvalue| NumberStringFunction.parse("!n #{subvalue}") }
+      when "!rd" then values.map! { |subvalue| DateStringFunction.parse("!d #{subvalue}") }
+      end
+      Range.new(*values)
+    end
+  end
+end

data/lib/reportinator/functions/string/symbol.rb

@@ -0,0 +1,9 @@
+module Reportinator
+  class SymbolStringFunction < StringFunction
+    PREFIXES = [":"]
+
+    def output
+      body.to_sym
+    end
+  end
+end

data/lib/reportinator/functions/string/variable.rb

@@ -0,0 +1,10 @@
+module Reportinator
+  class VariableStringFunction < StringFunction
+    PREFIXES = ["$"]
+
+    def output
+      return element unless variables.include? body.to_sym
+      variables[body.to_sym]
+    end
+  end
+end

data/lib/reportinator/functions/string.rb

@@ -0,0 +1,29 @@
+module Reportinator
+  class StringFunction < Function
+    PREFIXES = []
+
+    attribute :prefix
+    attribute :body
+
+    def self.accepts? input
+      return false unless input.instance_of? String
+      return false if self::PREFIXES.empty?
+      self::PREFIXES.each do |prefix|
+        return true if input.start_with? prefix
+      end
+      false
+    end
+
+    def get
+      raise "Function missing output!" unless respond_to? :output
+      set_attributes
+      output
+    end
+
+    def set_attributes
+      prefix = get_prefix(element)
+      self.prefix = prefix
+      self.body = element.sub(prefix, "")
+    end
+  end
+end

data/lib/reportinator/loader.rb

@@ -7,10 +7,13 @@ module Reportinator
 
     def self.data_from_template(template, additional_params = {})
       template_data = load_template(template, additional_params)
-      return split_rows(template_data.data) unless template_data.instance_of?(Array)
+      unless template_data.instance_of?(Array)
+        output = split_rows(template_data.data)
+        return ReportParser.parse(output)
+      end
       output = []
-      template_data.each { |report| output += report.data }
-      split_rows(output)
+      template_data.each { |report| output += split_rows(report.data) }
+      ReportParser.parse(output)
     end
 
     def self.load_template(template, additional_params = {})
@@ -24,6 +27,11 @@ module Reportinator
     end
 
     def self.load_singular(data, additional_params)
+      parent_variables = additional_params[:variables]
+      child_variables = data[:variables]
+      if child_variables.present?
+        data[:variables] = ValueParser.parse(child_variables, parent_variables)
+      end
       data.merge!(additional_params) { |key, old_value, new_value| merge_values(new_value, old_value) }
       filtered_data = filter_params(data, attribute_names)
       variables = filtered_data[:variables]

data/lib/reportinator/parser.rb

@@ -0,0 +1,25 @@
+module Reportinator
+  class Parser < Base
+    cattr_writer :prefix_list
+
+    def self.get_prefix_list
+      config.configured_functions.map { |function| function::PREFIXES }.flatten
+    end
+
+    def self.prefix_list
+      @prefix_list ||= get_prefix_list
+    end
+
+    def prefix_list
+      self.class.prefix_list
+    end
+
+    def escape_value(value)
+      return value unless value.is_a? String
+      prefix_list.each do |escape|
+        return value.prepend("?/") if value.strip.start_with?(escape)
+      end
+      value
+    end
+  end
+end