From 438f2650dbbb6d8e01460caa9a39203bce09af10 Mon Sep 17 00:00:00 2001 From: Matthias Jentsch Date: Mon, 10 Aug 2015 15:13:59 +0200 Subject: [PATCH] Conform to coding guidelines Use exclusively getters and setters for accessing class variables. Add better documentation to INI parser and writer classes. --- library/Icinga/File/Ini/Dom/Comment.php | 19 +++- library/Icinga/File/Ini/Dom/Directive.php | 104 ++++++++++++++++++---- library/Icinga/File/Ini/Dom/Document.php | 42 ++++++++- library/Icinga/File/Ini/Dom/Section.php | 74 ++++++++++++--- library/Icinga/File/Ini/IniParser.php | 19 ++-- library/Icinga/File/Ini/IniWriter.php | 5 +- 6 files changed, 221 insertions(+), 42 deletions(-) diff --git a/library/Icinga/File/Ini/Dom/Comment.php b/library/Icinga/File/Ini/Dom/Comment.php index 9cd9e416f..a1f6c04d2 100644 --- a/library/Icinga/File/Ini/Dom/Comment.php +++ b/library/Icinga/File/Ini/Dom/Comment.php @@ -3,14 +3,31 @@ namespace Icinga\File\Ini\Dom; +/** + * A single comment-line in an INI file + */ class Comment { /** + * The comment text + * * @var string */ - public $content; + protected $content; /** + * Set the text content of this comment + * + * @param $content + */ + public function setContent($content) + { + $this->content = $content; + } + + /** + * Render this comment into INI markup + * * @return string */ public function render() diff --git a/library/Icinga/File/Ini/Dom/Directive.php b/library/Icinga/File/Ini/Dom/Directive.php index 97bc6d37c..0014d25bb 100644 --- a/library/Icinga/File/Ini/Dom/Directive.php +++ b/library/Icinga/File/Ini/Dom/Directive.php @@ -3,42 +3,57 @@ namespace Icinga\File\Ini\Dom; +use Icinga\Exception\ConfigurationError; + +/** + * A key value pair in a Section + */ class Directive { /** + * The value of this configuration directive + * * @var string */ protected $key; /** + * The immutable name of this configuration directive + * * @var string */ protected $value; /** - * @var array - */ - public $commentsPre; - - /** - * @var string - */ - public $commentPost; - - /** - * @param string $key + * Comments added one line before this directive * - * @throws Exception + * @var Comment[] The comment lines + */ + protected $commentsPre = null; + + /** + * Comment added at the end of the same line + * + * @var Comment + */ + protected $commentPost = null; + + /** + * @param string $key The name of this configuration directive + * + * @throws ConfigurationError */ public function __construct($key) { $this->key = trim($key); if (strlen($this->key) < 1) { - throw new Exception(sprintf('Ini parser error: empty key.')); + throw new ConfigurationError(sprintf('Ini error: empty directive key.')); } } /** + * Return the name of this directive + * * @return string */ public function getKey() @@ -47,7 +62,9 @@ class Directive } /** - * @return string + * Return the value of this configuration directive + * + * @return string */ public function getValue() { @@ -55,7 +72,9 @@ class Directive } /** - * @param string $value + * Set the value of this configuration directive + * + * @param string $value */ public function setValue($value) { @@ -63,7 +82,39 @@ class Directive } /** - * @return string + * Set the comments to be rendered on the line before this directive + * + * @param Comment[] $comments + */ + public function setCommentsPre(array $comments) + { + $this->commentsPre = $comments; + } + + /** + * Return the comments to be rendered on the line before this directive + * + * @return Comment[] + */ + public function getCommentsPre() + { + return $this->commentsPre; + } + + /** + * Set the comment rendered on the same line of this directive + * + * @param Comment $comment + */ + public function setCommentPost(Comment $comment) + { + $this->commentPost = $comment; + } + + /** + * Render this configuration directive into INI markup + * + * @return string */ public function render() { @@ -82,16 +133,35 @@ class Directive return $str; } + /** + * Assure that the given identifier contains no newlines and pending or trailing whitespaces + * + * @param $str The string to sanitize + * + * @return string + */ protected function sanitizeKey($str) { return trim(str_replace(PHP_EOL, ' ', $str)); } + /** + * Escape the significant characters in directive values, normalize line breaks and assure that + * the character contains no linebreaks + * + * @param $str The string to sanitize + * + * @return mixed|string + */ protected function sanitizeValue($str) { $str = trim($str); $str = str_replace('\\', '\\\\', $str); $str = str_replace('"', '\\"', $str); - return str_replace(PHP_EOL, ' ', $str); + + // line breaks in the value should always match the current system EOL sequence + // to assure editable configuration files + $str = preg_replace("/(\r\n)|(\n)/", PHP_EOL, $str); + return $str; } } diff --git a/library/Icinga/File/Ini/Dom/Document.php b/library/Icinga/File/Ini/Dom/Document.php index 2f606a1f5..69b628916 100644 --- a/library/Icinga/File/Ini/Dom/Document.php +++ b/library/Icinga/File/Ini/Dom/Document.php @@ -6,16 +6,22 @@ namespace Icinga\File\Ini\Dom; class Document { /** - * @var array + * The sections of this INI file + * + * @var Section[] */ protected $sections = array(); /** - * @var array + * The comemnts at file end that belong to no particular section + * + * @var Comment[] */ - public $commentsDangling; + protected $commentsDangling; /** + * Append a section to the end of this INI file + * * @param Section $section */ public function addSection(Section $section) @@ -24,6 +30,8 @@ class Document } /** + * Return whether this INI file has the section with the given key + * * @param string $name * * @return bool @@ -34,6 +42,8 @@ class Document } /** + * Return the section with the given name + * * @param string $name * * @return Section @@ -44,6 +54,8 @@ class Document } /** + * Set the section with the given name + * * @param string $name * @param Section $section * @@ -55,6 +67,8 @@ class Document } /** + * Remove the section with the given name + * * @param string $name */ public function removeSection($name) @@ -63,6 +77,28 @@ class Document } /** + * Set the dangling comments at file end that belong to no particular directive + * + * @param Comment[] $comments + */ + public function setCommentsDangling(array $comments) + { + $this->commentsDangling = $comments; + } + + /** + * Get the dangling comments at file end that belong to no particular directive + * + * @return array + */ + public function getCommentsDangling() + { + return $this->commentsDangling; + } + + /** + * Render this document into the corresponding INI markup + * * @return string */ public function render() diff --git a/library/Icinga/File/Ini/Dom/Section.php b/library/Icinga/File/Ini/Dom/Section.php index e46d4f8ca..dbc9188cb 100644 --- a/library/Icinga/File/Ini/Dom/Section.php +++ b/library/Icinga/File/Ini/Dom/Section.php @@ -5,30 +5,43 @@ namespace Icinga\File\Ini\Dom; use Icinga\Exception\ConfigurationError; +/** + * A section in an INI file + */ class Section { /** + * The immutable name of this section + * * @var string */ protected $name; /** - * @var array + * All configuration directives of this section + * + * @var Directive[] */ protected $directives = array(); /** - * @var array + * Comments added one line before this section + * + * @var Comment[] */ - public $commentsPre; + protected $commentsPre; /** + * Comment added at the end of the same line + * * @var string */ - public $commentPost; + protected $commentPost; /** - * @param string $name + * @param string $name The immutable name of this section + * + * @throws ConfigurationError When the section name is empty */ public function __construct($name) { @@ -39,7 +52,9 @@ class Section } /** - * @param Directive $directive + * Append a directive to the end of this section + * + * @param Directive $directive The directive to append */ public function addDirective(Directive $directive) { @@ -47,7 +62,9 @@ class Section } /** - * @param string $key + * Remove the directive with the given name + * + * @param string $key They name of the directive to remove */ public function removeDirective($key) { @@ -55,7 +72,9 @@ class Section } /** - * @param string $key + * Return whether this section has a directive with the given key + * + * @param string $key The name of the directive * * @return bool */ @@ -65,6 +84,8 @@ class Section } /** + * Get the directive with the given key + * * @param $key string * * @return Directive @@ -75,7 +96,9 @@ class Section } /** - * @return string + * Return the name of this section + * + * @return string The name */ public function getName() { @@ -83,6 +106,28 @@ class Section } /** + * Set the comments to be rendered on the line before this section + * + * @param Comment[] $comments + */ + public function setCommentsPre(array $comments) + { + $this->commentsPre = $comments; + } + + /** + * Set the comment rendered on the same line of this section + * + * @param Comment $comment + */ + public function setCommentPost(Comment $comment) + { + $this->commentPost = $comment; + } + + /** + * Render this section into INI markup + * * @return string */ public function render() @@ -90,7 +135,9 @@ class Section $dirs = ''; $i = 0; foreach ($this->directives as $directive) { - $dirs .= (($i++ > 0 && ! empty($directive->commentsPre)) ? PHP_EOL : '') . $directive->render() . PHP_EOL; + $comments = $directive->getCommentsPre(); + $dirs .= (($i++ > 0 && ! empty($comments)) ? PHP_EOL : '') + . $directive->render() . PHP_EOL; } $cms = ''; if (! empty($this->commentsPre)) { @@ -106,6 +153,13 @@ class Section return $cms . sprintf('[%s]', $this->sanitize($this->name)) . $post . PHP_EOL . $dirs; } + /** + * Escape the significant characters in sections and normalize line breaks + * + * @param $str The string to sanitize + * + * @return mixed + */ protected function sanitize($str) { $str = trim($str); diff --git a/library/Icinga/File/Ini/IniParser.php b/library/Icinga/File/Ini/IniParser.php index 85ab20e18..43c96836d 100644 --- a/library/Icinga/File/Ini/IniParser.php +++ b/library/Icinga/File/Ini/IniParser.php @@ -93,7 +93,7 @@ class IniParser $token .= $s; } else { $sec = new Section($token); - $sec->commentsPre = $coms; + $sec->setCommentsPre($coms); $doc->addSection($sec); $dir = null; $coms = array(); @@ -108,8 +108,7 @@ class IniParser $token .= $s; } else { $dir = new Directive($token); - $dir->commentsPre = $coms; - + $dir->setCommentsPre($coms); if (isset($sec)) { $sec->addDirective($dir); } else { @@ -177,16 +176,16 @@ class IniParser $token .= $s; } else { $com = new Comment(); - $com->content = $token; + $com->setContent($token); $token = ''; // Comments at the line end belong to the current line's directive or section. Comments // on empty lines belong to the next directive that shows up. if ($state === self::COMMENT_END) { if (isset($dir)) { - $dir->commentPost = $com; + $dir->setCommentPost($com); } else { - $sec->commentPost = $com; + $sec->setCommentPost($com); } } else { $coms[] = $com; @@ -212,12 +211,12 @@ class IniParser case self::COMMENT: case self::COMMENT_END: $com = new Comment(); - $com->content = $token; + $com->setContent($token); if ($state === self::COMMENT_END) { if (isset($dir)) { - $dir->commentPost = $com; + $dir->setCommentPost($com); } else { - $sec->commentPost = $com; + $sec->setCommentPost($com); } } else { $coms[] = $com; @@ -236,7 +235,7 @@ class IniParser self::throwParseError('File ended in unterminated state ' . $state, $line); } if (! empty($coms)) { - $doc->commentsDangling = $coms; + $doc->setCommentsDangling($coms); } return $doc; } diff --git a/library/Icinga/File/Ini/IniWriter.php b/library/Icinga/File/Ini/IniWriter.php index ab024bf62..8bf8241aa 100644 --- a/library/Icinga/File/Ini/IniWriter.php +++ b/library/Icinga/File/Ini/IniWriter.php @@ -117,7 +117,10 @@ class IniWriter protected function updateSectionOrder(Config $newconfig, Document $oldDoc) { $doc = new Document(); - $doc->commentsDangling = $oldDoc->commentsDangling; + $dangling = $oldDoc->getCommentsDangling(); + if (isset($dangling)) { + $doc->setCommentsDangling($dangling); + } foreach ($newconfig->toArray() as $section => $directives) { $doc->addSection($oldDoc->getSection($section)); }