rest_framework 1.0.0.rc1 → 1.0.1

data/lib/rest_framework/mixins/model_controller_mixin.rb

@@ -5,13 +5,13 @@ module RESTFramework::Mixins::BaseModelControllerMixin
     return value unless BASE64_REGEX.match?(value)
 
     _, content_type, payload = value.match(BASE64_REGEX).to_a
-    return {
+    {
       io: StringIO.new(Base64.decode64(payload)),
       content_type: content_type,
       filename: "file_#{field}#{Rack::Mime::MIME_TYPES.invert[content_type]}",
     }
   }
-  ACTIVESTORAGE_KEYS = [:io, :content_type, :filename, :identify, :key]
+  ACTIVESTORAGE_KEYS = [ :io, :content_type, :filename, :identify, :key ]
 
   include RESTFramework::BaseControllerMixin
 
@@ -23,27 +23,30 @@ module RESTFramework::Mixins::BaseModelControllerMixin
     # Attributes for configuring record fields.
     fields: nil,
     field_config: nil,
+    read_only_fields: RESTFramework.config.read_only_fields,
+    write_only_fields: RESTFramework.config.write_only_fields,
+    hidden_fields: nil,
 
     # Attributes for finding records.
     find_by_fields: nil,
-    find_by_query_param: "find_by",
+    find_by_query_param: "find_by".freeze,
 
     # Options for what should be included/excluded from default fields.
     exclude_associations: false,
 
     # Options for handling request body parameters.
     allowed_parameters: nil,
-    filter_pk_from_request_body: true,
-    exclude_body_fields: RESTFramework.config.exclude_body_fields,
 
     # Attributes for the default native serializer.
     native_serializer_config: nil,
     native_serializer_singular_config: nil,
     native_serializer_plural_config: nil,
-    native_serializer_only_query_param: "only",
-    native_serializer_except_query_param: "except",
+    native_serializer_only_query_param: "only".freeze,
+    native_serializer_except_query_param: "except".freeze,
+    native_serializer_include_query_param: "include".freeze,
+    native_serializer_exclude_query_param: "exclude".freeze,
     native_serializer_associations_limit: nil,
-    native_serializer_associations_limit_query_param: "associations_limit",
+    native_serializer_associations_limit_query_param: "associations_limit".freeze,
     native_serializer_include_associations_count: false,
 
     # Attributes for filtering, ordering, and searching.
@@ -51,19 +54,19 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       RESTFramework::QueryFilter,
       RESTFramework::OrderingFilter,
       RESTFramework::SearchFilter,
-    ],
+    ].freeze,
     filter_recordset_before_find: true,
     filter_fields: nil,
     ordering_fields: nil,
-    ordering_query_param: "ordering",
+    ordering_query_param: "ordering".freeze,
     ordering_no_reorder: false,
     search_fields: nil,
-    search_query_param: "search",
+    search_query_param: "search".freeze,
     search_ilike: false,
     ransack_options: nil,
-    ransack_query_param: "q",
+    ransack_query_param: "q".freeze,
     ransack_distinct: true,
-    ransack_distinct_query_param: "distinct",
+    ransack_distinct_query_param: "distinct".freeze,
 
     # Options for association assignment.
     permit_id_assignment: true,
@@ -74,7 +77,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
   }
 
   module ClassMethods
-    IGNORE_VALIDATORS_WITH_KEYS = [:if, :unless].freeze
+    IGNORE_VALIDATORS_WITH_KEYS = [ :if, :unless ].freeze
 
     def get_model
       return @model if @model
@@ -91,7 +94,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
 
     # Override to include ActiveRecord i18n-translated column names.
     def label_for(s)
-      return self.get_model.human_attribute_name(s, default: super)
+      self.get_model.human_attribute_name(s, default: super)
     end
 
     # Get the available fields. Fallback to this controller's model columns, or an empty array. This
@@ -121,7 +124,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         input_fields = input_fields.map(&:to_s)
       end
 
-      return input_fields
+      input_fields
     end
 
     # Get a full field configuration, including defaults and inferred values.
@@ -135,13 +138,15 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       reflections = model.reflections
       attributes = model._default_attributes
       readonly_attributes = model.readonly_attributes
-      exclude_body_fields = self.exclude_body_fields&.map(&:to_s)
+      read_only_fields = self.read_only_fields&.map(&:to_s)&.to_set || Set[]
+      write_only_fields = self.write_only_fields&.map(&:to_s)&.to_set || Set[]
+      hidden_fields = self.hidden_fields&.map(&:to_s)&.to_set || Set[]
       rich_text_association_names = model.reflect_on_all_associations(:has_one)
         .collect(&:name)
         .select { |n| n.to_s.start_with?("rich_text_") }
       attachment_reflections = model.attachment_reflections
 
-      return @field_configuration = self.get_fields.map { |f|
+      @field_configuration = self.get_fields.map { |f|
         cfg = field_config[f]&.dup || {}
         cfg[:label] ||= self.label_for(f)
 
@@ -149,14 +154,29 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         if model.primary_key == f
           cfg[:primary_key] = true
 
-          unless cfg.key?(:readonly)
-            cfg[:readonly] = true
+          unless cfg.key?(:read_only)
+            cfg[:read_only] = true
           end
         end
 
-        # Annotate readonly attributes.
-        if f.in?(readonly_attributes) || f.in?(exclude_body_fields)
-          cfg[:readonly] = true
+        # Annotate field mutability and display properties.
+        cfg[:read_only] = true if f.in?(readonly_attributes) || f.in?(read_only_fields)
+        cfg[:write_only] = true if f.in?(write_only_fields)
+        cfg[:hidden] = true if f.in?(hidden_fields)
+
+        # Raise warnings on some bad combinations of properties.
+        if cfg[:write_only]
+          if cfg[:read_only]
+            Rails.logger.warn("RRF: `#{f}` write_only conflicts with read_only.")
+          end
+
+          if cfg[:hidden]
+            Rails.logger.warn("RRF: `#{f}` write_only implies hidden.")
+          end
+
+          if cfg[:hidden_from_index]
+            Rails.logger.warn("RRF: `#{f}` write_only implies hidden_from_index.")
+          end
         end
 
         # Annotate column data.
@@ -167,12 +187,12 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         end
 
         # Add default values from the model's schema.
-        if column_default = column_defaults[f] && !cfg[:default].nil?
-          cfg[:default] ||= column_default
+        if cfg[:default].nil? && (column_default = column_defaults[f])
+          cfg[:default] = column_default
         end
 
         # Add metadata from the model's attributes hash.
-        if attribute = attributes[f]
+        if attributes.key?(f) && attribute = attributes[f]
           if cfg[:default].nil? && default = attribute.value_before_type_cast
             cfg[:default] = default
           end
@@ -218,7 +238,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
               v[:kind] = "method"
             end
 
-            next [sf, v]
+            next [ sf, v ]
           }.to_h.compact.presence
 
           # Determine if we render id/ids fields. Unfortunately, `has_one` does not provide this
@@ -231,7 +251,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
           if self.permit_nested_attributes_assignment && (
             nested_opts = model.nested_attributes_options[f.to_sym].presence
           )
-            cfg[:nested_attributes_options] = {field: "#{f}_attributes", **nested_opts}
+            cfg[:nested_attributes_options] = { field: "#{f}_attributes", **nested_opts }
           end
 
           begin
@@ -256,6 +276,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         # Determine if this is just a method.
         if !cfg[:kind] && model.method_defined?(f)
           cfg[:kind] = "method"
+          cfg[:read_only] = true if cfg[:read_only].nil?
         end
 
         # Collect validator options into a hash on their type, while also updating `required` based
@@ -283,8 +304,8 @@ module RESTFramework::Mixins::BaseModelControllerMixin
           cfg[:validators][kind] << options
         end
 
-        next [f, cfg]
-      }.to_h.with_indifferent_access
+        next [ f, cfg ]
+      }.to_h.compact.with_indifferent_access
     end
 
     def openapi_schema
@@ -295,7 +316,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         required: field_configuration.select { |_, cfg| cfg[:required] }.keys,
         type: "object",
         properties: field_configuration.map { |f, cfg|
-          v = {title: cfg[:label]}
+          v = { title: cfg[:label] }
 
           if cfg[:kind] == "association"
             v[:type] = cfg[:reflection].collection? ? "array" : "object"
@@ -309,7 +330,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
             v[:type] = cfg[:type]
           end
 
-          v[:readOnly] = true if cfg[:readonly]
+          v[:readOnly] = true if cfg[:read_only]
           v[:default] = cfg[:default] if cfg.key?(:default)
 
           if enum_variants = cfg[:enum_variants]
@@ -324,7 +345,14 @@ module RESTFramework::Mixins::BaseModelControllerMixin
           v[:"x-rrf-kind"] = cfg[:kind] if cfg[:kind]
 
           if cfg[:reflection]
-            v[:"x-rrf-reflection"] = cfg[:reflection]
+            v[:"x-rrf-reflection"] = {
+              class_name: cfg[:reflection].class_name,
+              foreign_key: cfg[:reflection].foreign_key,
+              association_foreign_key: cfg[:reflection].association_foreign_key,
+              association_primary_key: cfg[:reflection].association_primary_key,
+              inverse_of: cfg[:reflection].inverse_of&.name,
+              join_table: cfg[:reflection].join_table,
+            }.compact
             v[:"x-rrf-association_pk"] = cfg[:association_pk]
             v[:"x-rrf-sub_fields"] = cfg[:sub_fields]
             v[:"x-rrf-sub_fields_metadata"] = cfg[:sub_fields_metadata]
@@ -332,15 +360,15 @@ module RESTFramework::Mixins::BaseModelControllerMixin
             v[:"x-rrf-nested_attributes_options"] = cfg[:nested_attributes_options]
           end
 
-          next [f, v]
+          next [ f, v ]
         }.to_h,
       }
 
-      return @openapi_schema
+      @openapi_schema
     end
 
     def openapi_schema_name
-      return @openapi_schema_name ||= self.name.chomp("Controller").gsub("::", ".")
+      @openapi_schema_name ||= self.name.chomp("Controller").gsub("::", ".")
     end
 
     def openapi_paths(_routes, tag)
@@ -358,7 +386,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
           if !extra_action && method != "options"  # rubocop:disable Style/Next
             # Add schema to request body content types.
             action.dig(:requestBody, :content)&.each do |_t, v|
-              v[:schema] = {"$ref" => "#/components/schemas/#{schema_name}"}
+              v[:schema] = { "$ref" => "#/components/schemas/#{schema_name}" }
             end
 
             # Add schema to successful response body content types.
@@ -368,7 +396,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
               response[:content]&.each do |t, v|
                 next if t == "text/html"
 
-                v[:schema] = {"$ref" => "#/components/schemas/#{schema_name}"}
+                v[:schema] = { "$ref" => "#/components/schemas/#{schema_name}" }
               end
             end
 
@@ -385,7 +413,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         end
       end
 
-      return paths
+      paths
     end
 
     def openapi_document(request, route_group_name, _routes)
@@ -396,7 +424,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       document[:components][:schemas] ||= {}
       document[:components][:schemas][self.openapi_schema_name] = self.openapi_schema
 
-      return document.merge(
+      document.merge(
         {
           "x-rrf-primary_key" => self.get_model.primary_key,
           "x-rrf-callbacks" => self._process_action_callbacks.as_json,
@@ -471,7 +499,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
   end
 
   def get_fields
-    return self.class.get_fields(input_fields: self.class.fields)
+    self.class.get_fields(input_fields: self.class.fields)
   end
 
   # Get a hash of strong parameters for the current action.
@@ -490,7 +518,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       config = self.class.field_configuration[f]
 
       # ActionText Integration:
-      if self.class.enable_action_text && reflections.key?("rich_test_#{f}")
+      if self.class.enable_action_text && reflections.key?("rich_text_#{f}")
         next f
       end
 
@@ -520,7 +548,7 @@ module RESTFramework::Mixins::BaseModelControllerMixin
         # TODO: Consider adjusting this based on `nested_attributes_options`.
         if self.class.permit_nested_attributes_assignment
           hash_variations["#{f}_attributes"] = (
-            config[:sub_fields] + ["_destroy"]
+            config[:sub_fields] + [ "_destroy" ]
           )
         end
 
@@ -534,11 +562,11 @@ module RESTFramework::Mixins::BaseModelControllerMixin
     @_get_allowed_parameters += variations
     @_get_allowed_parameters << hash_variations
 
-    return @_get_allowed_parameters
+    @_get_allowed_parameters
   end
 
   def get_serializer_class
-    return super || RESTFramework::NativeSerializer
+    super || RESTFramework::NativeSerializer
   end
 
   # Use strong parameters to filter the request body.
@@ -610,8 +638,8 @@ module RESTFramework::Mixins::BaseModelControllerMixin
     body_params = if allowed_params == true
       ActionController::Parameters.new(data).permit!
     elsif bulk_mode
-      pk = bulk_mode == :update ? [pk] : []
-      ActionController::Parameters.new(data).permit({_json: allowed_params + pk})
+      pk = bulk_mode == :update ? [ pk ] : []
+      ActionController::Parameters.new(data).permit({ _json: allowed_params + pk })
     else
       ActionController::Parameters.new(data).permit(*allowed_params)
     end
@@ -625,15 +653,13 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       body_params[k].unshift(*v)
     end
 
-    # Filter primary key, if configured.
-    if self.class.filter_pk_from_request_body && bulk_mode != :update
-      body_params.delete(pk)
+    # Filter read-only fields.
+    body_params.delete_if do |f, _|
+      cfg = self.class.field_configuration[f]
+      cfg && cfg[:read_only]
     end
 
-    # Filter fields in `exclude_body_fields`.
-    (self.class.exclude_body_fields || []).each { |f| body_params.delete(f) }
-
-    return body_params
+    body_params
   end
   alias_method :get_create_params, :get_body_params
   alias_method :get_update_params, :get_body_params
@@ -647,14 +673,14 @@ module RESTFramework::Mixins::BaseModelControllerMixin
       return model.all
     end
 
-    return nil
+    nil
   end
 
   # Filter the recordset and return records this request has access to.
   def get_records
     data = self.get_recordset
 
-    return @records ||= self.class.filter_backends&.reduce(data) { |d, filter|
+    @records ||= self.class.filter_backends&.reduce(data) { |d, filter|
       filter.new(controller: self).filter_data(d)
     } || data
   end
@@ -687,14 +713,14 @@ module RESTFramework::Mixins::BaseModelControllerMixin
 
     # Return the record. Route key is always `:id` by Rails' convention.
     if is_pk
-      return @record = collection.find(request.path_parameters[:id])
+      @record = collection.find(request.path_parameters[:id])
     else
-      return @record = collection.find_by!(find_by_key => request.path_parameters[:id])
+      @record = collection.find_by!(find_by_key => request.path_parameters[:id])
     end
   end
 
   # Determine what collection to call `create` on.
-  def get_create_from
+  def create_from
     if self.class.create_from_recordset
       # Create with any properties inherited from the recordset. We exclude any `select` clauses
       # in case model callbacks need to call `count` on this collection, which typically raises a
@@ -713,8 +739,8 @@ module RESTFramework::Mixins::BaseModelControllerMixin
     # the serializer directly. This would fail for active model serializers, but maybe we don't
     # care?
     s = RESTFramework::Utils.wrap_ams(self.get_serializer_class)
-    return records.map do |record|
-      s.new(record, controller: self).serialize.merge!({errors: record.errors.presence}.compact)
+    records.map do |record|
+      s.new(record, controller: self).serialize.merge!({ errors: record.errors.presence }.compact)
     end
   end
 end
@@ -743,7 +769,7 @@ module RESTFramework::Mixins::ListModelMixin
       end
     end
 
-    return records
+    records
   end
 end
 
@@ -762,7 +788,7 @@ module RESTFramework::Mixins::CreateModelMixin
 
   # Perform the `create!` call and return the created record.
   def create!
-    return self.get_create_from.create!(self.get_create_params)
+    self.create_from.create!(self.get_create_params)
   end
 end
 
@@ -776,7 +802,7 @@ module RESTFramework::Mixins::UpdateModelMixin
   def update!
     record = self.get_record
     record.update!(self.get_update_params)
-    return record
+    record
   end
 end
 
@@ -789,7 +815,7 @@ module RESTFramework::Mixins::DestroyModelMixin
 
   # Perform the `destroy!` call and return the destroyed (and frozen) record.
   def destroy!
-    return self.get_record.destroy!
+    self.get_record.destroy!
   end
 end
 

data/lib/rest_framework/paginators/page_number_paginator.rb

@@ -34,11 +34,11 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
     end
 
     # Ensure we return at least 1.
-    return [page_size, 1].max
+    [ page_size, 1 ].max
   end
 
   # Get the page and return it so the caller can serialize it.
-  def get_page(page_number=nil)
+  def get_page(page_number = nil)
     # If page number isn't provided, infer from the params or use 1 as a fallback value.
     unless page_number
       page_number = @controller&.params&.[](@controller.class.page_query_param&.to_sym)
@@ -55,7 +55,7 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
 
     # Get the data page and return it so the caller can serialize the data in the proper format.
     page_index = @page_number - 1
-    return @data.limit(@page_size).offset(page_index * @page_size)
+    @data.limit(@page_size).offset(page_index * @page_size)
   end
 
   # Wrap the serialized page with appropriate metadata.
@@ -63,13 +63,13 @@ class RESTFramework::Paginators::PageNumberPaginator < RESTFramework::Paginators
     page_query_param = @controller.class.page_query_param
     base_params = @controller.params.to_unsafe_h
     next_url = if @page_number < @total_pages
-      @controller.url_for({**base_params, page_query_param => @page_number + 1})
+      @controller.url_for({ **base_params, page_query_param => @page_number + 1 })
     end
     previous_url = if @page_number > 1
-      @controller.url_for({**base_params, page_query_param => @page_number - 1})
+      @controller.url_for({ **base_params, page_query_param => @page_number - 1 })
     end
 
-    return {
+    {
       count: @count,
       page: @page_number,
       page_size: @page_size,

data/lib/rest_framework/routers.rb

@@ -43,10 +43,10 @@ module ActionDispatch::Routing
         end
       end
 
-      return controller
+      controller
     end
 
-    # Interal interface for routing extra actions.
+    # Internal interface for routing extra actions.
     def _route_extra_actions(actions, &block)
       parsed_actions = RESTFramework::Utils.parse_extra_actions(actions)
 
@@ -84,13 +84,7 @@ module ActionDispatch::Routing
       unscoped = kwargs.delete(:unscoped)
 
       # Determine plural/singular resource.
-      force_singular = kwargs.delete(:force_singular)
-      force_plural = kwargs.delete(:force_plural)
-      if force_singular
-        singular = true
-      elsif force_plural
-        singular = false
-      elsif !controller_class.singleton_controller.nil?
+      if !controller_class.singleton_controller.nil?
         singular = controller_class.singleton_controller
       else
         singular = default_singular
@@ -98,7 +92,7 @@ module ActionDispatch::Routing
       resource_method = singular ? :resource : :resources
 
       # Call either `resource` or `resources`, passing appropriate modifiers.
-      skip = RESTFramework::Utils.get_skipped_builtin_actions(controller_class)
+      skip = RESTFramework::Utils.get_skipped_builtin_actions(controller_class, singular)
       public_send(resource_method, name, except: skip, **kwargs) do
         if controller_class.respond_to?(:extra_member_actions)
           member do
@@ -114,7 +108,7 @@ module ActionDispatch::Routing
           RESTFramework::RRF_BUILTIN_ACTIONS.each do |action, methods|
             next unless controller_class.method_defined?(action)
 
-            [methods].flatten.each do |m|
+            [ methods ].flatten.each do |m|
               public_send(m, "", action: action) if self.respond_to?(m)
             end
           end
@@ -123,7 +117,7 @@ module ActionDispatch::Routing
           RESTFramework::RRF_BUILTIN_BULK_ACTIONS.each do |action, methods|
             next unless controller_class.method_defined?(action)
 
-            [methods].flatten.each do |m|
+            [ methods ].flatten.each do |m|
               public_send(m, "", action: action) if self.respond_to?(m)
             end
           end
@@ -154,7 +148,7 @@ module ActionDispatch::Routing
     end
 
     # Route a controller without the default resourceful paths.
-    def rest_route(name=nil, **kwargs, &block)
+    def rest_route(name = nil, **kwargs, &block)
       controller = kwargs.delete(:controller) || name
       route_root_to = kwargs.delete(:route_root_to)
       if controller.is_a?(Class)
@@ -184,7 +178,7 @@ module ActionDispatch::Routing
           RESTFramework::RRF_BUILTIN_ACTIONS.each do |action, methods|
             next unless controller_class.method_defined?(action)
 
-            [methods].flatten.each do |m|
+            [ methods ].flatten.each do |m|
               public_send(m, "", action: action) if self.respond_to?(m)
             end
           end
@@ -201,7 +195,7 @@ module ActionDispatch::Routing
     end
 
     # Route a controller's `#root` to '/' in the current scope/namespace, along with other actions.
-    def rest_root(name=nil, **kwargs, &block)
+    def rest_root(name = nil, **kwargs, &block)
       # By default, use RootController#root.
       root_action = kwargs.delete(:action) || :root
       controller = kwargs.delete(:controller) || name || :root
@@ -211,7 +205,7 @@ module ActionDispatch::Routing
         kwargs[:path] = ""
       end
 
-      return rest_route(controller, route_root_to: root_action, **kwargs) do
+      rest_route(controller, route_root_to: root_action, **kwargs) do
         yield if block_given?
       end
     end

data/lib/rest_framework/serializers/active_model_serializer_adapter_factory.rb

@@ -1,18 +1,20 @@
 # This is a helper factory to wrap an ActiveModelSerializer to provide a `serialize` method which
 # accepts both collections and individual records. Use `.for` to build adapters.
+# :nocov:
 class RESTFramework::Serializers::ActiveModelSerializerAdapterFactory
   def self.for(active_model_serializer)
-    return Class.new(active_model_serializer) do
+    Class.new(active_model_serializer) do
       def serialize
         if self.object.respond_to?(:to_ary)
           return self.object.map { |r| self.class.superclass.new(r).serializable_hash }
         end
 
-        return self.serializable_hash
+        self.serializable_hash
       end
     end
   end
 end
+# :nocov:
 
 # Alias for convenience.
 # rubocop:disable Layout/LineLength

data/lib/rest_framework/serializers/base_serializer.rb

@@ -4,7 +4,7 @@ class RESTFramework::Serializers::BaseSerializer
   attr_accessor :object
 
   # Accept/ignore `*args` to be compatible with the `ActiveModel::Serializer#initialize` signature.
-  def initialize(object=nil, *args, controller: nil, **kwargs)
+  def initialize(object = nil, *args, controller: nil, **kwargs)
     @object = object
     @controller = controller
   end
@@ -16,24 +16,26 @@ class RESTFramework::Serializers::BaseSerializer
   end
 
   # Synonym for `serialize` for compatibility with `active_model_serializers`.
+  # :nocov:
   def serializable_hash(*args)
-    return self.serialize(*args)
+    self.serialize(*args)
   end
 
   # For compatibility with `active_model_serializers`.
   def self.cache_enabled?
-    return false
+    false
   end
 
   # For compatibility with `active_model_serializers`.
   def self.fragment_cache_enabled?
-    return false
+    false
   end
 
   # For compatibility with `active_model_serializers`.
   def associations(*args, **kwargs)
-    return []
+    []
   end
+  # :nocov:
 end
 
 # Alias for convenience.