ConfEditor Class Reference

This is a state machine style parser with two internal stacks: * A next state stack, which determines the state the machine will progress to next * A path stack, which keeps track of the logical location in the file. More...

List of all members.

Public Member Functions

 __construct ($text)
 Construct a new parser.
 edit ($ops)
 Edit the text.
 getVars ()
 Get the variables defined in the text.
 setVar (&$array, $path, $key, $value)
 Set a value in an array, unless it's set already.
 parseScalar ($str)
 Parse a scalar value in PHP.
 replaceSourceRegion ($start, $end, $newText=false)
 Replace the byte offset region of the source with $newText.
 findDeletionRegion ($pathName)
 Finds the source byte region which you would want to delete, if $pathName was to be deleted.
 findValueRegion ($pathName)
 Find the byte region in the source corresponding to the value part.
 findLastArrayElement ($path)
 Find the path name of the last element in the array.
 findFirstArrayElement ($path)
 getIndent ($pos, $key=false, $arrowPos=false)
 Get the indent string which sits after a given start position.
 parse ()
 Run the parser on the text.
 newTokenObj ($internalToken)
 Create a ConfEditorToken from an element of token_get_all().
 firstToken ()
 Reset the parse position.
 currentToken ()
 Get the current token.
 nextToken ()
 Advance the current position and return the resulting next token.
 getTokenAhead ($offset)
 Get the token $offset steps ahead of the current position.
 skipSpace ()
 Advances the current position past any whitespace or comments.
 expect ($type)
 Throws an error if the current token is not of the given type, and then advances to the next position.
 pushState ($nextState, $stateAfterThat=null)
 Push a state or two on to the state stack.
 popState ()
 Pop a state from the state stack.
 validatePath ($path)
 Returns true if the user input path is valid.
 endPath ()
 Internal function to update some things at the end of a path region.
 pushPath ($path)
 Go up to a new path level, for example at the start of an array.
 popPath ()
 Go down a path level, for example at the end of an array.
 nextPath ($path)
 Go to the next path on the same level.
 startPathValue ()
 Mark the start of the value part of a path.
 endPathValue ()
 Mark the end of the value part of a path.
 markComma ()
 Mark the comma separator in an array element.
 markArrow ()
 Mark the arrow separator in an associative array element.
 error ($msg)
 Generate a parse error.
 getTypeName ($type)
 Get a readable name for the given token type.
 isAhead ($type, $offset=0)
 Looks ahead to see if the given type is the next token type, starting from the current position plus the given offset.
 prevToken ()
 Get the previous token object.
 dumpTokens ()
 Echo a reasonably readable representation of the tokenizer array.

Static Public Member Functions

static test ($text)
 Simple entry point for command-line testing.

Public Attributes

 $text
 The text to parse.
 $tokens
 The token array from token_get_all().
 $pos
 The current position in the token array.
 $lineNum
 The current 1-based line number.
 $colNum
 The current 1-based column number.
 $byteNum
 The current 0-based byte number.
 $currentToken
 The current ConfEditorToken object.
 $prevToken
 The previous ConfEditorToken object.
 $stateStack
 The state machine stack.
 $pathStack
 The path stack is a stack of associative arrays with the following elements: name The name of top level of the path level The level (number of elements) of the path startByte The byte offset of the start of the path startToken The token offset of the start endByte The byte offset of thee endToken The token offset of the end, plus one valueStartToken The start token offset of the value part valueStartByte The start byte offset of the value part valueEndToken The end token offset of the value part, plus one valueEndByte The end byte offset of the value part, plus one nextArrayIndex The next numeric array index at this level hasComma True if the array element ends with a comma arrowByte The byte offset of the "=>", or false if there isn't one.
 $pathInfo
 The elements of the top of the pathStack for every path encountered, indexed by slash-separated path.
 $serial
 Next serial number for whitespace placeholder paths (-N).
 $edits
 Editor state.

Protected Member Functions

 initParse ()
 Initialise a parse.
 setPos ($pos)
 Set the parse position.


Detailed Description

This is a state machine style parser with two internal stacks: * A next state stack, which determines the state the machine will progress to next * A path stack, which keeps track of the logical location in the file.

Reference grammar:

file = T_OPEN_TAG *statement statement = T_VARIABLE "=" expression ";" expression = array / scalar / T_VARIABLE array = T_ARRAY "(" [ element *( "," element ) [ "," ] ] ")" element = assoc-element / expression assoc-element = scalar T_DOUBLE_ARROW expression scalar = T_LNUMBER / T_DNUMBER / T_STRING / T_CONSTANT_ENCAPSED_STRING

Definition at line 18 of file ConfEditor.php.


Constructor & Destructor Documentation

ConfEditor::__construct ( text  ) 

Construct a new parser.

Definition at line 101 of file ConfEditor.php.

References $text.


Member Function Documentation

ConfEditor::currentToken (  ) 

Get the current token.

Definition at line 749 of file ConfEditor.php.

Referenced by expect(), firstToken(), nextToken(), parse(), setPos(), and skipSpace().

ConfEditor::dumpTokens (  ) 

Echo a reasonably readable representation of the tokenizer array.

Definition at line 993 of file ConfEditor.php.

References $out, getTypeName(), and newTokenObj().

ConfEditor::edit ( ops  ) 

Edit the text.

Returns the edited text.

Parameters:
array $ops Array of operations.
Operations are given as an associative array, with members: type: One of delete, set, append or insert (required) path: The path to operate on (required) key: The array key to insert/append, with PHP quotes value: The value, with PHP quotes

delete Deletes an array element or statement with the specified path. e.g. array('type' => 'delete', 'path' => '$foo/bar/baz' ) is equivalent to the runtime PHP code: unset( $foo['bar']['baz'] );

set Sets the value of an array element. If the element doesn't exist, it is appended to the array. If it does exist, the value is set, with comments and indenting preserved.

append Appends a new element to the end of the array. Adds a trailing comma. e.g. array( 'type' => 'append', 'path', '$foo/bar', 'key' => 'baz', 'value' => "'x'" ) is like the PHP code: $foo['bar']['baz'] = 'x';

insert Insert a new element at the start of the array.

Definition at line 139 of file ConfEditor.php.

References $out, $path, findDeletionRegion(), findFirstArrayElement(), findLastArrayElement(), findValueRegion(), getIndent(), parse(), and replaceSourceRegion().

ConfEditor::endPath (  ) 

Internal function to update some things at the end of a path region.

Do not call except from popPath() or nextPath().

Definition at line 838 of file ConfEditor.php.

References $i, and $pathInfo.

Referenced by nextPath(), and popPath().

ConfEditor::endPathValue (  ) 

Mark the end of the value part of a path.

Definition at line 919 of file ConfEditor.php.

References $path.

Referenced by parse().

ConfEditor::error ( msg  ) 

Generate a parse error.

Definition at line 944 of file ConfEditor.php.

References $msg.

Referenced by expect(), and parse().

ConfEditor::expect ( type  ) 

Throws an error if the current token is not of the given type, and then advances to the next position.

Definition at line 800 of file ConfEditor.php.

References currentToken(), error(), getTypeName(), and nextToken().

Referenced by parse().

ConfEditor::findDeletionRegion ( pathName  ) 

Finds the source byte region which you would want to delete, if $pathName was to be deleted.

Includes the leading spaces and tabs, the trailing line break, and any comments in between.

Definition at line 371 of file ConfEditor.php.

References $path, firstToken(), getTokenAhead(), and nextToken().

Referenced by edit().

ConfEditor::findFirstArrayElement ( path  ) 

Definition at line 480 of file ConfEditor.php.

References $path.

Referenced by edit().

ConfEditor::findLastArrayElement ( path  ) 

Find the path name of the last element in the array.

If the array is empty, this will return the interstitial element. If the specified path is not found or is not an array, it will return false.

Definition at line 444 of file ConfEditor.php.

References $path.

Referenced by edit().

ConfEditor::findValueRegion ( pathName  ) 

Find the byte region in the source corresponding to the value part.

This includes the quotes, but does not include the trailing comma or semicolon.

The end position is the past-the-end (end + 1) value as per convention.

Definition at line 428 of file ConfEditor.php.

References $path.

Referenced by edit().

ConfEditor::firstToken (  ) 

Reset the parse position.

Definition at line 737 of file ConfEditor.php.

References currentToken(), ConfEditorToken::newEnd(), prevToken(), and setPos().

Referenced by findDeletionRegion(), initParse(), and parse().

ConfEditor::getIndent ( pos,
key = false,
arrowPos = false 
)

Get the indent string which sits after a given start position.

Returns false if the position is not at the start of the line.

Definition at line 504 of file ConfEditor.php.

References $pos.

Referenced by edit().

ConfEditor::getTokenAhead ( offset  ) 

Get the token $offset steps ahead of the current position.

$offset may be negative, to get tokens behind the current position.

Definition at line 777 of file ConfEditor.php.

References $pos, ConfEditorToken::newEnd(), and newTokenObj().

Referenced by findDeletionRegion(), and isAhead().

ConfEditor::getTypeName ( type  ) 

Get a readable name for the given token type.

Definition at line 951 of file ConfEditor.php.

Referenced by dumpTokens(), and expect().

ConfEditor::getVars (  ) 

Get the variables defined in the text.

Returns:
array( varname => value )

Definition at line 253 of file ConfEditor.php.

References $name, $path, parse(), parseScalar(), and setVar().

ConfEditor::initParse (  )  [protected]

Initialise a parse.

Definition at line 700 of file ConfEditor.php.

References firstToken().

Referenced by parse().

ConfEditor::isAhead ( type,
offset = 0 
)

Looks ahead to see if the given type is the next token type, starting from the current position plus the given offset.

Skips any intervening whitespace.

Definition at line 964 of file ConfEditor.php.

References getTokenAhead().

Referenced by parse().

ConfEditor::markArrow (  ) 

Mark the arrow separator in an associative array element.

Definition at line 936 of file ConfEditor.php.

References $path.

Referenced by parse().

ConfEditor::markComma (  ) 

Mark the comma separator in an array element.

Definition at line 928 of file ConfEditor.php.

References $path.

Referenced by parse().

ConfEditor::newTokenObj ( internalToken  ) 

Create a ConfEditorToken from an element of token_get_all().

Definition at line 726 of file ConfEditor.php.

Referenced by dumpTokens(), getTokenAhead(), and setPos().

ConfEditor::nextPath ( path  ) 

Go to the next path on the same level.

This ends the current path and starts a new one. If $path is , the new path is set to the next numeric array element.

Definition at line 884 of file ConfEditor.php.

References $i, $path, and endPath().

Referenced by parse().

ConfEditor::nextToken (  ) 

Advance the current position and return the resulting next token.

Definition at line 756 of file ConfEditor.php.

References $text, currentToken(), prevToken(), and setPos().

Referenced by expect(), findDeletionRegion(), parse(), and skipSpace().

ConfEditor::parse (  ) 

Run the parser on the text.

Throws an exception if the string does not match our defined subset of PHP syntax.

Definition at line 526 of file ConfEditor.php.

References $text, currentToken(), endPathValue(), error(), expect(), firstToken(), initParse(), isAhead(), markArrow(), markComma(), nextPath(), nextToken(), parseScalar(), popPath(), popState(), pushPath(), pushState(), skipSpace(), startPathValue(), and validatePath().

Referenced by edit(), and getVars().

ConfEditor::parseScalar ( str  ) 

Parse a scalar value in PHP.

Returns:
mixed Parsed value

Definition at line 306 of file ConfEditor.php.

Referenced by getVars(), and parse().

ConfEditor::popPath (  ) 

Go down a path level, for example at the end of an array.

Definition at line 874 of file ConfEditor.php.

References endPath().

Referenced by parse().

ConfEditor::popState (  ) 

Pop a state from the state stack.

Definition at line 822 of file ConfEditor.php.

Referenced by parse().

ConfEditor::prevToken (  ) 

Get the previous token object.

Definition at line 986 of file ConfEditor.php.

Referenced by firstToken(), and nextToken().

ConfEditor::pushPath ( path  ) 

Go up to a new path level, for example at the start of an array.

Definition at line 855 of file ConfEditor.php.

References $path.

Referenced by parse().

ConfEditor::pushState ( nextState,
stateAfterThat = null 
)

Push a state or two on to the state stack.

Definition at line 812 of file ConfEditor.php.

Referenced by parse().

ConfEditor::replaceSourceRegion ( start,
end,
newText = false 
)

Replace the byte offset region of the source with $newText.

Works by adding elements to the $this->edits array.

Definition at line 335 of file ConfEditor.php.

References $i.

Referenced by edit().

ConfEditor::setPos ( pos  )  [protected]

Set the parse position.

Do not call this except from firstToken() and nextToken(), there is more to update than just the position.

Definition at line 713 of file ConfEditor.php.

References $pos, currentToken(), ConfEditorToken::newEnd(), and newTokenObj().

Referenced by firstToken(), and nextToken().

ConfEditor::setVar ( &$  array,
path,
key,
value 
)

Set a value in an array, unless it's set already.

For instance, setVar( $arr, 'foo/bar', 'baz', 3 ); will set $arr['foo']['bar']['baz'] = 3;

Parameters:
$array array
$path string slash-delimited path
$key mixed Key
$value mixed Value

Definition at line 288 of file ConfEditor.php.

References $path.

Referenced by getVars().

ConfEditor::skipSpace (  ) 

Advances the current position past any whitespace or comments.

Definition at line 789 of file ConfEditor.php.

References currentToken(), and nextToken().

Referenced by parse().

ConfEditor::startPathValue (  ) 

Mark the start of the value part of a path.

Definition at line 910 of file ConfEditor.php.

References $path.

Referenced by parse().

static ConfEditor::test ( text  )  [static]

Simple entry point for command-line testing.

Definition at line 88 of file ConfEditor.php.

References $text, and ConfEditorParseError::highlight().

ConfEditor::validatePath ( path  ) 

Returns true if the user input path is valid.

This exists to allow "/" and "@" to be reserved for string path keys

Definition at line 830 of file ConfEditor.php.

References $path.

Referenced by parse().


Member Data Documentation

ConfEditor::$byteNum

The current 0-based byte number.

Definition at line 35 of file ConfEditor.php.

ConfEditor::$colNum

The current 1-based column number.

Definition at line 32 of file ConfEditor.php.

ConfEditor::$currentToken

The current ConfEditorToken object.

Definition at line 38 of file ConfEditor.php.

ConfEditor::$edits

Editor state.

This consists of the internal copy/insert operations which are applied to the source string to obtain the destination string.

Definition at line 83 of file ConfEditor.php.

ConfEditor::$lineNum

The current 1-based line number.

Definition at line 29 of file ConfEditor.php.

ConfEditor::$pathInfo

The elements of the top of the pathStack for every path encountered, indexed by slash-separated path.

Definition at line 72 of file ConfEditor.php.

Referenced by endPath().

ConfEditor::$pathStack

The path stack is a stack of associative arrays with the following elements: name The name of top level of the path level The level (number of elements) of the path startByte The byte offset of the start of the path startToken The token offset of the start endByte The byte offset of thee endToken The token offset of the end, plus one valueStartToken The start token offset of the value part valueStartByte The start byte offset of the value part valueEndToken The end token offset of the value part, plus one valueEndByte The end byte offset of the value part, plus one nextArrayIndex The next numeric array index at this level hasComma True if the array element ends with a comma arrowByte The byte offset of the "=>", or false if there isn't one.

Definition at line 66 of file ConfEditor.php.

ConfEditor::$pos

The current position in the token array.

Definition at line 26 of file ConfEditor.php.

Referenced by getIndent(), getTokenAhead(), and setPos().

ConfEditor::$prevToken

The previous ConfEditorToken object.

Definition at line 41 of file ConfEditor.php.

ConfEditor::$serial

Next serial number for whitespace placeholder paths (-N).

Definition at line 77 of file ConfEditor.php.

ConfEditor::$stateStack

The state machine stack.

This is an array of strings where the topmost element will be popped off and become the next parser state.

Definition at line 47 of file ConfEditor.php.

ConfEditor::$text

The text to parse.

Definition at line 20 of file ConfEditor.php.

Referenced by __construct(), nextToken(), parse(), and test().

ConfEditor::$tokens

The token array from token_get_all().

Definition at line 23 of file ConfEditor.php.


The documentation for this class was generated from the following file:

Generated on Sat Apr 30 22:57:34 2011 for MediaWiki by  doxygen 1.5.9