ClearSilver++: A C++ Interface to ClearSilver
- Author:
- Brook Milligan, Department of Biology, New Mexico State University, Las Cruces, New Mexico 88003, USA, <brook@nmsu.edu>
- Date:
- 2006/05/16 20:20:20
- Version:
- 0.2
ClearSilver is a fast, powerful, and language-neutral HTML template system. In both static content sites and dynamic HTML applications, it provides a separation between presentation code and application logic which makes working with your project easier. The current implementation of ClearSilver is written in the C language with language wrappers for Java, Perl, and Python. This project provides a C++ language interface to ClearSilver.
This package provides a C++ interface to the ClearSilver C API. The design of ClearSilver++ is intended to follow as many of the conventions of the C++ Standard Template Library (STL) as possible. This is especially true for the interface to the Hierarchical Data Format (HDF) datasets used by ClearSilver. Thus, for the HDF class there exists a full range of iterators, as well as a complete associative array interface for accessing and manipulating elements within the dataset. Because HDF datasets are hierarchical, some extensions have been introduced to the standard STL concept of iterators and to the standard notion of an associative array interface. First, the iterators provide access to the virtual container of child nodes descending from the currently addressed node, rather than to the entire HDF dataset as might be expected for iterators across a flat data structure. Second, the reference obtained either by derefencing an iterator or from the associative array interface is itself a complex type of its own right (as opposed to a simple pointer into the dataset). The node references themselves are instances of the HDF class and therefore provide the complete interface, including their own iterator constructors and their own associative array interface, both of which are constrained to refer to the subtree rooted at the referenced node. Consequently, expressions like the following can be used to represent the path to a node nested within the dataset.
HDF hdf;
hdf ["level 1"]["level 2"]["level 3"];
These extensions make little sense for STL containers, which hide any hierarchical aspects as implementation details. For ClearSilver HDF datasets, however, the hierarchical nature is fundamental to their meaning. Consequently, this C++ interface retains the capability of working hierarchically, while building directly on well-known STL concepts.
For all the classes within this collection, the standard set of STL typedefs (e.g., iterators and references) is available. Thus, it should be possible to write generic code for use with this package and appropriate STL or STL-inspired algorithms should work.
Finally, besides the obvious core CGI and HDF classes, a number of related classes are included to improve type safety, to ensure correct resource management, or to guarantee correct interpretation of strings. It is hoped that these will prove useful for improving the correctness of code making use of this library.
Additionally, two application framework classes, CGIApplication and FastCGIApplication are available to simplify and standardize the process of constructing CGI applications based on this library.
Typeset postscript documentation for ClearSilver++ is also available.
In addition to providing a C++ interface to the ClearSilver HTML template library, this project seeks to meet the following design goals.
- Adhere to as many of the design principles and expectations associated with the C++ Standard Template Library (STL) as makes sense in this context. Consequently, many coding idioms and algorithms designed with STL concepts in mind should be transferable to the use of the ClearSilver++ library.
- Assume as little as possible about the internals of the underlying ClearSilver C library used in the implementation. Consequently, the ClearSilver++ library should be reasonably robust to changes in the underlying implementation.
A strict reliance on the C API, while important for stability of ClearSilver++, presents challenges for the design of this library. For example, the C API is written from the perspective of dealing with an HDF dataset as a whole. Thus, node operations are specified with the complete path from the root of the dataset to the node. However, individual nodes do not retain information about the path. Therefore, operations performed through iterators pointing to individual nodes cannot directly access the path information required by the C API implementation. Consequently, the ClearSiver++ library must maintain its own contextual path information separately, which complicates its design. Reorganizing the underlying C library could solve these issues and greatly simplify the design of this library. For example, including parent links in the HDF dataset nodes would allow the path information to be retrieved directly from any node and would not require duplicate storage. Althernatively, a richer interface operating on nodes specified by a pointer rather than a path would simplify this.
The C++ source code for this project is available for download at the following site.
As currently written, this package is intended to be used directly in conjunction with the www/clearsilver-base package installed in its default location (see http://www.pkgsrc.org for details on the packaging system). Consequently, the build environment makes use of the standard BSD make system. The code itself should be fairly portable, as it compiles with no warnings under the strictest conditions using g++ version 3.3.3. In the future, a more portable build system will be constructed to ease the installation burden. Anyone wishing to assist on that portion of the project is welcome to contact me directly. Ideally, at some point this will be incorporated directly into ClearSilver itself, at which point the installation issue will be moot.
Besides creating a new Makefile for your own system, two possible pathways exist for making use of the existing one: install the minimal components of BSD make on your system or make use of the platform-independent Pkgsrc system to manage a broader collection of your packages. BSD make itself may be installed from a standalone collection or using Pkgsrc.
A version of BSD make is available that includes autoconf configuration and is portable to a wide array of systems. The necessary files are available at the following site:
Installation is straightforward and minimally involves the following steps, which are described further in the bmake/README file. Untar both files into a common directory, thereby creating both bmake and mk subdirectories. Within the bmake subdirectory, execute the boot-strap command to build bmake. Upon successful completion, boot-strap will emit the commands needed to install both bmake and the necessary system Makefiles.
Because the Pkgsrc system is designed to support a wide array of distinct operating systems (at the time of this writing, 12 distinct operating systems, 24 distinct binary installation kits, and collections of pre-compiled binary packages for seven distinct platforms), it also provides the BSD make system as a platform-independent package. The two relevant packages are described below.
These packages are included within the binary kits for each platform, as they are required for the Pkgsrc system itself. Simply download the binary kit for your platform, and extract it into, for example, the root directory (/).
# cd /
# gzip -c -d /tmp/bootstrap-pkgsrc-SunOS-5.9-sparc-20031023.tar.gz \
| tar -xpf -
At that point you should have a usable copy of BSD make in /usr/pkg/bin/bmake and the relevant system Makefiles in /usr/pkg/share/mk/. Building ClearSilver++ with bmake should be as described below. Of course, as with any binary distributions, you should verify the checksum against the SUM or CKSUM file and inspect the contents before extracting it.
As described below, the code within ClearSilver++ makes use of additional packages. These, of course, need managing, as probably many other components on your system do. Thus, it may be useful to install the Pkgsrc system and use it not just as a convenient means of obtaining BSD make, but as a more general tool for managing your software. The initial step for this is the same as described above: download the appropriate binary kit for your platform, which is available at http://www.pkgsrc.org. The additional steps required either to use pre-existing binary packages or to build packages from source code are described there as well.
Beyond the build system, the C++ code within ClearSilver++ requires additional packages. Obviously, there is a dependency on ClearSilver for the underlying C API. In addition, however, it makes use of the Boost Library for memory management and lexical casts. Finally, if optional FastCGI support is desired, the underlying library must be installed. Within Pkgsrc these are available as the following packages.
Using the provided build system, installation should be straightforward. Only the following steps are required.
# configure
# cd lib && make
# cd lib && make install
--help option. Of particular interest are the following.
--prefix=DIR, --exec_prefix=DIR, --includedir=DIR, --libdir=DIR These options define the install locations for the library following standard autoconf conventions.
--with-localbase=DIR The directory pointed to by LOCALBASE is assumed to contain the standard directories (include and lib), which contain installed versions of the ClearSilver C library, the Boost library, and optionally the FastCGI library.
--with-FastCGI, --without-FastCGI These options control whether to include the FastCGI application framework in the compiled library. Note that the application framework requires that FastCGI be already installed in LOCALBASE.
--enable-broken-hdf-set-attr This option is currently required because the underlying ClearSilver C library does not handle HDF atttributes correctly. Enabling this replaces the broken function with a correct one.
--enable-object-tracing This option includes a TraceObject in several major classes, which enables the tracing of object lifetimes. This is sometimes useful for debugging purposes. By default, this option is disabled and no overhead is added to any classes.
Please report any configuration problems so that this process can be improved.
The following license applies to all files within the ClearSilver++ package.
$Id: LICENSE,v 1.3 2006/03/27 19:17:43 brook Exp $
ClearSilver++ Software License.
Copyright (c) 2005,2006 Brook Milligan <brook@nmsu.edu>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior
written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
To: majordomo@biology.nmsu.edu
Subject: leave blank; this is ignored anyway
subscribe clearsilver++ name@host.com
Generated on Tue May 16 14:50:51 2006 for ClearSilver C++ Library by
1.4.5