Continue Updating Claro Docs to Use Auto-Validated Examples

mdbook_docs/src/BUILD

@@ -48,6 +48,7 @@ write_source_file(
         "//mdbook_docs/src/guaranteed_deadlock_free/re_what_color_is_your_function:blocking_generics",
         "//mdbook_docs/src/http_servers:http_servers",
         "//mdbook_docs/src/images:logo",
+        "//mdbook_docs/src/json_parsing:json_parsing",
         "//mdbook_docs/src/lambdas_and_first_class_procedures:lambdas_and_first_class_procedures",
         "//mdbook_docs/src/lambdas_and_first_class_procedures/lambda_closures:lambda_closures",
         "//mdbook_docs/src/module_system:module_system",

mdbook_docs/src/SUMMARY.tmpl.md

@@ -95,6 +95,7 @@
         - [Re: "What Color is Your Function?"](./guaranteed_deadlock_free/re_what_color_is_your_function.generated_docs.md)
         - [(Advanced) Blocking Generics](./guaranteed_deadlock_free/re_what_color_is_your_function/blocking_generics.generated_docs.md)
 - [Basic HTTP Servers](./http_servers/http_servers.generated_docs.md)
+- [JSON Parsing](./json_parsing/json_parsing.generated_docs.md)
 
 ---
 

mdbook_docs/src/http_servers/http_servers.tmpl.md

@@ -1,9 +1,9 @@
 # Basic HTTP Servers
 
 Claro has been carefully designed to be uniquely well-suited for building highly efficient, scalable web servers.
-Claro's "Fearless Concurrency" guarantees are explicitly an effort to make it significantly challenging to make a buggy,
-slow web server - and instead, Claro's novel concurrency model will lead to performant and easy-to-maintain web
-servers naturally falling out of even naive usages of the language.
+Claro's ["Fearless Concurrency"](../fearless_concurrency/fearless_concurrency.md) guarantees are explicitly an effort to
+make it significantly challenging to make a buggy, slow web server - and instead, Claro's novel concurrency model will
+lead to performant and easy-to-maintain web servers naturally falling out of even naive usages of the language.
 
 To actually demonstrate this explicitly, Claro provides very basic support for building HTTP servers that can be used in
 the absence of any sort of 3rd party framework to jump you right into your first web server in Claro. This feature is
@@ -26,7 +26,7 @@ The above defines a very simple service with two basic endpoints.
 Claro will automatically generate a pre-configured, non-blocking web server implementation for your `HttpService`
 definition by using the builtin magic function `http::getBasicHttpServerForPort()`. This function is implemented as a
 compiler intrinsic that will infer the server to automatically generate based on the type asserted on the call. So, we
-can request the Claro generate a web server for the example `Greeter` service as in the example below.
+can get Claro to generate a web server for the example `Greeter` service as in the example below.
 
 <div class="warning">
 Note that no Endpoint Handlers have been implemented yet so we should actually expect the below to fail to compile and

mdbook_docs/src/json_parsing/BUILD

@@ -0,0 +1,25 @@
+load("//:rules.bzl", "claro_module", "claro_binary")
+load("//mdbook_docs:docs_with_validated_examples.bzl", "doc_with_validated_examples")
+
+doc_with_validated_examples(
+    name = "json_parsing",
+    doc_template = "json_parsing.tmpl.md",
+    examples = [
+        {
+            "example": "//mdbook_docs/src/module_system/module_apis/static_values:ex-server-config.json",
+            "executable": False,
+            "codeblock_css_class": "json",
+        },
+        {
+            "example": "ex1-format.claro",
+            "append_output": False,
+        },
+        {
+            "example": "ex1.claro",
+            "hidden_setup": "ex1-format.claro",
+            "resources": {
+                "ServerConfigJSON": "//mdbook_docs/src/module_system/module_apis/static_values:ex-server-config.json"
+            },
+        },
+    ],
+)

mdbook_docs/src/json_parsing/ex1-format.claro

@@ -0,0 +1,12 @@
+alias ServerConfig : struct {
+  server_name: string,
+  port: int,
+  logging: struct {
+    filename: string
+  },
+  database: struct {
+    host: string,
+    port: int,
+    database_name: string
+  }
+}

mdbook_docs/src/json_parsing/ex1.claro

@@ -0,0 +1,15 @@
+
+resources::ServerConfigJSON
+  |> files::readOrPanic(^)
+  |> var parsedConfig: std::ParsedJson<ServerConfig> = fromJson(^);
+
+var parsedResult = unwrap(parsedConfig).result;
+if (parsedResult instanceof ServerConfig) {
+  print("Config has correct format and was parsed successfully!");
+  print(strings::repeated("-", 50));
+  print("Server Name: {parsedResult.server_name}");
+  print("Port:        {parsedResult.port}");
+} else {
+  print("JSON parsing failed!");
+  print(parsedResult);
+}

mdbook_docs/src/json_parsing/json_parsing.tmpl.md

@@ -0,0 +1,34 @@
+# JSON Parsing
+
+Claro strives to make development easier in many ways, and as being able to write programs that interact with the 
+network is an important goal, Claro has some initial support for automatically generating efficient JSON parsers for
+relatively arbitrary formats. If you know the schema of the JSON data that you'll be interacting with, and can describe
+it as some Claro struct, then in general you can automatically parse JSON data from a string directly into the Claro
+type. 
+
+Claro's JSON parsing is implemented by **generating a custom parser for the target data format at compile time**. So, in
+addition to ergonomic improvements, this approach offers potential performance benefits over a general-purpose JSON
+parser.
+
+For example, the following JSON string could be included in a 
+[Resource File](../resource_files/resource_files.generated_docs.md):
+
+{{EX1}}
+
+We can represent that JSON format as the following Claro data structure:
+
+{{EX2}}
+
+And now, the JSON string can be parsed by a simple call to the `fromJson(...)` builtin function:
+
+{{EX3}}
+
+## Limitations
+
+<div class="warning">
+
+To be clear, Claro's JSON parsing support is currently fairly constrained and doesn't yet support the full range of
+possible JSON formats. You'll be warned at compile-time if the format you're attempting to auto-parse is supported or
+not. More work will be needed to complete the implementation. **If you're interested in contributing to this please
+reach out!**  
+</div>

mdbook_docs/src/module_system/module_apis/static_values/BUILD

@@ -1,6 +1,8 @@
 load("//:rules.bzl", "claro_module", "claro_binary")
 load("//mdbook_docs:docs_with_validated_examples.bzl", "doc_with_validated_examples")
 
+exports_files(["ex-server-config.json"])
+
 doc_with_validated_examples(
     name = "static_values",
     doc_template = "static_values.tmpl.md",

mdbook_docs/src/module_system/module_apis/static_values/static_values.tmpl.md

@@ -76,7 +76,7 @@ them at compile time to ensure that you don't accidentally create an infinite lo
 conceptually considered to be in the ["Singleton" scope](https://github.com/google/guice/wiki/Scopes#singleton) in any
 of the mentioned DI frameworks.
 
-[^2]: Learn more about Claro's support for automatic JSON Parsing. (TODO(steving) Add documentation on Claro's JSON Parser generation.)
+[^2]: Learn more about Claro's support for automatic [JSON Parsing](../../../json_parsing/json_parsing.generated_docs.md).
 
 [^3]: Learn more about Claro's support for Resource Files in the StdLib's [files module](../../../stdlib/files_module.generated_docs.md).