Class: File_Therion

Use this to create a new interface for parsing existing files or writing new ones.

The $filename tells the physical file name of the file. Use fetch() if you want to read the source contents or write() to write the current content to the target.

Example:

 $thFile = new File_Therion('foobar.th'); // local file (r/w access)

 $thFile->fetch();  // get contents
 $thFile->updateObjects();  // parse fetched contents
 $surveys = $thFile->getObjects('File_Therion_Survey'); // get surveys
 $all = $thFile->getObjects(); // get all parsed objects

Parameters:

The formatters will be called in the order they were added.

Parameters:

The optional index parameter allows to adjust the insertion point; the line will be inserted at the index, pushing already present content one line down (-1=end, 0=start, ...). When replacing, the selected index will be replaced.

Instead of $index 0 and -1 you can use the strings 'start'/'end', this will make your code more readable. Using

addLine(..., $lln - 1)

Beware that clearLines() will discard any manual insertions. Also be aware that fetch() will clean the line buffer too.

Note that addLine() will not take care of wrapping; make sure that the line content remains consistent.

Be sure to use the correct encoding for your data (-> setEncoding() and encode() for more details).

Example:

 // add a simple line (implicitely to the end):

 $th->addLine(new File_Therion_Line("somecontent"));
 
 // add a line to the start, pushing previous line one down:
 $th->addLine(new File_Therion_Line("startline"), 0);
 // result: line-0="startline", line-1="somecontent"
 
 // add another simple line (explicitely to the end):
 $th->addLine(new File_Therion_Line("final"), 'end');
 // result: line-0="startline", line-1="somecontent", line-3="final"
 
 // replace line-1:
 $th->addLine(new File_Therion_Line("othercontent"), 1, true);
 // result: line-0="startline", line-1="othercontent", line-3="final"

Instead of Line objects you may also add a string as $line argument. In this case a new Line object will be parsed for you. Right spaces and newline will be trimmed.

Note that the lines content is expected to be already encoded in the current files encoding. If the codesets differ, encode them first. See encode() for encoding or use phps own functions.

Parameters:

Associated objects can be written to a file after updateLines() has been called to update the internal line representation.

Be aware that clearObjects() will discard any manual changes made so far, and be warned that updateObjects() will clean them too.

Parameters:

This validates basic syntax of internal file buffer. The following checks will be performed:

• last line should not expect additional data
• matching multiline commands

Parameters:

This will wipe out the internal line buffer.

This will unassociate all registered objects. You probably want to call clearLines() hereafter to also clean the calculated line content.

returns the count of physical (ie. wrapped) lines in this file. To count logical lines (ie. unwrapped, or line objects), use $logical.

Parameters:

Will check if target-encoding is supported by therion.

If $strictCheck is set to TRUE, the from encoding will also be verified against supported therion encodings. Use this in case the source encoding is a known therion file.

Parameters:

Therions 'input' statement will include the remote file content at the place of the 'input <filename>' therion command.

This will try to interpret the given filepath in local context; the input-parameter is always a filepath in a filesystem. When the filename has no extension, ".th" is assumed.

For actually fetching the content, the currently associated File_Therion_Reader implementation will be used (see setReader()). With the default FileReader this means that we will assume the filename to be relative to the local file on a local mounted disk.

Please note that referenced files will be converted to the parent file encoding (all 'input' content is encoded to this files codeset).

To limit the number of possible nested levels you may specify the $lvls parameter:

• null: endless recursion (default)
• 0: no input
• 1: only local inputs
• >1: nested levels

Parameters:

This will order the lines passed into a nested array sorting the lines belonging together into subarrays collected under a common tag.

The first level contains all "seen" tags like surveys. There all survey lines will be collected and ordered into their own array. The special 'LOCAL' array kay holds all lines that where not enclosed into their own contect and are therefore considered "local".

Nested structures (like they are ancountered with surveys) need to be resolved with consecutive calls to this method. The structure holds all the lines of the first levels, so eg. in case of nested structures there will be all lines of the outermost survey command

The structure will look like this:

 array(

      'LOCAL'  => array(local lines without own context)
      'survey' => array(
                      array(lines-of-survey-1),
                      array(lines-of-survey-2),
      'centreline' => array(
                          array(lines-of-centreline-1),
                          array(lines-of-centreline-2),
      ...

Parameters:

This will use the supplied Reader to fetch therion file content. If no Reader was supplied (NULL/missing value), the internal default reader will be used (File_Therion_FileReader). The supplied reader will be also used for subsequent reads, like when resolving input commands.

Be aware that the Reader usually clears the internal line buffer, so any changes made by addLine() get discarded. Please refer to the readers documentation if you want to avoid this.

After fetching physical content, you may call updateObjects() to generate Therion data model objects out of it. (Some Reader implementeations may already do this for you!)

Parameters:

Parameters:

Example:

 $allObjects = $thFile->getObjects(); // get all

Note that this kind of object is usually not "lone" in a file but commonly part of a survey. This function returns only "lone" objects without parent structure.

Example:

 $allCentrelines = $thFile->getCentrelines();

Parameters:

The lines will be formatted using the registered formatters (see addFormatter()).

On each consecutive run of getLines() the formatters will be reapplied. This may yield strange results. If you want to format just once, {link removeFormatters()} after formatting was applied.

Note that this kind of object is usually not "lone" in a file but commonly part of a survey. This function returns only "lone" objects without parent structure.

Example:

 $allMaps = $thFile->getMaps();

You can optionaly query for specific types using $filter. You may ommit the prefix 'File_Therion_' from the filter.

Example:

 $allObjects = $thFile->getObjects(); // get all

 $surveys    = $thFile->getObjects('File_Therion_Survey'); // get surveys
 $surveys    = $thFile->getObjects('Survey'); // get surveys

Parameters:

Note that this kind of object is usually not "lone" in a file but commonly part of a survey. This function returns only "lone" objects without parent structure.

Example:

 $allScraps = $thFile->getScraps();

Note that this kind of object is usually not "lone" in a file but commonly part of a survey. This function returns only "lone" objects without parent structure.

Example:

 $allSurfaces = $thFile->getSurfaces();

Example:

 $allSurveys = $thFile->getSurveys();

This will perform the following operations:

• create a new File_Therion object pointing to the datasource given
• fetch() the datasource
• evalInputCMD() optionally import referenced content ($lvls > 0)
• updateObjects() represented by the lines

To limit the number of possible nested levels you may specify the $recurse parameter (null=default: endless, 0: none, >0: nested levels).

Please read also the documentation of fetch(), evalInputCMD() and updateObjects() for informations on their respective capabilitys and pitfalls.

Parameters:

This will tell what encoding to use.

This method only signals which encoding the data should be in and will not actively change encoding. Make sure your data matches the encoding given!

Only a small subset of PHP encoding names are supported by therion, see $_supportedEncodings for a list.

When NULL is given, the current encoding will be reset to "unknown".

Parameters:

This will just change the path, no data will be read/written!

Parameters:

Parameters:

Parameters:

Returns the file line content as string, suitable for writing using PHPs fwrite().

The actual content can optionally be formatted by adding File_Therion_Formatter instances with addFormatter(). This can influence line endings and wrapping for instance.

By default, the line ending used is depending on the current PHP_EOL constant. No wrapping will occur, unless the internal lines have such wrapping.

This will generate therion file lines out of the associated objects. Be aware that this will clear already existing line content!

You may use fetch() to update the internal line buffer with real physical content from the datasource. Alternatively you can craft the file yourself using addLine().

Be aware that this function cleans all references to associated objects.

The writing will be carried out by the supplied writer object. If no writer was supplied, a new DirectWriter will be instantiated as default.

Parameters:

Parameters: