docs(cpp-matrix): handlebars helpers

Author: alandefreitas

cpp-matrix/action.yml

@@ -140,12 +140,12 @@ description: |
   existing values in the matrix. For instance, consider an entry in the matrix that has
   the `x86` factor set to true. 
   
-  When using `b2`, we should set `address-model=32` for this entry. Otherwise, we should set
+  Assume we are using `b2` and should set `address-model=32` for this entry. Otherwise, we should set
   `address-model=64`. With GitHub expressions, we can generate this value based on the `x86` factor:
   
   `b2 address-model={{ matrix.x86 && '32' || '64' }}`
   
-  If this pattern needs to be repeated in many entries, this pattern might become cumbersome.
+  If this pattern needs to be repeated in many entries, it might become cumbersome.
   In this case, the action allows the user to define extra values to be injected in each entry
   of the matrix. These values can be used to generate new values based on existing values in 
   the matrix with handlebars. You could set the following extra values in each entry of the matrix:
@@ -159,6 +159,45 @@ description: |
   run: |
     b2 address-model={{ matrix.address-model }}
   ----
+
+  or
+  
+  [source,yml]
+  ----
+  extra-values: |
+      address-model-arg: address-model={{#if x86}}32{{else}}64{{/if}}
+  
+  # ...
+  run: |
+    b2 {{ matrix.address-model-arg }}
+  ----
+  
+  The syntax for each entry in the `extra-values` input is a key-value pair, where the key is the name of the
+  value to be injected in the matrix and the value is a handlebars expression that generates the value based on
+  other values in the matrix. The handlebars expression can access previous values in the matrix, including
+  other extra values. 
+  
+  Besides referencing other values in the matrix, the handlebars expressions can also use the 
+  built-in https://handlebarsjs.com/guide/builtin-helpers.html[helpers] provided by Handlebars and the
+  predefined helpers defined by the action:
+  
+  [cols="1,3"]
+  |===
+  | Helper | Description
+  | `lowercase` | Converts the value to lowercase
+  | `uppercase` | Converts the value to uppercase
+  | `contains` | Checks if the value contains a substring
+  | `startsWith` / `starts-with` | Checks if the value starts with a substring
+  | `endsWith` / `ends-with` | Checks if the value ends with a substring
+  | `substring` | Extracts a substring from the value
+  | `and` | Logical AND operator
+  | `or` | Logical OR operator
+  | `not` | Logical NOT operator
+  | `eq` | Equality operator
+  | `ieq` | Case-insensitive equality operator
+  | `ne` | Inequality operator
+  | `ine` | Case-insensitive inequality operator
+  |===
   
   == Ordering entries
   

cpp-matrix/index.js

@@ -1165,6 +1165,16 @@ function registerHelpers() {
         args.pop()
         return args.every((it) => it)
     })
+    Handlebars.registerHelper('or', function(...args) {
+        const numArgs = args.length
+        if (numArgs === 3) return args[0] || args[1]
+        if (numArgs < 3) throw new Error('{{or}} helper expects at least 2 arguments')
+        args.pop()
+        return args.some((it) => it)
+    })
+    Handlebars.registerHelper('not', function(value) {
+        return !value
+    })
     Handlebars.registerHelper('eq', function(a, b) {
         return a === b
     })
@@ -1177,16 +1187,6 @@ function registerHelpers() {
     Handlebars.registerHelper('ine', function(a, b) {
         return a.toLowerCase() !== b.toLowerCase()
     })
-    Handlebars.registerHelper('or', function(...args) {
-        const numArgs = args.length
-        if (numArgs === 3) return args[0] || args[1]
-        if (numArgs < 3) throw new Error('{{or}} helper expects at least 2 arguments')
-        args.pop()
-        return args.some((it) => it)
-    })
-    Handlebars.registerHelper('not', function(value) {
-        return !value
-    })
 }