From c96d64674defb8c86d0000083f5649292ba2853c Mon Sep 17 00:00:00 2001 From: Peter Verhas Date: Wed, 9 Oct 2024 10:30:01 +0200 Subject: [PATCH] yaml package documentation was amended to describe how to loop over parts of the yaml structure --- README.jrf | 2 +- jamal-cmd/README.adoc | 6 +- .../main/java/javax0/jamal/cmd/Jamalizer.java | 38 +++- jamal-snippet/README.adoc | 2 +- jamal-sql/demodb.mv.db | Bin 24576 -> 24576 bytes .../src/test/resources/demoConverted.docx | Bin 12792 -> 12792 bytes .../test/resources/includetestConverted.docx | Bin 34572 -> 34572 bytes .../src/test/resources/pictureConverted.docx | Bin 21869 -> 21869 bytes .../src/test/resources/sampleConverted.docx | Bin 40818 -> 40810 bytes jamal-xls/README.adoc | 2 +- jamal-yaml/README.adoc | 202 ++++++++++++++++-- jamal-yaml/README.adoc.jam | 156 +++++++++++++- 12 files changed, 374 insertions(+), 34 deletions(-) diff --git a/README.jrf b/README.jrf index 2e4db4ae..ad7d3d50 100644 --- a/README.jrf +++ b/README.jrf @@ -1,5 +1,5 @@ # This is a Jamal reference file containing serialized base64 encoded macros -# Created: 2024-10-07 21:54:28 +0200 +# Created: 2024-10-08 20:08:24 +0200 # id|openStr|closeStr|verbatim|tailParameter|pure|content|parameters # TOC VE9D|eyU=|JX0=|0|0|0|Ci4gPDxJbnN0YWxsYXRpb24+PgouIDw8R1M+PgouIDw8Q29uZmlndXJhdGlvbj4+Ci4gPDxGZWF0dXJlcz4+Ci4gPDxDb250cmlidXRpbmc+PgouIDw8RG9jdW1lbnRhdGlvbj4+Ci4gPDxMaWNlbnNlPj4KLiA8PENoYW5nZWxvZz4+Ci4gPDxSb2FkbWFwPj4KLiA8PFN1cHBvcnQ+PgouIDw8RkFRPj4KLiA8PE1haW50ZW5hbmNlPj4=| diff --git a/jamal-cmd/README.adoc b/jamal-cmd/README.adoc index 8655c6cd..c31807e3 100644 --- a/jamal-cmd/README.adoc +++ b/jamal-cmd/README.adoc @@ -104,4 +104,8 @@ See also the option `-from`. * `-jamalize` will install Jamal in the `.asciidoctor/lib` directory. It version of the installed Jamal is the same as the one installing it. -It can also install a different version if the option `-version=xxx` is specifying a specific versions. \ No newline at end of file +It can also install a different version if the option `-version=xxx` is specifying a specific versions. + + + + diff --git a/jamal-cmd/src/main/java/javax0/jamal/cmd/Jamalizer.java b/jamal-cmd/src/main/java/javax0/jamal/cmd/Jamalizer.java index 241a05cf..4d82f1f3 100644 --- a/jamal-cmd/src/main/java/javax0/jamal/cmd/Jamalizer.java +++ b/jamal-cmd/src/main/java/javax0/jamal/cmd/Jamalizer.java @@ -20,20 +20,50 @@ public class Jamalizer { private static final String version = System.getProperty("jamal.version") == null ? Processor.jamalVersionString() : System.getProperty("jamal.version"); + private static final String DOWNLOAD_URL_TEMPLATE = "https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-asciidoc/%s/jamal-asciidoc-%s-jamal-asciidoc-distribution.zip"; static void jamalize(String version) throws IOException, BadSyntax { - if( version == null ){ + if (version == null) { version = Jamalizer.version; } + warnAboutSnapshot(version); createAsccidoctorLibDir(); - extratZip(FileTools.getFileBinaryContent( - String.format("https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-asciidoc/%s/jamal-asciidoc-%s-jamal-asciidoc-distribution.zip", version, version), + extractZip(FileTools.getFileBinaryContent( + String.format(DOWNLOAD_URL_TEMPLATE, version, version), false, new javax0.jamal.engine.Processor()) ); } - private static void extratZip(final byte[] zipContent) throws IOException { + private static void warnAboutSnapshot(String version) { + if (version.contains("SNAPSHOT")) { + System.err.println("The version of the Jamalizer is a SNAPSHOT version.\n" + + "This is not recommended for production use.\n" + + "Since the command 'jamalize' downloads Jamal from Maven central using the URL\n\n" + + String.format(DOWNLOAD_URL_TEMPLATE, version, version) + + "\n\nit is possible that the version is not available in the repository yet.\n" + + "Use 'jamal -jamalize version=...' to specify a version that is available in the repository." + ); + } + } + + /** + * Extracts JAR files from a ZIP archive provided as a byte array. + * + *

This method processes the given byte array, which represents the content + * of a ZIP archive. It scans the archive, looking for entries that are JAR files + * (files with a ".jar" extension). For each JAR file found, it writes the content + * to a specified directory on the filesystem.

+ * + *

The output JAR files are extracted to the path specified by the + * concatenation of {@code ASCIIDOCTOR_DIR} and {@code LIB_DIR}, using + * the JAR filename from the ZIP entry.

+ * + * @param zipContent the byte array containing the ZIP archive content + * @throws IOException if an I/O error occurs while reading the ZIP archive + * or writing the extracted JAR files to the filesystem + */ + private static void extractZip(final byte[] zipContent) throws IOException { try (final var is = new JarInputStream(new ByteArrayInputStream(zipContent))) { ZipEntry entry; while ((entry = is.getNextEntry()) != null) { diff --git a/jamal-snippet/README.adoc b/jamal-snippet/README.adoc index faabdce8..ad71d3be 100644 --- a/jamal-snippet/README.adoc +++ b/jamal-snippet/README.adoc @@ -3816,7 +3816,7 @@ will result in the output .output [source] ---- -2024-10-04 10:17:51 +2024-10-08 09:13:51 ---- diff --git a/jamal-sql/demodb.mv.db b/jamal-sql/demodb.mv.db index 2c88665d8c54d8a3500433f585969f01844816fb..93740a587741d9ef923819bb9a4b75f8f1049778 100644 GIT binary patch literal 24576 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 delta 216 zcmey7{3Dq+z?+#xgn@&DgCQ`;Wh3t%MrI(r`3$2ngz<@~9m1$#nFMA`7GygCR&s~U zgd5Bd7BYn>@fMy2VLTC8$_$q3k${@#Ep?n1EF!9LlMTd}{87&iOdIK&f$400YcRc1 o-v&&-(1*xt8bJ6N2JT?-O$N4L`V*8kGK9z%8d`zH*BN>N06gqLT>t<8 diff --git a/jamal-word/src/test/resources/includetestConverted.docx b/jamal-word/src/test/resources/includetestConverted.docx index 22f289b8329b7e75e4d15ccc8d9672cde31057fa..c2fdd90639ab90bea2659998194595f17f807572 100644 GIT binary patch delta 221 zcmeC_W9sQ+;tlX-W)WfF;NW1m=IODKcLpOfklwt4Q4+#9!t@Qo*vnD~VHmPSae~$K z@q0i-ZVIR{fkZY5Uk(A$lMUI#Hor-K&jwa@FK-tQm@&KhIz*(jsROKWQi~l}xnqkN wn67HE2GcuQY{2w)C~em24(2zs+Jfl=t&U)tr46Faxy=e9-{t_O54U*&03rQTqyPW_ delta 221 zcmeC_W9sQ+;tlX-W)WfF;NV~g4074XJA;uKNN--jC<$R4VfqGP>}4s0FbvtEIKgWA z_&p#ZHw9FfKq8xjFNc8W$%brVo8P3rX9Fv{m$!=t%$Qw$9U@ZN)B)Bwsl^Vg+_A+B vOjos7gXtYDHemWYls0R12lE?RZNc<`R!1<+(gsoI+-3!lZ*u_Chub^>Pnt)h diff --git a/jamal-word/src/test/resources/pictureConverted.docx b/jamal-word/src/test/resources/pictureConverted.docx index 60ccbbaba3528a6a88658e4f940832566a87ae8e..1a047b2202f0abbfa6ec4acbc4bb0f3b9eb4f208 100644 GIT binary patch delta 304 zcmaF6it+6#M&1B#W)=|!4h{~6Yn~n(dCxO41L@888T}y)L*~Cw25Sj~v4SlT!rXfkIe7!fEkBfu0urTdK*HtU-aRE zFz)$QLl`ms9bm@f=K*#gO_MbO&A@bGpf#ADA7}%n?*&5S<%1ynxFC11_=+G~F#RIP o5lrg@L-;wt5Ou4AtswHj4q#e4#2ZXkhJ=CXOCkPXS|!vI0Mcx5RR910 delta 304 zcmaF6it+6#M&1B#W)=|!4h{~6z#x~6yyqF2f%NA4jQ$XYA@g4-gS7<0SizPEVeoLY zaDWw076^feyb_$k1Qux&5tINkrs}w|f*E%Wnb^RLN9OlLE#*C8Tvy$vDSFZysn z825auA&eOR4lrZ#^8h=LrpX$CW?(uo&>Bq753~W(_W~jE@<9-OT#!3hd_|Bgn0^uD o2&Q#{A^emTWPF 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 diff --git a/jamal-xls/README.adoc b/jamal-xls/README.adoc index 859f7853..98c000ef 100644 --- a/jamal-xls/README.adoc +++ b/jamal-xls/README.adoc @@ -68,7 +68,7 @@ Parameter options (parops) can be defined without parentheses. The `(` and `)` are optional.) * `file` (aliases are `in`, `input`, `from`) is the name of the file that contains the XLS workbook. -Technically `file` is also an alias, thus a macro havign the name of `file` will not be considered. +Technically, `file` is also an alias; thus a macro having the name of `file` will not be considered. This parop must be defined. * `out` (aliases are `output`, `to`) is the name of the file where the XLS workbook is written. This parop is optional. diff --git a/jamal-yaml/README.adoc b/jamal-yaml/README.adoc index 5d9b9c80..4d36943f 100644 --- a/jamal-yaml/README.adoc +++ b/jamal-yaml/README.adoc @@ -17,7 +17,6 @@ To use this module, you have to add the dependency to your Maven project, as: Following that, you can use the - . <> . <> . <> @@ -30,6 +29,8 @@ Following that, you can use the . <> . <> . <> +. <> + macros. @@ -113,7 +114,7 @@ b: this is c.b The advantage of using this macro over just writing the Yaml directly to the output is that: -* you can split up the Yaml file into smaller pieces using the <>, and <> macros, +* you can split up the Yaml file into smaller pieces using the <>, and <> macros, * you can use user-defined macro parameters mixing the yaml content with Jamal macros. @@ -260,7 +261,7 @@ The format of the macro is ---- -User-defined Yaml macros created using the <> or <> macros may reference other user-defined Yaml macros. +User-defined Yaml macros created using the <> or <> macros may reference other user-defined Yaml macros. When you invoke the macro `yaml:resolve`, it will replace the references in the Yaml macro content with the content of the Yaml macro it references. The resolving process is recursive. If there are any references in the referenced Yaml macro, it will also be resolved. @@ -621,7 +622,7 @@ This macro does not test the structure. It simply tells that the structure went through the resolve process or not. Usually there is narrow use of this macro. -There is no penalty invoking <> on a structure that was already resolved. +There is no penalty invoking <> on a structure that was already resolved. The macro resolve does not re-run the resolution process for a structure that was already resolved. Other macros that need resolved structures automatically invoke resolving. @@ -650,7 +651,7 @@ For more information about the OGNL language visit the web site https://commons. When getting a value out of a Yaml user defined macro the macro will automatically be resolved. The resolution can be cloning or in-place. -To control the resolution process the same options can be used as for the <> macro. +To control the resolution process the same options can be used as for the <> macro. ===== Examples @@ -682,9 +683,10 @@ deep h === vii. `yaml:set` -The macro `yaml:set` can define a yaml user defined macro from an already existing yaml macro. -It is similar to `yaml:define` but this macro does not parse a text and interpret it as yaml formatted text. -Instead, it uses an already defined yaml user defined macro and uses some part of it, and it assignes that to a new user defined macro name. +The macro `yaml:set` can define a user-defined YAML macro from an already existing YAML macro. +It is similar to `yaml:define` but this macro does not parse a text and does not interpret it as YAML formatted text. +Instead, it uses an already defined YAML user-defined macro and uses some part of it. +It assigns the specific part to a new user-defined macro. The syntax of the macro is @@ -698,11 +700,11 @@ The syntax of the macro is ** `yamlResolveClone` (alias `clone`) to clone ** `yamlResolveCopy` (alias `copy`) to copy resolve - ** `yamlDataSource` (alias `from`) the name of the user defined macro which is the source of the data + ** `yamlDataSource` (alias `from`) the name of the user-defined macro which is the source of the data -If the `from` value is missing then the macro interprets the `OGNL` expression star as the name of the macro. -It should start as `/xxxx.`. -The identifier `xxxx` between the starting `/` and the `.` is used as the name of the macro, from which the data is to be fetched. +If the `from` value is missing then the macro interprets the `OGNL` expression start as the name of the macro. +In this case the first character of the expression has to be `/`. +It essentially will start with `/xxxx.` where `xxxx` is the name of the macro. The `macroName` is the name of the macro to assign the new object value to. @@ -737,6 +739,43 @@ deep h ---- +When calling set the new macro will refer to the same object as the original one. +It does not create a copy of the object pointed by the OGNL expression. +This is demonstrated with the followinf example: + +.Jamal source +[source] +---- +{@yaml:define a= +a: alma +b: + c: 3 + d: + - 1 + - 2 + - q: + h: shallow dust} +{@yaml:set s=/a.b.d[2].q} +{@yaml:add to=a.b.d[2].q key=z +deep water +} +{s} +---- + +We set the reference to the object `q`. +Then we add a new key-value pair to the object `q` using the macro `a`. +In the output the result is modified in the macro `s` as well. + +.output +[source] +---- +h: shallow dust +z: deep water +---- + + +It is the behavior even of the `clone` or `copy` options are used. +These options are controlling the resolution process and not the object creation. [[add]] === viii. `yaml:add` @@ -781,7 +820,7 @@ When this option is specified it is an error to specify any `key` since in this ==== Examples -===== Adding a value to the top level Map +===== Adding a value to the top-level Map This example adds a new value to the root of the Yaml structure. @@ -1848,13 +1887,146 @@ The format of the macro is: {@yaml:output yamlMacro} ---- -Here the `yamlMacro` is the name of a Yaml macro to be rendered as the final output of the Jamal processing. +Here the `yamlMacro` is the name of a YAML macro to be rendered as the final output of the Jamal processing. It has to be defined at the end of the processing. It also means that this macro has to be on the top level in the macro hierarchy. In other words, it has to be a global macro. When this macro is used, the output of the Jamal processing will be the Yaml formatted structure of the data held in the macro `yamlMacro`. If this macro contained references and was not yet resolved, then it will be resolved. -Since this is the last step processing the whole Jamal structure following the entire process, usually there is no need for cloning. +Since this is the last step to processing the whole Jamal structure following the entire process, usually there is no need for cloning. If for any reason there is need for cloning then the `clone` option may be used on the command. The command also supports the `copy` option. + +[[Looping]] +==== xiii. Looping over values + +There is no special macro to support looping over values in a YAML structure. +It can be done using the core `for` macro. + +The core `for` macro has two forms. +The conventional is when the macro loops over strings provided in the macro invocation. +In this case the loop the `in` keyword separates the variables from the value list. + +The other case is when the looping is over some Java object. +In this case the `from` keyword separates the variable from the macro holding the object. +These macros must be so-called "object holder" macros, and the user-defined YAML macros are such. + +In the following example we have a YAML structure defined in the macro `games`. +This structure has two lists, `PCgames` and `ConsoleGames`. +We want to loop over the `PCgames` list. + +.Jamal source +[source] +---- +{@yaml:define games= +PCgames: + - "Doom" + - "Quake" + - "Unreal" +ConsoleGames: + - "Mario" + - "Zelda" + - "Metroid" + } +{@yaml:set cGames=/games.PCgames} +{@for game from cGames= +- game} +---- + +The output is the list of the games under the `PCgames` key. + +.output +[source] +---- +- Doom +- Quake +- Unreal +---- + + +Note that we had to use the macro `yaml:set` to set the `cGames` macro to the `PCgames` list. +That is because the `for` macro can only loop over an object provided by a macro. +Writing + +.Jamal source +[source] +---- +{@yaml:define games= +PCgames: +- "Doom" +- "Quake" +- "Unreal" +ConsoleGames: +- "Mario" +- "Zelda" +- "Metroid" +} +{@yaml:set cGames=/games.PCgames} +{@try! {#for game from {@yaml:get /games.PCgames} +- game}} +---- + +will result in the error message: + +.output +[source] +---- +The user defined macro '[Doom,' does not exist or cannot be used as data source for a 'for' loop. +---- + + +because the `{@yaml:get /games.PCgames}` macro evaluated is a string and not a macro. +As you can see from the error message, the result of the macro is the list of the game names. + +You can iterate through lists and maps in the same way. +When you iterate through maps you will get the keys: + +.Jamal source +[source] +---- +{@yaml:define cGames= + first: "Doom" + second: "Quake" + third: "Unreal" +} +{@for game from cGames= +- game} +---- + +The output is the list of the games under the `PCgames` key. + +.output +[source] +---- +- first +- second +- third +---- + + +If you want to go deeper, you can use the loop variable as a key in the map. +For example, you can loop through the list of games by key: + +.Jamal source +[source] +---- +cGames is still defined from the prior example +{!@for game from cGames= +{@yaml:get (from=cGames) game}} +---- + +The output is the list of the games under `cGames` + +.output +[source] +---- +cGames is still defined from the prior example + +Doom +Quake +Unreal +---- + + +For a full-fledged example how to document an OpenAPI stack using Jamal and the YAML macros, visit the documentation at https://github.com/serverless-u/AxsessGard/blob/main/README.adoc.jam. \ No newline at end of file diff --git a/jamal-yaml/README.adoc.jam b/jamal-yaml/README.adoc.jam index 33faa4f5..9ba88cd2 100644 --- a/jamal-yaml/README.adoc.jam +++ b/jamal-yaml/README.adoc.jam @@ -18,7 +18,10 @@ To use this module, you have to add the dependency to your Maven project, as: ---- Following that, you can use the -{%@define chap($x)=. <<$x,`yaml:$x`>>%}{%@define ImportingChapter=Importing yaml from a file%} +{%@define chap($x)=. <<$x,`yaml:$x`>>%}\ +{%@define chapNm($x)=. <<$x,`$x`>>%}\ +{%@define ImportingChapter=Importing yaml from a file%}\ +{%@define Looping=Looping over values%}\ {%chap define%} {%chap ref%} @@ -32,10 +35,14 @@ Following that, you can use the {%chap dump%} {%chap xml%} {%chap output%} +. <> {%@define chap($x)=[[$x]] === {%macroChapter%}`yaml:$x` %}{%@define link($x)=<<$x,`yaml:$x`>>%} +{%@define chapNm($x)=[[$x]] +=== {%macroChapter%}`$x` +%}{%@define link($x)=<<$x,`$x`>>%} macros. == Macros implemented in the package @@ -471,9 +478,10 @@ will result {%chap set%} -The macro `yaml:set` can define a yaml user defined macro from an already existing yaml macro. -It is similar to `yaml:define` but this macro does not parse a text and interpret it as yaml formatted text. -Instead, it uses an already defined yaml user defined macro and uses some part of it, and it assignes that to a new user defined macro name. +The macro `yaml:set` can define a user-defined YAML macro from an already existing YAML macro. +It is similar to `yaml:define` but this macro does not parse a text and does not interpret it as YAML formatted text. +Instead, it uses an already defined YAML user-defined macro and uses some part of it. +It assigns the specific part to a new user-defined macro. The syntax of the macro is @@ -485,11 +493,11 @@ The syntax of the macro is ** `yamlResolveClone` (alias `clone`) to clone ** `yamlResolveCopy` (alias `copy`) to copy resolve - ** `yamlDataSource` (alias `from`) the name of the user defined macro which is the source of the data + ** `yamlDataSource` (alias `from`) the name of the user-defined macro which is the source of the data -If the `from` value is missing then the macro interprets the `OGNL` expression star as the name of the macro. -It should start as `/xxxx.`. -The identifier `xxxx` between the starting `/` and the `.` is used as the name of the macro, from which the data is to be fetched. +If the `from` value is missing then the macro interprets the `OGNL` expression start as the name of the macro. +In this case the first character of the expression has to be `/`. +It essentially will start with `/xxxx.` where `xxxx` is the name of the macro. The `macroName` is the name of the macro to assign the new object value to. @@ -515,6 +523,35 @@ will result {%output%} +When calling set the new macro will refer to the same object as the original one. +It does not create a copy of the object pointed by the OGNL expression. +This is demonstrated with the followinf example: + +{%sample/ +{@yaml:define a= +a: alma +b: + c: 3 + d: + - 1 + - 2 + - q: + h: shallow dust} +{@yaml:set s=/a.b.d[2].q} +{@yaml:add to=a.b.d[2].q key=z +deep water +} +{s} +%} + +We set the reference to the object `q`. +Then we add a new key-value pair to the object `q` using the macro `a`. +In the output the result is modified in the macro `s` as well. + +{%output%} + +It is the behavior even of the `clone` or `copy` options are used. +These options are controlling the resolution process and not the object creation. {%chap add%} @@ -555,7 +592,7 @@ When this option is specified it is an error to specify any `key` since in this ==== Examples -===== Adding a value to the top level Map +===== Adding a value to the top-level Map This example adds a new value to the root of the Yaml structure. @@ -1058,13 +1095,110 @@ The format of the macro is: {@yaml:output yamlMacro} %} -Here the `yamlMacro` is the name of a Yaml macro to be rendered as the final output of the Jamal processing. +Here the `yamlMacro` is the name of a YAML macro to be rendered as the final output of the Jamal processing. It has to be defined at the end of the processing. It also means that this macro has to be on the top level in the macro hierarchy. In other words, it has to be a global macro. When this macro is used, the output of the Jamal processing will be the Yaml formatted structure of the data held in the macro `yamlMacro`. If this macro contained references and was not yet resolved, then it will be resolved. -Since this is the last step processing the whole Jamal structure following the entire process, usually there is no need for cloning. +Since this is the last step to processing the whole Jamal structure following the entire process, usually there is no need for cloning. If for any reason there is need for cloning then the `clone` option may be used on the command. The command also supports the `copy` option. + +[[Looping]] +==== {%macroChapter%}{%Looping%} + +There is no special macro to support looping over values in a YAML structure. +It can be done using the core `for` macro. + +The core `for` macro has two forms. +The conventional is when the macro loops over strings provided in the macro invocation. +In this case the loop the `in` keyword separates the variables from the value list. + +The other case is when the looping is over some Java object. +In this case the `from` keyword separates the variable from the macro holding the object. +These macros must be so-called "object holder" macros, and the user-defined YAML macros are such. + +In the following example we have a YAML structure defined in the macro `games`. +This structure has two lists, `PCgames` and `ConsoleGames`. +We want to loop over the `PCgames` list. + +{%sample/ +{@yaml:define games= +PCgames: + - "Doom" + - "Quake" + - "Unreal" +ConsoleGames: + - "Mario" + - "Zelda" + - "Metroid" + } +{@yaml:set cGames=/games.PCgames} +{@for game from cGames= +- game} +%} + +The output is the list of the games under the `PCgames` key. + +{%output%} + +Note that we had to use the macro `yaml:set` to set the `cGames` macro to the `PCgames` list. +That is because the `for` macro can only loop over an object provided by a macro. +Writing + +{%sample/ +{@yaml:define games= +PCgames: +- "Doom" +- "Quake" +- "Unreal" +ConsoleGames: +- "Mario" +- "Zelda" +- "Metroid" +} +{@yaml:set cGames=/games.PCgames} +{@try! {#for game from {@yaml:get /games.PCgames} +- game}} +%} + +will result in the error message: + +{%output%} + +because the `{@yaml:get /games.PCgames}` macro evaluated is a string and not a macro. +As you can see from the error message, the result of the macro is the list of the game names. + +You can iterate through lists and maps in the same way. +When you iterate through maps you will get the keys: + +{%sample/ +{@yaml:define cGames= + first: "Doom" + second: "Quake" + third: "Unreal" +} +{@for game from cGames= +- game} +%} + +The output is the list of the games under the `PCgames` key. + +{%output%} + +If you want to go deeper, you can use the loop variable as a key in the map. +For example, you can loop through the list of games by key: + +{%sample/ +cGames is still defined from the prior example +{!@for game from cGames= +{@yaml:get (from=cGames) game}} +%} + +The output is the list of the games under `cGames` + +{%output%} + +For a full-fledged example how to document an OpenAPI stack using Jamal and the YAML macros, visit the documentation at https://github.com/serverless-u/AxsessGard/blob/main/README.adoc.jam. \ No newline at end of file