sprinkles-opts 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa12d8ee5410cdbd3e47d4f1b2e1cec293b9097208dbbaae043d7804da3153cf
-  data.tar.gz: 3ae63c4d2bc388276778ae46809571f4b4e975a90f2618ab7ce73427245fc67b
+  metadata.gz: 9e4b137fd5adbc7abaf8dcf83d4129fb99762dd1312373c596be6894814085da
+  data.tar.gz: f2980f5b6f3abf8906049759ed1f1edeec7f3986bd57278670b75abb0fe9a2b2
 SHA512:
-  metadata.gz: fa177fc8e6752839665457657eff697776e12324dfab2ce47b0f59be0c28729346ec246818a4c135cea07ca7b4aefb6b5da2ccb12ca513c72324751751e37ecf
-  data.tar.gz: 63963328fb25de91205f032fc86332b1dc25066b5cc8bf2756e8cf7300e4af330eabe17a4448bd69104fa6bbcea6512cae6494139f9090ff20d93c431845c396
+  metadata.gz: 37b02710c9b1e6bf6189aeae192e7a805aba61cc0d6518b3fdc60e369cd145f723a22c1510bf53ab7197b322a9ecb48c657102a86deeca426ec254c6c074fa7c
+  data.tar.gz: ac3191f10b60d631f2a4e1e2cfafbca62ff87c4e9a9b06e66664fc8253aecf6acf8cafa835c65d75d09031a6baceeb6901292e58c452a804092d7a175dcc3743

data/.github/workflows/ruby.yml

@@ -19,18 +19,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6', '2.7']
+        ruby-version: ['3.0', '3.1', '3.2', '3.3', '4.0']
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
     - name: Set up Ruby
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-    # uses: ruby/setup-ruby@v1
-      uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+        bundler-cache: true
     - name: Run tests
       run: bundle exec rake
     - name: Typecheck

data/.gitignore

@@ -7,3 +7,6 @@
 /spec/reports/
 /tmp/
 *~
+bin/tapioca
+.ruby-version
+Gemfile.lock

data/README.md

@@ -5,16 +5,16 @@ argument parsing.
 
 ## Basic usage
 
-Create a class that is a subclass of `Spinkles::Opts::GetOpt`. Define fields and their types with `const`, analogously to [how you would with `T::Struct`](), but those fields can have `short:` and `long:` options that map to the flags used to provide them. You'll also have to provide a value for `program_name` by overriding an abstract method:
+Create a class that is a subclass of `Spinkles::Opts::GetOpt`. Define fields and their types with `const`, analogously to [how you would with `T::Struct`](https://sorbet.org/docs/tstruct), but those fields can have `short:` and `long:` options that map to the comman-line options used to provide them. You may also provide a value for `program_name` by overriding an abstract method, which will otherwise default to `$PROGRAM_NAME`:
 
 ```ruby
 class MyOptions < Sprinkles::Opts::GetOpt
-  sig {override.returns(String)}
-  def self.program_name; "my-program"; end
+  sig { override.returns(String) }
+  def self.program_name = "my-program"
 
-  const :input, String, short: 'i', long: 'input'
-  const :num_iterations, Integer, short: 'n', placeholder: 'N'
-  const :verbose, T::Boolean, short: 'v', long: 'verbose', factory: -> {false}
+  const :input, String, short: "i", long: "input"
+  const :num_iterations, Integer, short: "n", placeholder: "N"
+  const :verbose, T::Boolean, short: "v", long: "verbose", factory: -> { false }
 end
 ```
 
@@ -22,7 +22,7 @@ You can then call `MyOptions.parse(ARGV)` in order to get a value of type `MyOpt
 
 ```ruby
 opts = MyOptions.parse(%w{-i foo -n 8 --verbose})
-assert_equal('foo', opts.input)
+assert_equal("foo", opts.input)
 assert_equal(8, opts.num_iterations)
 assert_equal(true, opts.verbose)
 ```
@@ -33,16 +33,13 @@ Fields without a `short:` or `long:` parameter will be understood to be position
 
 ```ruby
 class PosOptions < Sprinkles::Opts::GetOpt
-  sig {override.returns(String)}
-  def self.program_name; "positional-options"; end
-
   const :source, String
   const :destination, String
 end
 
 opts = PosOptions.parse(%w{this that})
-assert_equal('this', opts.source)
-assert_equal(that, opts.destination)
+assert_equal("'this", opts.source)
+assert_equal("that", opts.destination)
 ```
 
 Parsing will fail and exit the program with a usage statement if either too many or too few positional parameters are provided.
@@ -55,11 +52,13 @@ opts = PosOptions.parse(%w{this})
 #     -h, --help                       Prints this help
 ```
 
+In addition to only providing `const` (and therefore not allowing writer methods for the relevant fields) the resulting objects has been frozen and cannot be mutated at all, even by other methods. The intended use of a `GetOpt` subclass is as a pure data container; any other logic should be implemented as a wrapper around the container.
+
 ## Optional arguments
 
 There are two ways of making arguments optional:
 - A field whose type is marked as `T.nilable` will implicitly be initialized as `nil` if it is not provided.
-- A field can have a `factory:` which should be a lambda that will be called to initialize the field if the argument is not provided.
+- A field can have a `factory:` which should be a proc that will be called to initialize the field if the argument is not provided.
 
 Fields that are not `T.nilable` and do not have a `factory:` must be provided when parsing arguments.
 
@@ -67,9 +66,6 @@ For _positional_ arguments, there's currently an extra restriction: all mandator
 
 ```ruby
 class PosOptions < Sprinkles::Opts::GetOpt
-  sig {override.returns(String)}
-  def self.program_name; "positional-options"; end
-
   const :a, String
   const :b, T.nilable(String)
   const :c, T.nilable(String)
@@ -117,6 +113,33 @@ PosArray.parse(%w{-a 5})         # a is [5]
 PosArray.parse(%w{-a 22 -a 33})  # a is [22, 33]
 ```
 
+## Other data types
+
+Not all types are valid, and invalid types will cause a load-time exception. Basic Ruby types including `String`, `Symbol`, `Integer`, and `Float` are all valid field types, as well as a few gem-provided types like `Date` and `URI`. You can also provide a Sorbet `T::Enum` type and it will deserialize it from the provided value if possible.
+
+Additionally, you can use a `T.any` of multiple types, and arguments will use successive attempts at parsing, falling back on the later types if the provided string cannot be parsed as an earlier type. One note is that it will attempt parsing in the order of the `T.any`, but some types will always parse correctly: for example, if you have a field whose type is `T.any(String, URI)`, then the field will never actually be set to a `URI` because it's impossible to provide an invalid `String` value.
+
+```ruby
+class TrafficLight < T::Enum
+  enums do
+    Green = new("green")
+    Yellow = new("yellow")
+    Red = new("red")
+  end
+end
+
+class OtherValues < Sprinkles::Opts::GetOpt
+  const :num, Integer, short: "n"
+  const :date, Date, short: "d"
+  const :tl, TrafficLight, short: "t"
+end
+
+OtherValues.parse(%w{-d 2015-07-01 -n 33 -t yellow})
+# num is 22
+# date is Date.new(2015, 07, 01)
+# tl is TrafficLight::Yellow
+```
+
 ## Help text and descriptions
 
 The option names `-h` and `--help` are reserved, and when they are provided the program will print a usage panel and exit:
@@ -131,7 +154,6 @@ Usage: my-program --input=VALUE -nN
 
 Individual fields can customize their default placeholder text away from the default `VALUE` using the `placeholder:` argument, and can provide more extensive descriptions using the `description:` argument.
 
-
 ## Why sprinkles?
 
 Well, because it's a Sorbet topping. I have other unfinished ideas for how to leverage Sorbet to write certain abstractions, and my thought was that it might be nice to put them in a common namespace.

data/Rakefile

@@ -1,10 +1,10 @@
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task default: :test
+task(default: :test)

data/lib/sprinkles/opts/version.rb

@@ -3,6 +3,6 @@
 
 module Sprinkles
   module Opts
-    VERSION = '0.1.0'
+    VERSION = "0.2.0"
   end
 end