@slugbugblue/trax 0.5.0 → 0.9.0

package/CHANGELOG.md

@@ -1,51 +1,91 @@
 # @slugbugblue/trax
 
+## 0.9.0 - 2022-04-24
+
+- Added tab-completion and completion preview code to the interactive CLI
+- Restructured the CLI by moving most commands to their own file
+- Changed the `view` CLI command to optionally examine previous moves
+
+## 0.8.0 - 2022-04-08
+
+- Breaking change: `playMove()` now takes the _next_ move number instead of the
+  _last_ move number. It makes more sense to say "move number 1 is @0/" than to
+  say "the move following move number 0 is @0/".
+- Added variant name info to the engine as `Trax.name[rules]` as well as
+  `trax.name`
+- Restructured the repo to handle additional files, creating `src` and `hooks`
+  folders
+- Added a command-line interface (CLI) `cli.js` which npm will install using the
+  alias `trax`
+- The CLI usage is self-documenting; run `trax help` to get started
+- Initial commands available: `delete`, `export`, `help`, `import`, `list`,
+  `new`, `play`, `select`, `try`, `undo`, `view`
+
+## 0.7.0 - 2022-03-28
+
+- Fixed a bug when including extra characters in a starting notation
+- Added regression tests to detect/prevent this bug in the future
+
+## 0.6.0 - 2022-02-13
+
+- Completed documentation for `engine.js` at [docs/engine.md](docs/engine.md)
+- `x` and `y` locations are now handled in a `Point` class
+- Renamed `tentativeIcon()` to `dropsIcon()`
+
+## 0.5.0 - 2022-01-29
+
+This code base is now using [`xo`](https://github.com/xojs/xo) for style and
+[`ava`](https://github.com/avajs/ava) for testing. Should be no functional
+changes, but a lot of code was updated, including the names of all functions and
+variables from snake_case to camelCase.
+
 ## 0.4.0 - 2022-01-17
 
-* Testing coverage of `engine.js` is now at 100%
-* Testing revealed a few bugs, which are now fixed
-* The name and signature for provisional move handling,
-  which was broken, has been changed. It is now called
-  `provisional_moves()` and takes three arguments:
+- Testing coverage of `engine.js` is now at 100%
+- Testing revealed a few bugs, which are now fixed
+- The name and signature for provisional move handling, which was broken, has
+  been changed. It is now called `provisional_moves()` and takes three
+  arguments:
 
-  * `from`: the normalized position code of the board before the move
-  * `to`: the normalized position code of the board after the move
-  * `via`: the move notation to go from `from` to `to`
+  - `from`: the normalized position code of the board before the move
+  - `to`: the normalized position code of the board after the move
+  - `via`: the move notation to go from `from` to `to`
 
 ### 0.3.1 - 2022-01-07
 
-* Make a faster implementation of `trax.possible_locations()`
-* Display updates for tentative moves
+- Make a faster implementation of `trax.possible_locations()`
+- Display updates for tentative moves
 
 ## 0.3.0 - 2021-12-29
 
 Display a tentative move on the screen
 
-* Add `trax.tentative_icon()` function
-* `tty.display()` now accepts a tentative move
+- Add `trax.tentative_icon()` function
+- `tty.display()` now accepts a tentative move
 
 ## 0.2.0 - 2021-12-28
 
 Breaking changes:
 
-* Converted from CommonJS to ESM
-* `trax.normalized` now prepends turn information to the string
+- Converted from CommonJS to ESM
+- `trax.normalized` now prepends turn information to the string
 
 More convenience:
 
-* `trax.color`: the color of the player whose turn it is
-* `Trax.color_of[num]`: go from player number to color
-* `Trax.player_num[color]`: or from color to player number
-* `Trax.other[color]`: easily switch from 'w' to 'b' and back
+- `trax.color`: the color of the player whose turn it is
+- `Trax.color_of[num]`: go from player number to color
+- `Trax.player_num[color]`: or from color to player number
+- `Trax.other[color]`: easily switch from 'w' to 'b' and back
 
 ## 0.1.0 - 2021-12-26
 
 Initial release:
 
-* engine.js
-  * create a new Trax game with `trax = new Trax()`
-  * play one move at a time with `trax.play('@0/')`
-  * ... etc
+- engine.js
+
+  - create a new Trax game with `trax = new Trax()`
+  - play one move at a time with `trax.play('@0/')`
+  - ... etc
 
-* tty.js
-  * display a game with `tty.display(trax)`
+- tty.js
+  - display a game with `tty.display(trax)`

package/README.md

@@ -4,33 +4,101 @@ Trax game-playing engine and etc.
 
 ## Description
 
-Trax is a two-player boardless board game invented by David Smith.
-For more information about Trax,
-including its rules and history,
-see the official website at [traxgame.com][traxgame].
+Trax is a two-player boardless board game invented by David Smith. For more
+information about Trax, including its rules and history, see the official
+website at [traxgame.com][traxgame].
 
-This goal of this javascript project
-is to allow Trax to be played programmatically.
-It can be used as an engine in a web browser
-or in nodejs.
+This goal of this javascript project is to allow Trax to be played
+programmatically. It can be used as an engine in a web browser, for example at
+[slugbugblue.com][sbb]; or in nodejs, for example by using the `trax` CLI
+provided as part of this project.
 
-The Trax engine now enjoys automated testing
-with 100% code coverage. Any future changes
-to the engine should meet the same standard.
+The Trax engine now enjoys automated testing with 100% code coverage. Any future
+changes to the engine should meet the same standard.
 
 ## Installation
 
 ```bash
+# Install into a javascript project
 npm install @slugbugblue/trax
+
+# Or install globally to use the trax CLI
+npm install -g @slugbugblue/trax
+```
+
+## CLI Usage
+
+The command-line interface is provided as `trax`, available in your path if
+installed globally, or in the `node_modules/.bin` directory and runnable using
+`npx trax` if installed locally.
+
+The CLI can be used interactively by passing the `--interactive` or `-i` flag.
+When run interactively, you can avoid worries about the need to escape certain
+characters from the shell, and it can be easier to run multiple commands back to
+back.
+
+Help is available for the CLI through the use of the `help` command. Type
+`trax help` to see a list of the available commands, and `trax help play` to see
+information about the `play` command. Aliases and abbreviations are provided to
+minimize typing and to try to avoid the requirement of memorizing the commands.
+For example, the `list` command has an alias of `ls`, and the `select` command
+can be activated using `#`.
+
+When you first launch the CLI, you can create a new game using the `new`
+command, and then enter moves for that game using `play`. Since `play` is likely
+to be the most common command used, you can simply omit the command name. For
+example, at the interactive prompt, entering `@0/` is the same as if you had
+entered `play 1. @0/`.
+
+Multiple games can be started at once, and the CLI will remember the currently
+active game and apply future actions to that game. Each game will retain its
+`#id` number until it is deleted, and you can use that number to switch between
+games. For example, to make game #1 active, enter `select 1` or `select #1` or
+simply `#1` at the interactive prompt.
+
+For ease of working at the command line, the symbols used as the last character
+of the Trax notation can optionally be replaced with letters. Use `s` for slash
+symbol (`/`), `b` for backslash (`\`), and `p` for plus (`+`). While there is no
+need to escape at the interactive prompt, these substitutions will be avilable
+there as well.
+
+The CLI uses standard Windows and Linux [XDG][xdg] file locations as provided by
+the [env-paths library][env-path], with current uses being the `config` and
+`data` folders.
+
+Examples:
+
+```text
+# Start a new Trax game with Chad playing as white
+> trax new Chad vs
+
+# Start a new Loop Trax game with Chad playing as black
+> trax new loop vs Chad
+
+# Start a new 8x8 Trax game with Chad as white and Another Player as black
+> trax new 8x8 Chad vs Another Player
+
+# Switch back to the first game. Note the quoting required at the command line.
+# This would not be necessary when running at the interactive prompt.
+> trax '#1'
+
+# Play two moves, using full notation
+> trax play 1. @0/ 2. A0/
+
+# Two more moves, using short notation and symbol substitution
+# B2/ => b2s and A0\ => a0b
+> trax b2s a0b
+
+# See the status of all games
+> trax ls
 ```
 
-## Usage
+## API Usage
 
-The main Trax engine is provided as `engine.js`,
-which can be used as follows:
+The main Trax engine is provided as `engine.js`, which can be used as follows:
 
 ```javascript
-import Trax from '@slugbugblue/trax'
+import { Trax } from '@slugbugblue/trax'
 
 // default constructor gives you a Trax game
 let trax = new Trax()
@@ -47,89 +115,72 @@ let puzzle = new Trax('trax', '@0/ a0\\ @2/')
 puzzle.play('@2\\')
 ```
 
-Explore the file `engine.js` for more information
-until I get around to documenting the functionality.
+For specifics, see the [engine.js documentation][engine-docs].
 
 ## Roadmap
 
-* Documentation
-* Command line interface
-* Bot for solo games (?)
-* Puzzles
+- Game position analysis
+- Bot
+- Puzzles
 
 ## Support
 
-This project is built by [Chad Transtrum][ctrans]
-for [slugbugblue.com][sbb].
-Issues can be opened on the
-[gitlab project page][repo].
+This project is built by [Chad Transtrum][ctrans] for [slugbugblue.com][sbb].
+Issues can be opened on the [gitlab project page][repo].
 
 ## Contributing
 
-Contributions are welcome.
-Ideally in the form of pull requests,
-but feel free to open an issue with a bug report
-or a suggestion as well.
-
-## Authors and acknowledgment
-
-Many thanks to the late David Smith
-for coming up with the idea of Trax
-and for his generosity in allowing me to
-add the game to [GoldToken.com][goldtoken].
-
-Thanks to his widow Colleen Foley-Smith
-for extending that courtesy
-to allow me to include Trax on [slugbugblue.com][sbb]
-as well.
-
-I would also like to extend a huge heartfelt appreciation
-to the magnanimous [Donald G. Bailey][dgb],
-who, through his excellent [book][traxbook],
-taught me the basics (and more!) of Trax.
-I found him always ready to share his insights
-on the mechanics of the game,
-as well as various approaches to encoding its complexities.
-His undeserved kindness
-and infinite patience
-in indulging my many questions
-can never be repaid.
+Contributions are welcome. Ideally in the form of pull requests, but feel free
+to open an issue with a bug report or a suggestion as well.
+
+## Acknowledgments
+
+Many thanks to the late David Smith for coming up with the idea of Trax and for
+his generosity in allowing me to add the game to [GoldToken.com][goldtoken].
+
+Thanks to his widow Colleen Foley-Smith for extending that courtesy to allow me
+to include Trax on [slugbugblue.com][sbb] as well.
+
+I would also like to extend a huge heartfelt appreciation to the magnanimous
+[Donald G. Bailey][dgb], who, through his excellent [book][traxbook], taught me
+the basics (and more!) of Trax. I found him always ready to share his insights
+on the mechanics of the game, as well as various approaches to encoding its
+complexities. His undeserved kindness and infinite patience in indulging my many
+questions can never be repaid.
 
 ## License
 
 Copyright 2019-2022 Chad Transtrum
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use the files in this project
-except in compliance with the License.
-You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+the files in this project except in compliance with the License. You may obtain
+a copy of the License at
 
-  http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
 
 ## Trax rules copyright
 
-In the United States, game mechanics may not be copyrighted;
+In the United States, game mechanics are not eligible for coyright protection;
 however, the specific wording of game rules does fall under copyright law.
 
 The official rules for Trax are found at http://traxgame.com/about_rules.php.
 
-As Trax is a proprietary game,
-these rules are the intellectual property
-of David Smith and heirs,
-and are not to be used without permission.
-
-
+As Trax is a proprietary game, these rules are the intellectual property of
+David Smith and heirs, and are not to be used without permission.
 
 [ctrans]: mailto:chad@transtrum.net
 [dgb]: mailto:donald@traxgame.com
+[engine-docs]: docs/engine.md
+[env-path]: https://www.npmjs.com/package/env-paths
 [goldtoken]: https://goldtoken.com/
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
+[xdg]:
+  https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html