AI Assistant Quickstart

For AI Agents

This page is a quick reference for AI agents. For a complete implementation guide, see AI Implementation Guide. Humans looking for prompts should see CCL Prompts.

Use this page as a compact orientation. For full details, follow the linked documentation pages.

Quick Facts

• CCL = Categorical Configuration Language
• Not YAML or JSON: CCL uses recursive fixed-point parsing
• All identifiers use snake_case (never hyphens)
• Core requirement: parse + build_hierarchy functions only
• Everything else is optional library convenience

Standard Terminology

Use these exact terms when discussing CCL:

Category	Terms
Core Functions	parse, build_hierarchy
Typed Access	get_string, get_int, get_bool, get_float, get_list
Processing	filter, compose
Formatting	print, canonical_format
Features	comments, empty_keys, multiline, unicode, whitespace
Experimental	experimental_dotted_keys (not standard)

Behaviors (Implementation Choices)

Behaviors are not inherently mutually exclusive. Tests use a conflicts field to specify incompatible combinations.

Behavior Group	Options	Description
Continuation Baseline	toplevel_indent_strip vs toplevel_indent_preserve	Top-level N=0 (reference) vs N=first key’s indent (simpler)
Line Endings	crlf_preserve_literal vs crlf_normalize_to_lf	CRLF handling: preserve \r chars vs normalize to LF
Boolean Parsing	boolean_lenient vs boolean_strict	Accept “yes”/“no” vs only “true”/“false”
Tab Handling	continuation_tab_to_space vs continuation_tab_preserve	Leading tabs on continuation lines: normalize 1:1 to space (OCaml reference) vs preserve verbatim
Delimiter	delimiter_first_equals vs delimiter_prefer_spaced	Split on the first = vs prefer spaced = when present
Indentation	indent_spaces vs indent_tabs	Output formatting style
List Access	list_coercion_enabled vs list_coercion_disabled	List access coercion behavior
Array Ordering	array_order_insertion vs array_order_lexicographic	Preserve insertion order vs sort lexicographically

Variants

• reference_compliant - OCaml reference implementation behavior

Key Concept: Recursive Fixed-Point Parsing

CCL is fundamentally different from YAML/JSON. Understanding this is critical:

database =
  host = localhost
  port = 5432

1. Parse → Entry("database", "\n host = localhost\n port = 5432")
2. Value contains = → parse recursively
3. Result → {database: {host: "localhost", port: "5432"}}
4. Fixed point → “localhost” and “5432” have no = → done

Full details: Parsing Algorithm

Documentation Map

For Implementation

Page	Use When
Implementing CCL	Starting a new implementation, choosing data structures
Parsing Algorithm	Understanding the core recursive algorithm
Syntax Reference	Looking up syntax rules and edge cases

For Library Features

Page	Use When
Library Features	Adding typed access, entry processing, or formatting
Library Features: Formatting	Understanding print vs canonical_format

For Testing

Page	Use When
Test Suite Guide	Setting up test filtering, understanding test format

Test Suite Repository: https://github.com/CatConfLang/ccl-test-data

Common AI Assistant Pitfalls

Use snake_case, not hyphens

• Wrong: build-hierarchy, get-string, dotted-keys
• Right: build_hierarchy, get_string, experimental_dotted_keys

Use generated tests, not source tests

• source_tests/ → For test suite maintainers
• generated_tests/ → For implementers (use this one)

Keep dotted keys out of the standard progression

• Dotted keys are experimental
• Not part of standard CCL implementation path

Do not parse CCL like YAML or JSON

• CCL uses recursive fixed-point parsing
• See Parsing Algorithm

Keep print and canonical_format distinct

• print → Structure-preserving: print(parse(x)) == x
• canonical_format → Semantic-preserving: transforms to model representation
• See Library Features: Formatting

Quick Reference Card

TERMINOLOGY:     Use snake_case everywhere
CORE:            parse, build_hierarchy (required)
OPTIONAL:        get_*, filter, compose, print, canonical_format
FEATURES:        comments, empty_keys, multiline, unicode, whitespace
EXPERIMENTAL:    experimental_dotted_keys (NOT standard)
TEST FORMAT:     Use generated_tests/ directory (flat format)
ALGORITHM:       Recursive fixed-point parsing (NOT like YAML/JSON)