Login   Register  
PHP Classes
elePHPant
Icontem

File: README.TXT

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Classes of Mark Quah  >  INIParser  >  README.TXT  >  Download  
File: README.TXT
Role: Documentation
Content type: text/plain
Description: Explanation
Class: INIParser
use ini format to generate HTML image
Author: By
Last change: Added complete function listing to the end of README.TXT.
Date: 2002-11-14 09:57
Size: 9,350 bytes
 

Contents

Class file image Download
FUNCTION DESCRIPTION IS AT THE END OF THIS FILE.

Description:
    This class is aim to read in .ini file into array for easy reference.

Syntax:
       $data = new INIPARSER( "filename" [, "start state", "debuglevel"])

explanation:
    $filename: empty if you want to 'program' in the data.
    start state = 0 wait for keyword PARSERSTART before interpretation
    start state = 1 jump straight into interpretation

This is give me three mode of reading an ini file which illustrates in the
sample script

-----------------------------------------------
EXTERNAL DATA FILE

Say a file with format:

    [category1]
    item1="asfasfd"
    item2="safdasdfsaf"
    item3="asfdasfdasfd"

    [category2, FREE]
    line 1 lsjdfsadf
    line 2 lsajfdlsadfsf

[ ] encloses the category name, if the items are free forms, ie no equal signs, use a  ",FREE" after the category name.

To read this file,

    $data = new INIPARSER("filename");
    echo $data->item['category1']['item1']."<BR>";
    echo $data->item['category1']['item2']."<BR>";
    ...
    echo $data->item['category2'][0]."<BR>";
    echo $data->item['category2'][1]."<BR>";
    echo $data->item['category2'][2]."<BR>";

--------------------------------------------------------
INTERNAL SOURCE
If I want to embed the table in my php script, here's how I do it:
Note that class start with referencing itself using PHP built-in variable
__FILE__, and init state 0, ie don't interprete unless between PARSERSTART
and PARSEREND pair.

<?php
     include_once "class_iniparser.php";

     $data= new INIPARSER(__FILE__, 0);
      .....

    die;  // so I won't leak out the following lines to client
?>
<! // so it will not display even it leak out
PARSERSTART
[cat1]
item1=asfddsaf
....
PASEREND
!>

--------------------------------------------------------
PROGRAMM MODE

For those who want to rig in prgram code, here's how to assess parser
engine directly, one line at one time:


    $data = new INIPARSER("");
    $data->ParseLine('[cat1]');
    $data->ParseLine('item1=sdfsadf');
    ....

========================================================
Update Category using item from another category

If I have two category:

    [FIELD]
    data1=abc
    date2=def

    [STYLE]
    HEADER=<BODY ALIGN=CENTER>

    [CONTENT, FREE]
    {HEADER}
    Data 1 is {data1} and Data 2 is {data2}


Why don't I use data in FIELD to update CONTENT to give me

    Data 1 is abc and Data 2 is def

That's how I do it:

    $data->UpdateCat('HTML', 'CONTENT', 'STYLE', 'FIELD', ...)

The 'CONTENT' must be a FREE format since it is the data and not the key that changes and 'FIELD; must be a index field since it must have both key and value. The declaration of FREE category is by adding a ", FREE" prefix.
Note that the change in destination cat is permanent, ie the data in 'HTML' is change
permanently. If such changes is not desired, have to do a bit of work

    $content = $data->GetCatStr('HTML');
    $html = $data->UpdateStr($content, 'STYLE');
    $html = $data->UpdateStr($html, 'FIELD');
    $html = $data->UpdateStr($html, 'FIELD2');
    $html = $data->UpdateStr($html, 'FIELD3');

The command GetCatStr will return a string that contains all the row in the FREE format category.

----------------------------------------------------------------------
============================
function INIPARSER($file_name = "", $parse_state=1, $debug_level=1)
USES: to initialize INIPARSER class
INPUT:
    file_name
        : name of ini file to be read in
        "": start with empty set
    parase_state:
        1: jump straight into interpretation
        0: wait for PARSERSTART before interpretation
           PARSEREND will end. Use for embeded data within
           PHP program or data file
    debug_level:
        0 - 9: 0 no output, 9: very messy output.


============================
function ParseFile($file_name="", $parse_state=1)
USES: to read in category from a file
INPUT
    file_name: file to be read
    parse_state: as in INIPARSER

============================
function ReadFile($des_cat, $file_name)
USES: To read a file content into a FREE FORM category
INPUT:
    $des_cat: destination category to be used
    $file_name: name of file to be read
OUTPUT:
    content of file stored in $this->item[$des_cat][<line_no start from 0>]
    to reproduct: $str = $this->GenCatStr($des_cat);

============================
function ReadStr($des_cat, $str)
USES: To store a string of text into a FREE FORM category
INPUT:
    $des_cat: destination category to be used
    $str: data content
OUTPUT:
    content of file stored in $this->item[$des_cat][<line_no start from 0>]
    to reproduct: $str = $this->GenCatStr($des_cat);

============================
function SetItem($des_cat, $field_name, $value)
USES: to store a value to an item within a category
INPUT:
    $des_cat: destination category
    $field_name: destination field
    $value: value to be stored
REMARK
    to retreive:  $value = $this->item[$des_cat][$field_name]

============================
function ParseLine($buffer)
INTERNAL: parse ini file with a state diagram.

============================
function ParseCategory($input)
INTERNAL: to determine a category header is free form or index

============================
function ParseItem($input)
INTERNAL: to add an item according to category type

============================
function UpdateCat( $tmpl_cat, $data_cat, $des_cat = "")
USES: To replace {} fields in $tmpl_cat with actual value from $data_cat
      If des_cat is ommitted, $tmpl_cat is overwritten
INPUT
    $tmpl_cat: template category whose items contain {} field
    $data_cat: {name} field will be replaced by the $this->item[data_cat]['name']
    $des_cat: destination cat to be written to, if empty, tmpl_cat is used.

============================
function UpdateStr( $str, $src_cat)
USES: to replace {} fields in string with the src_cat

============================
function GetCatStr( $cat)
USES: to combine the items in the $cat to give a string
INPUT: $cat: category to be output
OUTPUT: string
    eg. $html = GetCatStr("HTML_SOURCE");

============================
function GenForm()
USES: Single template with multiple data sources merge
INPUT:
    Arg 1 (MUST) des_cat: des_cat to be written to
    Arg 2 (MUST) tmpl_cat: template cat with {} fields
    Arg 3- (OPTION) data_cat: zero or more data cat to be merged
OUTPUT:
    string of the destination cat
Example
    $html = $this->GenForm("HTML_FINAL", "HTML_TEMPLATE",
                            "STYLE_DATA", "FIELD_DATA");
    HTML_TEMPLATE's {} fields will be replaced by items in
    STYLE_DATA followed by FIELD_DATA in that order.
    The output is returned to $html.

============================
function FormLogic($action_cat, $action)
USES: based on the $action, trigger respective function
    [HTMLACTION]
    ACTION1=FUNC1, FILENAME1.php, FILENAME2.php
    ACTION2=FUNC2
FormLogic('HTMLACTION', 'ACTION1') will cause this action:
    include FILENAME1.php;
    include FILENAME2.php;
    FUNC1();
FormLogic('HTMLACTION', 'ACTION2') will cause this action:
    FUNC2();
Note that I have not master how to throw in the argument. If you can post it
to me.

============================
function ShowItem( $html = 1)
USES: to show all category and item on screen. For debugging purposes.

============================
function SetForm($form_name, $action_file="", $action_field="form_action",  $method="POST", $extension="")
USES: To create a form related field:
INPUT:
        form_name: name of the form to be generated
        action_file: the form will be submitted to this URL
        action_field: the name of the field containing the action value
        method: form method, either POST or GET
        extenstion: eg encode=multpart/application ...
OUTPUT
    $this->item["FORM_NAME"]["FORMSTART"] =
        <FORM NAME=FORM_NAME METHOD=GET ACTION=action_file $extension>
        <INPUT TYPE=HIDDEN NAME=action_field>
        note that this formstart will be added hidden fidden field
        with AddFormHidden statement;

    $this->item["FORM_NAME"]["JSSUBMIT"] =
        <script>function SUBMIT(value)
        {   document.forms.FORM_NAME.action_field = value;
            document.forms.submit();
        } </script>

    use for page link. Eg
        <A HREF='javascript:SUBMIT('FORMACTION')'>FORM ACTION</A>
    will create a link to jump to the same page but execute the function
    defined by FORMACTION in the logic category.

============================
function AddFormHidden($form_name, $name, $value)
USES: To add a hidden field to pass information between pages
INPUT: FORM_NAME: form name to add to
    $name: name of the field
    $value: value of the field
OUTPUT
    $this->item[FORM_NAME]['FORMSSTART'] will be appended with
    a statement:
        <INPUT TYPE=HIDDEN NAME=name VALUE=value>

============================
function Debug($level, $msg)
USES: Debug purpose. If $level < $this->debug_level, the msg will not be displayed

============================
function Output($str, $html)
INTERNAL