Private API

This page lists non-exported (internal) symbols of CoveragePostprocessing, CTBase.Strategies, CTBase.DevTools, CTBase.Orchestration, CTBase.Interpolation, CTBase.Options, CTBase.Descriptions, CTBase.Core, CTBase.Exceptions, CTBase.Unicode, DocumenterReference, TestRunner.

---

From CoveragePostprocessing

_clean_stale_cov_files! [Function]

CoveragePostprocessing._clean_stale_cov_files! Function

_clean_stale_cov_files!(source_dirs)

Internal helper that removes stale .cov files from source_dirs.

If multiple runs are detected (PID suffix in filenames), this function keeps the PID with the largest number of .cov files and removes the others.

_collect_and_move_cov_files! [Function]

CoveragePostprocessing._collect_and_move_cov_files! Function

_collect_and_move_cov_files!(source_dirs, dest_dir) -> Vector{String}

Internal helper that moves all .cov files from source_dirs into dest_dir.

Returns a vector of destination paths for the moved files.

_count_cov_files [Function]

CoveragePostprocessing._count_cov_files Function

_count_cov_files(source_dirs) -> Int

Internal helper that counts the number of .cov files in the provided directories.

_generate_coverage_reports! [Function]

CoveragePostprocessing._generate_coverage_reports! Function

_generate_coverage_reports!(source_dirs, coverage_dir, root_dir, worst_n_files, max_uncovered_lines)

Internal helper that generates coverage reports from .cov files.

Arguments

• source_dirs::Vector{String}: Directories to scan for .cov files.

• coverage_dir::String: Destination directory for reports.

• root_dir::String: Project root directory for path resolution.

• worst_n_files::Int: Maximum number of lowest-covered files to list in the report.

• max_uncovered_lines::Int: Maximum number of uncovered lines to display in the report.

Writes:

• coverage/lcov.info

• coverage/cov_report.md

_get_pid_suffix [Function]

CoveragePostprocessing._get_pid_suffix Function

_get_pid_suffix(cov_file_path) -> String

Internal helper that extracts the PID suffix from a .cov file path.

Arguments

• cov_file_path::String: Path to a .cov file (e.g., src/foo.jl.12345.cov)

Returns

• String: The PID suffix (e.g., "12345"), or empty string if no suffix found.

_reset_coverage_dir [Function]

CoveragePostprocessing._reset_coverage_dir Function

_reset_coverage_dir(coverage_dir, cov_storage_dir)

Internal helper that recreates the coverage/ directory structure.

This function removes coverage_dir (recursively) if it already exists, then creates cov_storage_dir.

---

From CTBase.Strategies

_default_parameter [Function]

CTBase.Strategies._default_parameter Function

_default_parameter(
    _::Type{<:CTBase.Strategies.AbstractStrategy}
)

Get the default parameter type for a strategy.

This function returns the default parameter type that a strategy accepts. Strategies should override this method to specify their default parameter.

Arguments

• strategy_type::Type{<:AbstractStrategy}: The strategy type

Returns

• Type{<:AbstractStrategyParameter}: Default parameter type

Default Behavior

By default, returns CPU for backward compatibility. Strategies that have a different default parameter should override this method.

Example

# Strategy that defaults to CPU
_default_parameter(::Type{<:MyStrategy}) = CPU

# Strategy that defaults to GPU
_default_parameter(::Type{<:MyOtherStrategy}) = GPU

See also: CPU, GPU

_describe_metadata [Function]

CTBase.Strategies._describe_metadata Function

Display metadata for strategy types, handling multiple parameters and extensions.

For strategies with multiple parameters, groups options into:

• Common options (default source, same across parameters)

• Computed options (per-parameter, shown separately)

_describe_multi_param_metadata [Function]

CTBase.Strategies._describe_multi_param_metadata Function

Display metadata for multi-parameter strategies, grouping common and computed options.

_describe_parameter_registry [Function]

CTBase.Strategies._describe_parameter_registry Function

Describe a parameter using registry (internal implementation).

_describe_single_metadata [Function]

CTBase.Strategies._describe_single_metadata Function

Display metadata for a single strategy type (non-parameterized or single parameter).

_describe_strategy_registry [Function]

CTBase.Strategies._describe_strategy_registry Function

Describe a strategy using registry (internal implementation).

_error_unknown_options_strict [Function]

CTBase.Strategies._error_unknown_options_strict Function

_error_unknown_options_strict(
    remaining::NamedTuple,
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy},
    meta::CTBase.Strategies.StrategyMetadata
)

Throw an error for unknown options in strict mode.

This function generates a detailed error message that includes:

• List of unrecognized options

• Available options from metadata

• Suggestions based on Levenshtein distance

• Guidance on using permissive mode

Arguments

• remaining::NamedTuple: Unknown options provided by user

• strategy_type::Type{<:AbstractStrategy}: Strategy type being configured

• meta::StrategyMetadata: Strategy metadata with option definitions

Throws

• Exceptions.IncorrectArgument: Always throws with detailed error message

Example

# Internal use only - called by build_strategy_options()
_error_unknown_options_strict((unknown_opt=123,), Solvers.Ipopt, meta)

See also: build_strategy_options, suggest_options

_find_strategies_using_parameter [Function]

CTBase.Strategies._find_strategies_using_parameter Function

Find all strategies in the registry that use a specific parameter type.

Returns a vector of tuples: (strategy_id, family_type, strategy_type)

Arguments

• param_type::Type{<:AbstractStrategyParameter}: The parameter type to search for

• registry::StrategyRegistry: The registry to search in

Returns

• Vector{Tuple{Symbol, Type, Type}}: List of (strategy_id, family, strategy_type) tuples

_find_strategy_in_registry [Function]

CTBase.Strategies._find_strategy_in_registry Function

Find a strategy in the registry by its ID.

Returns (family_type, [matched_types...]) where matched_types are all strategy types with the given ID.

Throws IncorrectArgument if the ID is not found.

_print_labeled_multiline [Function]

CTBase.Strategies._print_labeled_multiline Function

_print_labeled_multiline(
    io::IO,
    prefix::String,
    cont::String,
    fmt,
    label::String,
    text::String
)

Print a labeled field with multi-line text support, aligning continuation lines under the text.

The first line is printed as prefix + colored_label + text_line_1. Each subsequent line (split on '\n') is indented to align with the start of the text, using cont followed by spaces equal to the visible length of label.

Arguments

• io::IO: Output stream

• prefix::String: Prefix for the first line (e.g., "├─ " or " │ ")

• cont::String: Continuation prefix for subsequent lines (e.g., "│ " or " ")

• fmt: Format codes from Core.get_format_codes

• label::String: The field label text (e.g., "description: ")

• text::String: The field value, may contain '\n' for multi-line content

Example

fmt = Core.get_format_codes(stdout)
_print_labeled_multiline(stdout, "├─ ", "│  ", fmt, "description: ", "Line one.\nLine two.")
# Output:
# ├─ description: Line one.
# │               Line two.

_raw_options [Function]

CTBase.Strategies._raw_options Function

_raw_options(
    opts::CTBase.Strategies.StrategyOptions
) -> NamedTuple

Private helper function - for internal framework use only.

Returns the raw NamedTuple of OptionValue objects from the internal storage. This is needed for Options.extract_raw_options which requires access to the full OptionValue objects, not just their .value fields.

Internal Use Only

This function is not part of the public API and may change without notice. External code should use the public collection interface (pairs, keys, values, etc.).

Returns

• NamedTuple of (Symbol => OptionValue) from the internal storage

_resolve_key [Function]

CTBase.Strategies._resolve_key Function

_resolve_key(
    opts::CTBase.Strategies.StrategyOptions,
    key::Symbol
) -> Symbol

Private helper function - for internal framework use only.

Resolve an alias to its canonical name, or return the key unchanged if not an alias.

This function performs O(1) lookup in the alias_map to resolve aliases to their canonical names. If the key is not found in the alias_map, it is assumed to be already canonical and returned unchanged.

Internal Use Only

This function is not part of the public API and may change without notice. External code should use the public access methods which handle alias resolution automatically.

Arguments

• opts::StrategyOptions: Strategy options containing the alias map

• key::Symbol: Key to resolve (can be canonical name or alias)

Returns

• Symbol: Canonical name for the option

Example

# Internal usage only
canonical = _resolve_key(opts, :maxiter)  # Returns :max_iter
canonical = _resolve_key(opts, :max_iter)  # Returns :max_iter (already canonical)

See also: Base.getindex, Base.haskey

_route_to_from_namedtuple [Function]

CTBase.Strategies._route_to_from_namedtuple Function

_route_to_from_namedtuple(
    routes::NamedTuple
) -> CTBase.Strategies.RoutedOption

Validate a NamedTuple of routes and wrap it in a RoutedOption.

Throws PreconditionError if routes is empty.

_strategy_base_name [Function]

CTBase.Strategies._strategy_base_name Function

_strategy_base_name(T::DataType) -> String

Extract the base type name without parameters for strategy headers.

This function removes module prefixes and parameter information, returning just the clean base type name (e.g., "ADNLP" from "ADNLP{CPU}").

Arguments

• T::Type: The type to extract the base name from

Returns

• String: Clean base type name without parameters

Examples

julia> using CTBase.Strategies

julia> struct FakeADNLP{P <: CTBase.Strategies.AbstractStrategyParameter} end
julia> _strategy_base_name(FakeADNLP{CTBase.Strategies.CPU})
"FakeADNLP"

julia> _strategy_base_name(Collocation)
"Collocation"

Notes

• Used specifically for strategy headers to avoid redundancy with parameter display

• Handles both DataType and UnionAll types

See also: _strategy_type_name, describe

_strategy_id_set [Function]

CTBase.Strategies._strategy_id_set Function

_strategy_id_set(
    registry::CTBase.Strategies.StrategyRegistry
) -> Set{Symbol}

Internal helper returning the set of all registered strategy IDs.

This function is used by registry utilities that need to distinguish strategy tokens from other tokens that may appear in a method tuple (e.g. parameter tokens).

Arguments

• registry::StrategyRegistry: Strategy registry.

Returns

• Set{Symbol}: Set of all strategy IDs present in the registry.

Notes

• This function is internal and not part of the public API.

_strategy_type_name [Function]

CTBase.Strategies._strategy_type_name Function

_strategy_type_name(T::DataType) -> String

Extract a clean type name from a DataType by removing module prefixes while preserving parameter structure.

This method handles both parameterized DataTypes (e.g., Exa{CPU}) and non-parameterized DataTypes (e.g., Collocation). For parameterized types, it removes module prefixes from both the base type and parameters while preserving the parameter structure.

Arguments

• T::DataType: The DataType to format

Returns

• String: Clean type name without module prefixes (e.g., "Exa{CPU}" or "Collocation")

Examples

julia> using CTBase.Strategies

julia> struct FakeExa{P <: CTBase.Strategies.AbstractStrategyParameter} end
julia> _strategy_type_name(FakeExa{CTBase.Strategies.CPU})
"FakeExa{CPU}"

julia> _strategy_type_name(Collocation)
"Collocation"

Notes

• This is the most common case, handling concrete instantiated types

• For parameterized types, each parameter is formatted recursively

See also: describe, _describe_parameter_registry

_strategy_type_name(T::UnionAll)

Extract a clean type name from a UnionAll type by removing module prefixes.

This method handles generic types that have not been fully instantiated, preserving the type parameter variable name.

Arguments

• T::UnionAll: The UnionAll type to format

Returns

• String: Clean type name with generic parameter (e.g., "Exa{P}" where P is the type variable)

Notes

• This is a fallback for generic types that are not yet instantiated

• Less common than the DataType method in typical usage

See also: _strategy_type_name(::DataType)

_strategy_type_name(T::Type) -> String

Extract a clean type name from any other Type.

This is the most general fallback method for types that don't match more specific methods.

Arguments

• T::Type: Any type that doesn't match other methods

Returns

• String: String representation of the type

Notes

• This is the ultimate fallback for edge cases

• Simply converts the type to a string representation

See also: _strategy_type_name(::DataType), _strategy_type_name(::UnionAll)

_supertype_chain [Function]

CTBase.Strategies._supertype_chain Function

Build a supertype chain from a type up to (and including) a stop type.

Returns a vector of types representing the inheritance chain.

Arguments

• T::Type: Starting type

• stop_at::Type: Type to stop at (inclusive)

Returns

• Vector{Type}: Chain of types from T to stop_at

Example

chain = _supertype_chain(ADNLP{CPU}, AbstractStrategy)
# Returns: [ADNLP{CPU}, AbstractNLPModeler, AbstractStrategy]

_warn_unknown_options_permissive [Function]

CTBase.Strategies._warn_unknown_options_permissive Function

_warn_unknown_options_permissive(
    remaining::NamedTuple,
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy}
)

Warn about unknown options in permissive mode.

This function generates a warning message that informs the user that unvalidated options will be passed directly to the backend without validation.

Arguments

• remaining::NamedTuple: Unknown options provided by user

• strategy_type::Type{<:AbstractStrategy}: Strategy type being configured

Example

# Internal use only - called by build_strategy_options()
_warn_unknown_options_permissive((custom_opt=123,), Solvers.Ipopt)

See also: build_strategy_options, _error_unknown_options_strict

extract_global_parameter_from_method [Function]

CTBase.Strategies.extract_global_parameter_from_method Function

extract_global_parameter_from_method(
    method::Tuple{Vararg{Symbol}},
    registry::CTBase.Strategies.StrategyRegistry
) -> Union{Nothing, Type{<:CTBase.Strategies.AbstractStrategyParameter}}

Extract the global strategy parameter from a method tuple.

The method tuple may contain at most one parameter token (e.g. :cpu, :gpu). If present, it is resolved to a parameter type using registry.parameters.

If any of the selected strategies in the method are parameterized, then a parameter token is required and must be supported by each parameterized strategy.

Arguments

• method::Tuple{Vararg{Symbol}}: Method tuple containing strategy IDs and optionally one parameter token.

• registry::StrategyRegistry: Strategy registry.

Returns

• Union{Nothing, Type{<:AbstractStrategyParameter}}: The extracted parameter type, or nothing if none is present.

Throws

• Exceptions.IncorrectArgument: If more than one parameter token is present, if a parameter is missing but required, if a parameter is unsupported, or if a parameter token is provided but no selected strategy is parameterized.

See also: available_parameters, Strategies.AbstractStrategyParameter

is_a_parameter [Function]

CTBase.Strategies.is_a_parameter Function

is_a_parameter(_::Type{T}) -> Bool

Check whether a type is a strategy parameter type.

This predicate is useful for contract validation and generic code paths that need to distinguish parameter types from other types.

Arguments

• T::Type: Any Julia type

Returns

• Bool: true if T <: AbstractStrategyParameter, otherwise false

Example

julia> Strategies.is_a_parameter(Strategies.CPU)
true

julia> Strategies.is_a_parameter(Int)
false

See also: AbstractStrategyParameter, validate_parameter_type

is_parameter_type [Function]

CTBase.Strategies.is_parameter_type Function

is_parameter_type(_::Type{T}) -> Bool

Deprecated

is_parameter_type is deprecated; use is_a_parameter instead.

levenshtein_distance [Function]

CTBase.Strategies.levenshtein_distance Function

levenshtein_distance(s1::String, s2::String) -> Int64

Compute the Levenshtein distance between two strings.

The Levenshtein distance is the minimum number of single-character edits (insertions, deletions, or substitutions) required to change one string into another.

Arguments

• s1::String: First string

• s2::String: Second string

Returns

• Int: Levenshtein distance between the two strings

Example

julia> levenshtein_distance("kitten", "sitting")
3

julia> levenshtein_distance("max_iter", "max_it")
2

Algorithm

Uses dynamic programming with O(m*n) time and space complexity, where m and n are the lengths of the input strings.

See also: suggest_options

option [Function]

CTBase.Strategies.option Function

option(
    opts::CTBase.Strategies.StrategyOptions,
    key::Symbol
) -> Any

Get the OptionValue wrapper for an option.

Arguments

• opts::StrategyOptions: Strategy options

• key::Symbol: Option name

Returns

• Options.OptionValue: The option value wrapper

Example

julia> opt = option(opts, :max_iter)
julia> Options.value(opt)
200

julia> opt = option(opts, :maxiter)  # Alias - automatically resolved
julia> Options.value(opt)
200

Notes

• Aliases are automatically resolved to canonical names

See also: Base.getproperty, Options.source

parameter_id [Function]

CTBase.Strategies.parameter_id Function

parameter_id(
    parameter_type::Type{<:CTBase.Strategies.AbstractStrategyParameter}
) -> Symbol

Get the identifier of a strategy parameter type.

This is an explicit alias for id to make code using parameter IDs more self-documenting.

Arguments

• parameter_type::Type{<:AbstractStrategyParameter}: The parameter type

Returns

• Symbol: The parameter identifier

Example

julia> Strategies.parameter_id(Strategies.CPU)
:cpu

See also: id, AbstractStrategyParameter

validate_parameter_type [Function]

CTBase.Strategies.validate_parameter_type Function

validate_parameter_type(
    parameter_type::Type{<:CTBase.Strategies.AbstractStrategyParameter}
)

Validate that a parameter type satisfies the AbstractStrategyParameter contract.

This function performs lightweight structural checks:

• the parameter type must be concrete

• the parameter type must be a singleton type (no fields)

• the parameter type must implement id

Arguments

• parameter_type::Type{<:AbstractStrategyParameter}: The parameter type to validate

Returns

• Nothing: Returns nothing if validation succeeds

Throws

• Exceptions.IncorrectArgument: If the parameter type is not concrete or has fields

• Exceptions.NotImplemented: If the parameter type does not implement id

Example

struct MyParam <: Strategies.AbstractStrategyParameter end
Strategies.id(::Type{MyParam}) = :my_param

Strategies.validate_parameter_type(MyParam)  # returns nothing

Notes

• This function does not validate global ID uniqueness; that is handled by registry construction.

See also: id, parameter_id, is_a_parameter

---

From CTBase.Orchestration

RoutingContext [Struct]

CTBase.Orchestration.RoutingContext Type

struct RoutingContext

Internal struct to encapsulate routing context.

Holds precomputed mappings used during option routing to avoid passing multiple dictionaries around and improve performance.

Fields

• strategy_to_family::Dict{Symbol, Symbol}: Maps strategy IDs to their family names

• option_owners::Dict{Symbol, Set{Symbol}}: Maps option names to the set of families that own them

Notes

• This struct is immutable and created once per routing operation

• Precomputing these mappings avoids repeated lookups during routing

• Used internally by the routing helper functions

_build_routed_result [Function]

CTBase.Orchestration._build_routed_result Function

_build_routed_result(
    action_options::Dict,
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}
) -> NamedTuple{(:action, :strategies), <:Tuple{NamedTuple, NamedTuple}}

Build the final routed result structure.

Converts the routing dictionary and action options into the final NamedTuple format expected by the routing system API.

Arguments

• action_options::Dict: Dictionary of extracted action options with OptionValue wrappers

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary with options per family

Returns

• NamedTuple: Final result with structure (action=..., strategies=...) where:

  • action: NamedTuple of action options with OptionValue wrappers

  • strategies: NamedTuple of strategy options per family (raw values)

Notes

• Converts routing dictionary to nested NamedTuple structure

• Preserves OptionValue wrappers for action options

• Strategy options remain in their raw form for downstream processing

• This is the final step in the routing pipeline

_build_routing_context [Function]

CTBase.Orchestration._build_routing_context Function

_build_routing_context(
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry
) -> CTBase.Orchestration.RoutingContext

Build routing context with precomputed mappings.

Creates a RoutingContext containing strategy-to-family and option ownership maps to optimize routing performance by avoiding repeated computations.

Arguments

• resolved::ResolvedMethod: Resolved method containing strategy information

• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types

• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup

Returns

• RoutingContext: Context containing precomputed mappings for efficient routing

Notes

• Precomputes expensive mapping operations once per routing call

• Strategy-to-family mapping enables quick family lookup from strategy ID

• Option ownership mapping enables quick validation of option routing

_check_action_option_shadowing [Function]

CTBase.Orchestration._check_action_option_shadowing Function

_check_action_option_shadowing(
    action_options::Dict,
    option_owners::Dict{Symbol, Set{Symbol}}
)

Check for action option shadowing and emit info messages.

Detects when a user-provided action option also exists in strategy metadata, which means the action option "shadows" the strategy option. Emits informational messages to help users understand the shadowing.

Arguments

• action_options::Dict: Dictionary of extracted action options with OptionValue wrappers

• option_owners::Dict{Symbol, Set{Symbol}}: Maps option names to families that own them

Returns

• Nothing: This function only emits info messages

Notes

• Only checks user-provided options (source === :user), not default values

• Provides helpful guidance on using route_to() for specific strategy targeting

• Uses @info to emit messages without interrupting execution

_collect_suggestions_across_strategies [Function]

CTBase.Orchestration._collect_suggestions_across_strategies Function

_collect_suggestions_across_strategies(
    key::Symbol,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry;
    max_suggestions
) -> Vector{@NamedTuple{primary::Symbol, aliases::Tuple{Vararg{Symbol}}, distance::Int64}}

Collect option suggestions across all strategies in the method, deduplicated by primary name. Returns the top max_suggestions results sorted by minimum Levenshtein distance.

_error_ambiguous_option [Function]

CTBase.Orchestration._error_ambiguous_option Function

_error_ambiguous_option(
    key::Symbol,
    value,
    owners::Set{Symbol},
    strategy_to_family::Dict{Symbol, Symbol},
    source_mode::Symbol,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry
)

Helper to throw an informative error when an option belongs to multiple strategies and needs disambiguation. Suggests using route_to syntax with specific examples for the conflicting strategies.

_error_unknown_option [Function]

CTBase.Orchestration._error_unknown_option Function

_error_unknown_option(
    key::Symbol,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    strategy_to_family::Dict{Symbol, Symbol},
    registry::CTBase.Strategies.StrategyRegistry
)

Helper to throw an informative error when an option doesn't belong to any strategy. Lists all available options for the active strategies to help the user.

Notes

• Also searches the registry for strategies not in the current method that have this option, suggesting the user may have chosen the wrong strategy.

_find_option_in_registry [Function]

CTBase.Orchestration._find_option_in_registry Function

_find_option_in_registry(
    key::Symbol,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry
) -> Vector{Tuple{Symbol, Symbol}}

Search for an option in all strategies of the registry, excluding strategies in the current method.

This helper function checks if an unknown option exists in strategies that are not part of the current method, enabling helpful error messages that suggest the user may have chosen the wrong strategy.

Arguments

• key::Symbol: The option name to search for

• resolved::ResolvedMethod: Resolved method containing current strategy IDs

• families::NamedTuple: NamedTuple mapping family names to family types

• registry::Strategies.StrategyRegistry: Strategy registry containing all registered strategies

Returns

• Vector{Tuple{Symbol, Symbol}}: Vector of (strategy_id, family_name) tuples for strategies that have this option

Notes

• Strategies in the current method are excluded from the search

• Uses try/catch around metadata() for robustness against incomplete strategy definitions

• Results are not ordered; caller should sort if needed

_initialize_routing_dict [Function]

CTBase.Orchestration._initialize_routing_dict Function

_initialize_routing_dict(
    families::NamedTuple
) -> Dict{Symbol, Vector{Pair{Symbol, Any}}}

Initialize the routing dictionary structure.

Creates an empty routing dictionary with one entry per family to collect routed options during the routing process.

Arguments

• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types

Returns

• Dict{Symbol, Vector{Pair{Symbol, Any}}}: Empty routing dictionary with entries for each family

Notes

• Each family gets an empty Vector{Pair{Symbol, Any}} to collect routed options

• The structure enables efficient accumulation of options per family

• Used as the starting point for routing operations

_route_auto! [Function]

CTBase.Orchestration._route_auto! Function

_route_auto!(
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}},
    key::Symbol,
    value,
    context::CTBase.Orchestration.RoutingContext,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry,
    source_mode::Symbol
)

Route a single option automatically based on ownership.

Handles options without explicit disambiguation by checking ownership:

• Unknown option → error with helpful suggestions

• Single owner → auto-route to that family

• Multiple owners → ambiguity error requiring disambiguation

Arguments

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary to populate

• key::Symbol: Option name being routed

• value::Any: Option value to route

• context::RoutingContext: Precomputed routing mappings

• resolved::ResolvedMethod: Resolved method containing strategy information

• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types

• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup

• source_mode::Symbol: Controls error verbosity (:description or :explicit)

Returns

• Nothing: Modifies routed in-place

Throws

• Exceptions.IncorrectArgument: If option is unknown or ambiguous

Notes

• Uses option ownership mapping to determine routing destination

• Provides detailed error messages with suggestions for unknown/ambiguous options

• Auto-routing only occurs when option has exactly one owner

_route_single_option! [Function]

CTBase.Orchestration._route_single_option! Function

_route_single_option!(
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}},
    key::Symbol,
    raw_val,
    context::CTBase.Orchestration.RoutingContext,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry,
    source_mode::Symbol
)

Route a single option (dispatcher).

Determines whether the option has explicit disambiguation and routes accordingly. Acts as the main dispatcher for option routing logic.

Arguments

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary to populate

• key::Symbol: Option name being routed

• raw_val::Any: Raw option value (may be wrapped in RoutedOption)

• context::RoutingContext: Precomputed routing mappings

• resolved::ResolvedMethod: Resolved method containing strategy information

• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types

• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup

• source_mode::Symbol: Controls error verbosity (:description or :explicit)

Returns

• Nothing: Modifies routed in-place

Notes

• Extracts strategy disambiguations from RoutedOption values if present

• Delegates to _route_with_disambiguation! for explicit routing

• Delegates to _route_auto! for automatic routing

• Central point for all option routing decisions

_route_with_disambiguation! [Function]

CTBase.Orchestration._route_with_disambiguation! Function

_route_with_disambiguation!(
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}},
    key::Symbol,
    disambiguations::Vector{Tuple{Any, Symbol}},
    context::CTBase.Orchestration.RoutingContext,
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry
)

Route a single option with explicit disambiguation.

Handles options wrapped in route_to() with explicit strategy targets. Validates that the target family owns the option or that bypass is used.

Arguments

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary to populate

• key::Symbol: Option name being routed

• disambiguations::Vector{Tuple{Any, Symbol}}: List of (value, strategy_id) pairs

• context::RoutingContext: Precomputed routing mappings

• resolved::ResolvedMethod: Resolved method containing strategy information

• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types

• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup

Returns

• Nothing: Modifies routed in-place

Throws

• Exceptions.IncorrectArgument: If option is unknown or routed to wrong family

Notes

• BypassValue allows routing unknown options without validation

• Validates option ownership to prevent incorrect routing

• Provides helpful error messages for misrouted options

_separate_action_and_strategy_options [Function]

CTBase.Orchestration._separate_action_and_strategy_options Function

_separate_action_and_strategy_options(
    kwargs::NamedTuple,
    action_defs::Vector{<:CTBase.Options.OptionDefinition}
) -> Tuple{Dict{Symbol, CTBase.Options.OptionValue}, NamedTuple}

Separate action options from strategy options.

Filters out RoutedOption values from action extraction, processes action definitions, and re-integrates RoutedOption values for strategy routing.

Arguments

• kwargs::NamedTuple: All keyword arguments (action + strategy options mixed)

• action_defs::Vector{<:Options.OptionDefinition}: Definitions for action-specific options

Returns

• Tuple{Dict, NamedTuple}: (action_options, strategy_kwargs) where:

  • action_options: Dict of extracted action options with OptionValue wrappers

  • strategy_kwargs: NamedTuple of remaining kwargs for strategy routing

Notes

• RoutedOption values are excluded from action extraction and preserved for strategy routing

• Action options are wrapped in OptionValue with source tracking

• Strategy options remain in their original form for further processing

_warn_unknown_option_permissive [Function]

CTBase.Orchestration._warn_unknown_option_permissive Function

_warn_unknown_option_permissive(
    key::Symbol,
    strategy_id::Symbol,
    family_name::Symbol
)

Helper to warn when an unknown option is routed in permissive mode.

build_alias_to_primary_map [Function]

CTBase.Orchestration.build_alias_to_primary_map Function

build_alias_to_primary_map(
    resolved::CTBase.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTBase.Strategies.StrategyRegistry
) -> Dict{Symbol, Symbol}

Build a mapping from alias names to their primary option names for all strategies in the method.

Arguments

• resolved::ResolvedMethod: Resolved method information (active strategies)

• families::NamedTuple: NamedTuple mapping family names to abstract types

• registry::Strategies.StrategyRegistry: Strategy registry

Returns

• Dict{Symbol, Symbol}: Dictionary mapping alias => primary_name

Example

resolved = resolve_method(method, families, registry)
alias_map = build_alias_to_primary_map(resolved, families, registry)

See also: build_option_ownership_map, resolve_method

---

From CTBase.Interpolation

AbstractInterpolation [Abstract Type]

CTBase.Interpolation.AbstractInterpolation Type

abstract type AbstractInterpolation

Abstract interpolation method (trait).

Concrete subtypes (Linear, Constant) are singleton trait values carried as a type parameter of Interpolant, so the call method is resolved statically.

Constant [Struct]

CTBase.Interpolation.Constant Type

struct Constant <: CTBase.Interpolation.AbstractInterpolation

Piecewise-constant (right-continuous steppost) interpolation method.

Linear [Struct]

CTBase.Interpolation.Linear Type

struct Linear <: CTBase.Interpolation.AbstractInterpolation

Linear interpolation method (with flat extrapolation outside the node range).

method [Function]

CTBase.Interpolation.method Function

method(_::CTBase.Interpolation.Interpolant{M}) -> Any

Return the interpolation method (a subtype of AbstractInterpolation) of interp.

---

From CTBase.Options

NotStored [Constant]

CTBase.Options.NotStored Constant

NotStored

Internal singleton instance of NotStoredType.

Used internally by the option extraction system to signal that an option should not be stored. This is distinct from nothing which is a valid option value.

See also: NotProvided, extract_option

NotStoredType [Struct]

CTBase.Options.NotStoredType Type

struct NotStoredType

Internal sentinel type used by the option extraction system to signal that an option should not be stored in the instance.

This is returned by extract_option when an option has NotProvided as its default and was not provided by the user.

Note

This type is internal to the Options module and should not be used directly by users. Use NotProvided instead.

See also: NotProvided, extract_option

_construct_option_definition [Function]

CTBase.Options._construct_option_definition Function

_construct_option_definition(
    name::Symbol,
    type::Type,
    default::Nothing,
    description::String,
    aliases::Tuple{Vararg{Symbol}},
    validator::Union{Nothing, Function},
    computed::Bool
) -> CTBase.Options.OptionDefinition{Any}

Construct an OptionDefinition with a nothing default value.

This method handles the special case where default = nothing, creating an OptionDefinition{Any} with type = Any since nothing can represent any type.

Arguments

• name::Symbol: Primary name of the option

• type::Type: Expected Julia type (ignored for nothing defaults)

• default::Nothing: Must be nothing

• description::String: Human-readable description

• aliases::Tuple{Vararg{Symbol}}: Alternative names (default: empty tuple)

• validator::Union{Function, Nothing}: Optional validation function (default: nothing)

• computed::Bool: Whether the default is computed from parameters (default: false)

Returns

• OptionDefinition{Any}: Option definition with nothing default

Example

julia> using CTBase.Options

julia> def = _construct_option_definition(
           :backend,
           Union{Nothing, String},
           nothing,
           "Execution backend",
           (:be,)
       )
OptionDefinition{Any}(...)

julia> default(def)
nothing

See also: OptionDefinition, NotProvided

_construct_option_definition(
    name::Symbol,
    type::Type,
    default::CTBase.Options.NotProvidedType,
    description::String,
    aliases::Tuple{Vararg{Symbol}},
    validator::Union{Nothing, Function},
    computed::Bool
) -> CTBase.Options.OptionDefinition{CTBase.Options.NotProvidedType}

Construct an OptionDefinition with a NotProvided default value.

This method handles the special case where default = NotProvided, creating an OptionDefinition{NotProvidedType}. The declared type is preserved since NotProvided indicates the absence of a default value while maintaining type information for validation.

Arguments

• name::Symbol: Primary name of the option

• type::Type: Expected Julia type for user-provided values

• default::NotProvidedType: Must be NotProvided

• description::String: Human-readable description

• aliases::Tuple{Vararg{Symbol}}: Alternative names (default: empty tuple)

• validator::Union{Function, Nothing}: Optional validation function (default: nothing)

• computed::Bool: Whether the default is computed from parameters (default: false)

Returns

• OptionDefinition{NotProvidedType}: Option definition with no default value

Example

julia> using CTBase.Options

julia> def = _construct_option_definition(
           :input_file,
           String,
           NotProvided,
           "Input file path",
           (:input,)
       )
OptionDefinition{NotProvidedType}(...)

julia> is_required(def)
true

See also: OptionDefinition, NotProvided, is_required

_construct_option_definition(
    name::Symbol,
    type::Type,
    default,
    description::String,
    aliases::Tuple{Vararg{Symbol}},
    validator::Union{Nothing, Function},
    computed::Bool
) -> CTBase.Options.OptionDefinition{Any}

Construct an OptionDefinition with a concrete default value.

This method handles the general case where default is a concrete value. It infers the type parameter T from the default value and validates that the default value is compatible with the declared type.

Arguments

• name::Symbol: Primary name of the option

• type::Type: Expected Julia type for the option value

• default::T: Default value (type T is inferred)

• description::String: Human-readable description

• aliases::Tuple{Vararg{Symbol}}: Alternative names (default: empty tuple)

• validator::Union{Function, Nothing}: Optional validation function (default: nothing)

• computed::Bool: Whether the default is computed from parameters (default: false)

Returns

• OptionDefinition{T}: Option definition with concrete default value

Throws

• CTBase.Exceptions.IncorrectArgument: If default is not compatible with type

Example

julia> using CTBase.Options

julia> def = _construct_option_definition(
           :max_iter,
           Int,
           100,
           "Maximum number of iterations",
           (:max,)
       )
OptionDefinition{Int}(...)

julia> default(def)
100

See also: OptionDefinition, Exceptions.IncorrectArgument

---

From CTBase.Descriptions

_compute_similarity [Function]

CTBase.Descriptions._compute_similarity Function

_compute_similarity(
    desc1::Tuple{Vararg{Symbol}},
    desc2::Tuple{Vararg{Symbol}}
) -> Float64

Compute similarity between two descriptions based on the Jaccard index of their symbols.

Arguments

• desc1::Description: First description to compare

• desc2::Description: Second description to compare

Returns

• Float64: A value between 0.0 (no similarity) and 1.0 (identical)

Example

julia> using CTBase

julia> CTBase.Descriptions.compute_similarity((:a, :b), (:a, :c))
0.5
julia> CTBase.Descriptions.compute_similarity((:a, :b), (:a, :b))
1.0
julia> CTBase.Descriptions.compute_similarity((:x, :y), (:a, :b))
0.0

_find_similar_descriptions [Function]

CTBase.Descriptions._find_similar_descriptions Function

_find_similar_descriptions(
    target::Tuple{Vararg{Symbol}},
    descriptions::Tuple{Vararg{Tuple{Vararg{Symbol}}}};
    max_results
) -> Vector{String}

Find descriptions most similar to the target description based on symbol overlap.

Arguments

• target::Tuple{Vararg{Symbol}}: The partial or incorrect description to match

• descriptions::Tuple{Vararg{Description}}: A catalog of valid descriptions

Keyword Arguments

• max_results::Int=5: Maximum number of similar descriptions to return

Returns

• Vector{String}: Formatted string representations of the most similar descriptions

Example

julia> using CTBase

julia> descriptions = ((:a, :b), (:a, :c), (:x, :y))
julia> CTBase.Descriptions.find_similar_descriptions((:a,), descriptions)
2-element Vector{String}:
 "(:a, :b)"
 "(:a, :c)"

_format_description_candidates [Function]

CTBase.Descriptions._format_description_candidates Function

_format_description_candidates(
    descriptions::Tuple{Vararg{Tuple{Vararg{Symbol}}}};
    max_show
) -> Vector{String}

Format description candidates from a catalog for display in error messages.

Arguments

• descriptions::Tuple{Vararg{Description}}: A catalog of descriptions

Keyword Arguments

• max_show::Int=5: Maximum number of descriptions to include in the output

Returns

• Vector{String}: A vector of formatted description strings

Example

julia> using CTBase

julia> descriptions = ((:a, :b), (:a, :c), (:x, :y), (:p, :q))
julia> CTBase.Descriptions.format_description_candidates(descriptions; max_show=3)
3-element Vector{String}:
 "(:a, :b)"
 "(:a, :c)"
 "(:x, :y)"

---

From CTBase.Core

_ACTIVE_PALETTE [Constant]

CTBase.Core._ACTIVE_PALETTE Constant

Runtime reference to the currently active palette.

Initialised to CTBase.Core.DEFAULT_PALETTE. All display paths read from this reference; mutate it via CTBase.Core.set_palette! and CTBase.Core.reset_palette!.

__display [Function]

CTBase.Core.__display Function

__display() -> Bool

Return the default value of the display flag.

This internal utility is used to decide whether output should be shown during execution.

Returns

• Bool: The default value true, indicating that output is displayed.

Example

julia> using CTBase

julia> CTBase.__display()
true

__matrix_dimension_storage [Function]

CTBase.Core.__matrix_dimension_storage Function

__matrix_dimension_storage() -> Int64

Return the default dimension for matrix storage.

_apply_ansi [Function]

CTBase.Core._apply_ansi Function

_apply_ansi(s, code, io::IO) -> Any

Apply a raw ANSI numeric code string to s, respecting the IO colour capability.

Prefer CTBase.Core._style with a CTBase.Core.Style from the active palette over calling this function directly.

_bold [Function]

CTBase.Core._bold Function

_bold(s, io::IO) -> Any

Apply the emphasis role style from the active palette.

See also: CTBase.Core.current_palette, CTBase.Core._style

_dim [Function]

CTBase.Core._dim Function

_dim(s, io::IO) -> Any

Apply the muted role style from the active palette.

See also: CTBase.Core.current_palette, CTBase.Core._style

_green [Function]

CTBase.Core._green Function

_green(s, io::IO) -> Any

Apply the success role style from the active palette (defaults to green).

See also: CTBase.Core.current_palette, CTBase.Core._style

_red [Function]

CTBase.Core._red Function

_red(s, io::IO) -> Any

Apply the error role style from the active palette (defaults to red).

See also: CTBase.Core.current_palette, CTBase.Core._style

_style [Function]

CTBase.Core._style Function

_style(st::CTBase.Core.Style, s, io::IO) -> Any

Apply a CTBase.Core.Style to string s, respecting the IO colour capability.

Returns s wrapped in ANSI escape codes when get(io, :color, false) is true and st.code is non-empty; returns the plain string otherwise.

See also: CTBase.Core._apply_ansi, CTBase.Core.get_format_codes

_yellow [Function]

CTBase.Core._yellow Function

_yellow(s, io::IO) -> Any

Apply the warning role style from the active palette (defaults to yellow).

See also: CTBase.Core.current_palette, CTBase.Core._style

---

From CTBase.Exceptions

_build_primary_pairs [Function]

CTBase.Exceptions._build_primary_pairs Function

_build_primary_pairs(
    e::CTBase.Exceptions.IncorrectArgument
) -> Vector{Any}

Build primary field (label, value, color) tuples for IncorrectArgument display.

Arguments

• e::IncorrectArgument: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples. Colors are :yellow for warnings, :green for expected values, :default otherwise.

Notes

• Only includes fields that are not nothing.

_build_primary_pairs(
    e::CTBase.Exceptions.PreconditionError
) -> Vector{Any}

Build primary field (label, value, color) tuples for PreconditionError display.

Arguments

• e::PreconditionError: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples.

Notes

• Only includes fields that are not nothing.

_build_primary_pairs(
    e::CTBase.Exceptions.NotImplemented
) -> Vector{Any}

Build primary field (label, value, color) tuples for NotImplemented display.

Arguments

• e::NotImplemented: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples.

Notes

• Only includes fields that are not nothing.

_build_primary_pairs(
    e::CTBase.Exceptions.ParsingError
) -> Vector{Any}

Build primary field (label, value, color) tuples for ParsingError display.

Arguments

• e::ParsingError: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples.

Notes

• Only includes fields that are not nothing.

_build_primary_pairs(
    e::CTBase.Exceptions.AmbiguousDescription
) -> Vector{Any}

Build primary field (label, value, color) tuples for AmbiguousDescription display.

Arguments

• e::AmbiguousDescription: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples.

Notes

• The candidates field is passed as a Vector{String} for multi-line rendering.

• Only includes fields that are not nothing or empty.

_build_primary_pairs(
    e::CTBase.Exceptions.ExtensionError
) -> Vector{T} where T<:Tuple{String, Union{Base.AnnotatedString{String}, String}, Symbol}

Build primary field (label, value, color) tuples for ExtensionError display.

Arguments

• e::ExtensionError: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Single tuple with the missing dependencies.

Notes

• Always includes the Missing field with joined weakdeps.

_build_primary_pairs(
    e::CTBase.Exceptions.SolverFailure
) -> Vector{Any}

Build primary field (label, value, color) tuples for SolverFailure display.

Arguments

• e::SolverFailure: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples.

Notes

• Only includes fields that are not nothing.

_build_secondary_pairs [Function]

CTBase.Exceptions._build_secondary_pairs Function

_build_secondary_pairs(
    e::CTBase.Exceptions.CTException
) -> Vector{Any}

Build secondary field (label, value, color) tuples for generic CTException display.

Arguments

• e::CTException: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples for Context and Hint (from suggestion) fields.

Notes

• Only includes fields that exist and are not nothing.

• Hint is colored green for visibility.

_build_secondary_pairs(
    e::CTBase.Exceptions.ExtensionError
) -> Vector{Any}

Build secondary field (label, value, color) tuples for ExtensionError display.

Arguments

• e::ExtensionError: The exception instance.

Returns

• Vector{Tuple{String, Any, Symbol}}: Vector of (label, value, color) tuples. The Hint is dynamically generated from weakdeps.

Notes

• The Hint field is generated as "Run: using " followed by the joined dependency names.

• This override is necessary because ExtensionError does not have a suggestion field.

_extract_user_frames [Function]

CTBase.Exceptions._extract_user_frames Function

extract_user_frames(st::Vector)

Extract stacktrace frames that are relevant to user code. Filters out Julia stdlib.

Arguments

• st::Vector: Stacktrace from stacktrace(catch_backtrace())

Returns

• Vector: Filtered stacktrace frames

_format_diagnostic [Function]

CTBase.Exceptions._format_diagnostic Function

_format_diagnostic(diagnostic::String) -> String

Format a diagnostic tag for AmbiguousDescription display, expanding shorthand tags into human-readable messages.

Arguments

• diagnostic::String: The diagnostic tag (e.g., "empty catalog", "unknown symbols", "no complete match").

Returns

• String: The expanded human-readable message.

Notes

• Unknown tags are returned unchanged.

_format_user_friendly_error [Function]

CTBase.Exceptions._format_user_friendly_error Function

format_user_friendly_error(io::IO, e::CTException)

Display an error in a user-friendly format with clear sections and user code location.

Arguments

• io::IO: Output stream

• e::CTException: The exception to display

_print_colored [Function]

CTBase.Exceptions._print_colored Function

_print_colored(io, text, color::Symbol) -> Any

Print colored text based on a color symbol.

Arguments

• io::IO: Output stream.

• text::AbstractString: The text to print.

• color::Symbol: The color symbol (:yellow, :green, or any other for default).

Notes

• :yellow and :green apply ANSI styling; all other colors print as plain text.

_print_pipe_field [Function]

CTBase.Exceptions._print_pipe_field Function

_print_pipe_field(
    io,
    label::String,
    value,
    max_len::Int64,
    color::Symbol
)

Print a pipe-formatted field with dynamic label alignment.

Arguments

• io::IO: Output stream.

• label::String: The field label.

• value: The field value (can be a Vector for multi-line rendering).

• max_len::Int: The maximum label length for alignment.

• color::Symbol: The color symbol (:yellow, :green, or :default).

Notes

• For Vector values, the first line includes the label, subsequent lines are indented.

• The pipe character │ is dimmed for visual hierarchy.

---

From DocumenterReference

APIBuilder [Abstract Type]

DocumenterReference.APIBuilder Type

APIBuilder <: Documenter.Builder.DocumentPipeline

Custom Documenter pipeline stage for automatic API reference generation.

This builder is inserted into the Documenter pipeline at order 0.0 (before most other stages) to generate API reference pages from the configurations stored in CONFIG.

CONFIG [Constant]

DocumenterReference.CONFIG Constant

CONFIG::Vector{_Config}

Global configuration storage for API reference generation.

Each call to CTBase.automatic_reference_documentation appends a new _Config entry to this vector. Use reset_config! to clear it between builds.

DOCTYPE_NAMES [Constant]

DocumenterReference.DOCTYPE_NAMES Constant

DOCTYPE_NAMES::Dict{DocType, String}

Mapping from DocType enum values to their human-readable string representations.

DOCTYPE_ORDER [Constant]

DocumenterReference.DOCTYPE_ORDER Constant

DOCTYPE_ORDER::Dict{DocType, Int}

Ordering for DocType values used when sorting symbols for display. Lower values appear first.

DocType [Struct]

DocumenterReference.DocType Type

primitive type DocType <: Enum{Int32} 32

Enumeration of documentation element types recognized by the API reference generator.

Values

• DOCTYPE_ABSTRACT_TYPE: An abstract type declaration

• DOCTYPE_CONSTANT: A constant binding (including non-function, non-type values)

• DOCTYPE_FUNCTION: A function or callable

• DOCTYPE_MACRO: A macro (name starts with @)

• DOCTYPE_MODULE: A submodule

• DOCTYPE_STRUCT: A concrete struct type

PAGE_CONTENT_ACCUMULATOR [Constant]

DocumenterReference.PAGE_CONTENT_ACCUMULATOR Constant

PAGE_CONTENT_ACCUMULATOR::Dict{String, Vector{Tuple{Module, Vector{String}, Vector{String}}}}

Global accumulator for multi-module combined pages. Maps output filename to a list of (module, public_docstrings, private_docstrings) tuples.

_Config [Struct]

DocumenterReference._Config Type

struct _Config

Internal configuration for API reference generation.

Fields

• current_module::Module: The module being documented.

• subdirectory::String: Output directory for generated API pages.

• modules::Dict{Module,Vector{String}}: Mapping of modules to their source files. When a module is specified as Module => files, the files are stored here.

• sort_by::Function: Custom sort function for symbols.

• exclude::Set{Symbol}: Symbol names to exclude from documentation.

• public::Bool: Flag to generate public API page.

• private::Bool: Flag to generate private API page.

• title::String: Title displayed at the top of the generated page.

• title_in_menu::String: Title displayed in the navigation menu.

• source_files::Vector{String}: Global source file paths (fallback if no module-specific files).

• filename::String: Base filename (without extension) for the markdown file.

• include_without_source::Bool: If true, include symbols whose source file cannot be determined.

• external_modules_to_document::Vector{Module}: Additional modules to search for docstrings.

• public_title::String: Custom title for public API page (empty string uses default).

• private_title::String: Custom title for private API page (empty string uses default).

• public_description::String: Custom description for public API page (empty string uses default).

• private_description::String: Custom description for private API page (empty string uses default).

_build_api_page [Function]

DocumenterReference._build_api_page Function

_build_api_page(
    document::Documenter.Document,
    config::DocumenterReference._Config
)

Generate public and/or private API reference pages for a module. Accumulates content in PAGE_CONTENT_ACCUMULATOR for later finalization.

Arguments

• document::Documenter.Document: the Documenter document object.

• config::_Config: configuration for the API page generation.

Returns

• Nothing.

_build_combined_page_content [Function]

DocumenterReference._build_combined_page_content Function

_build_combined_page_content(
    modules_str::String,
    module_contents
) -> Tuple{String, Vector{String}}

Build the overview and docstrings for a combined (Public + Private) API page.

Arguments

• modules_str::String: comma-separated list of module names.

• module_contents: vector of (module, public_docs, private_docs) tuples.

Returns

• Tuple{String, Vector{String}}: overview markdown and docstring blocks.

_build_page_path [Function]

DocumenterReference._build_page_path Function

_build_page_path(
    subdirectory::String,
    filename::String
) -> String

Build the page path by joining subdirectory and filename. Handles special cases where subdirectory is "." or empty.

Arguments

• subdirectory::String: output subdirectory ("." or empty for current directory).

• filename::String: markdown filename.

Returns

• String: complete page path.

_build_page_return_structure [Function]

DocumenterReference._build_page_return_structure Function

_build_page_return_structure(
    title_in_menu::String,
    subdirectory::String,
    filename::String,
    public::Bool,
    private::Bool
) -> Union{Pair{String, Vector{Pair{String, String}}}, Pair{String, String}}

Build the return structure for automatic_reference_documentation.

Arguments

• title_in_menu::String: title displayed in navigation menu.

• subdirectory::String: output subdirectory.

• filename::String: base filename for generated markdown.

• public::Bool: whether documenting public API.

• private::Bool: whether documenting private API.

Returns

• Pair: structure suitable for automatic_reference_documentation, either a single page or nested public/private pages.

_build_private_page_content [Function]

DocumenterReference._build_private_page_content Function

_build_private_page_content(
    modules_str::String,
    module_contents,
    is_split::Bool;
    custom_title,
    custom_description
) -> Tuple{String, Vector{String}}

Build the overview and docstrings for a private API page.

Arguments

• modules_str::String: comma-separated list of module names.

• module_contents: vector of (module, public_docs, private_docs) tuples.

• is_split::Bool: whether this is part of a split public/private documentation.

• custom_title::String: optional custom title (empty string uses default).

• custom_description::String: optional custom description (empty string uses default).

Returns

• Tuple{String, Vector{String}}: overview markdown and docstring blocks.

_build_public_page_content [Function]

DocumenterReference._build_public_page_content Function

_build_public_page_content(
    modules_str::String,
    module_contents,
    is_split::Bool;
    custom_title,
    custom_description
) -> Tuple{String, Vector{String}}

Build the overview and docstrings for a public API page.

Arguments

• modules_str::String: comma-separated list of module names.

• module_contents: vector of (module, public_docs, private_docs) tuples.

• is_split::Bool: whether this is part of a split public/private documentation.

• custom_title::String: optional custom title (empty string uses default).

• custom_description::String: optional custom description (empty string uses default).

Returns

• Tuple{String, Vector{String}}: overview markdown and docstring blocks.

_classify_symbol [Function]

DocumenterReference._classify_symbol Function

_classify_symbol(
    obj,
    name_str::String
) -> DocumenterReference.DocType

Classify a symbol by its type (function, macro, struct, constant, module, abstract type).

Arguments

• obj: the symbol object to classify.

• name_str::String: the name of the symbol as a string.

Returns

• DocType: the classification of the symbol.

_collect_external_module_docstrings [Function]

DocumenterReference._collect_external_module_docstrings Function

_collect_external_module_docstrings(
    config::DocumenterReference._Config
) -> Vector{String}

Collect docstrings for methods from external modules defined in source files.

Arguments

• config::_Config: configuration for documentation generation.

Returns

• Vector{String}: docstring blocks for external module methods.

_collect_methods_from_source_files [Function]

DocumenterReference._collect_methods_from_source_files Function

_collect_methods_from_source_files(
    mod::Module,
    source_files::Vector{String}
) -> Dict{Symbol, Vector{Method}}

Collect all methods from a module that are defined in the given source files.

Arguments

• mod::Module: the module to search for methods.

• source_files::Vector{String}: source file paths to filter by.

Returns

• Dict{Symbol, Vector{Method}}: mapping of function names to their methods.

_collect_module_docstrings [Function]

DocumenterReference._collect_module_docstrings Function

_collect_module_docstrings(
    config::DocumenterReference._Config,
    symbol_list;
    include_module
) -> Vector{String}

Collect docstring blocks for symbols from the current module.

Arguments

• config::_Config: configuration for documentation generation.

• symbol_list: list of symbols to document.

• include_module::Bool: whether to include the module docstring (default: true).

Returns

• Vector{String}: docstring blocks formatted for Documenter.

_collect_private_docstrings [Function]

DocumenterReference._collect_private_docstrings Function

_collect_private_docstrings(
    config::DocumenterReference._Config,
    symbol_list
) -> Vector{String}

Collect docstring blocks for private symbols, including external module methods.

Arguments

• config::_Config: configuration for documentation generation.

• symbol_list: list of private symbols to document.

Returns

• Vector{String}: docstring blocks formatted for Documenter.

_default_basename [Function]

DocumenterReference._default_basename Function

_default_basename(
    filename::String,
    public::Bool,
    private::Bool
) -> String

Compute the default base filename for the generated markdown file.

Arguments

• filename::String: user-provided filename (empty to use default).

• public::Bool: whether documenting public API.

• private::Bool: whether documenting private API.

Returns

• String: base filename for the generated markdown file.

_default_title [Function]

DocumenterReference._default_title Function

_default_title(public::Bool, private::Bool) -> String

Compute the default title based on public/private flags. Returns empty string for single pages to use configured title.

Arguments

• public::Bool: whether documenting public API.

• private::Bool: whether documenting private API.

Returns

• String: default title, or empty string to use configured title.

_exported_symbols [Function]

DocumenterReference._exported_symbols Function

_exported_symbols(
    mod::Module
) -> @NamedTuple{exported::Vector{Pair{Symbol, DocumenterReference.DocType}}, private::Vector{Pair{Symbol, DocumenterReference.DocType}}}

Classify all symbols in a module into exported and private categories. Returns a NamedTuple with exported and private fields, each containing sorted lists of (Symbol, DocType) pairs.

Arguments

• mod::Module: the module to analyze.

Returns

• NamedTuple: with exported and private fields, each containing sorted lists of (Symbol, DocType) pairs.

_finalize_api_pages [Function]

DocumenterReference._finalize_api_pages Function

_finalize_api_pages(document::Documenter.Document)

Finalize all accumulated API pages by combining content from multiple modules.

Arguments

• document::Documenter.Document: the Documenter document object.

Returns

• Nothing.

_format_datatype_for_docs [Function]

DocumenterReference._format_datatype_for_docs Function

_format_datatype_for_docs(T::DataType) -> String

Format a DataType for use in @docs blocks.

Arguments

• T::DataType: the DataType to format.

Returns

• String: formatted DataType string with full module qualification.

_format_type_for_docs [Function]

DocumenterReference._format_type_for_docs Function

_format_type_for_docs(T) -> String

Format a type for use in Documenter's @docs block. Always fully qualifies types to avoid UndefVarError when Documenter evaluates in Main.

Arguments

• T: the type to format.

Returns

• String: formatted type string with :: prefix and full module qualification.

_format_type_param [Function]

DocumenterReference._format_type_param Function

_format_type_param(p) -> Any

Format a type parameter (can be a type or a value like an integer).

Arguments

• p: the type parameter to format.

Returns

• String: formatted type parameter string.

_get_effective_source_files [Function]

DocumenterReference._get_effective_source_files Function

_get_effective_source_files(
    config::DocumenterReference._Config
) -> Vector{String}

Determine the effective source files for filtering symbols. Priority: module-specific files > global source_files > empty (no filtering).

Arguments

• config::_Config: configuration object.

Returns

• Vector{String}: effective source files for the current module.

_get_source_file [Function]

DocumenterReference._get_source_file Function

_get_source_file(
    mod::Module,
    key::Symbol,
    type::DocumenterReference.DocType
) -> Union{Nothing, String}

Determine the source file path where a symbol is defined. Returns nothing if the source file cannot be determined.

Arguments

• mod::Module: the module containing the symbol.

• key::Symbol: the symbol name.

• type::DocType: the type of the symbol.

Returns

• Union{String, Nothing}: absolute path to the source file, or nothing if undetermined.

_get_source_from_docstring [Function]

DocumenterReference._get_source_from_docstring Function

_get_source_from_docstring(
    mod::Module,
    key::Symbol
) -> Union{Nothing, String}

Try to get source file path from docstring metadata.

Arguments

• mod::Module: the module containing the symbol.

• key::Symbol: the symbol name.

Returns

• Union{String, Nothing}: absolute path to the source file, or nothing if not found.

_get_source_from_methods [Function]

DocumenterReference._get_source_from_methods Function

_get_source_from_methods(obj) -> Union{Nothing, String}

Try to get source file path from method definitions.

Arguments

• obj: the function or type object to inspect.

Returns

• Union{String, Nothing}: absolute path to the source file, or nothing if not found.

_has_documentation [Function]

DocumenterReference._has_documentation Function

_has_documentation(
    mod::Module,
    key::Symbol,
    type::DocumenterReference.DocType,
    modules::Dict
) -> Bool

Check if a symbol has documentation. Logs a warning if not.

Arguments

• mod::Module: the module containing the symbol.

• key::Symbol: the symbol name.

• type::DocType: the type of the symbol.

• modules::Dict: mapping of modules to their source files.

Returns

• Bool: true if the symbol has documentation, false otherwise.

_iterate_over_symbols [Function]

DocumenterReference._iterate_over_symbols Function

_iterate_over_symbols(
    f,
    config::DocumenterReference._Config,
    symbol_list
)

Iterate over symbols, applying a function to each documented symbol. Filters symbols based on exclusion list, documentation presence, and source files.

Arguments

• f: function to apply to each symbol, receives (key::Symbol, type::DocType).

• config::_Config: configuration for documentation generation.

• symbol_list: list of symbols to iterate over.

Returns

• Nothing.

_method_signature_string [Function]

DocumenterReference._method_signature_string Function

_method_signature_string(
    m::Method,
    mod::Module,
    key::Symbol
) -> String

Generate a Documenter-compatible signature string for a method. Returns a string like Module.func(::Type1, ::Type2) for use in @docs blocks.

Arguments

• m::Method: the method to format.

• mod::Module: the module containing the method.

• key::Symbol: the function name.

Returns

• String: Documenter-compatible signature string.

_normalize_paths [Function]

DocumenterReference._normalize_paths Function

_normalize_paths(paths) -> Any

Normalize a collection of paths to absolute paths.

Arguments

• paths: collection of file paths to normalize.

Returns

• Vector{String}: vector of absolute paths, or empty vector if input is empty.

_parse_primary_modules [Function]

DocumenterReference._parse_primary_modules Function

_parse_primary_modules(
    primary_modules::Vector
) -> Dict{Module, Vector{String}}

Parse the primary_modules argument into a dictionary mapping modules to their source files. Handles both plain modules and Module => files pairs.

Arguments

• primary_modules::Vector: vector of modules or Module => files pairs.

Returns

• Dict{Module, Vector{String}}: dictionary mapping each module to its source file paths.

Throws

• CTBase.Exceptions.IncorrectArgument: if an element is neither a Module nor a Pair.

_passes_source_filter [Function]

DocumenterReference._passes_source_filter Function

_passes_source_filter(
    mod::Module,
    key::Symbol,
    type::DocumenterReference.DocType,
    source_files::Vector{String},
    include_without_source::Bool
) -> Bool

Check if a symbol passes the source file filter.

Arguments

• mod::Module: the module containing the symbol.

• key::Symbol: the symbol name.

• type::DocType: the type of the symbol.

• source_files::Vector{String}: source file paths to filter by.

• include_without_source::Bool: whether to include symbols without source location.

Returns

• Bool: true if the symbol passes the filter, false otherwise.

_register_config [Function]

DocumenterReference._register_config Function

_register_config(
    current_module::Module,
    subdirectory::String,
    modules::Dict{Module, Vector{String}},
    sort_by::Function,
    exclude::Set{Symbol},
    public::Bool,
    private::Bool,
    title::String,
    title_in_menu::String,
    source_files::Vector{String},
    filename::String,
    include_without_source::Bool,
    external_modules_to_document::Vector{Module},
    public_title::String,
    private_title::String,
    public_description::String,
    private_description::String
)

Create and register a _Config in the global CONFIG vector.

Arguments

• current_module::Module: the module being documented.

• subdirectory::String: output subdirectory for generated documentation.

• modules::Dict{Module,Vector{String}}: mapping of modules to their source files.

• sort_by::Function: sorting function for symbols.

• exclude::Set{Symbol}: symbols to exclude from documentation.

• public::Bool: whether to document public API.

• private::Bool: whether to document private API.

• title::String: page title.

• title_in_menu::String: title displayed in navigation menu.

• source_files::Vector{String}: global source files for filtering.

• filename::String: base filename for generated markdown.

• include_without_source::Bool: whether to include symbols without source location.

• external_modules_to_document::Vector{Module}: external modules to document.

• public_title::String: title for public API section.

• private_title::String: title for private API section.

• public_description::String: description for public API section.

• private_description::String: description for private API section.

Returns

• Nothing.

_to_string [Function]

DocumenterReference._to_string Function

_to_string(x::DocumenterReference.DocType) -> String

Convert a DocType enumeration value to its string representation.

Arguments

• x::DocType: the DocType value to convert.

Returns

• String: human-readable string representation.

reset_config! [Function]

DocumenterReference.reset_config! Function

reset_config!()

Clear the global CONFIG vector and PAGE_CONTENT_ACCUMULATOR. Useful between documentation builds or for testing.

Returns

• Nothing.

---

From TestRunner

TestRunInfo [Struct]

TestRunner.TestRunInfo Type

struct TestRunInfo

Context information passed to test callbacks (on_test_start, on_test_done).

Provides details about the current test being executed, including progress information (index, total) and execution results (status, error, elapsed).

Fields

• spec::TestSpec: test identifier (Symbol or relative path String)

• filename::String: absolute path of the included test file

• func_symbol::Union{Symbol,Nothing}: function to call (nothing if eval_mode=false)

• index::Int: 1-based index of the current test in the selected list

• total::Int: total number of selected tests

• status::Symbol: one of :pre_eval, :post_eval, :skipped, :error, :test_failed

• error::Union{Exception,Nothing}: captured exception when status == :error

• elapsed::Union{Float64,Nothing}: wall-clock seconds for the eval phase (only in on_test_done)

Example

julia> using CTBase.TestRunner

julia> info = TestRunner.TestRunInfo(
           :utils, 
           "/path/to/test_utils.jl", 
           :test_utils, 
           3, 10, 
           :post_eval, 
           nothing, 
           1.23
       )
TestRunner.TestRunInfo(:utils, "/path/to/test_utils.jl", :test_utils, 3, 10, :post_eval, nothing, 1.23)

julia> info.status
:post_eval

julia> info.elapsed
1.23

TestSpec [Struct]

TestRunner.TestSpec Type

Union type representing a test specification.

A test spec can be either:

• Symbol: A logical test name (e.g., :utils, :core)

• String: A relative file path or glob pattern (e.g., "suite/test_utils.jl", "suite/core/*")

This type is used throughout TestRunner to represent both user-provided selections and internal test identifiers.

Notes

• Symbol specs are resolved via filename_builder and funcname_builder

• String specs are treated as relative paths from test_dir

• Glob patterns are supported for String specs

See also: CTBase.DevTools.run_tests

_PROGRESS_BAR_THRESHOLD [Constant]

TestRunner._PROGRESS_BAR_THRESHOLD Constant

_PROGRESS_BAR_THRESHOLD

Internal constant defining the maximum number of tests for full-resolution progress bars.

When the total number of tests is ≤ _PROGRESS_BAR_THRESHOLD (100), the progress bar displays one character per test with cumulative coloring (each test gets its own colored block). Beyond this threshold, the bar switches to compressed mode with uniform coloring.

This threshold balances visual clarity with terminal width constraints.

_bar_width [Function]

TestRunner._bar_width Function

_bar_width(total::Int64) -> Int64
_bar_width(
    total::Int64,
    progress_bar_threshold::Int64
) -> Int64

Compute the progress bar character width based on the number of tests.

• total ≤ progress_bar_threshold: width equals total (one block per test).

• total > progress_bar_threshold: fixed width of progress_bar_threshold (some tests skip a block advance).

Arguments

• total::Int: Total number of tests

• progress_bar_threshold::Int: Maximum tests for full-resolution progress bar (default: 100)

Returns

• Int: Character width for the progress bar (0 if total ≤ 0)

Example

julia> using CTBase.TestRunner

julia> TestRunner._bar_width(10)
10

julia> TestRunner._bar_width(25)
25

julia> TestRunner._bar_width(0)
0

julia> TestRunner._bar_width(100, progress_bar_threshold=30)
30

_block_char_for_severity [Function]

TestRunner._block_char_for_severity Function

_block_char_for_severity(sev::Int) -> String

Internal helper to map severity level to block character for colorblind-friendly display.

Uses distinct glyphs to ensure progress bars are readable without color:

• Success: █ (solid block)

• Skipped: ┆ (thin vertical line)

• Failure: ▚ (diagonal pattern)

Arguments

• sev::Int: Severity level (3=failure, 2=skipped, 1=success)

Returns

• String: Unicode block character representing the severity

_builder_to_string [Function]

TestRunner._builder_to_string Function

_builder_to_string(x) -> Any

Convert a Symbol or String to String.

This helper function ensures that builder function outputs are always converted to strings for consistent handling.

Arguments

• x: Symbol or String to convert

Returns

• String: The string representation of x

Example

julia> TestRunner._builder_to_string(:utils)
"utils"

julia> TestRunner._builder_to_string("utils")
"utils"

_collect_test_files_recursive [Function]

TestRunner._collect_test_files_recursive Function

_collect_test_files_recursive(
    test_dir::AbstractString
) -> Vector{String}

Recursively collect all .jl files in test_dir (excluding runtests.jl).

Returns relative paths from test_dir, sorted alphabetically.

Arguments

• test_dir::AbstractString: Root directory to search

Returns

• Vector{String}: Relative paths to all .jl files (excluding runtests.jl)

Example

# Assuming test_dir contains:
# - test/utils.jl
# - test/core/test_core.jl
# - test/runtests.jl

julia> TestRunner._collect_test_files_recursive("test")
2-element Vector{String}:
 "test/core/test_core.jl"
 "test/utils.jl"

_color_for_severity [Function]

TestRunner._color_for_severity Function

_color_for_severity(sev::Int, io::IO) -> String

Internal helper to map severity level to an ANSI opening code, respecting the colour capability of io and the active CTBase colour palette.

Arguments

• sev::Int: Severity level (3=failure, 2=skipped, 1=success)

• io::IO: Output stream (checked for colour support)

Returns

• String: ANSI colour escape code, or empty string when colour is disabled

_default_on_test_done [Function]

TestRunner._default_on_test_done Function

_default_on_test_done(info::TestRunInfo)

Backward compatibility shim for the default test completion callback.

Creates a fresh stateful callback via _make_default_on_test_done and invokes it with the given info. This function exists for compatibility with existing code/tests that expect a stateless callback signature.

For new code, prefer using _make_default_on_test_done directly to create a persistent callback that maintains test history across multiple invocations.

Arguments

• info::TestRunInfo: Test execution information

See also: _make_default_on_test_done

_ensure_jl [Function]

TestRunner._ensure_jl Function

_ensure_jl(filename::AbstractString) -> AbstractString

Ensure that a filename ends with .jl extension.

If the filename already ends with .jl, returns it unchanged. Otherwise, appends .jl to the filename.

Arguments

• filename::AbstractString: Base filename with or without .jl extension

Returns

• String: Filename guaranteed to end with .jl

Example

julia> TestRunner._ensure_jl("test_utils")
"test_utils.jl"

julia> TestRunner._ensure_jl("test_utils.jl")
"test_utils.jl"

_find_symbol_test_file_rel [Function]

TestRunner._find_symbol_test_file_rel Function

_find_symbol_test_file_rel(
    name::Symbol,
    filename_builder::Function;
    test_dir
)

Find the relative path to a test file for a given symbol name.

Uses the filename_builder to construct the expected filename, then searches for files matching that basename. If multiple matches exist (e.g., files in different subdirectories), prefers the shallowest path.

Arguments

• name::Symbol: Test name to resolve

• filename_builder::Function: Function that maps test names to filenames

• test_dir::AbstractString: Root directory containing test files

Returns

• String: Relative path to the matching test file

• nothing: If no matching file is found

Notes

• Searches recursively in test_dir

• Excludes runtests.jl from consideration

• Prefers shallower paths when multiple matches exist

• Returns the exact relative path if found

See also: TestRunner._collect_test_files_recursive, TestRunner._ensure_jl

_format_progress_line [Function]

TestRunner._format_progress_line Function

_format_progress_line(
    io::IO,
    info::TestRunner.TestRunInfo;
    history,
    cumulative_severity,
    progress_bar_threshold,
    show_progress_bar
)

Write a styled progress line for a completed test to io.

Uses the active CTBase colour palette (see CTBase.Core.set_palette!): the success, warning, and error roles drive the status colour; type drives the index; emphasis and muted drive boldness and the time suffix. Colour is only emitted when get(io, :color, false) is true.

Arguments

• io::IO: Output stream to write to

• info::TestRunInfo: Test execution information

• history::Union{Vector{Int},Nothing}: Optional history array for per-test coloring (default: nothing)

• cumulative_severity::Union{Int,Nothing}: Optional cumulative severity for coloring (default: nothing)

• progress_bar_threshold::Int: Maximum tests for full-resolution progress bar (default: 100)

• show_progress_bar::Bool: Show graphical progress bar [█░░░...] (default: true)

Notes

• Format: [progress_bar] symbol [index/total] spec (time) status

• Time is displayed with one decimal place when available

• Cursor-style display: In full-resolution mode (total ≤ threshold), only the current test position is filled for successes, while failures and skips persist at their positions. This creates a lighter, cursor-like visual where past successes are ephemeral.

Example

julia> using CTBase.TestRunner, IOBuffer

julia> info = TestRunner.TestRunInfo(
           :test_example,
           "/path/to/test.jl",
           :test_example,
           5, 10,
           :post_eval,
           nothing,
           1.23
       );

julia> buf = IOBuffer();
julia> TestRunner._format_progress_line(buf, info);
julia> String(take!(buf))
"[█████░░░░░░░░░░░] ✓ [05/10] test_example (1.2s)"

_glob_to_regex [Function]

TestRunner._glob_to_regex Function

_glob_to_regex(pattern::AbstractString) -> Regex

Convert a glob pattern (using * and ?) into a regular expression.

The returned regex is anchored (matches the full string).

Arguments

• pattern::AbstractString: Glob pattern to convert

Returns

• Regex: Anchored regular expression equivalent to the glob pattern

Example

julia> using CTBase.TestRunner

julia> TestRunner._glob_to_regex("test_*.jl")
r"^test_.*\.jl$"

julia> TestRunner._glob_to_regex("suite/test_?.jl")
r"^suite/test.\.jl$"

_has_failures_in_results [Function]

TestRunner._has_failures_in_results Function

_has_failures_in_results(ts::Test.DefaultTestSet) -> Bool
_has_failures_in_results(
    ts::Test.DefaultTestSet,
    from::Int64
) -> Bool

Recursively scan a DefaultTestSet results for Test.Fail or Test.Error entries, starting at index from.

This is used to detect @test failures that occurred during a specific eval by comparing the results count before and after the eval. The anynonpass field is unreliable because it is only updated when a testset finishes (in Test.finish).

Arguments

• ts::Test.DefaultTestSet: TestSet to scan

• from::Int: Starting index for scanning (default: 1)

Returns

• Bool: true if any failures are found, false otherwise

Example

julia> using CTBase.TestRunner, Test

julia> ts = Test.DefaultTestSet("test", [])
julia> Test.@testset "example" begin
           Test.@test 1 == 1
           Test.@test 2 == 0  # This will fail
       end
Test.DefaultTestSet("example", Any[Test.Pass(1), Test.Fail("false")])

julia> TestRunner._has_failures_in_results(ts)
true

_make_default_on_test_done [Function]

TestRunner._make_default_on_test_done Function

_make_default_on_test_done(
    io::IO,
    total::Int64
) -> TestRunner.var"#update#_make_default_on_test_done##0"{<:IO, Int64, Bool, Base.RefValue{Int64}, Vector{Int64}}
_make_default_on_test_done(
    io::IO,
    total::Int64,
    progress_bar_threshold::Int64
) -> TestRunner.var"#update#_make_default_on_test_done##0"{<:IO, Int64, Bool, Base.RefValue{Int64}, Vector{Int64}}
_make_default_on_test_done(
    io::IO,
    total::Int64,
    progress_bar_threshold::Int64,
    show_progress_bar::Bool
) -> TestRunner.var"#update#_make_default_on_test_done##0"{<:IO, Int64, Bool, Base.RefValue{Int64}, Vector{Int64}}

Create a stateful progress callback for on_test_done. Prints to io.

Arguments

• io::IO: Output stream for progress display

• total::Int: Total number of tests

• progress_bar_threshold::Int: Maximum tests for full-resolution progress bar (default: 100)

• show_progress_bar::Bool: Show graphical progress bar [█░░░...] (default: true)

Returns

• Function: Callback function that accepts TestRunInfo and updates progress display

Notes

• This is the default callback used when show_progress_line=true and no custom on_test_done is provided

• The returned callback maintains state (history, max_severity) across invocations

• Outputs a formatted progress line to io with colors and timing information

• When show_progress_bar=false, displays minimal output without the graphical bar

Example

julia> using CTBase.TestRunner

julia> cb = TestRunner._make_default_on_test_done(stdout, 10)

julia> info = TestRunner.TestRunInfo(
           :test_example,
           "/path/to/test.jl",
           :test_example,
           5, 10,
           :post_eval,
           nothing,
           1.23
       );

julia> cb(info)
[█████░░░░░░░░░░░] ✓ [05/10] test_example (1.2s)

_normalize_available_tests [Function]

TestRunner._normalize_available_tests Function

_normalize_available_tests(
    available_tests
) -> Vector{Union{String, Symbol}}

Normalize and validate the available_tests argument.

Converts the input to a Vector{TestSpec} and validates that all entries are either Symbol or String. Returns an empty vector if available_tests is nothing.

Arguments

• available_tests: nothing, Vector, or Tuple containing Symbol or String entries

Returns

• Vector{TestSpec}: Normalized vector of test specifications

Throws

• ArgumentError: If available_tests is not a Vector/Tuple or contains invalid entries

Example

julia> TestRunner._normalize_available_tests([:utils, "suite/*"])
2-element Vector{Union{Symbol, String}}:
 :utils
 "suite/*"

julia> TestRunner._normalize_available_tests(nothing)
Union{Symbol, String}[]

_normalize_selections [Function]

TestRunner._normalize_selections Function

_normalize_selections(
    selections::Vector{String},
    candidates::Vector{<:Union{String, Symbol}}
) -> Vector{String}

Normalize user-provided selection patterns before glob matching.

Applied transformations:

• Strip trailing / (e.g. "suite/exceptions/" → "suite/exceptions")

• If a selection contains no glob wildcard (* or ?) and matches a directory prefix of at least one candidate, expand it to "selection/*" so that all files under that directory are selected.

The original selection is always kept so that exact-name matches still work.

Arguments

• selections::Vector{String}: User-provided selection patterns

• candidates::Vector{<:TestSpec}: Available test candidates

Returns

• Vector{String}: Normalized selection patterns

Example

julia> using CTBase.TestRunner

julia> TestRunner._normalize_selections(
           ["suite/"], 
           ["suite/test_a.jl", "suite/test_b.jl"]
       )
2-element Vector{String}:
 "suite"
 "suite/*"

_parse_test_args [Function]

TestRunner._parse_test_args Function

_parse_test_args(
    args::Vector{String}
) -> Tuple{Vector{String}, Bool, Bool}

Parse command-line test arguments, filtering out coverage-related flags.

Arguments

• args::Vector{String}: Raw command-line arguments

Returns

• Tuple{Vector{String}, Bool, Bool}: (selections, run_all, dry_run) where:

  • selections: selection patterns provided by the user (as strings)

  • run_all: whether -a / --all was present

  • dry_run: whether -n / --dryrun was present

Notes

• Coverage flags (coverage=true, --coverage, etc.) are automatically filtered out

• Selection patterns starting with test/ or test\ are automatically stripped so that users can write test/suite/foo or suite/foo interchangeably

Example

julia> using CTBase.TestRunner

julia> TestRunner._parse_test_args(["utils", "-a", "--dryrun"])
(["utils"], true, true)

julia> TestRunner._parse_test_args(["test/suite", "coverage=true"])
(["suite"], false, false)

_progress_bar [Function]

TestRunner._progress_bar Function

_progress_bar(index::Int64, total::Int64; width) -> String

Render a progress bar string like [████████░░░░░░░░░░░░].

When width is nothing (default), the width is computed automatically via _bar_width(total). Returns an empty string when the bar is hidden.

Arguments

• index::Int: current progress (1-based)

• total::Int: total number of items

• width::Union{Int,Nothing}: character width of the bar (default: auto)

Returns

• String: Progress bar string, or empty string if hidden

Example

julia> using CTBase.TestRunner

julia> TestRunner._progress_bar(5, 10)
"[█████░░░░░]"

julia> TestRunner._progress_bar(5, 10; width=20)
"[██████████░░░░░░░░░░]"

julia> TestRunner._progress_bar(0, 10; width=5)
"[░░░░░]"

_resolve_test [Function]

TestRunner._resolve_test Function

_resolve_test(
    spec::Union{String, Symbol};
    filename_builder,
    funcname_builder,
    eval_mode,
    test_dir
)

Resolve a test spec into an absolute filename and function symbol.

Handles both String specs (relative paths) and Symbol specs (logical names). Raises errors if the file is not found or if eval_mode=true but no function can be determined.

Arguments

• spec::TestSpec: Test specification to resolve

• filename_builder::Function: Function to map test names to filenames

• funcname_builder::Function: Function to map test names to function names

• eval_mode::Bool: Whether to resolve a function name

• test_dir::String: Root directory containing test files

Returns

• Tuple{String, Union{Symbol,Nothing}}: (filename, func_symbol) where:

  • filename: Absolute path to the test file

  • func_symbol: Function symbol to call (or nothing if eval_mode=false)

Throws

• ErrorException: If the test file is not found

• ErrorException: If eval_mode=true but no function can be determined

Notes

• This function is not part of the public API

• Use run_tests for running tests with proper error handling

_run_single_test [Function]

TestRunner._run_single_test Function

_run_single_test(
    spec::Union{String, Symbol};
    filename_builder,
    funcname_builder,
    eval_mode,
    test_dir,
    index,
    total,
    on_test_start,
    on_test_done
)

Run a single selected test.

This helper:

• Resolves a test filename via filename_builder

• Includes the file into Main

• Calls on_test_start (if provided) after include, before eval

• Optionally evaluates a function (via funcname_builder) when eval_mode=true

• Calls on_test_done (if provided) after eval, skip, or error

Arguments

• spec::TestSpec: Test specification to run

• filename_builder::Function: Function to map test names to filenames

• funcname_builder::Function: Function to map test names to function names

• eval_mode::Bool: Whether to evaluate the function after include

• test_dir::String: Root directory containing test files

• index::Int: 1-based index in the selected list (default: 1)

• total::Int: Total number of selected tests (default: 1)

• on_test_start::Union{Function,Nothing}: Callback before eval (default: nothing)

• on_test_done::Union{Function,Nothing}: Callback after eval (default: nothing)

Notes

• This function is not part of the public API

• Use run_tests for running multiple tests with proper orchestration

_select_tests [Function]

TestRunner._select_tests Function

_select_tests(
    selections::Vector{String},
    available_tests::AbstractVector{<:Union{String, Symbol}},
    run_all::Bool,
    filename_builder::Function;
    test_dir
) -> Vector{Union{String, Symbol}}

Determine which tests to run based on selections, available_tests filter, and file globbing.

1. Identify potential test files in test_dir (default: test/).

2. Filter by available_tests if provided.

3. Filter by selections (interpreted as globs) if present.

Arguments

• selections::Vector{String}: User-provided selection patterns

• available_tests::AbstractVector{<:TestSpec}: Allowed tests (empty = auto-discovery)

• run_all::Bool: Whether to run all available tests

• filename_builder::Function: Function to map test names to filenames

• test_dir::String: Root directory containing test files

Returns

• Vector{TestSpec}: Selected test specifications

Notes

• If available_tests is empty, this function falls back to an auto-discovery heuristic using the filename stem as the candidate test name

• Selection arguments are matched against multiple representations of each candidate

_severity [Function]

TestRunner._severity Function

_severity(status::Symbol) -> Int

Internal helper to map test status to severity level for display formatting.

Arguments

• status::Symbol: Test status (:error, :test_failed, :skipped, or success)

Returns

• Int: Severity level (3=failure, 2=skipped, 1=success)

_strip_test_prefix [Function]

TestRunner._strip_test_prefix Function

_strip_test_prefix(s::AbstractString) -> Any

Strip a leading test/ or test\ prefix from a selection pattern.

This allows users to type test/suite/foo instead of suite/foo since the test directory is already the root for pattern matching.

Arguments

• s::AbstractString: Selection pattern to process

Returns

• String: Pattern with test/ or test\ prefix stripped (if present)

Example

julia> using CTBase.TestRunner

julia> TestRunner._strip_test_prefix("test/suite/foo")
"suite/foo"

julia> TestRunner._strip_test_prefix("suite/foo")
"suite/foo"

julia> TestRunner._strip_test_prefix("test\windows\path")
"windows\path"