<?xml version="1.0"?>
<documentation status="function names are guaranteed to stay as they are now, it's safe to write a big work with it" date="November the 1st 2002">
<basic title="Basics">
<base title="Things you should already know">
First of all, you must have studied the following topics to continue:
The <a href="http://www.php.net">PHP</a> Scripting Language
XML (extensible markup language)
If you don't know about these things yet, please <font color="red">study them first</font>.
</base>
<base title="The tag selection base">
in most of the API functions introduced in Kxparse you will remark a method of direct tag selection, this method allows selection of tags in the deepest trees (unlimited) with only one API function, for example:
get_attribute("enclosingtag:child:childofchild:childofchildofchild","1:2:1:4","name");
So what is that? this function told the parser to first select the root tag of the XML document with the index 1, and then to select its child named "child" with the index 2, and then the child of child named "childofchild" index 1,and then the child of child of child called "childofchildofchild" with index 4.
If we looked at the XML snippet below, this function will select the tag in bold, and then extract from it (according to the function), the attribute value written in red:
/*<t;?xml version="1.0"?>t;
<t;enclosingtag>t;
<t;child>t;
any value or children go here
<t;/child>t;
<t;child>t;
<t;childofchild>t;
<t;childofchildofchild>t;
any value here
<t;/childofchildofchild>t;
<t;childofchildofchild>t;
any value here
<t;/childofchildofchild>t;
<t;childofchildofchild>t;
any value here
<t;/childofchildofchild>t;
<b><t;childofchildofchild name="<font color="red">any name man :)</font>">t;
<t;/childofchildofchild>t;</b>
<t;/childofchild>t;
<t;/child>t;
<t;/enclosingtag>t;
There's one more rule for ease of use, you can remove the the index and write "-1" instead, this refers to the last tag of the name matching it in the tag name string, for example:
because the example above introduced "4" in the last selection, and 4 is same as the last tag in the snippet so the following code will give the same value marked in the snippet:
get_attribute("enclosingtag:child:childofchild:childofchildofchild","1:2:1:<font color="red">-1</font>","name");
Note: When we get to API documentation, you will be able to see the difference between normal strings and these colon separated strings like that:
the tag name colon-spearated list will be called: colonedtagname
the tag index colon-separated list will be called: colonedtagindex
<font color="red">Note: Since Kxparse 1.0 it is safe to write more than one "-1" for example(not with the snippet above): </font>
get_attribute("enclosingtag:child:childofchild:childofchildofchild","<font color="red">-1:-1:-1:-1</font>","name");
</base>
<base title="Name Spaces support">
in Kxparse 1.0 it's possible to select a tag name that has a name space in it, just surround the tag name with braces for example:
<code>get_tag_text("atag:anothertag:(xsl:apply-templates)","1:1:1","name");</code>
</base>
</basic>
<api title="API Documentation">
<function name="kxparse" text="Class constructor">
<code>kxparse(string file)</code>
This is the constructor through which you can instantiate Kxparse, it takes only one argument which is the XML file you want the parser to work on, the parser then loads the XML file in the object variable <code>xml</code>.
Note: The function inherits its functionality from the PHP function fopen, everything that applies to that function applies here as well, for example, you can open remote files on HTTP/FTP servers, by specifying a valid URL in the <code>file</code> argument.
</function>
<function name="get_attribute" text="Get the value of an attribute of a tag in the XML tree">
<code>string get_attribute(string colonedtagname, string colonedtagindex, string attribute)</code>
This function simply gets the value of the <code>attribute</code> from the tag selected using the <code>colonedtagname</code> and <code>colonedtagindex</code>
The <code>colonedtagname</code> is a colon-separated list of the tag tree, and the <code>colonedtagindex</code> is a colon-separated list of the tree indeces.
Example:
<code>get_attribute("myroot:firstlevel","1:3","name")</code>
Will select the tag in bold and the attribute value in red of the XML snippet below:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel name="<font color="red">my name</font>">t;
<t;/firstlevel>t;</b>
<t;/myroot>t;
</function>
<function name="get_tag_text" text="Get the text of a tag available in the XML tree">
<code>string get_tag_text(string colonedtagname, string colonedtagindex)</code>
This function will get the text enclosed within the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code>.
The <code>colonedtagname</code> is a colon-separated list of the tag tree, and the <code>colonedtagindex</code> is a colon-separated list of the tree indeces.
Example:
<code>get_tag_text("myroot:firstlevel","1:3")</code>
Will select the tag in bold and return the text in red of the XML snippet below:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel>t;
<font color="red">the text selected</font>
<t;/firstlevel>t;</b>
<t;/myroot>t;
</function>
<function name="set_attribute" text="Set the value of an attribute of a tag in the XML tree">
<code>void set_attribute(string colonedtagname, string colonedtagindex, string attribute, string value)</code>
This function either adds a new attribute to the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code> and assigns the given value to it, or(if the attribute was already found) changes the value of an already available attribute in that tag to the given value.
The <code>colonedtagname</code> is a colon-separated list of the tag tree, and the <code>colonedtagindex</code> is a colon-separated list of the tree indeces.
Example:
<code>set_attribute("myroot:firstlevel","1:3","name","Kxparse is useful")</code>
Before excution of the above code(the tag concerned with the change is in bold):
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel>t;
<t;/firstlevel>t;</b>
<t;/myroot>t;
After Excution of the code, the tag in bold and the change in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel <font color="red">name="Kxparse is useful"</font>>t;
<t;/firstlevel>t;</b>
<t;/myroot>t;
</function>
<function name="count_tag" text="Counts the number of occurences of a particular tag">
<code>integer count_tag(string colonedtagname, string colonedtagindex)</code>
This function is used to count the number of tags in a particular level of the XML file.
<code>colonedtagname</code> is a colon-separated list of the tags, the last tag of them is the tag which you want to count, and the tag before the last is the parent tag of the counted tag.
<code>colonedtagindex</code> is a colon-separated list of the tags matching the tree inserted in <code>colonedtagname</code>, the last index is removed and instead of it writen a question mark "?", so that the parser knows that you want to count the occurences of the tag matching the question mark.
Example:
<code>count_tag("myroot:firstlevel","1:?")</code>
This will return 3 and will count the tags in bold in the XML snippet below:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<b><t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;</b>
<t;/myroot>t;
</function>
<function name="remove_tag" text="Remove a tag from the XML tree">
<code>void remove_tag(string colonedtagname, string colonedtagindex)</code>
This function removes a tag (with its children) from the XML tree, this tag is selected by <code>colonedtagname</code> and <code>colonedtagindex</code>
<code>colonedtagindex</code> is a colon-separated list of the tags matching the tree inserted in <code>colonedtagname</code>, the last index is removed and instead of it writen a question mark "?", so that the parser knows that you want to count the occurences of the tag matching the question mark.
Example:
<code>remove_tag("myroot:firstlevel","1:2")</code>
Before excution, the part that will be removed is in bold:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel someattr="some value">t;
this tag will be removed ofcourse
<t;/firstlevel>t;</b>
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
After excution of the above example:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
</function>
<function name="create_tag" text="Create a tag in the XML tree">
<code>void create_tag(string colonedtagname,string colonedtagindex, string tagname)</code>
This function inserts a tag in the XML tree, and appends it to the children of the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code>
<code>colonedtagindex</code> is a colon-separated list of the tags matching the tree inserted in <code>colonedtagname</code>, the last index is removed and instead of it writen a question mark "?", so that the parser knows that you want to count the occurences of the tag matching the question mark.
Example:
<code>create_tag("myroot:firstlevel","1:2","secondlevel")</code>
Before excution, the parent under which the tag will be inserted is in bold:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel someattr="some value">t;
<t;/firstlevel>t;</b>
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
After excution, the tag inserted is marked in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel someattr="some value">t;
<font color="red"><t;secondlevel>t;
<t;/secondlevel>t;</font>
<t;/firstlevel>t;</b>
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
</function>
<function name="save" text="Save the current XML content">
void save(string file)
This function simply saves the current XML content to <code>file</code>
If the file is already available the function will overwrite it.
Note: as fopen doesn't allow writing on remote servers, so this function is only able to save to the local web tree or physical path.
Example:
<code>save("../myfirstxml.xml")</code>
</function>
<function name="xml" text="a Property that holds the current XML content">
<code>string xml</code>
This is a property that holds the current XML content in the parser, all functions operate on it.
you can use it to modify the XML content yourself, for example, you can delete the current XML content:
<code>$xmlobj->xml=""</code>
And then load your own XML into it
<code>$xmlobj->xml="<t;?xml version="1.0"?>t;<t;root>t;<t;/root>t;"
you can also use it to just print the current XML content:
<code>echo $xmlobj->xml</code>
</function>
<function name="set_tag_text" text="Sets the text of a tag present in the XML tree">
<code>void set_tag_text(string colonedtagname, string colonedtagindex, string text)</code>
This function is used to change the text of the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code>.
<code>colonedtagindex</code> is a colon-separated list of the tags matching the tree inserted in <code>colonedtagname</code>, the last index is removed and instead of it writen a question mark "?", so that the parser knows that you want to count the occurences of the tag matching the question mark.
Example:
<code>set_tag_text("myroot:firstlevel","1:3","The new text")</code>
Before excution, the tag is in bold and the text that will be replaced is in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel someattr="some value">t;
<t;/firstlevel>t;
<b><t;firstlevel>t;
<font color="red">This a bad text that will be replaced</font>
<t;/firstlevel>t;</b>
<t;/myroot>t;
After excution, the inserted text is also in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel someattr="some value">t;
<t;/firstlevel>t;
<b><t;firstlevel>t;
<font color="red">The new text</font>
<t;/firstlevel>t;</b>
<t;/myroot>t;
</function>
<function name="set_pi" text="Sets or changes the a particular attribute of the Processing Instruction">
<code>void set_pi(string attribute, string value)</code>
This function simply adds a new processing instruction <code>attribute</code> with the value <code>value</code>
If the processing instruction attribute was found the function changes its value to <code>value<code>
Example:
<code>set_pi("encoding","ISO-8859-1")</code>
Before the change the affected area is in bold:
<b><t;?xml version="1.0"?>t;</b>
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel someattr="some value">t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
After the change, the inserted attribute and value are in red:
<b><t;?xml version="1.0" <font color="red">encoding="ISO-8859-1"</font> ?>t;</b>
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel someattr="some value">t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
</function>
<function name="load" text="Dynamically Loads a new XML file into the parser">
<code>void load(string filename)</code>
This function erases the current XML content and then loads another XML file into the parser.
You may here -as well as the constructor- use a URL as the <code>filename</code>
Example:
<code>load("http://www.mydomain.com/example.xml")</code>
</function>
<function name="search_tags" text="Search for a tag in the XML tree that has a known text">
<code>mixed search_tags(string colonedtagname, string colonedtagindex, string matchtext)</code>
This function searches for a tag in the XML tree which has text matching <code>matchtext</code>
The function searches in collection of tags indiciated by the index which has the "?" instead of the index number, and with the name corresponding to the ? in <code>colonedtagname</code>
If the function finds results, it returns an array carrying the indeces of the matching tags, if no tags matched it returns false
Example:
<code>search_tags("myroot:firstlevel","1:?","the new text")</code>
The tags that will be searched are in bold and the matching tags are in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<b><font color="red"><t;firstlevel>t;
the new text
<t;/firstlevel>t;</font>
<t;firstlevel>t;
something different from "the new text"
<t;/firstlevel>t;
<font color="red"><t;firstlevel>t;
the new text
<t;/firstlevel>t;</b></font>
<t;/myroot>t;
</function>
<function name="isearch_tags" text="Case-insensitive search for a tag in the XML tree that has a known text">
Identical to search_tags in everything, the only difference is that it's case-insensitive
</function>
<function name="search_attributes" text="Search for a tag in the XML tree that has a particular attribute value">
<code>mixed search_attributes(string colonedtagname, string colonedtagindex, string attributename, string attributevalue)</code>
The function searches for a tag in the XML tree whose attribute named <code>attributename</code> has the value <code>attributevalue</code>
The function searches in collection of tags indiciated by the index which has the "?" instead of the index number, and with the name corresponding to the ? in <code>colonedtagname</code>
If the function finds results, it returns an array carrying the indeces of the matching tags, if no tags matched it returns false
Example:
<code>search_attributes("myroot:firstlevel","1:?","name","a good name")</code>
The searched tags are in bold and the mathcing are in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<b><font color="red"><t;firstlevel name="a good name">t;
<t;/firstlevel>t;
<t;firstlevel name="a good name">t;
<t;/firstlevel>t;</font>
<t;firstlevel>t;
<t;/firstlevel>t;</b>
<t;/myroot>t;
</function>
<function name="isearch_attributes" text="Case-insensitive search for a tag in the XML tree that has a particular attribute value">
Identical to search_attributes in everything, the only difference is that it's case-insensitive
</function>
<function name="has_attribute" text="Checks if a tag has a particular attribute">
<code>boolean has_attribute(string colonedtagname, string colonedtagindex, string attributename)</code>
This function checks if the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code> has an attribute named <code>attribute name</code>
returns true in case that the attribute was found, otherwise the function returns false
Example:
with the XML snippet below, the following code will return true
<code>has_attribute("myroot:firstlevel","1:1","name")</code>
while this one will return false:
<code>has_attribute("myroot:firstlevel","1:1","age")</code>
The tag which both of the functions operate on is in bold:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<b><t;firstlevel name="a good name">t;</b>
<t;/firstlevel>t;
<t;firstlevel name="a good name">t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
</function>
<function name="get_attributes" text="Get all the attributes of a tag with their values in an array">
<code>Array get_attributes(string colonedtagname, string colonedtagindex)</code>
This function returns an array of (attribute name->attribute value) pairs of the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code>
Example:
<code>get_attributes("myroot:firstlevel","1:2")</code>
on the XML snippet below, the tag that will be operated on is in bold:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel name="a good name" age="no age" gender="no gender">t;
<t;/firstlevel>t;</b>
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
Will return:
Array
(
[name] => a good name
[age] => no age
[gender] => no gender
)
</function>
<function name="set_ns" text="disables or enables namespaces support">
<code>void set_ns(boolean to)</code>
Namespaces support is enabled by default, but if you are sure that your XML document won't contain namespaces, so it's better to disable namespaces support for faster parsing.
This function enables you to do this because it sets namespaces support according to the boolean variable <code>to</code>
Note: namespaces support doesn't change when you use the function <code>load</code> to load a new XML file, you must manually edit it if you want to.
Note: expectedly disabling namespaces support makes the function <code>create_tag</code> return an error message when you try to create a tag with a namespace in it.
<font color="red">Note: trying to retrieve a tag with a namespace in it while the support is disabled will in most cases return an error message, but in other -few- cases it may <b>make unexpected changes to the file</b></font>
Refer to the <a href="docs.php?place=base">Basics section</a> for more info about namespaces support
Example:
<code>set_ns(false)</code>
This disables namespaces support
</function>
<function name="set_attributes" text="Set a group of attributes for a tag using an array">
<code>void set_attributes(string colonedtagname, string colonedtagindex, string[][] arr)</code>
This function gets an array <code>arr</code> (attribute name -> attribute value) and sets attributes for the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code> according to it.
It's good for integration with <code>get_attributes</code>, to copy the whole attributes of a tag typically, or after edition to another tag.
Example:
consider the following array named <code>atts</code>:
<code>
print_r($atts);
produces the following:
Array
(
[name]=> no name
[age]=> no age
}
</code>
Using it with this function like this:
<code>set_attributes("myroot:firstlevel","1:3",$atts)</code>
Before edition the selected tag is in bold:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel>t;
<t;/firstlevel>t;</b>
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
After edition the affected tag is in bold and the inserted attributes are in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel <font color="red">name="no name" age="no age"</font>>t;
<t;/firstlevel>t;</b>
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
</function>
<function name="set_CD" text="Enables/disables CDATA sections support">
<code>void set_CD(boolean to)</code>
CDATA sections support is enabled by default, but it was found that it greatly affects the parser speed, so if you are sure that your XML document will not contain CDATA sections, it's extremely recommended to disable CDATA sections support.
This function enables you to do that, according to the argument <code>to</code> -- true enables and false disables.
The function then does all the internal changes required.
Example:
<code>set_CD(false)</code>
disables CDATA sections support.
</function>
<function name="create_CD" text="Makes a CDATA section from a given text">
<code>string create_CD(string text)</code>
This is an auxillary function that automatically creates a CDATA section out of the given text.
honestly it does two things:
-- It checks for CDATA tags inside the given text, if found the function gives an error message
-- Concats the start and end of the CDATA section tag to the given string
You can then use this function with <code>set_tag_text</code>.
Example:
<code>create_CD("no one but no one can catch <t;![CDATA[ elmagnifico ]]>t;")</code>
This will kill your script and write:
Error: Kxparse: create_CD: A CDATA section cannot contain an opening or closing symbol of CDATA
Because simply the given text contained a CDATA tag.
</function>
<function name="to_internal_close" text="turns an empty tag into an internally-closed tag">
<code>void to_internal_close(string colonedtagname, string colonedtagindex)</code>
This function turns the tag selected by <code>colonedtagname</code> and <code>colonedtagindex</code> into an internally closed tag.
If the tag contained text it's not turned, not to lose data.
If the tag is already internally closed, the function does nothing.
Note: The function preserves the attributes of the tag.
Example:
to_internal_close("root:firstlevel","1:2")
Before execution, The affected tag is in bold:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><t;firstlevel name="good name">t;
<t;/firstlevel>t;</b>
<t;firstlevel name="no name" age="no age">t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
After excution the resulting tag is in red:
<t;?xml version="1.0"?>t;
<t;myroot>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<b><font color="red"><t;firstlevel name="good name"/>t;</font></b>
<t;firstlevel name="no name" age="no age">t;
<t;/firstlevel>t;
<t;firstlevel>t;
<t;/firstlevel>t;
<t;/myroot>t;
</function>
</api>
</documentation> |
Stumble It!
Bookmark in del.icio.us
Download
