Commit dfd29860 authored by Vivien Kraus's avatar Vivien Kraus
Browse files

Add the manual back

parent b0b1817f
......@@ -23,3 +23,8 @@ m4/ltversion.m4
m4/ltsugar.m4
m4/lt~obsolete.m4
test-driver
doc/mdate-sh
doc/stamp-vti
doc/tarot.info
doc/texinfo.tex
doc/version.texi
\ No newline at end of file
bin_PROGRAMS =
lib_LTLIBRARIES = libtarot.la
libtarot_la_SOURCES = \
src/_tarot_count_cards.c \
src/_tarot_count_handful.c \
src/_tarot_has_lead_suit.c \
src/_tarot_n_cards_in_trick.c \
src/_tarot_n_players_between.c \
src/_tarot_strongest_trump.c \
src/tarot_decompose.c \
src/tarot_game_bids.c \
src/tarot_game_call.c \
src/tarot_game_cards.c \
src/tarot_game_decl.c \
src/tarot_game_discard.c \
src/tarot_game_dog.c \
src/tarot_game_handful.c \
src/tarot_game_init.c \
src/tarot_game_options.c \
src/tarot_game_state.c \
src/tarot_game_trick.c \
src/tarot_game_trick_card.c \
src/tarot_libtarot_version.c \
src/tarot_of.c \
src/tarot_private.h \
src/tarot_strerror.c
libtarot_la_CFLAGS = $(OPENMP_CFLAGS) $(ASAN_CFLAGS)
libtarot_la_LDFLAGS = -no-undefined -version-info $(LIBTAROT_VERSION_INFO)
libtarot_la_LIBADD = $(ASAN_LIBS)
include_HEADERS = src/tarot.h
TESTS = \
check_composition \
check_game_init
check_PROGRAMS = \
check_composition \
check_game_init
check_composition_SOURCES = src/check_composition.c
check_composition_CFLAGS = $(ASAN_CFLAGS)
check_composition_LDADD = libtarot.la
check_composition_LIBS = $(ASAN_LIBS)
check_game_init_SOURCES = src/check_game_init.c
check_game_init_CFLAGS = $(ASAN_CFLAGS)
check_game_init_LDADD = libtarot.la
check_game_init_LIBS = $(ASAN_LIBS)
INDENTED_FILES = \
$(include_HEADERS) \
$(libtarot_la_SOURCES) \
$(check_composition_SOURCES) \
$(check_game_init_SOURCES)
SUBDIRS = doc src
ACLOCAL_AMFLAGS = -I m4
dist_noinst_SCRIPTS = bootstrap.sh
EXTRA_DIST = $(srcdir)/indent.stamp .gitignore \
$(srcdir)/hooks/pre-commit.sh
$(srcdir)/indent.stamp: $(INDENTED_FILES)
if HAVE_INDENT
(cd $(srcdir) && $(INDENT) -gnu $(INDENTED_FILES))
echo "Done!" > $(srcdir)/indent.stamp
EXTRA_DIST = .gitignore \
$(srcdir)/hooks/pre-commit.sh \
README.org \
README.md
AM_DISTCHECK_CONFIGURE_FLAGS = "EMACS=no INDENT=no"
if HAVE_ORGMODE
README: README.org
echo "$(srcdir)/README.txt" | $(EMACS) \
"$(srcdir)/README.org" \
--batch \
--eval "(require 'ox-ascii)" \
-f org-ascii-export-to-ascii && \
mv "$(srcdir)/README.txt" "$(srcdir)/README"
README.md: README.org
echo "$(srcdir)/README.md" | $(EMACS) \
"$(srcdir)/README.org" \
--batch \
--eval "(require 'ox-md)" \
-f org-md-export-to-markdown
else
@ >&2 echo "ERROR: you have changed the source code, \
but you don't have indent installed."
README: README.org
@ >&2 echo \
"README.org has changed but you don't have emacs installed." \
&& exit 1
README.md: README.org
@ >&2 echo \
"README.org has changed but you don't have emacs installed." \
&& exit 1
endif
This is a standard autotools-based project.
\ No newline at end of file
________________________________________
READ ME !
Vivien Kraus <vivien@planete-kraus.eu>
________________________________________
Table of Contents
_________________
1 Read me
2 Compile this project
.. 2.1 Gitlab users: make a source distribution
.. 2.2 Everyone: configure, make and install
3 Let me know
1 Read me
=========
This repository hosts the project named Tarot, for /The Amazing Rules
Of Tarot/. It aims at providing a game and an artificial
intelligence.
2 Compile this project
======================
To compile this project, you will need a /source distribution/. If
you have received an archive of source code, then you it is what you
have. If you cloned this project from gitlab, then you have to do
some more work.
2.1 Gitlab users: make a source distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You have to install the autotools (`autoconf', `automake', `libtool',
`texinfo'). Once this is done, you can run the `bootstrap.sh' script
at the top-level directory that will:
- make a source distribution in the sub-folder `devel-build';
- set up the company-clang options for emacs;
- install a pre-commit hook into the git repository.
2.2 Everyone: configure, make and install
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can run:
,----
| ./configure --help
`----
to know what options are available. If you want more details, see
`INSTALL'.
3 Let me know
=============
I develop Tarot as a personal hobby. If you find it interesting, or
have bugs to submit, please let me know: `vivien@planete-kraus.eu'
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#org9a8080a">1. Read me</a></li>
<li><a href="#orgaad5631">2. Compile this project</a>
<ul>
<li><a href="#orgf696d2a">2.1. Gitlab users: make a source distribution</a></li>
<li><a href="#orgb86c25e">2.2. Everyone: configure, make and install</a></li>
</ul>
</li>
<li><a href="#org984d9b0">3. Let me know</a></li>
</ul>
</div>
</div>
<a id="org9a8080a"></a>
# Read me
This repository hosts the project named Tarot, for *The Amazing Rules
Of Tarot*. It aims at providing a game and an artificial
intelligence.
<a id="orgaad5631"></a>
# Compile this project
To compile this project, you will need a *source distribution*. If
you have received an archive of source code, then you it is what you
have. If you cloned this project from gitlab, then you have to do
some more work.
<a id="orgf696d2a"></a>
## Gitlab users: make a source distribution
You have to install the autotools (`autoconf`, `automake`, `libtool`,
`texinfo`). Once this is done, you can run the `bootstrap.sh` script
at the top-level directory that will:
- make a source distribution in the sub-folder `devel-build`;
- set up the company-clang options for emacs;
- install a pre-commit hook into the git repository.
<a id="orgb86c25e"></a>
## Everyone: configure, make and install
You can run:
./configure --help
to know what options are available. If you want more details, see
`INSTALL`.
<a id="org984d9b0"></a>
# Let me know
I develop Tarot as a personal hobby. If you find it interesting, or
have bugs to submit, please let me know: `vivien@planete-kraus.eu`
#+title: Read me !
#+author: Vivien Kraus <vivien@planete-kraus.eu>
#+language: en
* Read me
This repository hosts the project named Tarot, for /The Amazing Rules
Of Tarot/. It aims at providing a game and an artificial
intelligence.
* Compile this project
To compile this project, you will need a /source distribution/. If
you have received an archive of source code, then you it is what you
have. If you cloned this project from gitlab, then you have to do
some more work.
** Gitlab users: make a source distribution
You have to install the autotools (=autoconf=, =automake=, =libtool=,
=texinfo=). Once this is done, you can run the =bootstrap.sh= script
at the top-level directory that will:
- make a source distribution in the sub-folder =devel-build=;
- set up the company-clang options for emacs;
- install a pre-commit hook into the git repository.
** Everyone: configure, make and install
You can run:
#+BEGIN_SRC sh
./configure --help
#+END_SRC
to know what options are available. If you want more details, see
=INSTALL=.
* Let me know
I develop Tarot as a personal hobby. If you find it interesting, or
have bugs to submit, please let me know: =vivien@planete-kraus.eu=
......@@ -13,6 +13,7 @@ ln -s devel-build/.dir-locals.el ../.dir-locals.el || exit 1
make -j 16 distcheck || exit 1
rm -f ../.git/hooks/pre-commit.sh || exit 1
mkdir -p ../.git/hooks || exit 1
ln -s ../../hooks/pre-commit.sh ../.git/hooks/pre-commit || exit 1
chmod ugo+x ../.git/hooks/pre-commit || exit 1
......
......@@ -2,16 +2,10 @@
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.69])
AC_INIT([libtarot], [devel], [vivien@planete-kraus.eu])
AC_INIT([tarot], [devel], [vivien@planete-kraus.eu])
AC_SUBST([LIBTAROT_VERSION_INFO], [[0:0:0]])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_MACRO_DIRS([m4])
AC_ARG_ENABLE([indent],
AS_HELP_STRING([--enable-indent],
[use the indent program (for contributors) (default: if available)]))
AC_ARG_VAR([INDENT],
AS_HELP_STRING([indent program (optional, but strongly recommanded
for contributors)]))
# Checks for programs.
AC_PROG_CC
......@@ -19,6 +13,7 @@ AM_INIT_AUTOMAKE([subdir-objects])
AM_PROG_AR
LT_INIT
AX_INDENT
AX_ORGMODE
# Checks for libraries.
......@@ -30,5 +25,10 @@ AX_ASAN
# Checks for library functions.
AC_CONFIG_FILES([Makefile .dir-locals.el])
AC_CONFIG_FILES([
Makefile
src/Makefile
doc/Makefile
.dir-locals.el
])
AC_OUTPUT
2017-04-29 Vivien Kraus <vivien@planete-kraus.eu>
* tarot.org (Libtarot API): add a section about libtarot-hand.
2017-04-26 Vivien Kraus <vivien@planete-kraus.eu>
* prepare-emacs.el (ox-md): Require ox-md and ox-ascii.
* tarot.org: Update the manual to use the reentrant error
management.
2017-04-14 Vivien Kraus <vivien@planete-kraus.eu>
* tarot.org.in (printers): Make example tangle to source.
* Makefile.am (examples/name_the_card.c): Now tarot.org lives in
the build directory.
($(top_srcdir)/doc/tarot.texi): Explicitly move tarot.texi in
source directory after exporting.
* tarot.org.in: Rewrite to work with org 9.
2017-04-13 Vivien Kraus <vivien@planete-kraus.eu>
* Makefile.am: move examples to doc/examples/.
2017-04-12 Vivien Kraus <vivien@planete-kraus.eu>
* Makefile.am ($(top_srcdir)/doc/tarot.texi): The texi file
depends on the example to demonstrate it.
* prepare-emacs.el (custom-set-variables): Do not need to set up python.
* tarot.org: Switch from python to elisp for the hacks.
2017-04-11 Vivien Kraus <vivien@planete-kraus.eu>
* tarot.org: Explain name.
2017-04-10 Vivien Kraus <vivien@planete-kraus.eu>
* prepare-emacs.el (ox-texinfo): Do not load user conf in prepare-emacs.el.
* tarot.org: Add the section about the game rules.
info_TEXINFOS = tarot.texi
tarot_TEXINFOS = about.texi game.texi ai.texi invoking.texi \
output.texi conditions.texi index.texi \
game/cards.texi game/steps.texi fdl.texi \
game/steps/libtarot.texi game/steps/deal.texi game/steps/bids.texi \
game/steps/slam.texi game/steps/call.texi game/steps/discard.texi \
game/steps/handful.texi game/steps/tricks.texi game/steps/score.texi \
game/steps/libtarot/init_quit.texi game/steps/libtarot/error.texi \
game/steps/libtarot/game.texi
pkginfofiguresdir = $(infodir)/tarot-figures/
dist_pkginfofigures_DATA =
AM_MAKEINFOHTMLFLAGS = --css-ref=style.css
## style.css: https://bitbucket.org/sirgazil/texinfo-css
## We put it in a local rule, so that it is only installed if we
## install html, and not if we just install the binaries
install-html-local:
$(MKDIR_P) ${DESTDIR}${htmldir}/${PACKAGE}.html/tarot-figures && \
${INSTALL_DATA} ${top_srcdir}/doc/style.css ${DESTDIR}${htmldir}/${PACKAGE}.html/style.css
@node About tarot
@chapter About tarot
Tarot is a framework for playing the tarot card game. It may have had
an incentive to start after a school assignment (PE46, ECL 2016), but
it has been redesigned and rewritten since then.
@menu
* The name::
@end menu
@node The name
@section The name
Tarot stands for @emph{The Amazing Rules Of TAROT}, which is a recursive
acronym. However, recursive acronyms usually start with the
recursion, so let me call this a @emph{tail}-recursive acronym instead.
@node Artificial intelligence
@chapter Artificial intelligence
The AI works in two steps. First, @emph{impute} the cards of the
adversaries, and second, make the best choice on the most likely
imputation.
@menu
* Hand imputation:: How to impute and assess the likelihood of an imputation
@end menu
@c====================================================================
@node Hand imputation
@section Hand imputation
The imputation is a way to guess the unknown cards of the other
players.
When a player plays a card, the imputation gains information about the
game. For instance, when a player trumps, it means that she cannot
have any other card of the lead suit. Then, the imputation will
respect this while guessing the cards of the players.
Each @code{TarotGame} is in one of two states. Either it is not
imputed (i.e. client-side) and it can be imputed, or it is already
imputed (i.e. server-side) and all cards of all players are known.
@deftypefun {void} tarot_game_seed (TarotGame *restrict @var{game}, size_t @var{n_bytes}, const char *restrict @var{random_data})
Since the imputation is a randomized operation, the random seed needs
to be fixed early.
This function sets the random seed for @var{game}, using the random
data @var{random_data} of size @var{n_bytes} bytes.
@end deftypefun
The imputation works by giving the cards, one at a time, respecting
the game rules. If the rules cannot be satisfied, the previous card
is given to the next player and the imputation continues.
This algorithm gives quick results most of the time, but if it makes a
wrong guess early, it can hang for a potentially infinite time while
exploring impossible solutions. The solution is to stop searching
after a certain number of iterations, re-shuffle, and start again.
If the imputation fails, it means that either the algorithm has bad
luck, or someone has cheated.
@deftypefun {int} tarot_game_impute (TarotGame *restrict @var{game}, unsigned int @var{max_iter})
Explore the imputation in @var{game} for @var{max_iter} iterations
(try 100). Return 0 on success. If it does not succeed, you can
either try again (call this exact same function again), or call
@code{tarot_game_shuffle} and start again.
@end deftypefun
@deftypefun {void} tarot_game_shuffle (TarotGame *restrict @var{game})
Start another exploration in @var{game}.
@end deftypefun
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
This diff is collapsed.
@node The game
@chapter The game
The tarot game involves players, cards and steps. The goal is to take
as much points as possible with your team. Every player plays in turn
a card, and when all players have played the @emph{trik taker}
(@pxref{Tricks}) takes all points and a new trick starts with the
remaining cards.
There are different types of cards. Some will help you take a trick,
but without giving you many points. Other will add more points to the
trick, but without helping you much to take it. More details in
section @ref{The cards,3.2}.
But before the players start to play, some preliminary steps occur to
set up the teams.
@menu
* The cards::
* Game steps::
@end menu
@lowersections
@include game/cards.texi
@include game/steps.texi
@raisesections
@node The cards
@chapter The cards
@cindex card
@cindex number (card)
@cindex card number
@cindex suit (card)
@cindex card suit
The game has 78 cards. There are:
@itemize
@item
an excuse, which is a special card;
@item
77 other cards that can be decomposed into a @dfn{number} and a
@dfn{suit}.
@end itemize
@deftp {typedef} TarotCard
@var{TarotCard} is an alias for @strong{unsigned int}, to store the
78 cards from 0 to 77. There are constants for the @emph{oudlers}:
@itemize
@item
TAROT_PETIT: the code for the petit;
@deftypefun {TarotCard} tarot_petit ()
Return @code{TAROT_PETIT}.
@end deftypefun
@item
TAROT_TWENTYONE: the code for the 21;
@deftypefun {TarotCard} tarot_twentyone ()
Return @code{TAROT_TWENTYONE}.
@end deftypefun
@item
TAROT_EXCUSE: the code for the excuse.
@deftypefun {TarotCard} tarot_excuse ()
Return @code{TAROT_EXCUSE}.
@end deftypefun
@end itemize
It is perfectly safe to compare any card to @code{TAROT_EXCUSE} to
detect whether it is the excuse or not.
@end deftp
@cindex trumps
@cindex petit
@cindex the world
@cindex minor suit
@cindex ace
@cindex jack
@cindex knight
@cindex queen
@cindex king
There are five different suits:
@itemize
@item
the @dfn{trumps}, whose numbers range from one (the @dfn{petit}) to
twenty-one (the @dfn{twenty-one}) @footnote{These correspond to the
"major arcana" in divinatory tarot, however they do not represent the
same thing in the card game. The twenty-one is famously called ``the
world'' in divinatory tarot but not here.};
@item
the four traditional, @dfn{minor} suits, @dfn{hearts}, @dfn{clubs}, @dfn{diamonds},
@dfn{spades}, with the following @emph{numbers}:
@itemize
@item
the ace (one, @code{TAROT_ACE}), abbreviated @code{A};
@deftypefun {TarotNumber} tarot_ace ()
Return @code{TAROT_ACE}.
@end deftypefun
@item
the numbers from two to ten inclusive;
@item
the jack (eleven, @code{TAROT_JACK}), abbreviated @code{J};
@deftypefun {TarotNumber} tarot_jack ()
Return @code{TAROT_JACK}.
@end deftypefun
@item
the knight @footnote{This number does not exist in 54-card decks}
(twelve, @code{TAROT_KNIGHT}), abbreviated @code{C} @footnote
{@code{C} is the french capital letter of ``cavalier'' to avoid
confusions with the @emph{king}};
@deftypefun {TarotNumber} tarot_knight ()
Return @code{TAROT_KNIGHT}.
@end deftypefun
@item
the queen (thirteen, @code{TAROT_QUEEN}), abbreviated @code{Q};
@deftypefun {TarotNumber} tarot_queen ()
Return @code{TAROT_QUEEN}.
@end deftypefun
@item
the king (fourteen, @code{TAROT_KING}), abbreviated @code{K}.
@deftypefun {TarotNumber} tarot_king ()
Return @code{TAROT_KING}.
@end deftypefun
@end itemize
@end itemize
As we will see later (@pxref{Tricks}), the higher trumps are more
likely to take tricks, whereas the kings add most value to the tricks
(@pxref{Score}).
@deftp {enum} TarotSuit
An enumeration for all five suits, the trumps coming @strong{last}. Values are:
@itemize
@item
@code{TAROT_HEARTS}
@item
@code{TAROT_CLUBS}
@item
@code{TAROT_DIAMONDS}
@item
@code{TAROT_SPADES}
@item
@code{TAROT_TRUMPS}
@end itemize
The GObject enumeration type @code{TarotSuit} has values @code{HEARTS,
CLUBS, DIAMONDS, SPADES} and @code{TRUMPS}.
@end deftp
@deftp {typedef} TarotNumber
A descriptor for card numbers, starting at value 1 and @strong{not} at
0. For instance, the 1 of @code{TAROT_TRUMPS} is the
@code{TAROT_PETIT}. Some values are predefined:
@itemize
@item
@code{TAROT_ACE}
@item
@code{TAROT_JACK}
@item
@code{TAROT_KNIGHT}
@item
@code{TAROT_QUEEN}
@item
@code{TAROT_KING}
@end itemize
@end deftp
To switch from the card index to the pair (@emph{number},
@emph{suit}), you can use the following functions: