Add release notes

.release-notes/3844.md

@@ -0,0 +1,108 @@
+## Remove options package
+
+Removes the options package, which was deprecated in version 0.26.0 in favor of the cli package.
+
+An example program using the options package is immediately below, while the rewrite with the cli package follows it.
+
+```pony
+use "options"
+
+actor Main
+  let _env: Env
+  // Some values we can set via command line options
+  var _a_string: String = "default"
+  var _a_number: USize = 0
+  var _a_unumber: USize = 0
+  var _a_float: Float = F64(0.0)
+
+  new create(env: Env) =>
+    _env = env
+    try
+      arguments()?
+    end
+
+    _env.out.print("The String is " + _a_string)
+    _env.out.print("The Number is " + _a_number.string())
+    _env.out.print("The UNumber is " + _a_unumber.string())
+    _env.out.print("The Float is " + _a_float.string())
+
+  fun ref arguments() ? =>
+    var options = Options(_env.args)
+
+    options
+      .add("string", "t", StringArgument)
+      .add("number", "i", I64Argument)
+      .add("unumber", "u", U64Argument)
+      .add("float", "c", F64Argument)
+
+    for option in options do
+      match option
+      | ("string", let arg: String) => _a_string = arg
+      | ("number", let arg: I64) => _a_number = arg.usize()
+      | ("unumber", let arg: U64) => _a_unumber = arg.usize()
+      | ("float", let arg: F64) => _a_float = arg
+      | let err: ParseError => err.report(_env.out) ; usage() ; error
+      end
+    end
+
+  fun ref usage() =>
+    // this exists inside a doc-string to create the docs you are reading
+    // in real code, we would use a single string literal for this but
+    // docstrings are themselves string literals and you can't put a
+    // string literal in a string literal. That would lead to total
+    // protonic reversal. In your own code, use a string literal instead
+    // of string concatenation for this.
+    _env.out.print(
+      "program [OPTIONS]\n" +
+      "  --string      N   a string argument. Defaults to 'default'.\n" +
+      "  --number      N   a number argument. Defaults to 0.\n" +
+      "  --unumber     N   a unsigned number argument. Defaults to 0.\n" +
+      "  --float       N   a floating point argument. Defaults to 0.0.\n"
+      )
+```
+
+```pony
+use "cli"
+
+actor Main
+  new create(env: Env) =>
+    let cs =
+      try
+        CommandSpec.leaf("run", "", [
+          OptionSpec.string("string", "String argument"
+            where short' = 't', default' = "default")
+          OptionSpec.i64("number", "Number argument"
+            where short' = 'i', default' = 0)
+          OptionSpec.u64("unumber", "Unsigned number argument"
+            where short' = 'u', default' = 0)
+          OptionSpec.f64("float", "Float argument"
+            where short' = 'c', default' = 0.0)
+        ], [])? .> add_help()?
+      else
+        env.exitcode(-1)  // some kind of coding error
+        return
+      end
+
+    let cmd =
+      match CommandParser(cs).parse(env.args, env.vars)
+      | let c: Command => c
+      | let ch: CommandHelp =>
+          ch.print_help(env.out)
+          env.exitcode(0)
+          return
+      | let se: SyntaxError =>
+          env.out.print(se.string())
+          env.exitcode(1)
+          return
+      end
+
+    let string = cmd.option("string").string()
+    let number = cmd.option("number").i64()
+    let unumber = cmd.option("unumber").u64()
+    let float = cmd.option("float").f64()
+
+    env.out.print("The String is " + string)
+    env.out.print("The Number is " + number.string())
+    env.out.print("The UNumber is " + unumber.string())
+    env.out.print("The Float is " + float.string())
+```