reportinator 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb46422febcfaac711a20fbb21418ed224bc22e59468e9295dfccdd0c7ca309e
-  data.tar.gz: afba11ce1ecc80668797392b5c24eeffc715d349b78f93fa7d6e7ea8dfdc096a
+  metadata.gz: 94a9663b55f56092c18cbb75fd7832823c7f80a20404575e168ffc7ef3c9bdb0
+  data.tar.gz: 367ffe4a9b45bbe04b8e5992d8495d4988bf590d81daee9f8959bba4b88013f7
 SHA512:
-  metadata.gz: 8c604e8d6b30dff8df130dd6af08fcbc7a6ee0a4bb4a9e3c39478e97f2d3a2bb073c4543dcd2f366c4a39b5b15c97925d64bcba4060ed344c4c95de616507d91
-  data.tar.gz: 678d1ed69042d72e8f0c146abcc0a55becb31a7961f034bb58d63a1f2999100443f13e91fd71129bcaab33616a1bc0361bbac7dd62ae5003c21159574c2c4ef0
+  metadata.gz: 0d0a1cc0db797d02d212d33ec8fcbb50127d9d5801a92bddf0544505f4ffe903ebb4230e48114cf067c62e73e89ca5f64b91f90261ef41682244780c65c09975
+  data.tar.gz: 64de0d19db4a9bd0553de2abd6bd5426a5b68d4efdf872c7ec7a9ab353b9223bc2f0df6737fe5174a79f3a06d6c85091de172d75a42e5004ffb95694e22a6f82

data/CHANGELOG.md

@@ -1,6 +1,23 @@
 ## [Unreleased]
+### Added
+- Added parser for true, false and nil ("@true", "@false", "@nil")
+- Escape parsed methods and values starting with a special character
+- Added Report parser
+- Added "!j" join function.
+- Added [">"] array helper functions.
+
+### Changed
+- Load from template method now parses the report through the Report parser.
+- Plain strings in the model report method list return as a string rather than nil
+- Arrays starting with a string containing only a hash attempt to use the second value as target
+- Improved Loader's row splitting.
+- Refactored Value parser, allowing for custom functions
 
-## [0.1.0] - 2022-10-04
+### Fixed
+- Method Parser no longer ignores empty and nil results.
+- Model report no longer double-parses values.
+
+## [0.1.0] - 2022-10-06
 - Initial release
 
 ### Added
@@ -8,4 +25,9 @@
 - Method parser
 - Preset report type
 - Model report type
-- Readme with report tutorial
+- 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    reportinator (0.1.0)
+    reportinator (0.2.0)
       activemodel (~> 7.0)
       require_all (~> 3.0)
 

data/README.md

@@ -18,312 +18,8 @@ If bundler is not being used to manage dependencies, install the gem by executin
     $ gem install reportinator
 
 ## Usage
-### 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::ValueParser.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!
-### Reports in more detail
-#### The Report Template Object
-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 |
-| params    | hash   | report specific parameters                         |
-
-#### Reportinator String Parse Cheatsheet
-| prefix | example                     | output                                     |
-|--------|-----------------------------|--------------------------------------------|
-| `:`    | ":symbol"                   | :symbol                                    |
-| `&`    | "&Constant"                 | Constant                                   |
-| `$`    | "$variable"                 | Value of key `variable` in variables hash. |
-| `!a`   | "!a 1,2,3"                  | 6                                          |
-| `!d`   | "!d 1970-01-01"             | 1970-01-01 00:00:00                        |
-| `!n`   | "!n 100"                    | 100                                        |
-| `!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) |
-| `!rn`  | "!rn 1,100"                 | (1..100)                                   |
-
-#### Reportinator Method Parse Cheatsheet
-When an array has a string as it's first value, and that string has the `#` prefix,
-that string is parsed, and the result becomes the target of the following methods.
-
-Hashes within the array take the first key in the hash as the method,
-and the first value as parameters for that method. If the first value
-is an array, each item in the array is sent as a seperate parameter.
-
-Subsequent symbols in the array are sent as methods to the target.
-| method array                                   | ruby equivalent               |
-|------------------------------------------------|-------------------------------|
-| `["#&Date", ":today"]`                         | Date.today                    |
-| `["#&Date", ":today", ":to_s"]`                | Date.today.to_s               |
-| `["#&Date", ":today", {"strftime": "%b, %Y"}]` | Date.today.strftime("%b, %Y") |
-| `["#&Range", {"new": [1,100]}]`                | Range.new(1, 100)             |
+For a detailed walkthrough of creating your first report, see
+[Creating my First Report](docs/0_first_report.md)
 
 ### Where to put my Reports?
 By default, Reportinator checks `app/reports` for reports.
@@ -347,6 +43,77 @@ Here is how templates are resolved:
 Params is a hash, accepting the same keys as a template would.
 Params are merged with those provided by the template, overriding any conflicts.
 
+### Reports in more detail
+#### The Report Template Object
+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 |
+| params    | hash   | report specific parameters                         |
+
+#### Reportinator String Function Cheatsheet
+| prefix  | example                     | output                                     |
+|---------|-----------------------------|--------------------------------------------|
+| `:`     | ":symbol"                   | :symbol                                    |
+| `&`     | "&Constant"                 | Constant                                   |
+| `$`     | "$variable"                 | Value of key `variable` in variables hash. |
+| `!a`    | "!a 1,2,3"                  | 6                                          |
+| `!d`    | "!d 1970-01-01"             | 1970-01-01 00:00:00                        |
+| `!n`    | "!n 100"                    | 100                                        |
+| `!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) |
+| `!rn`   | "!rn 1,100"                 | (1..100)                                   |
+| `@true` | "@true"                     | true                                       |
+| `@false`| "@false"                    | false                                      |
+| `@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 functions have a target, then an array of values. Often, the values will work
+with the target to achieve an outcome.
+
+Take for example this array:
+```
+["#&Date", ":today", ":to_s"]
+```
+This array has the following
+- a prefix: `#`
+- a target: `&Date` (Date)
+- values: `[":today", ":to_s"]` ([:today, :to_s])
+
+The `#` prefix tells the parser to run it as a Method Array.
+The target, `&Date`, is parsed, then the values `[":today", ":to_s"]`
+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.
+```
+["#", "&Date", ":today", ":to_s"]
+```
+This will still return the same result. Note that this allows the target
+to be more flexible, as it no longer has to be resolved from a string.
+```
+["#", ["#&Date", ":today"], ":to_s"]
+```
+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   |
+
 ### Configuring Reportinator
 ```
 Reportinator.configuration do |config|
@@ -356,6 +123,9 @@ Reportinator.configuration do |config|
     config.report_types = {
         my_type: "MyModule::MyReportType"
     }
+    config.parser_functions = [
+      "MyModule::MyParserFunction"
+    ]
 end
 ```
 Configuration set will not override the default configuration.
@@ -378,6 +148,55 @@ end
 Once a report has been written, it must be registed as a report type.
 See the configuration section for more details.
 
+### Making a Custom Parser Function
+The requirements to make a Parser Function are fairly simple:
+1. The function must inherit from either "Reportinator::StringFunction"
+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:
+- `prefix`, the prefix that the string used
+- `body`, the rest of the string with the prefix removed
+
+Array functions gain access to three variables:
+- `prefix`, the prefix that was used
+- `target`, the first value after the prefix
+- `values`, the rest of the values, with the target removed
+
+Once a function has been written, it must be registed as a parser function.
+See the configuration section for more details.
+
+#### Example String Function:
+```
+class TitleizeStringFunction < Reportinator::StringFunction
+  PREFIXES = ["!t"]
+
+  def output
+    body.titleize
+  end
+end
+```
+```
+> Reportinator.parse "!t hello world"
+=> "Hello World"
+```
+
+#### Example Array Function:
+```
+class TargetSumArrayFunction < Reportinator::ArrayFunction
+  PREFIXES = [">targetsum"]
+
+  def output
+    values.map { |value| value + target }
+  end
+end
+```
+```
+> Reportinator.parse [">targetsum", 10, 1, 2, 3]
+=> [11, 12, 13]
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -386,7 +205,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/reportinator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/reportinator/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/moxvallix/reportinator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/moxvallix/reportinator/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -394,4 +213,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Reportinator project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/reportinator/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Reportinator project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/moxvallix/reportinator/blob/master/CODE_OF_CONDUCT.md).