Public API

Descriptions

Description management utilities for CTBase.

This module provides types and functions for working with symbolic descriptions, including type aliases, manipulation functions, and completion utilities.

Organization

The Descriptions module is organized into thematic submodules:

• types.jl: Core type definitions (DescVarArg, Description)
• similarity.jl: Similarity computation and intelligent suggestions
• display.jl: Display utilities for descriptions
• catalog.jl: Catalog management functions (add, remove)
• complete.jl: Description completion utilities

Public API

Exported Types

• DescVarArg: Variable number of symbols type alias
• Description: Tuple of symbols type alias

Exported Functions

• add: Add descriptions to a catalog
• complete: Find matching descriptions with intelligent suggestions
• remove: Remove symbols from descriptions

A type alias representing a variable number of Symbols.

Example

julia> using CTBase

julia> CTBase.DescVarArg
Vararg{Symbol}

See also: Description

struct Tuple{Vararg{Symbol}}

A description is a tuple of symbols, used to declarative encode algorithms or configurations.

Example

Base.show is overloaded for descriptions, so tuples of descriptions are printed one per line:

julia> using CTBase

julia> display(((:a, :b), (:b, :c)))
(:a, :b)
(:b, :c)

See also: DescVarArg

add(
    _::Tuple{},
    y::Tuple{Vararg{Symbol}}
) -> Tuple{Tuple{Vararg{Symbol}}}

Initialize a new description catalog with a single description y.

Arguments

• y::Description: The initial description to add

Returns

• Tuple{Vararg{Description}}: A tuple containing only the description y

Example

julia> using CTBase

julia> descriptions = ()
julia> descriptions = CTBase.add(descriptions, (:a,))
(:a,)
julia> print(descriptions)
((:a,),)
julia> descriptions[1]
(:a,)

See also: Description

add(
    x::Tuple{Vararg{Tuple{Vararg{Symbol}}}},
    y::Tuple{Vararg{Symbol}}
) -> Tuple{Tuple{Vararg{Symbol}}}

Add the description y to the catalog x if it is not already present.

Arguments

• x::Tuple{Vararg{Description}}: Existing description catalog
• y::Description: Specific description to add

Returns

• Tuple{Vararg{Description}}: The updated catalog with y appended

Throws

• IncorrectArgument: If the description y is already contained in x

Example

julia> using CTBase

julia> descriptions = ()
julia> descriptions = CTBase.add(descriptions, (:a,))
(:a,)
julia> descriptions = CTBase.add(descriptions, (:b,))
(:a,)
(:b,)
julia> descriptions = CTBase.add(descriptions, (:b,))
ERROR: IncorrectArgument: the description (:b,) is already in ((:a,), (:b,))
       Got: (:b,)
       Expected: a unique description not in the catalog
       Suggestion: Check existing descriptions before adding, or use a different description
       Context: description catalog management

See also: complete, remove

complete(list::Symbol...; descriptions)

Select the most matching description from a catalog based on a partial list of symbols.

If multiple descriptions contain all the symbols in list, the one with the largest intersection is selected. If multiple descriptions have the same intersection size, the first one in the catalog wins (priority is top-to-bottom).

Arguments

• list::Symbol...: A variable number of symbols representing a partial description

Keyword Arguments

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

Returns

• Description: The best-matching description from the catalog

Throws

• AmbiguousDescription: If the catalog is empty or if no description contains all symbols in list.

Example

julia> using CTBase

julia> D = ((:a, :b), (:a, :b, :c), (:b, :c), (:a, :c))
(:a, :b)
(:b, :c)
(:a, :c)
julia> CTBase.complete(:a; descriptions=D)
(:a, :b)
julia> CTBase.complete(:a, :c; descriptions=D)
(:a, :b, :c)
julia> CTBase.complete((:a, :c); descriptions=D)
(:a, :b, :c)
julia> CTBase.complete(:f; descriptions=D)
ERROR: AmbiguousDescription: the description (:f,) is ambiguous / incorrect
       Description: (:f,)
       Valid candidates:
       - (:a, :b)
       - (:a, :b, :c)
       - (:b, :c)
       - (:a, :c)
       Suggestion: Available descriptions: (:a, :b), (:a, :b, :c), (:b, :c), (:a, :c)
       Context: description completion

Enhanced Error Features

When no matching description is found, the function provides suggestions based on similarity and lists existing candidates.

See also: compute_similarity, find_similar_descriptions, format_description_candidates

complete(list::Tuple{Vararg{Symbol}}; descriptions)

Convenience overload of complete for tuple inputs.

This method is equivalent to complete(list...; descriptions=descriptions).

Arguments

• list::Tuple{Vararg{Symbol}}: A tuple of symbols representing a partial description.

Keyword Arguments

• descriptions::Tuple{Vararg{Description}}: Candidate descriptions used for completion.

Returns

• Description: A description from descriptions that contains all symbols in list.

Throws

• $AmbiguousDescription$: If descriptions is empty, or if list is not contained in any candidate description.

remove(
    x::Tuple{Vararg{Symbol}},
    y::Tuple{Vararg{Symbol}}
) -> Tuple{Vararg{Symbol}}

Remove symbols from a description tuple.

Example

julia> using CTBase

julia> CTBase.remove((:a, :b, :c), (:a,))
(:b, :c)