borse 0.1.0__py3-none-any.whl

borse/progress.py

@@ -0,0 +1,167 @@
+"""Progress tracking for Borse."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+
+
+@dataclass
+class DailyProgress:
+    """Progress for a single day.
+
+    Attributes:
+        morse_words: Number of Morse code words answered.
+        braille_words: Number of Braille words answered.
+        semaphore_words: Number of semaphore words answered.
+        a1z26_words: Number of A1Z26 words answered.
+    """
+
+    morse_words: int = 0
+    braille_words: int = 0
+    semaphore_words: int = 0
+    a1z26_words: int = 0
+
+    @property
+    def total_words(self) -> int:
+        """Get total words answered today.
+
+        Returns:
+            Sum of all words across all modes.
+        """
+        return (
+            self.morse_words
+            + self.braille_words
+            + self.semaphore_words
+            + self.a1z26_words
+        )
+
+    def to_dict(self) -> dict[str, int]:
+        """Convert to dictionary.
+
+        Returns:
+            Dictionary representation.
+        """
+        return {
+            "morse_words": self.morse_words,
+            "braille_words": self.braille_words,
+            "semaphore_words": self.semaphore_words,
+            "a1z26_words": self.a1z26_words,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, int]) -> DailyProgress:
+        """Create from dictionary.
+
+        Args:
+            data: Dictionary with progress values.
+
+        Returns:
+            DailyProgress instance.
+        """
+        return cls(
+            morse_words=data.get("morse_words", 0),
+            braille_words=data.get("braille_words", 0),
+            semaphore_words=data.get("semaphore_words", 0),
+            a1z26_words=data.get("a1z26_words", 0),
+        )
+
+
+@dataclass
+class Progress:
+    """Overall progress tracking.
+
+    Attributes:
+        daily: Dictionary mapping date strings to daily progress.
+    """
+
+    daily: dict[str, DailyProgress] = field(default_factory=dict)
+
+    def get_today(self) -> DailyProgress:
+        """Get today's progress.
+
+        Returns:
+            DailyProgress for today, creating if needed.
+        """
+        today = date.today().isoformat()
+        if today not in self.daily:
+            self.daily[today] = DailyProgress()
+        return self.daily[today]
+
+    def add_word(self, mode: str) -> None:
+        """Add a completed word for today.
+
+        Args:
+            mode: The game mode ('morse', 'braille', 'semaphore', or 'a1z26').
+        """
+        today = self.get_today()
+        if mode == "morse":
+            today.morse_words += 1
+        elif mode == "braille":
+            today.braille_words += 1
+        elif mode == "semaphore":
+            today.semaphore_words += 1
+        elif mode == "a1z26":
+            today.a1z26_words += 1
+
+    def to_dict(self) -> dict[str, dict[str, dict[str, int]]]:
+        """Convert to dictionary.
+
+        Returns:
+            Dictionary representation.
+        """
+        return {"daily": {k: v.to_dict() for k, v in self.daily.items()}}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, dict[str, dict[str, int]]]) -> Progress:
+        """Create from dictionary.
+
+        Args:
+            data: Dictionary with progress values.
+
+        Returns:
+            Progress instance.
+        """
+        daily_data = data.get("daily", {})
+        daily = {k: DailyProgress.from_dict(v) for k, v in daily_data.items()}
+        return cls(daily=daily)
+
+
+def load_progress(progress_path: Path | str) -> Progress:
+    """Load progress from file.
+
+    Args:
+        progress_path: Path to progress file.
+
+    Returns:
+        Progress instance with loaded or default values.
+    """
+    path = Path(progress_path)
+
+    if not path.exists():
+        return Progress()
+
+    try:
+        with open(path) as f:
+            data = json.load(f)
+        return Progress.from_dict(data)
+    except (json.JSONDecodeError, OSError):
+        return Progress()
+
+
+def save_progress(progress: Progress, progress_path: Path | str) -> None:
+    """Save progress to file.
+
+    Args:
+        progress: Progress instance to save.
+        progress_path: Path to progress file.
+    """
+    path = Path(progress_path)
+
+    # Ensure directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(path, "w") as f:
+        json.dump(progress.to_dict(), f, indent=2)

borse/semaphore.py

@@ -0,0 +1,154 @@
+"""Flag semaphore encoding module with ASCII art display."""
+
+# Flag positions (like clock positions):
+# 0 = down (6 o'clock)
+# 1 = down-left (about 7:30)
+# 2 = out-left (9 o'clock)
+# 3 = up-left (about 10:30)
+# 4 = up (12 o'clock)
+# 5 = up-right (about 1:30)
+# 6 = out-right (3 o'clock)
+# 7 = down-right (about 4:30)
+
+# Semaphore positions for each letter: (left_flag, right_flag)
+# Positions are numbered 0-7 going clockwise from down
+SEMAPHORE_POSITIONS: dict[str, tuple[int, int]] = {
+    "A": (0, 1),
+    "B": (0, 2),
+    "C": (0, 3),
+    "D": (0, 4),
+    "E": (0, 5),
+    "F": (0, 6),
+    "G": (0, 7),
+    "H": (1, 2),
+    "I": (1, 3),
+    "J": (4, 6),
+    "K": (1, 4),
+    "L": (1, 5),
+    "M": (1, 6),
+    "N": (1, 7),
+    "O": (2, 3),
+    "P": (2, 4),
+    "Q": (2, 5),
+    "R": (2, 6),
+    "S": (2, 7),
+    "T": (3, 4),
+    "U": (3, 5),
+    "V": (4, 7),
+    "W": (5, 6),
+    "X": (5, 7),
+    "Y": (3, 6),
+    "Z": (6, 7),
+}
+
+# Grid is 7x5 (wider for horizontal arms):
+#   0  1  2  3  4  5  6
+#   7  8  9 10 11 12 13
+#  14 15 16 17 18 19 20
+#  21 22 23 24 25 26 27
+#  28 29 30 31 32 33 34
+# Position 17 is center (the person)
+
+# Grid positions for each flag position
+# Most positions have 2 cells (inner, outer)
+# Horizontal positions (2, 6) have 3 cells for longer arms
+POSITION_TO_GRID: dict[int, tuple[int, ...]] = {
+    0: (24, 31),  # down
+    1: (23, 29),  # down-left
+    2: (16, 15, 14),  # out-left (3 hyphens)
+    3: (9, 1),  # up-left
+    4: (10, 3),  # up
+    5: (11, 5),  # up-right
+    6: (18, 19, 20),  # out-right (3 hyphens)
+    7: (25, 33),  # down-right
+}
+
+# Characters to show for each flag position
+# Based on the direction from center
+POSITION_CHARS: dict[int, str] = {
+    0: "|",  # down
+    1: "/",  # down-left
+    2: "-",  # out-left
+    3: "\\",  # up-left
+    4: "|",  # up
+    5: "/",  # up-right
+    6: "-",  # out-right
+    7: "\\",  # down-right
+}
+
+
+def encode_char(char: str) -> list[str]:
+    """Encode a single character to semaphore ASCII art.
+
+    Args:
+        char: A single character to encode.
+
+    Returns:
+        A list of 5 strings representing the 5 rows of the semaphore display.
+    """
+    upper = char.upper()
+    if upper not in SEMAPHORE_POSITIONS:
+        return ["       ", "       ", "       ", "       ", "       "]
+
+    left_pos, right_pos = SEMAPHORE_POSITIONS[upper]
+
+    # Build the 7x5 grid
+    grid = [" "] * 35
+    grid[17] = "O"  # Person in center
+
+    # Place the flags (variable length based on position)
+    left_cells = POSITION_TO_GRID[left_pos]
+    right_cells = POSITION_TO_GRID[right_pos]
+
+    left_char = POSITION_CHARS[left_pos]
+    right_char = POSITION_CHARS[right_pos]
+
+    for cell in left_cells:
+        grid[cell] = left_char
+    for cell in right_cells:
+        grid[cell] = right_char
+
+    # Convert to 5 rows (7 columns each)
+    rows = [
+        "".join(grid[0:7]),
+        "".join(grid[7:14]),
+        "".join(grid[14:21]),
+        "".join(grid[21:28]),
+        "".join(grid[28:35]),
+    ]
+
+    return rows
+
+
+def encode_word(word: str) -> list[list[str]]:
+    """Encode a word to semaphore ASCII art.
+
+    Args:
+        word: The word to encode.
+
+    Returns:
+        A list of character encodings, each being a list of 5 row strings.
+    """
+    return [encode_char(c) for c in word if c.upper() in SEMAPHORE_POSITIONS]
+
+
+def get_display_lines(word: str) -> list[str]:
+    """Get the display lines for a word in semaphore.
+
+    Args:
+        word: The word to encode.
+
+    Returns:
+        A list of 5 strings, one for each row, with characters separated by spaces.
+    """
+    chars = encode_word(word)
+    if not chars:
+        return ["", "", "", "", ""]
+
+    # Combine all characters horizontally with space between
+    lines = []
+    for row in range(5):
+        line = "  ".join(char[row] for char in chars)
+        lines.append(line)
+
+    return lines

borse/words.py

@@ -0,0 +1,44 @@
+"""Word list for the game."""
+
+import random
+import string
+from pathlib import Path
+
+LETTERS = string.ascii_lowercase
+PATH_TO_WORDS = Path(__file__).with_name("WORDS.txt")
+
+
+with open(PATH_TO_WORDS) as f:
+    COMMON_WORDS = [line.strip() for line in f]
+
+
+def get_random_word() -> str:
+    """Get a random word from the word list.
+
+    Returns:
+        A random common English word.
+    """
+    return random.choice(COMMON_WORDS)
+
+
+def get_random_letter() -> str:
+    """Get a random single letter from A-Z.
+
+    Returns:
+        A random lowercase letter.
+    """
+    return random.choice(LETTERS)
+
+
+def get_random_word_or_letter(single_letter_probability: float = 0.3) -> str:
+    """Get either a random word or a single letter based on probability.
+
+    Args:
+        single_letter_probability: Probability (0-1) of returning a single letter.
+
+    Returns:
+        A random word or single letter.
+    """
+    if random.random() < single_letter_probability:
+        return get_random_letter()
+    return get_random_word()

borse-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: borse
+Version: 0.1.0
+Summary: A terminal game for practicing Morse code, Braille, and semaphore.
+Project-URL: repository, https://github.com/vEnhance/borse
+Author-email: Evan Chen <evan@evanchen.cc>
+License: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# borse
+
+**borse** is a terminal program meant to practice
+reading braille, Morse code, and semaphore,
+which are common encodings for
+[puzzle hunts](https://web.evanchen.cc/upload/EvanPuzzleCodings.pdf).
+Also supports A1Z26 practice.
+
+## Usage
+
+```bash
+uvx borse
+```
+
+Or you can install from PyPI by using `uv`, `pip`, etc.
+
+## Configuration
+
+Configuration is stored in `~/.config/borse/config.json` by default:
+
+```json
+{
+  "progress_file": "~/.config/borse/progress.json",
+  "words_per_game": 10
+}
+```
+
+Your daily progress is also automatically saved and displayed on the main menu.
+
+## Hints for memorizing the encodings
+
+Actually this is a note-to-self.
+
+### Remembering braille
+
+For Grade 1 (just the letters `A-Z`),
+the chart on [Wikipedia](https://en.wikipedia.org/wiki/English_Braille)
+is helpful!
+The trick is to memorize just the first 10 symbols for `A-J`,
+which only use the upper four dots.
+That's because `K-T` are the same as `A-J` with one extra dot,
+while `UVXYZ` are `A-E` with one extra dot.
+
+In real life, Grade 2 braille has some additional contractions.
+It might be nice to add these into borse at some point.
+
+### Remembering Morse code
+
+In Morse code, the most frequent letters are shorter.
+So I think it's a lot easier to remember Morse code as a binary tree,
+since the common letters will all be towards the top.
+I found [this picture on the Internet](https://slidetodoc.com/binary-trees-binary-tree-structure-root-node-stores/):
+
+![A Morse code binary tree](morse-tree.jpg)
+
+I think the dot looks like 0 and a dash looks like a (rotated) 1,
+so it makes sense to me that dots are in the left of the tree.
+
+Then you can just memorize the letters in each row in order.
+Here are some terrible mnemonics I made up that worked for me
+for the first three rows (you're on your own for the last one):
+
+- `ET`: Eastern Time, or a [1982 movie][et]
+- `IANM`: I Am Not Mad
+- `SURWDKGO`: [SuperUser][su] [ReWrote][rw] [DynamicKernel][dk] in [GO][go]
+
+(Also, `surdwkgo` is also the name of a
+[Taiwanese CodeForces grandmaster](https://codeforces.com/profile/surwdkgo).)
+
+[et]: https://en.wikipedia.org/wiki/E.T._the_Extra-Terrestrial
+[su]: https://en.wikipedia.org/wiki/Su_(Unix)
+[rw]: https://lean-lang.org/doc/reference/latest/Tactic-Proofs/Tactic-Reference/#rw
+[dk]: https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support
+[go]: https://en.wikipedia.org/wiki/Go_(programming_language)
+
+### Remembering semaphore
+
+If you look at a semaphore chart,
+what you'll find is that there are some groups of adjacent letters
+that just differ in one hand rotating clockwise.
+For example, the letters from `A-G` are obtained
+by fixing one arm at 6 o'clock and rotating the other arm
+all the way from 7:30 to 4:30.
+
+So in my head, I organize the letters in "blocks",
+where each block starts with two arms at a 45-degree angle,
+and then having the other arm rotate clockwise.
+The resulting blocks are then easier to remember:
+
+- **A block**: `ABCDEFG`
+- **H block**: `HIKLMN` (note `J` is missing)
+- **O block**: `OPQRS`
+- **T block**: `TUY` (note the additional `Y`)
+- **# block**: `#JV` (this is the weird exceptions one)
+- **W block**: `WX`
+- **Z block**: `Z`
+
+I don't know if `A HOT #WZ` means anything to you.
+
+## Development
+
+Set up by cloning the repository and running
+
+```bash
+uv sync
+uv run prek install
+```
+
+To manually run the linter and tests
+
+```bash
+uv run prek --all-files # run linter
+uv run prek --all-files --hook-stage pre-push
+```
+
+## FAQ
+
+- _Where does the name come from?_
+
+  From `Braille mORse SEmaphore`.
+
+- _Should "braille" be capitalized?_
+
+  [No](https://www.brailleauthority.org/capitalization/capitalization.html).
+
+- _Why would you spend time learning this?_
+
+  It could be a great conversation starter for a first date…

borse-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+borse/WORDS.txt,sha256=eEjDg7tmTgtFzhQMQrSNx58UdPpPmnax7JZIHjRGA5g,40575
+borse/__about__.py,sha256=0zET0Hr7ZlMR2QzPnTxlIVERltHMYywiz05ap-993o8,67
+borse/__init__.py,sha256=M5ARPgePzj8zEaqyk11jzt0RtDD5nbhA2KPS31vGJRk,109
+borse/a1z26.py,sha256=BmkTTxeCu4fvjFRMDSZktJWu0E169H32uga1khkl7gY,964
+borse/braille.py,sha256=h1q_r_4Am3_RswL3gqsa5Mm076RU0vSY7TSsQ72ExZQ,2642
+borse/config.py,sha256=eUDNRkxTIQRRpCnm9P3tQgFKjS4f2MF5-lNZFtt78Jg,3695
+borse/game.py,sha256=h_vLIRk-AX0FeHiL9y5UCj-1QyJW2iSOCFFPWjUvOnA,17278
+borse/main.py,sha256=peNdARRdBjtCP0rg2_hjq1GRkESWQhfxxAuGMYxyCkw,535
+borse/morse.py,sha256=nh7ptvXaoIHoUN_eval0-nZRd4oWyDNpDdnxsclx9F0,1818
+borse/progress.py,sha256=CPsv5SMF4ulHKbZu95_qK2_kpR1_BX1OFWChSoiKl44,4390
+borse/semaphore.py,sha256=mdU1siRkW4eAAgtCuSdc7aMCr2-DbZOwgmzpGnism8I,3855
+borse/words.py,sha256=3YifBii9OuMI2eHXAtvENxVM5n0T4eyZTU-NJ7EPmtQ,1023
+borse-0.1.0.dist-info/METADATA,sha256=LRsX8A7DmCJIa6pFCisk_MGg7KDhS3ybCPHea6ASnOg,4175
+borse-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+borse-0.1.0.dist-info/entry_points.txt,sha256=e3JYLL_H22Xgqe3_TyecetryyyE2kt07nBOGz4T41Ic,42
+borse-0.1.0.dist-info/licenses/LICENSE,sha256=gq-dD45uKs1sNrFCbrHXC8PpsWoSauIPzU-NEQHmTEc,1066
+borse-0.1.0.dist-info/RECORD,,

borse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

borse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+borse = borse.main:main

borse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.