<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>Search and Replace class documentation</TITLE>
<LINK REL="STYLESHEET" MEDIA="screen" HREF="documentation.css" TYPE="text/css">
</HEAD>
<BODY>
<H1 CLASS="center background border">Search and Replace class</H1>
<DIV CLASS="background-light border">
<H2>Contents</H2>
<TABLE BORDER="0">
<TR>
<TD>
<UL>
<LI>Introduction</LI>
<LI>Installation</LI>
<LI>Main Usage</LI>
<LI>Function Reference</LI>
<LI>License</LI>
</UL>
</TD>
</TR>
</TABLE>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Introduction</H2>
<P>
This class was originally a script that performed a simple search/replace on files
and/or directories. I've now converted it to a class with a few extra features so it
should be a little more useful and easier to use. Should also be easier to incorporate
into to other scripts.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Installation</H2>
<P>
Simply copy the class file to your usual "includes" directory and include it the
script you wish to use it in.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Main Usage</H2>
<P>
To use it (after include()ing it), do this:
</P>
<PRE>
$sr = new search_replace('find this', 'replacement', 'file.txt');
$sr->do_search();
</PRE>
<P>
The full arguments you can pass when creating the object are described below. There are
of course other functions to use, which are also described below.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Function Reference</H2>
<!-- Constructor -->
<P>
<CODE><B><I>void</I> search_replace(</B></CODE>
</P>
<PRE>
<CODE><B>
<I>string</I> find pattern,
<I>string</I> Replace pattern,
<I>mixed</I> File(s),
[<I>mixed</I> Directories,
<I>int</I> Include Subdirectories,
<I>array</I> Ignore Lines])
</B></CODE>
</PRE>
<P>
Being the constructor you shouldn't call this directly. The arguments are quite self explanatory,
the last three being optional.
</P>
<P>
When using regular expression (see set_search_function()) searching, the find argument is the entire
regex, so when using preg it should include the two delimiters and any modifiers you wish to use.
</P>
<P>
Files should be either a comma seperated string or array of files you want searched. If you specify
the directories argument the files argument can be left as a blank string. The directories argument
can also be a comma seperated string or an array.
</P>
<P>
The include subdirectories argument is optional, and
should be either 1 (one) or 0 (zero) depending on whether you want subdirectories to be included. This argument is
only relevant if you're using the directories argument.
</P>
<P>
The ignore_lines argument is useful if you wish lines beginning with a certain string to be ignored, but is only
supported by one search type (see below). This should be an array.
</P>
<!-- set_search_function -->
<P>
<CODE><B><I>bool</I> set_search_function(<I>string</I> search type)</B></CODE>
</P>
<P>
This sets the type of search function you wish to use. The argument should be one of the below (lowercase):
</P>
<P>
<I>normal</I><BR>
The default search function and the only one that supports the ignore_lines feature. This function
will go through each line and do the search/replace using str_replace(). Because it splits the file
on a newline (\n or ASCII 10), multiline search patterns are not supported.
</P>
<P>
<I>quick</I><BR>
Basically an enhancement of the default search function. Still uses str_replace(), but does not search
line by line, hence this is the quickest search feature. Does not support the ignore_lines feature.
</P>
<P>
<I>preg</I><BR>
Search and replace using preg_replace. The find pattern should be a valid preg_replace() search pattern,
including the delimiters and any modifiers. Does not support the ignore_lines feature.
</P>
<P>
<I>ereg</I><BR>
Search and replace using ereg_replace. The find pattern should be a valid ereg_replace() search pattern.
Does not support the ignore_lines feature.
</P>
<!-- do_search -->
<P>
<CODE><B><I>void</I> do_search(void)</B></CODE>
</P>
<P>
This starts the search. Obviously files will need to be writeable by the script.
</P>
<!-- get_num_occurences -->
<P>
<CODE><B><I>int</I> get_num_occurences(void)</B></CODE>
</P>
<P>
This returns the number of times the search pattern was found. If multiple files are searched,
this will be cumulative.
</P>
<!-- get_num_occurences -->
<P>
<CODE><B><I>string</I> get_last_error(void)</B></CODE>
</P>
<P>
This returns the last error if there is one.
</P>
<!-- set_find -->
<P>
<CODE><B><I>void</I> set_find(<I>string</I> find pattern)</B></CODE>
</P>
<P>
Accessor to set the find pattern.
</P>
<!-- set_replace -->
<P>
<CODE><B><I>void</I> set_replace(<I>string</I> replace string)</B></CODE>
</P>
<P>
Accessor to set the replace string.
</P>
<!-- set_files -->
<P>
<CODE><B><I>void</I> set_files(<I>mixed</I> file(s))</B></CODE>
</P>
<P>
Accessor to set the files to be parsed. Argument should be either a comma seperated string
or an array.
</P>
<!-- set_directories -->
<P>
<CODE><B><I>void</I> set_directories(<I>mixed</I> directories)</B></CODE>
</P>
<P>
Accessor to set the directories to be parsed. Argument should be either a comma seperated string
or an array.
</P>
<!-- set_include_subdir -->
<P>
<CODE><B><I>void</I> set_include_subdir(<I>int</I> include subdirs)</B></CODE>
</P>
<P>
Accessor to set whether sub-directories are parsed or not. Only used when directories are
to be parsed. Should be either 1 (one) or 0 (zero).
</P>
<!-- set_ignore_lines -->
<P>
<CODE><B><I>void</I> set_ignore_lines(<I>array</I> lines to ignore)</B></CODE>
</P>
<P>
Accessor to set whether sub-directories are parsed or not. Only used when directories are
to be parsed. Should be either 1 (one) or 0 (zero). Lines beginning with the strings provided
will not be searched.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>Bugs</H2>
<P>
Not bloody likely.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>History</H2>
<P>
<B>10/09/2000 - Version 1.0</B><BR>
Converted plain script to a class, added extra functionality and re-released.
</P>
<P>
<B>11/04/2000 - Version 0.9</B><BR>
Released as plain script.
</P>
</DIV>
<DIV CLASS="nocenter padding background-light border">
<H2>License</H2>
<P>
Postcard-ware. If you use this utility then I'd appreciate a postcard from ya. :)<BR>
Otherwise, it's free, be grateful, don't whinge, and don't sue me if it screws your system.
</P>
<P CLASS="center" ALIGN="CENTER">
<A HREF="http://validator.w3.org/check/referer">
<IMG SRC="http://validator.w3.org/images/vh40" BORDER="0" ALT="Valid HTML 4.0!" HEIGHT="31" WIDTH="88">
</A>
<A HREF="http://jigsaw.w3.org/css-validator/">
<IMG SRC="http://jigsaw.w3.org/css-validator/images/vcss.gif" BORDER="0" ALT="Valid CSS 1.0">
</A>
</P>
</DIV>
</BODY>
</HTML> |
Stumble It!
Bookmark in del.icio.us
Download
