b0f715a90af4b24daa3c892ceb00f7eb78478281 — Zach Smith 7 months ago ce6d559
Add some explanatory text
1 files changed, 54 insertions(+), 2 deletions(-)

M whist.lit
M whist.lit => whist.lit +54 -2
@@ 7,11 7,61 @@

@s Introduction

This program implements a **rules engine** for Tamerlane, the Card
Game Server. It provides a working version of the game Bid Whist, as
This program implements a **rules engine** for Tamerlane, the card
game server. It provides a working version of the game Bid Whist, as
well as an example implementation of a realistically complex rules

@s About This Document

This is a **literate program** which describes the full implementation
of a rules engine for Tamerlane. In it is contained all the source
code required to compile and run a web server which implements
Tamerlane's API contract.

This code is written using the [Literate][literate] program, which takes a
literate source document and renders the document you are reading, as
well as the source files needed to compile the program.

[literate]: http://literate.zbyedidia.webfactional.com/

The language that I've implemented this software in is [Janet][janet],
a lightweight lisp. To thoroughly understand the implementation it
might be good to know Janet, or at least a language like Clojure or
Scheme. To be able to follow along and understand what you need to
implement in order to write your *own* rules engine (which is the
purpose of this document), you don't need to know Janet. You just need
to understand some basic Lisp control forms like `let` and `defn`, and
to understand how to read an s-expression.

[janet]: https://janet-lang.org/

You should be able to read this document front-to-back, like a
book. I've tried to focus on the concepts that are central to the
function of the Tamerlane rules engine concept. Therefore, the bulk of
this document is concerned with writing the business logic that
defines the rules to the game Bid Whist. Also important is
understanding the specifics of the endpoints and HTTP methods that are
expected by Tamerlane.

Other implementation details are handled in appendices at the end of
the document. I've tried to make the code as readable and effective as
possible, but it should be less crucial to this document's purpose as
a guide for writing a games engine for Tamerlane.

@s Bid Whist

The game of Bid Whist is, as its name suggests, a descendent of the
old English game of Whist, and a cousin of the game Bridge.

A full copy of the rules are available at
[Pagat](https://www.pagat.com/auctionwhist/bidwhist.html). I've tried
to reproduce them faithfully and completely; one notable exception is
that I've opted to allow the auction to go around until all players
have passed instead of having it go exactly once around the table.

## The Tamerlane Arhitecture

@s Rules Engine Architecture

Here's a simplified sequence diagram illustrating how a player

@@ 1182,6 1232,8 @@ is still very much in development.
In Janet, the standard web framework is [Joy][]; we'll define an
extremely simple API using that library.

[joy]: https://joyframework.com/

--- main.janet
(import json)
(import init)