Skip to content

AutoCorrect2 writer

writer

Append approved AutoCorrect2 candidates to the generated include file.

GENERATED_FILE_HEADER module-attribute 

GENERATED_FILE_HEADER = "; AUTO-GENERATED BY autocorrect2-hotstring-generation\n; Add this file to AutoCorrect2 with a one-time #Include.\n; Do not edit generated entries manually.\n"

Header written when the generated include file is first created.

append_candidates 

append_candidates(
    candidates: Sequence[AutoCorrect2CandidateHotstring],
    *,
    project_dir: Path,
    relative_path: Path = GENERATED_HOTSTRINGS_RELATIVE_PATH,
) -> Path

Append accepted candidates to the project-owned AutoCorrect2 include.

Each candidate must explicitly use B0 and X, which are required by the AutoCorrect2 f()-based generated form. Trigger rendering is delegated to the hotstring model, which emits its canonical ahk_trigger source form.

Parameters:

Name Type Description Default
candidates Sequence[AutoCorrect2CandidateHotstring]

Accepted AutoCorrect2 candidates to append.

 required
project_dir Path

AutoCorrect2 project directory.

 required
relative_path Path

Generated include path relative to project_dir.

 GENERATED_HOTSTRINGS_RELATIVE_PATH

Returns:

Type Description
Path

Path of the generated include file.

Raises:

Type Description
ValueError

If a candidate is not explicitly configured with B0X behavior.
OSError

If the generated file cannot be read or written.
Source code in hotstring\autocorrect2\writer.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def append_candidates(
    candidates: Sequence[AutoCorrect2CandidateHotstring],
    *,
    project_dir: Path,
    relative_path: Path = GENERATED_HOTSTRINGS_RELATIVE_PATH,
) -> Path:
    """Append accepted candidates to the project-owned AutoCorrect2 include.

    Each candidate must explicitly use `B0` and `X`, which are required by the
    AutoCorrect2 `f()`-based generated form. Trigger rendering is delegated to
    the hotstring model, which emits its canonical `ahk_trigger` source form.

    Args:
        candidates:
            Accepted AutoCorrect2 candidates to append.
        project_dir:
            AutoCorrect2 project directory.
        relative_path:
            Generated include path relative to `project_dir`.

    Returns:
        Path of the generated include file.

    Raises:
        ValueError:
            If a candidate is not explicitly configured with `B0X` behavior.
        OSError:
            If the generated file cannot be read or written.
    """
    target_path = project_dir / relative_path
    if not candidates:
        return target_path

    for candidate in candidates:
        _validate_writable_candidate(candidate)

    prefix = ""
    if not target_path.exists() or target_path.stat().st_size == 0:
        prefix = GENERATED_FILE_HEADER
    else:
        current = read_text(target_path)
        if not current.endswith(("\n", "\r")):
            prefix = "\n"

    rendered = "\n".join(candidate.render() for candidate in candidates)
    write_text(target_path, prefix + rendered + "\n", append=True)
    return target_path

_validate_writable_candidate 

_validate_writable_candidate(
    candidate: AutoCorrect2CandidateHotstring,
) -> None

Validate the AutoCorrect2-specific B0X writing contract.

Parameters:

Name Type Description Default
candidate AutoCorrect2CandidateHotstring

Candidate that may be appended to the generated include.

 required

Raises:

Type Description
ValueError

If automatic backspacing is not explicitly disabled or execution is not explicitly enabled.
Source code in hotstring\autocorrect2\writer.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def _validate_writable_candidate(candidate: AutoCorrect2CandidateHotstring) -> None:
    """Validate the AutoCorrect2-specific `B0X` writing contract.

    Args:
        candidate:
            Candidate that may be appended to the generated include.

    Raises:
        ValueError:
            If automatic backspacing is not explicitly disabled or execution
            is not explicitly enabled.
    """
    if candidate.options.automatic_backspacing is not SettingState.DISABLED:
        raise ValueError(
            "AutoCorrect2 generated candidates must explicitly disable "
            "automatic backspacing with B0."
        )
    if candidate.options.execute is not SettingState.ENABLED:
        raise ValueError(
            "AutoCorrect2 generated candidates must explicitly enable "
            "executable content handling with X."
        )