Command Completion

Feather provides intelligent command completion through the usage complete subcommand. This enables hosts to offer tab-completion, IDE autocomplete, or any interactive completion UI.

Feather Extension

This is a Feather-specific feature, not part of standard TCL.

Why Use Completion?

When embedding Feather in an application (game console, CLI tool, REPL), you often want to help users discover available commands and their arguments. The completion system:

Returns structured completion candidates based on usage specs
Handles commands, subcommands, flags, and argument values
Supports nested script contexts (completing inside if bodies, etc.)
Works with any UI (terminal, GUI, web)

Try It

Experience completion in this interactive REPL. Press Tab to trigger completions, Shift+Tab to cycle back, and Enter to select.

Feather REPL

%

Basic Usage

tcl

usage complete script pos

Returns a list of completion candidates at byte position pos in script.

Return Format

Each candidate is a dict with these keys:

tcl

{text <string> type <category> help <description>}

For argument placeholders (when the user must provide a value):

tcl

{text {} type arg-placeholder name <arg-name> help <description>}

Completion Types

Type	Description
`command`	Top-level command name
`subcommand`	Subcommand from usage spec
`flag`	Flag option (-v, --verbose)
`value`	Value from `choices` list
`arg-placeholder`	Indicates user must provide a value

Examples

Command Completion

Output

Subcommand Completion

Output

Flag Completion

Output

Value Completion (from choices)

Output

Argument Placeholders

Output

Host Integration

Terminal REPL Example (Go)

go

func complete(script string, pos int) []Completion {
    // usage complete returns a native Go slice of objects
    result, _ := interp.Eval("usage", "complete", script, pos)
    
    candidates := result.ToList()
    var completions []Completion
    
    for _, c := range candidates {
        dict := c.ToDict()
        comp := Completion{
            Text: dict["text"].String(),
            Type: dict["type"].String(),
            Help: dict["help"].String(),
        }
        
        // Handle arg-placeholder specially
        if comp.Type == "arg-placeholder" {
            comp.Name = dict["name"].String()
            comp.Display = fmt.Sprintf("<%s>", comp.Name)
        } else {
            comp.Display = comp.Text
        }
        
        completions = append(completions, comp)
    }
    
    return completions
}

Type Hints for File Completion

Arguments with type file or type dir are not completed by Feather. The host should intercept these and provide filesystem-based completion:

tcl

usage for load {
    arg <script> {type file}
}

When you get an arg-placeholder with a file type, query the filesystem in your host application.

Completion Rules

Command matching: Case-sensitive prefix match, alphabetically sorted
Subcommand matching: Prefix match, preserved spec order
Flag matching: Offered when valid, both short and long forms included
Value matching: Only when flag/arg has choices defined
Hidden entries: Entries with hide are excluded from completions
Script contexts: Recursively completes inside type script arguments

Nested Script Completion

Feather can complete inside script arguments:

tcl

usage for if {
    arg <condition>
    arg <body> {type script}
}

usage for puts {arg <text>}

# Completing "pu" inside the if body:
usage complete {if {$x > 0} {pu}} 17
# => {text puts type command help {}}

See Also

usage - Full usage command reference