summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/starray/doc/starray.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/starray/doc/starray.tex')
-rw-r--r--macros/latex/contrib/starray/doc/starray.tex101
1 files changed, 94 insertions, 7 deletions
diff --git a/macros/latex/contrib/starray/doc/starray.tex b/macros/latex/contrib/starray/doc/starray.tex
index a18117ac37..d52e6ec101 100644
--- a/macros/latex/contrib/starray/doc/starray.tex
+++ b/macros/latex/contrib/starray/doc/starray.tex
@@ -15,7 +15,7 @@
%%
%% The Current Maintainer of this work is Alceu Frigeri
%%
-%% This is version 1.1 (2023/05/16)
+%% This is version 1.2 (2023/05/20)
%%
%% The list of files that compose this work can be found in the README.md file at
%% https://ctan.org/pkg/starray
@@ -29,7 +29,7 @@
\RequirePackage[inline]{enumitem}
\SetEnumitemKey{miditemsep}{parsep=0ex,itemsep=0.4ex}
-
+\RequirePackage[hidelinks,hypertexnames=false]{hyperref}
\begin{document}
\tstitle{
author={Alceu Frigeri\footnote{\tsverb{https://github.com/alceu-frigeri/starray}}},
@@ -62,9 +62,8 @@ The current implementation, albeit also complex, tries to reach a balance betwee
\end{tsremark}
\begin{tsremark}[\color{red}Important:]
- \textsl{Expandability}, unfortunately most/all defined functions are not ''fully expandable'', in particular, the conditional/branching functions aren't. This means, among other things, one can't have a 'predicated variant' of any conditional defined in this (for instance, to be used in a boolean expression).
+ \textsl{Expandability}, unfortunately most/all defined functions are not ''fully expandable'', in particular, most conditional/branching functions aren't, with just a few exceptions (marked with a star \ding{72}, as per \tsobj[pkg]{expl3} documentation convention).
- For what it's worth, all user visible functions are 'protected'.
\end{tsremark}
@@ -100,12 +99,27 @@ By default, the \tsobj[pkg]{starray} package only generates ''warnings'', with \
\tsmacro{\starray_new:n}{starray}
\tsmacro{\starray_new:nTF}{starray,if-true,if-false}
\end{codesyntax}
-\end{codedescribe}
Creates a new \tsobj[marg]{starray} or raises a warning if the name is already taken. The declaration (and associated property lists) is global. The given name is referred (in this text) as the \tsobj[marg]{starray-root} or just \tsobj[marg]{root}.
+\end{codedescribe}
\begin{tsremark}
A warning is raised (see \ref{pack:options}) if the name is already taken. The branching version doesn't raise any warning.
\end{tsremark}
+\subsection{Conditionals}\label{conditionals:exist}
+\begin{codedescribe}[code,EXP,new=2023/05/20]{\starray_if_exist_p:n,\starray_if_exist:nTF,\starray_if_valid_p:n,\starray_if_valid:nTF}
+\begin{codesyntax}%
+\tsmacro{\starray_if_exist_p:n}{starray}
+\tsmacro{\starray_if_exist:nTF}{starray,if-true,if-false}
+\tsmacro{\starray_if_valid_p:n}{starray}
+\tsmacro{\starray_if_valid:nTF}{starray,if-true,if-false}
+\end{codesyntax}
+\tsobj{\starray_if_exist:nTF} only tests if \tsobj[marg]{starray} (the base property) is defined. It doesn't verifies if it really is a \tsobj[pkg]{starray}.
+\tsobj{\starray_if_valid:nTF} further tests if an internal boolean (\tsobj[key]{is\_starray}) is also defined. This doesn't necessary mean it is a \tsobj[pkg]{starray} or if it's a really valid one (chances are that it is, but...), see \tsobj{\starray_term_syntax:nTF}, section \ref{conditionals:terms}, for a more reliable validity test.
+\end{codedescribe}
+\begin{tsremark}
+The predicate versions, \tsobj{_p}, expand to either \tsobj{\prg_return_true:} or \tsobj{\prg_return_false:}.
+\end{tsremark}
+
\section{Defining and initialising a starray structure}\label{pack:def}
\begin{codedescribe}{\starray_def_prop:nnn,\starray_def_prop:nnnTF}
@@ -448,6 +462,17 @@ Before the reset \tsobj[marg]{st-root.subY.subYYY} was equivalent to \tsobj[marg
A warning is raised (see \ref{pack:options}) in case of a \tsobj[marg]{starray-ref} syntax error. The branching version doesn't raise any warning.
\end{tsremark}
+\begin{codedescribe}[code,EXP,new=2023/05/20]{\starray_parsed_get_iter:}
+\begin{codesyntax}%
+\tsobj{\starray_parsed_get_iter:}{}
+\end{codesyntax}
+\tsobj{\starray_parsed_get_iter:} will place in the current iterator's value, using \tsobj{\int_use:N}, of the last parsed term in the input stream.
+\end{codedescribe}
+\begin{tsremark}[\color{red}Warning:]
+This can be used after any command which 'parses a term', for instance \tsobj{\starray_term_syntax:n}, see section \ref{conditionals:terms}, but it only makes sense (and returns a reliable/meaningful result) IF the last parser operation was successfully executed.
+\end{tsremark}
+
+
\begin{codedescribe}{\starray_get_cnt:n,\starray_get_cnt:nN,\starray_get_cnt:nNTF}
\begin{codesyntax}%
\tsmacro{\starray_get_cnt:n}{starray-ref}
@@ -460,6 +485,17 @@ A warning is raised (see \ref{pack:options}) in case of a \tsobj[marg]{starray-r
A warning is raised (see \ref{pack:options}) in case of a \tsobj[marg]{starray-ref} syntax error. The branching version doesn't raise any warning.
\end{tsremark}
+\begin{codedescribe}[code,EXP,new=2023/05/20]{\starray_parsed_get_cnt:}
+\begin{codesyntax}%
+\tsobj{\starray_parsed_get_cnt:}{}
+\end{codesyntax}
+\tsobj{\starray_parsed_get_cnt:} will place the current number of terms, using \tsobj{\int_use:N}, of the last parsed term, in the input stream.
+\end{codedescribe}
+\begin{tsremark}[\color{red}Warning:]
+This can be used after any command which 'parses a term', for instance \tsobj{\starray_term_syntax:n}, see section \ref{conditionals:terms}, but it only makes sense (and returns a reliable/meaningful result) IF the last parser operation was successfully executed.
+\end{tsremark}
+
+
\section{Changing and recovering starray properties}\label{pack:get/set}
\begin{codedescribe}{\starray_set_prop:nnn,\starray_set_prop:nnV,\starray_set_prop:nnnTF,\starray_set_prop:nnVTF,\starray_gset_prop:nnn,\starray_gset_prop:nnV,\starray_gset_prop:nnnTF,\starray_gset_prop:nnVTF}
@@ -537,17 +573,68 @@ Also note that the above example is fully equivalent to:
\tscode*[codeprefix=~]{keyval.demo9}
+\begin{codedescribe}{\starray_get_prop:nn,\starray_get_prop:nnN,\starray_get_prop:nnNTF}
+\begin{codesyntax}%
+\tsmacro{\starray_get_prop:nn}{starray-ref,key}
+\tsmacro{\starray_get_prop:nnN}{starray-ref,key,tl-var}
+\tsmacro{\starray_get_prop:nnNTF}{starray-ref,key,tl-var,if-true,if-false}
+\end{codesyntax}
+\tsmacro{\starray_get_prop:nn}{starray-ref,key} places the value of \tsobj[marg]{key} in the input stream.
+\tsmacro{\starray_get_prop:nnN}{starray-ref,key,tl-var} recovers the value of \tsobj[marg]{key} and places it in \tsobj[marg]{tl-var} (a token list variable), this is specially useful in conjunction with \tsobj{\starray_set_prop:nnV}, whilst the \tsobj{\starray_get_prop:nnNTF} version branches accordly.
+\end{codedescribe}
+\begin{tsremark}
+In case of a syntax error, or \tsobj[marg]{key} doesn't exist, an empty value is left in the stream (or \tsobj[marg]{tl-var}).
+\end{tsremark}
+\begin{tsremark}
+A warning is raised (see \ref{pack:options}) in case of a \tsobj[marg]{starray-ref} syntax error. The branching version doesn't raise any warning.
+\end{tsremark}
+
+
+\begin{codedescribe}[code,EXP,new=2023/05/20]{\starray_parsed_get_prop:n}
+\begin{codesyntax}%
+\tsmacro{\starray_parsed_get_prop:nn}{key}
+\end{codesyntax}
+\tsmacro{\starray_parsed_get_prop:n}{key} places the value of \tsobj[marg]{key}, if it exists, from the last parsed term, in the input stream.
+\end{codedescribe}
+\begin{tsremark}[\color{red}Warning:]
+This can be used after any command which 'parses a term', for instance \tsobj{\starray_term_syntax:n}, see section \ref{conditionals:terms}, but it only makes sense (and returns a reliable/meaningful result) IF the last parser operation was successfully executed.
+\end{tsremark}
+
-\section{Additional Conditionals}\label{pack:extra}
+\section{Additional Commands and Conditionals}\label{conditionals:terms}
\begin{codedescribe}{\starray_if_in:nnTF,\starray_term_syntax:nTF}
\begin{codesyntax}%
\tsmacro{\starray_if_in:nnTF}{starray-ref,key,if-true,if-false}
\tsmacro{\starray_term_syntax:nTF}{starray-ref,if-true,if-false}
\end{codesyntax}
+The \tsmacro{\starray_if_in:nnTF}{starray-ref,key,\ldots,\ldots} tests if a given \tsobj[marg]{key} is present, whilst \tsmacro{\starray_term_syntax:nTF}{starray-ref,if-true,if-false} just verifies if the \tsobj[marg]{starray-ref} syntax is valid or not, branching accordly.
\end{codedescribe}
-The \tsmacro{\starray_if_in:nnTF}{starray-ref,key,\ldots,\ldots} tests if a given \tsobj[marg]{key} is present, whilst \tsmacro{\starray_term_syntax:nTF}{starray-ref,\ldots,\ldots} just verifies if the \tsobj[marg]{starray-ref} syntax is valid or not, branching accordly.
+\begin{codedescribe}{\starray_term_syntax:n}
+\begin{codesyntax}%
+\tsmacro{\starray_term_syntax:n}{starray-ref}
+\end{codesyntax}
+This will just parse a \tsobj[marg]{starray-ref} reference, and set interval variables so that commands like \tsobj{\starray_parsed_} can be used.
+\end{codedescribe}
+\begin{tsremark}[\color{red}Warning:]
+The main idea is to allow some expandable commands, but be aware that all \tsobj{\starray_} commands that use a \tsobj[marg]{starray-ref} use the very same parser variables.
+\end{tsremark}
+
+
+\begin{codedescribe}[code,EXP,new=2023/05/20]{\starray_parsed_if_in_p:n,\starray_parsed_if_in:nTF}
+\begin{codesyntax}%
+\tsmacro{\starray_parsed_if_in_p:nTF}{key}
+\tsmacro{\starray_parsed_if_in:nTF}{key,if-true,if-false}
+\end{codesyntax}
+This will test if the given \tsobj[key]{key} is present in the "last parsed term".
+\end{codedescribe}
+\begin{tsremark}
+The predicate version, \tsobj{_p}, expands to either \tsobj{\prg_return_true:} or \tsobj{\prg_return_false:}.
+\end{tsremark}
+\begin{tsremark}[\color{red}Warning:]
+This can be used after any command which 'parses a term', for instance \tsobj{\starray_term_syntax:n}, but it only makes sense (and returns a reliable/meaningful result) IF the last parser operation was successfully executed.
+\end{tsremark}
\section{Showing (debugging) starrays }\label{pack:show}