reportinator 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94a9663b55f56092c18cbb75fd7832823c7f80a20404575e168ffc7ef3c9bdb0
-  data.tar.gz: 367ffe4a9b45bbe04b8e5992d8495d4988bf590d81daee9f8959bba4b88013f7
+  metadata.gz: 1640b58d6109a19bdbf48ce1065c18cee4e026a0eb4e4fc0b983664258d3794d
+  data.tar.gz: '097529bb768d21517db8d511fa9b7b17c029c8a513bbdd95ee52e8d8e2747450'
 SHA512:
-  metadata.gz: 0d0a1cc0db797d02d212d33ec8fcbb50127d9d5801a92bddf0544505f4ffe903ebb4230e48114cf067c62e73e89ca5f64b91f90261ef41682244780c65c09975
-  data.tar.gz: 64de0d19db4a9bd0553de2abd6bd5426a5b68d4efdf872c7ec7a9ab353b9223bc2f0df6737fe5174a79f3a06d6c85091de172d75a42e5004ffb95694e22a6f82
+  metadata.gz: a8fc97d8d0d8ad6a780d25cd07ee87ef52960b9175be94f8b9cc6f8714921b5a489cfedd77a3546ad73b8dd68e61d918ef515d221b744427490c6c949a980bbb
+  data.tar.gz: 8b94e32337cf10a45ac0a699e729e1361d649a0122bf4e09696cee054fc45c3318a58d72b4394816f62313ae4ecef2f2e3e70c54dff7dd9654de463430c13210

data/CHANGELOG.md

@@ -1,4 +1,42 @@
-## [Unreleased]
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.2] 2022-11-24
+### Fixed
+- Reference to schema file
+
+## [0.3.1] 2022-11-24
+### Fixed
+- Add "json_schemer" to gem dependencies
+
+## [0.3.0] 2022-11-24
+### Added
+- Add template object
+- Report types can opt in to parsing the data themselves
+- Added "to_csv" method to report
+- Added ">string" array function
+- Added ">range" array function
+- Added ">sum" array function
+- Added "!nf" and "!ni" to convert a number to a float or integer
+- Added "snippets"
+- Added JSON Schema for report validation
+
+### Changed
+- Preset report now takes in a "values" array, rather than a "data" array
+- Refactor loader to be report loader
+- "variables" have now been moved to be underneath the "metadata" tag.
+- "metadata" is now passed to the Value parser instead of "variables"
+- Re-ordered changelog to be latest change first
+- Changelog now has KeepAChangelog info header
+
+### Fixed
+- The Method function now works with non-string targets
+
+## [0.2.0] - 2022-10-14
 ### Added
 - Added parser for true, false and nil ("@true", "@false", "@nil")
 - Escape parsed methods and values starting with a special character
@@ -17,6 +55,11 @@
 - Method Parser no longer ignores empty and nil results.
 - Model report no longer double-parses values.
 
+## [0.1.1] - 2022-10-06
+### Fixed
+- Move Base class to it's own file
+- Now uses require_rel rather than require_all
+
 ## [0.1.0] - 2022-10-06
 - Initial release
 
@@ -25,9 +68,4 @@
 - Method parser
 - Preset report type
 - Model report type
-- Readme with report tutorial
-
-## [0.1.1] - 2022-10-06
-### Fixed
-- Move Base class to it's own file
-- Now uses require_rel rather than require_all
+- Readme with report tutorial

data/Gemfile.lock

@@ -18,9 +18,17 @@ GEM
     ast (2.4.2)
     concurrent-ruby (1.1.10)
     diff-lcs (1.5.0)
+    ecma-re-validator (0.4.0)
+      regexp_parser (~> 2.2)
+    hana (1.3.7)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     json (2.6.2)
+    json_schemer (0.2.23)
+      ecma-re-validator (~> 0.3)
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      uri_template (~> 0.7)
     minitest (5.16.3)
     parallel (1.22.1)
     parser (3.1.2.1)
@@ -65,11 +73,13 @@ GEM
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.3.0)
+    uri_template (0.7.0)
 
 PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  json_schemer (~> 0.2)
   rake (~> 13.0)
   reportinator!
   rspec (~> 3.0)

data/README.md

@@ -50,19 +50,33 @@ A Report template has four attributes:
 | key       | type   | description                                        |
 |-----------|--------|----------------------------------------------------|
 | type      | symbol | specifies the report type to use                   |
-| variables | hash   | defines variables to be used with the `$` function |
 | template  | string | references another template to load and merge with |
+| metadata  | hash   | values accessible to parser functions              |
 | params    | hash   | report specific parameters                         |
 
-#### Reportinator String Function Cheatsheet
+Values in report templates are passed through the value parser.
+There are two main types of functions that can be parsed. String functions, and
+array functions.
+
+String functions return a value based on the contents of a string input.
+They are useful for quick conversions, and simple functions.
+
+Array functions return a value based on the contents of an array.
+They are used for more complex functions, as more can be expressed with them.
+The values in an array function are usually also parsed, although it is at the discretion
+of the function do so.
+
+#### String Function Cheatsheet
 | prefix  | example                     | output                                     |
 |---------|-----------------------------|--------------------------------------------|
 | `:`     | ":symbol"                   | :symbol                                    |
 | `&`     | "&Constant"                 | Constant                                   |
-| `$`     | "$variable"                 | Value of key `variable` in variables hash. |
+| `$`     | "$variable"                 | Value `variable` in variables metadata.    |
 | `!a`    | "!a 1,2,3"                  | 6                                          |
 | `!d`    | "!d 1970-01-01"             | 1970-01-01 00:00:00                        |
 | `!n`    | "!n 100"                    | 100                                        |
+| `!ni`   | "!ni 103.34"                | 103                                        |
+| `!nf`   | "!nf 103"                   | 103.0                                      |
 | `!j`    | "!j 1,2,3"                  | "123"                                      |
 | `!r`    | "!r a,z"                    | ("a".."z")                                 |
 | `!rd`   | "!rd 1970-01-01,1979-01-01" | (1970-01-01 00:00:00..1979-01-01 00:00:00) |
@@ -72,9 +86,9 @@ A Report template has four attributes:
 | `@nil`  | "@nil"                      | nil                                        |
 | `@null` | "@null"                     | nil                                        |
 
-#### Reportinator Array Function Cheatsheet
-When an array has a string as it's first value, and that string has a certain prefix
-the array is parsed as an Array Function.
+#### Array Function Cheatsheet
+When an array has a string as it's first value, and that string has a certain prefix,
+the given array is parsed as an Array Function.
 
 Array functions have a target, then an array of values. Often, the values will work
 with the target to achieve an outcome.
@@ -95,7 +109,8 @@ are parsed, and sent as methods to it. The result is returned.
 This array is equivalent to running `Date.today.to_s`.
 
 Optionally, the prefix can be put on it's own, with no additional values
-after it.
+after it. The second value, in this case "&Date", will become the target
+instead.
 ```
 ["#", "&Date", ":today", ":to_s"]
 ```
@@ -106,13 +121,76 @@ to be more flexible, as it no longer has to be resolved from a string.
 ```
 This array is equally valid, and still returns the same result.
 
- prefix    | example                                        | ruby equivalent                         |
------------|------------------------------------------------|-----------------------------------------|
- `#`       | `["#&Date", ":today"]`                         | Date.today                              |
- `>join`   | `[">join", " - ", "a", "b", "c"]`              | ["a", "b", "c"].join(" - ")             |
- `>strf`   | `[">strf", ["#&Date", ":today"], "%b, %Y"]`    | Date.today.strftime("%b, %Y")           |
- `>offset` | `[">offset $time", 2, ":month", ":end"]`       | $time.advance(month: 2).at_end_of_month |
- `>title`  | `[">title", "hello", "world"]`                 | ["hello", "world"].join(" ").titleize   |
+| prefix    | example                                        | ruby equivalent                         |
+|-----------|------------------------------------------------|-----------------------------------------|
+| `#`       | `["#&Date", ":today"]`                         | Date.today                              |
+| `>join`   | `[">join", " - ", "a", "b", "c"]`              | ["a", "b", "c"].join(" - ")             |
+| `>strf`   | `[">strf", ["#&Date", ":today"], "%b, %Y"]`    | Date.today.strftime("%b, %Y")           |
+| `>offset` | `[">offset $time", 2, ":month", ":end"]`       | $time.advance(month: 2).at_end_of_month |
+| `>title`  | `[">title", "hello", "world"]`                 | ["hello", "world"].join(" ").titleize   |
+| `>snippet`| `[">snippet :test", {"var1": "hi"}]`           | *See snippets section*                  |
+
+
+### Metadata
+Metadata is defined in the "metadata" field of the template, and can be used by Parser Functions.
+Metadata is merged from parent to child report template. Child metadata takes precedence over parent.
+
+Reportinator's built in Parser Functions use two metadata fields; "variables", and "snippets".
+
+#### Variables
+Variables are values that can be accessed with the "$" string function.
+
+```
+"metadata": {
+  "variables": {
+    "key": "value"
+  }
+}
+```
+```
+> Reportinator.parse "$key"
+=> "value"
+```
+
+Variable values are also parsed, and themselves can even reference variables from parent templates.
+
+```
+# $date = 1970-01-01
+"metadata": {
+  "variables": {
+    "formatted_date": [">strf", "$date", "%b %d, %Y"]
+  }
+}
+```
+```
+> Reportinator.parse "$formatted_date"
+=> "Jan 01, 1970"
+```
+
+#### Snippets
+Snippets are values that are not parsed until called from the ">snippet" array function,
+as opposed to variables, which are parsed before they are able to be called.
+
+Snippets can be passed variables with a hash in the first value of the array function.
+
+Example:
+```
+"metadata": {
+  "snippets": {
+    "plus_10": [">sum", "$var", 10]
+  }
+}
+```
+```
+> Reportinator.parse [">snippet :plus_10", { "var": 5 }]
+=> 15
+```
+
+Snippets help to reduce repetition of complex functionality in a report.
+However, if a report is getting unwieldy with complex values to parse, it might
+be a good idea to write a Custom Parser Function, or to write it into a method
+on a class, and call it from a "&Constant". See the next section for setting up
+custom functions.
 
 ### Configuring Reportinator
 ```
@@ -135,16 +213,27 @@ of the reports.
 ### Making a Custom Report Type
 The requirements to make a Report are very simple.
 1. The report must inherit from `Reportinator::Report`
-2. The report must provide a `data` method, which returns a one or two dimensional array.
+2. The report should provide some attributes, to be set with the "params" field,
+3. The report must provide a `data` method, which returns either a Reportinator::Row,
+or an array of them.
 
-For example, this is the entire code for the Preset Report:
+Here's an example of a basic report type:
 ```
-module Reportinator
-    class PresetReport < Report
-        attribute :data, default: []
-    end
+class BasicReport < Reportinator::Report
+  attribute :values, default: []
+
+  def data
+    Reportinator::Row.create(values)
+  end
 end
 ```
+
+`Reportinator::Row.create` takes in an array, and turns it into a Row.
+For more fine-grained control, an instance of a Row can have data
+inserted into it with the `insert` method. `insert` takes any data, then
+a position, being either :first, :last, or an index number, to indicate where in
+the row the data should be inserted.
+
 Once a report has been written, it must be registed as a report type.
 See the configuration section for more details.
 
@@ -155,11 +244,13 @@ or "Reportinator::ArrayFunction"
 2. The function must have a PREFIXES constant, with an array of the prefixes it'll accept.
 3. The function must provide an `output` method
 
-String functions gain access to two variables:
+All functions have access to the `metadata` variable.
+
+String functions gain access to two additional variables:
 - `prefix`, the prefix that the string used
 - `body`, the rest of the string with the prefix removed
 
-Array functions gain access to three variables:
+Array functions gain access to three additional variables:
 - `prefix`, the prefix that was used
 - `target`, the first value after the prefix
 - `values`, the rest of the values, with the target removed

data/app/reports/example.report.json

@@ -1,9 +1,13 @@
 [
   {
     "type": ":preset",
-    "variables": {"variable": "i am a variable"},
+    "metadata": {
+      "variables": {
+        "variable": "i am a variable"
+      }
+    },
     "params": {
-      "data": [
+      "values": [
         "string", ":symbol", "&Reportinator",
         "$variable", "!i 1234", "!a !i 2, 2",
         ["#!d 1970-01-01", {"strftime": "%b, %Y"}], "!r !i 1, !i 5"
@@ -13,7 +17,7 @@
   {
     "type": ":model",
     "params": {
-      "target": ["#&Reportinator", ":config"],
+      "target": ["#", "&Reportinator", ":config"],
       "method_list": [":configured_directories", ":configured_suffixes", ":configured_types"]
     }
   }

data/app/reports/multiplication.report.json

@@ -2,7 +2,7 @@
   {
     "type": ":preset",
     "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+      "values": ["nx1","nx2","nx3","nx4","nx5"]   
     }
   },
   {

data/app/reports/multiplication_v2.report.json

@@ -0,0 +1,15 @@
+[
+  {
+    "type": ":preset",
+    "params": {
+      "values": ["5x5","nx1","nx2","nx3","nx4","nx5"]   
+    }
+  },
+  {
+    "type": ":model",
+    "params": {
+      "target": "!rn 1,5",
+      "method_list": [[">join", "x", "$target", "n"],{"*": 1},{"*": 2},{"*": 3},{"*": 4},{"*": 5}]
+    }
+  }
+]

data/data/schema/report_schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://moxvallix.com/meta/reportinator/report_schema.json",
+  "title": "Report",
+  "description": "A Reportinator Report",
+  "type": ["array", "object"],
+  "$defs": {
+    "template": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": ["string", "array"]
+        },
+        "template": {
+          "type": ["string", "array"]
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "snippets": {
+              "type": "object"
+            },
+            "variables": {
+              "type": "object"
+            }
+          }
+        },
+        "params": {
+          "type": "object"
+        }
+      },
+      "oneOf": [
+        {
+          "required": ["type"]
+        },
+        {
+          "required": ["template"]
+        }
+      ],
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": ":preset" } }
+          },
+          "then": {
+            "properties": { "params": { "properties": { "values": { "type": "array" } } } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": ":model" } }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "properties": {
+                  "target": { "type": ["string", "array"] },
+                  "method_list": { "type": "array" }
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "if": {
+    "type": "object"
+  },
+  "then": {
+    "$ref": "#/$defs/template"
+  },
+  "else": {
+    "properties": { "items": { "$ref": "#/$defs/template" } }
+  }
+}

data/docs/0_first_report.md

@@ -31,7 +31,7 @@ Add "data" to a "params" object, and set it to be an empty array.
 {
   "type": ":preset",
   "params": {
-    "data": []   
+    "values": []   
   }
 }
 ```
@@ -50,7 +50,7 @@ Let's now add some data to this bad boy.
 {
   "type": ":preset",
   "params": {
-    "data": ["nx1","nx2","nx3","nx4","nx5"]
+    "values": ["nx1","nx2","nx3","nx4","nx5"]
   }
 }
 ```
@@ -59,13 +59,13 @@ Let's now add some data to this bad boy.
 => [["nx1", "nx2", "nx3", "nx4", "nx5"]]
 ```
 
-Now we could add the other rows ourselves, by adding more rows to "data":
+Now we could add the other rows ourselves, by adding more rows to "values":
 
 ```
 {
   "type": ":preset",
   "params": {
-    "data": [
+    "values": [
       ["nx1","nx2","nx3","nx4","nx5"],
       [1, 2, 3, 4, 5],
       [2, 4, 6, 8, 10],
@@ -98,7 +98,7 @@ This allows us to string reports together in the same template.
   {
     "type": ":preset",
     "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+      "values": ["nx1","nx2","nx3","nx4","nx5"]   
     }
   }
 ]
@@ -119,7 +119,7 @@ Set both to be an empty array.
   {
     "type": ":preset",
     "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+      "values": ["nx1","nx2","nx3","nx4","nx5"]   
     }
   },
   {
@@ -174,7 +174,7 @@ Using this, we can write a much smarter report.
   {
     "type": ":preset",
     "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]   
+      "values": ["nx1","nx2","nx3","nx4","nx5"]   
     }
   },
   {
@@ -242,7 +242,7 @@ Let's add this now as the target of our report:
   {
     "type": ":preset",
     "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]
+      "values": ["nx1","nx2","nx3","nx4","nx5"]
     }
   },
   {

data/lib/reportinator/base.rb

@@ -2,9 +2,10 @@ module Reportinator
   class Base
     include ActiveModel::API
     include ActiveModel::Attributes
-
     require_rel "."
 
+    include Helpers
+
     def self.config
       Reportinator.config
     end

data/lib/reportinator/config.rb

@@ -9,6 +9,10 @@ module Reportinator
     DEFAULT_FUNCTIONS = [
       "Reportinator::HelperArrayFunction",
       "Reportinator::JoinArrayFunction",
+      "Reportinator::RangeArrayFunction",
+      "Reportinator::StringArrayFunction",
+      "Reportinator::SnippetArrayFunction",
+      "Reportinator::FlattenArrayFunction",
       "Reportinator::MethodArrayFunction",
       "Reportinator::AdditionStringFunction",
       "Reportinator::ConstantStringFunction",
@@ -20,11 +24,13 @@ module Reportinator
       "Reportinator::SymbolStringFunction",
       "Reportinator::VariableStringFunction"
     ]
+    DEFAULT_UNPARSEDS = [:snippets]
 
     attribute :report_directories, default: []
     attribute :report_suffixes, default: []
     attribute :report_types, default: {}
     attribute :parser_functions, default: []
+    attribute :unparsed_metadata, default: []
     attribute :output_directory, default: "reports"
 
     def configured_directories
@@ -44,5 +50,9 @@ module Reportinator
       functions = DEFAULT_FUNCTIONS + parser_functions
       functions.map { |function| function.constantize }
     end
+
+    def configured_metadata
+      DEFAULT_UNPARSEDS + unparsed_metadata
+    end
   end
 end

data/lib/reportinator/function.rb

@@ -1,18 +1,18 @@
 module Reportinator
   class Function < Base
     attribute :element
-    attribute :variables, default: {}
+    attribute :metadata, default: {}
 
-    def self.parse(element, variables = {})
-      new(element: element, variables: variables).get
+    def self.parse(element, metadata = {})
+      new(element: element, metadata: metadata).get
     end
 
     def parse_value(value)
-      ValueParser.parse(value, variables)
+      ValueParser.parse(value, metadata)
     end
 
     def parse_and_execute_value(target, value)
-      ValueParser.parse_and_execute(target, value, variables)
+      ValueParser.parse_and_execute(target, value, metadata)
     end
 
     def prefixes

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

@@ -0,0 +1,12 @@
+module Reportinator
+  class FlattenArrayFunction < ArrayFunction
+    PREFIXES = [">flatten"]
+
+    def output
+      array = []
+      array.append parse_value(target)
+      array.append parse_value(values)
+      array.flatten
+    end
+  end
+end

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

@@ -1,6 +1,6 @@
 module Reportinator
   class HelperArrayFunction < ArrayFunction
-    PREFIXES = [">strf", ">offset", ">title"]
+    PREFIXES = [">strf", ">offset", ">title", ">sum"]
 
     INTERVALS = {
       days: {start: "at_beginning_of_day", end: "at_end_of_day"},
@@ -15,6 +15,7 @@ module Reportinator
       return parse_strftime if prefix == ">strf"
       return parse_offset if prefix == ">offset"
       return parse_title if prefix == ">title"
+      return parse_sum if prefix == ">sum"
       element
     end
 
@@ -55,6 +56,11 @@ module Reportinator
       to_join.join(" ").titleize
     end
 
+    def parse_sum
+      sum_values = parsed_values.append parsed_target
+      sum_values.sum { |value| parse_value("!n #{value}") }
+    end
+
     def parsed_target
       @parsed_target ||= parse_target
     end

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

@@ -3,7 +3,7 @@ module Reportinator
     PREFIXES = [">join"]
 
     def output
-      joiner = ValueParser.parse(target, variables)
+      joiner = parse_value(target)
       joiner = (joiner.instance_of?(String) ? joiner : target)
       values.map { |value| parse_value(value) }.join(joiner)
     end

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

@@ -0,0 +1,11 @@
+module Reportinator
+  class RangeArrayFunction < ArrayFunction
+    PREFIXES = [">range"]
+
+    def output
+      start_value = parse_value(target)
+      end_value = parse_value(values[0])
+      (start_value..end_value)
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Reportinator
+  class SnippetArrayFunction < ArrayFunction
+    PREFIXES = [">snippet"]
+
+    def output
+      name = target
+      name.strip! if name.instance_of? String
+      parsed_name = parse_value(name)
+      snippet = find_snippet(parsed_name)
+      return "Missing Snippet" unless snippet.present?
+      parse_snippet(snippet)
+    end
+
+    def find_snippet(name)
+      snippets = metadata[:snippets]
+      return false unless snippets.present?
+      return false unless snippets[name].present?
+      snippets[name]
+    end
+
+    def parse_snippet(snippet)
+      snippet_metadata = metadata.dup
+      snippet_metadata.delete :snippets
+      variables = values[0]
+      parsed_variables = parse_value(variables)
+      input_metadata = merge_hash(snippet_metadata, {variables: parsed_variables})
+      ValueParser.parse(snippet, input_metadata)
+    end
+  end
+end