apiculture - v0.3.0

apiculture/key

Key generation, formatting, parsing, and inspection.

This is the implementation module behind the top-level apiculture API. It keeps generation plans (KeyConfig), finalized values (Key), and parse descriptions (KeyFormat) as separate types so each pipeline stage has an explicit meaning.

Types

Key

</>

A finalized serialized key and its inspectable sections.

bytes and content describe the content section. Checksum fields contain only the checksum that was rendered into value, when one is configured.

pub type Key {
  Key(
    value: String,
    bytes: BitArray,
    prefix: option.Option(String),
    separator: option.Option(String),
    content: String,
    checksum_name: option.Option(String),
    checksum_value: option.Option(String),
    checksum_bytes: option.Option(BitArray),
  )
}

Constructors

KeyConfig

</>

A chainable plan for generating or formatting a key.

A configuration can select secure random bytes, direct alphabet sampling, or existing bytes supplied by an import function. It becomes a finalized Key only through a terminal operation such as generate or from_bytes.

pub type KeyConfig {
  KeyConfig(
    byte_count: option.Option(Int),
    char_count: option.Option(Int),
    alphabet: option.Option(alphabet.Alphabet),
    encoding: option.Option(encoding.Encoding),
    prefix: option.Option(String),
    separator: option.Option(String),
    checksum: option.Option(checksum.Checksum),
    checksum_name: option.Option(String),
    checksum_bytes: option.Option(Int),
  )
}

Constructors

KeyFormat

</>

The serialized shape required by a key parser.

Unlike KeyConfig, this type does not describe how content was generated; parsing cannot recover whether the source was random bytes, a UUID, or ULID.

pub type KeyFormat {
  KeyFormat(
    prefix: option.Option(String),
    separator: String,
    encoding: encoding.Encoding,
    checksum: option.Option(checksum.Checksum),
    checksum_name: option.Option(String),
    checksum_bytes: option.Option(Int),
    content_byte_count: option.Option(Int),
  )
}

Constructors

KeySections

</>

The sections of a finalized key grouped for tooling and diagnostics.

pub type KeySections {
  KeySections(
    prefix: option.Option(String),
    separator: option.Option(String),
    content_value: String,
    content_bytes: BitArray,
    checksum_name: option.Option(String),
    checksum_value: option.Option(String),
    checksum_bytes: option.Option(BitArray),
  )
}

Constructors

Values

bytes

</> 
pub fn bytes(key: Key) -> BitArray

Returns the raw bytes that were used to generate the key. Returns the raw content bytes of a finalized key.

bytes_from_ulid

</> 
pub fn bytes_from_ulid(
  input: String,
) -> Result(BitArray, error.Error)

Parses a ULID into canonical 16-byte content.

bytes_from_uuid

</> 
pub fn bytes_from_uuid(
  input: String,
) -> Result(BitArray, error.Error)

Parses a UUID into canonical 16-byte content.

checksum_byte_count

</> 
pub fn checksum_byte_count(key: Key) -> Int

Returns the checksum byte count, or 0 when absent.

checksum_bytes

</> 
pub fn checksum_bytes(key: Key) -> option.Option(BitArray)

Returns the optional raw checksum bytes.

checksum_char_count

</> 
pub fn checksum_char_count(key: Key) -> option.Option(Int)

Returns the encoded checksum character count, when present.

checksum_name

</> 
pub fn checksum_name(key: Key) -> option.Option(String)

Returns the optional checksum algorithm name.

checksum_value

</> 
pub fn checksum_value(key: Key) -> option.Option(String)

Returns the optional encoded checksum section.

content_byte_count

</> 
pub fn content_byte_count(key: Key) -> Int

Returns the number of raw content bytes.

content_bytes

</> 
pub fn content_bytes(key: Key) -> BitArray

Returns the raw bytes represented by the content section.

content_char_count

</> 
pub fn content_char_count(key: Key) -> Int

Returns the number of characters in the encoded content section.

content_value

</> 
pub fn content_value(key: Key) -> String

Returns the encoded content section without surrounding metadata.

default_format

</> 
pub fn default_format() -> KeyFormat

Returns the strict parser format for the v0.3.0 default layout.

disable_checksum_name

</> 
pub fn disable_checksum_name(config: KeyConfig) -> KeyConfig

Removes only the checksum name while keeping the checksum enabled.

disable_prefix

</> 
pub fn disable_prefix(config: KeyConfig) -> KeyConfig

Removes the prefix from a configuration.

format_with_checksum

</> 
pub fn format_with_checksum(
  format: KeyFormat,
  checksum: checksum.Checksum,
) -> KeyFormat

Returns a parser format expecting the supplied checksum algorithm and name.

format_with_checksum_bytes

</> 
pub fn format_with_checksum_bytes(
  format: KeyFormat,
  count: Int,
) -> KeyFormat

Returns a parser format expecting the supplied checksum byte count.

format_with_content_bytes

</> 
pub fn format_with_content_bytes(
  format: KeyFormat,
  count: Int,
) -> KeyFormat

Returns a parser format expecting the supplied content byte count.

format_with_encoding

</> 
pub fn format_with_encoding(
  format: KeyFormat,
  encoding: encoding.Encoding,
) -> KeyFormat

Returns a parser format with a different content encoding.

format_with_prefix

</> 
pub fn format_with_prefix(
  format: KeyFormat,
  prefix: String,
) -> KeyFormat

Returns a parser format with the expected prefix changed.

format_with_separator

</> 
pub fn format_with_separator(
  format: KeyFormat,
  separator: String,
) -> KeyFormat

Returns a parser format with a different structural separator.

format_without_checksum

</> 
pub fn format_without_checksum(format: KeyFormat) -> KeyFormat

Returns a parser format that does not expect a checksum.

format_without_checksum_name

</> 
pub fn format_without_checksum_name(
  format: KeyFormat,
) -> KeyFormat

Returns a parser format that does not expect a checksum algorithm name.

format_without_prefix

</> 
pub fn format_without_prefix(format: KeyFormat) -> KeyFormat

Returns a parser format that does not expect a prefix.

from_bytes

</> 
pub fn from_bytes(
  config: KeyConfig,
  bytes: BitArray,
) -> Result(Key, error.Error)

Formats existing bytes according to a configuration.

from_ulid

</> 
pub fn from_ulid(input: String) -> Result(Key, error.Error)

Parses and formats a ULID using the default configuration.

from_ulid_with

</> 
pub fn from_ulid_with(
  config: KeyConfig,
  input: String,
) -> Result(Key, error.Error)

Compatibility alias for from_ulid_with_config.

from_ulid_with_config

</> 
pub fn from_ulid_with_config(
  config: KeyConfig,
  input: String,
) -> Result(Key, error.Error)

Parses and formats a ULID using a supplied configuration.

from_uuid

</> 
pub fn from_uuid(input: String) -> Result(Key, error.Error)

Parses and formats a UUID using the default configuration.

from_uuid_with

</> 
pub fn from_uuid_with(
  config: KeyConfig,
  input: String,
) -> Result(Key, error.Error)

Compatibility alias for from_uuid_with_config.

from_uuid_with_config

</> 
pub fn from_uuid_with_config(
  config: KeyConfig,
  input: String,
) -> Result(Key, error.Error)

Parses and formats a UUID using a supplied configuration.

generate

</> 
pub fn generate(config: KeyConfig) -> Result(Key, error.Error)

Finalizes a configuration by generating its selected content.

has_checksum

</> 
pub fn has_checksum(key: Key) -> Bool

Reports whether a key has a checksum.

has_prefix

</> 
pub fn has_prefix(key: Key) -> Bool

Reports whether a key has a prefix.

is_ready

</> 
pub fn is_ready(config: KeyConfig) -> Bool

Reports whether a configuration selects one valid content source mode.

new

</> 
pub fn new() -> KeyConfig

Returns an empty configuration for building a custom key plan.

new_as_config

</> 
pub fn new_as_config() -> KeyConfig

Returns a ready configuration containing the v0.3.0 defaults.

new_as_string

</> 
pub fn new_as_string() -> Result(String, error.Error)

Generates and serializes one key using the v0.3.0 defaults.

new_default

</> 
pub fn new_default() -> Result(Key, error.Error)

Generates one finalized key using the v0.3.0 defaults.

parse

</> 
pub fn parse(input: String) -> Result(Key, error.Error)

Parses and verifies the strict default serialized key format.

parse_with_format

</> 
pub fn parse_with_format(
  input: String,
  format: KeyFormat,
) -> Result(Key, error.Error)

Parses and verifies a serialized key using an explicit format.

prefix_value

</> 
pub fn prefix_value(key: Key) -> option.Option(String)

Returns the optional serialized prefix.

sections

</> 
pub fn sections(key: Key) -> KeySections

Returns all key sections grouped in one value.

separator_value

</> 
pub fn separator_value(key: Key) -> option.Option(String)

Returns the optional structural separator.

value

</> 
pub fn value(key: Key) -> String

Returns the string value of the key.

verify_checksum

</> 
pub fn verify_checksum(
  key: Key,
  checksum: checksum.Checksum,
) -> Bool

Verifies the stored checksum with an explicit algorithm.

verify_default_checksum

</> 
pub fn verify_default_checksum(key: Key) -> Bool

Verifies the stored checksum using CRC32.

with_alphabet

</> 
pub fn with_alphabet(
  config: KeyConfig,
  alphabet: alphabet.Alphabet,
) -> KeyConfig

Sets the alphabet used by direct character sampling.

with_checksum

</> 
pub fn with_checksum(
  config: KeyConfig,
  checksum: checksum.Checksum,
) -> KeyConfig

Sets the checksum algorithm and its serialized lowercase name.

with_checksum_bytes

</> 
pub fn with_checksum_bytes(
  config: KeyConfig,
  count: Int,
) -> KeyConfig

Sets how many checksum bytes are retained in the serialized key.

with_encoding

</> 
pub fn with_encoding(
  config: KeyConfig,
  encoding: encoding.Encoding,
) -> KeyConfig

Sets the encoding used for generated or imported bytes.

with_prefix

</> 
pub fn with_prefix(
  config: KeyConfig,
  prefix: String,
) -> KeyConfig

Sets the serialized prefix for a key.

with_random_bytes

</> 
pub fn with_random_bytes(
  config: KeyConfig,
  count: Int,
) -> KeyConfig

Selects secure random byte generation with the given byte count.

This clears direct alphabet sampling settings.

with_random_chars

</> 
pub fn with_random_chars(
  config: KeyConfig,
  count: Int,
) -> KeyConfig

Selects direct random character sampling with the given character count.

Pair this with with_alphabet. This clears byte encoding settings.

with_separator

</> 
pub fn with_separator(
  config: KeyConfig,
  separator: String,
) -> KeyConfig

Sets the separator used at every structural boundary.

without_checksum

</> 
pub fn without_checksum(config: KeyConfig) -> KeyConfig

Removes the checksum and its serialized name from a configuration.

✨ Search Document