/* =============================================================================
   Description
   =============================================================================

   To read deals from a text (i.e. not a binary) giblib file.

   It can also be used to store the state of the deal, and to play/unplay
   cards starting with a given deal.

   The maximum line length is defined above by GIBLIB_LENLINE.

   Player and card values
   ----------------------

   See the file defs.h for definitions used.

   Standard giblib file
   --------------------
   The standard text giblib file consists of records like this:

JT852.93.KQ7.J82 AQ97.JT654.T6.A5 43.AK8.A542.7643 K6.Q72.J983.KQT9:88887777A9A977778888

   The first 67 characters is the deal, starting with the west hand,
   followed by north, east and south hands. The deal must consist of 52 cards.

   This is followed by a colon and 20 characters for possible tricks
   (number of tricks which can be made by north-south).
   Each group of four characters is for leader s/e/n/w in that order,
   with five groups for the contracts n/s/h/d/c in that order.

   Extensions
   ----------

   This module allows a number of extensions:

   1. The deal can be any number of tricks between 1 and 13 tricks,
      any multiple of four cards 4,8,12, ... ,48,52.

   2. The possible tricks are optional. If omitted notrumps is assumed.

   3. The possible tricks may be partial, e.g. 20 possible tricks are given
      but some of them are unknown, given by the character '-'.

   4. Any number of blank lines are allowed between deals.

   5. Comment lines may precede a deal. A comment starts with an open brace '{'
      and is terminated by a closing brace '}', spanning any number of lines.
      Any text can be include inside the comments, excluding the opening and
      closing brace characters.

   Options
   -------

   Options may be imbedded in the comment.

   Name Option
   -----------

   This has the form name=... followed by at least a blank or closing brace.
   This is used as the name for the deal, e.g.

     { name=gliblib1}

   Trumps Option
   -------------

   This has the form trumps= followed by one of the characters s/h/d/c/n, e.g.

     { name=gliblib1 trumps=d}

   The default contract is notrump.

   Leader Option
   -------------

   This has the form leader= followed by one of the characters w/n/e/s.
   This is the player leading the first card. In a 52-card deal it is
   understood that his RHO is the declarer, e.g.

     { name=gliblib1 trumps=n leader=e}

   The default leader is west.

   Played Option
   -------------

   Specifies that one or more cards are to be played starting with the deal
   given. The leader is determined by the first card. All cards must be present
   in the deal, be in the hand of the right player, must follow suit, and so on.
   Each trick must be started by the winner of the previous trick.

   A card is given as two characters, the suit and the rank. Use a dash '-'
   to separate tricks, and a period '.' to separate cards in a trick.

   The following is for the first three tricks and a further three cards played
   from the 52-card deal given:

     {name=cpt leader=w played=c8.c9.ct.ck-h7.h2.hk.hj-d3.d8.dk.d5-h9.h3.ha}
     j95.t8632.j65.85 t862.ak54.73.q92 k743.j.a98.ajt76 aq.q97.kqt42.k43

*/
