☼ Documentation ☼ Download ☼ ppC++ Scripts ☼ Bug tracking

ppC++ Manual

Last updated: October 19, 2003 by SY

Table of Contents:
·1 Preface
·2 Getting started ·2.1 Introduction
·2.2 Installation
·2.3
·3 ppC++ preprocessor syntax ·3.1 Functions, classes and global variables
·3.2 Control Structures
·3.3 HTTP request variables(GET and POST)
·3.4 Cookies
·3.5 #ppcinclude preprocessor directive
·4 Additional keyword list
·5 ppC++ constants list ·ppc.SCRIPT
·ppc.__COUNT__
·6 ppC++ function list ·ppc.header(string)
·ppc.content_type(string)
·ppc.addslashes(string)
·ppc.key(int)
·ppc.value(int)
·ppc.urldecode(string)
·ppc.urlencode(string)
·ppc.double()
·ppc.float()
·ppc.int()
·ppc.string()
·ppc.get(string)
·ppc.post(string)
·ppc.read_file(string)
·ppc.save_fle(string, string)
·cookie.set(string)

·1 Preface

ppC++(acronym for "ppC++ preprocessed C++"), is an HTML-preprocessed C/C++ programming language. This preprocessor lets you write server-side programs in C++ inside your HTML code and brings new additional features which make web programming easier.

ppC++ was developed for those, who need high performance, stability and harmony in simple HTML enviroment. For those, who know C or C++ and have some skills in HTML, doesn't wish to learn new interpreter languages like Perl, PHP or ASP and wants to start creating dynamic web-pages immediately. If you are C/C++ programmer, you would start to develop a full-featured dynamic server pages of full value and ease of HTML tags in a few hours.
The main goal of ppC++ is to bring classic C/C++ adopted in simple and rapid development of dynamic web pages.

This manual was written in HTML, using HTML-Kit and Aditor.

· Home ·

·2 Getting started

·2.1 Introduction

ppC++ lets you use powerfull, stable and fast C++ in simple web scripts and hides a lot of routine cgi programming.
How does it work? Here is an example:

<html>
  <body>
    <;    cout << "Hello from ppC++!";    ;>
  </body>
</html>

As you see, it looks like a regular HTML page, but you can find one line written in C++ between special tags.
Now save this file somwhere in your cgi-bin directory as, for example, "hello.ppc" and run it from ppC++ web compiler or simply type the script's path and name in your browser address line(only in UNIX) - it will create standalone cgi executable binary file "hello.ppc.cgi" in the same directory that outputs to client browser:

<html>
  <body>
     Hello from ppC++!
  </body>
</html>

Now "hello.ppc.cgi" is the independent compiled cgi-programm and doesn't require neither its "ppc" source, nor ppC++ compiler. And you don't have to worry if someone could download your original "hello.ppc" source code - if client will request it, web-server will treat ppc-source as an executable and will return 500 server error.

Remember, ppC++ always adds ".cgi" extentions to corresponding executable file's name.

· Home ·

·2.2 Installation

First you need to install web-server. Apache >2.0 is the only server now that supports ppC++(if somebody could cross it to other servers, please let me know). If you don't know what is web server and how to configure it, download one of easy-to-install distributions of server, like XAMPP(windows/linux).

When you have configured and started your server, go to download page.

· Home ·

·2.3

·3 ppC++ preprocessor syntax

These are the methods of inserting C++ code into HTML pages:

    1). <; cout << "Regular method - C/C++ semicoloned"; ;><br>
    
    2). <;= "The '<;=' is shortcut for '<; cout << '  ";  ;><br>

    
    3). <?= "You can also use PHP"?> <%="or ASP-style tags,"%> 
                <;= "and any kind"%> <%="of their"?> <?="combinations.";><br>
              
    4).Closing ppC++ tag implies the end of the statement, so
        <;=  "this";    ;>
        and <;="this";>
         are equivalent.

· Home ·

·3.1 Functions, classes and global variables

Functions, classes and global variables can be declared anywhere, for example in addittional standard C++ header files, the same or the other ppc scripts, and this constructions will be accessable anywhere in the script.
The simplest way is to write functions or classes in one file:

   This script contains a function: <; function("foo"); ;>
   
   <; void function(string parameter){
        cout << "Hello! I am the function with parameter <b>"
             << parameter << "</b>!"<<endl;
   };>

As it seen from example, the function can be declared after it was called.
OK, the function works, but doesn't it look a little cumbersome in this HTML enviroment? In this case ppC++ lets you write much more grace code:

   This script contains a function: <; function("foo"); ;>
   
   <; void function(string parameter){;>
        Hello! I am the function with parameter 
        <b><;=parameter;> </b>!
   <;};>

The same story about classes/structs:

Here i will create an object: <u><; myClass obj;></u><br>
Calling its functon: <u><; obj.function("bla-bla");></u><br>
<; class myClass{
     public:
     myClass(){;>This is a constructor of object <b><;=this;></b><;}
     ~myClass(){;>object <b><;=this;></b> is dying...<;}
     void function(string p){;>
        This is the function
        from object <b><;=this;></b> 
        and with parameter <b><;=p;></b>
     <;}
};>

To use global variables or class/srtuct objects(those, which must be accessible to functions or classes) you have to define it with special keyword: global (it is sacrifice for main()-function absence):

   <; // global variable:
      global int var = 2003;
   void function(){;>
        Hello, var is <b><;=var;></b>!
   <;};>
   This script contains a Global Variable <b><;=var;></b>.
   
   Lets call the function: <;function();>

The variable must be defined as a global, for example this will not work:

   <; int var = 2003;
   void function(){;>Hello, var is <b><;=var;></b>!<;};>

And of course you can use standard C/C++ library fuctions/classes - simply by including their header files:

   <; #include <math.h> ;>
   cosine of 0.5 is <b><;=cos(0.5);></b><br>
   The number of seconds since January 1, 1970 is 
   <b><;printf("%ld</b>",time(NULL));//and again function called 
                // before its definition.
   #include <time.h>;>

    The common header files as cstdio(stdio.h), 
    cstdlib(stdlib.h) or iostream(iostream.h)
    are always included.

Preprocessor lets you include your own native C/C++ files:

   <; #include "my_header_file.h" ;>
   Hello! The results of my functions  are
   <i><;=my_func1("bla-bla-bla");></i> and
   <i><;=my_func2(12345);></i>!

· Home ·

·3.2 Control Structures

The control structures(like while, for, if-else) are exactly the same as in C/C++, but also could be optimized for HTML. For example to get this result

     ab^c^c^cab^c^c^cO!b^c^c^cab^c^c^cab^c^c^cab^c^c^caO!^c^c^cab^c^c^cab^c^c^cab^c^c^cabO!^c^cab^c^c^cab^c^c^cab^c^c^cab^cO!^cab^c^c^cab^c^c^cab^c^c^cab^c^cO!ab^c^c^c

in your browser window, you can write:

<; 
    for(int i=0; i < 100; ++i){
        if(i%21 == 10){ 
            cout << "<b>O!</b>";
            i++;
        }   
        switch(i%5){
        case 0: cout << "<i>a</i>"; break;
        case 1: cout << "<u>b</u>"; break;
        default: cout << "<sup>c</sup>"; break;
        }
    }
;>

but ppC++ can offer another method for writing more "HTMLable" code:

<; 
    for(int i=0; i < 100; ++i){
        if(i%21 == 10){;> 
            <b>O!</b><;
            i++;
        }   
        switch(i%5){
        case 0: ;><i>a</i><; break;
        case 1: ;><u>b</u><; break;
        default: ;><sup>c</sup><; break;
        }
    }
;>

· Home ·

·3.3 HTTP request variables(GET and POST)

Now we can write dynamic HTML pages, but how to make our pages interactive? To use HTTP request variables, which can be sent to server via "<form>" or URL HTTP request string.
When the following form is submitted

    <form method="post" action="script.ppc.cgi">
        <input type="text" name="var1" value="value1">
        <input type="text" name="var2" value="value2">
        <input type="submit">
    </form>

or "script.ppc.cgi?var1=value1&var2=value2" is requested, ppC++ will create the variables "var1" and "var2" as members of ppc - special pseudo class object, which hides and encapsulates all the cgi routine work:

<;// script.ppc 
;><html><body>
    var1 is <;=ppc.var1;><br>
    var2 is <;=ppc.var2;><br>
<hr>Showing all variables:<br>
    <; for(int i=0; i< ppc.__COUNT__; ++i){;>
        <i><;=i;></i>). <;= ppc.key(i) ;> = <; = ppc.value(i) ;> <br>
    <;};>       
</body></html>

will show:

var1 is value1
var2 is value2

Showing all variables:
0). var1 = value1
1). var2 = value2

If GET and POST variables are used simultaneously in one script - use ppc.get(string variable) and ppc.post(string variable):

<form action="script.ppc.cgi?var1=value" method=POST>
<input name=var1 value=another_value>
</form>

If it is submitted, in script.ppc ppc.get("var1") will return value and ppc.post("var1") will return another_value. In this case ppc.var1 has priority to POST method.

Remember, the type of all the HTTP request variables from "ppc" return "string" type , though it is actually not string object - the string's common functions and properties are not accessible here.

· Home ·

·3.4 Cookies

All the cookie manipulations can be made via "cookie" pseudo-class object. cookie.set("name=value; EXPIRES=date; PATH=path; DOMAIN=domain_name; SECURE") will send the cookie to a browser. Afterwards (in the following pages) you can get the cookie as a variable - member of a "cookie".
The following page sets the cookie "foo" and offers the link to the second page:

<;// page1.ppc
;><html><body>
<;// set cookie here if it is empty:
  if(cookie.foo==""){;>
        Setting cookie<;
        cookie.set("foo=oof");};>
<a href="page2.ppc.cgi">go to second page</a>
</body></html>

"Page2.ppc" shows the cookie value. If it is absent, an empty string will be shown:

<;// page2.ppc
;><html><body>
Cookie <b>foo</b> is <b><;=cookie.foo;></b>!<br>
<a href="page3.ppc.cgi">go to third page</a>
</body></html>

"Page3.ppc" also has an acces to cookie.foo:

<;// page3.ppc
;><html><body>
Even here you can see, that cookie <b>foo</b> 
is <b><;=cookie.foo;></b>!!!<br>
<a href="page1.ppc.cgi">go to the first page</a>
</body></html>

To erease the cookie value, simply write cookie.set("foo=") and client browser will remove this variable.
Remember, the type of all the variables from "cookie" return "string" type , though it is actually not string object - the string's common functions and properties are not accessible here.

· Home ·

·3.5 #ppcinclude preprocessor directive

To include other *.ppc files you have to use the special preprocessor directive - "#ppcinclude" - if you will try to include these files via "#include" - you will get a list of compilation errors. Use native C-"#include" for instant C/C++ files: "*.h/*.c/*.cpp"

<;// main.ppc
;><html>
  Hello from main file! 
  <;int a=15;>
 a is <;=a;>!<br>
<; // as you see, nothing can be written before and after a 
   //directive at the same line - as in a native C++:
#ppcinclude "second_file.ppc" 
;>
</html>

<;//second_file.ppc
;><hr>
Hello from second file!<br>
 I can see variables defined in main file!<br>
 Here it is: a is <;=a;>!

running "main.ppc" will output:

Hello from main file! a is 15!

Hello from second file!
I can see variables defined in main file!
Here it is: a is 15!

But if you will try to compile "second_file.ppc" alone, you get a fatal error: variable "a" undeclared.

Included ppc files also can contain functions, structs and classes in addition to main code, which runs immediately. You can even include the same ppc file more than once without expecting name conflicts:

<;// main2.ppc
;><html><body>
  Hello from main 2 file! 
    <br>Here i will call the function from the <b>with_function.ppc</b> file,
    which will be included after:<br>
    <;function("One-two, one-two...");>
<hr>including "with_function.ppc"...<;
#ppcinclude "with_function.ppc" 
;>hm, let's include it again(will we get conflict with included before?):<?
#ppcinclude "with_function.ppc" 
;></body>
</html>

<;// with_function.ppc
;><fieldset>
Hello! this file contains the function. 
<br><br>
Calling function: <;function("bla-bla");>
<;void function(string word){;>
     <i>I am the function with parameter <b><;=word;></b></i>
<;};>
</fieldset>

Compile and run "main2.ppc" - browser will show:

Hello from main 2 file!
Here i will call the function from the with_function.ppc file, which will be included after:
I am the function with parameter One-two, one-two...

including "with_function.ppc"...

Hello! this file contains the function.

Calling function: I am the function with parameter bla-bla

hm, let's include it again(will we get conflict with included before?):

Hello! this file contains the function.

Calling function: I am the function with parameter bla-bla

· Home ·

·4 Additional keyword list

These words are added to standard C++ keyword list:
· ppc
· cookie
· global

· Home ·

·5 ppC++ constants list

·ppc.SCRIPT

string ppc.SCRIPT

The name of self-ppc script executable binary.

For example if this file called "script.ppc",
<;=ppc.SCRIPT;> will return 
  "script.ppc.cgi"(Windows) or "script.ppc"(UNIX).
Let's check it:<br>
<;if(ppc.SCRIPT == "script.ppc"){;>
    Yes! This file is "<;=ppc.SCRIPT;>"!
<;}else{;>
    No, this file is "<;=ppc.SCRIPT;>", not "script.ppc"...
<;};>

· Home ·

·ppc.COUNT

int ppc.__COUNT__

The quantity of all HTTP request variables.
See the ppc.__COUNT__ example here.

· Home ·

·6 ppC++ function list

·ppc.header(string)

void ppc.header(string val)

sends HTTP header to the browser.
Examples:

ppc.header("Content-type: text/html");
ppc.header("Location: script.ppc");

· Home ·

·ppc.content_type(string)

void ppc.content_type(string val)

sets the content type of the document.
Examples:

ppc.content_type("text/html");
ppc.content_type("image/gif");
ppc.content_type("text/plain");

· Home ·

·ppc.addslashes(string)

string ppc.addslashes(string val)

returns val with doubled back-slashes. For example

ppc.addslashes("it\'s \"ppC++\"!")

will return string

"it\\'s \\"ppC++\\"!"

· Home ·

·ppc.key(int)

const string ppc.key(int val)

Returns a name of HTTP request variable.
val must be more or equal to 0 and less than ppc.__COUNT__.
See the ppc.key example here.

· Home ·

·ppc.value(int)

const string ppc.value(int val)

Returns a value of HTTP request variable.
val must be more or equal to 0 and less than ppc.__COUNT__.
See the ppc.value example here.

· Home ·

·ppc.urldecode(string)

string ppc.urldecode(string val)

Decodes a Uniform Resource Identifier (URI) previously created by ppc.urlencode() or by a similar routine.

· Home ·

·ppc.urlencode(string)

string ppc.urlencode(string val)

Returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits. It is encoded the same way that the posted data from a WWW form is encoded.

    <;
       = ppc.urlencode("x = a * b"); // will print "x%20%3D%20a%20%2A%20b".
       // if I will try to send "x = a * b" through HTTP request string - it may
       // be parsed wrong, because of spaces and non-alphanumeric characters.
       // If i send it encoded, the content will be saved:
    ;><br>
    <a href='<;=ppc.SCRIPT;>?variable=x = a * b' >
        send a variable(unsafe).
    </a><br>
    <a href='<;=ppc.SCRIPT;>?variable=<;=ppc.urlencode("x = a * b");>'>
        send a variable(safe).
    </a><br>
    <;if(ppc.variable != ""){;>
        expression: <;=ppc.variable;>
    <;};>

· Home ·

·ppc.double()

double ppc.double(val)

This function converts val to double type. val can be string, double, float or char*.

· Home ·

·ppc.float()

float ppc.float(val)

Same as ppc.double()

· Home ·

·ppc.int()

int ppc.int(val)

This function converts val to int type. val can be string, double, float or char*.

· Home ·

·ppc.string()

string ppc.string(val)

This function converts val to string type. val can be int, double, float or char*.

· Home ·

·ppc.get(string)

string ppc.get(string variable)

Returns a value of variable if it was sent via GET.
example
available since 0.44 version

· Home ·

·ppc.post(string)

string ppc.post(string variable)

Returns a value of variable if it was sent via POST.
example
available since 0.44 version

· Home ·

·ppc.read_file(string)

string ppc.read_file(string filename)

Opens file filename and returns its content.

· Home ·

·ppc.save_file(string, string)

bool ppc.save_file(string filename, string content)

Saves content to filename. On error returns false, othervise - true;

· Home ·

·cookie.set(string)

void cookie.set(string val)

- this function sends a cookie to a client browser, with parameter val which has the following form:

"name=value; EXPIRES=date; PATH=path; DOMAIN=domain_name; SECURE"

· name - name of cookie.
· value - value of cookie.
· EXPIRES=date - the cookie will live until date. By default cookie dies in the moment of browser closing.
· PATH=path - the path of cookies visibility.
· DOMAIN=domain_name - domain of cookies visibility.
· SECURE - shows if the cookie is sent via secure shell.

The minimal parameter is "name=value".
See the cookie.set() example here.

· Home ·

* string - default type for character string in ppC++ - std::string from <string> C++ library.