5 년 전 · 9c5893b1cb
--- a/Makefile.am
+++ b/Makefile.am
@@ -4,6 +4,7 @@
 # There is NO WARRANTY, to the extent permitted by law.

 # SUBDIRS = doc po
 SUBDIRS = doc
 AUTOMAKE_OPTIONS = subdir-objects
 dist_doc_DATA = README doc/blackjack.texi

--- a/README.md
+++ b/README.md
@@ -114,7 +114,7 @@ To play through a TCP socket, call `blackjack` within `netcat`. On one host, do

 ```
 rm -f /tmp/f; mkfifo /tmp/f
 cat /tmp/f | blackjack 2>&1 | nc -l 127.0.0.1 1234 > /tmp/f
 cat /tmp/f | blackjack  | nc -l 127.0.0.1 1234 > /tmp/f
 ```

 On the other one, connect to the first host on port 1234:
@@ -123,11 +123,7 @@ On the other one, connect to the first host on port 1234:
 nc host 1234
 ```

 # Licensing

 Libre Blackjack is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

 # A note on the C++ implemenation
 ## A note on the C++ implementation

 The first Libre Blackjack version (v0.1) was written in C. This version (v0.2) is a re-implementation of nearly the same functionality but written completely from scratch in C++. I am not a fan of C++ and still prefer old plain C for most of my programming projects, but for the particular case of Libre Blackjack these advantages of C++ over C ought to be noted:

@@ -138,14 +134,19 @@ The first Libre Blackjack version (v0.1) was written in C. This version (v0.2)
    - [Free Bet Blackjack](https://wizardofodds.com/games/free-bet-blackjack/)
    - [Blackjack Switch](https://wizardofodds.com/games/blackjack/switch/)
    
   or even the Spanish “Siete y medio” could be also implemented in the same framework.  
   or even the Spanish “Siete y medio” could be also implemented in the same framework (the card deck should also be changed though). But also playing variations like a dealer that exposes the hole card a certain amount of the time (say 1% or 2% of the hands) could also be studied by extending the base blackjack dealer class.

 * the private members of the C++ classes allow information to be hidden between the dealer and the player, so a far better separation of information can be achieved. This also prevents “cheating” in players by looking at information which is not available for them (such as the dealer’s hole card or the content of the shoe).
 
 * the virtual members of derived players and even be linked to other high-level programming languages parsers (such as Python or Julia) allowing to use the vast variety of AI/ML libraries available for these languages to implement advanced playing strategies.
 * the virtual members of derived players and even be linked to other high-level programming language parsers (such as Python or Julia) allowing to use the vast variety of AI/ML libraries available for these languages to implement advanced playing strategies.
 
 * the usage of STL containers, methods and algorithms allows for a faster and cleaner implementation of cards, hands, decks and shoes.

 # Licensing

 Libre Blackjack is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.


 # Further information

 Home page: <https://www.seamplex.com/blackjack>  
--- a/configure.ac
+++ b/configure.ac
@@ -32,5 +32,5 @@ cat << EOF > src/version-conf.h
 EOF

 #AC_CONFIG_FILES([Makefile doc/Makefile po/Makefile.in])
 AC_CONFIG_FILES([Makefile])
 AC_CONFIG_FILES([Makefile doc/Makefile])
 AC_OUTPUT
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -0,0 +1,10 @@
 # Copyright (C) 2016--2020 jeremy theler
 # This file is part of libreblackjack.
 # This file is free software: you are free to change and redistribute it.
 # There is NO WARRANTY, to the extent permitted by law.

 info_TEXINFOS = blackjack.texi
 doc_blackjack_TEXINFOS = fdl.texi

 CLEANFILES = *.aux *.cp *.cps *.fn *.ky *.log *.op *.pg *.toc *.tp *.vr
 DISTCLEANFILES = ${CLEANFILES}
--- a/doc/blackjack.md
+++ b/doc/blackjack.md
@@ -0,0 +1,186 @@
 ---
 title: Libre Blackjack
 subtitle:  A free blackjack back end
 desc: a completely free-as-in-freedom blackjack engine designed to study and analyze the game statistics using different playing strategies ranging from simple card counting up to other complex algorithms based on artificial intelligence.
 author: Jeremy Theler
 date: December 20, 2020
 version: libreblackjackversion
 infoname: blackjack
 lang: en-US
 ---

 # Overview

 include(overview.md)

 # Running `blackjack`

 ## Invocation

 The format for running the `blackjack` program is:

 ```
 blackjack [options] [path_to_conf_file]
 ```

 If no configuration file is given, a file named `blackjack.conf` in the current directory is used, provided it exists.
 With no options and no configuration file, `blackjack` starts in interactive mode and it is ready to start a blackjack game.

 The `blackjack` executable supports the following options:


 include(help.md)

 All the options which can be given in the configuration file can be passed as a command-line argument. For example, running

 ```ini
 blackjack --decks=4 --no_insurance=true
 ```

 is equivalent to using a configuration file with

 ```
 decks = 4
 no_insurance = true
 ```


 ## Interactive game

 If `blackjack` is attached to an interactive TTY (i.e. neither the standard input nor outputs are redirected), an interactive game is triggered. First thing the program will do is to ask for a bet:

 ```
 LibreBlackjack v0.2+Δ
 a free & open blackjack engine


 Starting new hand #1 with bankroll 0
 <-- Bet?
 > 
 ```

 So the user should enter a number, say "1" and then press Enter and then a game will be dealt:

 ```
 Player's card is Q♥
 Dealer's up card is 10♠
 Player's card is Q♣
 Dealer's hole card is dealt
 No blackjacks
 -- Dealer's hand:  --------
 _____    _____   
 |10   |  |#####|  
 |     |  |#####|  
 |  ♠  |  |#####|  
 |     |  |#####|  
 |___10|  |#####|  
    Value: 10
 -- Player's hand --------
 _____    _____   
 |Q    |  |Q    |  
 |     |  |     |  
 |  ♥  |  |  ♣  |  
 |     |  |     |  
 |____Q|  |____Q|  
    Value: 20
 <-- Play? 20 10
 > 
 ```

 A flat-betting game can be played by passing `--flat_bet=true` through the command line.


 # Commands

 The dealer (he) and the player (she) “talk” through commands, which are ASCII strings sent through any of the different IPC mechanisms discussed in [Automated playing through IPC]. In the most basic case, a human player reads commands from the dealer from `blackjack`’s  standard output and writes her commands into the dealer’s standard input. Those commands from the dealer that require a particular action from the player end with a quotation sign such as `bet?`, `insurance?` or `play?`.

 All numerical values such as hand totals or bankrolls are given as decimal ASCII strings.

 ## From the dealer to the player


 ## From the player to the dealer

 The following commands are available for the player for playing her hand.

 include(input-particular.md)


 The following are general commands in the sense that they can be sent from the player to the dealer at any moment of the game.

 include(input-general.md)





 # Configuration file

 Libre Blackjacks reads a configuration file that contains
 
 * settings about the rules of the game
    - number of decks,
    - whether if the dealer has to hit soft seventeen or not,
    - blackjack payout,
    - maximum bet allowed,
    - etc...
 * how the player is supposed to play
    - number of hands
    - whether a flat or variable bet is going to be used,
    - etc...
 * if there are any particular shoe arrangement, i.e. a predefined set of cards dealt in a certain order for instance to play one million hands of a sixteen against a dealer’s ten
 * what kind of information is shown in the interactive session
    - if ASCII-art cards are supposed to be shown,
    - a real-time delay to make the game smoother,
    - etc.
 * how the automated player communicates with the dealer
    - using standard input/output,
    - FIFO named pipes,
    - POSIX message queues,
    - POSIX shared memory,
    - etc...
 
 The location of the configuration file can be given in the command line. If none is provided, a file named `blackjack.conf` in the current directory is used. If such file does not exists, the defaults values of each variable are used. Individual variables can be set from the command line by passing one or more times the option `--`configuration_variable`[=`*value*`]` in the [invocation].

 Comments can be inserted using either a hash `#` or a colon `;`. The following configuration file is the default provided in the main distribution tarball:

 ```ini
 # uncomment the following line to arrange cards
 # arranged_cards = 1 5 14 9 27

 flat_bet = 1       # do not ask for bets
 no_insurance = 1   # do not ask for insurance
 decks = 1          # number of decks, negative means infinite
 ```

 ## Variables and values

 include(conf.md)




 ## Dumb internal player



 # Example automated players

 The directory `players` contains a few examples of automated player, which are discussed in the following sections. A script `check.sh` runs some of them and compares the expected value of the bankroll relative to the number of hands which each player obtains with the theoretical expected value (according to the game rules and player’s strategy) within an  allowed statistical uncertainty. This scripts writes the following table (actual values might vary depending on the random nature of the game):

 include(../players/check.md)

 The columns are

 1. Case name, as discussed below.
 2. Expected theoretical result in absolute units (i.e. -0.004 means -0.4%)
 3. Actual result obtained by Libre Blackjack in absolute units
 4. Estimated error equal to the standard deviation of the result
 5. Number of played hands per second
 6. Whether the result coincides or not with the theoretical value


 include(players.md)



--- a/doc/blackjack.texi
+++ b/doc/blackjack.texi
--- a/doc/conf.md
+++ b/doc/conf.md
--- a/doc/fdl.texi
+++ b/doc/fdl.texi
@@ -0,0 +1,505 @@
@c The GNU Free Documentation License.
@center Version 1.3, 3 November 2008

@c This file is intended to be included within another document,
@c hence no sectioning command or @node.

@display
 Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
@uref{http://fsf.org/}

 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.
@end display

@enumerate 0
@item
 PREAMBLE

 The purpose of this License is to make a manual, textbook, or other
 functional and useful document @dfn{free} in the sense of freedom: to
 assure everyone the effective freedom to copy and redistribute it,
 with or without modifying it, either commercially or noncommercially.
 Secondarily, this License preserves for the author and publisher a way
 to get credit for their work, while not being considered responsible
 for modifications made by others.

 This License is a kind of ``copyleft'', which means that derivative
 works of the document must themselves be free in the same sense.  It
 complements the GNU General Public License, which is a copyleft
 license designed for free software.

 We have designed this License in order to use it for manuals for free
 software, because free software needs free documentation: a free
 program should come with manuals providing the same freedoms that the
 software does.  But this License is not limited to software manuals;
 it can be used for any textual work, regardless of subject matter or
 whether it is published as a printed book.  We recommend this License
 principally for works whose purpose is instruction or reference.

@item
 APPLICABILITY AND DEFINITIONS

 This License applies to any manual or other work, in any medium, that
 contains a notice placed by the copyright holder saying it can be
 distributed under the terms of this License.  Such a notice grants a
 world-wide, royalty-free license, unlimited in duration, to use that
 work under the conditions stated herein.  The ``Document'', below,
 refers to any such manual or work.  Any member of the public is a
 licensee, and is addressed as ``you''.  You accept the license if you
 copy, modify or distribute the work in a way requiring permission
 under copyright law.

 A ``Modified Version'' of the Document means any work containing the
 Document or a portion of it, either copied verbatim, or with
 modifications and/or translated into another language.

 A ``Secondary Section'' is a named appendix or a front-matter section
 of the Document that deals exclusively with the relationship of the
 publishers or authors of the Document to the Document's overall
 subject (or to related matters) and contains nothing that could fall
 directly within that overall subject.  (Thus, if the Document is in
 part a textbook of mathematics, a Secondary Section may not explain
 any mathematics.)  The relationship could be a matter of historical
 connection with the subject or with related matters, or of legal,
 commercial, philosophical, ethical or political position regarding
 them.

 The ``Invariant Sections'' are certain Secondary Sections whose titles
 are designated, as being those of Invariant Sections, in the notice
 that says that the Document is released under this License.  If a
 section does not fit the above definition of Secondary then it is not
 allowed to be designated as Invariant.  The Document may contain zero
 Invariant Sections.  If the Document does not identify any Invariant
 Sections then there are none.

 The ``Cover Texts'' are certain short passages of text that are listed,
 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
 the Document is released under this License.  A Front-Cover Text may
 be at most 5 words, and a Back-Cover Text may be at most 25 words.

 A ``Transparent'' copy of the Document means a machine-readable copy,
 represented in a format whose specification is available to the
 general public, that is suitable for revising the document
 straightforwardly with generic text editors or (for images composed of
 pixels) generic paint programs or (for drawings) some widely available
 drawing editor, and that is suitable for input to text formatters or
 for automatic translation to a variety of formats suitable for input
 to text formatters.  A copy made in an otherwise Transparent file
 format whose markup, or absence of markup, has been arranged to thwart
 or discourage subsequent modification by readers is not Transparent.
 An image format is not Transparent if used for any substantial amount
 of text.  A copy that is not ``Transparent'' is called ``Opaque''.

 Examples of suitable formats for Transparent copies include plain
 ASCII without markup, Texinfo input format, La@TeX{} input
 format, SGML or XML using a publicly available
 DTD, and standard-conforming simple HTML,
 PostScript or PDF designed for human modification.  Examples
 of transparent image formats include PNG, XCF and
 JPG@.  Opaque formats include proprietary formats that can be
 read and edited only by proprietary word processors, SGML or
 XML for which the DTD and/or processing tools are
 not generally available, and the machine-generated HTML,
 PostScript or PDF produced by some word processors for
 output purposes only.

 The ``Title Page'' means, for a printed book, the title page itself,
 plus such following pages as are needed to hold, legibly, the material
 this License requires to appear in the title page.  For works in
 formats which do not have any title page as such, ``Title Page'' means
 the text near the most prominent appearance of the work's title,
 preceding the beginning of the body of the text.

 The ``publisher'' means any person or entity that distributes copies
 of the Document to the public.

 A section ``Entitled XYZ'' means a named subunit of the Document whose
 title either is precisely XYZ or contains XYZ in parentheses following
 text that translates XYZ in another language.  (Here XYZ stands for a
 specific section name mentioned below, such as ``Acknowledgements'',
 ``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
 of such a section when you modify the Document means that it remains a
 section ``Entitled XYZ'' according to this definition.

 The Document may include Warranty Disclaimers next to the notice which
 states that this License applies to the Document.  These Warranty
 Disclaimers are considered to be included by reference in this
 License, but only as regards disclaiming warranties: any other
 implication that these Warranty Disclaimers may have is void and has
 no effect on the meaning of this License.

@item
 VERBATIM COPYING

 You may copy and distribute the Document in any medium, either
 commercially or noncommercially, provided that this License, the
 copyright notices, and the license notice saying this License applies
 to the Document are reproduced in all copies, and that you add no other
 conditions whatsoever to those of this License.  You may not use
 technical measures to obstruct or control the reading or further
 copying of the copies you make or distribute.  However, you may accept
 compensation in exchange for copies.  If you distribute a large enough
 number of copies you must also follow the conditions in section 3.

 You may also lend copies, under the same conditions stated above, and
 you may publicly display copies.

@item
 COPYING IN QUANTITY

 If you publish printed copies (or copies in media that commonly have
 printed covers) of the Document, numbering more than 100, and the
 Document's license notice requires Cover Texts, you must enclose the
 copies in covers that carry, clearly and legibly, all these Cover
 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
 the back cover.  Both covers must also clearly and legibly identify
 you as the publisher of these copies.  The front cover must present
 the full title with all words of the title equally prominent and
 visible.  You may add other material on the covers in addition.
 Copying with changes limited to the covers, as long as they preserve
 the title of the Document and satisfy these conditions, can be treated
 as verbatim copying in other respects.

 If the required texts for either cover are too voluminous to fit
 legibly, you should put the first ones listed (as many as fit
 reasonably) on the actual cover, and continue the rest onto adjacent
 pages.

 If you publish or distribute Opaque copies of the Document numbering
 more than 100, you must either include a machine-readable Transparent
 copy along with each Opaque copy, or state in or with each Opaque copy
 a computer-network location from which the general network-using
 public has access to download using public-standard network protocols
 a complete Transparent copy of the Document, free of added material.
 If you use the latter option, you must take reasonably prudent steps,
 when you begin distribution of Opaque copies in quantity, to ensure
 that this Transparent copy will remain thus accessible at the stated
 location until at least one year after the last time you distribute an
 Opaque copy (directly or through your agents or retailers) of that
 edition to the public.

 It is requested, but not required, that you contact the authors of the
 Document well before redistributing any large number of copies, to give
 them a chance to provide you with an updated version of the Document.

@item
 MODIFICATIONS

 You may copy and distribute a Modified Version of the Document under
 the conditions of sections 2 and 3 above, provided that you release
 the Modified Version under precisely this License, with the Modified
 Version filling the role of the Document, thus licensing distribution
 and modification of the Modified Version to whoever possesses a copy
 of it.  In addition, you must do these things in the Modified Version:

@enumerate A
@item
 Use in the Title Page (and on the covers, if any) a title distinct
 from that of the Document, and from those of previous versions
 (which should, if there were any, be listed in the History section
 of the Document).  You may use the same title as a previous version
 if the original publisher of that version gives permission.

@item
 List on the Title Page, as authors, one or more persons or entities
 responsible for authorship of the modifications in the Modified
 Version, together with at least five of the principal authors of the
 Document (all of its principal authors, if it has fewer than five),
 unless they release you from this requirement.

@item
 State on the Title page the name of the publisher of the
 Modified Version, as the publisher.

@item
 Preserve all the copyright notices of the Document.

@item
 Add an appropriate copyright notice for your modifications
 adjacent to the other copyright notices.

@item
 Include, immediately after the copyright notices, a license notice
 giving the public permission to use the Modified Version under the
 terms of this License, in the form shown in the Addendum below.

@item
 Preserve in that license notice the full lists of Invariant Sections
 and required Cover Texts given in the Document's license notice.

@item
 Include an unaltered copy of this License.

@item
 Preserve the section Entitled ``History'', Preserve its Title, and add
 to it an item stating at least the title, year, new authors, and
 publisher of the Modified Version as given on the Title Page.  If
 there is no section Entitled ``History'' in the Document, create one
 stating the title, year, authors, and publisher of the Document as
 given on its Title Page, then add an item describing the Modified
 Version as stated in the previous sentence.

@item
 Preserve the network location, if any, given in the Document for
 public access to a Transparent copy of the Document, and likewise
 the network locations given in the Document for previous versions
 it was based on.  These may be placed in the ``History'' section.
 You may omit a network location for a work that was published at
 least four years before the Document itself, or if the original
 publisher of the version it refers to gives permission.

@item
 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
 the Title of the section, and preserve in the section all the
 substance and tone of each of the contributor acknowledgements and/or
 dedications given therein.

@item
 Preserve all the Invariant Sections of the Document,
 unaltered in their text and in their titles.  Section numbers
 or the equivalent are not considered part of the section titles.

@item
 Delete any section Entitled ``Endorsements''.  Such a section
 may not be included in the Modified Version.

@item
 Do not retitle any existing section to be Entitled ``Endorsements'' or
 to conflict in title with any Invariant Section.

@item
 Preserve any Warranty Disclaimers.
@end enumerate

 If the Modified Version includes new front-matter sections or
 appendices that qualify as Secondary Sections and contain no material
 copied from the Document, you may at your option designate some or all
 of these sections as invariant.  To do this, add their titles to the
 list of Invariant Sections in the Modified Version's license notice.
 These titles must be distinct from any other section titles.

 You may add a section Entitled ``Endorsements'', provided it contains
 nothing but endorsements of your Modified Version by various
 parties---for example, statements of peer review or that the text has
 been approved by an organization as the authoritative definition of a
 standard.

 You may add a passage of up to five words as a Front-Cover Text, and a
 passage of up to 25 words as a Back-Cover Text, to the end of the list
 of Cover Texts in the Modified Version.  Only one passage of
 Front-Cover Text and one of Back-Cover Text may be added by (or
 through arrangements made by) any one entity.  If the Document already
 includes a cover text for the same cover, previously added by you or
 by arrangement made by the same entity you are acting on behalf of,
 you may not add another; but you may replace the old one, on explicit
 permission from the previous publisher that added the old one.

 The author(s) and publisher(s) of the Document do not by this License
 give permission to use their names for publicity for or to assert or
 imply endorsement of any Modified Version.

@item
 COMBINING DOCUMENTS

 You may combine the Document with other documents released under this
 License, under the terms defined in section 4 above for modified
 versions, provided that you include in the combination all of the
 Invariant Sections of all of the original documents, unmodified, and
 list them all as Invariant Sections of your combined work in its
 license notice, and that you preserve all their Warranty Disclaimers.

 The combined work need only contain one copy of this License, and
 multiple identical Invariant Sections may be replaced with a single
 copy.  If there are multiple Invariant Sections with the same name but
 different contents, make the title of each such section unique by
 adding at the end of it, in parentheses, the name of the original
 author or publisher of that section if known, or else a unique number.
 Make the same adjustment to the section titles in the list of
 Invariant Sections in the license notice of the combined work.

 In the combination, you must combine any sections Entitled ``History''
 in the various original documents, forming one section Entitled
 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
 and any sections Entitled ``Dedications''.  You must delete all
 sections Entitled ``Endorsements.''

@item
 COLLECTIONS OF DOCUMENTS

 You may make a collection consisting of the Document and other documents
 released under this License, and replace the individual copies of this
 License in the various documents with a single copy that is included in
 the collection, provided that you follow the rules of this License for
 verbatim copying of each of the documents in all other respects.

 You may extract a single document from such a collection, and distribute
 it individually under this License, provided you insert a copy of this
 License into the extracted document, and follow this License in all
 other respects regarding verbatim copying of that document.

@item
 AGGREGATION WITH INDEPENDENT WORKS

 A compilation of the Document or its derivatives with other separate
 and independent documents or works, in or on a volume of a storage or
 distribution medium, is called an ``aggregate'' if the copyright
 resulting from the compilation is not used to limit the legal rights
 of the compilation's users beyond what the individual works permit.
 When the Document is included in an aggregate, this License does not
 apply to the other works in the aggregate which are not themselves
 derivative works of the Document.

 If the Cover Text requirement of section 3 is applicable to these
 copies of the Document, then if the Document is less than one half of
 the entire aggregate, the Document's Cover Texts may be placed on
 covers that bracket the Document within the aggregate, or the
 electronic equivalent of covers if the Document is in electronic form.
 Otherwise they must appear on printed covers that bracket the whole
 aggregate.

@item
 TRANSLATION

 Translation is considered a kind of modification, so you may
 distribute translations of the Document under the terms of section 4.
 Replacing Invariant Sections with translations requires special
 permission from their copyright holders, but you may include
 translations of some or all Invariant Sections in addition to the
 original versions of these Invariant Sections.  You may include a
 translation of this License, and all the license notices in the
 Document, and any Warranty Disclaimers, provided that you also include
 the original English version of this License and the original versions
 of those notices and disclaimers.  In case of a disagreement between
 the translation and the original version of this License or a notice
 or disclaimer, the original version will prevail.

 If a section in the Document is Entitled ``Acknowledgements'',
 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
 its Title (section 1) will typically require changing the actual
 title.

@item
 TERMINATION

 You may not copy, modify, sublicense, or distribute the Document
 except as expressly provided under this License.  Any attempt
 otherwise to copy, modify, sublicense, or distribute it is void, and
 will automatically terminate your rights under this License.

 However, if you cease all violation of this License, then your license
 from a particular copyright holder is reinstated (a) provisionally,
 unless and until the copyright holder explicitly and finally
 terminates your license, and (b) permanently, if the copyright holder
 fails to notify you of the violation by some reasonable means prior to
 60 days after the cessation.

 Moreover, your license from a particular copyright holder is
 reinstated permanently if the copyright holder notifies you of the
 violation by some reasonable means, this is the first time you have
 received notice of violation of this License (for any work) from that
 copyright holder, and you cure the violation prior to 30 days after
 your receipt of the notice.

 Termination of your rights under this section does not terminate the
 licenses of parties who have received copies or rights from you under
 this License.  If your rights have been terminated and not permanently
 reinstated, receipt of a copy of some or all of the same material does
 not give you any rights to use it.

@item
 FUTURE REVISIONS OF THIS LICENSE

 The Free Software Foundation may publish new, revised versions
 of the GNU Free Documentation License from time to time.  Such new
 versions will be similar in spirit to the present version, but may
 differ in detail to address new problems or concerns.  See
@uref{http://www.gnu.org/copyleft/}.

 Each version of the License is given a distinguishing version number.
 If the Document specifies that a particular numbered version of this
 License ``or any later version'' applies to it, you have the option of
 following the terms and conditions either of that specified version or
 of any later version that has been published (not as a draft) by the
 Free Software Foundation.  If the Document does not specify a version
 number of this License, you may choose any version ever published (not
 as a draft) by the Free Software Foundation.  If the Document
 specifies that a proxy can decide which future versions of this
 License can be used, that proxy's public statement of acceptance of a
 version permanently authorizes you to choose that version for the
 Document.

@item
 RELICENSING

 ``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
 World Wide Web server that publishes copyrightable works and also
 provides prominent facilities for anybody to edit those works.  A
 public wiki that anybody can edit is an example of such a server.  A
 ``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
 site means any set of copyrightable works thus published on the MMC
 site.

 ``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
 license published by Creative Commons Corporation, a not-for-profit
 corporation with a principal place of business in San Francisco,
 California, as well as future copyleft versions of that license
 published by that same organization.

 ``Incorporate'' means to publish or republish a Document, in whole or
 in part, as part of another Document.

 An MMC is ``eligible for relicensing'' if it is licensed under this
 License, and if all works that were first published under this License
 somewhere other than this MMC, and subsequently incorporated in whole
 or in part into the MMC, (1) had no cover texts or invariant sections,
 and (2) were thus incorporated prior to November 1, 2008.

 The operator of an MMC Site may republish an MMC contained in the site
 under CC-BY-SA on the same site at any time before August 1, 2009,
 provided the MMC is eligible for relicensing.

@end enumerate

@page
@heading ADDENDUM: How to use this License for your documents

 To use this License in a document you have written, include a copy of
 the License in the document and put the following copyright and
 license notices just after the title page:

@smallexample
@group
  Copyright (C)  @var{year}  @var{your name}.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
@end group
@end smallexample

 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
 replace the ``with@dots{}Texts.''@: line with this:

@smallexample
@group
    with the Invariant Sections being @var{list their titles}, with
    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
    being @var{list}.
@end group
@end smallexample

 If you have Invariant Sections without Cover Texts, or some other
 combination of the three, merge those two alternatives to suit the
 situation.

 If your document contains nontrivial examples of program code, we
 recommend releasing these examples in parallel under your choice of
 free software license, such as the GNU General Public License,
 to permit their use in free software.

@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
--- a/doc/header.m4
+++ b/doc/header.m4
@@ -0,0 +1,4 @@
 divert(-1)
 changequote([!,!])
 changecom([!/*!], [!*/!])
 divert(0)dnl
--- a/doc/help.md
+++ b/doc/help.md
@@ -0,0 +1 @@

--- a/doc/help.sh
+++ b/doc/help.sh
@@ -0,0 +1,25 @@
 #!/bin/bash

 src="main"
 tag="op"
 dir="../src"

 kws=`grep "///${tag}+" ${dir}/${src}.cpp | awk '{print $1}' | awk -F+ '{print $2}' | uniq` 

 for kw in ${kws}; do

  # option como definition list
  grep "///${tag}+${kw}+option" ${dir}/${src}.cpp | cut -d" " -f2-
  echo  

  # detailed description
  # el cut saca los tags especiales
  # el segundo se es para poder poner links como https:/\/ (sin la barra del medio gcc piensa que es un comentario)
  echo -n ':    '
  grep "///${tag}+${kw}+desc" ${dir}/${src}.cpp | cut -d" " -f2- | sed 's_/\\/_//_'
  echo  
  echo  
  
 done

 echo 
--- a/doc/help.txt
+++ b/doc/help.txt
@@ -0,0 +1 @@

--- a/doc/input-general.md
+++ b/doc/input-general.md
--- a/doc/input-particular.md
+++ b/doc/input-particular.md
--- a/doc/md2texi.sh
+++ b/doc/md2texi.sh
@@ -0,0 +1,33 @@
 if [ -z "$(which pandoc)" ]; then 
 echo "error: pandoc not installed"
 exit 1
 fi


 rm -f players.md
 for i in $(cat players); do
  echo $i
 #   grep 'define(case_title' ../players/${i}/README.m4 >> players.md
 #   awk '/> Difficulty.*/{t=1}t' ../players/${i}/README.m4 | grep -v Difficulty >> players.md
  sed 's/title:/title_case:/' ../players/${i}/README.md |\
    grep -v ':::' |\
    grep -v '> Difficulty:' |\
    grep -v 'Index' |\
    grep -vw '\-\-\-\-\-\-\-' |\
    pandoc --shift-heading-level-by=1 --markdown-headings=atx -t markdown >> players.md
  echo >> players.md
  echo >> players.md
 done

 ./help.sh > help.md
 # ./reference.sh bjinit va > conf.md

 # ./reference.sh dealer ig > input-general.md
 # ./reference.sh dealer ip > input-particular.md

 pandoc help.md -t plain > help.txt

 m4 ../version.m4 header.m4 blackjack.md | pandoc --toc --template template.texi -o blackjack.texi

 # m4 header.m4 blackjack.md > tmp.md
 # pandoc tmp.md --toc --template template.texi -o blackjack.texi
--- a/doc/overview.md
+++ b/doc/overview.md
@@ -0,0 +1,60 @@
 > A [free](https://www.gnu.org/philosophy/free-sw.html) [Blackjack](https://en.wikipedia.org/wiki/Blackjack) back end inspired by [GNU Chess](https://www.gnu.org/software/chess/).

 [Libre Blackjack](https://www.seamplex.com/blackjack) is a blackjack engine that emulates a dealer, deals (digital) cards and understands plain-text commands such as `hit` or `stand`. The basic idea is that one or more players can talk to Libre Blackjack either in an interactive or in an automated way through
 
 * the standard input and/or output (optionally using named pipes or TCP (web)sockets with `netcat` or `gwsocket`), or
 * C++ methods (optionally loaded at runtime from shared objects TBD).
  
 These players can be actual human players playing in real-time through a front end (a GUI application, a web-based interface, a mobile app, etc.) or robots that implement a certain betting and playing strategy playing (i.e. card counting) as fast as possible to study and analyze game statistics. There is an internal player that reads the strategy from a text file and plays accordingly. It can also be used to play interactive [ASCII blackjack].


 ## Why

 :::{.alert .alert-light}
 > “I am often surprised that when people drive down two-lane roads, they will trust complete strangers in the oncoming lane not to swerve into their lane causing a head-on collision; but they will not trust mathematicians to create the correct strategy for Blackjack.”
 >
 > [Norman Wattenberger, Modern Blackjack, 2009]{.blockquote-footer}
 :::

 With Libre Blackjack you do not have to trust other people anymore. You have a free blackjack engine which you can

 0. run as you wish, to see the results of billions of blackjack hands,
 1. study to see how it works and change it if you do not like it,
 2. share it with your friends and colleagues, and
 3. distribute copies of your modified versions.

 If you do not know how to program, you have the _freedom_ to hire a programmer to do it for you. That is why [Libre Blackjack](https://www.seamplex.com/blackjack) is [free software](https://www.gnu.org/philosophy/free-sw.html).


 ## How 

 Once you trust the blackjack engine is fair, you can model and simulate any blackjack situation you want, playing millions of times a certain hand (say a sixteen against a ten) in different ways (say hitting or standing) to obtain you own conclusions. You can even build  the [basic strategy charts](https://wizardofodds.com/games/blackjack/strategy/4-decks/) from scratch to convince yourself there is no [flaw](https://wizardofodds.com/ask-the-wizard/blackjack/).

 The main objective is research and optimization of playing and betting strategies depending on

 * particular table rules (number of decks, hit on soft 17, double after split, etc.), 
 * card counting strategies 
 * risk of ruin
 * removal of cards
 * arranged shoes
 
 These automatic players can range from simple no-bust or mimic-the-dealer hitters or standers, up to neural-networks trained players taking into account every card being dealt passing through basic strategy modified by traditional card counting mechanisms.

 ## A note on the C++ implementation

 The first Libre Blackjack version (v0.1) was written in C. This version (v0.2) is a re-implementation of nearly the same functionality but written completely from scratch in C++. I am not a fan of C++ and still prefer old plain C for most of my programming projects, but for the particular case of Libre Blackjack these advantages of C++ over C ought to be noted:

 * the inheritance mechanisms of C++ and virtual methods allows to have generic dealer and player classes from which particular games (dealers) and strategies (players) can be instantiated. This way, Blackjack variations like 
 
    - [Spanish 21](https://wizardofodds.com/games/spanish-21/)
    - [Down under Blackjack](https://wizardofodds.com/games/down-under-blackjack/)
    - [Free Bet Blackjack](https://wizardofodds.com/games/free-bet-blackjack/)
    - [Blackjack Switch](https://wizardofodds.com/games/blackjack/switch/)
    
   or even the Spanish “Siete y medio” could be also implemented in the same framework (the card deck should also be changed though). But also playing variations like a dealer that exposes the hole card a certain amount of the time (say 1% or 2% of the hands) could also be studied by extending the base blackjack dealer class.

 * the private members of the C++ classes allow information to be hidden between the dealer and the player, so a far better separation of information can be achieved. This also prevents “cheating” in players by looking at information which is not available for them (such as the dealer’s hole card or the content of the shoe).
 
 * the virtual members of derived players and even be linked to other high-level programming language parsers (such as Python or Julia) allowing to use the vast variety of AI/ML libraries available for these languages to implement advanced playing strategies.
 
 * the usage of STL containers, methods and algorithms allows for a faster and cleaner implementation of cards, hands, decks and shoes.
--- a/doc/players
+++ b/doc/players
@@ -0,0 +1,5 @@
 00-internal
 02-always-stand
 05-no-bust
 08-mimic-the-dealer
 20-basic-strategy
--- a/doc/players.md
+++ b/doc/players.md
--- a/doc/template.texi
+++ b/doc/template.texi
@@ -0,0 +1,64 @@
 \input texinfo @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
 $for(header-includes)$
 $header-includes$
 $endfor$

@setfilename $infoname$.info
@set UPDATED $date$
@set VERSION $version$

@copying
 This manual is for LibreBlackjack (version @value{VERSION}, @value{UPDATED}),
 which is $desc$.

 Copyright @copyright{} 2016-2020 Jeremy Theler.

@quotation
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled
 ``GNU Free Documentation License''.
@end quotation
@end copying

 $if(strikeout)$
@macro textstrikeout{text}
 ~~\text\~~
@end macro
 $endif$
@ifnottex
@paragraphindent 0
@end ifnottex
 $if(titlepage)$
@titlepage
@title $title$
@subtitle $subtitle$, $version$
 $for(author)$
@author $author$
 $endfor$
 $if(date)$
 $date$
@page
@vskip 0pt plus 1filll
@insertcopying
 $endif$
@end titlepage

 $endif$
 $for(include-before)$
 $include-before$
 $endfor$
 $if(toc)$
@contents

 $endif$
 $body$
 $for(include-after)$
 $include-after$
 $endfor$

@bye
--- a/players/00-internal/README.md
+++ b/players/00-internal/README.md
@@ -17,46 +17,16 @@ and you will get the following report with the results of playing one million ha

 ```yaml
 ---
 rules:
  decks:                  6
  hands:                  1e+06
  hit_soft_17:            1
  double_after_split:     1
  blackjack_pays:         1.5
  rng_seed:               -421186149
  number_of_burnt_cards:  0
  no_negative_bankroll:   0
  max_bet:                0
  penetration:            0.75
  penetration_sigma:      0.05
 cpu:
  user:             1.88959
  system:           0.32027
  wall:             2.20904
  second_per_hand:  2.2e-06
  hands_per_second: 4.5e+05
 player: 
  wins:               0.445075
  pushes:             0.087039
  losses:             0.492821
  dealer_blackjacks:  0.047582
  player_blackjacks:  0.047375
  dealer_busts:       0.23537
  player_busts:       0.160637
  doubled_hands:      0.107207
  doubled_wins:       0.0613
  insured_hands:      0
  insured_wins:       0
  number_of_hands:    1e+06
  number_of_shuffles: 23215
  total_money_waged:  1.23935e+06
  worst_bankroll:     -7212.5
  final_bankroll:     -7111
  return:             -0.007111
  variance:            1.32892
  deviation:           1.15279
  error:               0.00115279
  result:             "(-0.7 ± 0.2) %"
 result: "(-0.7 ± 0.3) %"
 mean: -0.006799
 error: 0.00348707
 hands: 1e+06
 bankroll: -6799
 bustsPlayer: 0.139358
 bustsDealer: 0.239722
 wins: 0.448034
 pushes: 0.085913
 losses: 0.495532
 ...

 ```
--- a/players/02-always-stand/README.md
+++ b/players/02-always-stand/README.md
@@ -10,7 +10,7 @@ title: Always stand
 To play Blackjack as an “always-stander” run the following command:

 ```terminal
 yes stand | blackjack -n1e5 --flat_bet --no_insurance > /dev/null
 yes stand | blackjack -n1e5 --flat_bet=true --no_insurance=true > /dev/null
 ```

 The UNIX command `yes stand` writes the string “stand” repeteadly to the standard output, which is piped to the executable `blackjack` (assumed to be installed system-wide). The arguments tell Libre Blackjack to play one hundred thousand hands (`-n1e5`) using a flat bet (`flat_bet`, it defaults to a unit bet in each hand) and without asking for insurance if the dealer shows an ace (`no_insurance`). As there is no `blackjack.conf` file, the rules are---as expected---the default ones (see the documentation for details).
@@ -25,46 +25,16 @@ This example is only one-way (i.e. the player ignores what the dealer says) so i

 ```yaml
 ---
 rules:
  decks:                  6
  hands:                  100000
  hit_soft_17:            1
  double_after_split:     1
  blackjack_pays:         1.5
  rng_seed:               -2067081387
  number_of_burnt_cards:  0
  no_negative_bankroll:   0
  max_bet:                0
  penetration:            0.75
  penetration_sigma:      0.05
 cpu:
  user:             0.238384
  system:           0.226465
  wall:             0.462519
  second_per_hand:  4.6e-06
  hands_per_second: 2.2e+05
 player: 
  wins:               0.38547
  pushes:             0.04744
  losses:             0.56709
  dealer_blackjacks:  0.04749
  player_blackjacks:  0.04803
  dealer_busts:       0.27168
  player_busts:       0
  doubled_hands:      0
  doubled_wins:       0
  insured_hands:      0
  insured_wins:       0
  number_of_hands:    100000
  number_of_shuffles: 2070
  total_money_waged:  100000
  worst_bankroll:     -15870.5
  final_bankroll:     -15868
  return:             -0.15868
  variance:            0.984727
  deviation:           0.992334
  error:               0.00313804
  result:             "(-15.9 ± 0.6) %"
 result: "(-15.8 ± 0.9) %"
 mean: -0.157675
 error: 0.00940803
 hands: 100000
 bankroll: -15767.5
 bustsPlayer: 0
 bustsDealer: 0.27344
 wins: 0.38585
 pushes: 0.04807
 losses: 0.56608
 ...

 ```
--- a/players/02-always-stand/run.sh
+++ b/players/02-always-stand/run.sh
@@ -1 +1 @@
 yes stand | blackjack -n1e5 --flat_bet --no_insurance > /dev/null
 yes stand | blackjack -n1e5 --flat_bet=true --no_insurance=true > /dev/null
--- a/players/05-no-bust/README.md
+++ b/players/05-no-bust/README.md
@@ -16,9 +16,7 @@ mkfifo fifo
 Then we execute `blackjack`, piping its output to the player (say `no-bust.pl`) and reading the standard input from `fifo`, whilst at the same time we redirect the player's standard output to `fifo`:

 ```terminal
 if test ! -e fifo; then
 mkfifo fifo
 fi
 rm -f fifo; mkfifo fifo
 blackjack -n1e5 < fifo | ./no-bust.pl > fifo
 ```

@@ -32,9 +30,8 @@ STDOUT->autoflush(1);
 while ($command ne "bye") {
  # do not play more than a number of commands
  # if the argument -n was not passed to blackjack
  if ($i++ == 123456789) {
  if ($i++ == 1234567) {
    print "quit\n";
    exit;
  }
  
  # read and process the commands
@@ -45,10 +42,8 @@ while ($command ne "bye") {
  } elsif ($command eq "insurance?") {
    print "no\n";
  } elsif ($comm eq "play?") {
    print "count\n";
    chomp($count = <STDIN>); # the count
    chomp($play = <STDIN>);  # again the "play?" query
    if ($count < 12) {
    @tokens = split(/ /, $command);
    if ($tokens[1] < 12) {
      print "hit\n";
    } else {
      print "stand\n";
@@ -62,18 +57,20 @@ The very same player may be implemented as a shell script:
 ```bash
 #!/bin/sh

 i=0
 while read command
 do
  if test "${command}" = 'bye'; then
  i=$((i+1))
  if test ${i} -ge 12345; then
    echo "quit"
  elif test "${command}" = 'bye'; then
    exit
  elif test "${command}" = 'bet?'; then
    echo 1  
  elif test "${command}" = 'insurance?'; then
    echo "no"
  elif test "`echo ${command} | cut -c-5`" = 'play?'; then
    echo "count"
    read count
    read play      # blackjack will ask again for 'play?'
  elif test "$(echo ${command} | cut -c-5)" = 'play?'; then
    count=$(echo ${command} | cut -f2 -d" ")
    if test ${count} -lt 12; then
      echo "hit"
    else
@@ -86,24 +83,10 @@ done
 To check these two players give the same results, make them play against Libre Blackjack with the same seed (say one) and send the YAML report to two different files:

 ```terminal
 blackjack -n1e3 --rng_seed=1 --yaml_report=perl.yml \
    < fifo | ./no-bust.pl > fifo
 blackjack -n1e3 --rng_seed=1 --yaml_report=shell.yml \
    < fifo | ./no-bust.sh > fifo
 blackjack -n1e5 --rng_seed=1 --report_file_path=perl.yml  < fifo | ./no-bust.pl  > fifo
 blackjack -n1e5 --rng_seed=1 --report_file_path=shell.yml < fifo | ./no-bust.awk > fifo
 diff perl.yml shell.yml 

 15,19c15,19
 <   user:             0
 <   system:           0.022603
 <   wall:             0.034317
 <   second_per_hand:  3.4e-05
 <   hands_per_second: 2.9e+04
 ---
 >   user:             0.06838
 >   system:           0.13676
 >   wall:             11.1446
 >   second_per_hand:  1.1e-02
 >   hands_per_second: 9.0e+01
 ```

 As expected, the reports are the same. They just differ in the speed because the shell script is orders of magnitude slower than its Perl-based counterpart. 
--- a/players/05-no-bust/diff.sh
+++ b/players/05-no-bust/diff.sh
@@ -1,3 +1,3 @@
 ../../blackjack -n100000 --rng_seed=1 --yaml_report=perl.yml  < fifo | ./no-bust.pl  > fifo
 ../../blackjack -n100000 --rng_seed=1 --yaml_report=shell.yml < fifo | ./no-bust.awk > fifo
 # diff perl.yml shell.yml 
 blackjack -n1e5 --rng_seed=1 --report_file_path=perl.yml  < fifo | ./no-bust.pl  > fifo
 blackjack -n1e5 --rng_seed=1 --report_file_path=shell.yml < fifo | ./no-bust.awk > fifo
 diff perl.yml shell.yml 
--- a/players/05-no-bust/perl.yml
+++ b/players/05-no-bust/perl.yml
@@ -0,0 +1,12 @@
 ---
 result: "(-7.6 ± 0.9) %"
 mean: -0.076185
 error: 0.00943779
 hands: 100000
 bankroll: -7618.5
 bustsPlayer: 0
 bustsDealer: 0.27408
 wins: 0.42048
 pushes: 0.06047
 losses: 0.51905
 ...
--- a/players/05-no-bust/run.sh
+++ b/players/05-no-bust/run.sh
@@ -1,4 +1,2 @@
 if test ! -e fifo; then
 mkfifo fifo
 fi
 rm -f fifo; mkfifo fifo
 blackjack -n1e5 < fifo | ./no-bust.pl > fifo
--- a/players/05-no-bust/shell.yml
+++ b/players/05-no-bust/shell.yml
@@ -0,0 +1,12 @@
 ---
 result: "(-7.6 ± 0.9) %"
 mean: -0.076185
 error: 0.00943779
 hands: 100000
 bankroll: -7618.5
 bustsPlayer: 0
 bustsDealer: 0.27408
 wins: 0.42048
 pushes: 0.06047
 losses: 0.51905
 ...
--- a/players/08-mimic-the-dealer/README.md
+++ b/players/08-mimic-the-dealer/README.md
@@ -14,15 +14,7 @@ This time, the configuration file `blackjack.conf` is used. If a file with this
 Now, there are two options that tell Libre Blackjack how the player is going to talk to the backend: `player2dealer` and `dealer2player`. The first one sets the communication mechanism from the player to the dealer (by default is `blackjack`’s standard input), and the second one sets the mechanism from the dealer to the player (by default `blackjack`’s standard output). In this case, the configuration file reads:

 ```ini
 hands = 1e5
 decks = 6
 hit_soft_17 = 1
 # uncomment to obtain the same cards each time
 # rng_seed = 1  

 player2dealer = fifo mimic_p2d
 dealer2player = fifo mimic_d2p
 buffered_fifo = 1
 h17 = true
 ```

 This means that two FIFOs (a.k.a. named pipes) are to be used for communication, `player2dealer` from the player to the dealer and `dealer2player` for the dealer to the player. If these FIFOs do not exist, they are created by `blackjack` upon execution. 
@@ -44,10 +36,9 @@ $ ./mimic-the-dealer.awk < dealer2player > player2dealer
 Both dealer and player may be run in the same terminal putting the first one on the background:

 ```terminal
 rm -f mimic_d2p mimic_p2d
 mkfifo mimic_d2p mimic_p2d
 blackjack &
 gawk -f mimic-the-dealer.awk < mimic_d2p > mimic_p2d
 rm -f d2p p2d; mkfifo d2p p2d
 gawk -f mimic-the-dealer.awk < d2p > p2d &
 blackjack -n1e5 > d2p < p2d 
 ```

 To understand the decisions taken by the player, we have to remember that when Libre Blackjack receives the command `count` asking for the current player's count, it returns a positive number for hard hands and a negative number for soft hands. The instructions `fflush()` are needed in order to avoid deadlocks on the named pipes:
@@ -67,9 +58,8 @@ function abs(x){return ( x >= 0 ) ? x : -x }
 }

 /play\?/ {
  count = $2
  # mimic the dealer: hit until 17 (hit soft 17)
  if (abs(count) < 17 || count == -17) {   # soft hands are negative
  if (abs($2) < 17 || $2 == -17) {   # soft hands are negative
    print "hit";
  } else {
    print "stand";
@@ -84,46 +74,16 @@ function abs(x){return ( x >= 0 ) ? x : -x }

 ```yaml
 ---
 rules:
  decks:                  6
  hands:                  100000
  hit_soft_17:            1
  double_after_split:     1
  blackjack_pays:         1.5
  rng_seed:               -1448949563
  number_of_burnt_cards:  0
  no_negative_bankroll:   0
  max_bet:                0
  penetration:            0.75
  penetration_sigma:      0.05
 cpu:
  user:             0.631905
  system:           1.19576
  wall:             2.15273
  second_per_hand:  2.2e-05
  hands_per_second: 4.6e+04
 player: 
  wins:               0.41044
  pushes:             0.09695
  losses:             0.49261
  dealer_blackjacks:  0.04658
  player_blackjacks:  0.04663
  dealer_busts:       0.18984
  player_busts:       0.27268
  doubled_hands:      0
  doubled_wins:       0
  insured_hands:      0
  insured_wins:       0
  number_of_hands:    100000
  number_of_shuffles: 2326
  total_money_waged:  100000
  worst_bankroll:     -5996.5
  final_bankroll:     -5994.5
  return:             -0.059945
  variance:            0.955017
  deviation:           0.97725
  error:               0.00309034
  result:             "(-6.0 ± 0.6) %"
 result: "(-5.7 ± 0.9) %"
 mean: -0.05716
 error: 0.00926292
 hands: 100000
 bankroll: -5716
 bustsPlayer: 0.27064
 bustsDealer: 0.18905
 wins: 0.41088
 pushes: 0.09888
 losses: 0.49024
 ...

 ```
--- a/players/08-mimic-the-dealer/run.sh
+++ b/players/08-mimic-the-dealer/run.sh
@@ -1,4 +1,3 @@
 rm -f d2p p2d
 mkfifo d2p p2d
 rm -f d2p p2d; mkfifo d2p p2d
 gawk -f mimic-the-dealer.awk < d2p > p2d &
 blackjack -n1e5 > d2p < p2d 
--- a/players/20-basic-strategy/README.md
+++ b/players/20-basic-strategy/README.md
--- a/players/README.md
+++ b/players/README.md
@@ -6,9 +6,9 @@ title: Example players for LibreBlackjack

 The subdirectory `players` contains some automatic players that play against LibreBlackjack. These players are coded in different languages and communicate with LibreBlackjack in a variety of ways in order to illustrate the design basis:

 * [`00-internal`](00-internal) uses the internal player (coded in C++) that defaults to playing one million hands of basic strategy
 * [`00-internal`](00-internal) uses the internal player that defaults to playing one million hands of basic strategy
 * [`02-always-stand`](02-always-stand), using the UNIX tool `yes` this player always says “stand” into the standard output (which is piped to libreblackjack’s standard input) no matter what the cards are
 * [`05-no-bust`](05-no-bust) is a PERL-based player does not bust (i.e. hits if the hard total is less than twelve) that receives the cards through the standard input but draws or stands using a FIFO to talk back to the dealer. There are also implementation in AWK (similar speed) and in a pure Bash script (10x slower)
 * [`05-no-bust`](05-no-bust) is a PERL-based player does not bust (i.e. hits if the hard total is less than twelve) that receives tha cards through the standard input but draws or stands using a FIFO to talk back to the dealer
 * [`08-mimic-the-dealer`](08-mimic-the-dealer) does tha same the dealer do (hits soft seventeens). It is implemented in AWK using two FIFOs.
 * [`20-basic-strategy`](20-basic-strategy) derives the basic strategy from scratch in less than one minute by calling the internal player successively with different strategy files from a shell script.
 * [`20-basic-strategy`](20-basic-strategy) derives the basic strategy from scratch in less than one minute.

--- a/players/check.md
+++ b/players/check.md
@@ -0,0 +1,6 @@
 Case                    | Expected      | Result         | Error         |  Status
 ----------------------- | ------------- | -------------- | ------------- | -------
 Internal player		| -0.0065	| -0.008294	 | 0.00348423	 | ok
 Always stand		| -0.150	| -0.155945	 | 0.0094198	 | ok
 No-bust strategy	| -0.075	| -0.078935	 | 0.00943574	 | ok
 Mimic the dealer	| -0.055	| -0.056205	 | 0.0092778	 | ok
--- a/players/check.sh
+++ b/players/check.sh
@@ -0,0 +1,71 @@
 #!/bin/bash

 if [ -z "$(which gawk)" ]; then
  echo "error: gawk is not installed"
  exit 1
 fi      

 # get into the correct PWD
 if [ ! -f ./header.m4 ]; then
  cd players
 fi
 if [ ! -f ./header.m4 ]; then
  echo "error: call me from the players directory"
  exit 1
 fi

 # ordered cases
 cases="00-internal 02-always-stand 05-no-bust 08-mimic-the-dealer"

 # fancy names
 declare -A names=(\
 ["00-internal"]="Internal player" \
 ["02-always-stand"]="Always stand" \
 ["05-no-bust"]="No-bust strategy" \
 ["08-mimic-the-dealer"]="Mimic the dealer")

 # expected results
 declare -A expected=(\
 ["00-internal"]="-0.0065" \
 ["02-always-stand"]="-0.150" \
 ["05-no-bust"]="-0.075" \
 ["08-mimic-the-dealer"]="-0.055")

 # allowed deviation
 sigma=0.02

 # if there is something on the commandline, use that one, otherwise the expected keys
 if test ! -z "$1"; then
  player=$(basename $1)     # remove trailing '/'
 else
  player=${cases}
 fi

 echo 'Case                    | Expected      | Result         | Error         |  Status' | tee check.md
 echo '----------------------- | ------------- | -------------- | ------------- | -------' | tee -a check.md
 for i in ${player}; do
  if test -d ${i} -a -x ${i}/run.sh; then
    cd ${i}
    if test $(echo "${names[${i}]}" | wc -c) -gt 16 ; then
      sep="\\t"
    else
      sep="\\t\\t"
    fi  
    echo -ne ${names[${i}]}${sep}'| '${expected["${i}"]}\\t'| '
    ./run.sh 1>/dev/null 2> ../${i}.yaml
    
    return=$(grep mean ../${i}.yaml | awk '{print $2}')
    error=$(grep error ../${i}.yaml | awk '{print $2}')
    hands_per_second=$(grep hands_per_second ../${i}.yaml | awk '{print $2}')
    
    echo -ne ${return}\\t' | '${error}\\t' | '${hands_per_second}' | '
    status=$(echo ${return} | awk -v e=${expected["${i}"]} -v s=${sigma} 'END {ok = ($1>(e-s)&&$1<(e+s)); print ok?"ok":"failed"; exit !ok }')
    result=$?
    cd ..
    echo ${status}
    echo -e "${names[${i}]}${sep}| ${expected["${i}"]}\\t| ${return}\\t | ${error}\\t | ${status}" >> check.md
  else
 #     echo "skipped ${i}"
    result=77
  fi
 done
--- a/players/header.m4
+++ b/players/header.m4
@@ -0,0 +1,8 @@
 divert(-1)
 changequote([X,X])
 changecom([X/*X], [X*/X])
 define(case_nav, -------
 :::{.text-center}
 [Previous](../case_prev) | [Index](../) | [Next](../case_next)
 :::)
 divert(0)dnl
--- a/players/make.sh
+++ b/players/make.sh
@@ -0,0 +1,27 @@
 #!/bin/bash

 declare -A prev
 declare -A next

 current_prev=""
 i=1
 for dir in *; do
 if [ -e ${dir}/README.m4 ]; then
  cases[${i}]=$dir
  next[$((${i} - 1))]=$dir
  prev[${i}]=$current_prev
  current_prev=${dir}
  i=$((${i} + 1))
 fi
 done

 for i in $(seq 1 ${#cases[*]}); do
 echo $i ${cases[${i}]}
 cd ${cases[${i}]}
 difficulty=`echo ${cases[${i}]} | cut -c-2`
 m4 -Dcase_difficulty=${difficulty} \
    -Dcase_prev=${prev[${i}]} \
    -Dcase_next=${next[${i}]} \
    ../header.m4 README.m4 > README.md
 cd ..   
 done