Document built-in key and value renderers

fredemmott · fredemmott · commit 83945fdef02d · 2017-02-20T21:34:43.000-08:00
diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml
@@ -7,6 +7,7 @@
 - title: Hack Builder
   items:
   - id: hack-builder-blocks
+  - id: hack-builder-keys-and-values
 
 # n title:, 1 items: per title:, n id: per items:
 # - title: A
diff --git a/docs/_docs/hack-builder/keys-and-values.md b/docs/_docs/hack-builder/keys-and-values.md
@@ -0,0 +1,83 @@
+---
+docid: hack-builder-keys-and-values
+title: Keys & Values
+layout: docs
+permalink: /docs/hack-builder/keys-and-values/
+---
+
+Hack Codegen has an extensible system for rendering values, used by:
+
+ - `$hack_builder->addValue()`
+ - `$hack_builder->addAssignment()`
+ - `$hack_builder->addReturn()`
+ - `$hack_builder->addReturnCase()`
+
+This is based on the `IHackBuilderValueRenderer<T>` interface, which provides
+`public function render(IHackCodegenConfig $config, T $input): string` which
+returns PHP code.
+
+Basic Built-ins
+---------------
+
+Hack Codegen provides several implementation of this interface, accessed via
+the [`HackBuilderValues`](https://github.com/hhvm/hack-codegen/blob/master/src/key-value-render/HackBuilderValues.php)
+class:
+
+ - `HackBuilderValues::literal()`: returns the $input as literal code
+ - `HackBuilderValues::export()`: returns code that recreates `$input`; this is
+   similar to `var_export()`
+ - `HackBuilderValues::classname()`: renders the input as a `classname<T>`
+
+For example:
+
+``` php
+<?hh
+$builder->addValue(
+  'foo',
+  HackBuilderValues::export(),
+);
+```
+
+Collection Built-Ins
+--------------------
+
+As collections can be nested, the renderers are nested; the built-in value container
+renderers are:
+
+ - `HackBuilderValues::valueArray($value_renderer)`
+ - `HackBuilderValues::vector($value_renderer)`
+ - `HackBuilderValues::immVector($value_renderer)`
+ - `HackBuilderValues::set($value_renderer)`
+ - `HackBuilderValues::immSet($value_renderer)`
+
+For example:
+``` php
+<?hh
+
+$builder
+  ->addValue(
+    Vector { 'foo' },
+    HackBuilderValues::vector(
+      HackBuilderValues::export(),
+    ),
+  )
+  ->addValue(
+    Vector { Vector { 'foo ' } },
+    HackBuilderValues::vector(
+      HackBuilderValues::vector(
+        HackBuilderValues::export(),
+      )
+    ),
+  );
+```
+
+`IHackBuilderKeyRenderer<T>` is similar to `IHackBuilderValueRenderer<T>`, however
+it requires that `T` is an `arraykey` (`string` or `int`); this is used by `Map`,
+`Set`, key-value arrays, and so on - key renderers are required to implement this
+interface.
+
+The built-in key-value container renderers are:
+
+ - `HackBuilderValues::keyValueArray($key_renderer, $value_renderer)`
+ - `HackBuilderValues::map($key_renderer, $value_renderer)`
+ - `HackBuilderValues::immMap($key_renderer, $value_renderer)`
