Debian Codegraph @

texmf-dist/source/latex/soup/soup.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2017 by Thomas Simers
4 %
5 % This file may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of
13 % LaTeX version 2005/12/01 or later.
14 %
15 % \fi
16 %
17 % \iffalse
18 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
19 %<package>\ProvidesPackage{soup}[2019/04/05 v1.0.2 Package for word search puzzles.]
20 %
21 %<*driver>
22 \documentclass[full]{l3doc}
23 \usepackage[highlight]{soup}
24 \EnableCrossrefs
25 \CodelineIndex
26 \RecordChanges
27 \begin{document}
28 \DocInput{\jobname.dtx}
29 \end{document}
30 %</driver>
31 % \fi
32 % \changes{v1.0}{2017/01/10}{Initial version}
33 % \changes{v1.0.2}{2019/04/05}{Update to work with changes to expl3 kernel.}
34 % \GetFileInfo{soup.sty}
35 %
36 % \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
37 % \DoNotIndex{\@ne}
38 % \DoNotIndex{\advance,\begingroup,\catcode,\closein}
39 % \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup}
40 % \DoNotIndex{\noindent,\begin,\end,\ExplSyntaxOn,\ExplSyntaxOff,\equal,}
41 % \DoNotIndex{\par,\ProcessKeysPackageOptions,\ProcessKeysOptions,\vspace}
42 % \DoNotIndex{\draw,\node}
43 % \DoNotIndex{\RequirePackage,\NewDocumentCommand,\NewDocumentEnvironment}
44 %
45 %
46 % \title{The \pkg{soup} package
47 % \thanks{This document corresponds to \pkg{soup}~\fileversion,
48 % last revised~\filedate.}}
49 %
50 % \author{Thomas Simers
51 % \thanks{E-mail: \href{mailto:[email protected]}{[email protected]}}
52 % }
53 %
54 % \date{Released \filedate}
55 %
56 % \maketitle
57 %
58 %
59 % \vspace*{\fill}\noindent
60 % \begin{minipage}{1.8in}
61 % \begin{alphabetsoup}*[6][6][\sffamily]
62 % \hideinsoup{2}{2}{right}{s,o,u,p}
63 % \hideinsoup*{6}{2}{downleft}{s,o,u,p}
64 % \end{alphabetsoup}
65 % \end{minipage}
66 % \begin{minipage}{1.8in}
67 % \begin{numbersoup}*[6][6]{9}
68 % \hideinsoup{3}{3}{right}{1,0}
69 % \hideinsoup*{5}{3}{downleft}{1,0}
70 % \end{numbersoup}
71 % \end{minipage}
72 % \vspace*{\fill}
73 % \begin{minipage}{1.8in}
74 % \begin{homemadesoup}*[6][6]{
75 % $\nearrow$, $\searrow$, $\nwarrow$, $\swarrow$,
76 % $\uparrow$, $\downarrow$, $\leftarrow$, $\rightarrow$
77 % }[\small]
78 % \hideinsoup{6}{2}{downleft}{$\swarrow$,$\swarrow$,$\swarrow$,$\swarrow$}
79 % \end{homemadesoup}
80 % \end{minipage}
81 %
82 % \begin{abstract}
83 % The goal of \pkg{soup} is to generate the grid of letters for
84 % a word search, puzzle sometimes called ``alphabet soup'' (from which
85 % this package gets its name) or ``find-the-word.''
86 %
87 % In addition to supporting classic word searches, the soup can be
88 % filled with numbers or a user-defined set of glyphs.
89 %
90 % Full functionality relies on TikZ, but limited support without TikZ
91 % is available through a package option.
92 % \end{abstract}
93 %
94 % \vspace*{\fill}
95 % \clearpage{}
96 %
97 %
98 % \section{User Guide}
99 %
100 % The \pkg{soup} interface is rests primarily in two parts:
101 % The environments which determine the type of soup (alphabet, number,
102 % or homemade), and the shared macros for inserting and marking clues.
103 %
104 %
105 % \subsection{Load-Time Options}
106 %
107 %
108 % \begin{variable}{usetikz}
109 % \begin{syntax}
110 % \cs{usepackage} \oarg{usetikz=false} \{soup\}
111 % \end{syntax}
112 % Usually, \pkg{soup} will use TikZ to draw the soup grid and provide
113 % the optional highlighting of clues.
114 %
115 % To disable this, and use a non-TikZ fallback (the \env{tabular} environment),
116 % pass the option |usetikz=false| when loading \pkg{soup}.
117 % \end{variable}
118 %
119 %
120 % \begin{variable}{highlight}
121 % \begin{syntax}
122 % \cs{usepackage} \oarg{highlight=true} \{soup\}
123 % \end{syntax}
124 % As a puzzle generator, \pkg{soup} does not usually indicate the solution.
125 %
126 % To have \pkg{soup} highlight the solutions, pass the option |highlight|
127 % (or |highlight=true|) when loading \pkg{soup}.
128 %
129 % If TikZ is disabled, the solutions will be indicated with boldface letters.
130 % Note that if the the puzzle is drawn in boldface, this will hide the
131 % highlighting.
132 % \end{variable}
133 %
134 %
135 % \begin{variable}{highlightcolor}
136 % \begin{syntax}
137 % \cs{usepackage} \oarg{highlightcolor=\emph{color}} \{soup\}
138 % \end{syntax}
139 % Specify the fill color to be used when highlighting solutions (TikZ only).
140 %
141 % The default color is |orange|.
142 %
143 % Color mixes are fine here, too: |green!50!white|.
144 % \end{variable}
145 %
146 %
147 % \begin{variable}{linecolor}
148 % \begin{syntax}
149 % \cs{usepackage} \oarg{linecolor=\emph{color}} \{soup\}
150 % \end{syntax}
151 % Specify the line color to be used when highlighting solutions (TikZ only).
152 %
153 % The default color is |red|.
154 %
155 % Color mixes are fine here, too: |green!20!black|.
156 % \end{variable}
157 %
158 %
159 % \subsection{Environments}
160 %
161 %
162 % \begin{function}{alphabetsoup, alphabetsoup*,Alphabetsoup,Alphabetsoup*}
163 % \begin{syntax}
164 % \cs{begin\{alphabetsoup\}}~ \oarg{width} \oarg{height} \oarg{font}
165 % \cs{begin\{alphabetsoup\}}* \oarg{width} \oarg{height} \oarg{font}
166 % \cs{begin\{Alphabetsoup\}}~ \oarg{width} \oarg{height} \oarg{font}
167 % \cs{begin\{Alphabetsoup\}}* \oarg{width} \oarg{height} \oarg{font}
168 % \end{syntax}
169 %
170 % An \env{alphabetsoup} environment will build a grid of letters
171 % using lowercase Latin a--z, weighted for their frequence in English words.
172 % The \env{Alphabetsoup} environment uses uppercase A--Z.
173 % (For other alphabets, use a custom
174 % \env{homemadesoup}.)
175 %
176 % A list of clues will be included after the grid. Use the starred version
177 % to omit the list. (To include the list later, use |\listofclues|.)
178 %
179 % If the \meta{height} is omitted, the number of rows will
180 % be the same as the number of columns.
181 %
182 % If the \meta{width} is omitted, it will default to 20.
183 %
184 % Therefore, with no parameters, a 20-by-20 grid of letters will be generated.
185 %
186 % \meta{font} can be optionally used to set the size of the letters in the soup
187 % (e.g., |\Large|, |\scriptsize|) or other font-related commands
188 % (e.g., |\sffamily|, |\itshape|)
189 % \end{function}
190 %
191 %
192 % \begin{function}{numbersoup, numbersoup*}
193 % \begin{syntax}
194 % \cs{begin\{numbersoup\}}~ \oarg{width} \oarg{height} \marg{max} \oarg{min} \oarg{font}
195 % \cs{begin\{numbersoup\}}* \oarg{width} \oarg{height} \marg{max} \oarg{min} \oarg{font}
196 % \end{syntax}
197 %
198 % The \env{numbersoup} environment follows \env{alphabetsoup} with two
199 % important differences:
200 % \begin{itemize}
201 % \item
202 % The grid is filled with numbers (not letters)
203 %
204 % \item
205 % Numbers are between \meta{min} (or 0 if omitted) and \meta{max}, inclusive.
206 % \end{itemize}
207 %
208 % The \meta{max} must be specified.
209 % \end{function}
210 %
211 %
212 % \begin{function}{homemadesoup, homemadesoup*}
213 % \begin{syntax}
214 % \cs{begin\{homemadesoup\}}~ \oarg{width} \oarg{height} \marg{symbols} \oarg{font}
215 % \cs{begin\{homemadesoup\}}* \oarg{width} \oarg{height} \marg{symbols} \oarg{font}
216 % \end{syntax}
217 %
218 % Instead of filling with digits or letters, the soup will be filled
219 % randomly from the user-specified comma-separated list \meta{symbols}
220 %
221 % \end{function}
222 %
223 %
224 % \subsection{Macros}
225 %
226 %
227 % \begin{function}{\hideinsoup, \hideinsoup*}
228 % \begin{syntax}
229 % \cs{hideinsoup} \marg{x} \marg{y} \marg{dir} \marg{seq} \oarg{clue}
230 % \end{syntax}
231 %
232 % Generally, an alphabetsoup will have words hidden in it.
233 % Other soups will have appropriate clues hidden (e.g., a number series).
234 %
235 % These are put in the soup with |\hideinsoup|.
236 %
237 % If two words overlap, and the overlapping letters (or other symbols)
238 % are different, \pkg{soup} will issue a warning, and it will display
239 % \emph{both} letters in the grid, separated by a slash.
240 %
241 % If highlighting is enabled, |\hideinsoup| will call |\highlightinsoup|.
242 % Use the starred version, |\hideinsoup*| to avoid this behavior.
243 %
244 % If \pkg{soup} was loaded with |usetikz=false|, the highlighting
245 % of hidden clues will be simple boldface. The starred version will
246 % have no effect on this.
247 % \end{function}
248 %
249 %
250 % \begin{function}{\highlightinsoup}
251 % \begin{syntax}
252 % \cs{highlightinsoup} \marg{x1} \marg{y1} \marg{x2} \marg{y2}
253 % \end{syntax}
254 %
255 % Highlights the word (or sequence of symbols) between (\meta{x1},\meta{y1})
256 % and (\meta{x2},\meta{y2}), where (1,1) is the top left of the soup grid,
257 % (2,1) is to the right of the top left, and (1,2) is the first symbol in
258 % the second row.
259 %
260 % If \pkg{soup} was loaded with |usetikz=false|, this macro will have no effect.
261 % \end{function}
262 %
263 %
264 % \begin{function}{\listofclues}
265 % \begin{syntax}
266 % \cs{listofclues} \oarg{format}
267 % \end{syntax}
268 %
269 % Displays a list of all clues for the current puzzle.
270 %
271 % The optional \meta{format} should use |\theclue| where the text of
272 % the clue should appear.
273 %
274 % Must be used after all uses of |\hideinsoup| for the current soup.
275 % If included before |\end{...soup}|, the clues will appear \emph{before}
276 % the soup. If includes after |\end{...soup}|, then they will appear
277 % \emph{after} the soup.
278 %
279 % A typical use might be to display the clues as an enumerated list in columns:
280 %
281 % \begin{verbatim}
282 % \begin{alphabetsoup}*
283 % ...
284 % \end{alphabetsoup}
285 % \begin{multicols}{3}
286 % \begin{enumerate}
287 % \listofclues[\item \theclue]
288 % \end{enumerate}
289 % \end{multicols}
290 % \end{verbatim}
291 % \end{function}
292 %
293 %
294 %
295 % \StopEventually{\clearpage{}\PrintChanges\clearpage{}\PrintIndex}
296 %
297 %
298 %
299 % \section{Implementation}
300 %
301 %
302 % \subsection{Dependencies}
303 %
304 %
305 % \begin{macrocode}
306 \RequirePackage{xparse}
307 \RequirePackage{expl3}
308 \RequirePackage{l3keys2e}
309 % \end{macrocode}
310 %
311 %
312 % \subsection{Initialization and Parameter Handling}
313 %
314 %
315 % \begin{macrocode}
316 \ExplSyntaxOn
317
318 \msg_new:nnn{soup}{mismatch}{
319 Clue~mismatch~at~#1.~Will~appear~as~#2/#3~in~the~soup.
320 }
321
322 \bool_new:N \g_soup_use_tikz_bool
323 \bool_gset_true:N \g_soup_use_tikz_bool
324
325 \bool_new:N \g_soup_highlight_bool
326 \bool_gset_false:N \g_soup_highlight_bool
327
328 \tl_new:N \g_soup_highlight_color
329 \tl_gset:Nn \g_soup_highlight_color {orange}
330
331 \tl_new:N \g_soup_line_color
332 \tl_gset:Nn \g_soup_line_color {red}
333
334 \keys_define:nn { soup }{
335 highlightcolor .initial:n = orange,
336 highlightcolor .value_required:n = true,
337 highlightcolor .code:n = \tl_set:Nn \g_soup_highlight_color {#1},
338 linecolor .initial:n = red,
339 linecolor .value_required:n = true,
340 linecolor .code:n = \tl_set:Nn \g_soup_line_color {#1},
341 highlight .default:n = true,
342 highlight .bool_set:N = \g_soup_highlight_bool,
343 usetikz .default:n = true,
344 usetikz .bool_set:N = \g_soup_use_tikz_bool,
345 }
346
347 \ProcessKeysPackageOptions{ soup }
348 \IfBooleanT \g_soup_use_tikz_bool {
349 \RequirePackage{tikz}
350 }
351 \clist_const:Nn \c_soup_Alphabet_clist {
352 A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,
353 E,T,A,O,H,N,I,S,R,D,L,U,W,M,C,G,F,Y,P,V,K,B,J,
354 E,T,A,O,H,N,I,S,R,D,L,U,W,M,C,G,F,Y,P,V,K,B,
355 E,T,A,O,H,N,I,S,R,D,L,U,W,M,
356 E,T,A,O,H,N,I,S,
357 E,T,A,O,H,
358 }
359
360 \clist_const:Nn \c_soup_alphabet_clist {
361 a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z,
362 e,t,a,o,h,n,i,s,r,d,l,u,w,m,c,g,f,y,p,v,k,b,j,
363 e,t,a,o,h,n,i,s,r,d,l,u,w,m,c,g,f,y,p,v,k,b,
364 e,t,a,o,h,n,i,s,r,d,l,u,w,m,
365 e,t,a,o,h,n,i,s,
366 e,t,a,o,h,
367 }
368
369 \prop_new:N \g_soup_data_prop
370 \seq_new:N \g_soup_clue_seq
371 % \end{macrocode}
372 %
373 %
374 % \subsection{Internal Functions}
375 %
376 %
377 % \begin{macro}[aux]{\__soup_init:nn}
378 % Resets the storage in preparation for a new soup.
379 % \begin{macrocode}
380 \cs_new:Nn \__soup_init:nn {
381 \clist_clear_new:N \g_soup_symbol_clist
382 \dim_gzero_new:N \g_soup_highlight_dim
383 \dim_gzero_new:N \g_soup_spacing_dim
384 \int_gzero_new:N \g_soup_columns_int
385 \int_gzero_new:N \g_soup_number_max_int
386 \int_gzero_new:N \g_soup_number_min_int
387 \int_gzero_new:N \g_soup_number_range_int
388 \int_gzero_new:N \g_soup_rows_int
389 \int_gzero_new:N \g_soup_symbol_count_int
390 \prop_clear_new:N \g_soup_data_prop
391 \seq_clear_new:N \g_soup_clue_seq
392 \seq_clear_new:N \g_soup_highlight_seq
393 \int_gset:Nn \g_soup_columns_int {#1}
394 \IfNoValueTF{#2} {
395 \int_gset:Nn \g_soup_rows_int {\g_soup_columns_int}
396 }{
397 \int_gset:Nn \g_soup_rows_int {#2}
398 }
399 \dim_gset:Nn \g_soup_spacing_dim {\textwidth / (\g_soup_columns_int + 1)}
400 \dim_gset:Nn \g_soup_highlight_dim {\g_soup_spacing_dim * 7 / 10}
401 \tl_clear_new:N \g_soup_font_tl
402 \tl_gset:Nn \g_soup_font_tl {\normalfont}
403 }
404 % \end{macrocode}
405 % \end{macro}
406 %
407 %
408 % \begin{macro}[aux]{\__soup_random_int:nn}
409 % Returns a pseudo-random integer between |#1| and |#2|.
410 %
411 % \url{https://en.wikipedia.org/wiki/Lehmer_random_number_generator}
412 % \begin{macrocode}
413 \int_gzero_new:N \g__soup_random_previous_int
414 \int_gzero_new:N \g__soup_random_current_int
415 \cs_new:Nn \__soup_random_int:nn {
416 \int_compare:nNnT \g__soup_random_previous_int = 0 {
417 \int_gset:Nn \g__soup_random_previous_int {\time}
418 }
419 % A = 16807, Q = 127773 (M / A), R = 2836 (M % A), M = 2147483647 (2^31-1)
420 \int_zero_new:N \l__hi_int
421 \int_zero_new:N \l__lo_int
422 \int_set:Nn \l__hi_int {\g__soup_random_previous_int / 127773}
423 \int_set:Nn \l__lo_int {\int_mod:nn{\g__soup_random_previous_int}{127773}}
424 \int_gset:Nn \g__soup_random_previous_int {
425 16807 * \l__hi_int - 2836 * \l__lo_int
426 }
427 \int_compare:nNnT \g__soup_random_previous_int < 1 {
428 \int_gadd:Nn \g__soup_random_previous_int {2147483647}
429 }
430 \int_gset:Nn \g__soup_random_current_int {
431 #1 + \int_mod:nn{\g__soup_random_previous_int}{#2 - #1 + 1}
432 }
433 }
434 % \end{macrocode}
435 % \end{macro}
436 %
437 %
438 % \begin{macro}[aux]{\__soup_draw_nodes:}
439 % Must be used inside a |tikzpicture| environment.
440 %
441 % For every node pushed, now draw a node using either the previously set value
442 % or one now generated by the |getrand| macro.
443 %
444 % \begin{macrocode}
445 \cs_new:Nn \__soup_draw_nodes: {
446 \int_step_variable:nnnNn {1} {1} {\g_soup_columns_int} \l_tmpb_int {
447 \int_step_variable:nnnNn {1} {1} {\g_soup_rows_int} \l_tmpc_int {
448 \exp_args:Nnx
449 \prop_get:NnNTF \g_soup_data_prop {
450 (\l_tmpb_int,\l_tmpc_int)
451 } \l_tmpa_tl {
452 \node
453 at (\l_tmpb_int,\l_tmpc_int)
454 {\l_tmpa_tl};
455 }{
456 \node
457 at (\l_tmpb_int,\l_tmpc_int)
458 {\__soup_show_random_symbol:};
459 }
460 }
461 }
462 }
463 % \end{macrocode}
464 % \end{macro}
465 %
466 %
467 % \begin{macro}[aux]{\__soup_draw_highlights:}
468 % Must be used inside a |tikzpicture| environment.
469 %
470 % For every previously stored highlight coords, now draw the lines.
471 %
472 % \begin{macrocode}
473 \cs_new:Nn \__soup_draw_highlights: {
474 \seq_map_inline:Nn \g_soup_highlight_seq {
475 \draw[
476 double=\g_soup_highlight_color,
477 double~distance=\g_soup_highlight_dim,
478 line~width=2pt,
479 color=\g_soup_line_color,
480 opacity=0.4,
481 line~cap=round
482 ] ##1;
483 }
484 }
485 % \end{macrocode}
486 % \end{macro}
487 %
488 %
489 % \begin{macro}[aux]{\__soup_draw_soup_tikz:}
490 % Do the actual work of drawing the soup
491 %
492 % \begin{macrocode}
493 \cs_new:Nn \__soup_draw_soup_tikz: {
494
495 \tikzset{
496 every~node/.style={
497 font=\g_soup_font_tl,
498 },
499 }
500 \begin{tikzpicture}[
501 x=\g_soup_spacing_dim,
502 y=-\g_soup_spacing_dim,
503 ]
504 \draw[rounded~corners=6pt, use~as~bounding~box]
505 (0.5,0)
506 ++(0,0.5) rectangle +(\g_soup_columns_int, \g_soup_rows_int);
507 \__soup_draw_highlights:
508 \__soup_draw_nodes:
509 \end{tikzpicture}
510 }
511 % \end{macrocode}
512 % \end{macro}
513 %
514 %
515 % \begin{macro}[aux]{\__soup_draw_soup_tabular:}
516 % Do the actual work of drawing the soup (as a table)
517 %
518 % \begin{macrocode}
519 \cs_new:Nn \__soup_draw_soup_tabular: {
520 \dim_zero_new:N \l_soup_colwidth_dim
521 \exp_args:Nnx
522 \dim_set:Nn \l_soup_colwidth_dim {\fp_to_dim:n {0.45 * \textwidth / (\g_soup_columns_int + 1)}}
523
524 \dim_zero_new:N \l_soup_lineheight_dim
525 \dim_set:Nn \l_soup_lineheight_dim {2\l_soup_colwidth_dim - \baselineskip}
526
527 \setlength{\tabcolsep}{\l_soup_colwidth_dim}
528 \vspace{0.25\g_soup_spacing_dim}\par
529 \noindent
530 \begin{tabular*}{\textwidth}{
531 @{\extracolsep{\fill}}
532 | *{\g_soup_columns_int}{c@{\hskip\l_soup_colwidth_dim}} |
533 }
534 \hline\rule{0pt}{\g_soup_spacing_dim}
535 \int_step_inline:nnnn {1} {1} {\g_soup_rows_int } {
536 \int_gset:Nn \g_tmpa_int {##1}
537 \int_step_variable:nnnNn {1} {1} {\g_soup_columns_int} \l_tmpb_int {
538 \exp_args:Nnx
539 \prop_get:NnNTF \g_soup_data_prop {
540 (\l_tmpb_int,\the\g_tmpa_int)
541 } \l_tmpa_tl {
542 \g_soup_font_tl
543 \IfBooleanTF{\g_soup_highlight_bool}{
544 {\bfseries\l_tmpa_tl}
545 }{
546 \l_tmpa_tl
547 }
548 }{
549 \g_soup_font_tl\__soup_show_random_symbol:
550 }
551 \int_compare:nNnT \l_tmpb_int < \g_soup_columns_int {
552 &
553 }
554 }
555 \int_compare:nNnTF \g_tmpa_int < \g_soup_rows_int {
556 \\[\l_soup_lineheight_dim]
557 }{
558 \\[\l_soup_lineheight_dim]\hline\end{tabular*}
559 }
560 }
561 }
562 % \end{macrocode}
563 % \end{macro}
564 %
565 %
566 % \begin{macro}[aux]{\__soup_show_random_symbol:}
567 % Called for every coordinate not defined by calls to |\hideinsoup|,
568 % this generates a random symbol---either a number from the
569 % |\g_soup_number_range_int| (if nonzero) or from the list of symbols in
570 % |\g_soup_symbol_clist| set by |homemadesoup|, |alphabetsoup|,
571 % and |Alphabetsoup|.
572 % \begin{macrocode}
573 \cs_new:Nn \__soup_show_random_symbol: {
574 \int_compare:nNnTF \g_soup_symbol_count_int = 0 {
575 \__soup_random_int:nn {\g_soup_number_min_int}{\g_soup_number_max_int}
576 \the\g__soup_random_current_int
577 }{
578 \__soup_random_int:nn {1}{\g_soup_symbol_count_int}
579 \clist_item:Nn \g_soup_symbol_clist {\g__soup_random_current_int}
580 }
581 }
582 % \end{macrocode}
583 % \end{macro}
584 %
585 %
586 % \subsection{User Document Functions}
587 %
588 %
589 % \begin{macro}{\listofclues}
590 % Display the list of clues. THe optional argument will be expanded with
591 % |\theclue| as each clue. The default is defined as |\theclue\par|.
592 % \begin{macrocode}
593 \NewDocumentCommand \listofclues { +o } {
594 \tl_clear_new:N \theclue
595 \IfNoValueTF{#1}{
596 \tl_set:Nn \l_tmpa_tl {\theclue\par}
597 }{
598 \tl_set:Nn \l_tmpa_tl {#1}
599 }
600 \seq_map_variable:NNn \g_soup_clue_seq \theclue {
601 \l_tmpa_tl
602 }
603 }
604 % \end{macrocode}
605 % \end{macro}
606 %
607 %
608 % \begin{macro}{\highlightinsoup}
609 % Given the coordinates of a word (expressed as |{x1}{y1}{x2}{y2}|),
610 % this will mark the word (or other sequence).
611 %
612 % This is automatically called for every clue hidden via |\hideinsoup|.
613 %
614 % This does nothing unless |highlight=true| was passed to the package.
615 % \begin{macrocode}
616 \NewDocumentCommand \highlightinsoup { m m m m }{
617 \bool_if:NT \g_soup_highlight_bool {
618 \seq_gput_left:Nx \g_soup_highlight_seq {(#1, #2) -- (#3, #4)}
619 }
620 }
621 % \end{macrocode}
622 % \end{macro}
623 %
624 %
625 % \begin{macro}{\hideinsoup, \hideinsoup*}
626 % Given a starting coordinate, a direction, a comma-separated list of symbols,
627 % and an optional clue, set the appropriate coordinates to these symbols.
628 %
629 % \marg{x1}, \marg{y1}, \marg{direction}, \marg{word}, \oarg{clue}
630 %
631 % The starred version will disable highlighting (if enabled) to allow
632 % setting parts of the soup that are outside actual answers.
633 %
634 % If a clue is specified, insert it into the |\listofclues|
635 % \begin{macrocode}
636 \NewDocumentCommand \hideinsoup { smmmmo } {
637 \int_zero_new:N \l__soup_dx_int
638 \int_zero_new:N \l__soup_dy_int
639
640 \str_case:nn {#4} {
641 {left}{
642 \int_set:Nn \l__soup_dx_int {-1}
643 \int_set:Nn \l__soup_dy_int { 0}
644 }
645 {right}{
646 \int_set:Nn \l__soup_dx_int { 1}
647 \int_set:Nn \l__soup_dy_int { 0}
648 }
649 {up}{
650 \int_set:Nn \l__soup_dx_int { 0}
651 \int_set:Nn \l__soup_dy_int {-1}
652 }
653 {upleft}{
654 \int_set:Nn \l__soup_dx_int {-1}
655 \int_set:Nn \l__soup_dy_int {-1}
656 }
657 {upright}{
658 \int_set:Nn \l__soup_dx_int { 1}
659 \int_set:Nn \l__soup_dy_int {-1}
660 }
661 {down}{
662 \int_set:Nn \l__soup_dx_int { 0}
663 \int_set:Nn \l__soup_dy_int { 1}
664 }
665 {downleft}{
666 \int_set:Nn \l__soup_dx_int {-1}
667 \int_set:Nn \l__soup_dy_int { 1}
668 }
669 {downright}{
670 \int_set:Nn \l__soup_dx_int { 1}
671 \int_set:Nn \l__soup_dy_int { 1}
672 }
673 }
674
675 \clist_set:Nn \l__soup_clue_clist {#5}
676 \int_zero_new:N \l__soup_clue_count_int
677 \int_set:Nn \l__soup_clue_count_int {\clist_count:N \l__soup_clue_clist}
678
679 \int_zero_new:N \l__soup_cx_int
680 \int_zero_new:N \l__soup_cy_int
681 \tl_clear_new:N \l__soup_ci_tl
682 \tl_clear_new:N \l__soup_ch_tl
683 \tl_clear_new:N \l__soup_nn_tl
684
685 \int_step_variable:nnnNn {1} {1} {\l__soup_clue_count_int} \l__soup_ci_tl {
686 \int_set:Nn \l__soup_cx_int
687 {#2 + \l__soup_dx_int * (\l__soup_ci_tl - 1)}
688
689 \int_set:Nn \l__soup_cy_int
690 {#3 + \l__soup_dy_int * (\l__soup_ci_tl - 1)}
691
692 \exp_args:Nnx
693 \tl_set:Nn \l__soup_ch_tl
694 {\clist_item:Nn \l__soup_clue_clist {\l__soup_ci_tl}}
695
696 \exp_args:Nnx
697 \tl_set:Nn \l__soup_nn_tl
698 {(\the\l__soup_cx_int,\the\l__soup_cy_int)}
699
700 \exp_args:Nnx
701 \tl_set:Nn \l__soup_cv_tl
702 {\exp_args:Nno \prop_item:Nn \g_soup_data_prop \l__soup_nn_tl}
703
704 \str_if_empty:NTF \l__soup_cv_tl {
705 \exp_args:Nnx \prop_gput:Noo \g_soup_data_prop {
706 \l__soup_nn_tl
707 } {\l__soup_ch_tl}
708 }{
709 \str_if_eq:NNF \l__soup_cv_tl \l__soup_ch_tl {
710 \msg_warning:nnxxx{soup}{mismatch}{
711 \l__soup_nn_tl
712 }{\l__soup_cv_tl}{\l__soup_ch_tl}
713
714 \tl_put_left:Nx \l__soup_ch_tl
715 {\l__soup_cv_tl/}
716
717 \exp_args:Nnx
718 \prop_gput:Noo \g_soup_data_prop {\l__soup_nn_tl}
719 {\l__soup_ch_tl}
720 }
721 }
722 }
723
724 \IfBooleanF{#1}{
725 \exp_args:Nnx
726 \int_set:Nn \l__soup_cx_int
727 {#2 + \l__soup_dx_int * (\l__soup_clue_count_int - 1)}
728
729 \exp_args:Nnx
730 \int_set:Nn \l__soup_cy_int
731 {#3 + \l__soup_dy_int * (\l__soup_clue_count_int - 1)}
732
733 \exp_args:Nnx
734 \tl_set:Nn \l__soup_nn_tl
735 {(\the\l__soup_cx_int,\the\l__soup_cy_int)}
736
737 \exp_args:Nnx
738 \seq_gput_left:Nx \g_soup_highlight_seq
739 {(#2, #3) -- \l__soup_nn_tl}
740 }
741 \IfNoValueF{#6}{
742 \seq_gput_left:No \g_soup_clue_seq {#6}
743 }
744 }
745 % \end{macrocode}
746 % \end{macro}
747 %
748 %
749 % \subsection{Environments}
750 %
751 %
752 % \begin{macro}{alphabetsoup, alphabetsoup*}
753 % A soup environment where unspecified coordinates are fill with a--z
754 %
755 % For something else, see the |homemadesoup| environment.
756 % \begin{macrocode}
757 \NewDocumentEnvironment{alphabetsoup}{ sO{15}oo }
758 {
759 \par\noindent
760 \__soup_init:nn {#2}{#3}
761 \IfBooleanTF{#1}{
762 \def\showlist{}
763 }{
764 \def\showlist{\par\vspace*{1em}\listofclues}
765 }
766 \IfNoValueF{#4}{
767 \tl_gset:Nn \g_soup_font_tl {#4}
768 }
769
770 \clist_gset_eq:NN \g_soup_symbol_clist
771 \c_soup_alphabet_clist
772
773 \int_gset:Nn \g_soup_symbol_count_int
774 {\clist_count:N \g_soup_symbol_clist}
775 }{
776 \IfBooleanTF \g_soup_use_tikz_bool {
777 \__soup_draw_soup_tikz:
778 }{
779 \__soup_draw_soup_tabular:
780 }
781 \showlist
782 }
783 % \end{macrocode}
784 % \end{macro}
785 %
786 %
787 % \begin{macro}{Alphabetsoup, Alphabetsoup*}
788 % A soup environment where unspecified coordinates are
789 % A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z
790 %
791 % For something else, see the |homemadesoup| environment.
792 % \begin{macrocode}
793 \NewDocumentEnvironment{Alphabetsoup}{ sO{15}oo }
794 {
795 \par\noindent
796 \__soup_init:nn {#2}{#3}
797 \IfBooleanTF{#1}{
798 \def\showlist{}
799 }{
800 \def\showlist{\par\vspace*{1em}\listofclues}
801 }
802 \IfNoValueF{#4}{
803 \tl_gset:Nn \g_soup_font_tl {#4}
804 }
805
806 \clist_gset_eq:NN \g_soup_symbol_clist
807 \c_soup_Alphabet_clist
808
809 \int_gset:Nn \g_soup_symbol_count_int
810 {\clist_count:N \g_soup_symbol_clist}
811 }{
812 \IfBooleanTF \g_soup_use_tikz_bool {
813 \__soup_draw_soup_tikz:
814 }{
815 \__soup_draw_soup_tabular:
816 }
817 \showlist
818 }
819 % \end{macrocode}
820 % \end{macro}
821 %
822 %
823 % \begin{macro}{homemadesoup, homemadesoup*}
824 % The |homemadesoup| environment builds a soup from the user-supplied
825 % comma-separated list of symbols.
826 % \begin{macrocode}
827 \NewDocumentEnvironment{homemadesoup}{ sO{15}omo }
828 {
829 \par\noindent
830 \__soup_init:nn {#2}{#3}
831 \IfBooleanTF{#1}{
832 \def\showlist{}
833 }{
834 \def\showlist{\par\vspace*{1em}\listofclues}
835 }
836 \IfNoValueF{#5}{
837 \tl_gset:Nn \g_soup_font_tl {#5}
838 }
839
840 \clist_gset:Nn \g_soup_symbol_clist
841 {#4}
842
843 \int_gset:Nn \g_soup_symbol_count_int
844 {\clist_count:N \g_soup_symbol_clist}
845 }
846 {
847 \IfBooleanTF \g_soup_use_tikz_bool {
848 \__soup_draw_soup_tikz:
849 }{
850 \__soup_draw_soup_tabular:
851 }
852 \showlist
853 }
854 % \end{macrocode}
855 % \end{macro}
856 %
857 %
858 % \begin{macro}{numbersoup, numbersoup*}
859 % Sets up a soup with all unspecified coordinates displaying numbers.
860 % \begin{macrocode}
861 \NewDocumentEnvironment{numbersoup}{ sO{15}omO{0}o }
862 {
863 \par\noindent
864 \__soup_init:nn{#2}{#3}
865 \IfBooleanTF{#1}{
866 \def\showlist{}
867 }{
868 \def\showlist{\par\vspace*{1em}\listofclues}
869 }
870 \IfNoValueF{#6}{
871 \tl_gset:Nn \g_soup_font_tl {#6}
872 }
873
874 \int_gset:Nn \g_soup_number_max_int
875 {#4}
876
877 \int_gset:Nn \g_soup_number_min_int
878 {#5}
879
880 \int_gset:Nn \g_soup_number_range_int
881 {\g_soup_number_max_int - \g_soup_number_min_int}
882 }
883 {
884 \IfBooleanTF \g_soup_use_tikz_bool {
885 \__soup_draw_soup_tikz:
886 }{
887 \__soup_draw_soup_tabular:
888 }
889 \showlist
890 }
891 % \end{macrocode}
892 % \end{macro}
893 %
894 %
895 % \begin{macrocode}
896 \ExplSyntaxOff
897 % \end{macrocode}
898 % \Finale
899 \endinput