module Athena::DependencyInjection::Extension::Schema

Overview

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.

Defined in:

extension.cr

Macro Summary

Macro Detail

macro 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]
macro array_of?(name, *members) #

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


[View source]
macro 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][Athena::DependencyInjection::Extension::Schema--member-markup]


[View source]
macro object_of?(name, *members) #

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


[View source]
macro 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]