[URI] Adds support for lists of contexts and ids. (#5)

It is now possible to create URIs with a given list of possible context and ids.

Author: mitnal

README.md

@@ -21,22 +21,27 @@ gem 'studitemps-utils'
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install studitemps-utils
+```shell
+$ gem install studitemps-utils
+```
 
 ## URI
 
 An Studitemps Utils URI references similar to a normal URI a specific resource. It contains at least a `schema` but most
 of the time when used to reference a resource it also has a `context`, `resource`, and an `id`.
 
 Example: `com.example:billing:invoice:R422342`
-- schema: `com.example` - Some kind of schema to make URI globally unique.
-- context: `billing` - The context the URI (and the resource) belongs to.
-- resource: `invoice` - The resource type.
-- id: `R422342` - The resource id.
+
+-   schema: `com.example` - Some kind of schema to make URI globally unique.
+-   context: `billing` - The context the URI (and the resource) belongs to.
+-   resource: `invoice` - The resource type.
+-   id: `R422342` - The resource id.
 
 ### Usage
 
@@ -52,6 +57,18 @@ uri.to_s # => 'com.example:billing:invoice:R422342'
 InvoiceURI.build('com.example:billing:invoice:R422342') # => #<InvoiceURI 'com.example:billing:invoice:R422342'>
 InvoiceURI.build(id: 'R422342') # => #<InvoiceURI 'com.example:billing:invoice:R422342'>
 InvoiceURI.build(uri) # => #<InvoiceURI 'com.example:billing:invoice:R422342'>
+
+# `resource` and `id` supports array so that `.build` will verify every value for a given string.
+# If we also want to check the initializer we can use the "types" extension to do so:
+require 'studitemps/utils/uri/extensions/types'
+
+InvoiceURI = Studitemps::Utils::URI.build(
+  schema: 'com.example', context: 'billing', resource: 'invoice', id: %w[final past_due]
+)
+
+InvoiceURI.build('com.example:billing:invoice:pro_forma') # => Studitemps::Utils::URI::Base::InvalidURI
+InvoiceURI.new(id: 'final') # => #<InvoiceURI 'com.example:billing:invoice:final'>
+InvoiceURI.new(id: 'pro_forma') # => Dry::Types::ConstraintError
 ```
 
 ### Extensions
@@ -75,11 +92,12 @@ MyBaseURI.load('com.example:billing:invoice:R422342') # =>  #<MyBaseURI 'com.exa
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
+
 <!-- To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/STUDITEMPS/studitemps-utils.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/STUDITEMPS/studitemps-utils>.
 
 ## License
 

lib/studitemps/utils/uri.rb

@@ -41,8 +41,8 @@ module URI
       #
       #  ExampleURI.build('com.example:billing:invoice:R422342')
       #  # => #<ExampleURI 'com.example:billing:invoice:R422342'>
-      def build(schema: nil, context: nil, resource: nil, from: Base)
-        Builder.new.call(schema: schema, context: context, resource: resource, superclass: from)
+      def build(schema: nil, context: nil, resource: nil, id: nil, from: Base)
+        Builder.new.call(schema: schema, context: context, resource: resource, id: id, superclass: from)
       end
     end
   end

lib/studitemps/utils/uri/base.rb

@@ -14,6 +14,13 @@ class InvalidURI < StandardError; end
         defines :schema
         defines :context
         defines :resource
+        defines :id
+
+        # @!parse
+        #   # Regular expression which the string representation of the URI has to match.
+        #   #   `value` - matches the exact value
+        #   #   `enum` - matches any of the given values
+        #   REGEX = /\A(?<schema>`value`)\:(?<context>`value`)(:(?<resource>`enum`)(:(?<id>`enum`))?)?\z/
 
         # Returns string representation of URI.
         #

lib/studitemps/utils/uri/builder.rb

@@ -15,17 +15,18 @@ class Builder
         #
         # @param [String, nil] schema the schema part of the new URI
         # @param [String, nil] context the context part of the new URI
-        # @param [String, nil] resource the resource part of the new URI
+        # @param [String, [String], nil] resource the resource part of the new URI
+        # @param [String, [String], nil] id the optional fixed id part of the new URI
         # @param [String] superclass uri base class
         # @return [Base] the new URI class
         #
         # @note Use {URI.build} instead to create new URI classes
         # @api private
-        def call(schema: nil, context: nil, resource: nil, superclass: ::Studitemps::Utils::URI::Base)
+        def call(schema: nil, context: nil, resource: nil, id: nil, superclass: ::Studitemps::Utils::URI::Base)
           raise ArgumentError, 'missing schema' if superclass == ::Studitemps::Utils::URI::Base && schema.nil?
 
           klass = build_class(superclass)
-          configure_class(klass, schema, context, resource)
+          configure_class(klass, schema, context, resource, id)
           build_regex(klass)
           build_initializer(klass)
           run_extensions(klass)
@@ -38,41 +39,61 @@ def build_class(superclass)
           Class.new(superclass)
         end
 
-        def configure_class(klass, new_schema, new_context, new_resource)
+        def configure_class(klass, new_schema, new_context, new_resource, new_id)
           klass.class_eval do
             schema new_schema if new_schema
             context new_context if new_context
             resource new_resource if new_resource
+            id new_id if new_id
           end
         end
 
-        def build_regex(klass, default: '[\w\-_]+')
-          schema = Regexp.escape(klass.schema)
-          context = klass.context ? Regexp.escape(klass.context) : default
-          resource = klass.resource ? Regexp.escape(klass.resource) : default
+        def build_regex(klass)
           regex = /\A
-            (?<schema>#{schema})\:
-            (?<context>#{context})
-            (:(?<resource>#{resource})
-            (:(?<id>.*))?)?
+            (?<schema>#{value_regex(:schema, klass)})\:
+            (?<context>#{value_regex(:context, klass)})
+            (:(?<resource>#{enum_regex(:resource, klass)})
+            (:(?<id>#{enum_regex(:id, klass, default: '.*')}))?)?
           \z/x
           klass.const_set('REGEX', regex.freeze)
         end
 
         def build_initializer(klass) # rubocop:disable Metrics/AbcSize
-          klass.class_eval do
-            include Dry::Initializer[undefined: false].define -> {
-              option :schema, proc(&:to_s), optional: false, default: -> { klass.schema }
-              option :context, proc(&:to_s), optional: true, default: -> { klass.context }
-              option :resource, proc(&:to_s), optional: true, default: -> { klass.resource }
-              option :id, proc(&:to_s), optional: true
-            }
-          end
+          klass.extend Dry::Initializer[undefined: false]
+
+          klass.option :schema, type: schema_type(klass), optional: false, default: -> { klass.schema }
+          klass.option :context, type: context_type(klass), optional: true, default: -> { klass.context }
+          klass.option :resource, type: resource_type(klass), optional: true,
+            default: -> { Array(klass.resource).first }
+          klass.option :id, type: id_type(klass), optional: true
         end
 
         def run_extensions(klass)
           self.class.extensions.each { |extension| extension.call(klass) }
         end
+
+        def value_regex(value, klass, default: '[\w\-_]+')
+          return default unless klass.send(value)
+
+          Regexp.escape(klass.send(value))
+        end
+
+        def enum_regex(value, klass, default: '[\w\-_]+')
+          return default unless klass.send(value)
+
+          values = Array(klass.send(value)).map { |v| Regexp.escape(v) }
+          "(#{values.join('|')})"
+        end
+
+        def default_type
+          proc(&:to_s)
+        end
+
+        %i[schema context resource id].each do |attribute|
+          define_method "#{attribute}_type" do |_klass|
+            default_type
+          end
+        end
       end
     end
   end

lib/studitemps/utils/uri/extensions/types.rb

@@ -32,6 +32,54 @@ module Types
             types.const_set 'String', Dry.Types.Constructor(klass) { |value| klass.build(value).to_s }
             klass.const_set 'Types', types
           }
+
+        end
+      end
+
+      ##
+      # Adds type checks to initializer arguments.
+      # `schema` and `context` values are checked and `resource` and `id` are checked against a possible list of
+      # values (enum if URI builder is provided with an array as the argument).
+      #
+      # @example
+      #   require 'studitemps/utils/uri/extensions/types'
+      #   InvoiceURI = Studitemps::Utils::URI.build(
+      #     schema: 'com.example', context: 'billing', resource: 'invoice', id: %w[final past_due]
+      #   )
+      #
+      #   InvoiceURI.new(id: 'final') # => #<InvoiceURI 'com.example:billing:invoice:final'>
+      #   InvoiceURI.new(id: 'pro_forma') # => Dry::Types::ConstraintError
+      #
+      # @since 0.2.0
+      class Builder
+        private
+
+        def schema_type(klass)
+          value_type(:schema, klass)
+        end
+
+        def context_type(klass)
+          value_type(:context, klass)
+        end
+
+        def resource_type(klass)
+          enum_type(:resource, klass)
+        end
+
+        def id_type(klass)
+          enum_type(:id, klass)
+        end
+
+        def value_type(value, klass, default: default_type)
+          return default unless klass.send(value)
+
+          Dry.Types::Value(klass.send(value))
+        end
+
+        def enum_type(value, klass, default: default_type)
+          return default unless klass.send(value)
+
+          Dry.Types::Strict::String.enum(*Array(klass.send(value)))
         end
       end
     end