ecpp(7)

📦

version 3.0 · 3 versions

3.0 · debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
2.2.1 · ubuntu jammy
3.0 · fedora 43, fedora 44, nixos 26.05

, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ ecpp — the tntnet(8) template language, bestie edition ✨

sooo this is ecpp(7) from the Tntnet users guide and it's about to be your whole personality, no cap. 🎀

🌸 NAME 🌸

ecpp — the template language for tntnet(8). that's it, that's the name, slay. 💅

🦋 DESCRIPTION 🦋

okay so ecpp is the template language the tntnet system uses to generate dynamic content. literally its whole job. 💖

A template is just normal content (normally html data) that's been enriched with special tags — and those tags trigger some special handling. that's the vibe. that's the whole vibe. ✨

Here's the part that lowkey blows my mind: one ecpp file gets compiled into a C++ class. one file → one class. The C++ class lands in the namespace component, and an ecpp file that's been compiled into a C++ class is called a component. And the name of the class? it's just the basename of the file. iconic behavior honestly. 👑

🫶 request, reply, qparam 🫶

Every single component has 3 parameters: request, reply and qparam. three besties. let's meet them. 💜

request — holds the info about the client request, like http headers and the url, plus additional parameters specified in the config file tntnet.xml(7). Its type is tnt::HttpRequest. 📨
reply — receives the answer from the component. this is where the component can set additional http headers, set cookies, and — most important — generate output. The most important methods here are reply.out() and reply.sout(). Both return a std::ostream, which receives the output of the component. 📤

here's the tea tho: reply.sout() has a filter installed on it that translates some characters — the ones with special meanings in html — into the corresponding html entities. the characters are <, >, " and '. this is sooo useful for printing values from variables straight into the html code. 🧚

qparam — holds the query parameters parsed from GET- or POST-parameters, or received from other components. Its type is tnt::QueryParams. Normally you use a <%args> block to specify the parameters, but there are special cases where it's useful to access these directly. 🍓

🌈 component addressing 🌈

Each component has a unique name. The name is composed from:

the class name
the character '@'
the name of the shared library it's located in

Components can also have internal sub components. The name of the internal sub component is appended to the class name, separated by a dot (.). so like, dot notation but make it components. 💅

💀 special rule for line feeds after a `</%something>`-tag 💀

okay this one is weird but important: a line feed immediately after a closing tag for all <%something> blocks is ignored. 🙈

so blocks that follow immediately one after another do not generate white space in output — which is often super undesirable. hence the rule. the more you know. ⭐

😭 errorhandling 😭

Error handling is done by exception. Tntnet catches all exceptions thrown by components and handles them properly.

Exceptions must be derived from std::exception.
Exceptions derived from tnt::HttpError are handled separately. They carry a http return code, which is sent to the client.
Other exceptions derived from std::exception result in a http error code 500 (Internal Server Error).

so fr fr, derive from std::exception or the whole thing falls apart bestie. 😌

✨ more coming, don't go anywhere ✨

✨ TAGS ✨

okay bestie, this is the section where ecpp shows off. sit down, hydrate, we're going through every single tag 💅

<$ expr $> — prints the expression expr to the output stream. The characters <, >, ,, " and ' all have special meanings in html, so they get translated to the corresponding html entities. no raw chaos escaping into your html, we're being responsible today ✨
<$$ expr $> — prints the expression expr to the output stream, but this time without translating the characters that have special meaning in html into html entities. raw, unfiltered, out here living its truth 😌
<? cond ? expr ?> — conditional output. Prints the expression expr to the output stream if cond evaluates to true. Characters with special meaning in html get translated to the corresponding html entities. 🎀
<?? cond ? expr ?> — conditional output too. Prints expr to the output stream if cond evaluates to true, and the characters with special meaning in html are not translated to the corresponding html entities. 🙈
< component [ arguments ] > — calls the specified component. The output of the component gets printed into the output stream. If the component name does not start with a letter, the ecpp compiler treats it as an expression, which returns the name of the component. And if that expression has spaces in it, you must surround it in brackets. lowkey strict but fair.

The arguments part specifies the parameters the component will receive. Arguments are name-value pairs separated by =. They get put in the qparam parameter of the component and are normally declared in the <%args> block. Values can be specified in 3 forms:

a plain word without spaces
a string enclosed in quotation marks
an expression enclosed in brackets

A single plain word in the argument list is treated as a variable of type cxxtools::QueryParams and a copy is passed to the component. Other parameters get added to this copy. Wanna pass all the parameters of the current component? Just put the variable qparam as a plain word in the argument list. ez 💖

</component> — the closing tag for a component call. When components are called, this closing tag might occur later. The code in the <%close> block gets placed here.
<{...}> — C++ inline processing block. The code in this block is copied into the C++ class unchanged. and listen: a linefeed after the closing tag is not ignored. noted. 💀
<#...#> — comment block. Everything in this block is ignored. nothing to see here, moving on 🫶
<%application [ scope="component|page|shared|global" ] >...</%application> — variables defined here have the lifetime of the application. Application scope is automatically locked. 🔒
<%args>...</%args> — defines the GET or POST parameters received by the component. Each argument has a name and optionally a default value. The default value is delimited from the name by =. A single argument definition is followed by a semicolon (;). In the component, a variable with the same name, of type std::string, is defined, and it receives the value. slay. An argument name can be prefixed by a type definition. The ecpp compiler generates code that tries to convert the value with the cxxtools deserialization operator. If the argument can't be converted, the default value is set. no crash, just vibes 🦋 Argument names can be postfixed by empty square brackets. This defines a std::vector with the specified type — or std::string if no type is specified. This way, multiple values with the same name can be received. If a type is specified, each value gets converted to the target type. 💅
<%attr>...</%attr> — components may define attributes, which can be queried from other components. These values are strings and are defined by specifying a name followed by = and the string value. No type is allowed here. periodt. Another component can fetch a reference to the component using fetchComp(name). fetchComp is a member of the base class tnt::EcppComponent of components built with ecpp. The component then has a member method getAttribute(name), which returns the attribute, or an empty string when it's not found. A different default string can be passed as the second parameter to getAttribute.

Example: A content component specifies a title:

<%attr>
title = "my title";
</%attr>

A component webmain wants to add a title depending on a content component:

<head>
  <title>
    <$ fetchComp("theContent").getAttribute("title", "default title") $>
  </title>
  ...

To separate the C++ code from the html, the actual doing can be moved to a C++ section. The component can then also be called later to generate the content:

<%cpp>
  tnt::Component theContent = fetchComp("theContent");
  std::string title = theContent.getAttribute("title", "default title");
</%cpp>
<head>
  <title><$ title $></title>
  ...
  <div id="contnent">
    <{ theContent(request, reply, qparam); }>
  </div>

<%close>...</%close> — code in these tags is placed into the calling component when a closing tag </component> is found. The <%close> receives the same parameters as the corresponding normal component call.

⚠️ bestie this tag is deprecated and should not be used any more. we're not doing that. 🚫

<%config>...</%config> — web applications often need some configuration, like database names or login information for the database. These configuration variables can be read from the tntnet.xml. Variable names that end with a semicolon are defined as static std::string variables and filled from tntnet.xml. A variable can be prepended by a type — the value from tntnet.xml is then converted with a std::istream. You can also specify a default value by appending a = and the value to the variable. cute AND practical.

Example:

<%config>
  dburl = "sqlite:db=mydbfile.sqlite";
  int maxvalue = 10;
</%config>

tntnet.xml:

<dburl>postgresql:dbname=mydb</dburl>

<%cpp>...</%cpp> — C++ processing block. The code between these tags is copied into the C++ class unchanged. A linefeed after the closing tag is ignored. (again — noted. 🤝)
<%def name>...</%def> — defines an internal sub component with the name name, which can be called like other components. main character energy for a lil sub component ✨
<%doc>...</%doc> — comment block. Everything in this block is ignored. A linefeed after the closing tag is ignored.
<%get>...</%get> — works like a <%args> block, but it receives only GET parameters.
<%include>filename</%include> — the specified file is read and compiled. 📥
<%param>...</%param> — defines parameters received from calling components. In contrast to query parameters, these variables can be of any type. The syntax (and the underlying technology) is the same as in scoped variables — see the description about scoped variables to see how to define parameters. The main difference is that a parameter variable has no scope, since the parameter is always local to the component. iykyk 🧚
<%out> expr </%out> — same as <$$ ... $>. Prints the contained C++ expression expr.
<%post>...</%post> — works like a <%args> block, but it receives only POST parameters.
<%pre>...</%pre> — defines C++ code that is placed outside the C++ class and outside the namespace definition. This is a good place to define #include directives. 🎀
<%request [ scope="component|page|shared|global" ] >...</%request> — define request scope variables. Variables defined here have the lifetime of the request.
<%session [ scope="component|page|shared|global" ] >...</%session> — variables defined here have the lifetime of the session. Sessions are identified with cookies. If a <%session> block is defined somewhere in a component, a session cookie is sent to the client. 🍪 Sessions are automatically locked. 🔐
<%securesession [ scope="component|page|shared|global" ] >...</%securesession> — secure session is just like session, but a secure cookie is used to identify the session. Secure cookies are transferred only over a ssl connection from the browser, and hence the variables are only kept in a ssl secured application. If a variable defined here is used in a non ssl page, the variable values are lost after the current request. 😭 tragic but that's the rule.
<%sout> expr </%sout> — same as <$ ... $>. Prints the contained C++ expression expr. The characters <, >, ,, " and ', which have special meanings in html, are translated to the corresponding html entities. guarding the html, respectfully 💅
<%thread [ scope="component|page|shared|global" ] >...</%thread> — variables defined here have the lifetime of the thread. Each thread has its own instance of these variables. Thread scope variables do not need to be locked at all, because they are only valid in the current thread. no lock needed, she's local 💜

✨ SCOPED VARIABLES ✨

okay bestie, scoped variables are c++ variables whose lifetime is handled by tntnet. They have a lifetime and a scope. The lifetime is defined by the tag used to declare the variable, and the scope is passed as a parameter to the tag. iykyk.

There are 5 different lifetimes for scoped variables:

request — the variable is valid in the current request. The tag is <%request>.
application — the variable is valid in the application. The tag is <%application>. The application is specified by the shared library of the top level component.
session — the variable is valid for the current session. The tag is <%session>. If at least one session variable is declared in the current request, a session cookie is sent to the client.
thread — the variable is valid in the current thread. The tag is <%thread>.
param — the variable receives parameters. The tag is <%param>.

And 3 scopes:

component — the variable is only valid in the same component. This is the default scope.
page — the variable is shared between the components in a single ecpp file. You can specify multiple internal sub components in a <%def> block. Variables defined in page scope are shared between these sub components.
global or shared — variables are shared between all components. If you define the same variable with shared scope in different components, they must have the same type. This is achieved most easily by defining them in a separate file and including them with a <%include> block. The global and shared are just synonyms.

Variables are automatically locked as needed. If you use session variables, tntnet ensures that all requests of the same session are serialized. If you use application variables, tntnet serializes all requests to the same application scope. Request and thread scope variables do not need to be locked at all, because they are not shared between threads.

Syntax of scoped variables 🧚

Scoped variables are declared with exactly the same syntax as normal variables in c++ code. They can be of any type and are instantiated when needed. Objects which do not have default constructors need to be specified with proper constructor parameters in brackets or separated by '='. The parameters are only used if the variable need to be instantiated. This means that parameters to e.g. application scope variables are only used once. When the same component is called later in the same or another request, the parameters are not used any more.

Examples 💖

Specify an application-specific shared variable, which is initialized with 0:

<%application>
unsigned count = 0;
</%application>

Specify a variable with a user defined type, which holds the state of the session:

<%session>
MyClass sessionState;
</%session>

Specify a persistent database connection, which is initialized when first needed and hold for the lifetime of the current thread. This variable may be used in other components:

<%thread scope="shared">
tntdb::Connection conn(dburl);
</%thread>

AUTHOR 👑

This manual page was written by Tommi Mäkitalo ⟨tommi@tntnet.org⟩.