CCLARGS(1)		     UTILITAIRE	RPN		    CCLARGS(1)

NOM
     cclargs - recuperation des	parametres d'appel a un	script.

USAGE
   eval	`cclargs {$0} {-+} {"[help_general]"}
    <-cle{+/_} {"def1"}	{"def2"} {"[help_cle]"}> ++ $*`

     NOTE: - un	element	optionnel est indique par les symboles { }
	   - la	 presence des symboles < > englobant un	element	indique	que
	     l'on peut repeter cet element une ou plusieurs fois.

DESCRIPTION
     cclargs - est  un	utilitaire  permettant	de recuperer les parametres
d'appel	 d'un  script executant	a partir du BOURNE SHELL et d'en faire	des
variables locales au script.   On utilise cclargs lorsqu'on desire produire
des  scripts dont l'invocation permet  le passage de parametres	de type	mot
clef.	 cclargs  permet  au concepteur	d'un script de	donner	une  valeur
initiale a une variable	et permet a l'usager du	script de changer a volonte
la valeur de cette variable.

     L'execution de cclargs comporte deux volets.   Dans un premier  temps,
cclargs	initialise la definition des differentes clefs et en cree une sorte
de dictionaire.	  Deuxiemement,	 cclargs recupere les parametres de l'appel
au script et fait les associations valeur-clef qui s'imposent.

     cclargs dresse  le	 dictionnaire de clefs a partir	 des specifications
fournies  par  le  concepteur du script.   Dans	 l'appel  a  cclargs,	les
descriptions  de  clefs	se retrouvent entre les	symboles < et  >  (voir	 la
ligne prototype	ci-dessous).

     Les  parametres  passes  par un usager lors d'un appel  au	 script	 se
retrouvent dans	$*.

     La	 recuperation des parametres de	la sequence d'appel a un script	 se
fait de	trois facons.  On recupere tout	d'abord	les parametres positionnels
c'est  a  dire	les variables qui ne sont pas associees	a  une	clef.	 On
recupere  ensuite  les parametres associes a un	mot clef  (recuperation	 en
mode  equivalence).   Finalement,  si le parametre --  apparait	lors de	 la
sequence d'appel,  on recupere tous les	arguments suivants et on les ajoute
a la  liste  des  parametres positionnels .  Lors de  l'appel  a  un script
utilisant cclargs,  tous les parametres	 positionnels doivent preceder	les
parametres de type mot	clef ou	etre a la suite	du parametre --	 qui,  lui,
doit necessairement suivre les parametres de type mot clef.

CCLARGS(1)		     UTILITAIRE	RPN		    CCLARGS(1)

UTILISATION
     Au	debut d'un script, on utilise un enonce	de la forme

     eval `cclargs {$0}	{-+} {"[help_general]"}\
     <-kle{+/_}	{"def1"} {"def2"} {"[help_cle]"} > ++ $*`

	Notes:	les symboles < > indique qu'on peut repeter la sequence	a
	       volonte.
	       un argument optionnel se	trouve entre les symboles { }.

     DEFINITION	DES PARAMETRES

     $0		    ce	parametre optionnel suit  immediatement	 l'appel  a
		    cclargs.	Il represente le nom du	script presentement
		    en cours (le script	faisant	l'appel	a cclargs).  Si	 ce
		    parametre  est present,  il	se doit	d'etre en  premiere
		    position pour l'appel a cclargs.

     -+		    ce parametre  optionnel permet de forcer l'execution de
		    cclargs en mode plein-ecran.

     [help_general] ce	parametre contient une chaine de caracteres donnant
		    une	 breve description de l'utilite	du script.    Cette
		    chaine de  caractere  est  affichee	a l'ecran lorsqu'on
		    passe en  mode plein-ecran.	 On peut  inclure  dans	 la
		    chaine  les	caracteres \n afin de permettre	l'affichage
		    sur	 deux  lignes.	La chaine de caracteres	 doit  etre
		    entouree des caracteres [ et ]. Par	exemple:

		    "[script pour l'impression\nd'un fichier quelconque]"

		    Ce	parametre  ne doit jamais etre	place  en  premiere
		    position.

     -kle{+/_}	    represente	 le  nom  des  differentes clefs  que  l'on
		    desire  initialiser.   cclargs retournera au script	des
		    variables  locales qui porteront les memes noms que	les
		    clefs.    Si  le nom d'une	clef est suivi d'un  +
		    (-kle+),la valeur donnee a cette clef sera forcee a	des
		    lettres majuscules.	  Si le	nom de la clef est suivi du
		    symbole  de	soulignement _ (-kle_)	la valeur de  cette
		    clef sera toujours	en minuscules.	 Un nom	de clef	est
		    toujours precede du	signe moins (-).  Pour connaitre la
		    facon de disposer les valeurs a donner a une clef, voir
		    la	rubrique  DEFINITION   DES  VALEURS  DE	 CLEFS	ci-
		    dessous.

     def1	    premiere  valeur de	defaut que l'on	desire donner a	une
		    clef.   C'est cette	valeur qui sera	donnee a la clef si
		    son	 nom n'apparait	pas lors de la sequence	d'appel	 au
		    script. Parametre optionnel.

CCLARGS(1)		     UTILITAIRE	RPN		    CCLARGS(1)

     def2	    deuxieme  valeur de	defaut que l'on	desire donner a	une
		    clef.   C'est cette	valeur qui sera	attribuee a la clef
		    si	son  nom est present lors de l'appel au	 script	 et
		    qu'il   n'est   pas	 accompagne  par  une	valeur	 de
		    remplacement. Parametre optionnel.

		    NOTE:    Le	  concepteur  d'un   script   peut   rendre
			     obligatoire l'attribution	d'une  valeur a	une
			     clef  en  donnant	a celle-ci  une	 valeur	 de
			     defaut  (def1   et/ou def2)   egale  a  quatre
			     virgules ',,,,'.	Si l'utilisateur  du script
			     omet   de	donner	une  valeur  a	 une   clef
			     obligatoire,  cclargs forcera alors  l'edition
			     en	  mode	plein-ecran  afin  de  permettre  a
			     l'usager  de donner une valeur aux	 clefs	non
			     initialisees.

			     Exemples:

			       cclargs $0  -cle1 ",,,,"	",,,," ++ $*

			       cclargs $0 -user	${USER:-,,,,} ",,,," ++	$*

			     Si	  une	clef   obligatoire  n'a	  pas	ete
			     initialisee  et que l'execution du	 script	 se
			     fait  en  lot ( pas associee a  un	 terminal),
			     cclargs mettra fin	au travail.

     [help_cle]	    help_cle   est  une	 chaine	 de  caracteres	  decrivant
		    l'utilisation  d'une clef quelconque.   Cette chaine de
		    caracteres	apparait  a l'ecran,  en mode  plein-ecran,
		    lorsque l'usager tape Control-A.

     ++		    indique la fin de la section de definition des clefs.

     $*		    contient  la liste des parametres ayant  servi  lors de
		    l'appel au script.

     cclargs retournera	a l'environnement du script la liste des parametres
positionnels ayant servi a l'appel ainsi qu'une	serie de variables  locales
ayant	pour  noms  les	differents noms	de clefs utilises  pour	 l'appel  a
cclargs.    On pourra donc pour	le reste du script utiliser  ces  variables
directement en les invoquant par leur nom precede de $.	 Par exemple,

			echo valeur de kle1 = $kle1

     Dans  le  script,	on retrouvera les parametres  positionnels  a  leur
position respective soit $1, $2,... Le nombre d'arguments positionnels	est
contenu	dans la	variable $#.

CCLARGS(1)		     UTILITAIRE	RPN		    CCLARGS(1)

DEFINITION DES VALEURS DE CLEFS
     Lors de l'attribution des valeurs de defaut def1 et def2 a	l'interieur
d'un   script,	  ou sur la ligne de commande invoquant	un script utilisant
cclargs,   on  peut  donner  a une clef	une valeur simple  ou  des  valeurs
multiples que l'on separe par des espaces ou par deux points (:).   Si l'on
desire attribuer a une clef une	valeur negative, on doit preceder la valeur
d'un signe egal	ce qui permet de  faire	la difference entre un nom de  clef
(toujours precede  du signe moins)  et une valeur a donner a une clef.	 Si
une  valeur  negative  est  inseree dans une liste dont	les  elements  sont
separes	par deux points	et que cette valeur n'est pas le premier element de
la liste, le signe d'egalite devient alors superflu.

      On attribue une ou des valeurs  a	une clef de la facon suivante:

     -clef valeur
     -clef "valeur"
     -clef 'valeur'
     -clef valeur1 valeur2 valeur3
     -clef valeur1:valeur2:valeur3
     -clef=valeur1:valeur2:valeur3

     Par exemple:

     -clef 10 =-12 =-34	45
     -clef 10:-12:-34:45
     -clef =-12:10:-34:45
     -clef=-12:10:-34:45

	Lorsqu'on passe	en mode	plein-ecran, il	n'est plus necessaire de se
soucier	des regles enoncees ci-dessus.	 On n'a	simplement qu'a	separer	les
valeurs	multiples d'une	clef par des blancs.

     Par exemple:

     clef      -12 10 -34 45

CCLARGS(1)		     UTILITAIRE	RPN		    CCLARGS(1)

EXEMPLES

     Supposons	un  script imprime qui a pour fonction d'afficher a l'ecran
la  liste des parametres qu'il a recue lorsqu'il a ete appele.	  Remarquez
que pour ce script,  l'execution en mode plein-ecran n'a pas ete forcee	(la
clef -+	 est absente).	 L'usager peut toutefois passer	en mode	plein-ecran
en incluant la clef -+ lors de l'appel a imprime.

     Le	contenu	du script imprime est le suivant:

      ___________________________________________________________________
     |									 |
     |eval `cclargs $0 "[script	servant	a imprimer a l'ecran\nla liste \ |
     |des parametres recus a l'appel]"\					 |
     |	    -cle1 "cle1def1" "cle1def2"	\				 |
     |	    -cle2+ "cle2def1" "cle2def2" "[clef	en majuscules]"	\	 |
     |	    -cle3_ "cle3def1" "cle3def2" "[clef	forcee\na minuscule]" \	 |
     |	    -clenum "10" "=-10"	"[donner une valeur numerique]"\	 |
     |	    ++ $* `							 |
     |									 |
     |echo il y	a $# parametres	positionnels $*				 |
     |echo valeur de cle1      $cle1					 |
     |echo valeur de cle2      $cle2					 |
     |echo valeur de cle3      $cle3					 |
     |echo valeur de clenum    $clenum					 |
     |___________________________________________________________________|

     Voici maintenant une serie	d'appels possibles au script imprime et	les
resultats d'execution.

    Appel:	imprime

    Resultat:	il y a 0 parametres positionnels
		valeur de cle1	   cle1def1
		valeur de cle2	   CLE2DEF1
		valeur de cle3	   cle3def1
		valeur de clenum   10

    Appel:	imprime	posit1 posit2

    Resultat:	il y a 2 parametres positionnels  posit1 posit2
		valeur de cle1	   cle1def1
		valeur de cle2	   CLE2DEF1
		valeur de cle3	   cle3def1
		valeur de clenum   10

    Appel:	imprime	posit1 -cle1 -cle2 -cle3 -clenum -- posit2 posit3

    Resultat:	il y a 3 parametres positionnels  posit1 posit2	posit3
		valeur de cle1	   cle1def2
		valeur de cle2	   CLE2DEF2
		valeur de cle3	   cle3def2
		valeur de clenum   -10

CCLARGS(1)		     UTILITAIRE	RPN		    CCLARGS(1)

    Appel:	imprime	-cle1 Val1 -cle2 Val2 -cle3 Val3 -clenum 20:34:-40

    Resultat:	il y a 0 parametres positionnels
		valeur de cle1	   Val1
		valeur de cle2	   VAL2
		valeur de cle3	   val3
		valeur de clenum   20 34 -40

    Appel:	imprime	-cle1 val1 val2	val3 -clenum 22	33 44 =-23

    Resultat:	il y a 0 parametres positionnels
		valeur de cle1	   val1	val2 val3
		valeur de cle2	   CLE2DEF1
		valeur de cle3	   cle3def1
		valeur de clenum   22 33 44 -23

    Quelques exemples d'appels en mode plein-ecran:
      Chacun  de  ces appels fera apparaitre un	ecran ou l'usager  peut	 se
deplacer et modifier a sa guise	la valeur des clefs.

		imprime	-+
		imprime	posit1 posit2 -+
		imprime	posit1 posit2 -+ -- posit3 posit4
		imprime	posit1 -cle1 une valeur	-cle2 -+ -- posit2
		imprime	posit1 -cle1 -+	-cle2

NOTES
     Lorsque  le premier parametre passe a un script utilisant cclargs	est
-h, cclargs retourne la	sequence d'appel au script ainsi que les valeurs de
defaut	def1  et  def2.	 La sequence d'appel sera aussi	 retournee  lorsque
l'usager  d'un script utilise un nom de	clef qui n'a pas ete  defini.	Par
exemple,  pour connaitre la sequence d'appel du	script imprime,	 on entrera
la commande:

     imprime -h

pour obtenir:

     *** SEQUENCE D'APPEL ***

     imprime [positionnels]
		      -cle1 [cle1def1:cle1def2]
		      -cle2 [CLE2DEF1:CLE2DEF2]
		      -cle3 [cle3def1:cle3def2]
		      -clenum [10:-10]

AUTEURS
     Michel Valin, James Caveen	- RPN
     Walter Richards - pour le logiciel	de la portion mode plein-ecran.