NAME

       begin-handler -  (service-processing)

PURPOSE

       Define a request handler.

SYNTAX

           begin-handler <request path> [ private | public ]
               <any code>
           end-handler

DESCRIPTION

       begin-handler  starts  the implementation of a request handler for <request path> (see request), which is
       <any code> up to end-handler. <request path> is not quoted.

       A <request path> is a path  consisting  of  any  number  of  path  segments.  A  request  path  can  have
       alphanumeric characters, hyphens and forward slashes, and can start only with a forward slash.

       For  example,  a  <request path> can be "/wine-items" or "/items/wine" etc. In general, it represents the
       nature of a request, such as an action on an object, a resource path handled  by  it  etc.  There  is  no
       specific way to interpret a request path, and you can construct it in a way that works for you.

       The  source  ".golf"  file name that implements a given begin-handler matches its path and name, fully or
       partially  (see  request).  For  example,  <request  path>  of  "/items/wine"  might  be  implemented  in
       "items/wine.golf" file (meaning in file "wine.golf" in subdirectory "items").

       Note  that you can also use "%%" instead of either begin-handler or end-handler or both. A <request path>
       cannot be a C reserved word, such as for instance "main" or "typedef" etc.

       SECURITY OF REQUEST CALLS

       If "public" clause is used, then a handler can be called from an outside caller, be  it  a  web  browser,
       some web service, service call or command-line program.

       If  "private"  clause  is  used,  then  a handler cannot be called from an outside caller; it can only be
       called from another handler by using call-handler statement.

       If neither "public" nor "private" is  used,  then  the  default  is  "private".  This  default  mechanism
       automatically guards direct execution by outside callers of all handlers not marked "public"; it provides
       automatic safety guard.

       You can change this default behavior with "--public" option in gg, in which case the default is "public".
       This  is  useful  if  either  all  request handlers should be public, or if only a handful fixed ones are
       private.

EXAMPLES

       The following begin-handler is implemented in file "items/wines/red-wine.golf":

           begin-handler  /items/wines/red-wine public
               @This is a request handler to display a list of red wines!
           end-handler

       Another way to write this is:

           %%  /items/wines/red-wine public
               @This is a request handler to display a list of red wines!
           %%

SEE ALSO

        Service processing

       after-handler before-handler begin-handler call-handler See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)