Author: Derick Rethans
Date: 2006-01-29 14:26:35 +0100 (Sun, 29 Jan 2006)
New Revision: 2085
Log:
- Finish configuration tutorial.
Added:
packages/Configuration/trunk/docs/examples/settings.php
packages/Configuration/trunk/docs/tutorial_example_02.php
packages/Configuration/trunk/docs/tutorial_example_03.php
Modified:
packages/Configuration/trunk/docs/examples/
packages/Configuration/trunk/docs/tutorial.txt
Property changes on: packages/Configuration/trunk/docs/examples
___________________________________________________________________
Name: svn:ignore
- defaults.ini
settings.php
+ defaults.ini
Added: packages/Configuration/trunk/docs/examples/settings.php
===================================================================
--- packages/Configuration/trunk/docs/examples/settings.php 2006-01-29
13:25:48 UTC (rev 2084)
+++ packages/Configuration/trunk/docs/examples/settings.php 2006-01-29
13:26:35 UTC (rev 2085)
@@ -0,0 +1,31 @@
+<?php
+return array (
+ 'settings' =>
+ array (
+ 'site' =>
+ array (
+ 'title' => 'Example site',
+ ),
+ 'db' =>
+ array (
+ 'host' => 'localhost',
+ 'user' => 'root',
+ 'password' => 42,
+ 'connection_retries' => 'five',
+ ),
+ ),
+ 'comments' =>
+ array (
+ 'site' =>
+ array (
+ '#' => ' Settings for the site itself',
+ ),
+ 'db' =>
+ array (
+ '#' => ' Database settings used for all connections',
+ 'password' => ' Storing passwords in INI files is not a good idea,
+ is it?',
+ ),
+ ),
+);
+?>
Property changes on: packages/Configuration/trunk/docs/examples/settings.php
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: packages/Configuration/trunk/docs/tutorial.txt
===================================================================
--- packages/Configuration/trunk/docs/tutorial.txt 2006-01-29 13:25:48 UTC
(rev 2084)
+++ packages/Configuration/trunk/docs/tutorial.txt 2006-01-29 13:26:35 UTC
(rev 2085)
@@ -88,19 +88,245 @@
methods to see if an setting or list of settings exists before accessing them
with one of the get*Setting() methods to prevent exceptions from being thrown.
-Using the Reader/Writer Classes Directly
-----------------------------------------
+Using the Reader Classes Directly
+---------------------------------
+Instead of using the manager class, you can also simply retrieve the
+configuration data directly with the reader classes. The following example
+illustrates this:
+.. include:: tutorial_example_02.php
+ :literal:
+In line 4 we instantiate an object of the ezcConfigurationIniReader class which
+we initialize in line 5. It is also possible to initialize the reader directly
+through the constructor but in that case you need to specify the full file name
+to the configuration file. If you do it in the way that this example does it
+then you can simply change the classname to f.e. ezcConfigurationArrayReader
+and your code does not need any changes. The lines 7 to 12 how you can use the
+validate() method to find out if your configuration file has the correct
+format. The code in line 14 retrieves the settings from the configuration file
+and returns them as an ezcConfiguration object. With this object you can read
+settings and modify the settings. (See the API documentation of
+ezcConfiguration for those methods).
+
+Writing Configuration Files
+===========================
+
+After modifying an ezcConfiguration object with the designated methods there
+are multiple classes to write the configuration object back to disk. In the
+next example we write a ezcConfiguration object stored in the variable $cfg to
+disk:
+
+.. include:: tutorial_example_03.php
+ :literal:
+
+In line 4 we instantiate the writer object, in the example we use the
+ezcConfigurationArrayWriter that writes the configuration data as a PHP
+structure. The component also provides a ezcConfigurationIniWriter class that
+writes a file that the ezcConfigurationIniReader can read. After initializing
+the object in line 5 we use the save() method in line 6 to write the
+configuration file.
+
+
File Format
===========
+General Information Regarding Configuration Data
+------------------------------------------------
-More Information
-================
+The configuration format consists of four elements:
+- Groups, they allow you to group similar settings into one group and it also
+ allows you to have multiple settings with the same name but in different
+ groups. This means that you don't have to prefix your settings with the group
+ name.
+- Settings, the name of the setting which identifies the setting. A setting
+ contains a value.
+
+- Values, a value can be of the following types: boolean, integers, floats,
+ arrays and strings.
+
+- Comments, comments belongs to either a group or a setting and can be added to
+ describe what the group contains or what a setting controls.
+
+Group and setting identifiers can only contain the characters a to z, A to Z, 0
+to 9, underscore (_), dash (-) and dot (.). The case of settings are preserved
+but accessing them can be done with any case, this means you cannot have two
+settings with the same identifier only differing in case.
+
+The following are legal names::
+
+ ASimpleName
+ asimplename
+ a_simple_name
+ a.simple.name
+ a-simple_and.longName
+
+and these are illegal::
+
+ A simple name
+ -=A simple name=-
+
+In addition the group names may contain forward slashes (/), for instance::
+
+ a/simple/groupname
+
+Ini File Format
+---------------
+
+This is the format that is written by the ezcConfigurationIniWriter class and
+read by the ezcConfigurationIniReader class. The parser itself is located in
+the ezcConfigurationIniParser class.
+
+The parser will remove leading and trailing whitespace from group names,
+settings and setting values. If you wish to keep whitespace in a string it will
+have to be quoted.
+
+Comments are written using a # (hash) and must be placed at the start of the
+line. The whitespace block before the comment text on all the lines will be
+trimmed away while whitespace after this block is kept. Trailing whitespace is
+also trimmed. For instance the follow comments: ::
+
+ # A simple comment
+ # A simple comment
+ # A simple comment
+
+will become: ::
+
+ #A simple comment
+ # A simple comment
+ # A simple comment
+
+Multiple comment lines will be read as one comment with multiple lines, if
+there are empty lines in between comments they will be read as empty lines in
+the comment itself::
+
+ # A single line comment
+ Setting = value
+
+ # Multiple lines
+ # for this
+ # comment
+ Setting = value
+
+ # Multiple lines
+
+ # with empty lines
+ # for this comment
+ Setting = value
+
+ # Multiple lines
+ #
+ # with empty lines
+ # for this comment
+ # Actually same as above
+ Setting = value
+
+Comments are always placed *in front* of the group or setting. A line
+that only contains whitespace will be ignored.
+
+The files are always encoded in UTF-8 format, this means it can contain Unicode
+characters if needed or plain ASCII without specific encoding.
+
+Groups are defined by placing an identifier inside square brackets alone on the
+string. Any setting that is read after this will be placed as part of this
+group. Settings without groups are not allowed and will cause an error to be
+issued. The group name will have its leading and trailing whitespace trimmed
+away: ::
+
+ [Group1]
+ [Another group]
+ [ Yet another group ]
+
+Settings are defined by placing an identifier with an equal sign (=) after it,
+the value follows after the equal sign. The setting and the value must be on
+one line, it cannot span multiple lines: ::
+
+ Setting1 = Some example string
+ Setting2 = 42
+
+The values of settings are generally seen as strings with the exception of:
+
+1. Booleans which can be written as *true* or *false*, if you need these
+ strings as text they must be quoted: ::
+
+ SystemEnabled = true
+ LogErrors = false
+
+2. Numbers are written using English locale and can be in the following format:
+
+ - decimal::
+
+ [1-9][0-9]* | [0]
+
+ MaxSize = 400
+ MinSize = 0
+
+ - hexadecimal::
+
+ 0[xX][0-9a-fA-F]+
+
+ BackgroundColor = 0xaabbcc
+ TextColor = 0x0102FE
+
+ - octal::
+
+ 0[0-7]+
+
+ Permission = 0666
+
+ - float::
+
+ LNUM [0-9]+
+ DNUM ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
+ EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
+
+ Price = 10.4
+ Seed = 10e5
+
+3. An explicit string which is enclosed in double quotes ("), all whitespace is
+ kept inside the quotes and characters are read literally with the exception
+ of escaped characters. The escaped characters are:
+
+ a) *\\"* which will be replaced with the quote character (")::
+
+ "This contains \"quote\" characters"
+
+ b) *\\\\* which will be replaced with the backslash character (\)::
+
+ "This contains a backslash \\"
+
+In addition it is possible to define arrays in a second way by using square
+brackets ([]) after the setting name and before the equal (=) character. This
+will make the setting an array and the value is parsed as explained above.
+In addition the square brackets may be enclosed around a string which turns the
+array into a hash (or associative array) with the text being used as the key.
::
+
+ List[] = First string
+ List[] = Second string
+ List[] = 5
+ Hash[abc] = 4
+ Hash["def"] = 5
+
+
+Array File Format
+-----------------
+
+The *Array* format can be written using the ezcConfigurationArrayWriter class
+and read with the ezcConfigurationArrayReader class. The format is a simple
`var_export`_ of the contained settings and
+for reading the PHP will parse the file. The file contains an array with two
+elements. One for the groups and settings and one for the comments.
+For instance the file could look like:
+
+.. include:: examples/settings.php
+ :literal:
+
+The # element in line 25 contains the comment for the group 'db' (line 23).
+
+.. _var_export: http://www.php.net/var_export
+
..
Local Variables:
Added: packages/Configuration/trunk/docs/tutorial_example_02.php
===================================================================
--- packages/Configuration/trunk/docs/tutorial_example_02.php 2006-01-29
13:25:48 UTC (rev 2084)
+++ packages/Configuration/trunk/docs/tutorial_example_02.php 2006-01-29
13:26:35 UTC (rev 2085)
@@ -0,0 +1,15 @@
+<?php
+require_once 'tutorial_autoload.php';
+
+$reader = new ezcConfigurationIniReader();
+$reader->init( dirname( __FILE__ ), 'settings' );
+
+$validationResult = $reader->validate();
+foreach ( $result->getResultList() as $resultItem )
+{
+ print $resultItem->file . ":" . $resultItem->line . ":" .
$resultItem->column. ":";
+ print " " . $resultItem->details . "\n";
+}
+
+$cfg = $reader->load();
+?>
Property changes on: packages/Configuration/trunk/docs/tutorial_example_02.php
___________________________________________________________________
Name: svn:eol-style
+ native
Added: packages/Configuration/trunk/docs/tutorial_example_03.php
===================================================================
--- packages/Configuration/trunk/docs/tutorial_example_03.php 2006-01-29
13:25:48 UTC (rev 2084)
+++ packages/Configuration/trunk/docs/tutorial_example_03.php 2006-01-29
13:26:35 UTC (rev 2085)
@@ -0,0 +1,7 @@
+<?php
+require_once 'tutorial_autoload.php';
+
+$writer = new ezcConfigurationArrayWriter();
+$writer->init( dirname( __FILE__ ), "settings", $cfg );
+$writer->save();
+?>
Property changes on: packages/Configuration/trunk/docs/tutorial_example_03.php
___________________________________________________________________
Name: svn:eol-style
+ native
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
