capturegraph.procedures.toolkits.control_flow.user_select

User Select Procedure Toolkit

This module provides high-level utilities for user-driven procedural selection, combining UserInputSelectString with conditional execution branching. These functions streamline the common pattern of presenting users with multiple procedure options and executing the selected one.

Key differences from switch_case_strings: - Specifically designed for interactive user selection workflows - Automatically handles UserInputSelectString setup and option mapping - Uses first dictionary option as default (no explicit default parameter) - Prevents code duplication by encapsulating the UserInputSelectString + switch pattern

This abstraction eliminates boilerplate code and ensures consistent handling of user-driven procedural choices across the application.

user_select_procedure(label, options)

Creates a procedure that prompts the user to select from multiple procedure options.

This function combines UserInputSelectString with switch_case_strings to provide a streamlined way to present users with procedural choices and execute the selected option. It eliminates the boilerplate of manually setting up user input and conditional branching.

Parameters:

Name	Type	Description	Default
label	str	The text displayed to the user when making the selection	required
options	dict[str, Procedure[R]]	Dictionary mapping option names (strings) to their corresponding procedures. All procedures must return the same type.	required

Returns:

Type	Description
Procedure[R]	A procedure that will execute the user's selected procedure and return its result

Example

return user_select_procedure(
    label="Enable notifications?",
    options={
        "No": DoNothing(),
        "Yes, use time-of-day scheduling": configure_time_of_day_notification(),
        "Yes, use fixed interval scheduling": configure_interval_notifications()
    }
)

Source code in capturegraph-lib/capturegraph/procedures/toolkits/control_flow/user_select.py

def user_select_procedure[R: PType](
    label: str,
    options: dict[str, Procedure[R]],
) -> Procedure[R]:
    """
    Creates a procedure that prompts the user to select from multiple procedure options.

    This function combines UserInputSelectString with switch_case_strings to provide
    a streamlined way to present users with procedural choices and execute the
    selected option. It eliminates the boilerplate of manually setting up user input
    and conditional branching.

    Args:
        label: The text displayed to the user when making the selection
        options: Dictionary mapping option names (strings) to their corresponding procedures.
                All procedures must return the same type.

    Returns:
        A procedure that will execute the user's selected procedure and return its result

    Example:
        ```python
        return user_select_procedure(
            label="Enable notifications?",
            options={
                "No": DoNothing(),
                "Yes, use time-of-day scheduling": configure_time_of_day_notification(),
                "Yes, use fixed interval scheduling": configure_interval_notifications()
            }
        )
        ```
    """
    items = list((key, value) for key, value in options.items())

    selection = UserInputSelectString(
        label=label,
        options=[key for key, _ in items],
    )

    return switch_case_strings(
        case=selection,
        cases={key: procedure for key, procedure in items[1:]},
        default=items[0][1],
    )

cached_user_select_procedure(label, options, file, skip_if_exists=False)

Creates a user selection procedure with persistent caching of the user's choice.

Similar to user_select_procedure, but caches the user's selection to a file for persistence across sessions. This is useful for user preferences or settings that should be remembered across session captures.

Parameters:

Name	Type	Description	Default
label	str	The text displayed to the user when making the selection	required
options	dict[str, Procedure[R]]	Dictionary mapping option names to procedures. All procedures must return the same type.	required
file	Procedure[PFile]	The file procedure where the selection will be cached	required
skip_if_exists	bool	If True, skips user input if the cached file already exists	False

Returns:

Type	Description
Procedure[R]	A procedure that will execute the user's selected (or cached) procedure and return its result

Example

return cached_user_select_procedure(
    label="Enable notifications?",
    options={
        "No": DoNothing(),
        "Yes, use time-of-day scheduling": configure_time_of_day_notification(),
        "Yes, use fixed interval scheduling": configure_interval_notifications()
    },
    file=settings_directory.new_file(".enabled"),
    skip_if_exists=True
)

Source code in capturegraph-lib/capturegraph/procedures/toolkits/control_flow/user_select.py

def cached_user_select_procedure[R: PType](
    label: str,
    options: dict[str, Procedure[R]],
    file: Procedure[PFile],
    skip_if_exists: bool = False,
) -> Procedure[R]:
    """
    Creates a user selection procedure with persistent caching of the user's choice.

    Similar to user_select_procedure, but caches the user's selection to a file
    for persistence across sessions. This is useful for user preferences or
    settings that should be remembered across session captures.

    Args:
        label: The text displayed to the user when making the selection
        options: Dictionary mapping option names to procedures. All procedures must return the same type.
        file: The file procedure where the selection will be cached
        skip_if_exists: If True, skips user input if the cached file already exists

    Returns:
        A procedure that will execute the user's selected (or cached) procedure and return its result

    Example:
        ```python
        return cached_user_select_procedure(
            label="Enable notifications?",
            options={
                "No": DoNothing(),
                "Yes, use time-of-day scheduling": configure_time_of_day_notification(),
                "Yes, use fixed interval scheduling": configure_interval_notifications()
            },
            file=settings_directory.new_file(".enabled"),
            skip_if_exists=True
        )
        ```
    """
    items = list((key, value) for key, value in options.items())

    selection = file.cache(
        UserInputSelectString(
            label=label,
            options=[key for key, _ in items],
        ),
        skip_if_exists=skip_if_exists,
    ).set_label("Cached User Selection")

    return switch_case_strings(
        case=selection,
        cases={key: procedure for key, procedure in items[1:]},
        default=items[0][1],
    )