cube-cli 0.3.0__py3-none-any.whl

cube_cli/__init__.py

@@ -0,0 +1 @@
+'''cube_cli - CLI frontend for cube_model.'''

cube_cli/_version.py

@@ -0,0 +1,9 @@
+'''Package version string.'''
+from importlib.metadata import PackageNotFoundError, version
+
+def get_version() -> str:
+  '''Return the installed package version, or a dev fallback.'''
+  try:
+    return version('cube-cli')
+  except PackageNotFoundError:
+    return '0.0.0.dev0'

cube_cli/command.py

@@ -0,0 +1,355 @@
+'''Abstract Command base and all concrete REPL command types.'''
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Self
+
+from cube_model import Color, Cube, Side, shuffled, solved
+from cube_model.action import Action, ParseError, act, parse_actions
+from cube_model.navigation import all_colors, side_color
+
+from .repl_state import (
+  Exit,
+  LoadError,
+  ReplState,
+  UndoCube,
+  UndoItem,
+  UndoMove,
+  are_you_sure,
+)
+from .save_load import SaveError, load, save
+
+DEFAULT_FILE: str = 'cube.json'
+
+_LOAD_RE: re.Pattern[str] = re.compile(r'^load(?:\s+(\S.*?))?$', re.IGNORECASE)
+_SAVE_RE: re.Pattern[str] = re.compile(r'^save(?:\s+(\S.*?))?$', re.IGNORECASE)
+
+def _resolve_file(rs: ReplState, filename: str | None) -> str:
+  '''Resolve the filename to use for a save or load.
+
+  Uses filename if given, otherwise the last used file, otherwise
+  the default file.
+  '''
+  if filename is not None:
+    return filename
+  if rs.last_file is not None:
+    return rs.last_file
+  return DEFAULT_FILE
+
+def _is_solved(cube: Cube) -> bool:
+  '''Return True if every side shows a single uniform color.'''
+  colors: dict[Side, list[Color]] = all_colors(cube)
+  side: Side
+  for side in colors:
+    center: Color = side_color(cube, side)
+    if any(c != center for c in colors[side]):
+      return False
+  return True
+
+@dataclass
+class Command(ABC):
+  '''Abstract base for all REPL commands.'''
+
+  @classmethod
+  @abstractmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Parse a raw input string; return an instance if it matches.
+    Assumes that strip() has already been applied.'''
+
+  @abstractmethod
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Execute the command against the given REPL state.'''
+
+@dataclass
+class Shuffle(Command):
+  '''Randomize the cube.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Shuffle if cmd is "shuffle".'''
+    if cmd == 'shuffle':
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Replace the cube with a shuffled copy, if confirmed.'''
+    if not are_you_sure(rs):
+      return None
+    UndoCube.push(rs)
+    rs.cube = shuffled(initial=rs.cube)
+    rs.unsaved = True
+    return None
+
+@dataclass
+class Solve(Command):
+  '''Return the cube to its solved state.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Solve if cmd is "solve".'''
+    if cmd == 'solve':
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Replace the cube with a solved copy, if confirmed.'''
+    if not are_you_sure(rs):
+      return None
+    UndoCube.push(rs)
+    rs.cube = solved(initial=rs.cube)
+    rs.unsaved = False
+    return None
+
+@dataclass
+class Load(Command):
+  '''Load cube state from a file.'''
+  filename: str | None
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Load if cmd starts with "load".
+
+    The filename, if any, runs from the first non-whitespace
+    character after "load" to the end of the line, with only
+    trailing whitespace stripped.
+    '''
+    m: re.Match[str] | None = _LOAD_RE.match(cmd)
+    if m is None:
+      return None
+    return cls(filename=m.group(1))
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Load cube state from file, if confirmed.'''
+    if not are_you_sure(rs):
+      return None
+    target: str = _resolve_file(rs, self.filename)
+    result: Cube | LoadError = load(target, rs.cube)
+    if not isinstance(result, Cube):
+      rs.load_error = result
+      rs.print_cube = False
+      return None
+    UndoCube.push(rs)
+    rs.cube = result
+    rs.last_file = target
+    rs.unsaved = False
+    return None
+
+@dataclass
+class Save(Command):
+  '''Save cube state to a file.'''
+  filename: str | None
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Save if cmd starts with "save".
+
+    The filename, if any, runs from the first non-whitespace
+    character after "save" to the end of the line, with only
+    trailing whitespace stripped.
+    '''
+    m: re.Match[str] | None = _SAVE_RE.match(cmd)
+    if m is None:
+      return None
+    return cls(filename=m.group(1))
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Save cube state to file.'''
+    rs.print_cube = False
+    target: str = _resolve_file(rs, self.filename)
+    err: SaveError | None = save(rs.cube, target)
+    if err is not None:
+      print(f'Could not save to {target}: {err}')
+      return None
+    print(f'Cube saved to {target}')
+    rs.last_file = target
+    rs.unsaved = False
+    return None
+
+@dataclass
+class Undo(Command):
+  '''Undo the last command.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return an Undo if cmd is "undo".'''
+    if cmd == 'undo':
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Pop and apply the last undo item, if any.
+
+    If the undo buffer is empty, print 'Nothing to undo' instead
+    and do not print the cube.
+    '''
+    if not rs.undo_buf:
+      print('Nothing to undo')
+      rs.print_cube = False
+      return None
+    item: UndoItem = rs.undo_buf.pop()
+    item.undo(rs)
+    rs.redo_buf.append(item)
+    return None
+
+@dataclass
+class Redo(Command):
+  '''Redo the last undone command.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Redo if cmd is "redo".'''
+    if cmd == 'redo':
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Pop and apply the last redo item, if any.
+
+    If the redo buffer is empty, print 'Nothing to redo' instead
+    and do not print the cube.
+    '''
+    if not rs.redo_buf:
+      print('Nothing to redo')
+      rs.print_cube = False
+      return None
+    item: UndoItem = rs.redo_buf.pop()
+    item.redo(rs)
+    rs.undo_buf.append(item)
+    return None
+
+@dataclass
+class Quit(Command):
+  '''Exit the REPL.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Quit if cmd is "quit" or "q".'''
+    if cmd in ('quit', 'q'):
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Signal the REPL to exit, if confirmed.'''
+    if not are_you_sure(rs):
+      return None
+    return Exit.EXIT
+
+# Command reference text, shared with the --help epilog.
+HELP_TEXT: str = '''\
+Commands:
+
+  Before you enter a command, the current state of the cube is
+  printed in a textual format.
+
+  <moves>     A sequence of moves in standard cube move syntax.
+              Case-insensitive. To specify a wide move, use a
+              'w' suffix.
+
+  ^<moves>    A sequence of moves in standard cube move syntax.
+              Case-sensitive. To specify a wide move, use either
+              a lower-case face letter or a 'w' suffix.
+
+  solve       Return the cube to its initial solved position.
+
+  shuffle     Randomize the position of the cube.
+
+  undo        Undo the last previous command.
+
+  redo        If the last previous command was an undo, reverse
+              its effect.
+
+  save [file] Save the cube to a file. If [file] is not
+              specified, save to the last file used for a load
+              or save, or to cube.json in the current directory.
+
+  load [file] Load a saved cube. If [file] is not specified,
+              load from the last file used for a load or save,
+              or to cube.json in the current directory.
+
+  help, ?     Print this command reference.
+
+  quit, q     Exit cube.'''
+
+@dataclass
+class Help(Command):
+  '''Print a summary of available commands.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Help if cmd is "help" or "?".'''
+    if cmd in ('help', '?'):
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Print the command reference to stdout.'''
+    print(HELP_TEXT)
+    return None
+
+@dataclass
+class Noop(Command):
+  '''Do nothing.'''
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Return a Noop if cmd is the empty string.'''
+    if not cmd:
+      return cls()
+    return None
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Do nothing. Not even print the cube.'''
+    rs.print_cube = False
+    return None
+
+@dataclass
+class Move(Command):
+  '''Apply a parsed sequence of actions to the cube.'''
+  actions: list[Action]
+
+  @classmethod
+  def parse(cls, cmd: str) -> Self | None:
+    '''Parse a move sequence, with optional "^" prefix for case-sensitivity.
+
+    A leading "^" enables case-sensitive parsing. Without it, parsing
+    is case-insensitive. Returns None if the input is empty or cannot
+    be parsed as a valid move sequence.
+    '''
+    if cmd.startswith('^'):
+      tail: str = cmd[1:]
+      if not tail:
+        return None
+      ci: bool = False
+    else:
+      tail = cmd
+      ci = True
+    try:
+      actions: list[Action] = parse_actions(tail, ci=ci)
+    except ParseError:
+      return None
+    if not actions:
+      return None
+    return cls(actions=actions)
+
+  def run(self, rs: ReplState) -> Exit | None:
+    '''Apply each action in sequence to the cube.'''
+    UndoMove.push(rs, self.actions)
+    action: Action
+    for action in self.actions:
+      act(action, rs.cube)
+    rs.unsaved = not _is_solved(rs.cube)
+    return None
+
+# All command types in parse-priority order.
+all_commands: list[type[Command]] = [
+  Shuffle,
+  Solve,
+  Load,
+  Save,
+  Undo,
+  Redo,
+  Quit,
+  Help,
+  Noop,
+  Move,
+]

cube_cli/cube_json.py

@@ -0,0 +1,104 @@
+'''JSON serialisation and deserialisation for the Cube model.'''
+from typing import Any, NewType, cast
+
+from cube_model import Color, CornerSticker, Cube, EdgeSticker
+
+# JSON alias for a serialised cube object
+type CubeJSON = dict[str, str | dict[str, str]]
+
+# JSONError is a NewType of str. At runtime it is just str; use
+# isinstance(result, Cube) to distinguish success from error.
+JSONError = NewType('JSONError', str)
+
+def _color_ch(c: Color) -> str:
+  return c.name[0].lower()
+
+def _corner_str(cs: CornerSticker) -> str:
+  '''Encode a CornerSticker as a 3-char string.'''
+  return ''.join([
+    _color_ch(cs.color),
+    _color_ch(cs.other.color),
+    _color_ch(cs.other.other.color),
+  ])
+
+def _edge_str(es: EdgeSticker) -> str:
+  '''Encode an EdgeSticker as a 2-char string.'''
+  return ''.join([_color_ch(es.color), _color_ch(es.other.color)])
+
+def cube_to_json(cube: Cube) -> CubeJSON:
+  '''Serialise a Cube to a CubeJSON dict.'''
+  return {
+    'front_color': _color_ch(cube.front_color),
+    'top_color': _color_ch(cube.top_color),
+    'home': _corner_str(cube.home),
+    'next_edge': {
+      _corner_str(cs): _edge_str(es)
+      for cs, es in cube.next_edge.items()
+    },
+    'next_corner': {
+      _edge_str(es): _corner_str(cs)
+      for es, cs in cube.next_corner.items()
+    },
+  }
+
+def json_to_cube(cube_json: CubeJSON, initial: Cube) -> Cube | JSONError:
+  '''Deserialise a CubeJSON dict into a Cube, reusing stickers from initial.
+
+  Assumes well-formed input (i.e. produced by cube_to_json). Returns a
+  JSONError string on failure. Use isinstance(result, Cube) to distinguish
+  success from error at runtime.
+  '''
+  ch_to_color: dict[str, Color] = {_color_ch(c): c for c in Color}
+  corners: dict[str, CornerSticker] = {
+    _corner_str(cs): cs for cs in initial.next_edge
+  }
+  edges: dict[str, EdgeSticker] = {
+    _edge_str(es): es for es in initial.next_corner
+  }
+  try:
+    return Cube(
+      home=corners[cast(str, cube_json['home'])],
+      front_color=ch_to_color[cast(str, cube_json['front_color'])],
+      top_color=ch_to_color[cast(str, cube_json['top_color'])],
+      next_edge={
+        corners[k]: edges[v]
+        for k, v in cast(dict[str, str], cube_json['next_edge']).items()
+      },
+      next_corner={
+        edges[k]: corners[v]
+        for k, v in cast(dict[str, str], cube_json['next_corner']).items()
+      },
+    )
+  except (KeyError, AttributeError, TypeError) as e:
+    return JSONError(str(e))
+
+def any_to_json(value: Any) -> CubeJSON | JSONError:
+  '''Validate that an arbitrary parsed JSON value is a valid CubeJSON.
+
+  Returns a JSONError (str at runtime) on failure. Use isinstance(result,
+  dict) to distinguish success from error.
+  '''
+  if not isinstance(value, dict):
+    return JSONError('expected a JSON object at the top level')
+  result: CubeJSON = {}
+  k: object
+  v: object
+  for k, v in value.items():
+    if not isinstance(k, str):
+      return JSONError(f'non-string key: {k!r}')
+    if isinstance(v, str):
+      result[k] = v
+    elif isinstance(v, dict):
+      inner: dict[str, str] = {}
+      ik: object
+      iv: object
+      for ik, iv in v.items():
+        if not isinstance(ik, str) or not isinstance(iv, str):
+          return JSONError(f'non-string entry in nested object {k!r}')
+        inner[ik] = iv
+      result[k] = inner
+    else:
+      return JSONError(
+        f'value for {k!r} must be str or object, got {type(v).__name__}'
+      )
+  return result

cube_cli/main.py

@@ -0,0 +1,39 @@
+'''Entry point for the cube_cli application.'''
+import argparse
+
+from ._version import get_version
+from .command import HELP_TEXT
+from .repl import repl
+
+def _make_parser() -> argparse.ArgumentParser:
+  '''Build the argument parser for the cube command.'''
+  parser: argparse.ArgumentParser = argparse.ArgumentParser(
+    prog='cube',
+    description=(
+      'A textual CLI environment for manipulating a 3x3x3 cube\n'
+      'and solving puzzles based on it.'
+    ),
+    epilog=HELP_TEXT,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+  )
+  parser.add_argument(
+    '--version',
+    action='version',
+    version=f'cube {get_version()}',
+  )
+  parser.add_argument(
+    'file',
+    nargs='?',
+    metavar='file',
+    help=(
+      'Saved cube from a previous session. '
+      'If not specified, the cube starts solved.'
+    ),
+  )
+  return parser
+
+def main() -> None:
+  '''Run the cube CLI.'''
+  parser: argparse.ArgumentParser = _make_parser()
+  args: argparse.Namespace = parser.parse_args()
+  repl(args.file)

cube_cli/print.py

@@ -0,0 +1,86 @@
+'''Render a Cube as ASCII text lines.'''
+
+from collections.abc import Iterator
+
+from cube_model import Color, Cube, Side, all_colors, side_color
+
+def _center(cube: Cube, side: Side) -> str:
+  '''The color of the center of a side.'''
+  c: str = side_color(cube, side).name[0].lower()
+  return c
+
+def _face_grid(
+  cube: Cube, side: Side, indices: list[int]
+) -> list[str]:
+  '''The three display rows for a face.
+
+  indices is a list of 9 values indexing into all_colors for this
+  side, or -1 for the center, in order left-to-right then
+  top-to-bottom.
+  '''
+  ac: list[Color] = all_colors(cube)[side]
+  raw: list[str] = [
+    ac[i].name[0].lower() if i >= 0
+    else _center(cube, side)
+    for i in indices
+  ]
+  return [
+    ' '.join(raw[0:3]),
+    ' '.join(raw[3:6]),
+    ' '.join(raw[6:9]),
+  ]
+
+def print_cube(cube: Cube) -> Iterator[str]:
+  '''Render an ASCII representation of a cube.
+
+  Layout:
+
+         top
+         -----
+  left | front | right | back
+         -----
+         bottom
+
+  Each face is three rows of three color chars separated by spaces.
+  Faces in the horizontal row are separated by " | ".
+  Faces in the vertical column are separated by "-----".
+  Top/bottom are indented to align with front.
+  '''
+  # For each face, the indices into the all_colors color list,
+  # or -1 for the center, to get the colors for that face
+  # in the correct order for display.
+  # The indices for a face depend on the starting corner of
+  # the all_corners color list for the face.
+  face_indices: dict[Side, list[int]] = {
+    # front: top-left start
+    Side.FRONT:  [0, 1, 2,  7, -1, 3,  6, 5, 4],
+    # top: front-left start
+    Side.TOP:    [2, 3, 4,  1, -1, 5,  0, 7, 6],
+    # bottom: left-front start
+    Side.BOTTOM: [0, 1, 2,  7, -1, 3,  6, 5, 4],
+    # left: top-front start
+    Side.LEFT:   [6, 7, 0,  5, -1, 1,  4, 3, 2],
+    # right: front-top start
+    Side.RIGHT:  [0, 1, 2,  7, -1, 3,  6, 5, 4],
+    # back: top-right start
+    Side.BACK:   [6, 7, 0,  5, -1, 1,  4, 3, 2],
+  }
+  indent: str = ' ' * 8
+  sep: str = '-' * 5
+  rows: dict[Side, list[str]] = {
+    s: _face_grid(cube, s, face_indices[s])
+    for s in Side
+  }
+  row: str
+  for row in rows[Side.TOP]:
+    yield indent + row
+  yield indent + sep
+  middle: tuple[Side, Side, Side, Side] = (
+    Side.LEFT, Side.FRONT, Side.RIGHT, Side.BACK
+  )
+  l: str; f: str; r: str; b: str
+  for l, f, r, b in zip(*(rows[s] for s in middle)):
+    yield f'{l} | {f} | {r} | {b}'
+  yield indent + sep
+  for row in rows[Side.BOTTOM]:
+    yield indent + row

cube_cli/repl.py

@@ -0,0 +1,65 @@
+'''REPL loop and command parser for the cube CLI.'''
+import readline
+
+from cube_model import Cube, solved
+
+from .command import Command, Quit, all_commands
+from .print import print_cube
+from .repl_state import Exit, LoadError, ReplState
+from .save_load import SaveError, load
+
+def parse_command(inp: str) -> Command | None:
+  '''Try each command type in order; return the first match.'''
+  cmd_type: type[Command]
+  for cmd_type in all_commands:
+    cmd: Command | None = cmd_type.parse(inp)
+    if cmd is not None:
+      return cmd
+  return None
+
+def _initial_state(filename: str | None) -> ReplState:
+  '''Build the initial REPL state, loading filename if given.
+
+  If the load fails, report the error.
+  '''
+  if filename is None:
+    return ReplState(cube=solved())
+  result: Cube | LoadError = load(filename, solved())
+  if isinstance(result, Cube):
+    return ReplState(cube=result, last_file=filename)
+  return ReplState(cube=solved(), load_error=result)
+
+def repl(filename: str | None) -> None:
+  '''Run the interactive REPL.
+
+  If filename is given, load it as the initial cube state. If the
+  load fails, fall back to a solved cube and report the error.
+  '''
+  cmd: Command | None
+  rs: ReplState = _initial_state(filename)
+  while True:
+    if rs.print_cube:
+      line: str
+      for line in print_cube(rs.cube):
+        print(line)
+    else:
+      rs.print_cube = True # reset for next time
+    if rs.load_error is not None:
+      fn: str = rs.load_error.filename
+      msg: str = rs.load_error.msg
+      print(f'Could not load from {fn}: {msg}')
+      rs.load_error = None # reset for next time
+    try:
+      inp: str = input(
+        'Command (? for help, q to quit): ').strip()
+    except EOFError:
+      cmd = Quit()
+    else:
+      cmd = parse_command(inp)
+      if cmd is None:
+        print('Invalid command')
+        rs.print_cube = False
+        continue
+    result: Exit | None = cmd.run(rs)
+    if result is Exit.EXIT:
+      break

cube_cli/repl_state.py

@@ -0,0 +1,146 @@
+'''REPL state and exit signal for the cube CLI.'''
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+
+from cube_model import Cube, Move
+from cube_model.action import Action, Rotation, SliceMove, WideMove, act
+from cube_model.move import invert
+
+class Exit(Enum):
+  '''Singleton signal that the REPL should exit.'''
+  EXIT = 'exit'
+
+@dataclass
+class LoadError:
+  '''The error message resulting from a failed load of the cube from
+  a file.
+  '''
+  filename: str
+  msg: str
+
+def _invert_action(action: Action) -> Action:
+  '''Return the inverse of a single action.
+
+  Inverting a Move inverts its multiplicity directly. Inverting a
+  Rotation, WideMove, or SliceMove inverts the multiplicity of the
+  Move it wraps, preserving the wrapper type.
+  '''
+  match action:
+    case Rotation(move=m):
+      return Rotation(Move(m.face, invert[m.mult]))
+    case WideMove(move=m):
+      return WideMove(Move(m.face, invert[m.mult]))
+    case SliceMove(move=m):
+      return SliceMove(Move(m.face, invert[m.mult]))
+    case Move() as m:
+      return Move(m.face, invert[m.mult])
+
+def _invert_actions(actions: list[Action]) -> list[Action]:
+  '''Return the inverse of a sequence of actions.
+
+  The order of the actions is reversed, and each action's
+  multiplicity is inverted.
+  '''
+  return [_invert_action(a) for a in reversed(actions)]
+
+@dataclass
+class UndoItem(ABC):
+  '''Abstract base for an entry in a ReplState undo or redo stack.'''
+  unsaved: bool
+
+  @abstractmethod
+  def undo(self, rs: ReplState) -> None:
+    '''Undo this item against rs, preparing self for the redo
+    buffer.
+    '''
+
+  @abstractmethod
+  def redo(self, rs: ReplState) -> None:
+    '''Redo this item against rs, preparing self for the undo
+    buffer.
+    '''
+
+@dataclass
+class UndoCube(UndoItem):
+  '''Undo item capturing a full previous cube and saved state.
+
+  Used by the Shuffle, Solve, and Load commands, which completely
+  replace the cube.
+  '''
+  cube: Cube
+
+  @classmethod
+  def push(cls, rs: ReplState) -> None:
+    '''Snapshot rs's current cube and unsaved flag onto the undo
+    buffer, and clear the redo buffer.
+    '''
+    rs.undo_buf.append(cls(unsaved=rs.unsaved, cube=rs.cube))
+    rs.redo_buf.clear()
+
+  def undo(self, rs: ReplState) -> None:
+    '''Swap unsaved and cube with rs.'''
+    rs.unsaved, self.unsaved = self.unsaved, rs.unsaved
+    rs.cube, self.cube = self.cube, rs.cube
+
+  def redo(self, rs: ReplState) -> None:
+    '''Identical to undo: swap unsaved and cube with rs.'''
+    self.undo(rs)
+
+@dataclass
+class UndoMove(UndoItem):
+  '''Undo item capturing a sequence of actions to invert or reapply.
+
+  Used by the Move command.
+  '''
+  actions: list[Action]
+
+  @classmethod
+  def push(cls, rs: ReplState, actions: list[Action]) -> None:
+    '''Snapshot rs's current unsaved flag and the actions about to
+    be applied onto the undo buffer, and clear the redo buffer.
+    '''
+    rs.undo_buf.append(cls(unsaved=rs.unsaved, actions=actions))
+    rs.redo_buf.clear()
+
+  def undo(self, rs: ReplState) -> None:
+    '''Swap unsaved with rs and apply the inverse of the actions.'''
+    rs.unsaved, self.unsaved = self.unsaved, rs.unsaved
+    action: Action
+    for action in _invert_actions(self.actions):
+      act(action, rs.cube)
+
+  def redo(self, rs: ReplState) -> None:
+    '''Swap unsaved with rs and reapply the actions.'''
+    rs.unsaved, self.unsaved = self.unsaved, rs.unsaved
+    action: Action
+    for action in self.actions:
+      act(action, rs.cube)
+
+@dataclass
+class ReplState:
+  '''Mutable state threaded through REPL command execution.'''
+  cube: Cube
+  unsaved: bool = False
+  last_file: str | None = None
+  load_error: LoadError | None = None
+  print_cube: bool = True
+  undo_buf: list[UndoItem] = field(default_factory=list)
+  redo_buf: list[UndoItem] = field(default_factory=list)
+
+def are_you_sure(rs: ReplState) -> bool:
+  '''Prompt for confirmation if the cube is unsaved.
+
+  Returns True if the action should proceed: either the cube is
+  already saved, or the user confirmed with (case-insensitive)
+  "yes" or "y". Returns False otherwise.
+  '''
+  if not rs.unsaved:
+    return True
+  answer: str = input('The cube is not saved. Are you sure? ')
+  if answer.strip().lower() in ('yes', 'y'):
+    return True
+  rs.print_cube = False
+  return False

cube_cli/save_load.py

@@ -0,0 +1,55 @@
+'''Save and load cube state to and from JSON files.'''
+import json
+from typing import NewType
+
+from cube_model import Cube
+
+from ._version import get_version
+from .cube_json import (CubeJSON, JSONError, any_to_json,
+  cube_to_json, json_to_cube)
+from .repl_state import LoadError
+
+# The error message resulting from a failed save of the cube to
+# a file.
+SaveError = NewType('SaveError', str)
+
+def save(cube: Cube, filename: str) -> SaveError | None:
+  '''Serialise cube to a JSON file, including the current version.
+
+  Returns a SaveError on failure, None on success.
+  '''
+  cj: CubeJSON = cube_to_json(cube)
+  cj['version'] = get_version()
+  try:
+    with open(filename, 'w') as f:
+      json.dump(cj, f)
+  except PermissionError:
+    return SaveError('permission denied')
+  except OSError:
+    return SaveError('could not write file')
+  return None
+
+def load(filename: str, initial: Cube) -> Cube | LoadError:
+  '''Deserialise a Cube from a JSON file, ignoring the version field.
+
+  Returns a LoadError on failure. Use isinstance(result, Cube) to
+  distinguish success from error at runtime.
+  '''
+  try:
+    with open(filename) as f:
+      raw = json.load(f)
+  except FileNotFoundError:
+    return LoadError(filename, 'file not found')
+  except PermissionError:
+    return LoadError(filename, 'permission denied')
+  except OSError:
+    return LoadError(filename, 'could not read file')
+  except json.JSONDecodeError:
+    return LoadError(filename, 'not a valid JSON file')
+  cj: CubeJSON | JSONError = any_to_json(raw)
+  if not isinstance(cj, dict):
+    return LoadError(filename, 'JSON has invalid format')
+  result: Cube | JSONError = json_to_cube(cj, initial)
+  if not isinstance(result, Cube):
+    return LoadError(filename, 'JSON has invalid format')
+  return result

cube_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: cube-cli
+Version: 0.3.0
+Summary: A CLI application for interacting with cube_model
+Requires-Python: >=3.13,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: cube-model (>=1.0.4,<2.0.0)
+Project-URL: Repository, https://github.com/ygale/cube-cli
+Description-Content-Type: text/markdown
+
+# cube-cli
+
+A textual cli environment for manipulating a 3x3x3 cube and solving
+puzzles based on it.
+
+## Usage
+
+    cube [options] [file]
+
+[file] is a saved cube from a previous session. If not specified,
+the cube is initialized to its solved state.
+
+## Options
+
+--help
+--version
+
+## Commands
+
+Before you enter a command, the current state of the cube is printed
+in a textual format.
+
+\<moves> A sequence of moves in standard cube move syntax.
+Case-insensitive. To specify a wide move, use a 'w' suffix.
+
+^\<moves> A sequence of moves in standard cube move syntax.
+Case-sensitive. To specify a wide move, use either a lower-case face
+letter or a 'w' suffix.
+
+solve Return the cube to its initial solved position.
+
+shuffle Randomize the position of the cube.
+
+undo Undo the last previous command.
+
+redo If the last previous command was an undo, reverse its effect.
+
+save [file] Save the cube to a file. If [file] is not specified, save
+to the last file used for a load or save, or to cube.json in the
+current directory.
+
+load [file] Load a saved cube. If [file] is not specified, load from
+the last file used for a load or save, or to cube.json in the
+current directory.
+
+help, ? Print this command reference.
+
+quit, q Exit cube.
+

cube_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cube_cli/__init__.py,sha256=7GnaFYeAAHVLgWr0qRe-Q0SOJc0KbJXr4ARAv-oymBA,46
+cube_cli/_version.py,sha256=AM0tu5yAmFzzrAIEGNw8-GkTMy7SgyEDHXGCPcFdJd4,276
+cube_cli/command.py,sha256=qkYJKgVldOWvSvoya-PJk7IQlRZkHl-3QjvIyLe6hiQ,9411
+cube_cli/cube_json.py,sha256=D3076BND-7NAIwRpzXbuT5xKSgd1gP4ZJTY409dzu80,3439
+cube_cli/main.py,sha256=bQ8D4eIywWXImKo8q4BOf2cm0jANRGzxGXwadRuM0ZE,1022
+cube_cli/print.py,sha256=MOVBnVw_57SrpyJDwvNOFKaUPB6haxTllj50Cp61CgU,2527
+cube_cli/repl.py,sha256=i37a6c4NWMZfZjpeip6NRO001S6BONzKLyv_VjlbY6Q,1957
+cube_cli/repl_state.py,sha256=P73IY-JYuQgo4aIeRtuO9ZZ1Ejt3mlYP9Rw7kpbFTpc,4355
+cube_cli/save_load.py,sha256=xl1g7QREGOnyLCbFpGE1tGsD3CMP6ouq5LenFzBVe3M,1778
+cube_cli-0.3.0.dist-info/METADATA,sha256=v3X8UHs21sZr6uhx_RyesdizkXc93vjC-o8AwyCmb3Q,1663
+cube_cli-0.3.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+cube_cli-0.3.0.dist-info/entry_points.txt,sha256=4SfY9yBwJ4QxCZeyocL01xiLt-L3wrSX-jLcOuJbBQs,43
+cube_cli-0.3.0.dist-info/RECORD,,

cube_cli-0.3.0.dist-info/WHEEL

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

cube_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cube=cube_cli.main:main
+