NAME

CIPP - Powerful preprocessor for embedding Perl and SQL in HTML

SYNOPSIS

use CIPP;
my $CIPP = new CIPP ( @params );

# @params are too complex for a synopsis

$CIPP->Preprocess;

DESCRIPTION

CIPP = CgI Perl Preprocessor

CIPP is a perl module for translating CIPP sources to pure perl programs. CIPP defines a HTML embedding language called CIPP which has powerful features for CGI and database developers. Many standard CGI- and database operations (and much more) are covered by CIPP, so the developer has no need to code them again and again.

CIPP is useful in two ways. One aproach is to let CIPP generate standalone CGI scripts, which only need a little environment to run (some configuration files). If you want to use CIPP in this way: there is a complete development environment called spirit which supports you in many ways, to develop such CGI programms with CIPP. spirit can be downloaded from CPAN, but is only free for non commercial usage.

The second is to use the Apache::CIPP_Handler module. This module defines an Apache request handler for CIPP sources, so they will be executed in an Apache environment on the fly, with a two-level cache and great performance. The Apache::CIPP_Handler module is free software.

CIPP LANGUAGE REFERENCE

Use 'perldoc CIPP::Manual' for a language reference. There also exists a PDF document with some additional chapters about CIPP language basics and configuration hints. This file can be downloaded from CPAN as an extra package. This is usefull, because the format of the documentation is PDF and the file has more than 500kb. Also not every modification of CIPP leads to modification of the documentation.

PUBLIC METHODS

The following description of the methods is currently in german only. We will provide english documentation in future.

 $CIPP = new CIPP ($input, $output, $projects_file, $database_file,
		  $mime_type, $default_db, $call_path,
		  $skip_header_line, $debugging
		  [, $result_type ] [, $use_strict] [, $reintrant]
		  [, $apache_mod ] [, $spirit_project ]
		  [, $use_inc_cache ] [, $lang ] );
	$input		Dateiname oder Filehandle-Referenz oder
			Scalar-Referenz fuer Output
	$output		Dateiname oder Filehandle-Referenz oder
			Scalar-Referenz fuer Output
	$projects_file	Dateiname der Projekt-Konfigurationsdatei
	$database_file	Dateiname der Datenbank-Konfigurationsdatei
	$mime_type	Mime-Type der zu generierenden Seite
			= "cipp/dynamic" wenn Seite selber den HTTP-
			  Header ausgibt
	$default_db	Name der Datenbank, auf die defaultmaessig
			zugegriffen werden soll. Darf undef sein,
			dann werden SQL Befehle ohne Angabe einer
			Datenbank als Fehler gemeldet
	$call_path	Auflistung der Macros ueber die diese
			CIPP-Quelle aufgerufen wurde, mit : getrennt.
			Muß bei erstem Aufruf weggelassen werden bzw.
			leer sein
     $skip_header_line	Wenn dieser Parameter gesetzt ist,
			wird beim Einlesen eines CIPP Sources
			der Anfang solange ueberlesen, bis der Inhalt
			von $skip_header_line als einziges in
			der Zeile steht.
	$debugging	wenn 1, dann werden im erzeugten Perl-Code
			entsprechende Remarks erzeugt, aus denen
			der Perl-Interpreter bei Laufzeitfehlern
			die dem CIPP-Originaltext entsprechednen
			Zeilennummern generieren kann.
	$result_type	Typ des Dokumentes, was durch das Preprocessing
			erstellt werden soll:
			'cipp'	    : CIPP-CGI-Programm (Default)
			'cipp-html' : statische HTML Seite
			Wenn 'cipp-html' angegeben wird, werden
			URL's auf statische Seiten relativ ausgegeben
	$use_strict	soll 'use strict' generiert werden oder nicht
	$reintrant	soll reintranter Code generiert werden oder nicht
	$apache_mod	true, wenn Einsatz als Apache-Modul
	$project	Das Project, in dem sich das zu bearbeitende
			Objekt befindet.
	$use_inc_cache	Soll der Include Cache verwendet werden?
	$lang		Sprache für Fehlermeldungen EN=Englisch, DE=Deutsch

 $status = $CIPP->Get_Init_Status();
	liefert	0 : Fehler beim Initialisieren
		1 : OK

 $CIPP->Preprocess();
	Uebersetzt die CIPP-Quelle nach Perl 

 $CIPP->Set_Write_Script_Header($on)
	$on		1 = Perl-Header wird geschrieben (zum Einbinden
			    von Libraries etc.)
			0 = Perl-Header wird nicht geschrieben, d.h.
			    es wird NUR der CIPP-Code 1:1 uebersetzt

 $CIPP->Set_Print_Content_Type ($on)
	$on		1 = Content-Type wird vom generierten Perl
			    Script ausgegeben
			0 = Content-Type wird vom generierten Perl
			    Script nicht ausgegeben

	Wirkt sich nur aus, wenn Write_Script_Header eingeschaltet
	ist.

 $status = $CIPP->Get_Preprocess_Status();
	- liefert 0, wenn Fehler aufgetreten sind
	- liefert 1, wenn keine Preprocessorfehler aufgetreten sind

 $status = $CIPP->Set_Preprocess_Status();
	Setzt den Status.

 $array_ref = $CIPP->Get_Messages();
	Liefert Preprocessor-Meldungen als Referenz auf
	ein Array, dessen Elemente folgendes Format haben:
		Aufrufpfad <TAB> Zeilennummer <TAB> Meldung

 $hash_ref = $CIPP->Get_Used_Macros();
	Liefert eine Hash-Referenz mit den Namen der Macros als Key,
	die von der uebersetzten Seite eingebunden werden. Liefert
	undef, wenn Methode vor Preprocess() aufgerufen wird oder keine
	Macros benutzt wurden

 $hash_ref = $CIPP->Get_Used_Images();
	Liefert eine Hash-Referenz mit den Namen der Bilder als Key,
	die von der uebersetzten Seite eingebunden werden. Liefert
	undef, wenn Methode vor Preprocess() aufgerufen wird oder keine
	Bilder benutzt wurden

 $hash_ref = $CIPP->Get_Used_Databases();
	Liefert eine Hash-Referenz mit den Namen der von der Seite
	benutzten Datenbanken als Key. Liefert undef, wenn Methode vor
	Preprocess() aufgerufen wird oder keine DB's benutzt wurden

 $hash_ref = $CIPP->Get_Used_Configs();
	Liefert eine Hash-Referenz mit den Namen der von der Seite
	benutzten Konfigurationen als Key. Liefert undef, wenn Methode
	vor Preprocess() aufgerufen wird oder keine Configs benutzt
	wurden

PRIVATE METHODS

 $hash_ref = $CIPP->Get_Include_Inputs();
	Liefert eine Listen-Referenz mit den Namen der von dem Include
	deklarierten MUSS-Input Parametern.

 $hash_ref = $CIPP->Get_Include_Optionals();
	Liefert eine Listen-Referenz mit den Namen der von dem Include
	deklarierten optionalen Input Parametern.

 $CIPP->Add_Message ($message, [$line] );
	Haengt Meldung $message an das Meldungs-Array an. Wenn $line
	nicht angegeben wird, wird die aktuelle Zeilennummer eingesetzt,
	sonst die uebergebene.

 $CIPP->Error ($tag, $message, [$line] );
	Schreibt $message und $tag in Meldungs-Array und setzt
	Preprocess_Status auf 0. Wenn eine Zeilennummer ($line)
	angegeben wird diese in die Fehlermeldung eingesetzt, ansonsten
	die aktuelle Zeilennummer

 $CIPP->Check_Options ($tag, $must_options, $valid_options, $hash_ref);
	Prueft die Optionen eines Tags auf Korrektheit.
	Es muessen alle in $must_options aufgefuehrten Parameter
	vorkommen. Es duerfen keine anderen als in $valid_options
	aufgefuehrten Parameter vorkommen. Wenn in $valid_options
	ein * steht, wird diese Pruefung nicht vorgenommen.
	Im Fehlerfalle wird 0 zurueckgegeben, sonst 1.

 $CIPP->Check_Nesting ($tag, $end_tag);
	Prueft, ob das uebergebene $tag an dieser Stelle syntaktisch,
	bzw. von der Schachtelung her, korrekt ist. Ist $end_tag
	gesetzt, wird geprueft ob das Schließen des uebergebenen Tags
	an dieser Stelle korrekt ist.
	Im Fehlerfalle wird eine entsprechende Fehlermeldung in das
	Meldungs-Array 	geschrieben und 0 zurueckgegeben. Ist alles
	korrekt, wird 1 zurueckgegeben.

 $CIPP->Generate_CGI_Code
	Generiert ggf. Script-Header, der u.a. fuer das Importieren
	der via CGI uebergebenen Eingabeparameter sorgt.
	Es wird keine Ausgabe generiert, wenn das Flag
	$CIPP->{write_script_header} nicht gesetzt ist.
	Der Code wird direkt in die Zieldatei geschrieben.

 $CIPP->Generate_Database_Code
	Generiert Code zum Initialiseren und Beenden von Datenbank-
	verbindungen, wenn es Datenbank-Befehle in der Seite gibt.
	Der Code wird direkt in die Zieldatei geschrieben. Die
	Methode darf NICHT VOR Generate_CGI_Header() aufgerufen
	werden.

 $CIPP->Skip_Header ()
	Liest solange von der Eingabequelle, bis
	$CIPP->{skip_header_line} gefunden wurde. Der Zeilen-
	zaehler der Eingabequelle wird auf 0 gesetzt.

 $object_type = $CIPP->Get_Object_Type ($object)
	Gibt den Typ des übergebenen $object zurück. Wenn dieser
	nicht eindeutig sein sollte, wird undef zurückgegeben.

 $object_path = $CIPP->Resolve_Object_Source ($object [, $object_type])
	Ermittelt aus dem abstrakten Objektnamen $object und
	dessen Typ $object_type den absoluten vollstaendigen
	Dateinamen im src-Zweig. $object_type darf auch weggelassen
	werden, dann wird keine Endung beim Dateinamen generiert.
	Liefert undef wenn der Projektanteil des Objektnames
	nicht bekannt ist.
	ES WIRD NICHT GEPRUEFT, OB DIE DATEI EXISTIERT!

 $url = $CIPP->Get_Object_URL ($object)
	Gibt die URL des Objektes zurück, wenn es eine hat. Gibt
	undef zurück, wenn das Objekt nicht existiert, oder wenn
	es keine URL hat.

 ($url, $ext) = $CIPP->Get_Image_Info ($object)
	Gibt Bildinformationen zu $object zurück. $url enthält
	die URL und $ext die Dateiendung des Bildes. $url ist
	undef, wenn das Bild nicht exisitiert oder $object nicht
	vom Type 'cipp-img' ist.

 \$html_formatted_source_code = $CIPP->Format_Debugging_Source (e)
	Gibt HTML formatierten CIPP-Quellcode zurück. Dabei werden
	die in der Instanz festgehaltenen Fehlermeldungen eingearbeitet
	und hervorgehoben.

AUTHOR

Jörn Reder, joern@dimedis.de

COPYRIGHT

Copyright 1997-1999 dimedis GmbH, All Rights Reserved

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), Apache::CIPP_Handler(3pm)