From a3e1bc8fd87bc5355a4ef85ca26611c94713ea81 Mon Sep 17 00:00:00 2001
From: "Sean T. Allen" <sean@seantallen.com>
Date: Sat, 20 Jan 2024 18:59:01 +0000
Subject: [PATCH] Add "static constructor" pattern

---
 .spelling-wordlist.txt              |  1 +
 docs/creation/static-constructor.md | 83 +++++++++++++++++++++++++++++
 mkdocs.yml                          |  1 +
 3 files changed, 85 insertions(+)
 create mode 100644 docs/creation/static-constructor.md

diff --git a/.spelling-wordlist.txt b/.spelling-wordlist.txt
index 8b278a5..15c5f03 100644
--- a/.spelling-wordlist.txt
+++ b/.spelling-wordlist.txt
@@ -12,6 +12,7 @@ mixin
 mixins
 namespace
 natively
+OCaml
 oof
 ponylang
 preallocate
diff --git a/docs/creation/static-constructor.md b/docs/creation/static-constructor.md
new file mode 100644
index 0000000..53c320a
--- /dev/null
+++ b/docs/creation/static-constructor.md
@@ -0,0 +1,83 @@
+---
+hide:
+  - toc
+---
+
+# Static Constructor
+
+## Problem
+
+You want to construct an object or return a meaningful error message. Unfortunately, in Pony there's no way to do that. Pony constructors always return an initialized instance of their class unless, the constructor is partial in which case nothing is return as we jump to the nearest error handler.
+
+```pony
+class Foo
+  // Always returns a foo
+  new create() => None
+
+  // Sometimes returns a foo
+  new perhaps(a: Bool) ? =>
+    if not a then
+      error
+    end
+```
+
+What you would like to do instead is:
+
+```pony
+class Error
+  let msg: String
+
+  new create(m: String) =>
+    msg = m
+
+class Foo
+  // return a Foo or Error message
+  new create(a: Bool): (Foo | Error) =>
+    if not a then
+      Error("Can't build Foo that way")
+    else
+      this
+    end
+```
+
+## Solution
+
+Use a `primitive`.
+
+```pony
+class Error
+  let msg: String
+
+  new create(m: String) =>
+    msg = m
+
+class Foo
+  new create() => None
+
+primitive FooConstructor
+  fun apply(a: Bool): (Foo | Error) =>
+    if not a then
+      Error("Can't build a Foo that way")
+    else
+      Foo
+    end
+```
+
+## Discussion
+
+Static constructor is the [Global Function](../code-sharing/global-function.md) pattern applied to object construction. As we discussed in Global Function, Pony's primitives are a great way to group together stateless "like functions". If you are looking to do anything that might be classified as a static function or a utility function in another language, you probably want to use a primitive in Pony.
+
+If you have an background in [ML](https://en.wikipedia.org/wiki/ML_(programming_language)) type languages, you can think of primitives as similar to modules in [OCaml](https://ocaml.org/) and [F#](https://fsharp.org/).
+
+Finally, here's our static constructor in action:
+
+```pony
+actor Main
+  new create(env: Env) =>
+    match FooConstructor(true)
+    | let f: Foo =>
+      // ToDo: do something with Foo
+      None
+    | let e: Error =>
+      env.err.print(e.msg)
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 52a1372..8247d85 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -83,6 +83,7 @@ nav:
     - Notifier: 'code-sharing/notifier.md'
   - Creation Patterns:
     - Overview: 'creation/index.md'
+    - Static Constructor: 'creation/static-constructor.md'
     - Supply Chain: 'creation/supply-chain.md'
   - Data Sharing Patterns:
     - Overview: 'data-sharing/index.md'