chpp

Tutorial and Reference

last updated 13 January 1998 for version 0.2

Table of Contents

• Introduction
  • What chpp stands for
  • Uses for chpp
  • What chpp should not be used for
  • Planned but not yet Implemented Features
  • Obtaining chpp
  • The History of chpp
  • Problems and Known Bugs
  • Reporting Bugs
  • Licence and Warranty
  • The Authors
  • Acknowledgements
• A Guided Tour through chpp
• Invoking chpp
• Examples
  • Song Lyrics
  • Web Site
  • Tautogen
• Language Reference
  • Commands
    • Command Reference
  • The Meta-Char
  • Data Types
    • Scalars
    • Lists
    • Hashes
    • Macros
  • Variables
    • Accessing Variables
    • List and Hash Subscription
    • Macro Invocation
    • Subscribing Non-Variables
    • Assignment
    • Scoping Rules
  • Arithmetic Expansion
  • Quotation
  • Explicit Evaluation
• Macro Reference
  • Flow Control
  • List Operations
  • Hash Operations
  • File Operations
  • String Operations
  • Miscellaneous
  • Symbol Table Manipulation
• Internal Variables
• Package Reference
  • `files.chh'
  • `strings.chh'
• Macro Index
• Concept Index

Introduction

chpp is a preprocessor. Therefore, its main purpose is to modify input text by including other input files and by macro expansion. Programs performing these tasks already exist, among them the popular C Preprocessor (cpp) and m4, which have proven to be convenient and valuable tools suitable for a variety of tasks. The motivation for chpp is thus questionable.

What distinguishes chpp from at least the two programs mentioned above are mainly two features:

• chpp is non-intrusive. This means that you can take your favourite text and it is very unlikely that it will be changed when piped through chpp. Due to this feature it is pretty easy to start using chpp since you can just start writing your text and need not concern yourself with chpp sitting in the background changing it for no obvious reason.
• chpp is not just a package for performing simple macro expansion, but can indeed be considered a full-fledged programming language. Most importantly, it provides support for complex data structures, namely lists and hashes (associative arrays), which can be nested arbitrarily.

chpp consists of two parts which could, in some sense, be seen as two separate passes over the input file. This is not entirely true, though, since the two parts are intertwined and cannot be separated. The first part, which performs command processing, is similar to what cpp does. It allows the inclusion of other files, simple macro definitions and conditional inclusion and exclusion of parts of the input. The second part does macro processing and is the actual workhorse and core of chpp.

Although macro processing on its own could do anything that can be accomplished with commands, the latter are not only easier to use but also easier to read and therefore improve clarity.

What chpp stands for

chpp does not stand for Chakotay Preprocessor.

Uses for chpp

chpp can be used very well as

• a preprocessor for HTML (see section Web Site). This was, by the way, our original motivation for chpp (see section The History of chpp).
• a CGI scripting language. chpp will become even more attractive for this kind of application when the planned database interface (see section Planned but not yet Implemented Features) is available.
• a generator of Quake(tm) configuration files.
• a producer of funny sentences (see section Tautogen).
• and a lot more...

What chpp should not be used for

chpp should, due to its nature, not be used for

• interactive applications.
• applications where text output is only a secondary function.
• applications which require speed. Unfortunately, chpp is not a fast program. However, this may change in the future (see section Planned but not yet Implemented Features).

Planned but not yet Implemented Features

We are planning to change chpp's dynamic scoping to a lexical scoping scheme. Furthermore, we want to introduce references (i.e. pointers) to the language, which also implies the need for garbage collection. These two features would not only make chpp a cleaner language but should also open the possibility of making the chpp interpreter a lot faster.

We would also like to add a few extension packages to chpp, which will make it more suitable for and easier to apply to various applications, most notably CGI scripting, HTML generation and database interfacing.

Obtaining chpp

chpp is available for free download on the world-wide-web. Point your web-browser at @url{http://chakotay.ml.org/} (or @url{http://chakotay.ml.org/chpp/} if you are using an ancient browser). From there you can download the latest version of chpp.

The History of chpp

Not much here, yet.

Problems and Known Bugs

chpp is far from error-free in its current version. It works quite reliably now when not stressed too far, though. The biggest problem is currently that chpp's error handling is insufficient. chpp does not report some errors, while others cause it to crash or to end up in an endless loop. We do of course plan to change this in the future.

Reporting Bugs

Before you tell us about a bug, please check that you are using the latest version of chpp (see section Obtaining chpp). If this is not the case, please upgrade and try again.

Please do not report bugs that concern chpp's error handling. We know that it is unreliable and buggy and will change that. You should, however, report any incident where chpp does anything wrong with a script which you believe is correct. In such a case, please write us an email containing the script that causes chpp to fail and any additional files that your script needs. Better yet, try to narrow the bug down to the smallest script possible. Do also include information on the configuration you ran chpp on, especially if the bug only happens to show up with this configuration. The email address you should send your bug-report to is @email{chpp@unix.cslab.tuwien.ac.at}.

Licence and Warranty

chpp is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

chpp is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with chpp; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

The Authors

chpp was designed and implemented by Heinz Deinhart and Mark Probst. Check out the chpp homepage (see section Obtaining chpp) for more information.

Acknowledgements

Our thanks go to Tatjana Svizensky for proofreading this manual and to Herbert P@"otzl for donating the hash-table functions, which we were too lazy, erm, too busy to implement, and for not reading the examples chapter of this document.

A Guided Tour through chpp

Invoking chpp

To get a quick overview of chpp command line syntax, just type

chpp --help

The general chpp syntax is

chpp [option ...] [filename ...]

chpp reads and processes all specified files in sequential order, as if they were one file. If no file is specified, chpp reads from standard input. Output is written to standard output if not otherwise specified.

The following is a summary and description of all available chpp options:

--version

Prints out the version number of the invoked chpp.

--help

Prints out a summary of chpp command line syntax.

--output filename

-o filename

Specifies that output should be written to file filename.

--include-dir dir

-I dir

Adds dir to the list of standard include directories.

-D name=value

Defines the chpp variable name with the value value.

--generate-dependencies

-M

Generates a dependency list suitable for make like cpp.

Examples

This chapter gives a few more practical examples of the use of chpp, illustrating a few of its many possible applications.

Song Lyrics

Let us assume you have gathered a collection of song lyrics by various performers as text files. You wish to generate not only HTML files for all the songs but also an index page for each performer which contains, sorted by album, hyperlinks to all the song HTML files.

The song files you have collected all look like this:

Gloria

I try to sing this song.
I try to stand up.
But I can't find my feet.
I try, I try to speak up.
But only in you I'm complete.
...

Furthermore, assume you have created a directory for each performer containing a directory for each album where the song files reside. The names of the directories not necessarily match the corresponding performer's name or the album's, as these often contain spaces, which are uncommon in file names. The same applies to the song file names. Thus, our first task is to somehow associate the names of the performers, albums and songs with the song files. We have a bonus for the song names since these are included in the song files themselves (in the first line). For simplicity we will include this information in the files themselves, namely as HTML comments containing assignments in chpp syntax. To modify the files, we will use the following chpp script:

#include files.chh
%<file=%fopen(%SONGFILENAME)>\
%<songname=%removews(%fgets(%file))>\
<!-- %%<song=%songname>%%<album=%ALBUM>%%<perf=%PERF> -->
%frest(%file)\
%fclose(%file)\

The variables SONGFILENAME, ALBUM and PERF must be set via the command-line. We can now convert all files in one album with the following shell-command (assuming we are in the correct directory and that all song files have the extension `.txt'):

$ pwd
/home/schani/lyrics/u2/october
$ for fn in *.txt ; do
>   chpp -DSONGFILENAME=$fn -DALBUM='October' \
>        -DPERF='U2' ../../convert.ch >../$fn
> done

Note that we have generated the modified files in the performer's directory. After we have done this for all albums, we can delete the album directories. The song files now look like this:

<!-- %<song=Gloria>%<album=October>%<perf=U2> -->

I try to sing this song.
I try to stand up.
But I can't find my feet.
I try, I try to speak up.
But only in you I'm complete.
...

We will now generate HTML files for the songs. For simplicity, we will generate a simple HTML file which contains the song text in a <pre> block:

#include files.chh
%<file=%fopen(%SONGFILENAME)>%void(%{%fgets(%file)})\
\
<html> <head>
<title>%song - %album - %perf</title>
</head> <body>
<h1>%song</h1>
<pre>
%frest(%file)\
</pre>
</body>
</html>
%fclose(file)\

Since the information about the song title, album and performer is coded as chpp code in the first line, we can obtain it by just evaluating it and ignoring its result. With this script we can now generate HTML files for all songs of one performer with the following bash command:

$ pwd
/home/schani/lyrics/u2
$ for fn in *.txt ; do
>   chpp -DSONGFILENAME=$fn ../template.ch >${fn%.txt}.html
> done

Finally, we need to generate an index file for each performer containing hyperlinks to all songs. This file is generated by the following chpp script:

#include files.chh
%<albums=%hash()>\
%<file=%fpipe(/bin/sh,-c,ls *.txt)>\
%foreach(songfilename,%split(%removews(%frest(file)),%"[ \n]+"),
    %<songfile=%fopen(%songfilename)>\
    %void(%{%fgets(%songfile)})\
    %fclose(%songfile)\
    %<htmlfile=%void(%match(%"(.*)\\.",%songfilename))%1.html>\
    %ifdefkey(%albums,%album,
        %<albums{%album}{%song}=%htmlfile>
    ,
        %<albums{%album}=%hash(%song,%htmlfile)>
    )\
)\
%fclose(file)\
\
<html>
<head>
<title>%perf</title>
</head>
<body>
<h1>%perf</h1>
%foreach(album,%sort(%keys(%albums)),\
    <h2>%album</h2>%"\n"<blockquote>%"\n"\
    %foreach(song,%sort(%keys(%albums{%album})),\
        <p><a href="%albums{%album}{%song}">%song</a>%"\n"\
    )\
    </blockquote>%"\n"\
)\
</body>
</html>

The first part of the file gets all information about the songs in the current directory. It generates an entry in the hash %albums for each album, which in turn is a hash containing all names of the HTML files indexed by the song names. The second part just iterates through this table, producing an <h2> for each album and an anchor for each song within.

Web Site

Suppose you were to create a web-site with three main pages: News, Tips and Tricks. Each of these pages should have a layout similar to this:

  N   N EEEE W     W  SSS         News
  NN  N E    W     W S
  N N N EEE   W W W   SSS         _Tips_
  N  NN E     W W W      S
  N   N EEEE   W W    SSS         _Tricks_

--------------------------------------------

This is good news!

--------------------------------------------

         News | _Tips_ | _Tricks_

The header consists of a big graphic banner denoting the title of this particular page. On the right side of the banner are three little graphics, each standing for one of the pages. Two of them lead to the other two pages, whereas the one for the actual page is not functional and grayed out.

The footer consists of a textual link bar with two active links and one 'inactive link' (normal text) for the actual page.

Although these three pages are easy to implement with conventional methods, this becomes increasingly difficult when there are more pages or even hierarchical structures of pages. We will thus use this as an example of how to easily create HTML pages with chpp, leaving more sophisticated designs to the gentle reader.

Ideally, we would like, say, the news source file (which we name `news.csml'), as rendered above, to look like this:

#include header.chml

This is good news!

#include footer.chml

This way, we need not be concerned with the design of the header and footer when we work on the pages and we can easily modify the header and footer in one central place, although they apply to our whole web-site.

Now we need a place where we can enter all the names of the main pages of our web-site and associate them with their corresponding files. We call this file `menu.chml':

%addmenuentry(News,news.csml)
%addmenuentry(Tips,tips.csml)
%addmenuentry(Tricks,tricks.csml)

We simply assume that the generated HTML files will have the same base-name as the sources but the extension `.html'. We furthermore assume that for each main-page we have three additional graphics available, namely one containing the large banner and two containing the small icons, where one of the two is grayed out. These images have the format JPEG, hence the extension `.jpg'. Their base-names consist of the base-names of their main-pages followed by one of the suffixes `_l', `_s' and `_s_g', where `l' denotes large, `s' small and `g' gray.

The include-file `header.chml' fulfills two purposes: Firstly, it must process the information of the file `menu.chml' and secondly, it must generate the header of the HTML file. Since the latter depends on the former, we will focus our attention on processing the information of `menu.chml'. Each main page will be represented by a hash containing the keys filename, name, htmlfilename, imglarge, imgsmall and imgsmallgray, the meanings of which should be obvious. We will collect all these hashes in a list named menu, which will contain these hashes in the order in which they were entered in `menu.chml'. Since `menu.chml' is already in chpp syntax, all we need to do is to define a macro addmenuentry which creates such a hash and appends it to the list menu:

%<menu=%list()>\
%define(addmenuentry,name,filename,
    %<basename=%void(%match(%"(.*)\\.csml$",%filename))%1>\
    %<menu=%append(%menu,
        %hash(filename,%filename,
              name,%name,
              htmlfilename,%basename.html,
              imglarge,%<basename>_l.jpg,
              imgsmall,%<basename>_s.jpg,
              imgsmallgray,%<basename>_s_g.jpg))>
)\

Now we can include `menu.chml' for its side-effects:

%void(
#include menu.chml
)\

Finally, for convenience, we define a variable thisentry which contains the hash that applies to the currently processed page:

%<thisentry=%foreach(menuentry,%menu,
    %if(%streq(%menuentry{filename},%mainfilename),%menuentry))>\

Now we are set and can generate the header of the HTML file:

<html>
<head>
<title>%thisentry{name}</title>
</head>
<body>
<table>
<td>
<img src="%thisentry{imglarge}" alt="%thisentry{name}">
<td>
#include choicestrip.chml
</table>
<hr>

The file `choicestrip.chml' generates a vertical table consisting of the small images for the main-pages with links. It is quite simple:

<table border=0 cellspacing=0 cellpadding=0>
%foreach(menuentry,%menu,
    <tr><td>\
    %if(%streq(%menuentry{filename},%thisentry{filename}),
        <img src="%menuentry{imgsmallgray}" alt="%menuentry{name}">
    ,
        <a href="%menuentry{htmlfilename}">\
        <img border=0 src="%menuentry{imgsmall}" alt="%menuentry{name}">\
        </a>
    )
)
</table>

The footer is even more simple: It contains a horizontal rule and a choice-bar:

<hr>
#include choicebar.chml
</body>
</html>

`choicebar.chml' is similar to `choicestrip.chml':

<h5><center>
%<barentries=%list()>\
%foreach(menuentry,%menu,
    %<barentries=%append(%barentries,
        %if(%streq(%menuentry{filename},%thisentry{filename}),
            %menuentry{name}
        ,
            <a href="%menuentry{htmlfilename}">%menuentry{name}</a>
        )
    )>
)\
%join(%" | ",%barentries)
</center></h5>

All we need now is a comfortable way to create all HTML files from the sources. This is what makefiles are for. They have the additional advantage that files are regenerated only when needed, i.e. when of the files that the file to be created depends on has changed. A makefile for gnumake suitable for our simple purposes would look like this:

CHFILES=header.chml footer.chml choicebar.chml choicestrip.chml

all : news.html tips.html tricks.html

%.html : %.csml
	../../macros -o $ $<

news.html tricks.html tips.html : $(CHFILES)

clean :
	rm -f news.html tips.html tricks.html

Tautogen

Suppose we have a simple context-sensitive grammar, which we want to use to generate sentences, which is quite the opposite of parsing sentences of that grammar. To illustrate this more clearly, let us assume we have file like this:

--sentence
$subject $verb $object.
$subject, while $gerund $object, $verb $object.
$subject watches $object $gerund $object.

--subject
$person
The $adjective $person

--object
$person

--person
Butthead
Mrs Krabappel
Charlie Brown
Mrs Robinson

--adjective
observant
naive
embarassed

--verb
kisses
kicks
envies

--gerund
holding
zapping
hugging
smashing

The file is separated into several categories containing so-called productions for so-called non-terminals. The first non-terminal is called the start non-terminal, which is, in out case, sentence. We start by picking by random one of the right-hand-sides of the productions of the start non-terminal (i.e. one of the lines following the introduction of sentence). Now we repeat the following cycle until our string contains no more placeholders (words prefixed by the dollar sign ($)): Replace the first placeholder by the right-hand-side of a randomly picked production for that placeholder.

The process could evolve like this:

$sentence
$subject, while $gerund $object, $verb $object.
The $adjective $person, while $gerund $object, $verb $object.
The naive $person, while $gerund $object, $verb $object.
The naive Charlie Brown, while $gerund $object, $verb $object.
The naive Charlie Brown, while hugging $object, $verb $object.
The naive Charlie Brown, while hugging $person, $verb $object.
The naive Charlie Brown, while hugging Mrs Robinson, $verb $object.
The naive Charlie Brown, while hugging Mrs Robinson, kicks $object.
The naive Charlie Brown, while hugging Mrs Robinson, kicks $person.
The naive Charlie Brown, while hugging Mrs Robinson, kicks Butthead.

It is easy to see that this simple algorithm even allows for recursive grammars.

This example is not a typical application for a pre-processor. It should rather demonstrate that chpp can be used very succesfully for tackling problems not in its direct field of application, i.e. that it is suitable for more general problems.

You may have noticed that our grammar file is not in chpp syntax, so we have the choice of either converting it or parsing it at run-time. Since the former has the disadvantage of being more complicated in usage (the grammar would have to be converted each time it is changed) and is not easier to implement than the letter, the choice is obvious.

The first step of our application is reading in the grammar file, which we call `grammar'. Its content will be stored in a hash data, where the keys are the names of the non-terminals and the values are the lists of the right-hand-sides of the corresponding productions.

%<file=%fopen(grammar)>\
%<current=runaway>\
%<data=%hash(runaway,%list())>\
%until(%feof(%file),
    %<line=%removews(%fgets(%file))>\
    %if(%[%match(%"^--([a-zA-Z0-9_]+)",%line)!=-1],
        %<current=%1>\
        %<data{%current}=%list()>\
        %ifdef(start,,%<start=%current>)
    ,
        %if(%line,%<data{%current}[%listlength(%data{%current})]=%line>)
    )
)\
%fclose(%file)\

We then proceed to define some variables and macros. First, if the variable n, which will denote the number of sentences generated, is not defined (it could be defined on the command-line), it is set to 10:

%ifdef(n,,%<n=10>)\

The macro some, when called with the name of a non-terminal, returns the right-hand-side of a random production for that non-terminal:

%define(some,nt,%data{%nt}[%random(%listlength(%data{%nt}))])\

The generation of the sentences is now a fairly trivial task:

%for(i,1,%n,
    %<current=%some(%start)>\
    %while(%<mp=%match(%"\\$([a-zA-Z0-9_]+)",%current)>%[mp!=-1],
        %<current=%replacesubstring(%current,%mp,%strlength(%0),%some(%1))>
    )\
    %current%"\n\n"
)\

Language Reference

Files processed with chpp are passed through two stages, which are, however, not sequential in nature but can rather be viewed as coroutines. The first stage processes commands (see section Commands). Command processing is a sequential process, i.e. no loops or recursions occur. The second stage is macro processing (see section The Meta-Char) and allows for loops as well as for recursion.

Commands

Command processing is line-oriented. It affects only lines which have, as their first non-whitespace character, the command-char (#). All other lines are passed through literally. Another function of command processing is the concatenation of lines: If the last character of a line is the backslash (\), then the backslash, the following newline and all leading whitespace of the next line are ignored.

A line invoking a command consists of optional whitespace at the beginning, the command-char #, optional whitespace, the command name, whitespace and the command arguments (if any). Thus, the following lines are all commands (given that the command names exist):

#abc
    #def arg
 #  ghi too many arguments

while the following lines are not:

this is a line without commands.
although this line contains a # it is not a command.

Command Reference

Command: include filename

Command: define name[(argname[,argname...])] value

Command: edefine name

Command: if condition

Command: ifdefined symbol

Command: ifdef symbol

Command: ifnotdefined symbol

Command: ifndef symbol

Command: error message

Command: discard

Command: disc

The Meta-Char

The second stage processes everything that is passed through by the first stage. It is called macro processing because its main use is the expansion of macros. There is just one special character for this stage, namely the meta-char (%). Only character sequences beginning with the meta-char are modified by the macro processing stage. All other characters are simply passed through. Since chpp was designed to be non-intrusive, even uses of the meta-char which do not correspond to the uses described in this chapter are copied verbatim. For example:

Temerature today is 10% above normal.
=> Temperature today is 10% above normal.

In cases where it is absolutely necessary that the meta-char not be interpreted as special, it can be quoted with itself (i.e. %%), yielding one meta-char. Example:

%<heinz=deinz>\
%%heinz evals to %heinz.
=> %heinz evals to deinz.

Data Types

The only primitive type in chpp is the string. Values of that type are referred to as scalars (see section Scalars). Values of any type can be combined arbitrarily to lists (see section Lists) and hashes (see section Hashes). Macros (see section Macros) also form a data type as they can be stored and used, even though they cannot be directly manipulated.

Scalars

Scalars are strings of arbitrary length (including the length 0).

Lists

Lists are ordered collections of arbitrary values indexed by consecutive numbers starting at 0. It follows that lists cannot have holes.

Hashes

Hashes are ordered collections of arbitrary values indexed by arbitrary scalars, i.e. they establish a so-called key/value mapping.

Macros

Macros are what most programming languages call functions. A macro in chpp is a body of text which can be parameterized by formal arguments which are implicitly assigned the values of the actual arguments in a local scope upon invocation. Thus, having defined a macro

%define(hello,name,Gruess Dich Gott %name!)

calling the macro with the argument Heinz

%hello(Heinz)

is semantically equivalent to

%locals(name,%<name=Heinz>Gruess Dich Gott %name!)

Variables

In order to be able to retain values for subsequent use it is necessary to store them in variables.

Accessing Variables

There are two different syntactic forms of variable access, called the short and the long form.

The short form consists of the meta-char followed by the variable name, e.g. %name. The variable name is taken as-is, i.e. is not evaluated. The variable name ends with the first char that is not a letter, a digit or the underscore (_). If a variable with the given name does not exist, the whole string is not interpreted as a variable access and is copied verbatim, i.e. %name evaluates to %name if there is no variable with the name name.

The long form consists of the meta-char followed by the variable name within angle brackets, e.g. %<name>. The variable name is evaluated before the variable is looked up, making it possible, for example, to use variable names containing right angle brackets: The term %<%">>>"> accesses the variable >>>. If a variable with the name does not exists, an error message is issued.

List and Hash Subscription

If the variable is a list or a hash, it can be subscribed by appending the index in brackets or curly braces to the name, in both the short and the long form. In order to access nested data structures, any number of such indexes can be used in one access, for example %name[3]{foo}.

Macro Invocation

A macro can be invoked by appending, in the short or long form of variable access, to the variable name or subscript a left parenthesis followed by the actual arguments separated by commas followed by a right parenthesis, e.g. %list(a,b). The value that is yielded by the macro invocation cannot be subscribed further, i.e. %list(a,b)[1] is not allowed. However, see section Subscribing Non-Variables.

Arguments of a macro-call are processed as follows: First, all leading and trailing whitespace from all arguments is removed. Then, the remaining strings are evaluated and the results are passed by-value as arguments to the macro. In order to pass an argument with leading or trailing whitespace to a macro, it must be quoted. For example:

%define(foobar,arg,"%arg")

%foobar(  xyz  )
=> "xyz"
%foobar(    )
=> ""
%foobar(  %"  "  )
=> "  "
%foobar(%"  xyz  ")
=> "  xyz  "

Subscribing Non-Variables

It is possible to subscribe values that are not variables, for example ones that are returned from macros, by using a modified long form of variable access. Instead of the variable name the expression yielding the value enclosed in parentheses is used. Upon evaluation, the expression is evaluated and all following subscriptions are applied to it. Example:

%<(%list(a,b))[1]>
=> b

Assignment

Assignment syntax is an enhancement of the long form of variable access. The last subscription (or the variable name, if no subscription is used) is followed by an equal sign (=) which is followed by an expression yielding the value to be assigned.

When assigning is attempted to an element of a list which is out of bounds, the list is enlarged. Elements between the formerly last element and the newly added element default to the empty string. Indexes less then 0 are not allowed.

Assigning to a key in a hash which is not part of it, adds the key/value pair to the hash.

It is not possible to assign to a subscript of a value which is not subscribable, i.e. it is not possible to do %<bar[3]=foo> if bar is not a list. To make bar an empty list, simply do %<bar=%list()>.

Assignment always copies the assigned value. In other words, there are no references or pointers. However, see section Planned but not yet Implemented Features.

Scoping Rules

chpp uses dynamic scoping (see, however, section Planned but not yet Implemented Features). This means that a variable is visible from the time its declaration is executed until the time its scope level ceases to exist. This also means that the scope of a variable is not immediately evident from the source of the program.

A new scope level is created when a macro is called and when the macro locals is executed. A macro call introduces a new scope level which contains all arguments to the macro, while local creates a new scope level with arbitrary variable names, which are initialized to be the empty string. The scope which is the one last created is called the innermost scope, while the outermost scope, which is always available, is referred to as the global scope.

Upon variable access all scopes starting with the innermost scope are tested for containing a variable with that name and, if one is found, that variable is used. If no scope containing a variable with that name is found, an error message is produced.

When a value is assigned to a variable, each scope, string with the innermost scope is searched for a variable bearing that name and, if one is found, the value is assigned to the variable in that scope. If the variable is not contained in any scope, a new variable is created in the global scope.

Arithmetic Expansion

chpp permits the evaluation of arithmetic expressions by enclosing the expression in square brackets ([]) preceded by the meta-char. The expression is first evaluated according to chpp rules and the resulting value is treated as an arithmetic expression which, in turn, yields a number. Whitespace between operators and operands is ignored. The following table is a summary of all available operators together with their arity. They are sorted by precedence, the first line being of the highest precedence. All binary operators evaluate from left to right. All operators have the same meaning as the corresponding operators in the C language.

@multitable @columnfractions .2 .8

%[1+2]
=> 3
%[1.5+3.3]
=> 4.800000
%[3==3]
=> 1
%[3!=3]
=> 0
%[(1+2)*(3+4)]
=> 21
%<x=4>%[%x+1]
=> 5
%<x=4>%[x+1]
=> 5

%<a=abc>%<b=%%a>%{%b}
=> abc