[Scidb-development] First Draft of eCQL - Player Search

[Gregor C. <re...@gm...>]

This is a continuation of the first draft of eCQL. In this part all the
functions/sub-functions for player search will be defined.

As usual the best view is with a monospaced font, and I've attached a text file
of this draft.

===================================================================

Player Search
~~~~~~~~~~~~~

The search for players will be performed with sub-functions of function 
?player.
Most of the function will be based on C/CIF standard
(http://ccif.sourceforge.net/cif-game-info-head-player.html).

eCQL                       CQL-S             CQL 5.1  Application    C/CIF
--------------------------------------------------------------------------
%player                    :whiteplayer      player   CB Scidb Scid    yes
&player.birth              :whitebirthyear            Scidb            yes
&player.death              :whitedeathyear                             yes
#player.age                                                            no
^player.clock                                                          yes
~player.federation         :whitecountry              CB Scidb Scid    yes
%player.forename                                      CB               yes
#player.frequency                                     Scidb            no
%player.gender             :whitegender               Scidb            yes
%player.identifier                                    Scidb            yes
%player.name               :whiteplayer      player   CB Scidb Scid    yes
~player.nation                                                         yes
%player.networkaddress                                                 yes
#player.ranking                                       Scidb            yes
#player.rating             :whiterating      elo      CB Scidb Scid    yes
#player.regioncode                                    Scidb            yes
^player.runningclock                                                   yes
%player.species            :whiteiscomputer           Scidb            yes
%player.surname                                       CB               yes
%player.team                                          CB               yes
%player.title              :whitetitle                CB Scidb Scid    yes
--------------------------------------------------------------------------
Per default the first level function %player is an abbreviation for the second
level function %player.name.

Note that a player query needs the color of the player as an argument, 
example:

   %player.name white

Some details:

#player.frequency returns the number of games with this player in searched
databases.

?player.name provides these third level functions:

   %player.name               := raw name (used in database)
   %player.name.ascii         := ASCII'fied name
	                              ("Réti" -> "Reti")
   %player.name.normalized    := normalized name
	                              ("Zunker,Reinhard,Dr." -> "Zunker, Reinhard")
   %player.name.standardized  := standardized name
	                              ("ZUNKER, REINHARD" -> "Zunker, Reinhard")
   %player.name.base          := base name from dictionary
	                              ("Aarland, St1" -> "Aarland, Stein")

Some sub-functions of ?player.name can be combined, example:

   %player.name.normalized.ascii

The specific federation will be tested with third level functions, some
examples:

   :player.federation.DE
   :player.federation.IT
   :player.federation.germany
   :player.federation.italy
   :player.nation.unknown

Nowadays the species of the player is an important information, but only Scidb
allows to define this attribute:

   :player.species.computer
   :player.species.human
   :player.species.unknown

The gender also contains the species 'computer' for convenience:

   :player.gender.computer
   :player.gender.man
   :player.gender.woman
   :player.gender.unknown

eCQL knows more rating types than only ELO as CQL 5.1:

   #player.rating.none
   #player.rating.acf
   #player.rating.blitz
   #player.rating.dwz
   #player.rating.ecf
   #player.rating.edo
   #player.rating.elo
   #player.rating.iccf
   #player.rating.rapid
   #player.rating.uscf

Note that the numeric functions for player attributes will provide the
additional fourth level functions "min", "max", "mid", "avg", and "abs".
This type of fourth level functions do not expect the color of the player.
Example:

   #player.rating.elo white   := ELO rating of white player
   #player.rating.elo black   := ELO rating of black player
   #player.rating.elo.min     := minimum of white and black ELO
   #player.rating.elo.max     := maximum of white and black ELO
   #player.rating.elo.mid     := 0 if no player has an ELO,
                                 average if both players have an ELO,
                                 otherwise value of single player with ELO
   #player.rating.elo.avg     := 0 if at least one of the players has no ELO,
                                 otherwise average of white and black ELO
   #player.rating.elo.abs     := absolute difference between white and black 
ELO

Moreover ?player.rating provides some selective functions:

   ?player.rating.best        := best rating of this player
   ?player.rating.actual      := most actual rating of this player

The title of the player is grouped by the organization:

   :player.title.none
   ----------------------
   :player.title.fide.cm
   :player.title.fide.fm
   :player.title.fide.gm
   :player.title.fide.im
   :player.title.fide.wcm
   :player.title.fide.wfm
   :player.title.fide.wgm
   :player.title.fide.wim
   ----------------------
   :player.title.iccf.gm
   :player.title.iccf.im
   :player.title.iccf.lgm
   :player.title.iccf.lim
   :player.title.iccf.sim
   ----------------------
   :player.title.uscf.nm
   :player.title.uscf.sm
   :player.title.uscf.lm
   ----------------------
   :player.title.bdf.njm
   :player.title.bdf.nm
   :player.title.bdf.nmb
   :player.title.bdf.nmc
   :player.title.bdf.nmg
   :player.title.bdf.nms
   :player.title.bdf.sm
   :player.title.bdf.wm
   :player.title.bdf.wsm
   ----------------------
   :player.title.cfc.nm
   :player.title.cfc.nwm
   ----------------------
   :player.title.ecf.nm
   ----------------------
   :player.title.nzcf.nm

The fourth level function "year" provides the year of the achieved title,
example:

   #player.title.fide.gm.year white := the year where white player has achieved
	                                    the GM title, is zero if unknown