Threadline.Evidence.Subject (Threadline v1.0.0)

Copy Markdown View Source

The closed set of subject names accepted by Threadline evidence records.

Use supported_subjects/0 to inspect the names, validate/1 to check a subject or descriptor, and supported?/1 when a boolean result is enough.

Summary

Types

subject_descriptor()

A subject name or descriptor. Recognized keys, in precedence order, are atom :subject, atom :name, string "subject", and string "name". Each recognized value may be an atom, string, or another descriptor, and nested recognized descriptors are normalized recursively. Key precedence applies at each nested level; unknown-only maps remain unchanged as unsupported values.

subject_input()

Any value accepted by the subject validator and predicate.

Functions

supported?(subject)

Returns true when a subject or subject descriptor is supported, and false for every other input.

supported_subjects()

Returns the six subject names accepted by Evidence record writers.

validate(subject)

Returns :ok for a supported subject or {:error, {:unsupported_subject, value}} otherwise.

Types

subject_descriptor()

@type subject_descriptor() ::
  atom()
  | String.t()
  | %{
      optional(:subject) => atom() | String.t() | subject_descriptor(),
      optional(:name) => atom() | String.t() | subject_descriptor()
    }
  | %{optional(String.t()) => atom() | String.t() | subject_descriptor()}

A subject name or descriptor. Recognized keys, in precedence order, are atom :subject, atom :name, string "subject", and string "name". Each recognized value may be an atom, string, or another descriptor, and nested recognized descriptors are normalized recursively. Key precedence applies at each nested level; unknown-only maps remain unchanged as unsupported values.

When a recognized key is present, other keys are ignored. If a map has no recognized key, it is returned unchanged as the unsupported value. The string-key map arm also represents extra keys and mixed atom/string maps.

subject_input()

@type subject_input() ::
  atom()
  | bitstring()
  | number()
  | %{optional(subject_input()) => subject_input()}
  | tuple()
  | list()
  | pid()
  | port()
  | reference()
  | function()

Any value accepted by the subject validator and predicate.

Functions

supported?(subject)

@spec supported?(subject_input()) :: boolean()

Returns true when a subject or subject descriptor is supported, and false for every other input.

supported_subjects()

@spec supported_subjects() :: [String.t()]

Returns the six subject names accepted by Evidence record writers.

validate(subject)

@spec validate(subject_input()) :: :ok | {:error, {:unsupported_subject, term()}}

Returns :ok for a supported subject or {:error, {:unsupported_subject, value}} otherwise.

The unsupported value is the normalized subject for recognized descriptors and the original input for values that cannot be normalized. The inventory is closed to supported_subjects/0.