CGI Services Architecture
Recent Pages

Environment Variables
Handling Concurrency
Template Processing
RDF Responses
RDF Messaging
URL Rewriting
File Uploads
Sample Authenticated Se ...
HTTP Cookies
Client Authentication

Links

www.strozzi.it on Twitter
CSA Home
Table of Contents

Advertising

Session

User ID
Password



Campaigns

stopsoftwarepatents.eu petition banner

Basic Naming Conventions

The rc shell, on which CSA is based, exports all variables and functions to the program environment, making them global to large portions of code (IMHO this is both an advantage and a nuissance, but I won't get into this discussion here). Because of this, we have the need to establish a precise naming convention for all names, also to make them as self-documenting as possible.

In the CSA name-space, a few name prefixes are either reserved for CSA or they are used internally by the rc shell, by AWK or by other underlying utility programs. The reserved prefixes are:

csa
case-insensitive prefix reserved for CSA use. It SHOULD NOT be used by application programs to identify their own commands, functions and variable names.

fn_csa
where csa is case-insensitive: same as csa.

_
A single underscore prefix is reserved for use by the CSA AWK function and variable names.

fn_
rc function definitions.

In addition to reserved prefixes there are others that, although not strictly reserved, are simply typical, or conventional, and they are:

WWW_
Decoded HTTP GET/POST variables.

XML_
XML-encoded strings (PCDATA), that can be safely included in XML files and templates.

ISO_
Template variables that are to be inserted in HTML response pages and forms. Such variables are derived from their unencoded versions by replacing special characters with their ISO representations (i.e. the newline becomes 
, and so on). CGI response variables SHOULD always be encoded like this, also to prevent the so called cross-site scripting (CSS) vulnerabilities.

URI_
These are similar to ISO_ variables, but the escaping of special characters is done according to RFC 1378 and the resulting values are meant to be inserted in the QUERY_STRING part of Uniform Resource Indicator (URI) strings (i.e. the newline becomes %0A, and so on).

URP_
These are a special version of the URI_ variables, that are meant to be used in the PATH_INFO part of a URI. They are slightly different from their URI_ equivalents, to account for the decoding done by the CGI interface on the PATH_INFO part of a URI.

TNS_
Recommended prefix for what I dubbed "This Name Space" (TNS) variables. These are global application-level variables that application programmers may use for their own Inter-Program Communications (IPC) needs.

For an application name-space not to clash with the CSA one, just make sure that your own CSA applications always use mixed-case function and command names (i.e. someFunction, MyCommand, and that), and either lower- or mixed-case variable names. Never define names that begin with either csa or CSA. In fact, casual all upper-case names (like SOME_NAME) SHOULD be avoided altogether. If nevertheless you need them, you SHOULD prefix them with the string CNS_ (e.g. CNS_MYVAR), if they are to be exported to the environment, or CNS (like CNSMYVAR) otherwise. As already explained, CNS is the prefix that CSA sets aside for use by application programs.

In addition to the naming conventions that we have seen so far, there are others that concern the naming of files on disk. The following few filename extensions are typical in a CSA application:

somefile
A generic data file, usually a TAB-delimited table.

somefile,v
RCS/CVS repository of somefile.

somefile.lock
Advisory lock on somefile.


Trackbacks (0) | New trackback | Print

This Web Site is Copyright © 2007,2008,2009,2010 Carlo Strozzi, Some Rights Reserved
site map | recent changes | disclaimer