Expand helper options documentation in readme

Author: theodorejb

README.md

@@ -10,7 +10,7 @@ PHP Handlebars compiles and executes complex templates up to 40% faster than Lig
 | Library            | Compile time | Runtime | Total time | Peak memory usage |
 |--------------------|--------------|---------|------------|-------------------|
 | LightnCandy 1.2.6  | 5.2 ms       | 2.8 ms  | 8.0 ms     | 5.3 MB            |
-| PHP Handlebars 1.0 | 3.5 ms       | 1.6 ms  | 5.1 ms     | 3.6 MB            |
+| PHP Handlebars 1.1 | 3.5 ms       | 1.6 ms  | 5.1 ms     | 3.6 MB            |
 
 _Tested on PHP 8.5 with the JIT enabled. See the `benchmark` branch to run the same test._
 
@@ -72,39 +72,37 @@ echo $template(['first' => 'John']); // Error: "last" not defined
 
 * `knownHelpers`: Associative array (`helperName => bool`) of helpers known to exist at template execution time.
   Passing this allows the compiler to optimize a number of cases.
-  Builtin helpers are automatically included in this list and may be omitted by setting that value to `false`.
-* `knownHelpersOnly`: Enable to allow further optimizations based on the known helpers list.
-* `noEscape`: Enable to not HTML escape any content.
+  Built-in helpers are automatically included in this list and may be omitted by setting that value to `false`.
+* `knownHelpersOnly`: Set to `true` to allow further optimizations based on the known helpers list.
+* `noEscape`: Set to `true` to disable HTML escaping of output.
 * `strict`: Run in strict mode. In this mode, templates will throw rather than silently ignore missing fields.
   This has the side effect of disabling inverse operations such as `{{^foo}}{{/foo}}`
   unless fields are explicitly included in the source object.
 * `assumeObjects`: Removes object existence checks when traversing paths.
   This is a subset of strict mode that generates optimized templates when the data inputs are known to be safe.
-* `preventIndent`: Prevent indented partial-call from indenting the entire partial output by the same amount.
+* `preventIndent`: Prevents an indented partial call from indenting the entire partial output by the same amount.
 * `ignoreStandalone`: Disables standalone tag removal.
   When set, blocks and partials that are on their own line will not remove the whitespace on that line.
 * `explicitPartialContext`: Disables implicit context for partials.
   When enabled, partials that are not passed a context value will execute against an empty object.
-* `partials`: Provide a `name => value` array of custom partial template strings.
-* `partialResolver`: A closure which will be called for any partial not in the `partials` array to return a template for it.
+* `partials`: An associative array of custom partial template strings (`name => template`).
+* `partialResolver`: A closure that will be called for any partial not found in the `partials` array,
+  and should return a template string for it.
 
 ## Runtime Options
 
 `Handlebars::compile` returns a closure which can be invoked as `$template($context, $options)`.
 The `$options` parameter takes an array of runtime options, accepting the following keys:
 
-* `data`: An array to define custom `@variable` private variables.
-* `helpers`: An `array<string, \Closure>` containing custom helpers to add to the built-in helpers.
-* `partials`: An `array<string, \Closure>` containing partial functions precompiled with `Handlebars::compile`.
-This is useful if multiple templates sharing the same partials need to be compiled and rendered, and you don't want
-to recompile the same partials over and over for each template.
+* `data`: An associative array of initial `@data` variables (e.g. `['version' => '1.0']` makes `@version` available in the template).
+* `helpers`: An `array<string, \Closure>` of helpers to merge with the built-in helpers. Can also be used to override a built-in helper by using the same name.
+* `partials`: An `array<string, \Closure>` of partial closures precompiled with `Handlebars::compile`.
+  Useful when multiple templates share the same partials, and you want to avoid recompiling them for each template.
 
 ## Custom Helpers
 
 Helper functions will be passed any arguments provided to the helper in the template.
 If needed, a final `$options` parameter can be included which will be passed a `HelperOptions` instance.
-This object contains properties for accessing `hash` arguments, `data`, and the current `scope`, `name`,
-as well as `fn()` and `inverse()` methods to render the block and else contents, respectively.
 
 For example, a custom `#equals` helper with JS equality semantics could be implemented as follows:
 
@@ -131,6 +129,37 @@ echo $template(['my_var' => 1], $options); // Not equal
 echo $template(['my_var' => null], $options); // Not equal
 ```
 
+### HelperOptions Reference
+
+**Properties**
+
+* `name` (readonly `string`): The helper name as it appeared in the template.
+  Useful in `helperMissing`/`blockHelperMissing` hooks to identify which name was called.
+* `hash` (readonly `array`): Key/value pairs passed as hash arguments in the template
+  (e.g. `{{helper foo=1 bar="x"}}` produces `['foo' => 1, 'bar' => 'x']`).
+* `blockParams` (readonly `int`): The number of block parameters declared by the helper call
+  (e.g. `{{#helper as |a b|}}` produces `2`).
+* `scope` (`mixed`): The current evaluation context (equivalent to `this` in a Handlebars.js helper).
+  Can be reassigned inside a helper to change the context passed to `fn()`.
+* `data` (`array`): The current `@data` frame. Contains `@`-prefixed private variables such as
+  `root`, `index`, `key`, `first`, `last`, and `_parent`. Can be read or modified inside a helper.
+
+**Methods**
+
+* `fn(mixed $context = <current scope>, mixed $data = null): string`: Renders the block body.
+  Pass a new context as `$context` to change what the block renders against (equivalent to `options.fn(newContext)` in JS).
+  Pass a `$data` array with a `'data'` key to inject additional `@`-prefixed variables into the block,
+  and/or a `'blockParams'` key containing an array of values to expose as block parameters.
+* `inverse(mixed $context = null, mixed $data = null): string`: Renders the `{{else}}` / inverse block.
+  Returns an empty string if no inverse block was provided.
+  Accepts the same optional `$context` and `$data` arguments as `fn()`.
+* `hasPartial(string $name): bool`: Returns `true` if a partial with the given name is registered in the
+  current render context. Useful alongside `registerPartial()` to implement lazy partial loading.
+* `registerPartial(string $name, \Closure $partial): void`: Registers a compiled partial closure under
+  the given name for the current render context. The closure must be produced by `Handlebars::compile`.
+
+`isset($options->fn)` and `isset($options->inverse)` can be used to test whether a block or inverse block was provided.
+
 ## Hooks
 
 If a custom helper named `helperMissing` is defined, it will be called when a mustache or a block-statement