Tutorials

h1. Coder une bibliothèque Scol en C - Niveau 2

Objectif : ajout d'éléments d'API, types Scol complexes

Moyens :

* manipuler des chaînes de caractères dans la pile;

* gérer des tuples;

* gérer des listes;

* gérer les listes de tuples;

* commenter avec doxygen;

* code source de la bibliothèque;

* exemple d'utilisation dans une application Scol.

STATUT : COMPLET

Version : 1.0, 1.0.1

Date : novembre 2010, décembre 2010 (initialement diffusé sur http://www.irizone.net)

Auteur : iri

Licence du tutoriel : GNU FDL v1.3

Licence du code source : GNU/GPL v3

Téléchargement : http://www.irizone.net/dl/tutos/vmscol/vm_example_2.tar.gz

Langage : *C*

Ok pour toute version de Scol Windows et GNU/Linux (>= 4.0).

Pré-requis : [[Coder une bibliothèque Scol en C - Niveau 1]]

h2. Les chaînes de caractères

Les chaînes requierent un traitement un peu particulier. Rien de bien sorcier, 

rassurez-vous ! Différentes fonctions et macros sont là pour vous aider :)

Première chose, récupérer le pointeur dans la pile. Ici, aucune différence,

ce sera soit <em>MMpull</em> soit <em>MMget</em> selon ce qu'on veut faire.

On utilisera la macro <em>MTOP</em> pour convertir le pointeur de la machine Scol 

en un pointeur système plus facilement manipulable. On aura ainsi :

<pre>int p_chaine = MTOP (MMpull (m));

int p_chaine = MTOP (MMget (m, X));</pre>

Seconde étape, récupérer la chaîne elle-même grâce à _MMstartstr_ qui

retourne le curseur à la position 0 de la chaîne :

<pre>char * chaine = MMstartstr (m, p_chaine);</pre>

On peut faire subir à _chaine_ tous les traitments C qu'on souhaite.

Cependant, gardez en mémoire que si vous devez allouer de la mémoire pour un

traitement particulier (typiquement un _malloc_ mais ce peut être aussi une allocation 

"cachée" telle que _strdup_) vous devez libérer ce que vous avez alloué, Scol ne 

le fera pas à votre place.

En revanche, vous devez libérer une fois le contenu passé à la pile Scol : à ce

moment là,la donnée sera allouée dans la bande Scol, indépendamment de votre propre

allocation.

Au final, pour retourner une chaine de caractères de type _char *_, (vous

pouvez bien sur caster si cela a un sens), la fonction _Mpushstrbloc_ doit 

être utilisée :

<pre>Mpushstrbloc (m, chaine_finale);</pre>

h3. Exemple

Une fonction stupide pour souhaiter la bienvenue (un remake du fameux "Hello

Word" !) : la fonction Scol attend un nom et retourne la chaine "Hello _le_nom_entré_".

Rien de bien transcendant donc !

Décortiquons en pseduo-code :

# DEPILE l'argument chaine

# PLACE lecurseur en début de chaine

# traitements

# EMPILE le résultat

Concrètement, cela va donner :

<pre>menter = MTOP (MMpull (m));		/* 1 */

enter = MMstartstr (m, menter);		/* 2 */

sprintf (result, "%s %s", "Hello", enter);	/* 3 */

Mpushstrbloc (m, result);	/* 4 */</pre>

Le code complet de la fonction est alors :

<pre>int sc_hello (mmachine m)

{

    int menter;

    char * enter = NULL;

    char * result = NULL;

    MMechostr (MSKDEBUG, "sc_hello : enteringn");

    menter = MTOP (MMpull (m));

    enter = MMstartstr (m, menter);

    result = (char *) malloc (sizeof (char) * (strlen (enter) +1));

    sprintf (result, "%s %s", "Hello", enter);

    Mpushstrbloc (m, result);

    free (result);

    return 0;

}</pre>

Bien entendu, on alloue dynamiquement la mémoire nécessaire à la chaine selon

la longueur de la chaine d'entrée et on libère ensuite.

Le type de la fonction Scol est : <code>fun [S] S</code>

h2. Les tuples

Les tuples sont des sortes de tableaux : un seul élément dans la pile contient

plusieurs variables distinctes.

h3. Méthode

Pour récupérer les variables d'un tuple passé en argument d'une fonction Scol,

on commence logiquement par dépiler ledit tuple via les fonctions habituelles. Puis,

le nombre de variables contenues étant connu (c'est un tuple, pas une liste !), 

on les extraie une à une (ou via

une boucle dans un tableau si le tuple est large, par exemple) grâce à la fonction

_MMfetch_. Celle-ci est, dans le concept, similaire à _MMget_ que

vous connaissez :

<pre>MMetch machine_scol tuple index_dans_le_tuple</pre>

sachant que l'index démarre à zéro pour le premier élément.

En pseudo-code, pour un tuple de 3 éléments, on a :

<pre>tuple = MMpull (m)

v1 = MMfetch (m, tuple, 0);

v2 = MMfetch (m, tuple, 1);

v3 = MMfetch (m, tuple, 2);</pre>

Pour retourner un tuple, c'est différent mais on garde une logique semblable.

On commence donc par empiler chaque élément du tuple dans l'ordre du type de la

fonction Scol. Puis on empile le nombre d'éléments du typle et on demande enfin

à Scol de créer le tuple. Au final, pour retourner un tuple de trois valeurs, le

pseudo-code sera :

<pre>MMpush (m, PTOM (v1))

Mpushstrbloc (m, PTOM (v2))

MMpush (m, PTOM (v3))

MMpush (m, ITOM (3))

MBdeftab (m)</pre>

h3. Exemple

Notre fonction Scol combinera des tuples en entrée et en sortie. Elle se propose

depuis deux entiers de retourner deux autres entiers qui seront respectivement leur

quotient et leur reste. Soit le prototypage Scol de cette fonction :

<code>fun [[I I]] [I I]</code>

L'extraction des deux entiers d'entrée sera :

<pre>mtuple = MTOI (MMpull (m));

mdividende = MTOI (MMfetch (m, mtuple, 0));

mdiviseur = MTOI (MMfetch (m, mtuple, 1));</pre>

Le tuple retournée est codée ainsi :

<pre>MMpush (m, ITOM (quotient));

MMpush (m, ITOM (reste));

MMpush (m, ITOM (2));

return MBdeftab (m);</pre>

D'où le code complet de la fonction :

<pre>int sc_division (mmachine m)

{

    int mtuple, mdividende, mdiviseur;

    int quotient, reste;

    MMechostr (MSKDEBUG, "sc_division : enteringn");

    mtuple = MTOI (MMpull (m));

    mdividende = MTOI (MMfetch (m, mtuple, 0));

    mdiviseur = MTOI (MMfetch (m, mtuple, 1));

    if (mdiviseur == 0)     /* on teste le cas de la division par zéro */

        return MMpush (m, NIL);

    quotient = mdividende / mdiviseur;

    reste = mdividende % mdiviseur;

    MMpush (m, ITOM (quotient));

    MMpush (m, ITOM (reste));

    MMpush (m, ITOM (2));

    return MBdeftab (m);

}</pre>

h2. Les listes simples et les listes de tuples

Petit rappel sur les listes en Scol : une liste possède une structure similaire

aux listes chainées dans leur principe. Une liste est un tuple de deux éléments :

le premier élément de la liste et la liste de la suite des autres éléments. Soit :

<code>liste = [element suite]</code>

Nous retrouverons donc cette structure dans la façon de coder la récupération

d'une liste ou le retour d'une liste.

En Scol, on code souvent les listes de cette manière :

<code>liste = 1 :: 2 :: 3 :: 4 :: 5 :: nil;</code>

Cette manière est considérée à raison comme plus lisible mais elle cache la structure

sous-jacente. Pour mieux se la représenter au niveau du code source, écrivons cette

liste avec l'écriture standard :

<code>liste = [1 [2 [3 [4 [5 nil]]]]];</code>

on voit bien l'imbrication de tuples...

Conséquence : pour lire ou écrire des listes, faudra boucler !

En lecture, le principe est le suivant :

<pre>WHILE (liste non vide)

        e = premier élément de liste

        SI e non vide

            instructions

        liste = suite de la liste</pre>

on pourra avoir des imbrications : liste dans une liste ou, moins rarement, une liste

de tuples auquel il faudra réaliser une boucle secondaire dans <code>instructions</code>

(cf code source dans l'archive téléchargeable).

En écriture, c'est un peu différent :

<pre>WHILE (liste_traitée)

       {

          values = liste_traitée->data

          x = values->x

          y = values->y

          z = values->z

          MMpush (m, PTOM (x))

          MMpush (m, PTOM (y))

          MMpush (m, PTOM (z))

          MMpush (m, ITOM (3))

          MBdeftab (m)

          compteur++

          liste_traitée = liste_traitée->next

      }

  MMpush (m, NIL)

  FOR (i=0; i < compteur; i++)

      {

          MMpush (m, ITOM (2))

          MBdeftab (m)

      }</pre>

On obtient alors un type Scol <code>[[u0 u1 u2] r1]</code> : une liste de tuples

de trois éléments (cf même code source que précédemment).

Le principe est malgré tout simple : on empile d'abord chaque élément de la liste,

que ce soit un simple entier ou un tuple complexe. Puis on ajoute un NIL final

(rappellez-vous qu'une liste se termine toujours par un 'nil'). Enfin, on crée nos

tuples à 2 éléments (rappelez-vous, une liste c'est <code>[a [b [c [d [e nil]]]]]</code>, soit <code>[a next]</code>).

h3. Exemple

Imaginons une fonction qui accepte une liste d'entiers en entrée et qui retourne

une même liste avec les entiers incrémentés ou décrémentés selon un flag d'une certaine

valeur passée elle-aussi en paramètre :

<code>fun [[I r1] I I] [I r1]</code>

Pour réaliser cela, nous devons dépiler les trois arguments, le dernier argument

étant le dernier sur la pile :

<pre>mflag = MTOI (MMpull (m));

mnumber = MTOI (MMpull (m));

mlist_enter = MMpull (m)>>1;</pre>

mlist_enter doit désormais être lue (elle contient la liste d'entiers) :

<pre> while (mlist_enter != NIL)

    {

         element_list = MTOI (MMfetch (m, mlist_enter, 0));

         if (element_list != NIL)

         {

             // traitements sur element_list

         }

         mlist_enter = MTOI (MMfetch(m, mlist_enter, 1));

    }</pre>

nous bouclons tant que la liste ne vaut pas nil. Chaque élément est lu grâce à la

fonction <em>MMfetch</em> que nous avons déjà vu. Cet élément est toujours à la position

0 du tuple, la suite de la liste étant à la position 1 (relisez le paragraphe plus

haut sinon).

Notez que nous ne pouvons pas lire les valeurs de manière directe avec <em>MMfetch</em>

comme nous l'avons effectué avec les tuples car cette fois nous ne connaissons pas le nombre

d'éléments a priori contenus dans la liste. Nous devons donc passer par une boucle WHILE.

Pour la sortie, nous devons également boucler :

<pre>while (mlist_out != NIL)

    {

         element_list = MTOI (MMfetch (m, mlist_out, 0));

         if (element_list != NIL)

         {

             MMpush (m, ITOM (element_list));

             compteur++;

         }

         mlist_out = MTOI (MMfetch(m, mlist_out, 1));

    }

    MMpush (m, NIL);

    for (i = 0; i  < compteur; i++)

    {

        MMpush (m, ITOM (2));

        MBdeftab (m);

    }

    return 0;</pre>

Chaque élément est d'abord empilés puis la liste est construite, comme décrit plus haut.

Au final, la fonction est :

<pre>int sc_calcul_list (mmachine m)

{

    int mlist_enter, mnumber, mflag;

    int element_list, i, compteur = 0;

    MMechostr (MSKDEBUG, "sc_calcul_list : enteringn");

    mflag = MTOI (MMpull (m));

    mnumber = MTOI (MMpull (m));

    mlist_enter = MMpull (m)>>1;

    while (mlist_enter != NIL)

    {

         element_list = MTOI (MMfetch (m, mlist_enter, 0));

         if (element_list != NIL)

         {

             MMpush (m, ITOM (element_list + (mnumber * mflag)));

             compteur++;

         }

         mlist_enter = MTOI (MMfetch(m, mlist_enter, 1));

    }

    MMpush (m, NIL);

    for (i = 0; i  < compteur; i++)

    {

        MMpush (m, ITOM (2));

        MBdeftab (m);

    }

    return 0;

}</pre>

Notez que pour alléger le code C, la boucle WHILE traite à la fois la lecture d'entrée

et l'écriture de sortie. Nous verrons plus loin comment est géré le flag Scol.

h2. Code source de la bibliothèque

La dernière fonction comprend un "flag" Scol. il y a plusieurs méthodes en C

pour les gérer, voyez le code source téléchargeable. Le principe est le suivant :

# dans le tableau des nom Scol, on définit son nom (par exemple "EXEMPLE_PLUS"),

# dans le tableau 2, on définit sa valeur,

# dans le tableau 3, on définit son type, ici _TYPVAR_ car c'est une valeur

numérique,

# dans le dernier tableau, on donne son type Scol, ici un entier donc "I".

Si on compte également utiliser le flag dans le code source (à des fins de comparaison

par exemple), la méthode la plus simple est alors d'ajouter une définition dans le header :

@#define EXEMPLE_PLUS 1@

Ci-dessous est simplement recopiée la nouvelle définition de l'API de ce niveau 2 :</p>

<div class="code2"><pre>char* example_name[EXAMPLE_PKG_NB] =

{

    /* nouvelles fonctions Scol */

    "example_increment",    /* fonction de l'API appelable depuis l'extérieur */

    "example_hello",

    "example_calcul",

    "example_list",

    /* nouveaux flags Scol */

    "EXAMPLE_MOINS",

    "EXAMPLE_PLUS"

};

int (*example_fun[EXAMPLE_PKG_NB]) (mmachine m) =

{

    sc_increment,   /* nom interne où le code de cette fonction est développé */

    sc_hello,

    sc_division,

    sc_calcul_list,

    (void*) ((-1)*2),   /* vaut '-1', on décrémente */

    (void*) (1*2)    /* vaut '+1', on incrémente */

};

int example_narg[EXAMPLE_PKG_NB] =

{

    1,      /* nombre d'argument attendu par cette fonction */

    1,

    1,

    3,

    TYPVAR,

    TYPVAR

};

char* example_type[EXAMPLE_PKG_NB] =

{

    "fun [I] I",    /* prototype Scol de cette fonction : on notera que le nombre d'argument est bien 1 */

    "fun [S] S",

    "fun [[I I]] [I I]",

    "fun [[I r1] I I] [I r1]",

    "I",

    "I"

};</pre>

Le code entier est disponible, comme toujours, dans l'archive téléchargeable !

h2. Exemples Scol

h3. Fonction "example_hello" :

<pre>fun main ()=

	_showconsole;

	_fooS example_hello "iri";

	0;;

</pre>

h3. Fonction "example_calcul" :

<pre>fun main ()=

	_showconsole;

	let example_calcul [17 3] -> [quotient reste] in

	_fooS strcatn "La division de 17 par 3 donne un quotient de " ::

			(itoa quotient) ::

			" et un reste de " ::

			(itoa reste) :: nil;

	0;;

</pre>

La console devrait afficher : <code>La division de 17 par 3 donne un quotient de 5 et un reste de 3</code>

h3. Fonction "example_list" :

<pre>fun main ()=

	_showconsole;

	_fooIList example_list 7 :: 5 :: 2 :: nil 10 EXAMPLE_PLUS;

	0;;

</pre>

La console devrait afficher en retour : <code>17 : 15 : 12</code>

Le même exemple mais en changeant de flag :

<pre>fun main ()=

	_showconsole;

	_fooIList example_list 7 :: 5 :: 2 :: nil 10 EXAMPLE_MOINS;

	0;;

</pre>

La console devrait afficher en retour : <code>-3: -5 : -8</code></p>

h2. Documenter avec Doxygen

Commenter son code source, c'est bien, le documenter c'est encore mieux !

Il existe plusieurs outils. J'utilise (et les autres développeurs du langage

aussi) "Doxygen":http://www.doxygen.org/, un outil complet et pratique.

Il permet d'exporter une documentation en plusieurs formats : du html au pdf en 

passant par Latex et plusieurs autres. Si vous utilisez Code::Blocks, le plugin

est désormais intégré dans la barre de menu. Autrement, vous trouverez de l'information

à cette adresse : "Wiki C::B":http://wiki.codeblocks.org/index.php?title=DoxyBlocks.

Sous le nom de menu _DoxyBlocks_, vous configurez la sortie selon vos souhaits

et lancez la génération des documents via l'item "Extract documentation" (ou en

lançant "DoxyWizard" si vous désirez plus d'options avec l'assistant graphique). C'est

simple, rapide et efficace.

La documentation générée par cet outil est également incluse dans l'archive.

En amont, il est nécessaire de suivre une certaine syntaxe dans les commentaires.

Vous la trouverez dans le code source de l'archive téléchargeable, pour la plus

courante.Pour aller plus en profondeur, consultez le site de "Doxygen":http://www.doxygen.org/.

Enfin, même si vous n'utilisez pas C::B, vous pouvez utiliser Doxygen pour générer

vos documentations !

Remarque : C::B intègre aussi un plugin pour Valgrind permettant de tester les

utilisations mémoire de votre application.