\r\n\r\n\r\n## Quick Start\r\n- install `$ npm install --save trool`\r\n\r\n- Open Excel, LibreOffice Calc, or some other spreadsheet tool of your choice.\r\n\r\n- A **Fact** is an instance-object or array of instance-objects, which you want to update based on\r\nconditions that may change over time. Create at least one decision-table on the spreadsheet so you\r\ncan update a fact.\r\n\r\n- You must follow the format closely for setting up a decision-table. Trool may throw errors if\r\nyou do not set things up correctly. The guide contains all the details for setting up a decision-table.\r\nYou can look at the screen-shot above if you want a quick glimpse on what decision-tables look like. \r\n\r\n- Export your spreadsheet as a CSV file. The rules for formatting the csv are the same as they are\r\nfor the `csvtojson` library. That's what Trool uses internally to convert the csv to a JSON object.\r\n\r\n- Create a new NodeJS program (preferably with TypeScript) and import the `trool` library at the top.\r\nInstantiate a new `trool` object and pass `true` to the constructor if you want to show logs while\r\nthe library updates your facts.\r\n\r\n```typescript\r\nimport Trool from 'trool';\r\n\r\nclass PriceCalculator {\r\n\r\n private trool: Trool;\r\n\r\n constructor() {\r\n this.trool = new Trool(true);\r\n }\r\n```\r\n\r\n- The trool library only provides 1 public method `applyRules(...)` which returns a promise containing\r\nthe updated facts. So create an `async/await` method to fire off `applyRules()` and wrap it in a `try/catch`\r\nblock.\r\n\r\n- `applyRules(...)` needs the path to the csv file, the facts to be updated, and optionally any imports.\r\n\r\n- The facts and the imports must be wrapped in holder objects, with the key being the name of the \r\nfact/import to use in the spreadsheet, and the value being the actual fact or import. The `imports`\r\nparam is optional because you only want to use ones specified in the spreadsheet or have no need for any. \r\n\r\n```typescript\r\npublic async calcTotalPrice(): Promise\r\n\r\n\r\n## Guide\r\n\r\n**Important! When you setup your decision-tables and imports there are some rules to follow the in order \r\nfor your tables/imports to be properly loaded into memory. Strict formatting is enforced for readability \r\npurposes**.\r\n\r\n**Decision-Tables:**\r\n\r\n- All decision-tables must start with a cell containing the text `Table: \"Fact Name\"`. A table without a \r\nfact name or with a fact name that does not exist on the facts-holder will throw an error. If you create\r\n2 tables that have the same fact-name, the second table will overwrite all the changes from the first.\r\n\r\n- A table will end when it reaches an empty row, the end of the file, or the start of a new table\r\nor import. For readability, you should terminate all tables with an empty row.\r\n\r\n- The first 2 rows on a decision-table are for specifying the conditions and the actions. If all conditions\r\nare true, then the actions will execute. After the start cell (the cell with `Table: \"Fact Name\"`) you\r\nmust specify at least 1 condition and 1 action.\r\n\r\n- Specifying Condition and Action columns must be done by putting `'Condition'` or `'Action'`, at the \r\ntop of each column. These are case sensitive so make sure to capitalize the values. All conditions\r\nmust come before all actions and you cannot have anything other than `'Condition'` or `'Action'` at\r\nthe top of your table columns. \r\n\r\n- The condition must be a statement which evaluates to `true` or `false`. The left side of the statement \r\nmust be a method or getter on the fact's instance-object and the right side must be `$param`. The operator \r\nmust be an existing JavaScript comparator such as `==` or `<=`. The values in the rows below will replace \r\n`$param`. For example, suppose I want to get the age of a visitor for an app which calculates ticket prices. I\r\nwould need to create a TypeScript getter (`get age(): number {}`) or a method like `getAge() {}` to \r\nfetch the visitor's age and compare it to the parameter value.\r\n\r\n- Actions are methods on a fact which will execute if all the conditions evaluate to true. Unlike conditions,\r\nyou can have multiple params passed in. The action must be a method or a TypeScript setter function on\r\nthe fact or else Trool will throw an error. The number of params in the action columns' cells below\r\nmust match the number or `$param` strings or else Trool will throw an error. \r\n\r\n- All rows on a decision-table, except for the first 2, are referred to as _rules_. A rule works by evaluating \r\na list of conditions against cell values which, if they all evaluate to true, will execute the specified \r\nactions. A rule must start with a rule name and can be anything but cannot be blank.\r\n\r\n- For each cell on the rule, if it is a condition column, the cell value will replace the `$param` value\r\nand evaluate the cell as `true` or `false`. An empty cell will automatically be evaluated as `true`. If\r\nany cell evaluates to `false`, that rule will fail and the decision-table will go on the next rule.\r\n\r\n- While on a rule's action column, each param specified must be separated by a comma. If no params\r\nare specified (the cell is blank), the rule will skip that action column. \r\n\r\n- Whew that was a lot! Now that we've gone over the rules for creating tables, let's look at an\r\nexample in detail. In the following snippet, we see an example on a decision-table and the fact `Tickets`.\r\n\r\n
\r\n\r\n- To update this fact you needs to make sure the `Tickets` property exists on the facts-holder when it\r\ngets passed to `applyRules()`. If `Tickets` is an array, the decision-table will get applied to each\r\nTicket instance in the array. \r\n\r\n- The table has one condition and one action. There's also 2 rules: `Set Price - Regular` and `Set Price - Season`. \r\nLook at the operations for the condition and action. On the left side of each operation \r\nwe can see the properties `option` and `price`. This means that each Ticket instance object passed in must have \r\ngetters/setters for the `option` and `price` properties or else an error will be thrown.\r\n\r\n- The first rule `Set Price - Regular` will take the value for `option` and check and see if its value\r\nis equal to the string `\"Regular\"`. If so, it will apply the action column to the fact. The setter for\r\n`price` will be called and the value `70` will be passed in. The exact same sequence of events will take\r\nplace for the next rule `Set Price - Season`. In other words, if the Ticket option is `\"Season\"`, the price\r\nwill be `600`, if the option is `\"Regular\"`, the price will be `70`.\r\n\r\n- And that's how Trool works! If you need to change the price for a Regular or Seasonal ticket over\r\ntime without bugging your engineers, just have someone else make updates to the spreadsheet :)\r\n\r\n\r\n\r\n**Imports:**\r\n\r\n- For large complicated spreadsheets you might want to reuse certain values. Suppose for Visitors who\r\nmight be buying these tickets the maximum age for a child is `18`. One might need to reuse this value\r\nfor multiple rules/tables and if it's updated in once place, it needs to be updated everywhere. For \r\nexample, the maximum age for a child might change from `18` to `15` or something like that. This is where\r\nimports come in handy. An import basically sets up a simple JSON object that you can access in your tables.\r\nImports can be created in the spreadsheet or passed through `applyRules()`. \r\n\r\n- Trool iterates the entire spreadsheet and first looks for all the imports, then it goes back through\r\nand initializes all the decision-tables. So the ordering of your tables/imports does not matter.\r\nFor cleanliness I recommend keeping them separated.\r\n\r\n- All imports must begin with the cell `Import: \"Import Name\"`. If you pass an import in the imports holder \r\n(via `applyRules()`) that has a key matching an import name in the spreadsheet, you will get the warning:\r\n`!!WARNING!! The spreadsheet is using an import name already passed via the imports object. The spreadsheet \r\nwill overwrite the import: \"Import Name\"`.\r\n\r\n- The quick-start had an example of passing imports through `applyRules()`. Let's look at an example of\r\nan import hardcoded in the spreadsheet.\r\n
\r\n\r\n- With this import, each table will have access to an object named `TicketTypes` and all of its properties.\r\nIf you were to place `TicketTypes.SEASON` in a cell for the operation `option == $param`, \r\nthe Ticket object would call the `option` getter and pass `\"SEASON\"` as the value.\r\n\r\n- When using imports through `applyRules()`, you don't have to necessary use an object as a property\r\nand could have it as a primitive. VisitorTypes itself could be a string or number. I don't\r\nrecommend using imports this way though; it could be confusing in a collaborative environment.\r\n\r\n- One more thing, you cannot use nested properties on imports: i.e. `Import.key.key` This is intentional,\r\nit would lead to a very message spreadsheet. \r\n\r\n\r\n\r\n**Special Notes:**\r\n\r\n- In Trool spreadsheets, `==` under the hood is actually using `===`. \r\n\r\n- The values you can pass through cells are strings, numbers, true, false, and null. Don't use objects\r\nor undefined. Via imports, you could actually use an object as a `$param` value, but don't do it. This\r\ncould be confusing for non-engineers. Stick with primitives. Create extra getters and setters when dealing\r\nwith multiple values. \r\n\r\n- Import property name rules are the same as for JavaScript keys. That means alphanumeric, underscores,\r\nand dashes. Anything other than characters will throw an error.\r\n","readmeFilename":"README.md"}