From aff173498b5e652667d1ab35d4caa82b0a62415e 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 +++++++++++++++++++++++++++++
 2 files changed, 84 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..7b7ae80
--- /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
+
+Primitives serve a number of roles in Pony. Similar to modules in [OCaml](https://ocaml.org/) and [F#](https://fsharp.org/), Pony's primitives are a great way to group together stateless "like functions". In general, 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.
+
+Here, our primitive `FooConstructor` has a single function `apply` that is used to try and construct a `Foo` or if its construction prerequisites aren't met, return an informative message.
+
+```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)
+```
+
+Static constructor is the [Global Function](../code-sharing/global-function.md) pattern applied to object construction.