File_Therion
[ class tree: File_Therion ] [ index: File_Therion ] [ all elements ]

Class: File_Therion_Line

Source Location: /File_Therion-0.4.1/File/Therion/Line.php

Class Overview


A single logical line of a Therion file.


Author(s):

Copyright:

  • 2016 Benedikt Hallinger

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 33]
A single logical line of a Therion file.

This class implements the basic file syntax and represent a single logical line of such a file. Therion files may be wrapped (a logically signle line can be wrapped into several physical lines); this class helps to deal with that.

The exact format is specified in the therion documentation, please refer to http://therion.speleo.sk/downloads/thbook.pdf, page 12).



[ Top ]


Class Variables

$_content = array()

[line 49]

Line content.

The internal data structure of the line is an array containing at least one associative array: 'intend' => detected intend characters 'data' => payload of the line 'comment' => comment of the line 'wrapped' => true, if the line expects additional content in the next physical line

  • Var: of data
  • Access: protected

Type:   array


[ Top ]

$_eol =  PHP_EOL

[line 61]

Default line ending character
  • Access: protected

Type:   mixed


[ Top ]

$_out_std_commentSep =  "\t"

[line 56]

Standard output separator for comment.
  • Access: protected

Type:   string


[ Top ]



Method Detail

__construct (Constructor)   [line 78]

File_Therion_Line __construct( string|array $data, [string $comment = ''], [string $indent = ''])

Create a new therion line object.

Data may be given in two forms:

  • string: line data will be used as given (like from file)
  • array: interpreted as array returned by getDatafields()
Be sure to escape values in string mode properly.

  • Throws: InvalidArgumentException
  • Access: public

Parameters:

string|array   $data   —  data of the line
string   $comment   —  comment of the line
string   $indent   —  intent characters

[ Top ]

addData   [line 157]

void addData( string $indent, string $data, string $comment)

Add internal data to stack.
  • Throws: InvalidArgumentException
  • Throws: File_Therion_SyntaxException in case the Line did not expect additional wrapped content
  • Access: protected

Parameters:

string   $data   —  data string of the line
string   $comment   —  comment of the line
string   $indent   —  intent characters

[ Top ]

addPhysicalLine   [line 132]

void addPhysicalLine( string|File_Therion_Line $line)

Add a physical Therion line as wrapped into its contents.
  • Throws: InvalidArgumentException
  • Throws: File_Therion_SyntaxException in case the Line did not expect additional wrapped content
  • Access: public

Parameters:

string|File_Therion_Line   $line   —  physical line or Line object

[ Top ]

changeEOL   [line 732]

void changeEOL( string $eol)

Change default End-of-Line characters of string representation.

The default EOL is PHP_EOL, eg. the local platform EOL.

Use this to change the EOL character to an platform dependant char sequence; for example to generate windows files from linux.

  • Access: public

Parameters:

string   $eol   —  EOL sequence (be sure to get the escaping right)

[ Top ]

checkSyntax_keyword   [line 782]

boolean checkSyntax_keyword( string $subject, [boolean $extended = false])

Check syntax on Therion keywords.

Therion keywords are a sequence of A-Z, a-z, 0-9 and _-/ characters (not starting with ‘-’). Extended keyword can also contain +*.,' characters, but not on the first position.

  • Access: public

Parameters:

string   $subject   —  String to check
boolean   $extended   —  TRUE to enable check on "extended keyword"

[ Top ]

count   [line 717]

int count( )

Count (wrapped) lines in this line (SPL Countable).

returns the raw value of lines. Ususally 1, however if the line contains wrapped data, it will return the 'true' count of those lines as they would appear in a textual representation.

  • Return: number of raw lines
  • Access: public

[ Top ]

escape   [line 466]

string|array escape( string|array $value)

Escapes one or more datafields for proper therion syntax.

This will escape and quote datafields properly, so the can be put into a file for writing.

Escaping and quoting rules are described in the therion book at p. 12.

When passed an array (like from getDatafields(), an array will be returned with each value escaped separately.

  • Return: with escaped/quoted values
  • Todo: []-escaping is also used for keywords with spaces; the are not yet supported
  • Access: public

Parameters:

string|array   $value   —  string or array to escape

[ Top ]

expectMoreLines   [line 222]

void expectMoreLines( [boolean $yesno = true])

Let the Line know that it should expect an additional wrapped line.

Do not confuse this with isContinued()!

  • Access: public

Parameters:

boolean   $yesno   —  set to false to explicitely revert

[ Top ]

extractOptions   [line 384]

array extractOptions( [boolean $inverse = false])

Extract options given to a command in this line.

Returns associative array of set options with key=option. The value is an array containing the values whose items can have the following forms:

  • empty string with no arguments
  • string when one argument was given
  • array with strings with multiple arguments
When an option is given more than once, value(s) will be appended to the already existing key like described above.

If inverting is selected, the fields that are non options are returned as indexed array in order of appearance.

Example:

  1.  //Line = 'survey foo -title "bar foo passage"'
  2.  $options $line->extractOptions();
  3.  print $options['title']// -> array("bar foo passage")
  4.  
  5.  //Line = 'scrap bar -author 2016 "Some One"'
  6.  $options $line->extractOptions();
  7.  print $options['author']// -> array(array("2016", "Some One"))
  8.  
  9.  //Line = 'scrap bar -author 2016 "Some One" -author "Someone Else"'
  10.  $options $line->extractOptions();
  11.  print $options['author']// -> array(array("2016", "Some One"), "Someone Else")
  12.  
  13.  //Inverting, that is filter out options
  14.  //Line = 'survey foo -title "bar foo passage"'
  15.  $options $line->extractOptions(true);
  16.  print_r($options)// -> array("survey", "foo")

  • Throws: File_Therion_SyntaxException in case of missing option arguments
  • Access: public

Parameters:

boolean   $inverse   —  when true, returns non-options datafields

[ Top ]

filterNonEmpty   [line 752]

int filterNonEmpty( array $arrayToCount)

Filter empty Therion data lines out of array.

Returns the lines that are not only commentary or empty; that is: lines with real content.

  • Throws: InvalidArgumentException in case element is not a line object
  • Access: public

Parameters:

array   $arrayToCount   — 

[ Top ]

getComment   [line 528]

string getComment( [string $ml_sep = '; '])

Returns the unwrapped comment as string.

Comments of wrapped lines will be joined.

  • Return: comment part of the unwrapped line
  • Access: public

Parameters:

string   $ml_sep   —  Separator used for joining multiline

[ Top ]

getContent   [line 243]

string getContent( )

Returns the unwrapped data-content as string.

Comments and indenting will be stripped

  • Return: data part of the unwrapped line
  • Access: public

[ Top ]

getDatafields   [line 269]

array getDatafields( )

Returns the data part of the line as array.

Each distinct value will form one array index. With single line therion commands the command will be naturally at i=0, whereas with multiline commands there will usually just be data.

Unescaping will be performed, so each array entry has only valid data suitable for proper processing.

If the line is empty (ie it has the empty string as content), an empty array will be returned.

  • See: escape() for escaping rules as per therion book
  • Throws: File_Therion_SyntaxException in case of quoting errors of this Line
  • Access: public

[ Top ]

getIndent   [line 548]

string getIndent( )

Returns the indenting characters.

In case this line contains wrapped content, the indenting of the first physical line will be used.

  • Access: public

[ Top ]

isCommentOnly   [line 596]

boolean isCommentOnly( )

Say if this is just a comment or empty line.
  • Access: public

[ Top ]

isContinuation   [line 640]

boolean isContinuation( $priorLine, File_Therion_Line|array $priorLines, File_Therion_Line $line)

Detect if the line is a continuation of a wrapped one.

This cannot be derived from the current line. The current line can be expected to be a continuation in case the preceeding line expects more content (that it does not contian itself), eg it was endet with an backslash. Such lines may be consolidatet into one single Therion_Line object using addPhysicalLine() on the prior line with the inspected one as parameter: '

  1. $priorLine->addPhysicalLine($thisOne)
'.

  • Return: true in case of continuation
  • Access: public

Parameters:

File_Therion_Line|array   $priorLines   —  array of prior lines
File_Therion_Line   $line   —  current line to test
   $priorLine   — 

[ Top ]

isContinued   [line 609]

boolean isContinued( )

Detect if this Line expects wrapped content in the following physical line.
  • Access: public

[ Top ]

isWrapped   [line 620]

boolean isWrapped( )

Detect if this logical Line contains wrapped physical data.
  • Access: public

[ Top ]

parse   [line 104]

File_Therion_Line parse( string $line)

Parse a physical Therion line into its contents.
  • Return: object
  • Throws: File_Therion_SyntaxException in case of syntax error
  • Access: public

Parameters:

string   $line   —  physical line

[ Top ]

setCommentSeparator   [line 673]

void setCommentSeparator( string $separator)

Set separator for appending comments to datalines in output (toString().
  • Access: public

Parameters:

string   $separator   — 

[ Top ]

setContent   [line 699]

void setContent( string $data)

Set payload of the line.

This reverts the line to consist of a single line with the payload. The indentation and comment stay intact.

  • Access: public

Parameters:

string   $data   — 

[ Top ]

setIndent   [line 685]

void setIndent( string $indent)

Set indenting for output (toString().
  • Access: public

Parameters:

string   $indent   — 

[ Top ]

toLines   [line 586]

void toLines( )

Return this line as object.

This is mainly useful for internal processing when lines of subobjects are requested in bulk.

  • Access: public

[ Top ]

toString   [line 561]

string toString( )

Returns the whole line as String.

Comments will be added using a single tabulator by default. Line ending is the current value of PHP_EOL (NEWLINE on *NIX).

  • Access: public

[ Top ]

unescape   [line 500]

string|array unescape( string|array $value)

Unescapes one or more datafields for proper processing in PHP.

This will undo the escaping and quoting performed by escape().

  • Return: with unescaped/unquoted values
  • Access: public

Parameters:

string|array   $value   —  string or array to unescape

[ Top ]

__toString   [line 575]

void __toString( )

Magic __toString() method calls toString().
  • Access: public

[ Top ]


Documentation generated on Mon, 11 Mar 2019 15:09:45 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.