"""
CSSL Built-in Functions Type Stubs
===================================

This file provides type hints and documentation for all CSSL built-in functions.
Total: 150+ functions across 15 categories.

Categories:
- Output Functions (6)
- Type Conversion (6)
- Type Checking (8)
- String Operations (22)
- Array/List Operations (17)
- Dictionary Operations (13)
- Math Functions (26)
- Date/Time Functions (7)
- File System Functions (23)
- JSON Functions (13)
- Instance Introspection (8)
- Regex Functions (4)
- Hash Functions (3)
- System/Control Functions (15)
- CSSL-Specific Functions (10)
"""

from typing import Any, List, Dict, Optional, Callable, Union, Tuple

# =============================================================================
# OUTPUT FUNCTIONS
# =============================================================================

def print(*args: Any, sep: str = " ", end: str = "") -> None:
    """Print values without newline.

    Args:
        *args: Values to print
        sep: Separator between values (default: space)
        end: String appended after last value (default: empty)

    Example:
        print("Hello", "World");  // Output: Hello World
    """
    ...

def printl(*args: Any, sep: str = " ") -> None:
    """Print values with newline (primary CSSL print function).

    Args:
        *args: Values to print
        sep: Separator between values (default: space)

    Example:
        printl("Hello World");  // Output: Hello World\\n
    """
    ...

def println(*args: Any, sep: str = " ") -> None:
    """Alias for printl. Print values with newline."""
    ...

def debug(*args: Any) -> None:
    """Print debug information with [DEBUG] prefix.

    Args:
        *args: Debug values to display

    Example:
        debug("Variable x =", x);  // Output: [DEBUG] Variable x = 42
    """
    ...

def error(*args: Any) -> None:
    """Print error message with [ERROR] prefix.

    Args:
        *args: Error message components

    Example:
        error("File not found:", path);
    """
    ...

def warn(*args: Any) -> None:
    """Print warning message with [WARN] prefix.

    Args:
        *args: Warning message components
    """
    ...

# =============================================================================
# TYPE CONVERSION FUNCTIONS
# =============================================================================

def int(value: Any) -> int:
    """Convert value to integer.

    Args:
        value: Value to convert (string, float, bool)

    Returns:
        Integer representation

    Example:
        int("42");     // 42
        int(3.14);     // 3
        int(true);     // 1
    """
    ...

def float(value: Any) -> float:
    """Convert value to floating-point number.

    Args:
        value: Value to convert

    Returns:
        Float representation

    Example:
        float("3.14");  // 3.14
        float(42);      // 42.0
    """
    ...

def str(value: Any) -> str:
    """Convert value to string.

    Args:
        value: Value to convert

    Returns:
        String representation

    Example:
        str(42);       // "42"
        str(true);     // "True"
    """
    ...

def bool(value: Any) -> bool:
    """Convert value to boolean.

    Args:
        value: Value to convert

    Returns:
        Boolean representation

    Example:
        bool(1);       // true
        bool("");      // false
        bool("text");  // true
    """
    ...

def list(value: Any = None) -> List[Any]:
    """Convert value to list or create empty list.

    Args:
        value: Optional value to convert (string, iterable)

    Returns:
        List representation

    Example:
        list("abc");     // ["a", "b", "c"]
        list();          // []
    """
    ...

def dict(value: Any = None) -> Dict[str, Any]:
    """Convert value to dictionary or create empty dict.

    Args:
        value: Optional value to convert

    Returns:
        Dictionary representation
    """
    ...

# =============================================================================
# TYPE CHECKING FUNCTIONS
# =============================================================================

def typeof(value: Any) -> str:
    """Get type name of value.

    Args:
        value: Value to check

    Returns:
        Type name as string

    Example:
        typeof(42);        // "int"
        typeof("hello");   // "str"
        typeof([1,2,3]);   // "list"
    """
    ...

def isinstance(value: Any, type_name: str) -> bool:
    """Check if value is instance of type.

    Args:
        value: Value to check
        type_name: Type name string

    Returns:
        True if value is instance of type
    """
    ...

def isint(value: Any) -> bool:
    """Check if value is an integer."""
    ...

def isfloat(value: Any) -> bool:
    """Check if value is a float."""
    ...

def isstr(value: Any) -> bool:
    """Check if value is a string."""
    ...

def isbool(value: Any) -> bool:
    """Check if value is a boolean."""
    ...

def islist(value: Any) -> bool:
    """Check if value is a list/array."""
    ...

def isdict(value: Any) -> bool:
    """Check if value is a dictionary."""
    ...

def isnull(value: Any) -> bool:
    """Check if value is null/None."""
    ...

# =============================================================================
# STRING OPERATIONS
# =============================================================================

def len(value: Union[str, List, Dict]) -> int:
    """Get length of string, list, or dictionary.

    Args:
        value: String, list, or dictionary

    Returns:
        Number of characters/elements/keys

    Example:
        len("hello");     // 5
        len([1,2,3]);     // 3
    """
    ...

def upper(s: str) -> str:
    """Convert string to uppercase.

    Example:
        upper("hello");  // "HELLO"
    """
    ...

def lower(s: str) -> str:
    """Convert string to lowercase.

    Example:
        lower("HELLO");  // "hello"
    """
    ...

def trim(s: str) -> str:
    """Remove whitespace from both ends of string.

    Example:
        trim("  hello  ");  // "hello"
    """
    ...

def ltrim(s: str) -> str:
    """Remove whitespace from left side of string."""
    ...

def rtrim(s: str) -> str:
    """Remove whitespace from right side of string."""
    ...

def split(s: str, delimiter: str = " ") -> List[str]:
    """Split string into list by delimiter.

    Args:
        s: String to split
        delimiter: Split delimiter (default: space)

    Returns:
        List of substrings

    Example:
        split("a,b,c", ",");  // ["a", "b", "c"]
    """
    ...

def join(arr: List[str], delimiter: str = "") -> str:
    """Join list elements into string.

    Args:
        arr: List of strings
        delimiter: Join delimiter

    Returns:
        Joined string

    Example:
        join(["a", "b", "c"], "-");  // "a-b-c"
    """
    ...

def replace(s: str, old: str, new: str) -> str:
    """Replace all occurrences of substring.

    Args:
        s: Original string
        old: Substring to replace
        new: Replacement string

    Example:
        replace("hello", "l", "x");  // "hexxo"
    """
    ...

def substr(s: str, start: int, length: int = None) -> str:
    """Extract substring.

    Args:
        s: Original string
        start: Start index (0-based)
        length: Number of characters (optional)

    Example:
        substr("hello", 1, 3);  // "ell"
    """
    ...

def contains(s: str, substring: str) -> bool:
    """Check if string contains substring.

    Example:
        contains("hello", "ell");  // true
    """
    ...

def startswith(s: str, prefix: str) -> bool:
    """Check if string starts with prefix.

    Example:
        startswith("hello", "he");  // true
    """
    ...

def endswith(s: str, suffix: str) -> bool:
    """Check if string ends with suffix.

    Example:
        endswith("hello", "lo");  // true
    """
    ...

def format(template: str, *args: Any) -> str:
    """Format string with placeholders.

    Args:
        template: String with {} placeholders
        *args: Values to insert

    Example:
        format("Hello, {}!", "World");  // "Hello, World!"
    """
    ...

def concat(*strings: str) -> str:
    """Concatenate multiple strings.

    Example:
        concat("a", "b", "c");  // "abc"
    """
    ...

def repeat(s: str, count: int) -> str:
    """Repeat string n times.

    Example:
        repeat("ab", 3);  // "ababab"
    """
    ...

def reverse(s: str) -> str:
    """Reverse string.

    Example:
        reverse("hello");  // "olleh"
    """
    ...

def indexof(s: str, substring: str, start: int = 0) -> int:
    """Find first occurrence of substring.

    Args:
        s: String to search in
        substring: Substring to find
        start: Start position (default: 0)

    Returns:
        Index of first occurrence, -1 if not found

    Example:
        indexof("hello", "l");  // 2
    """
    ...

def lastindexof(s: str, substring: str) -> int:
    """Find last occurrence of substring.

    Returns:
        Index of last occurrence, -1 if not found
    """
    ...

def padleft(s: str, length: int, char: str = " ") -> str:
    """Pad string on left to specified length.

    Example:
        padleft("42", 5, "0");  // "00042"
    """
    ...

def padright(s: str, length: int, char: str = " ") -> str:
    """Pad string on right to specified length.

    Example:
        padright("42", 5, "0");  // "42000"
    """
    ...

def capitalize(s: str) -> str:
    """Capitalize first character.

    Example:
        capitalize("hello");  // "Hello"
    """
    ...

def title(s: str) -> str:
    """Capitalize first character of each word.

    Example:
        title("hello world");  // "Hello World"
    """
    ...

# =============================================================================
# ARRAY/LIST OPERATIONS
# =============================================================================

def push(arr: List[Any], value: Any) -> List[Any]:
    """Add element to end of array.

    Args:
        arr: Target array
        value: Value to add

    Returns:
        Modified array

    Example:
        push([1, 2], 3);  // [1, 2, 3]
    """
    ...

def pop(arr: List[Any]) -> Any:
    """Remove and return last element.

    Returns:
        Removed element

    Example:
        pop([1, 2, 3]);  // 3, array becomes [1, 2]
    """
    ...

def shift(arr: List[Any]) -> Any:
    """Remove and return first element.

    Returns:
        Removed element
    """
    ...

def unshift(arr: List[Any], value: Any) -> List[Any]:
    """Add element to beginning of array.

    Returns:
        Modified array
    """
    ...

def slice(arr: List[Any], start: int, end: int = None) -> List[Any]:
    """Extract portion of array.

    Args:
        arr: Source array
        start: Start index
        end: End index (exclusive, optional)

    Returns:
        New array with extracted elements

    Example:
        slice([1, 2, 3, 4], 1, 3);  // [2, 3]
    """
    ...

def sort(arr: List[Any]) -> List[Any]:
    """Sort array in ascending order.

    Returns:
        Sorted array
    """
    ...

def rsort(arr: List[Any]) -> List[Any]:
    """Sort array in descending order.

    Returns:
        Reverse sorted array
    """
    ...

def unique(arr: List[Any]) -> List[Any]:
    """Remove duplicate elements.

    Returns:
        Array with unique elements only

    Example:
        unique([1, 2, 2, 3]);  // [1, 2, 3]
    """
    ...

def flatten(arr: List[Any]) -> List[Any]:
    """Flatten nested arrays.

    Example:
        flatten([[1, 2], [3, 4]]);  // [1, 2, 3, 4]
    """
    ...

def filter(arr: List[Any], predicate: Callable[[Any], bool]) -> List[Any]:
    """Filter array by predicate function.

    Args:
        arr: Source array
        predicate: Function returning true for elements to keep

    Returns:
        Filtered array
    """
    ...

def map(arr: List[Any], func: Callable[[Any], Any]) -> List[Any]:
    """Apply function to each element.

    Args:
        arr: Source array
        func: Transformation function

    Returns:
        Transformed array
    """
    ...

def reduce(arr: List[Any], func: Callable[[Any, Any], Any], initial: Any = None) -> Any:
    """Reduce array to single value.

    Args:
        arr: Source array
        func: Reducer function (accumulator, current) -> result
        initial: Initial accumulator value

    Returns:
        Reduced value
    """
    ...

def find(arr: List[Any], predicate: Callable[[Any], bool]) -> Optional[Any]:
    """Find first element matching predicate.

    Returns:
        First matching element or null
    """
    ...

def findindex(arr: List[Any], predicate: Callable[[Any], bool]) -> int:
    """Find index of first matching element.

    Returns:
        Index or -1 if not found
    """
    ...

def range(start_or_stop: int, stop: int = None, step: int = 1) -> List[int]:
    """Generate range of integers.

    Args:
        start_or_stop: Start value (or stop if only arg)
        stop: Stop value (exclusive)
        step: Step increment

    Returns:
        List of integers

    Example:
        range(5);           // [0, 1, 2, 3, 4]
        range(1, 5);        // [1, 2, 3, 4]
        range(0, 10, 2);    // [0, 2, 4, 6, 8]
    """
    ...

# =============================================================================
# DICTIONARY OPERATIONS
# =============================================================================

def keys(d: Dict[str, Any]) -> List[str]:
    """Get all dictionary keys.

    Returns:
        List of keys
    """
    ...

def values(d: Dict[str, Any]) -> List[Any]:
    """Get all dictionary values.

    Returns:
        List of values
    """
    ...

def items(d: Dict[str, Any]) -> List[Tuple[str, Any]]:
    """Get all key-value pairs.

    Returns:
        List of (key, value) tuples
    """
    ...

def haskey(d: Dict[str, Any], key: str) -> bool:
    """Check if dictionary has key.

    Example:
        haskey({"a": 1}, "a");  // true
    """
    ...

def getkey(d: Dict[str, Any], key: str, default: Any = None) -> Any:
    """Get value by key with optional default.

    Args:
        d: Dictionary
        key: Key to look up
        default: Default value if key not found

    Returns:
        Value or default
    """
    ...

def setkey(d: Dict[str, Any], key: str, value: Any) -> Dict[str, Any]:
    """Set key-value pair in dictionary.

    Returns:
        Modified dictionary
    """
    ...

def delkey(d: Dict[str, Any], key: str) -> Dict[str, Any]:
    """Delete key from dictionary.

    Returns:
        Modified dictionary
    """
    ...

def merge(*dicts: Dict[str, Any]) -> Dict[str, Any]:
    """Merge multiple dictionaries.

    Returns:
        Merged dictionary (later values override earlier)
    """
    ...

# =============================================================================
# MATH FUNCTIONS
# =============================================================================

def abs(x: Union[int, float]) -> Union[int, float]:
    """Absolute value."""
    ...

def min(*values: Union[int, float]) -> Union[int, float]:
    """Minimum value."""
    ...

def max(*values: Union[int, float]) -> Union[int, float]:
    """Maximum value."""
    ...

def sum(arr: List[Union[int, float]]) -> Union[int, float]:
    """Sum of array elements."""
    ...

def avg(arr: List[Union[int, float]]) -> float:
    """Average of array elements."""
    ...

def round(x: float, decimals: int = 0) -> float:
    """Round to specified decimal places."""
    ...

def floor(x: float) -> int:
    """Round down to nearest integer."""
    ...

def ceil(x: float) -> int:
    """Round up to nearest integer."""
    ...

def pow(base: float, exponent: float) -> float:
    """Raise base to power."""
    ...

def sqrt(x: float) -> float:
    """Square root."""
    ...

def random() -> float:
    """Random float between 0 and 1."""
    ...

def randint(min_val: int, max_val: int) -> int:
    """Random integer in range [min, max]."""
    ...

def sin(x: float) -> float:
    """Sine (radians)."""
    ...

def cos(x: float) -> float:
    """Cosine (radians)."""
    ...

def tan(x: float) -> float:
    """Tangent (radians)."""
    ...

def asin(x: float) -> float:
    """Arc sine (returns radians)."""
    ...

def acos(x: float) -> float:
    """Arc cosine (returns radians)."""
    ...

def atan(x: float) -> float:
    """Arc tangent (returns radians)."""
    ...

def atan2(y: float, x: float) -> float:
    """Two-argument arc tangent."""
    ...

def log(x: float, base: float = None) -> float:
    """Natural logarithm (or log with specified base)."""
    ...

def log10(x: float) -> float:
    """Base-10 logarithm."""
    ...

def exp(x: float) -> float:
    """Exponential function (e^x)."""
    ...

def pi() -> float:
    """Mathematical constant pi (3.14159...)."""
    ...

def e() -> float:
    """Mathematical constant e (2.71828...)."""
    ...

def radians(degrees: float) -> float:
    """Convert degrees to radians."""
    ...

def degrees(radians: float) -> float:
    """Convert radians to degrees."""
    ...

# =============================================================================
# DATE/TIME FUNCTIONS
# =============================================================================

def now() -> float:
    """Current timestamp as float (seconds since epoch)."""
    ...

def timestamp() -> int:
    """Current timestamp as integer."""
    ...

def sleep(seconds: float) -> None:
    """Pause execution for specified seconds.

    Example:
        sleep(1.5);  // Wait 1.5 seconds
    """
    ...

def date(format: str = "%Y-%m-%d") -> str:
    """Current date as formatted string.

    Args:
        format: strftime format string

    Example:
        date();              // "2025-12-30"
        date("%d/%m/%Y");    // "30/12/2025"
    """
    ...

def time(format: str = "%H:%M:%S") -> str:
    """Current time as formatted string.

    Example:
        time();              // "14:30:45"
    """
    ...

def datetime(format: str = "%Y-%m-%d %H:%M:%S") -> str:
    """Current date and time as formatted string."""
    ...

def strftime(format: str, timestamp: float = None) -> str:
    """Format timestamp as string.

    Args:
        format: strftime format string
        timestamp: Unix timestamp (default: now)
    """
    ...

# =============================================================================
# FILE SYSTEM FUNCTIONS
# =============================================================================

def read(path: str, encoding: str = "utf-8") -> str:
    """Read entire file content.

    Args:
        path: File path
        encoding: Character encoding (default: utf-8)

    Returns:
        File content as string

    Example:
        string content = read("/path/to/file.txt");
    """
    ...

def readline(line: int, path: str) -> str:
    """Read specific line from file (1-indexed).

    Args:
        line: Line number (1-based)
        path: File path

    Returns:
        Line content

    Example:
        string line5 = readline(5, "file.txt");
    """
    ...

def write(path: str, content: str) -> int:
    """Write content to file (overwrites).

    Args:
        path: File path
        content: Content to write

    Returns:
        Number of characters written
    """
    ...

def writeline(line: int, content: str, path: str) -> bool:
    """Write/replace specific line in file.

    Args:
        line: Line number (1-based)
        content: New line content
        path: File path

    Returns:
        Success status
    """
    ...

def appendfile(path: str, content: str) -> int:
    """Append content to file.

    Returns:
        Number of characters written
    """
    ...

def readlines(path: str) -> List[str]:
    """Read all lines from file.

    Returns:
        List of lines
    """
    ...

def pathexists(path: str) -> bool:
    """Check if path exists (file or directory)."""
    ...

def isfile(path: str) -> bool:
    """Check if path is a file."""
    ...

def isdir(path: str) -> bool:
    """Check if path is a directory."""
    ...

def listdir(path: str) -> List[str]:
    """List directory contents.

    Returns:
        List of file/folder names
    """
    ...

def makedirs(path: str) -> bool:
    """Create directory and parent directories.

    Returns:
        Success status
    """
    ...

def removefile(path: str) -> bool:
    """Delete a file."""
    ...

def removedir(path: str) -> bool:
    """Delete an empty directory."""
    ...

def copyfile(src: str, dst: str) -> bool:
    """Copy file from source to destination."""
    ...

def movefile(src: str, dst: str) -> bool:
    """Move/rename file."""
    ...

def filesize(path: str) -> int:
    """Get file size in bytes."""
    ...

def basename(path: str) -> str:
    """Get filename from path.

    Example:
        basename("/path/to/file.txt");  // "file.txt"
    """
    ...

def dirname(path: str) -> str:
    """Get directory from path.

    Example:
        dirname("/path/to/file.txt");  // "/path/to"
    """
    ...

def joinpath(*parts: str) -> str:
    """Join path components.

    Example:
        joinpath("/path", "to", "file.txt");  // "/path/to/file.txt"
    """
    ...

def abspath(path: str) -> str:
    """Get absolute path."""
    ...

# =============================================================================
# JSON FUNCTIONS (json:: namespace)
# =============================================================================

def json_read(path: str) -> Any:
    """Read and parse JSON file.

    Usage: json::read("/path/to/file.json")

    Returns:
        Parsed JSON data
    """
    ...

def json_write(path: str, data: Any, indent: int = 2) -> bool:
    """Write data to JSON file.

    Usage: json::write("/path/to/file.json", data)

    Returns:
        Success status
    """
    ...

def json_parse(s: str) -> Any:
    """Parse JSON string.

    Usage: json::parse('{"key": "value"}')

    Returns:
        Parsed object/array
    """
    ...

def json_stringify(data: Any) -> str:
    """Convert data to JSON string.

    Usage: json::stringify(data)
    """
    ...

def json_pretty(data: Any, indent: int = 2) -> str:
    """Pretty print JSON with indentation.

    Usage: json::pretty(data)
    """
    ...

def json_get(data: Any, path: str, default: Any = None) -> Any:
    """Get value by dot-path.

    Usage: json::get(data, "user.name")

    Args:
        data: JSON object
        path: Dot-separated path (e.g., "user.profile.age")
        default: Default value if path not found
    """
    ...

def json_set(data: Any, path: str, value: Any) -> Any:
    """Set value by dot-path.

    Usage: json::set(data, "user.name", "John")

    Returns:
        Modified data
    """
    ...

def json_has(data: Any, path: str) -> bool:
    """Check if path exists.

    Usage: json::has(data, "user.email")
    """
    ...

def json_keys(data: Dict) -> List[str]:
    """Get all keys from JSON object.

    Usage: json::keys(data)
    """
    ...

def json_values(data: Dict) -> List[Any]:
    """Get all values from JSON object.

    Usage: json::values(data)
    """
    ...

def json_merge(*dicts: Dict) -> Dict:
    """Deep merge multiple JSON objects.

    Usage: json::merge(obj1, obj2, obj3)
    """
    ...

# =============================================================================
# INSTANCE INTROSPECTION (instance:: namespace)
# =============================================================================

def instance_getMethods(obj: Any) -> List[str]:
    """Get all method names from object/module.

    Usage: instance::getMethods(@module)

    Returns:
        List of callable method names
    """
    ...

def instance_getClasses(obj: Any) -> List[str]:
    """Get all class names from module.

    Usage: instance::getClasses(@module)
    """
    ...

def instance_getVars(obj: Any) -> List[str]:
    """Get all variable/attribute names.

    Usage: instance::getVars(@module)
    """
    ...

def instance_getAll(obj: Any) -> Dict[str, List[str]]:
    """Get all attributes categorized.

    Usage: instance::getAll(@module)

    Returns:
        Dict with 'methods', 'classes', 'vars' keys
    """
    ...

def instance_call(obj: Any, method_name: str, *args: Any, **kwargs: Any) -> Any:
    """Dynamically call method on object.

    Usage: instance::call(@module, "methodName", arg1, arg2)
    """
    ...

def instance_has(obj: Any, name: str) -> bool:
    """Check if object has attribute.

    Usage: instance::has(@module, "methodName")
    """
    ...

def instance_type(obj: Any) -> str:
    """Get type name of object.

    Usage: instance::type(@module)
    """
    ...

def isavailable(name_or_obj: Any) -> bool:
    """Check if shared instance exists.

    Usage:
        isavailable("MyInstance")    // Check by name
        isavailable($MyInstance)     // Check if not null
        instance::exists("Name")     // Alias
    """
    ...

# =============================================================================
# REGEX FUNCTIONS
# =============================================================================

def match(pattern: str, string: str) -> Optional[Dict]:
    """Match regex at start of string.

    Returns:
        Dict with 'match', 'groups', 'start', 'end' or null
    """
    ...

def search(pattern: str, string: str) -> Optional[Dict]:
    """Search for regex anywhere in string.

    Returns:
        Dict with match info or null
    """
    ...

def findall(pattern: str, string: str) -> List[str]:
    """Find all regex matches.

    Returns:
        List of all matches
    """
    ...

def sub(pattern: str, replacement: str, string: str) -> str:
    """Replace all regex matches.

    Example:
        sub("\\d+", "X", "a1b2c3");  // "aXbXcX"
    """
    ...

# =============================================================================
# HASH FUNCTIONS
# =============================================================================

def md5(s: str) -> str:
    """Calculate MD5 hash.

    Returns:
        Hexadecimal hash string
    """
    ...

def sha1(s: str) -> str:
    """Calculate SHA1 hash."""
    ...

def sha256(s: str) -> str:
    """Calculate SHA256 hash."""
    ...

# =============================================================================
# SYSTEM/CONTROL FUNCTIONS
# =============================================================================

def exit(code: int = 0) -> None:
    """Exit CSSL execution.

    Args:
        code: Exit code (default: 0)
    """
    ...

def input(prompt: str = "") -> str:
    """Read user input from console.

    Args:
        prompt: Optional prompt message

    Returns:
        User input string
    """
    ...

def env(name: str) -> Optional[str]:
    """Get environment variable.

    Args:
        name: Variable name

    Returns:
        Variable value or null
    """
    ...

def setenv(name: str, value: str) -> None:
    """Set environment variable."""
    ...

def clear() -> None:
    """Clear console screen."""
    ...

def copy(obj: Any) -> Any:
    """Create shallow copy of object."""
    ...

def deepcopy(obj: Any) -> Any:
    """Create deep copy of object."""
    ...

def pyimport(module_name: str) -> Any:
    """Import Python module dynamically.

    Example:
        @os = pyimport("os");
        @os.getcwd();
    """
    ...

def include(path: str) -> Any:
    """Include/import CSSL module.

    Args:
        path: Module path (e.g., "mymodule.cssl-mod")

    Returns:
        Imported module object
    """
    ...

def payload(path: str) -> Any:
    """Load CSSL payload file.

    Args:
        path: Payload file path (e.g., "data.cssl-pl")
    """
    ...

# =============================================================================
# CSSL-SPECIFIC FUNCTIONS
# =============================================================================

def OpenFind(type_or_combo: Any, index: int = 0) -> Optional[Any]:
    """Find open parameter by type or combo space.

    Usage:
        string name = OpenFind<string>(0);
        value = OpenFind(&comboSpace);
    """
    ...

def datastruct(element_type: str = "dynamic") -> Any:
    """Create datastruct container.

    Example:
        datastruct<string> data;
    """
    ...

def shuffled(element_type: str = "dynamic") -> Any:
    """Create shuffled container for unorganized fast storage."""
    ...

def iterator(element_type: str = "int", size: int = 16) -> Any:
    """Create iterator with programmable tasks."""
    ...

def combo(element_type: str = "dynamic") -> Any:
    """Create combo filter/search space."""
    ...

def share(name: str, obj: Any) -> None:
    """Share Python object with CSSL.

    Args:
        name: Instance name for CSSL access
        obj: Python object to share

    Example (Python):
        CSSL.share("mydata", data_object)

    Example (CSSL):
        $mydata.property;
    """
    ...

def delete(name: str) -> bool:
    """Delete shared object.

    Args:
        name: Shared object name

    Returns:
        True if deleted, False if not found
    """
    ...

# =============================================================================
# PLATFORM DETECTION
# =============================================================================

def isLinux() -> bool:
    """Check if running on Linux."""
    ...

def isWindows() -> bool:
    """Check if running on Windows."""
    ...

def isMac() -> bool:
    """Check if running on macOS."""
    ...
