reportinator 0.1.1 → 0.3.2

data/README.md

@@ -18,334 +18,179 @@ 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.
+For a detailed walkthrough of creating your first report, see
+[Creating my First Report](docs/0_first_report.md)
 
-```
-{
-  "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.
+### Where to put my Reports?
+By default, Reportinator checks `app/reports` for reports.
+It checks for files named `*.json` and `*.report.json`
+More locations and suffixes can be added in the config.
 
-```
-{
-  "type": ":preset",
-  "params": {
-    "data": []   
-  }
-}
-```
+### Getting your Report's Output
+`Reportinator.report(template, params)` will output a two dimensional array.
+If you picture this as a table, each sub array is a row.
+`params` is optional.
 
-You can now try running this report:
+`Reportinator.output(template, params, filename)` will output the report to a csv,
+in the configured output directory.
+`params` and `filename` are optional.
 
-```
-> Reportinator.report("multiplication")
-=> []
-```
+Template is the name of the template file, minus the ".json" suffix.
+Here is how templates are resolved:
+- "profit" => "app/reports/profit.json"
+- "users/joined" => "app/reports/users/joined.json"
 
-If all went to plan, you should have gotten an empty array.
-Let's now add some data to this bad boy.
+Params is a hash, accepting the same keys as a template would.
+Params are merged with those provided by the template, overriding any conflicts.
 
-```
-{
-  "type": ":preset",
-  "params": {
-    "data": ["nx1","nx2","nx3","nx4","nx5"]
-  }
-}
-```
-```
-> Reportinator.report("multiplication")
-=> [["nx1", "nx2", "nx3", "nx4", "nx5"]]
-```
+### Reports in more detail
+#### The Report Template Object
+A Report template has four attributes:
 
-Now we could add the other rows ourselves, by adding more rows to "data":
+| key       | type   | description                                        |
+|-----------|--------|----------------------------------------------------|
+| type      | symbol | specifies the report type to use                   |
+| template  | string | references another template to load and merge with |
+| metadata  | hash   | values accessible to parser functions              |
+| params    | hash   | report specific parameters                         |
 
-```
-{
-  "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]
-]
-```
+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.
 
-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.
+String functions return a value based on the contents of a string input.
+They are useful for quick conversions, and simple functions.
 
-```
-[
-  {
-    "type": ":preset",
-    "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]   
-    }
-  }
-]
-```
+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.
 
-Add a new report object underneath the first.
-This time, the type will be ":model".
+#### String Function Cheatsheet
+| prefix  | example                     | output                                     |
+|---------|-----------------------------|--------------------------------------------|
+| `:`     | ":symbol"                   | :symbol                                    |
+| `&`     | "&Constant"                 | Constant                                   |
+| `$`     | "$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) |
+| `!rn`   | "!rn 1,100"                 | (1..100)                                   |
+| `@true` | "@true"                     | true                                       |
+| `@false`| "@false"                    | false                                      |
+| `@nil`  | "@nil"                      | nil                                        |
+| `@null` | "@null"                     | nil                                        |
 
-":model" reports take two parameters:
-  1. "target"
-  2. "method_list"
+#### 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.
 
-Add both these keys to the "params" of the second report object.
-Set both to be an empty array.
+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:
 ```
-[
-  {
-    "type": ":preset",
-    "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]   
-    }
-  },
-  {
-    "type": ":model",
-    "params": {
-      "target": [],
-      "method_list": []
-    }
-  }
-]
+["#&Date", ":today", ":to_s"]
 ```
+This array has the following
+- a prefix: `#`
+- a target: `&Date` (Date)
+- values: `[":today", ":to_s"]` ([:today, :to_s])
 
-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.
+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.
 
-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"
+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. The second value, in this case "&Date", will become the target
+instead.
 ```
-> "100".reverse
-=> "001"
+["#", "&Date", ":today", ":to_s"]
 ```
-
-We can chain methods using an array. For example: `[":reverse", ":to_i"]`
-
+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.
 ```
-> "100".reverse.to_i
-=> 1
+["#", ["#&Date", ":today"], ":to_s"]
 ```
+This array is equally valid, and still returns the same result.
 
-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.
+| 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*                  |
 
-Eg. `{"gsub": ["0", "1"]}`
 
-```
-> "100".gsub("0", "1")
-=> "111"
-```
+### 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".
 
-In Ruby, it turns out the multiplication "*" sign is a method.
-Using this, we can write a much smarter report.
+#### Variables
+Variables are values that can be accessed with the "$" string function.
 
 ```
-[
-  {
-    "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}]
-    }
+"metadata": {
+  "variables": {
+    "key": "value"
   }
-]
+}
 ```
-
-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]
-]
+> Reportinator.parse "$key"
+=> "value"
 ```
 
-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:
+Variable values are also parsed, and themselves can even reference variables from parent templates.
 
 ```
-> Reportinator::ValueParser.parse("!rn 1, 5")
-=> (1..5)
+# $date = 1970-01-01
+"metadata": {
+  "variables": {
+    "formatted_date": [">strf", "$date", "%b %d, %Y"]
+  }
+}
+```
+```
+> Reportinator.parse "$formatted_date"
+=> "Jan 01, 1970"
 ```
 
-Let's add this now as the target of our report:
+#### 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:
 ```
-[
-  {
-    "type": ":preset",
-    "params": {
-      "data": ["nx1","nx2","nx3","nx4","nx5"]
-    }
-  },
-  {
-    "type": ":model",
-    "params": {
-      "target": "!rn 1,5",
-      "method_list": [{"*": 1},{"*": 2},{"*": 3},{"*": 4},{"*": 5}]
-    }
+"metadata": {
+  "snippets": {
+    "plus_10": [">sum", "$var", 10]
   }
-]
+}
 ```
-
-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"
+> Reportinator.parse [">snippet :plus_10", { "var": 5 }]
+=> 15
 ```
 
-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)             |
-
-### Where to put my Reports?
-By default, Reportinator checks `app/reports` for reports.
-It checks for files named `*.json` and `*.report.json`
-More locations and suffixes can be added in the config.
-
-### Getting your Report's Output
-`Reportinator.report(template, params)` will output a two dimensional array.
-If you picture this as a table, each sub array is a row.
-`params` is optional.
-
-`Reportinator.output(template, params, filename)` will output the report to a csv,
-in the configured output directory.
-`params` and `filename` are optional.
-
-Template is the name of the template file, minus the ".json" suffix.
-Here is how templates are resolved:
-- "profit" => "app/reports/profit.json"
-- "users/joined" => "app/reports/users/joined.json"
-
-Params is a hash, accepting the same keys as a template would.
-Params are merged with those provided by the template, overriding any conflicts.
+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
 ```
@@ -356,6 +201,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.
@@ -365,19 +213,81 @@ 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.
 
+### 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
+
+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 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
+
+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 +296,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 +304,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).

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}]
+    }
+  }
+]