renamed generic object pointer to traditional void *self

[svn/Cll1h/.git] / cll1.txt

THIS FILE IS OBSOLETE !!!




C<<1: The Programming Language
==============================

Feedback: xchaos@arachne.cz
Homepage: http://gpl.arachne.cz

Copyright (G) 2004 Michael Polak, x@n.cz
C<<1 is available under terms of GNU Lesser Public License (LGPL)
This file is available under terms of GNU Free Documentation License

1. Introduction
---------------

There are various extensions and definitions of classical C language,
for example object oriented "C++" and "Objective C", minimalistic C--,
proprietary C# used by .Net project, etc. Many other modern languages

C<<1 is designed to work as "stylesheet" for very classical ANSI C, and
it was specificaly tested to work fine with GNU C Compiler gcc. There is
no special C<<1 compiler or interpreter; instead, you are expected to 
include special header file called cll1.h the same way you would include
let's say string or I/O library implemented in standard C library. Except
that you don't need to link your executable with any special library,
neither staticaly nor dynamicaly, and you don't have to configure your gcc
or make to do so.

#include <cll1.h>

Or #include "cll1.h", if cll1.h is not installed in your /usr/include
directory. That'it. No linking, no initialization, allocation, or so.

C<<1 can be used for dummy, structured or object oriented programing,
whatever method you prefere. C<<1 focuses mainly on adding new complex
semantic structures into C, rather than inventing brand new syntax or class
hieararchy, or providing set of pre-defined library functions. To allow
that, most of C<<1 functions are implemented as macros for C preprocessor.

2. Getting started
------------------

#include <cll1.h>

program
{
 puts("Hello World!"); 
}

Of course, int main(int argc,void **argv) can be still used. In fact,
macro "program" doesn't do much more than that ! Following program prints 
all arguments:

program
{
 char *ptr;
 
 arguments
 {
  thisargument(ptr);
  puts(ptr); 
 }
 else
  puts("Bleeeeh, no arguments supplied... :-(");
}

Well, don't be surprised with "else" after "arguments". This is not the 
last time in C<<1, when you will see C keywords somewhere you don't expect
them. Of course, you would like to use it this way, I guess: 

program
{
 char *ptr;
 
 arguments
 {
  argument("-?") printf("This is just help!\n");
  else argument("-f") { nextargument(ptr) printf("Forced argument: %s\n",ptr); }
  else { thisargument(ptr); printf("Simple argument: %s \n",ptr); }
 }
 else
  puts("Bleeeeh, no arguments supplied... :-(");
}

2. Where is my main() funciton ?!  
---------------------------------

If you want to use int main(int argc,void **argv) { } instead of 
program { }, it's ok. Being fan of Basic and not Pascal, I don't
like the program keyword at all. In fact, by avoiding "program" construct
and using standard main() declaration, you would be still able to access 
most of C<<1 functionality, but for example not the arguments() structure
mentioned above.

3. Ok, let's go on
------------------

This is some code to send e-mail using unix sendmail:
(ok, nothing special, same as "echo .... | sendmail ....")

program
{
 paste("From: me@here\nSubject: Here we go...\n\nblah blah blah")
 system("/usr/sbin/sendmail someone@somewhere");
}

This program prints exactly 6th column of /etc/passwd file 
(ok, nothing special, same as "cut -f 6 -d : /etc/passwd")

program
{
 char *ptr;
 parse("/etc/passwd")
 {
  column(ptr,_,':',6);
  if(ptr)puts(ptr);
 }
 done;
}

But next program prints 1st and 6th column of /etc/passwd.
(What is equivalent in bash ?)

program
{
 char *ptr;
 int i;
 parse("/etc/passwd")
 {
  columns(ptr,_,':',i) switch(i)
  {
   case 1: printf("%s...",ptr); break;
   case 6: puts(ptr);
  }
 }
 done;
}


4. Groups of C<<1 macros 
------------------------

! - macro is available only when using "program" instead of "main()"

I. Unconditional iterations - without else

every
iterate
repeat !

II. Conditional iterations - else can happen once

find
arguments !
argument
nextargument

III. Conditional iterations - else can happen many times

search
valid_split
valid_columns

IV. Weird iterations (with something special)

parse - [fail] - done

V. Standalone sequences - they look like function calls, but they are not.

insert
append
push
remove
sort
shell
paste
column
valid_column
...

VI. Well behaved seqences - can be used anywhere where functions can.

create
string
goto_*
prefix
suffix
...

5. Forbidden namespace
----------------------

Variables starting with _ (underscored) followed by one or more capital
characters (A-Z) are reserved as C<<1 private compile-time namespace.

6. Compile time errors
----------------------

- parse error at end of input 

You probably forgot to close some macro which must be obligatory
terminated by another macro - as "parse error" message suggests, 
it is likely to be error in macro "parse() { } [ fail ] { } done; "

:-)

7. We apologize for inconvenience
---------------------------------

This documentation file is unfortunately incomplete.
HTML online documentation is comming soon ... sooner ... or later...