diff options
Diffstat (limited to 'www/aws-demos/files/templates.tads')
| -rw-r--r-- | www/aws-demos/files/templates.tads | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/www/aws-demos/files/templates.tads b/www/aws-demos/files/templates.tads new file mode 100644 index 000000000000..6691d4b43161 --- /dev/null +++ b/www/aws-demos/files/templates.tads @@ -0,0 +1,264 @@ +@@-- This template is intended as a model of how to generate an Ada package +@@-- describing all the variables used in a set of AWS templates. +@@-- These Ada packages can then be used in your application to avoid +@@-- hard-coded strings, and help maintain the templates and the code to +@@-- parse them in sync. +@@-- +@@-- This template contains two possible behaviors, chosen through the +@@-- following variable: +@@SET@@ SINGLE_FILE = False +@@-- If you set it to True, then a single Ada package with its nested +@@-- packages is generated. If you set it to False, then the file generated +@@-- should be further processed through gnatchop, to generate several +@@-- Ada files organized into several files. This latter organization +@@-- avoids recompiling all your source files every time at least one +@@-- template changes. +@@-- +@@-- The following variable should be changed to set the name of the +@@-- generated packages. +@@SET@@ PACKAGE = Templates +@@-- +@@-- +@@-- When designing your own template for Ada packages, you should take +@@-- into account that the variables in your templates might not necessarily +@@-- be valid Ada identifier names, and you should therefore update the calls +@@-- to @_REPLACE:..._@ below. +@@-- +@@-- This template example also assumes a convention for Lazy_Tags. If you +@@-- are using such types, they are generally shared among templates, and +@@-- the Ada package should reflect that fact. Assuming all such tags start +@@-- with the prefix LAZY_, we generate one special package for them, and +@@-- omit them in all the other packages. +@@-- +@@-- Likewise, the templates2ada tool will not generate tag entries for tags +@@-- that are set through a @@SET@@ statement, since these are purely internal +@@-- to your template file and have no impact on your source code. +@@-- +@@-- For the best use of this tool, it is recommended that your template not +@@-- use @@INCLUDE@@ statements, but instead use a tag, set in the Ada code +@@-- to the preprocessed result of the same template file. This allows you to +@@-- better control unset tags. For instance, instead of using: +@@-- @@INCLUDE@@ foo.thtml +@@-- use something like: +@@-- @_BLOCK_FOO_@ +@@-- and in your Ada code set BLOCK_FOO to the result of Parse ("foo.thtml"). +@@-- +@@-- The templates2ada tool is able to generate constants for the HTTP +@@-- parameters set in your page, so that you can process them in your Ada +@@-- code. A few conventions must be followed, however: +@@-- - The name should be on a single line, preceded by "name=", as in +@@-- name="FOO" +@@-- - The name should use only letters, underscores and digits, unless you +@@-- enhance the regular expressions below to also remove other special +@@-- characters. +@@-- - In some cases, you must use a AWS tag in the name of an HTTP param, +@@-- for instance for checkboxes for which names should be unique (or you +@@-- won't know when the parameter is set to false). In this case, the +@@-- tag must be at the beginning or end of the name, not in the middle. +@@-- If there are multiple tags, they should be separated by non-letters, +@@-- as in: +@@-- name="PN_@_TAG1_@:@_TAG2_" +@@-- In this case, the following constant is generated: +@@-- PN_Prefix : constant String := "PN"; +@@-- - The name mustn't be only an AWS tag. The following is invalid: +@@-- name="@_TAG_@" +@@-- To avoid generating constants for <a name=..>, you must put the name +@@-- attribute right after the "<a". templates2ada doesn't try to parse the +@@-- HTML file, and doesn't know anything about HTML structure. +@@-- +@@-- Some HTTP parameters can be specified as GET parameters. These can be +@@-- documented directly in the templates with the following format: +@@-- @@-- HTTP_GET(name): documentation +@@-- and an entry will be generated for it. +@@-- One additional special kind of comment that is recognized by this tool is +@@-- @@-- HTTP_URL(url): documentation +@@-- This indicates the typical URL(s) associated with that template, and will +@@-- result in an additional string constant in the generated package, which +@@-- can for instance be used when registering the URLs, or when redirecting +@@-- the user to another URL. +@@-- +@@-- If you combine the use of HTTP_GET and HTTP_URL, this can help ensure +@@-- that any URL redirection you do through AWS.Response.URL is valid, if you +@@-- use the generated constants. In addition, you could generate a +@@-- template file (for instance using all_urls.thtml in this distribution) +@@-- that can be included in other templates. +@@-- +@@-- When a variable is removed from a template, your source code will no +@@-- longer compile. When a variable is added, you get no compilation error. +@@-- However, running "gnat xref -u" on your application will help detect +@@-- unreferenced variables, and thus tags that are used in templates but +@@-- never set in the code. For instance: +@@-- gnat xref -Pproject -u main.adb | grep templates +@@-- will list all unused template variables from the template packages that +@@-- are currently in use by your application. Template packages that are not +@@-- even withed will not appear in this listing, but can generally be found +@@-- through appropriate grep commands. +@@-- +@@-- The following tags are available in this template: +@@-- @_VARIABLE_@: Matrix of variable names for the current template, +@@-- sorted alphabetically +@@-- @_FILENAME_@: Vector of template file names. The name contains +@@-- directories relative to the directory given to +@@-- templates2ada +@@-- @_BASENAME_@: Same as @_FILENAME_@, but contains only the base +@@-- names of files, with no extension. +@@-- @_VARIABLE_LIST_@: List of all variables defined in all templates, +@@-- sorted alphabetically +@@-- @_INCLUDE_@: List of templates included by the current template. +@@-- Names are the base name. +@@-- @_HTTP_@: List of http parameters that can be returned by the +@@-- current template, sorted alphabetically. +@@-- @_FROM_GET_@: For each of the HTTP parameters above, this boolean +@@-- indicates whether it was defined in a HTTP_GET +@@-- comment as explained above. +@@-- @_URL_@: List of urls that are associated with the current +@@-- template, sorted alphabetically. +@@-- @_AJAX_EVENT_@: Event name (onclick, onchange...), corresponding +@@-- action in AJAX_ACTION. +@@-- @_AJAX_ACTION_@ Action for the given AJAX_EVENT above. +@@-- @_AJAX_FILE_@ File in which the corresponding action has been +@@-- found. +@@-- @_SET_VAR_@ Name of SET constants in the template +@@-- Only variables with prefix SET_ are exported. +@@-- @_SET_VAL@ Values of the above constants. +@@-- +@@-- This templates is processed through the tool templates2ada +@@-- +@@-- Possible enhancements: +@@-- - Take into account @@IF@@ statements, and make sure that all +@@-- needed variable in each branch is properly set. Hard to do. +@@-- - Have a way to specify comments for the variable, probably as a +@@-- special comment in the template files themselves. +@@-- - Handling of @@INCLUDE@@: the tags defined in the included file +@@-- be also included in the generated package for the template, so +@@-- that we can detect missing definitions. However, this means that +@@-- such tags will be duplicated in several places... It is generally +@@-- simpler to avoid using @@INCLUDE@@ statements. +@@-- We could also use child packages to represent them +@@-- +-- DO NOT EDIT, THIS FILE HAS BEEN GENERATED +package @_PACKAGE_@ is + pragma Style_Checks (Off); + + package Lazy is + @@TABLE@@ + @@IF@@ @_UPPER:SLICE(1..5):VARIABLE_LIST_@ = "LAZY_" + @_CAPITALIZE:REPLACE_ALL(__/_):VARIABLE_LIST_@ : constant String := "@_VARIABLE_LIST_@"; + @@END_IF@@ + @@END_TABLE@@ + end Lazy; + +@@IF@@ @_SINGLE_FILE_@ = True +@@TABLE@@ + package @_CAPITALIZE:REPLACE_ALL(\./_):BASENAME_@ is + Template : constant String := "@_FILENAME_@"; + @@TABLE@@@ + @@IF@@ not @_IS_EMPTY:URL_@ + @@IF@@ @_TABLE_LINE_@ = 1 + URL : constant String := "@_URL_@"; + @@ELSE@@ + URL@_TABLE_LINE_@ : constant String := "@_URL_@"; + @@END_IF@@ + @@END_IF@@ + @@END_TABLE@@ + + @@TABLE@@ + @@IF@@ not @_IS_EMPTY:VARIABLE_@ and @_UPPER:SLICE(1..5):VARIABLE_@ /= "LAZY_" + @_CAPITALIZE:REPLACE_ALL(__/_):VARIABLE_@ : constant String := "@_VARIABLE_@"; + @@END_IF@@ + @@END_TABLE@@ + +@@IF@@ @_EXIST:HTTP_@ + + package HTTP is + @@TABLE@@ + @@IF@@ not @_IS_EMPTY:HTTP_@ + @_CAPITALIZE:REPLACE_ALL(__/_):HTTP_@ : constant String := "@_HTTP_@"; + @@END_IF@@ + @@END_TABLE@@ + end HTTP; +@@END_IF@@ +@@IF@@ @_EXIST:SET_VAR_@ + + package Set is + @@TABLE@@ + @_CAPITALIZE:REPLACE_ALL(__/_):SET_VAR_@ : constant String := "@_SET_VAL_@"; + @@END_TABLE@@ + end Set; +@@END_IF@@ +@@IF@@ @_EXIST:AJAX_EVENT_@ + + package Ajax is + @@TABLE@@ + @@IF@@ not @_IS_EMPTY:AJAX_EVENT_@ + @_CAPITALIZE:AJAX_EVENT_@_@_CAPITALIZE:AJAX_ACTION_@ : constant String := "/@_AJAX_EVENT_@$@_AJAX_ACTION_@"; + @@END_IF@@ + @@END_TABLE@@ + end Ajax; +@@END_IF@@ + + end @_CAPITALIZE:REPLACE_ALL(\./_):BASENAME_@; + +@@END_TABLE@@ +@@END_IF@@ +end @_PACKAGE_@; + +@@IF@@ @_SINGLE_FILE_@ /= True +@@TABLE@@ +@@-- @@TABLE@@ +@@-- @@IF@@ @_EXIST:INCLUDE_@ +@@-- with @_PACKAGE_@.@_CAPITALIZE:REPLACE_ALL(\./_):INCLUDE_@; +@@-- @@END_IF@@ +@@-- @@END_TABLE@@ +-- DO NOT EDIT, THIS FILE HAS BEEN GENERATED +package @_PACKAGE_@.@_CAPITALIZE:REPLACE_ALL(\./_):BASENAME_@ is + pragma Style_Checks (Off); + + Template : constant String := "@_FILENAME_@"; + @@TABLE@@@ + @@IF@@ not @_IS_EMPTY:URL_@ + @@IF@@ @_TABLE_LINE_@ = 1 + URL : constant String := "@_URL_@"; + @@ELSE@@ + URL@_TABLE_LINE_@ : constant String := "@_URL_@"; + @@END_IF@@ + @@END_IF@@ + @@END_TABLE@@ + + @@TABLE@@ + @@IF@@ not @_IS_EMPTY:VARIABLE_@ and @_UPPER:SLICE(1..5):VARIABLE_@ /= "LAZY_" + @_CAPITALIZE:REPLACE_ALL(__/_):VARIABLE_@ : constant String := "@_VARIABLE_@"; + @@END_IF@@ + @@END_TABLE@@ +@@IF@@ @_EXIST:HTTP_@ + + package HTTP is + @@TABLE@@ + @@IF@@ not @_IS_EMPTY:HTTP_@ + @_CAPITALIZE:REPLACE_ALL(__/_):HTTP_@ : constant String := "@_HTTP_@"; + @@END_IF@@ + @@END_TABLE@@ + end HTTP; +@@END_IF@@ +@@IF@@ @_EXIST:SET_VAR_@ + + package Set is + @@TABLE@@ + @_CAPITALIZE:REPLACE_ALL(__/_):SET_VAR_@ : constant String := "@_SET_VAL_@"; + @@END_TABLE@@ + end Set; +@@END_IF@@ +@@IF@@ @_EXIST:AJAX_EVENT_@ + + package Ajax is + @@TABLE@@ + @@IF@@ not @_IS_EMPTY:AJAX_EVENT_@ + @_CAPITALIZE:AJAX_EVENT_@_@_CAPITALIZE:AJAX_ACTION_@ : constant String := "/@_AJAX_EVENT_@$@_AJAX_ACTION_@"; + @@END_IF@@ + @@END_TABLE@@ + end Ajax; +@@END_IF@@ + +end @_PACKAGE_@.@_CAPITALIZE:REPLACE_ALL(\./_):BASENAME_@; +@@END_TABLE@@ +@@END_IF@@ |