Skip to content

module Athena::DependencyInjection::Extension::Schema #

Used to denote a module as an extension schema. Defines the configuration properties exposed to compile passes added via ADI.add_compiler_pass. Schemas must be registered via ADI.register_extension.

Experimental

This feature is intended for internal/advanced use and, for now, comes with limited public documentation.

Member Markup#

#object_of and #array_of support a special doc comment markup that can be used to better document each member of the objects. The markup consists of --- to denote the start and end of the block. >> denotes the start of the docs for a specific property. The name of the property followed by a : should directly follow. From there, any text will be attributed to that property, until the next >> or ---. Not all properties need to be included.

For example:

module Schema
  include ADI::Extension::Schema

  # Represents a connection to the database.
  #
  # ---
  # >>username: The username, should be set to `admin` for elevated privileges.
  # >>port: Defaults to the default PG port.
  # ---
  object_of? connection, username : String, password : String, port : Int32 = 5432
end

Warning

The custom markup is only supported when using mkdocs with some custom templates.

Macros#

array_of(name, *members)#

Similar to #object_of, but defines an array of objects. 

module Schema
  include ADI::Extension::Schema

  array_of rules,
    path : String,
    value : String
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    rules: [
      {path: "/foo", value: "foo"},
      {path: "/bar", value: "bar"},
    ],
  },
})

If not provided, the property defaults to an empty array.

View source

array_of?(name, *members)#

Same as #array_of but makes the default value of the property nil.

View source

object_of(name, *members)#

Defines a required strictly typed NamedTupleLiteral object with the provided name and members. The members consist of a variadic list of declarations, with optional default values. 

module Schema
  include ADI::Extension::Schema

  object_of connection,
    username : String,
    password : String,
    hostname : String = "localhost",
    port : Int32 = 5432
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    connection: {username: "admin", password: "abc123"},
  },
})

This macro is preferred over a direct NamedTuple type as it allows default values to be defined, and for the members to be documented via the special Member Markup

View source

object_of?(name, *members)#

Same as #object_of but makes the object optional, defaulting to nil.

View source

property(declaration)#

Defines a schema property via the provided declaration. The type may be any primitive Crystal type (String, Bool, Array, Hash, Enum, Number, etc).

module Schema
  include ADI::Extension::Schema

  property enabled : Bool = true
  property name : String
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    name: "Fred",
  },
})
View source