Documentation

Table of contents

Intro

WebC is an open source precompiler to write dynamically generated web pages in the C language. WebC works by "embedding" C code into the HTML source. The way this is done is by the source having different modes for each language. The source is either in C mode or HTML mode and you switch between them as needed.

A WebC file starts out in HTML mode. If you do nothing else the WebC precompiler will take the whole file and output it to the web server. You switch to C code using the <?wc tag and back to HTML mode using ?> tag.

For example:

<!DOCTYPE html>
<html>
    <head>
        <title>Hello World</title>
    </head>

    <body>
        <?wc
        /* This is C code */
        wcecho("Hello World");
        ?>
    </body>
</html>

The file starts out in HTML mode so the WebC outputs all the lines to the web server until it finds a <?wc. At that point the WebC precompiler switches to C mode.

Everything between the <?wc ?> tags will be C code. You can put any valid C code in this block. wcecho() is a normal C function that sends a C string to the web server (you must provide this function, see below).

When the WebC precompiler see the ?> it will switch back to HTML mode and send the rest of the file to the web server. You can switch between the modes as many times as you wish.

Because WebC is a precompiler all it will do is convert a WebC file into a C file. You will then need to compile the output file with a standard C compiler.

You can compile the above example with:

webcc example.wc -o example.c

Note:The WebC precompiler can be found in the PreCompiler directory

This will make a example.c file that looks something like:

/*** GENERATED CODE FROM example.wc ***/
#include "WCWebAPI.h"
void Page_example(void)
{
    wcecho("<!DOCTYPE html>\n");
    wcecho("<html>\n");
    wcecho("    <head>\n");
    wcecho("        <title>Hello World</title>\n");
    wcecho("    </head>\n");
    wcecho("\n");
    wcecho("    <body>\n");
        /* This is C code */
        wcecho("Hello World");
    wcecho("    </body>\n"
    wcecho("</html>\n");
}

You can see that the HTML code was converted to a number wcecho() function calls and the C code is copied directly in the middle. Note that the generated code also includes an #include for the "WCWebAPI.h" file.

To compile the resulting file you will also need to provide a few support functions to connect the generated code to the web server. This support code doesn't actually need to send to the web server, you could for example send the output to stdout if you wanted.

The support functions you must provide are wcecho(), wcwrite(), and wcSetMine(). We will only provide a basic wcecho() here, see Support Functions for more information on these support functions.

Here are example support files that includes the needed functions set to output to stdout.

WCWebAPI.c

#include "WCWebAPI.h"
#include <stdio.h>
void wcecho(const char *buff)
{
    printf("%s",buff);
}

void wcwrite(const unsigned char *bin,int Len)
{
}

void wcSetMine(const char *Mime)
{
}

WCWebAPI.h

void wcecho(const char *buff);
void wcwrite(const unsigned char *bin,int Len);
void wcSetMine(const char *Mime);

main.c

void Page_example(void);
int main(void)
{
    /* Call the example page function */
    Page_example();
}

You can now compile using gcc:

gcc main.c example.c WCWebAPI.c

When you run a.out you will get:

<!DOCTYPE html>
<html>
    <head>
        <title>Hello World</title>
    </head>

    <body>
Hello World
    </body>
</html>

Requirements

WebC is a precompiler so you will also need a normal C/C++ compiler to build the output from WebC.

You will also need a web server to serve the web pages. This can be done as a CGI program or with an embedded web server.

These doc's will be using Bitty HTTP as it's web server.

Support Functions

You must provide some support functions for WebC to work. These are kept to a minimum.

There are currently 3 functions that need to be provided. wcecho(), wcwrite(), and wcSetMine().

wcecho()

/*******************************************************************************
 * NAME:
 *    wcecho
 *
 * SYNOPSIS:
 *    void wcecho(const char *buff);
 *
 * PARAMETERS:
 *    buff [I] -- The C string to send out of the web server.
 *
 * FUNCTION:
 *    This function is called to output a string from WebC code.  This function
 *    takes the C string sent in and sends this string to the web server to
 *    send.
 *
 * RETURNS:
 *    NONE
 *
 * SEE ALSO:
 *    wcwrite(), wcSetMine()
 ******************************************************************************/

This is the function that the called from the WebC code to send a string.

When you are writing your C code this is the function you call to send a string.

The WebC precompiler will call this function to output the HTML blocks and when it does a short echo.

wcwrite()

/*******************************************************************************
 * NAME:
 *    wcwrite
 *
 * SYNOPSIS:
 *    void wcwrite(const unsigned char *bin,int Len);
 *
 * PARAMETERS:
 *    bin [I] -- A binary block to send
 *    Len [I] -- The number of bytes in 'bin'
 *
 * FUNCTION:
 *    This function is called to output binary data from WebC code.  This
 *    function takes a pointer to binary data and sends it to the web server.
 *
 * RETURNS:
 *    NONE
 *
 * SEE ALSO:
 *    wcecho(), wcSetMine()
 ******************************************************************************/

This is the function that the called from the WebC code to send a binary file.

The WebC precompiler will call this function to output binary files.

wcSetMine()

/*******************************************************************************
 * NAME:
 *    wcSetMine
 *
 * SYNOPSIS:
 *    void wcSetMine(const char *Mime);
 *
 * PARAMETERS:
 *    Mime [I] -- The MIME type to set.  This is a string with the MIME
 *                type in it.
 *
 * FUNCTION:
 *    This function is called to set the MIME type for the current document.
 *    This sets the 'Content-Type' in the HTML headers.
 *
 * RETURNS:
 *    NONE
 *
 * SEE ALSO:
 *    wcecho()
 ******************************************************************************/

This is the function that the called from the WebC code to set the 'Content-Type' HTML header.

The WebC precompiler will call this function for binary files. WebC precompiler will guess what file type it is and call this function with the MIME type string for that type.

The WebC precompiler can also be told to output a MIME type as an option.

Using the WebC precompiler

To compile a .wc to a .c you use the webcc command from the "PreCompiler" directory.

The WebC precompiler takes the following arguments:

Usage:
    webcc [options] file...
Options:
  --help                   Display this information.
  -o <file>                Place the output into <file>.
  -x <language>            Specify the language of the following input files.
                           Supported values:
                                c -- A C file
                                c++ -- A C++ file
                                wc -- A WebC file
                                bin -- A binary file
                                c-header -- A C header file
  -m <mime type>           Overrides the auto detect of the mime type on binary files.

So for example lets say you have the example.wc file:

HTML code.  <?wc wcecho("C code."); ?>  HTML code again.

You would compile this with the following line:

webcc example.wc -o out.c
This will make a out.c file.

Modes (HTML/C)

WebC uses the idea of source code modes. You are either in C source mode or HTML source mode. You then switch between them as you build your web page. The WebC precompiler takes this markup code and converts it all to normal C code, which can be compiled by a standard C compiler.

A WebC file starts off in HTML source mode. You write normal HTML code as if it was a .html file. When you get to the point where you want to switch to writing some C code you put a <?wc tag. From this point on the source will be in C mode and you write normal C code. When you want to switch back to HTML source you write a ?> tag. You may switch back and forth between modes as many times as you would like.

The WebC precompiler will convert the WebC code by adding an include at the top of the file, convert all HTML source code to strings that are sent to the wcecho() function, and adds a void Page_{filename}(void) function with all the code in it.

There are a number of exceptions to what code is made by the WebC precompiler. For example you can add your own #includes and global by starting a file with an open <?wc tag. The output code will now include this first block of C code above the Page function.

See also:

Short Tags

Short Tags are shortcuts so you don't have to write the whole <?wc tag. When short tags are enabled (they are by default) you can write code like:

This is HTML<br/>
<?
wcecho("This is C code<br/>");
?>
Back to HTML code<br/>

See the short tags Example.

Short Echo

Short echo is a shortcut where instead of having to enter C source mode and then call wcecho() to output a string variable you can just put the name of the string variable.

For example consider the following code:

<?wc
User info:<br/>
First Name:<?wc wcecho(FirstName); ?>, <?wc wcecho(LastName); ?><br/>
Addresss:<?wc wcecho(Address); ?><br/>

You can instead us:

User info:<br/>
First Name:<?=FirstName?>, <?=LastName?><br/>
Addresss:<?=Address ?><br/>

The second version is somewhat easier to read.

See the short echo Example.

Global Space

Global space is the space outside of any function. Normally WebC places all C source code inside the page function. There are a number of times when you want to place C source outside of this function and place it in the global space instead. WebC lets you do this by starting the file with an open <?wc tag at the very top of the file.

The open <?wc tag must at the very top of the file with no blank lines or space before it (it must be the first 4 chars).

All the code in this first C source block will be added to the top of the C output file. The page function will be output at the point that the first HTML source starts (when you close the C source block with the ?> tag). You may add #includes and any functions you want before the page function here.

You can also access global space by adding a <?wc } at the end of the last HTML source block. This will end the page function and drop into the space directly after the page function. You can then add any C functions you want to use as this point. However if you close the C souce block (switching back to HTML source mode) the WebC precompiler will output wcecho() function calls for the remaining HTML.

See the global space Example.

Strings

Most of the time WebC calls wcecho() to send any HTML it finds out to the web server. However there are times when you want to treat the HTML source as a string instead of just sending it to the web server. This is where WebC strings come into play.

You mark an HTML block as a C string by ending your C block with a =?> instead of the normal ?> tag. WebC will place the next block of HTML in a C string until an open <?wc tag is found.

For example:

<?wc
void TestFn(void)
{
    printf("=?> <div class="block">
        HTML
        code
        is
        here
    </div><?wc);
}
?>

This will make the following C code:

void TestFn(void)
{
    printf(" <div class="block">\n"
"        HTML\n"
"        code\n"
"        is\n"
"        here\n"
"        </div>");
}

See the strings Example.

Binary Files

The WebC precompiler can take a binary file and convert that to C code as well. This is very useful when you want to include graphics or raw javascript into your web site.

This is as simple as running the WebC precompiler and giving it a binary file as an input. The WebC precompiler will look at the extension of the file and set the MIME type and convert the file to a hex array of bytes.

See the binary file Example.

Page Functions

Sometime you will want to replace the page function that WebC auto generates with your own. Maybe you want to call a function before you start outputing any HTML.

WebC will suppress the auto generated page function if the file begins with an open <?wc tag and the first HTML block is inside a function (or any curly brackets).

The WebC precompiler watches how many open braces ({) it see's. If there is a switch to HTML tag when it is inside an open block it will suppress the auto generated page function.

See the page function Example.