----
'''''Documentation Développeur'''''

'''Auteurs''' : Sébastien Denvil, Martial Mancip, Patrick Brockmann [[BR]]
----

'''Sommaire général''' [wiki:WikiStart libIGCM]
[[PageOutline(1-2,Table des matières,inline)]]

----

= Stratégies de développement =
 * Développer le plus clairement possible
 * S'appuyer sur des commandes UNIX avec des options standards
 * Inclure une documentation dans le code

{{{
#==================================================
# The documentation of this file can be automatically generated
# if you use the prefix #D- for comments to be extracted.
# Extract with command: cat lib* | grep "^#D-" | cut -c "4-"
#==================================================
#D-This line will be extracted
#D-This one too
}}}
 * Fournir une fonction de test pour chaque librairie. Le test se réalise en faisant la différence entre les résulats courants et un fichier de résultats de référence. 

{{{
Check libIGCM_debug ..........................................[ FAILED ]
}}}
Indique que la librairie libIGCM_debug n'est pas opérationnelle.
{{{
Check libIGCM_debug ..............................................[ OK ]
Check libIGCM_card ...............................................[ OK ]
Check libIGCM_date ...............................................[ OK ]
}}}
Indique que toutes ces librairies sont opérationnelles.

= Règles de syntaxe =
 * Les noms des variables sont définies sans espace avec des majuscules :
  * ceciestunevariable <-- incorrect
  * !CeciEstUneVariable <-- correct

= libIGCM_card =

Cette librairie se charge de faire la lecture et l'écriture dans les fichiers
carte.

== Description du format card ==

Ce paragraphe décrit les éléments du format d'un fichier CARD (inspiré du format INI):

 * Sections: Les sections commencent par ''['' et se termine par '']'' comme pour les sections [Messages] et [Recipes]  utilisées dans l'exemple ci-dessous.

 * Options: L'option ''Red = 120'' ci-dessous est un exemple d'option (aussi connu sous le nom de clé). Les options commencent par une clé ''Red'', suivie du signe égale '=', et elles se terminent par une valeur ''120''.

 * Commentaires: Toutes les lignes commençant par un '#' sont considérées comme étant des commentaires, et sont ignorées.

 * Continuation de lignes: Une option peut être écrite sur plusieurs lignes si le dernier caractère de la ligne est un '\'

 * Exemple:

{{{
[Messages]
Option1= "Hello Earth"
Option2= "Hello Mars"

# My comments
[Recipes]
Cake= "file1.doc"
Starter= "file2.doc"

[ColorValues]
Red= 120
Blue= 230
Green= 178

[Couples]
List1=   (up, down), \
         (humid, dry), \
         (hot, cold), \
         (far, close)
List2=   (ice, fire, air, water)
}}}

= Documentation interne =

{{{
#==================================================================
libIGCM_card
This ksh library handles extraction of information from configuration file
called "card" file (en français fichier "carte").
All function described bellow must be prefixed by IGCM_card.

#==================================================================
function IGCM_card_PrintOption
* Purpose: Print an option from a given file.card and section
* Usage: IGCM_card_PrintOption file.card section option

#==================================================================
function IGCM_card_PrintSection
* Purpose: Print all options from a given file.card and section
* Usage: IGCM_card_PrintSection file.card section

#==================================================================
function IGCM_card_DefineVariableFromOption
* Purpose: Define a variable from a given file.card, section and option
*          Variable name is automatically defined as file_section_option
* Usage: IGCM_card_DefineVariableFromOption file.card section option

#==================================================================
function IGCM_card_DefineArrayFromOption
* Purpose: Define an array variable from a given file.card, section and option
*          Array variable is automatically defined as file_section_option
* Usage: IGCM_card_DefineArrayFromOption file.card section option

#==================================================================
function IGCM_card_DefineArrayFromSection
* Purpose: Define an array variable from a given file.card and section
*          Array variable is automatically defined as file_section
* Usage: IGCM_card_DefineArrayFromSection file.card section

#==================================================================
function IGCM_card_WriteOption
* Purpose: Write an option from a given file.card and section
* Usage: IGCM_card_WriteOption file.card section newvalue
* Examples: IGCM_card_WriteOption file.card Recipes Red 150
            IGCM_card_WriteOption file.card Messages Option2 '"Hello Mercure"'
            IGCM_card_WriteOption file.card Messages ListVal1 '( 1, 2, 3 )'
            listname="(Sebastien, Martial, Patrick)"
            IGCM_card_WriteOption NewTestFile.card Messages ListVal2 "${listname}"

#==================================================================
function IGCM_card_Check
* Purpose: Check the present file by comparison with a reference file
* Usage: IGCM_card_Check
}}}

== libIGCM_comp ==

== libIGCM_config ==

== libIGCM_date ==
{{{
#==================================================================
libIGCM_date
This ksh library handles date calculs and convertions in different calendars.

#==================================================================
function IGCM_date_DaysInYear
 * Purpose: Return the number of days in a year
 * Usage: IGCM_date_DaysInYear yyyy
          if there is no argument on the command line,
          then assume that a yyyy is being piped in

#==================================================================
function IGCM_date_DaysInMonth
 * Purpose: Calculate the number of days in a month
 * Usage: IGCM_date_DaysInMonth yyyy mm
          or IGCM_date_DaysInMonth yyyymmdd
          if there are no command line arguments then
          assume that a yyyymmdd is being piped in and read the value.
          if there is only one argument assume it is a yyyymmdd on the command line
          other wise it is a yyyy and mm on the command line

#==================================================================
function IGCM_date_ConvertGregorianDateToJulian
 * Purpose: Convert yyyymmdd to yyyyddd
 * Usage: IGCM_date_ConvertGregorianDateToJulian 19980429
          if there is no command line argument, then assume that the date"
          is coming in on a pipe and use read to collect it

#==================================================================
function IGCM_date_ConvertJulianDateToGregorian()
 * Purpose: Convert yyyyddd to yyyymmdd
 * Usage: IGCM_date_ConvertJulianDateToGregorian 1998213
          if there is no command line argument, assume one is being
          piped in and read it

#==================================================================
function IGCM_date_AddDaysToJulianDate
 * Purpose: Add days to a yyyyddd formatted date
 * Usage: IGCM_date_AddDaysToJulianDate 1998312 { ,-}14
          Read from the difference from the command lines
          and the date from the command line, or standard input

#==================================================================
function IGCM_date_AddDaysToGregorianDate
 * Purpose: Add days to a yyyymmdd formatted date
 * Usage: IGCM_date_AddDaysToGregorianDate 19980312 { ,-}14
          Read from the difference from the command lines
          and the date from the command line, or standard input

#==================================================================
function IGCM_date_DaysBetweenJulianDate
 * Purpose: Calculate the days difference between two dates and reports
            the number days as jul1 - jul2
 * Usage: IGCM_date_DaysBetweenJulianDate jul1 jul2
          where julian date is in the form yyyyddd

#==================================================================
function IGCM_date_DaysBetweenGregorianDate ()
 * Purpose: Calculate the days difference between two dates and reports
            the number days as grg1 - grg2
 * Usage: IGCM_date_DaysBetweenGregorianDate grg1 grg2
          where gregorian date is in the form yyyymmdd

#==================================================================
function IGCM_date_DaysSinceJC ()
 * Purpose: Calculate the days difference between a date and 00010101
 * Usage: IGCM_date_DaysSinceJC grg1
          where gregorian date is in the form yyyymmdd

#==================================================================
function IGCM_date_Check
 * Purpose: Check the present file by comparison with a reference file
}}}

== libIGCM_debug ==
{{{
#==================================================================
function IGCM_debug_CallStack
* Purpose: Echo the Stack

#==================================================================
function IGCM_debug_PushStack
* Purpose: Push a function name in the stack

#==================================================================
function IGCM_debug_PopStack
* Purpose: Pop a function name in the stack

#==================================================================
function IGCM_debug_Exit
* Purpose: Print Call Stack and exit with number 1

#==================================================================
function IGCM_debug_Print
* Purpose: Print arguments according to a level of verbosity.

#==================================================================
function IGCM_debug_PrintVariables
* Purpose: Print arguments when match a pattern
           according to a level of verbosity.
#==================================================================
function IGCM_debug_Check
 * Purpose: Check the present file by comparison with a reference file
}}}

== libIGCM_post ==

== libIGCM_sys ==