mirror of
https://github.com/VCMP-SqMod/SqMod.git
synced 2025-06-16 07:07:13 +02:00
Major plugin refactor and cleanup.
Switched to POCO library for unified platform/library interface. Deprecated the external module API. It was creating more problems than solving. Removed most built-in libraries in favor of system libraries for easier maintenance. Cleaned and secured code with help from static analyzers.
This commit is contained in:
Sandu Liviu Catalin
442
vendor/POCO/PageCompiler/doc/PageCompilerUserGuide.page
vendored
Normal file
442
vendor/POCO/PageCompiler/doc/PageCompilerUserGuide.page
vendored
Normal file
@ -0,0 +1,442 @@
|
||||
POCO C++ Server Page Compiler User Guide
|
||||
POCO PageCompiler
|
||||
|
||||
!!!Introduction
|
||||
|
||||
PageCompiler is a command line tool that translates HTML files (and other kinds of files) into
|
||||
C++ code, more precisely, subclasses of Poco::Net::HTTPRequestHandler.
|
||||
The source files can contain special directives that allow embedding of C++ code.
|
||||
The syntax of these directives is based on the syntax used for
|
||||
Java Server Pages (JSP), Active Server Pages (ASP) or Embedded JavaScript (EJS) templating.
|
||||
|
||||
This makes PageCompiler a C++-based HTML templating system. Since the translation of
|
||||
the HTML template into a C++ class happens at compile time, runtime performance is
|
||||
excellent.
|
||||
|
||||
The following introductory sample shows the code for a simple page that displays the
|
||||
current date and time.
|
||||
|
||||
<%@ page class="TimeHandler" %>
|
||||
<%!
|
||||
#include "Poco/DateTime.h"
|
||||
#include "Poco/DateTimeFormatter.h"
|
||||
#include "Poco/DateTimeFormat.h"
|
||||
|
||||
|
||||
using Poco::DateTime;
|
||||
using Poco::DateTimeFormatter;
|
||||
using Poco::DateTimeFormat;
|
||||
%>
|
||||
|
||||
<%
|
||||
DateTime now;
|
||||
std::string dt(DateTimeFormatter::format(now, DateTimeFormat::SORTABLE_FORMAT));
|
||||
%>
|
||||
<html>
|
||||
<head>
|
||||
<title>Time Sample</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Time Sample</h1>
|
||||
<p><%= dt %></p>
|
||||
</body>
|
||||
</html>
|
||||
----
|
||||
|
||||
Sending the above code to the page compiler will generate two files, a header file
|
||||
(<[TimeHandler.h]>) and an implementation file (<[TimeHandler.cpp]>).
|
||||
The files define a subclass of Poco::Net::HTTPRequestHandler named <[TimeHandler]>.
|
||||
The generated <[handleRequest]> member function contains code to send the HTML
|
||||
code contained in the source file to the client, as well as the C++ code fragments found
|
||||
in between the Scriptlet tags.
|
||||
|
||||
|
||||
!!!C++ Server Page Syntax
|
||||
|
||||
The following special tags are supported in a C++ server page (CPSP) file.
|
||||
|
||||
!!Hidden Comment
|
||||
|
||||
A hidden comment documents the CPSP file, but is not sent to the client.
|
||||
|
||||
<%-- <comment> --%>
|
||||
----
|
||||
|
||||
!!Implementation Declaration
|
||||
|
||||
An implementation declaration is copied to the implementation file immediately after
|
||||
the block containing the standard <[#include]> directives.
|
||||
It is used to include additional header files and <[using]> declarations,
|
||||
as well as to define classes needed later on.
|
||||
|
||||
<%!
|
||||
<declaration>
|
||||
...
|
||||
%>
|
||||
----
|
||||
|
||||
!!Header Declaration
|
||||
|
||||
A header declaration is copied to the header file immediately after the
|
||||
block containing the standard <[#include]> directives.
|
||||
It is usually used to include the header file containing the definition
|
||||
of the base class for the request handler, if a custom base class
|
||||
is required.
|
||||
|
||||
<%!!
|
||||
<declaration>
|
||||
...
|
||||
%>
|
||||
----
|
||||
|
||||
!!Expression
|
||||
|
||||
The result of any valid C++ expression can be directly inserted into the page,
|
||||
provided the result can be written to an output stream. Note that the expression
|
||||
must not end with a semicolon. If HTML escape mode is enabled (new in POCO C++ Libraries
|
||||
release 1.10.0), HTML special characters < > " &
|
||||
will be replaced with corresponding character entities.
|
||||
|
||||
<%= <expression> %>
|
||||
----
|
||||
|
||||
An alternative form of this is:
|
||||
|
||||
<%- <expression> %>
|
||||
----
|
||||
|
||||
The latter form always copies the result of expression to the page verbatim,
|
||||
without escaping special HTML characters.
|
||||
|
||||
Note that if escape mode is disabled, both forms are equivalent.
|
||||
|
||||
|
||||
!!Scriptlet
|
||||
|
||||
Arbitrary C++ code fragments can be included using the Scriptlet directive.
|
||||
|
||||
<%
|
||||
<statement>
|
||||
...
|
||||
%>
|
||||
----
|
||||
|
||||
!!Pre-Response Scriptlet
|
||||
|
||||
This is similar to an ordinary scriptlet, except that it will be executed
|
||||
before the HTTP response is sent. This can be used to manipulate the HTTP response
|
||||
object.
|
||||
|
||||
<%%
|
||||
<statement>
|
||||
...
|
||||
%>
|
||||
|
||||
The main feature of this directive is that it allows to send a redirect response to
|
||||
the client if a certain condition is true.
|
||||
|
||||
Example:
|
||||
<%%
|
||||
if (!loggedIn)
|
||||
{
|
||||
return response.redirect("/");
|
||||
}
|
||||
%>
|
||||
|
||||
!!Include Directive
|
||||
|
||||
Another CPSP file can be included into the current file using the Include
|
||||
Directive.
|
||||
|
||||
<%@ include file="<path>" %>
|
||||
----
|
||||
|
||||
Alternatively, this can also be written as:
|
||||
|
||||
<%@ include page="<path>" %>
|
||||
----
|
||||
|
||||
!!C++ Header Include Directive
|
||||
|
||||
Include a C++ header file in the generated header file.
|
||||
<%@ header include="<path>" %>
|
||||
|
||||
This corresponds to:
|
||||
<%!! #include "<path>" %>
|
||||
|
||||
A variant of this directive is:
|
||||
<%@ header sinclude="<path>" %>
|
||||
|
||||
This corresponds to:
|
||||
<%!! #include <<path>> %>
|
||||
|
||||
|
||||
!!C++ Implementation Include Directive
|
||||
|
||||
Include a C++ header file in the generated implementation file.
|
||||
<%@ impl include="<path>" %>
|
||||
|
||||
This corresponds to:
|
||||
<%! #include "<path>" %>
|
||||
|
||||
A variant of this directive is:
|
||||
<%@ impl sinclude="<path>" %>
|
||||
|
||||
This corresponds to:
|
||||
<%! #include <<path>> %>
|
||||
|
||||
|
||||
!!Page Directive
|
||||
|
||||
The Page Directive allows the definition of attributes that control
|
||||
various aspects of C++ code generation.
|
||||
|
||||
<%@ page <attr>="<value>" ... %>
|
||||
----
|
||||
|
||||
The following page attributes are supported:
|
||||
|
||||
!class
|
||||
|
||||
Specifies the name of the generated class.
|
||||
Defaults to the base name of the source file with the word "Handler" appended.
|
||||
|
||||
!namespace
|
||||
|
||||
If specified, sets the namespace where the generated classes will be in.
|
||||
No namespace will be used if omitted.
|
||||
|
||||
!baseClass
|
||||
|
||||
Specifies the name of the class used as the base class for the generated
|
||||
request handler class.
|
||||
Defaults to Poco::Net::HTTPRequestHandler. Do not forget to add a Header Declaration
|
||||
containing an <[#include]> directive for the header file containing the definition
|
||||
of that class, otherwise the generated code won't compile.
|
||||
|
||||
!context
|
||||
|
||||
Allows passing of a context object to the request handler's constructor.
|
||||
The context object is stored in the request handler object and can be
|
||||
obtained by calling the context() object.
|
||||
|
||||
The class of the context object must be specified.
|
||||
Cannot be used together with <[ctorArg]>.
|
||||
|
||||
!ctorArg
|
||||
|
||||
Allows to specify the type of a single argument being passed to the constructor
|
||||
of the generated request handler class. Can only be used together with <[baseClass]>.
|
||||
The argument is passed on to the constructor of the base class, therefore, one of the
|
||||
constructors of the base class must also accept a single argument of the specified type.
|
||||
|
||||
Cannot be used together with <[context]>.
|
||||
|
||||
!escape
|
||||
|
||||
Enable (set to <[true]>) or disable (<[false]>, default) HTML escape mode.
|
||||
If enabled, the result of any expression enclosed in <%= %> tags will be HTML-escaped,
|
||||
which means HTML special characters < > " & will be replaced by corresponding
|
||||
character entities.
|
||||
|
||||
!export
|
||||
|
||||
Allows to specify a DLL import/export directive that is being added to the request
|
||||
handler class definition. Useful for exporting a request handler class from a
|
||||
Windows DLL.
|
||||
|
||||
!form
|
||||
|
||||
Enable or disable automatic form handling. If enabled, which is the default,
|
||||
a Poco::Net::HTMLForm object is automatically created in the request handler
|
||||
and accessible through a variable named <[form]>.
|
||||
Set the value to <[false]> to disable form handling.
|
||||
|
||||
!formPartHandler
|
||||
|
||||
Allows you to pass a Poco::Net::PartHandler object to the form object for
|
||||
processing file uploads. A subclass of Poco::Net::PartHandler must be
|
||||
defined (using an Implementation Declaration), and the constructor of the part
|
||||
handler must take a (const) reference to the request handler instance as argument.
|
||||
|
||||
!contentType
|
||||
|
||||
Allows you to specify the MIME content type for the page. Defaults to text/html.
|
||||
|
||||
!contentLanguage
|
||||
|
||||
Allows to specify a language tag (e.g., "en") that will be sent in the
|
||||
response Content-Language header if the client sends an Accept-Language
|
||||
header in the request.
|
||||
|
||||
!contentSecurityPolicy
|
||||
|
||||
Allows to specify the value of the HTTP Content-Security-Policy header.
|
||||
|
||||
!chunked
|
||||
|
||||
Allows you to specify whether the response is sent using chunked transfer encoding.
|
||||
Defaults to <[true]>.
|
||||
Set the value to <[false]> to disable chunked transfer encoding.
|
||||
|
||||
!compressed
|
||||
|
||||
Enables or disables response body compression. If set to <[true]>, and the client supports
|
||||
the "gzip" content encoding (indicated by the "Accept-Encoding" header),
|
||||
the response body will be compressed using the "gzip" format and the
|
||||
"Content-Encoding" header will be set accordingly.
|
||||
Defaults to <[false]>. Cannot be enabled together with response buffering.
|
||||
|
||||
!compressionLevel
|
||||
|
||||
Specify the compression level, if response body compression is enabled.
|
||||
Valid values are 1 (fastest) to 9 (best compression). Defaults to 1.
|
||||
|
||||
!buffered
|
||||
|
||||
Enables or disables response buffering. Response buffering is disabled by default.
|
||||
Set to <[true]> to enable buffering, or to <[false]> to disable it.
|
||||
If response buffering is enabled, everything written to the response stream
|
||||
is actually written to a string stream (<[std::ostringstream]>).
|
||||
Sending of the HTTP response back to the client is deferred to
|
||||
when the page is complete.
|
||||
|
||||
!cacheControl
|
||||
|
||||
If set to a non-empty string (e.g., "no-cache, no-store"), adds a "Cache-Control"
|
||||
header to the response with the given argument as value.
|
||||
|
||||
!session (OSP only)
|
||||
|
||||
For use with the POCO Open Service Platform only.
|
||||
|
||||
Specifies the identifier of the session obtained from the OSP Web Session Manager.
|
||||
If specified, a Poco::OSP::Web::WebSession object will be available in the
|
||||
request handler through a variable named <[session]>. The variable is of type
|
||||
Poco::OSP::Web::WebSession::Ptr. If the identifier starts with an asterisk
|
||||
('@'), the identifier is considered to be a bundle property name, and the
|
||||
session identifier is read from the respective bundle property.
|
||||
|
||||
!sessionTimeout (OSP only)
|
||||
|
||||
For use with the POCO Open Service Platform only.
|
||||
|
||||
Specifies the session timeout in minutes.
|
||||
If the argument is a string, it is considered to be a bundle property name
|
||||
and the timeout value is read from the respective bundle property.
|
||||
|
||||
!createSession (OSP only)
|
||||
|
||||
For use with the POCO Open Service Platform only.
|
||||
|
||||
If set to <[true]>, which is the default if the attribute is not specified,
|
||||
a new session will be created if the request does not contain a (valid) session cookie.
|
||||
If set to <[false]> and there is no existing session that matches the session
|
||||
cookie. the <[session]> variable will be null.
|
||||
|
||||
!precondition
|
||||
|
||||
Allows to specify a C++ boolean expression which will be evaluated before processing
|
||||
of the page begins. If the expression evaluates to false, processing of the
|
||||
page is immediately terminated and no response is sent to the client.
|
||||
|
||||
The expression can be a call to a member function defined in the handler base class.
|
||||
If that function returns false, it can send its own response to the client.
|
||||
|
||||
Example:
|
||||
<%@ page precondition="checkCredentials(request, response)" %>
|
||||
----
|
||||
|
||||
!path
|
||||
|
||||
Specify a server path for the page. If specified, the generated handler class
|
||||
will contain a public static <[const std::string]> member variable named <[PATH]>
|
||||
containing the specified path.
|
||||
|
||||
Example:
|
||||
<%@ page path="/index.html" %>
|
||||
----
|
||||
|
||||
|
||||
!!Implicit Objects
|
||||
|
||||
The following objects are available in the handler code.
|
||||
|
||||
!request
|
||||
|
||||
The HTTP request object - an instance of Poco::Net::HTTPServerRequest.
|
||||
|
||||
!response
|
||||
|
||||
The HTTP response object - an instance of Poco::Net::HTTPServerRequest.
|
||||
|
||||
!responseStream
|
||||
|
||||
The output stream where the response body is written to.
|
||||
|
||||
!form
|
||||
|
||||
An instance of Poco::Net::HTMLForm for processing form arguments.
|
||||
Only available if form processing has not been disabled by
|
||||
setting the <[form]> page attribute to <[false]>.
|
||||
|
||||
!session (OSP only)
|
||||
|
||||
An instance of Poco::OSP::Web::WebSession::Ptr for accessing the
|
||||
Poco::OSP::Web::WebSession object for the current session.
|
||||
Only available with the POCO Open Service Platform, and if the
|
||||
<[session]> page attribute has been specified. May be null if
|
||||
the <[createSession]> attribute is false and no session exists.
|
||||
|
||||
|
||||
!!!Invoking the Page Compiler
|
||||
|
||||
The Page Compiler is invoked from the command line. The file names of the
|
||||
CPSP files to be compiled are specified as arguments.
|
||||
|
||||
A number of options control the code generation. Options are specified
|
||||
using the usual command-line option syntax for the current operating
|
||||
system (e.g., <[/help]> on Windows, <[--help]> or <[-h]> on Unix).
|
||||
|
||||
* help (h): display usage information
|
||||
* define (D): define a configuration property
|
||||
* config-file (f): load configuration properties from a file
|
||||
* osp (O): add factory class definition/implementation for use with OSP
|
||||
* apache (A): add factory class definition/implementation and shared library manifest for use with ApacheConnector
|
||||
* escape (e): make HTML-escape mode default for all pages
|
||||
|
||||
Run the PageCompiler with the --help option to see all available options.
|
||||
|
||||
|
||||
!!Configuration Properties
|
||||
|
||||
The Page Compiler supports one configuration property, named
|
||||
<[PageCompiler.fileHeader]>, to optionally specify a header that is
|
||||
included in every generated file.
|
||||
|
||||
The file header can contain references to other configuration properties,
|
||||
using the usual property syntax: <[${property}]>.
|
||||
|
||||
For example, invoking the Page Compiler with the following configuration
|
||||
file:
|
||||
|
||||
PageCompiler.fileHeader = //\n// ${outputFileName}\n//\n
|
||||
----
|
||||
|
||||
places the following header at the beginning of each generated file
|
||||
(<[<filename>]> is replaced with the actual name of the file):
|
||||
|
||||
//
|
||||
// <filename>
|
||||
//
|
||||
----
|
||||
|
||||
The following pre-defined properties can be used in the file header:
|
||||
|
||||
* <[${inputFileName}]>: the name of the input file (with directories removed)
|
||||
* <[${inputFilePath}]>: the complete path of the input file
|
||||
* <[${dateTime}]>: the current date and time (YYYY-MM-DD HH:MM:SS)
|
||||
* <[${outputFileName}]>: the name of the current output file (header or implementation file), with
|
||||
directories removed
|
||||
* <[${outputFilePath}]>: the complete path of the current output file
|
||||
|
||||
Reference in New Issue
Block a user