% !TeX encoding = ISO-8859-1
% Ceci est la documentation du package "hlist"
%
% Fichier compilé avec pdflatex
\documentclass[french,a4paper,10pt]{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[margin=2cm]{geometry}
\usepackage[bottom]{footmisc}
\usepackage{libertine,boites,tikz,enumitem,MnSymbol,babel,xspace,listings,simplekv}
\usepackage[scaled=0.8]{luximono}
\frenchbsetup{og=«,fg=»}
\def\eTeX{\hbox{$\varepsilon$-\TeX}}
\def\SKV{\texttt{\skvname}\xspace}
\makeatletter
\def\code{\expandafter\code@i\string}
\def\code@i#1{%
	\begingroup
		\par\nobreak\medskip\parindent0pt
		\leftskip.1\linewidth
		\make@car@active\^^I{\leavevmode\space\space\space\space}%
		\let\do\@makeother \dospecials
		\ttfamily\small\@noligs
		\make@car@active\<{\begingroup$\langle$\itshape}%
		\make@car@active\>{$\rangle$\endgroup}%
		\obeylines\obeyspaces
		\def\code@ii##1#1{##1\par\medbreak\endgroup}%
		\code@ii
}
\long\def\grab@toks#1\relax{\gdef\right@content{#1}}

\newcommand\disable@lig[1]{%
	\catcode`#1\active
	\begingroup
		\lccode`\~`#1\relax
		\lowercase{\endgroup\def~{\leavevmode\kern\z@\string#1}}%
}

\newcommand\make@car@active[1]{%
	\catcode`#1\active
	\begingroup
		\lccode`\~`#1\relax
		\lowercase{\endgroup\def~}%
}

\newcommand\exemple{%
	\begingroup
	\parskip\z@
	\exemple@}

\newcommand\exemple@{%
	\medbreak\noindent
	\begingroup
		\let\do\@makeother\dospecials
		\make@car@active\ { {}}%
		\make@car@active\^^M{\par\leavevmode}%
		\make@car@active\^^I{\space\space}%
		\make@car@active\,{\leavevmode\kern\z@\string,}%
		\make@car@active\-{\leavevmode\kern\z@\string-}%
		\make@car@active\>{\leavevmode\kern\z@\string>}%
		\make@car@active\<{\leavevmode\kern\z@\string<}%
		\@makeother\;\@makeother\!\@makeother\?\@makeother\:% neutralise frenchb
		\exemple@@
}

\newcommand\exemple@@[1]{%
	\def\@tempa##1#1{\exemple@@@{##1}}%
	\@tempa
}

\newcommand\exemple@@@[1]{%
	\xdef\the@code{#1}%
	\endgroup
		\begingroup
			\fboxrule0.4pt \fboxsep=5pt
			\let\breakboxparindent\z@
			\def\bkvz@top{\hrule\@height\fboxrule}%
			\def\bkvz@bottom{\hrule\@height\fboxrule}%
			\let\bkvz@before@breakbox\relax
			\def\bkvz@set@linewidth{\advance\linewidth\dimexpr-2\fboxrule-2\fboxsep\relax}%
			\def\bkvz@left{\vrule\@width\fboxrule\kern\fboxsep}%
			\def\bkvz@right{\kern\fboxsep\vrule\@width\fboxrule}%
			\breakbox
				\kern.5ex\relax
				\begingroup
					\ttfamily\small\the@code\par
				\endgroup
				\kern3pt
				\hrule height0.1pt width\linewidth depth0.1pt
				\vskip5pt
				\newlinechar`\^^M\everyeof{\noexpand}\scantokens{#1}\par
			\endbreakbox
		\endgroup
	\medbreak
	\endgroup
}
\begingroup
	\catcode`\<13 \catcode`\>13
	\gdef\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
		\bgroup
			\verb@eol@error \let\do\@makeother \dospecials
			\verbatim@font\@noligs
			\catcode`\<13 \catcode`\>13 \def<{\begingroup$\langle$\itshape}\def>{\/$\rangle$\endgroup}%
			\@ifstar\@sverb\@verb}
\endgroup
\def\longfrhlstdate@i#1/#2/#3\@nil{\number#3\relax\space \ifcase#2 \or janvier\or février\or mars\or avril\or mai\or juin\or juillet\or aout\or septembre\or octobre\or novembre\or décembre\fi\space#1}
\edef\longfrhlstdate{\expandafter\longfrhlstdate@i\skvdate\@nil}
\def\<#1>{$\langle$\textit{#1}$\rangle$}
\makeatother

\begin{document}
\parindent=0pt
\thispagestyle{empty}
\begin{titlepage}
	\begingroup
		\centering
		\null\vskip.25\vsize
		{\large\bfseries L'extension pour \TeX/\LaTeX\par \Huge \skvname\par}
		\bigbreak
		v \skvver
		\smallbreak
		\longfrhlstdate
		\vskip1.5cm
		Christian \bsc{Tellechea}\par
		\texttt{unbonpetit@netc.fr}\par
	\endgroup
	\vskip2cm
	\leftskip=.2\linewidth \rightskip=.2\linewidth \small
	Cette petite extension est une implémentation d'un système dit  à «clé/valeurs» pour \TeX{} ou \LaTeX. Aucune fioriture inutile n'a été codée, elle comporte juste l'essentiel.
\end{titlepage}

\section{Clés, valeurs}
Lorsqu'une macro doit recevoir des paramètres dont le nombre n'est pas fixe ou connu, il est commode de procéder par \<clés> et \<valeurs>. Beaucoup d'extensions allant en ce sens existent déjà.

Le but de celle-ci n'est pas de grossir le nombre déjà trop grand de ces extensions, c'est simplement un morceau de l'extension \texttt{hlist} qui a été converti en extension car ce système \<clé>/\<valeurs> est également utilisé par l'extension \texttt{scratch}.\medskip

Voici brièvement les définitions et les limitations des structures mises à disposition :

\begin{itemize}
	\item une \<clé> est un mot désignant un paramètre; il est formé de préférence avec des caractères de code de catégorie 11 (lettres), 12 (autres caractères sauf la virgule) et 10 (l'espace). On peut cependant y mettre des caractères ayant d'autres codes de catégorie, dans la limitation de ce qui est admis dans la primitive \verb|\detokenize|;
	\item la syntaxe pour assigner une \<valeur> à une \<clé> est : \hbox{\<clé>=\<valeur>};
	\item les espaces qui précèdent et qui suivent la \<clé> et la \<valeur> sont ignorés, mais \emph{pas ceux} qui se trouvent à l'intérieur de la \<clé> ou de la \<valeur>;
	\item une \<valeur> est un \<code> arbitraire;
	\item si une \<valeur> est entourée d'accolades, ces dernières seront retirées : \verb|<clé>=<valeur>| est donc équivalent à \verb|<clé>={<valeur>}|;
	\item lorsque plusieurs couples de \<clés>/\<valeurs> doivent être spécifiés, ils sont séparés les uns des autres par des virgules;
	\item une virgule ne peut figurer dans une \<valeur> que si la virgule est dans un niveau d'accolades; par exemple, \verb|foo=1,5| n'est pas valide car la \<valeur> s'étend jusqu'au 1. Il faudrait écrire \verb|foo={1,5}| pour spécifier une valeur de \verb|1,5|;
	\item lorsqu'une valeur est entourée de \emph{plusieurs} d'accolades, seul le niveau externe est retiré;
	\item les \<valeurs> sont stockées \emph{telles qu'elles sont lues} ; en particulier, aucun développement n'est effectué;
	\item les définitions sont \emph{locales} : par conséquent, toute \<clé> définie ou modifiée dans un groupe est restaurée à son état antérieur à la sortie du groupe;
	\item des \<clé>/\<valeurs> destinées à une même macro ou à un même usage doivent être regroupées dans un ensemble dont on choisit le nom. Un tel ensemble est appelé \<trousseau>.
\end{itemize}

\section{Commandes mises à disposition}

\paragraph{La macro \texttt{\char`\\setKVdefault}}
Cette commande est un préalable à toute utilisation de \<clés> puisqu'elle définit un \<trousseau> contenant des \<clés> et leurs \<valeurs> par défaut.

On écrit
\begin{center} \verb|\setKVdefault[<trousseau>]{<clé 1>=<valeur 1>,<clé 2>=<valeur 2>,...,<clé i>=<valeur i>}|
\end{center}

Il faut noter que
\begin{itemize}
	\item l'argument entre accolades contenant les \<clés> et les \<valeurs> ne peut pas être vide;
	\item le nom du \<trousseau>, bien qu'entre crochet, est \emph{obligatoire}, mais il peut être vide bien que cela ne soit pas conseillé;
	\item si plusieurs \<clés> sont identiques, seule la dernière \<valeur> sera prise en compte;
	\item les \<valeurs> peuvent être booléennes, auquel cas, elles \emph{doivent} être «\texttt{true}» ou «\texttt{false}» en caractères de catcode 11;
	\item si une \<valeur> est omise, elle est comprise comme étant «\texttt{true}». Ainsi, écrire
	\code|\setKVdefault[foo]{mon bool}|
	est équivalent à
	\code|\setKVdefault[foo]{mon bool = true}|
	\item il est \emph{déconseillé} d'exécuter plusieurs fois \verb|\setKVdefault| pour le même \<trousseau>. Si cela est indispensable, il convient de redéfinir \emph{toutes} les \<clés> qui figuraient dans les précédents appels de \verb|\setKVdefault|.
\end{itemize}

\paragraph{La macro \texttt{\char`\\setKV}}
Cette macro fonctionne selon les mêmes principes et limitations que \verb|\setKVdefault|, sauf qu'elle redéfinit une ou plusieurs \<clés> dont les \<valeurs> ont précédemment été définies par \verb|\setKVdefault|.

Si une \<clé> n'a pas été prédéfinie par \verb|\setKVdefault|, une erreur sera émise.

\paragraph{La macro \texttt{\char`\\useKV}}
Cette macro purement développable renvoie la \<valeur> préalablement associée à une \<clé> dans un \<trousseau>:
\code|\useKV[<trousseau>]{<clé>}|

Il faut noter que
\begin{itemize}
	\item si la \<clé> n'a pas été prédéfinie par \verb|\setKVdefault|, une erreur sera émise;
	\item si la \<clé> est booléenne, le texte «\texttt{true}» ou «\texttt{false}» sera renvoyé;
	\item il faut 2 développements à \verb|\useKV[<trousseau>]{<clé>}| pour donner la \<valeur> associée à la \<clé>.
\end{itemize}

\exemple|\setKVdefault[foo]{nombre = 5 , lettres= AB \textit{CD} , mon bool}
a) \useKV[foo]{nombre}.\qquad   b) \useKV[foo]{lettres}.\qquad   c) \useKV[foo]{mon bool}.\par
\setKV[foo]{lettres = X Y Z \textbf{123} }
a) \useKV[foo]{nombre}.\qquad   b) \useKV[foo]{lettres}.\qquad   c) \useKV[foo]{mon bool}.|

\paragraph{La macro \texttt{\char`\\useKVdefault}}
L'exécution de cette macro par \verb|\useKVdefault[<trousseau>]| réinitialise toutes les \<clés> du \<trousseau> aux \<valeurs> qui ont été définies lors de l'exécution \verb|\setKVdefault|.

\paragraph{La macro \texttt{\char`\\ifboolKV}}
Cette macro permet, selon la valeur d'une \<clé booléenne>, d'exécuter un des deux \<codes> donnés. La syntaxe est
\code|\ifboolKV[<trousseau>]{<clé>}{<code si "true">}{<code si "false>}|

La macro est purement développable, elle nécessite 2 développements pour donner l'un des deux codes, et exige que la \<clé> soit booléenne sans quoi un message d'erreur est émis.

\paragraph{La macro \texttt{\char`\\showKV}}
Cette commande écrit dans le fichier \texttt{log} la \<valeur> assignée à une \<clé> d'un \<trousseau>:
\code|\showKV[<trousseau>]{<clé>}|

Si la \<clé> n'est pas définie, «\texttt{not defined}» est affiché dans le fichier log.

\section{Un exemple d'utilisation}
Voici comment on pourrait programmer une macro qui affiche un cadre sur une ligne. Pour cela les \<clés> suivantes seront utilisées:
\begin{itemize}
	\item le booléen \texttt{inline} qui affichera le cadre dans le texte s'il est vrai et sur une ligne dédié s'il est faux;
	\item \texttt{left code} et \texttt{right code} qui sont deux codes exécutés avant et après le cadre si le booléen est faux (par défaut : \verb|\hfill| et \verb|\hfill| pour un centrage sur la ligne);
	\item \texttt{sep} qui est une dimension mesurant la distance entre le texte et le cadre (par défaut \texttt{3pt});
	\item \texttt{width} qui est la largeur des traits du cadre (par défaut \texttt{0.5pt}).
\end{itemize}

\exemple|\setKVdefault[frame]{inline , left code = \hfill, right code = \hfill, sep = 3pt, width=0.5pt }
\newcommand\frametxt[2][]{%
	\setKV[frame]{#1}% lit les arguments optionnels
	\ifboolKV[frame]{inline}{}{\par\noindent\useKV[frame]{left code}}%
	\fboxsep=\useKV[frame]{sep}\relax
	\fboxrule=\useKV[frame]{width}\relax
	\fbox{#2}%
	\ifboolKV[frame]{inline}{}{\useKV[frame]{right code}\null\par}%
}
Un essai en ligne par défaut \frametxt{essai} puis un autre \frametxt[sep=5pt,width=2pt]{essai}
et un dernier \frametxt[sep=0.5pt]{essai}.

\useKVdefault[frame]% revenir au valeurs par défaut
Un essai centré \frametxt[inline = false]{essai centré}
un autre fer à gauche \frametxt[left code={}]{essai à gauche}
un dernier indenté \frametxt[left code=\hskip 5em, right code={}, sep=1pt, width=2pt]{essai indenté}|


\section{Le code}
Le code ci-dessous est l'exact verbatim du fichier \verb|simplekv.tex| :

\lstinputlisting[
		language=TeX,
		moretexcs={unless,ifcsname,ifdefined,detokenize,numexpr,dimexpr,glueexpr,unexpanded},
		basicstyle=\small\ttfamily\color{black!25},
		identifierstyle=\bfseries\color{white},%
		backgroundcolor=\color{black!85},
		keywordstyle=\bfseries\color{orange},
		commentstyle=\color{cyan!66},
		columns=fixed,
		alsoletter={\_},
		tabsize=2,
		extendedchars=true,
		showspaces=false,
		showstringspaces=false,
		numbers=left,
		numberstyle=\tiny\ttfamily\color{black},
		breaklines=true,
		prebreak={\hbox{$\rhookswarrow$}},
		breakindent=3em,
		breakautoindent=true,
		xleftmargin=1em,
		xrightmargin=0pt,
		lineskip=0pt,
		numbersep=1em,
		classoffset=1,
		alsoletter={\_},
		morekeywords={setKVdefault,setKV,useKVdefault,useKV,ifboolKV,},
		keywordstyle=\bfseries\color{red!85!black},
		classoffset=0,
		]{simplekv.tex}
\end{document}