Skip to content

Commit

Permalink
Merge pull request richthegeek#151 from lochmueller/documentation
Browse files Browse the repository at this point in the history 
Documentation PhpDoc
  • Loading branch information
@richthegeek
richthegeek committed Apr 23, 2014
2 parents f7c7242 + 8116914 commit 9519bf9
Show file tree
Hide file tree
Showing 45 changed files with 347 additions and 314 deletions.
7 changes: 3 additions & 4 deletions SassException.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,10 @@ class SassException extends Exception
{
/**
* Sass Exception.
* @param string Exception message
* @param array parameters to be applied to the message using <code>strtr</code>.
* @param object object with source code and meta data
* @param string $message Exception message
* @param object $object object with source code and meta data
*/
public function __construct($message, $object = NULL)
public function __construct($message, $object)
{
parent::__construct($message . (is_object($object) ? ": {$object->filename}::{$object->line}\nSource: {$object->source}" : ''));
}
Expand Down
41 changes: 21 additions & 20 deletions SassFile.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ class SassFile

/**
* Returns the parse tree for a file.
* @param string filename to parse
* @param SassParser Sass parser
* @param string $filename filename to parse
* @param SassParser $parser Sass parser
* @return SassRootNode
*/
public static function get_tree($filename, &$parser)
Expand Down Expand Up @@ -93,8 +93,8 @@ public static function resolve_path($name)
* The file is looked for recursively under the load_paths directories
* If the filename does not end in .sass or .scss try the current syntax first
* then, if a file is not found, try the other syntax.
* @param string filename to find
* @param SassParser Sass parser
* @param string $filename filename to find
* @param SassParser $parser Sass parser
* @return array of string path(s) to file(s) or FALSE if no such file
*/
public static function get_file($filename, &$parser, $sass_only = TRUE)
Expand All @@ -106,7 +106,7 @@ public static function get_file($filename, &$parser, $sass_only = TRUE)

return $sass ? $sass : self::get_file($filename . '.' . self::SCSS, $parser);
}
if (is_file($filename)) {
if (file_exists($filename)) {
return array($filename);
}
$paths = $parser->load_paths;
Expand Down Expand Up @@ -137,22 +137,21 @@ public static function get_file($filename, &$parser, $sass_only = TRUE)
/**
* Looks for the file recursively in the specified directory.
* This will also look for _filename to handle Sass partials.
* @param string filename to look for
* @param string path to directory to look in and under. There is no ending / in the path
* @param string $filename filename to look for
* @param string $dir path to directory to look in and under
* @return mixed string: full path to file if found, false if not
*/
public static function find_file($filename, $dir)
{
$partialname = str_replace(basename($filename), ('_'.basename($filename)), $filename);

if (strstr($filename, DIRECTORY_SEPARATOR . '**')) {
$specialDirectory = $dir . DIRECTORY_SEPARATOR . substr($filename, 0, strpos($filename, DIRECTORY_SEPARATOR . '**'));
if (is_dir($specialDirectory)) {
if (is_dir($dir . DIRECTORY_SEPARATOR . substr($filename, 0, strpos($filename, DIRECTORY_SEPARATOR . '**')))) {
$paths = array();
$files = scandir($specialDirectory);
$files = scandir($dir . DIRECTORY_SEPARATOR . substr($filename, 0, strpos($filename, DIRECTORY_SEPARATOR . '**')));
foreach ($files as $file) {
if ($file === '..') continue;
if (is_dir($specialDirectory . DIRECTORY_SEPARATOR . $file)) {
if (is_dir($dir . DIRECTORY_SEPARATOR . substr($filename, 0, strpos($filename, DIRECTORY_SEPARATOR . '**')) . DIRECTORY_SEPARATOR . $file)) {
if ($file === '.') {
$new_filename = str_replace(DIRECTORY_SEPARATOR . '**', '', $filename);
}
Expand Down Expand Up @@ -189,20 +188,22 @@ public static function find_file($filename, $dir)
}

foreach (array($filename, $partialname) as $file) {
if (is_file($dir . DIRECTORY_SEPARATOR . $file)) {
if (file_exists($dir . DIRECTORY_SEPARATOR . $file)) {
return realpath($dir . DIRECTORY_SEPARATOR . $file);
}
}

// select only dirs
$dirs = glob($dir . DIRECTORY_SEPARATOR . '*', GLOB_ONLYDIR);
foreach ($dirs as $deepDir) {
// ignore hidden folders
if ($deepDir[0] === '.') continue;
if (is_dir($dir)) {
$files = scandir($dir);

$path = self::find_file($filename, $deepDir);
if ($path !== false) {
return $path;
foreach ($files as $file) {
if (($file === '.') || ($file === '..')) continue;
if (substr($file, 0, 1) != '.' && is_dir($dir . DIRECTORY_SEPARATOR . $file)) {
$path = self::find_file($filename, $dir . DIRECTORY_SEPARATOR . $file);
if ($path !== false) {
return $path;
}
}
}
}

Expand Down
43 changes: 27 additions & 16 deletions SassParser.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ class SassParser

/**
* function:
* @var An array of (function_name => callback) items.
* @var array An array of (function_name => callback) items.
*/
public static $functions;

Expand Down Expand Up @@ -220,6 +220,7 @@ class SassParser
* Constructor.
* Sets parser options
* @param array $options
* @throws SassException
* @return SassParser
*/
public function __construct($options = array())
Expand Down Expand Up @@ -282,7 +283,8 @@ public function __construct($options = array())

/**
* Getter.
* @param string name of property to get
* @param string $name name of property to get
* @throws SassException
* @return mixed return value of getter function
*/
public function __get($name)
Expand Down Expand Up @@ -397,7 +399,8 @@ public function getOptions()

/**
* Parse a sass file or Sass source code and returns the CSS.
* @param string name of source file or Sass source
* @param string $source name of source file or Sass source
* @param boolean $isFile
* @return string CSS
*/
public function toCss($source, $isFile = true)
Expand All @@ -410,7 +413,9 @@ public function toCss($source, $isFile = true)
* returns the document tree that can then be rendered.
* The file will be searched for in the directories specified by the
* load_paths option.
* @param string name of source file or Sass source
* @param string $source name of source file or Sass source
* @param boolean $isFile
* @throws SassException
* @return SassRootNode Root node of document tree
*/
public function parse($source, $isFile = true)
Expand Down Expand Up @@ -474,7 +479,8 @@ public function parse($source, $isFile = true)
/**
* Parse Sass source into a document tree.
* If the tree is already created return that.
* @param string Sass source
* @param string $source Sass source
* @throws SassException
* @return SassRootNode the root of this document tree
*/
public function toTree($source)
Expand Down Expand Up @@ -505,7 +511,8 @@ public function toTree($source)
/**
* Builds a parse tree under the parent node.
* Called recursivly until the source is parsed.
* @param SassNode the node
* @param SassNode $parent the node
* @return SassNode
*/
public function buildTree($parent)
{
Expand All @@ -521,6 +528,8 @@ public function buildTree($parent)
/**
* Creates and returns the next SassNode.
* The tpye of SassNode depends on the content of the SassToken.
* @param SassNode $node
* @throws SassException
* @return SassNode a SassNode of the appropriate type. Null when no more
* source to parse.
*/
Expand Down Expand Up @@ -580,14 +589,15 @@ public function getToken()
* about it from SASS source.
* Sass statements are passed over. Statements spanning multiple lines, e.g.
* CSS comments and selectors, are assembled into a single statement.
* @throws SassException
* @return object Statement token. Null if end of source.
*/
public function sass2Token()
{
$statement = ''; // source line being tokenised
$token = null;

while ($token === null && !empty($this->source)) {
while (is_null($token) && !empty($this->source)) {
while (empty($statement) && is_array($this->source) && !empty($this->source)) {
$source = array_shift($this->source);
$statement = trim($source);
Expand Down Expand Up @@ -649,7 +659,7 @@ public function sass2Token()
/**
* Returns the level of the line.
* Used for .sass source
* @param string the source
* @param string $source the source
* @return integer the level of the source
* @throws Exception if the source indentation is invalid
*/
Expand All @@ -676,6 +686,7 @@ public function getLevel($source)
/**
* Returns an object that contains the next source statement and meta data
* about it from SCSS source.
* @throws SassException
* @return object Statement token. Null if end of source.
*/
public function scss2Token()
Expand All @@ -688,8 +699,7 @@ public function scss2Token()
if (empty($srclen)) {
$srclen = strlen($this->source);
}
$localSourceStringLength = strlen($this->source);
while ($token === null && $srcpos < $localSourceStringLength) {
while (is_null($token) && $srcpos < strlen($this->source)) {
$c = $this->source[$srcpos++];
switch ($c) {
case self::BEGIN_COMMENT:
Expand Down Expand Up @@ -746,7 +756,7 @@ public function scss2Token()
case self::END_BLOCK:
case self::END_STATEMENT:
$token = $this->createToken($statement . $c);
if ($token === null) {
if (is_null($token)) {
$statement = '';
}
break;
Expand All @@ -756,7 +766,7 @@ public function scss2Token()
}
}

if ($token === null) {
if (is_null($token)) {
$srclen = $srcpos = 0;
}

Expand All @@ -767,8 +777,8 @@ public function scss2Token()
* Returns an object that contains the source statement and meta data about
* it.
* If the statement is just and end block we update the meta data and return null.
* @param string source statement
* @return SassToken
* @param string $statement source statement
* @return object|null
*/
public function createToken($statement) {
$this->line += substr_count($statement, "\n");
Expand All @@ -792,8 +802,9 @@ public function createToken($statement) {

/**
* Parses a directive
* @param SassToken token to parse
* @param SassNode parent node
* @param SassToken $token token to parse
* @param SassNode $parent parent node
* @throws SassException
* @return SassNode a Sass directive node
*/
public function parseDirective($token, $parent)
Expand Down
22 changes: 11 additions & 11 deletions renderers/SassCompactRenderer.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ protected function end()
* Renders a comment.
* Comments preceeding a rule are on their own line.
* Comments within a rule are on the same line as the rule.
* @param SassNode the node being rendered
* @param SassNode $node the node being rendered
* @return string the rendered commnt
*/
public function renderComment($node)
Expand All @@ -58,8 +58,8 @@ public function renderComment($node)

/**
* Renders a directive.
* @param SassNode the node being rendered
* @param array properties of the directive
* @param SassNode $node the node being rendered
* @param array $properties properties of the directive
* @return string the rendered directive
*/
public function renderDirective($node, $properties)
Expand All @@ -70,8 +70,8 @@ public function renderDirective($node, $properties)

/**
* Renders properties.
* @param SassNode the node being rendered
* @param array properties to render
* @param SassNode $node the node being rendered
* @param array $properties properties to render
* @return string the rendered properties
*/
public function renderProperties($node, $properties)
Expand All @@ -81,7 +81,7 @@ public function renderProperties($node, $properties)

/**
* Renders a property.
* @param SassNode the node being rendered
* @param SassNode $node the node being rendered
* @return string the rendered property
*/
public function renderProperty($node)
Expand All @@ -93,9 +93,9 @@ public function renderProperty($node)

/**
* Renders a rule.
* @param SassNode the node being rendered
* @param array rule properties
* @param string rendered rules
* @param SassNode $node the node being rendered
* @param array $properties rule properties
* @param string $rules rendered rules
* @return string the rendered rule
*/
public function renderRule($node, $properties, $rules)
Expand All @@ -111,7 +111,7 @@ public function renderRule($node, $properties, $rules)
* {@link https://addons.mozilla.org/en-US/firefox/addon/103988/ FireSass}.
* Else if the node has the line_numbers option set true the line number and
* filename are rendered in a comment.
* @param SassNode the node being rendered
* @param SassNode $node the node being rendered
* @return string the debug information
*/
protected function renderDebug($node)
Expand All @@ -134,7 +134,7 @@ protected function renderDebug($node)

/**
* Renders rule selectors.
* @param SassNode the node being rendered
* @param SassNode $node the node being rendered
* @return string the rendered selectors
*/
protected function renderSelectors($node)
Expand Down
Loading

0 comments on commit 9519bf9

Please sign in to comment.