annotation Schema::Definition::Scalar

Overview

Annotate a type to mark it as a scalar, so a single string query value will be tried to cast. For example, Int32 is scalar by default, thus in case "foo=42", "42" is tried to cast to Int32.

Good candidates to become scalar: URI and Time; for example:

@[Schema::Definition::Scalar]
class URI
  def to_http_param(builder : HTTP::Params::Builder, key : String)
    builder.add(key, to_s)
  end

  def self.from_http_param(value : String)
    return URI.parse(value)
  end
end

struct MyParams
  include Schema::Definition
  getter uri : URI
end

params = MyParams.from_query("uri=https://example.com")
pp params.uri # => <URI @host="example.com" ...>

URI and Time::EpochConverter extensions are shipped by default:

require "schema"
require "schema/ext/uri"
require "schema/ext/time/epoch_converter"

struct MyParams
  include Schema::Definition

  getter uri : URI

  @[Schema::Param(converter: Time::EpochConverter)]
  getter time : Time
end

If you have annotated a type as scalar, then it must implement these methods:

def to_http_param(builder : HTTP::Params::Builder, key : String)
  # E.g. builder.add(key, self.to_s)
end

def self.from_http_param(value : String) : self
  # E.g. value.to_s
end

Otherwise (if the type is not Scalar), the methods become a little more complex:

def to_http_param(builder : HTTP::Params::Builder, key : String? = nil)
  # Notice the *key* is nilable
end

# Or if you're using a converter on a param:
def to_http_param(builder : HTTP::Params::Builder, key : String? = nil, converter : C = nil) forall C
  # ditto
end

def self.from_http_param(query : String, path : Tuple) : self
  # Notice the *path* argument
end

# Or if you're using a converter on a param:
def self.from_http_param(query : String, path : Tuple, converter : C = nil) : self forall C
  # ditto
end

Defined in:

schema/annotations.cr