home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / c / parse.lha / parse.doc < prev    next >
Text File  |  1992-08-11  |  10KB  |  204 lines
  1.  
  2.                                parse()
  3.                            version 1.00
  4.  
  5.                       par Jean-Pierre Rivière
  6.  
  7.              (English reader : please see file parse.edoc)
  8.  
  9.       RESUME : parcoureur ("parser") de ligne de commande facile
  10.                d'emploi et suivant totalement les conventions
  11.                du systeme V pour le passage des options.
  12.                copyright (c) 1992 par Jean-Pierre Rivière.
  13.                Librement redistribuable et gratuit ("freeware").
  14.                Toute utilisation dans tout programme libre et gratuite
  15.                pour peu que la source dudit programme, si elle est
  16.                distribuée, inclut le présent paquetage logiciel ou
  17.                à défaut indique ses références et le moyen de se le
  18.                procurer.
  19.                Toute utilisation de ce paquetage se fait aux seuls
  20.                risques et périls de l'utilisateur, l'auteur déclinant
  21.                par avance toute responsabilité.
  22.                Ça suffit comme ça, place à la suite !
  23.  
  24.  
  25.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26.       Veille au respect scrupuleux des conventions Unix System V v4
  27.    Utilise pour cela une chaîne de formatage où toutes les options
  28.    sont indiquées dans un ordre quelconque mais avec un espace
  29.    derrière chaque option sans argument et un point-virgule derrière
  30.    chaque option avec un argument.
  31.  
  32.       Si tout s'est bien passé, la valeur de retour est positive ou nulle,
  33.    égale au nombre d'options reconnues dans la ligne de commande.
  34.  
  35.       Sinon elle est négative pour indiquer une erreur de syntaxe ou bien
  36.    que l'allocation dynamique de mémoire faite par la fonction n'a pas pû
  37.    être réalisée. Dans chacun de ces cas, il n'y a rien corespondant à la
  38.    description de ce qui a été éventuellement vu, et en conséquence il ne
  39.    faut pas essayer de le voir !
  40.  
  41.       Si tout s'est bien passé, il faut désallouer manuellement la mémoire
  42.    allouée par la fonction parse() en appelant la fonction parse_cleanup().
  43.  
  44.       Rappelons que toutes les options doivent précéder les éventuels
  45.    arguments, que leur ordre n'a aucune importance mais qu'elles ne doivent
  46.    pas être répétées, même si cela ne se fait pas de façon contradictoire.
  47.  
  48.       parse() et parse_cleanup() sont deux fonctions que j'ai écrites sous
  49.    la forme d'un "module" C afin de faciliter la tâche du programmeur
  50.    quand il s'agit de gérer les multiples options que la ligne de commande
  51.    de son dernier utilitaire peut gérer. Mon but était puissance et ergo-
  52.    nomie et je peux dire qu'il est atteint.
  53.  
  54.       Puissance car le respect strict des normes Open Software Foundation
  55.    est intégral. Puissance car simple à mettre en oeuvre et à faire évo-
  56.    luer. Le tout est donc ergonomique à la fois pour le programmeur et
  57.    pour l'utilisateur (uniformisation des interfaces sous shell rendue plus
  58.    facile donc plus répandue).
  59.  
  60.       L'outil principal qui sert à ces deux fonctions est une bête chaîne
  61.    de caractères qui est une suite d'option et de type d'option : avec ou
  62.    sans argument.
  63.  
  64.       Par exemple si votre programme s'emploie ainsi :
  65.  
  66.       truc [-h] [-i] [-f <fichier>] [-o <dest>] [-v] [-R] <mode> [<type>]
  67.  
  68.    alors le traitement automatique des options est réalisé grâce à la
  69.    chaine C suivante :
  70.  
  71.       "h i f;o;v R "
  72.  
  73.    ou encore, car l'ordre des options y est sans importance :
  74.  
  75.       "R f;h i o;v "
  76.  
  77.       Les caractères en position impaire sont les lettres des options. Un
  78.    point-virgule après une lettre indique que l'option prend un argument,
  79.    un espace qu'elle n'en prend pas. Attention, le caractère après la lettre
  80.    d'option est strictement obligatoire.
  81.  
  82.       Attention aussi au fait que les options tiennent compte des majuscules
  83.    et des minuscules, et que normalement vous n'avez le droit qu'à des
  84.    lettres (ce dernier point n'est pas vérifiée mais c'est au programmeur
  85.    de décider ce qu'il fait en la matière).
  86.  
  87.       En respect des conventions sus-citées, les lignes de commandes ci-
  88.    dessous sont acceptées (et correctement traitées ;-) (sous réserve bien
  89.    sûr que truc trouve que le nombre de ses arguments lui convienne) :
  90.  
  91.       truc -i -hR -f merci mon gars
  92.  
  93.       truc de_rien camarade
  94.  
  95.       truc -o hara -hRi -f raime sapeur Camembert
  96.  
  97.       truc -h -  ---> ici - signifie entrée standard et n'est pas une option
  98.  
  99.       truc -h -o brien -- -i     --> -- indique la fin des options et donc
  100.                                      -i est le premier argument
  101.  
  102.       truc -hi -o -i dabord    --> l'argument d'une option à argument est
  103.                                    entièrement libre. -i est ici l'argument
  104.                                    de l'option o.
  105.  
  106.    Mais les suivantes ne le sont pas :
  107.  
  108.       truc -hRo hara kiri  ---> les options à arguments doivent être isolées
  109.  
  110.       truc -hRi -hv virus  ---> pas de répétition d'option
  111.  
  112.       truc -ohara sant     ---> pas d'argument collé à l'option
  113.  
  114.       truc -h - -i trema   ---> le - est considéré comme une option vide
  115.                                 Ceci est peut-être hors-norme (je n'ai plus
  116.                                 celles-ci sous les yeux) mais j'ai trouvé
  117.                                 que si - est suivi d'un groupe commençant
  118.                                 par -, alors le premier - résultait sans
  119.                                 aucun doute d'une erreur de frappe (c'est
  120.                                 en tous cas vrai pour - --). Ne pas faire
  121.                                 cette hypothèse simplifierait le codage.
  122.                                 J'attends vos réactions...
  123.  
  124.       Allez, voici une grammaire formelle de la chaîne de desciption :
  125.                   descripteur ::= descripteur | option
  126.                   option ::= (lettre type)
  127.                   lettre ::= { a...z A...Z }
  128.                   type ::= ( <espace> ; )
  129.  
  130.       Et pour exploiter tout ça ? Voyez le code source. En définissant TEST
  131.    sur la ligne de compilation, vous aurez un exécutable qui vous montrera
  132.    que je ne vous mentais pas. Comme le codage de la fonction main() le
  133.    montre, l'idée est de faire :
  134.  
  135.       if (parse(...) < 0) {
  136.          /* traitement des erreurs de syntaxe */
  137.          exit(1);
  138.       }
  139.       /* traitement des erreurs de logique propre au programme */
  140.       ...
  141.       /* fin du programme */
  142.       parse_cleanup();
  143.       exit(0);
  144.  
  145.       Pour plus de facilité, j'ai défini une structure regroupant les
  146.    données et permettant de déterminer précisément les erreurs éventuelles.
  147.  
  148.       Je vous laisse voir le code, il est inutile que je le recopie, je
  149.    pense. Faites bien attention cependant aux remarques qui suivent :
  150.       - un appel à parse_cleanup() sans appel précédent à parse() est
  151.          illégal et retourne un code d'erreur. Sans danger cependant.
  152.       - un appel à parse_cleanup() suite à un appel précédent à parse() qui
  153.          a echoué est illégal car parse() à déjà tout nettoyé, et un code
  154.          d'erreur est renvoyé. Sans danger cependant.
  155.       - deux appels consécutifs à la même fonction parse() ou parse_cleanup()
  156.          sont interdits et le second appel renvoit un code d'erreur. Sans
  157.          danger cependant.
  158.       - l'appel à parse_cleanup() sert à libérer la mémoire allouée par
  159.          parse() dans le cas où celui-ci a réussi. N'oublier pas de
  160.          l'appeler, même si par exemple les options mises ne respectent pas
  161.          la logique de votre programme. Regardez le main() donné en exemple.
  162.  
  163.       Pour utiliser ces deux fonctions, il est nécessaire qu'elles soient
  164.    compilées à part et de faire l'édition de lien avec le fichier objet
  165.    résultant, afin de garantir les procédés de vérification de séquence
  166.    d'appel indiqués précédemment.
  167.  
  168.       J'ai défine plusieurs drapeaux pour la compilation du module parse.o :
  169.  
  170.       NO_PARSE_ERR_MESS : s'il est défini, les messages d'erreur n'existent
  171.          pas. Vous n'aurez que les codes d'erreurs.
  172.       ENGLISH : s'il est défini et s'il y a des messages d'erreurs, ceux-ci
  173.          seront en anglais.
  174.       ERR_MESS_WITHOUT_LETTER : s'il est défini et qu'il y a des messages
  175.          d'erreurs, ceux-ci seront de simples chaînes de caractères à
  176.          imprimer directement. Par défault, ils comportent un %s pour
  177.          mettre à la bonne place l'option fautive et doivent donc être
  178.          utilisées avec une fonction du type printf.
  179.  
  180.       Quand vous éditerez votre source, le seul drapeau à définir éven-
  181.    tuellement (et avant d'inclure parse.h) est NO_PARSE_ERR_MESS.
  182.  
  183.       parse() et parse_cleanup() ne sont pas domaine public (car je ne veux
  184.    pas qu'un croquant m'en dépossède) mais sont librement redistribuables
  185.    et freeware. Leur emploi est encouragé chaque fois qu'une syntaxe de
  186.    type Unix est souhaitée (moi je n'ai jamais pu supporter getopt() car
  187.    il ne supporte pas bien les changement de syntaxe (ou alors je ne sais
  188.    pas m'en servir, mais de toute façon mon système est à la fois plus
  189.    simple, plus intuitif et plus performant.)). Il n'est pas autorisé de
  190.    le diffuser sans cette documentation ou pour un tarif excédant le prix
  191.    du support, la référence étant les disquettes AmigaLibDisk distribuées
  192.    par Fred Fish.
  193.  
  194.       Allez, bonne programmation en C. Si c'est en autre chose, vous avez
  195.    toute latitude pour le faire. Envoyez moi alors votre traduction, ce
  196.    serait sympa de votre part. :^)
  197.  
  198.    Mon adresse :
  199.  
  200.       Jean-Pierre Rivière
  201.       13, rue Maison Dieu
  202.       75014 PARIS
  203.       FRANCE
  204.