libtemplates-parser-doc 17.2-3 / usr / share / doc / libtemplates-parser-doc / examples / templates.tads

@@--  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@@