Add constrained_types package to the standard library

Implements RFC 79.

https://github.com/ponylang/rfcs/blob/main/text/0079-constrained-types.md

Closes #4492

.release-notes/4493.md

@@ -0,0 +1,9 @@
+## Add constrained types package to standard library
+
+We've added a new package to the standard library: `constrained_types`.
+
+The `constrained_types` package allows you to represent in the type system, domain rules like "Username must be 6 to 12 characters in length and only container lower case ASCII letters".
+
+To learn more about the package, checkout its [documentation on the standard library docs site](https://stdlib.ponylang.io/constrained_types--index/).
+
+You can learn more about the motivation behind the package by reading [the RFC](https://github.com/ponylang/rfcs/blob/main/text/0079-constrained-types.md).

examples/constrained_type/.gitignore

@@ -0,0 +1 @@
+constrained_type

examples/constrained_type/README.md

@@ -0,0 +1,35 @@
+# constrained_type
+
+Demonstrates the basics of using the `constrained_types` package to encode domain type constraints such as "number less than 10" in the Pony type system.
+
+The example program implements a type for usernames that requires that a username is between 6 and 12 characters long and only contains lower case ASCII characters.
+
+## How to Compile
+
+With a minimal Pony installation, in the same directory as this README file run `ponyc`. You should see content building the necessary packages, which ends with:
+
+```console
+...
+Generating
+ Reachability
+ Selector painting
+ Data prototypes
+ Data types
+ Function prototypes
+ Functions
+ Descriptors
+Optimising
+Writing ./constrained_type.o
+Linking ./constrained_type
+```
+
+## How to Run
+
+Once `constrained_type` has been compiled, in the same directory as this README file run `./constrained_type A_USERNAME`. Where `A_USERNAME` is a string you want to check to see if it meets the business rules above.
+
+For example, if you run `./constrained_type magenta` you should see:
+
+```console
+$ ./constrained_type magenta
+magenta is a valid username!
+```

examples/constrained_type/main.pony

@@ -0,0 +1,58 @@
+use "constrained_types"
+
+type Username is Constrained[String, UsernameValidator]
+type MakeUsername is MakeConstrained[String, UsernameValidator]
+
+primitive UsernameValidator is Validator[String]
+ fun apply(string: String): ValidationResult =>
+ recover val
+ let errors: Array[String] = Array[String]()
+
+ if (string.size() < 6) or (string.size() > 12) then
+ let msg = "Username must be between 6 and 12 characters"
+ errors.push(msg)
+ end
+
+ for c in string.values() do
+ if (c < 97) or (c > 122) then
+ errors.push("Username can only contain lower case ASCII characters")
+ break
+ end
+ end
+
+ if errors.size() == 0 then
+ ValidationSuccess
+ else
+ let failure = ValidationFailure
+ for e in errors.values() do
+ failure(e)
+ end
+ failure
+ end
+ end
+
+actor Main
+ let _env: Env
+
+ new create(env: Env) =>
+ _env = env
+
+ try
+ let arg1 = env.args(1)?
+ let username = MakeUsername(arg1)
+ match username
+ | let u: Username =>
+ print_username(u)
+ | let e: ValidationFailure =>
+ print_errors(e)
+ end
+ end
+
+ fun print_username(username: Username) =>
+ _env.out.print(username() + " is a valid username!")
+
+ fun print_errors(errors: ValidationFailure) =>
+ _env.err.print("Unable to create username")
+ for s in errors.errors().values() do
+ _env.err.print("\t- " + s)
+ end

packages/constrained_types/_test.pony

@@ -0,0 +1,124 @@
+use "pony_test"
+
+actor \nodoc\ Main is TestList
+ new create(env: Env) => PonyTest(env, this)
+ new make() => None
+
+ fun tag tests(test: PonyTest) =>
+ test(_TestFailureMultipleMessages)
+ test(_TestFailurePlumbingWorks)
+ test(_TestMultipleMessagesSanity)
+ test(_TestSuccessPlumbingWorks)
+
+class \nodoc\ iso _TestSuccessPlumbingWorks is UnitTest
+ """
+ Test that what should be a success, comes back as a success.
+ We are expecting to get a constrained type back.
+ """
+ fun name(): String => "constrained_types/SuccessPlumbingWorks"
+
+ fun ref apply(h: TestHelper) =>
+ let less: USize = 9
+
+ match MakeConstrained[USize, _LessThan10Validator](less)
+ | let s: Constrained[USize, _LessThan10Validator] =>
+ h.assert_true(true)
+ | let f: ValidationFailure =>
+ h.assert_true(false)
+ end
+
+class \nodoc\ iso _TestFailurePlumbingWorks is UnitTest
+ """
+ Test that what should be a failure, comes back as a failure.
+ This is a basic plumbing test.
+ """
+ fun name(): String => "constrained_types/FailurePlumbingWorks"
+
+ fun ref apply(h: TestHelper) =>
+ let more: USize = 11
+
+ match MakeConstrained[USize, _LessThan10Validator](more)
+ | let s: Constrained[USize, _LessThan10Validator] =>
+ h.assert_true(false)
+ | let f: ValidationFailure =>
+ h.assert_true(f.errors().size() == 1)
+ h.assert_array_eq[String](["not less than 10"], f.errors())
+ end
+
+class \nodoc\ iso _TestMultipleMessagesSanity is UnitTest
+ """
+ Sanity check that the _MultipleErrorsValidator works as expected and that
+ we can trust the _TestFailureMultipleMessages working results.
+ """
+ fun name(): String => "constrained_types/MultipleMessagesSanity"
+
+ fun ref apply(h: TestHelper) =>
+ let string = "magenta"
+
+ match MakeConstrained[String, _MultipleErrorsValidator](string)
+ | let s: Constrained[String, _MultipleErrorsValidator] =>
+ h.assert_true(true)
+ | let f: ValidationFailure =>
+ h.assert_true(false)
+ end
+
+class \nodoc\ iso _TestFailureMultipleMessages is UnitTest
+ """
+ Verify that collecting errors works as expected.
+ """
+ fun name(): String => "constrained_types/FailureMultipleMessages"
+
+ fun ref apply(h: TestHelper) =>
+ let string = "A1"
+
+ match MakeConstrained[String, _MultipleErrorsValidator](string)
+ | let s: Constrained[String, _MultipleErrorsValidator] =>
+ h.assert_true(false)
+ | let f: ValidationFailure =>
+ h.assert_true(f.errors().size() == 2)
+ h.assert_array_eq_unordered[String](
+ ["bad length"; "bad character"],
+ f.errors())
+ end
+
+primitive \nodoc\ _LessThan10Validator is Validator[USize]
+ fun apply(num: USize): ValidationResult =>
+ recover val
+ if num < 10 then
+ ValidationSuccess
+ else
+ ValidationFailure("not less than 10")
+ end
+ end
+
+primitive \nodoc\ _MultipleErrorsValidator is Validator[String]
+ fun apply(string: String): ValidationResult =>
+ recover val
+ let errors: Array[String] = Array[String]()
+
+ // Isn't too big or too small
+ if (string.size() < 6) or (string.size() > 12) then
+ let msg = "bad length"
+ errors.push(msg)
+ end
+
+ // Every character is valid
+ for c in string.values() do
+ if (c < 97) or (c > 122) then
+ errors.push("bad character")
+ break
+ end
+ end
+
+ if errors.size() == 0 then
+ ValidationSuccess
+ else
+ // We have some errors, let's package them all up
+ // and return the failure
+ let failure = ValidationFailure
+ for e in errors.values() do
+ failure(e)
+ end
+ failure
+ end
+ end

packages/constrained_types/constrained.pony

@@ -0,0 +1,69 @@
+type ValidationResult is (ValidationSuccess | ValidationFailure)
+
+primitive ValidationSuccess
+
+class val ValidationFailure
+ """
+ Collection of validation errors.
+ """
+ let _errors: Array[String val] = _errors.create()
+
+ new create(e: (String val | None) = None) =>
+ match e
+ | let s: String val => _errors.push(s)
+ end
+
+ fun ref apply(e: String val) =>
+ """
+ Add an error to the failure.
+ """
+ _errors.push(e)
+
+ fun errors(): this->Array[String val] =>
+ """
+ Get list of validation errors.
+ """
+ _errors
+
+interface val Validator[T]
+ """
+ Interface validators must implement.
+
+ We strongly suggest you use a `primitive` for your `Validator` as validators
+ are required to be stateless.
+ """
+ new val create()
+ fun apply(i: T): ValidationResult
+ """
+ Takes an instance and returns either `ValidationSuccess` if it meets the
+ constraint criteria or `ValidationFailure` if it doesn't.
+ """
+
+class val Constrained[T: Any val, F: Validator[T]]
+ """
+ Wrapper class for a constrained type.
+ """
+ let _value: T val
+
+ new val _create(value: T val) =>
+ """
+ Private constructor that guarantees that `Constrained` can only be created
+ by the `MakeConstrained` primitive in this package.
+ """
+ _value = value
+
+ fun val apply(): T val =>
+ """
+ Unwraps and allows access to the constrained object.
+ """
+ _value
+
+primitive MakeConstrained[T: Any val, F: Validator[T] val]
+ """
+ Builder of `Constrained` instances.
+ """
+ fun apply(value: T): (Constrained[T, F] | ValidationFailure) =>
+ match F(value)
+ | ValidationSuccess => Constrained[T, F]._create(value)
+ | let e: ValidationFailure => e
+ end