[Cs-content-commits] SF.net SVN: cs-content:[319] trunk/0.10/cs_siteConfig.class.php

[<cra...@us...>]

Revision: 319
          http://cs-content.svn.sourceforge.net/cs-content/?rev=319&view=rev
Author:   crazedsanity
Date:     2009-01-19 19:19:06 +0000 (Mon, 19 Jan 2009)

Log Message:
-----------
Headers for internal vars & methods, minor logic changes.

/cs_siteConfig.class.php:
	* __construct():
		-- call set_active_section() after calling parse_config()
	* set_active_section():
		-- upper-case the section name.
		-- throw exception if the given section isn't valid.
	* get_valid_sections():
		-- check that configSections is a valid array with data; if it's not, 
		throw an exception indicating as such.

Modified Paths:
--------------
    trunk/0.10/cs_siteConfig.class.php

Modified: trunk/0.10/cs_siteConfig.class.php
===================================================================
--- trunk/0.10/cs_siteConfig.class.php	2009-01-19 18:33:34 UTC (rev 318)
+++ trunk/0.10/cs_siteConfig.class.php	2009-01-19 19:19:06 UTC (rev 319)
@@ -20,11 +20,24 @@
 
 class cs_siteConfig {
 	
+	/** XMLParser{} object, for reading XML config file. */
 	private $xmlReader;
+	
+	/** cs_fileSystemClass{} object, for writing/updating XML config file 
+	 * (only available if file is writable)
+	 */
 	private $xmlWriter;
+	
+	/** XMLBuilder{} object, for updating XML. */
 	private $xmlBuilder;
+	
+	/** cs_fileSystemClass{} object, for handling generic file operations (i.e. reading) */
 	private $fs;
+	
+	/** boolean flag indicating if the given config file is readOnly (false=read/write) */
 	private $readOnly;
+	
+	/** Directory for the config file. */
 	private $configDirname;
 	
 	/** Active section of the full site configuration. */
@@ -47,7 +60,12 @@
 	/**
 	 * Constructor.
 	 * 
-	 * @$configFileLocation		(str) URI for config file.
+	 * @param $configFileLocation	(str) URI for config file.
+	 * @param $section				(str,optional) set active section (default=MAIN)
+	 * @param $setVarPrefix			(str,optional) prefix to add to all global & constant names.
+	 * 
+	 * @return NULL					(PASS) object successfully created
+	 * @return exception			(FAIL) failed to create object (see exception message)
 	 */
 	public function __construct($configFileLocation, $section='MAIN', $setVarPrefix=null) {
 		
@@ -57,8 +75,6 @@
 		$this->gf = new cs_globalFunctions;
 		$this->gf->debugPrintOpt=1;
 		
-		$this->set_active_section($section);
-		
 		if(strlen($configFileLocation) && file_exists($configFileLocation)) {
 			
 			$this->configDirname = dirname($configFileLocation);
@@ -68,6 +84,8 @@
 			
 			if($this->fs->is_writable($configFileLocation)) {
 				$this->readOnly = false;
+				$this->xmlWriter = new cs_fileSystemClass($this->configDirname);
+				
 			}
 			else {
 				$this->readOnly = true;
@@ -80,6 +98,7 @@
 		if(strlen($section)) {
 			try {
 				$this->parse_config();
+				$this->set_active_section($section);
 				$this->config = $this->get_section($section);
 			}
 			catch(exception $e) {
@@ -95,14 +114,38 @@
 	
 	
 	//-------------------------------------------------------------------------
+	/** 
+	 * Sets the active section.
+	 * 
+	 * @param $section		(str) section to be set as active.
+	 * 
+	 * @return VOID			(PASS) section was set successfully.
+	 * @return exception	(FAIL) problem encountred setting section. 
+	 */
 	public function set_active_section($section) {
-		$this->activeSection = strtoupper($section);
+		$section = strtoupper($section);
+		if(in_array($section, $this->configSections)) {
+			$this->activeSection = $section;
+		}
+		else {
+			throw new exception(__METHOD__ .": invalid section (". $section .")");
+		}
 	}//end set_active_section($section)
 	//-------------------------------------------------------------------------
 	
 	
 	
 	//-------------------------------------------------------------------------
+	/**
+	 * Parse the configuration file.  Handles replacing {VARIABLES} in values, 
+	 * sets items as global or as constants, and creates array indicating the 
+	 * available sections from the config file.
+	 * 
+	 * @param VOID			(void) no arguments accepted.
+	 * 
+	 * @return NULL			(PASS) successfully parsed configuration
+	 * @return exception	(FAIL) exception indicates problem encountered.
+	 */
 	private function parse_config() {
 		$data = $this->xmlReader->get_path($this->xmlReader->get_root_element());
 		
@@ -150,6 +193,14 @@
 	
 	
 	//-------------------------------------------------------------------------
+	/**
+	 * Retrieve all data about the given section.
+	 * 
+	 * @param $section		(str) section to retrieve.
+	 * 
+	 * @return array		(PASS) array contains section data.
+	 * @return exception	(FAIL) exception indicates problem.
+	 */
 	public function get_section($section) {
 		$data = $this->a2p->get_data($section);
 		
@@ -168,6 +219,17 @@
 	
 	
 	//-------------------------------------------------------------------------
+	/**
+	 * Retrieves value from the active section, or from another (other sections 
+	 * specified like "SECTION/INDEX").
+	 * 
+	 * @param $index		(str) index name of value to retrieve.
+	 * 
+	 * @return mixed		(PASS) returns value of given index.
+	 * 
+	 * NOTE::: this will return NULL if the given index or section/index does
+	 * not exist.
+	 */
 	public function get_value($index) {
 		if(preg_match("/\//", $index)) {
 			//section NOT given, assume they're looking for something in the active section.
@@ -181,12 +243,27 @@
 	
 	
 	//-------------------------------------------------------------------------
+	/**
+	 * Retrieves list of valid configuration sections, as defined by 
+	 * parse_config().
+	 * 
+	 * @param VOID			(void) no parameters accepted.
+	 * 
+	 * @return array		(PASS) array holds list of valid sections.
+	 * @return exception	(FAIL) exception gives error.
+	 */
 	public function get_valid_sections() {
-		return($this->configSections);
+		if(is_array($this->configSections) && count($this->configSections)) {
+			$retval = $this->configSections;
+		}
+		else {
+			throw new exception(__METHOD__ .": no sections defined, probably invalid configuration");
+		}
+		
+		return($retval);
 	}//end get_valid_sections()
 	//-------------------------------------------------------------------------
 	
-	
 }//end cs_siteConfig
 
 ?>


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.