types 0.2.0 → 0.4.0

data/readme.md

@@ -0,0 +1,71 @@
+# Types
+
+Provides abstract types for the Ruby programming language which can used for documentation and evaluation purposes.
+
+[![Development Status](https://github.com/ioquatix/types/workflows/Test/badge.svg)](https://github.com/ioquatix/types/actions?workflow=Test)
+
+## Motivation
+
+I've been working on documentation tools and Ruby has several implementations for adding type information. However, I've feel like we've over-complicated the language of types and I'd like something simpler and more compatible with the Ruby language.
+
+The original design started in [bake](https://github.com/ioquatix/bake) which uses `@parameter name [Signature] description` comments to document the types of parameters. The command-line interface of bake uses the type signature to coerce string arguments to the desired type. This has been a useful strategy to reduce code duplication and to make the code more readable.
+
+Subsequently, I started using these type signatures in [decode](https://github.com/ioquatix/decode) which uses similar `@parameter` comments. This information is fed into [utopia-project](https://github.com/socketry/utopia-project) which can present this information as part of the generated documentation.
+
+The expressions possible with this gem are a subset of all possible expressions in Ruby's type system. This is by design. At some point in the future, it is likely we will automate conversion of type signatures to the RBS compatible type signature files. This will allow us to use the same type signatures in the documentation and in the code.
+
+## Installation
+
+``` shell
+bundle add types
+```
+
+## Usage
+
+Parsing type signatures can be done using {ruby Types.parse} which returns a object that represents the given type, e.g.
+
+``` ruby
+string_type = Types.parse("String")
+string_type # => Types::String
+
+array_type = Types.parse("Array(String)")
+array_type.class # => Types::Array
+
+hash_type = Types.parse("Hash(String, Integer)")
+hash_type.key_type # => Types::String
+hash_type.value_type # => Types::Integer
+```
+
+You can generate a string representation of a type too:
+
+``` ruby
+# A lambda that takes an Integer as an argument and returns an Integer:
+lambda_type = Types.parse("Lambda(Integer, returns: Integer)")
+lambda_type.to_s # => "Lambda(Integer, returns: Integer)"
+```
+
+### String Parsing
+
+In addition, you can coerce strings into strongly typed values:
+
+``` ruby
+array_type = Types.parse("Array(String)")
+array_type.parse("'foo', 'bar'") # => ["foo", "bar"]
+```
+
+This can be useful for argument parsing.
+
+### Documentation
+
+This gem is designed to be integrated into documentation tools. It provides a way to document the types of parameters and return values of a function. This information is stored in `@parameter` and `@returns` comments.
+
+``` ruby
+# Double the value of a number.
+# @parameter value [Numeric] The value to double.
+# @returns [Numeric] The doubled value.
+def double(value)
+	return value * 2
+end
+```
+
+The motivation for discrete parameter and return types is to make integration with documentation tools easier. Specifically, language servers can use this information to provide context sensitive type information and documentation which is hard to do with existing formats like `rdoc`.

metadata

@@ -1,49 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: types
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIEhDCCAuygAwIBAgIBATANBgkqhkiG9w0BAQsFADA3MTUwMwYDVQQDDCxzYW11
-  ZWwud2lsbGlhbXMvREM9b3Jpb250cmFuc2Zlci9EQz1jby9EQz1uejAeFw0yMTA4
-  MTYwNjMzNDRaFw0yMjA4MTYwNjMzNDRaMDcxNTAzBgNVBAMMLHNhbXVlbC53aWxs
-  aWFtcy9EQz1vcmlvbnRyYW5zZmVyL0RDPWNvL0RDPW56MIIBojANBgkqhkiG9w0B
-  AQEFAAOCAY8AMIIBigKCAYEAyXLSS/cw+fXJ5e7hi+U/TeChPWeYdwJojDsFY1xr
-  xvtqbTTL8gbLHz5LW3QD2nfwCv3qTlw0qI3Ie7a9VMJMbSvgVEGEfQirqIgJXWMj
-  eNMDgKsMJtC7u/43abRKx7TCURW3iWyR19NRngsJJmaR51yGGGm2Kfsr+JtKKLtL
-  L188Wm3f13KAx7QJU8qyuBnj1/gWem076hzdA7xi1DbrZrch9GCRz62xymJlrJHn
-  9iZEZ7AxrS7vokhMlzSr/XMUihx/8aFKtk+tMLClqxZSmBWIErWdicCGTULXCBNb
-  E/mljo4zEVKhlTWpJklMIhr55ZRrSarKFuW7en0+tpJrfsYiAmXMJNi4XAYJH7uL
-  rgJuJwSaa/dMz+VmUoo7VKtSfCoOI+6v5/z0sK3oT6sG6ZwyI47DBq2XqNC6tnAj
-  w+XmCywiTQrFzMMAvcA7rPI4F0nU1rZId51rOvvfxaONp+wgTi4P8owZLw0/j0m4
-  8C20DYi6EYx4AHDXiLpElWh3AgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8E
-  BAMCBLAwHQYDVR0OBBYEFB6ZaeWKxQjGTI+pmz7cKRmMIywwMC4GA1UdEQQnMCWB
-  I3NhbXVlbC53aWxsaWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWB
-  I3NhbXVlbC53aWxsaWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEB
-  CwUAA4IBgQBVoM+pu3dpdUhZM1w051iw5GfiqclAr1Psypf16Tiod/ho//4oAu6T
-  9fj3DPX/acWV9P/FScvqo4Qgv6g4VWO5ZU7z2JmPoTXZtYMunRAmQPFL/gSUc6aK
-  vszMHIyhtyzRc6DnfW2AiVOjMBjaYv8xXZc9bduniRVPrLR4J7ozmGLh4o4uJp7w
-  x9KCFaR8Lvn/r0oJWJOqb/DMAYI83YeN2Dlt3jpwrsmsONrtC5S3gOUle5afSGos
-  bYt5ocnEpKSomR9ZtnCGljds/aeO1Xgpn2r9HHcjwnH346iNrnHmMlC7BtHUFPDg
-  Ts92S47PTOXzwPBDsrFiq3VLbRjHSwf8rpqybQBH9MfzxGGxTaETQYOd6b4e4Ag6
-  y92abGna0bmIEb4+Tx9rQ10Uijh1POzvr/VTH4bbIPy9FbKrRsIQ24qDbNJRtOpE
-  RAOsIl+HOBTb252nx1kIRN5hqQx272AJCbCjKx8egcUQKffFVVCI0nye09v5CK+a
-  HiLJ8VOFx6w=
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2022-07-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- agent.md
+- context/usage.md
 - lib/types.rb
 - lib/types/any.rb
 - lib/types/array.rb
@@ -55,20 +55,24 @@ files:
 - lib/types/generic.rb
 - lib/types/hash.rb
 - lib/types/integer.rb
+- lib/types/interface.rb
 - lib/types/lambda.rb
 - lib/types/method.rb
+- lib/types/named.rb
 - lib/types/nil.rb
 - lib/types/numeric.rb
 - lib/types/string.rb
 - lib/types/symbol.rb
 - lib/types/tuple.rb
 - lib/types/version.rb
+- license.md
+- readme.md
 homepage: https://github.com/ioquatix/types
 licenses:
 - MIT
 metadata:
   funding_uri: https://github.com/sponsors/ioquatix/
-post_install_message:
+  source_code_uri: https://github.com/ioquatix/types.git
 rdoc_options: []
 require_paths:
 - lib
@@ -76,15 +80,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A simple human-readable and Ruby-parsable type library.
 test_files: []