Zend Framework: Zend_Syntax Component Proposal

Proposed Component Name	Zend_Syntax
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Syntax
Proposers	My E-mail Address
Revision	1.1 - 16 Feb 2008: Created. (wiki revision: 12)

Milestone 1: Prototype robust flexible non cumbersome parsing and markup process
Milestone 2: Finalize naming conventions & Revisions based on community input
Milestone 3: Working prototype checked into the incubator when requirements are met.
Milestone 4: Unit tests exist, work, and are checked into SVN.
Milestone 5: Initial documentation exists.

7. Class Index

Zend_Syntax_Highlight
Zend_Syntax_Highlight_Definition
Zend_Syntax_Highlight_TokenList
Zend_Syntax_Highlight_Token
Zend_Syntax_Highlight_State
Zend_Syntax_Highlight_Keyword

8. Use Cases

UC-01

usage

<?php
	/**
	 * Trivial Test Case
	 * Grammar Highlighting
	 */
	require_once "Zend/Controller/Action.php";
	require_once "Zend/Syntax/Highlight.php";
	require_once 'Zend/Syntax/Highlight/Keyword.php';
	
	# Common Controller 
	class IndexController extends Zend_Controller_Action {
		protected $nouns = array('fox', 'dog');
		protected $verbs = array('jumps');
		protected $adjectives = array('quick', 'lazy', 'brown');
		
		# Common Action
		public function indexAction() {
			# Create a default definition
			$def =  new Zend_Syntax_Highlight_Definition();
			
			# Register noun keywords
			foreach($this->nouns as $n) {
				# Create new keyword state 
				$state = new Zend_Syntax_Highlight_Keyword($n);
				# what the state will be named (for view usage)
				$state->setName('noun');
				# add state to definition
				$def->addState($state);
			}
			# Register verb keywords
			foreach($this->verbs as $v) {
				# Create new keyword state
				$state = new Zend_Syntax_Highlight_Keyword($v);
				# what the state will be named (for view usage)
				$state->setName('verb');
				# add state to definition
				$def->addState($state);
			}
			# Register adjective keywords
			foreach($this->adjectives as $a) {
				# Create new keyword state
				$state = new Zend_Syntax_Highlight_Keyword($a);
				# what the state will be named (for view usage)
				$state->setName('adjective');
				# add state to definition
				$def->addState($state);
			}

			# Instantiate a new Zend Syntax Highlighter using our custom definition
			$syntax = new Zend_Syntax_Highlight($def ); 
			# Parse syntax and add highlighting
			$markup = $syntax->highlight("The quick brown fox jumps over the lazy dog.");
			# render our marked up syntax!
			echo $markup;
		}
	}
?>

Controller Action View

<style type='text/css'>
	.keyword { text-decoration: underline; }
	.noun { color: blue; }
	.verb { color: red; }
	.adjective { color: green; }
</style>

output

<style type='text/css'>
	.keyword { text-decoration: underline; }
	.noun { color: blue; }
	.verb { color: red; }
	.adjective { color: green; }
</style>
The <span class='Keyword adjective'>quick</span> <span class='Keyword adjective'>brown</span> <span class='Keyword noun'>fox</span> <span class='Keyword verb'>jumps</span> over the <span class='Keyword adjective'>lazy</span> <span class='Keyword noun'>dog</span>.

9. Class Skeletons

/**
	 * Zend_Syntax_Highlight Component
	 *
	 */
	class Zend_Syntax_Highlight {
		protected $definition = null;
		protected $activeState = null;
                  
                  public function __construct(Zend_Syntax_Highlight_Definition $definition);
		/**
		 * Highlight syntax source code
		 *
		 * @param string $syntax
		 * @return string
		 */
                  public function highlight($syntax_source);
          }

	/**
	 * Definition manages all states for a syntax language
	 *
	 */
	class Zend_Syntax_Highlight_Definition {
		protected $states = array();
		protected $view;
		
		public function __construct();
		
		/**
		 * Set the Zend_View Object that will be used to render scripts
		 *
		 * @param Zend_View $view
		 */
		public function setView(Zend_View $view);
		
		/**
		 * Get the Zend_View object to render scripts with
		 *
		 * @return Zend_View
		 */
		public function getView();
		
		/**
		 * Return token list from the source data
		 * Different definitions may tokenize text in different ways (by character, by space, etc)
		 *
		 * @param string $data
		 * @return TokenList
		 */
		public function tokenize($data);
		
		/**
		 * Add a state to this definition
		 *
		 * @param Zend_Syntax_Highlight_State $state
		 */
		public function addState(Zend_Syntax_Highlight_State $state);
		
		/**
		 * Get all the states for this definition
		 *
		 * @return array
		 */
		public function getStates();
	}

	/**
	 * Token manager 
	 *
	 */
	class Zend_Syntax_Highlight_TokenList {
		protected $list = null;
		
		public function __construct($raw_list);
		
		/**
		 * Get the token at $index position
		 *
		 * @param integer $index
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getToken($index);

		/**
		 * Get the first token
		 *
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getFirstToken();
		
		/**
		 * Get the Last Token
		 *
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getLastToken();
		
		/**
		 * Get the next token from $index positon
		 *
		 * @param integer $current_index
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getNextToken($current_index);
		
		/**
		 * Get the previous token from $index position
		 *
		 * @param integer $current_index
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getPreviousToken($current_index);
		
		/**
		 * Get the array of Zend_Syntax_Highlight_Token tokens
		 *
		 * @return array
		 */
		public function getTokens();
		
		/**
		 * Get number of tokens in list
		 *
		 * @return integer
		 */
		public function getTokenCount();
		
		/**
		 * Return subset of tokens 
		 *
		 * @param integer $offset
		 * @param integer $length
		 * @return array
		 */
		public function getTokenRange($offset, $length);
		
		/**
		 * Return a string value of a subset of tokens
		 *
		 * @param integer $offset
		 * @param integer $length
		 * @return array
		 */
		public function getTokenRangeString($offset, $length);
	}

<?php
	require_once "Zend/Syntax/Highlight/TokenList.php";

	/**
	 * Token - base syntax chunk of data
	 *
	 */
	class Zend_Syntax_Highlight_Token {
		protected $data = null;
		protected $index = null;
		protected $list = null;
		
		/**
		 * Create a new token storing token data, the index in the token list and a pointer to the list it belongs
		 *
		 * @param string $data
		 * @param integer $index
		 * @param Zend_Syntax_Highlight_TokenList $list
		 */
		public function __construct($data, $index, $list);
		
		/**
		 * Compare Token Data with Data
		 *
		 * @param char $data
		 * @param boolean $caseSensitive
		 * @return boolean
		 */
		public function eq($data, $caseSensitive = false);
		
		/**
		 * Get this Token data
		 *
		 * @return string
		 */
		public function getData();
		
		/**
		 * Get token Index
		 *
		 * @return integer
		 */
		public function getIndex() {
			return $this->index;
		}
		
		public function getList();
		
		/**
		 * Get next token in list
		 *
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getNextToken();
		
		/**
		 * Get previous token in list
		 *
		 * @return Zend_Syntax_Highlight_Token
		 */
		public function getPrevToken();
		
		public function __toString();
	}

	/**
	 * Interface for Highlight States
	 *
	 */
	interface Zend_Syntax_Highlight_State {
		/**
		 * Check if token begins a new highlight state
		 *
		 * @param Zend_Syntax_Highlight_Token $token
		 */
		public function isBeginningOfState(Zend_Syntax_Highlight_Token $token);
		/**
		 * Check if token ends a highlight state
		 *
		 * @param Zend_Syntax_Highlight_Token $token
		 */
		public function isEndOfState(Zend_Syntax_Highlight_Token $token);
		/**
		 * State becomes active event handler
		 *
		 * @param Zend_Syntax_Highlight_Token $token
		 */
		public function begin(Zend_Syntax_Highlight_Token $token);
		/**
		 * State is active event handler
		 *
		 * @param Zend_Syntax_Highlight_Token $token
		 */
		public function during(Zend_Syntax_Highlight_Token $token);
		/**
		 * State deactivates event handler
		 *
		 * @param Zend_Syntax_Highlight_Token $token
		 */
		public function end(Zend_Syntax_Highlight_Token $token);
		/**
		 * Get the script used to view this state
		 *
		 * @return string
		 */
		public function getViewScript();
		/**
		 * Get the type of state (base class)
		 *
		 * @return string
		 */
		public function getType();
		/**
		 * Get the name of the state (arbitrarily assigned)
		 * 
		 * @return string
		 */
		public function getName();
	}

	/**
	 * Simple State for single keyword Highlighting
	 * @todo This is a trivial example a better class would be Keywords
	 * @todo so once class highlights multiple words rather than a class per word
	 *
	 */
	class Zend_Syntax_Highlight_Keyword implements Zend_Syntax_Highlight_State {
		protected $word;
		protected $begin;
		protected $script = 'span.html';
		protected $name = 'keyword';
		
		public function __construct($word);
		
		# check if state begins
		public function isBeginningOfState(Zend_Syntax_Highlight_Token $token);
		
		#check if state ends
		public function isEndOfState(Zend_Syntax_Highlight_Token $token);
		
		# save information for end testing
		public function begin(Zend_Syntax_Highlight_Token $token);
		
		# do nothing while state is active
		public function during(Zend_Syntax_Highlight_Token $token);
		
		# do nothing when state end
		public function end(Zend_Syntax_Highlight_Token $token);
		
		# set view script
		public function setViewScript($script)
		
		# get view script
		public function getViewScript();
		
		# get the type of state this is
		final public function getType();
		
		# set the state name
		public function getName();
		
		#get the state name
		public function setName($name);
	}

?>

Default view script to be used for syntax definitions will be located in Zend/Syntax/Highlight/Scripts/

#span.phtml
<span class='<?=$this->state_type?> <?=$this->state_name?>'><?=$this->state_source?></span>

#bbcode.phtml
[font class='<?=$this->state_type?> <?=$this->state_name?>']<?=$this->state_source?>[/font]

#wiki.phtml
{span:class="<?=$this->state_type?> <?=$this->state_name?>"}
<?=$this->state_source?>
{span}
#etc

Name	Size	Creator (Last Modifier)	Creation Date	Last Mod Date	Comment
Chunk.php	9 kb	Jeremy Giberson	Feb 16, 2008	Feb 16, 2008	Zend_Syntax_State_Chunk class for matching word types (hex, metrics, etc)
Highlight.php	3 kb	Jeremy Giberson	Mar 28, 2008	Mar 28, 2008
Keyword.php	2 kb	Jeremy Giberson (modified by Jeremy Giberson)	Feb 16, 2008	Mar 28, 2008
Simple.php	4 kb	Jeremy Giberson	Feb 16, 2008	Feb 16, 2008	Zend_Syntax_State_Simple class for matching enclosed content by tags
Keywords.php	0.3 kb	Jeremy Giberson	Feb 16, 2008	Feb 16, 2008	Zend_Syntax_Definition_Keywords class demo definition for simple keyword matching
TextPad.php	5 kb	Jeremy Giberson	Feb 16, 2008	Feb 16, 2008	Zend_Syntax_Definition_TexPad class Demo definition for supporting TextPad syn files
TokenList.php	2 kb	Jeremy Giberson (modified by Jeremy Giberson)	Feb 16, 2008	Mar 28, 2008
Syntax.php	1 kb	Jeremy Giberson	Feb 16, 2008	Feb 16, 2008	Zend_Syntax component class
Definition.php	1 kb	Jeremy Giberson (modified by Jeremy Giberson)	Feb 16, 2008	Mar 28, 2008
Exception.php	0.1 kb	Jeremy Giberson	Feb 16, 2008	Feb 16, 2008	Zend_Syntax_Exception class
State.php	1 kb	Jeremy Giberson (modified by Jeremy Giberson)	Feb 16, 2008	Mar 28, 2008
Token.php	2 kb	Jeremy Giberson (modified by Jeremy Giberson)	Feb 16, 2008	Mar 28, 2008

Page Operations

Browse Space

Zend_Syntax_Highlight

Labels

Zend Framework: Zend_Syntax Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons