Docs For Class SML

Class SML

Description

Simple Markup Language (SML) Files

This is a wrapper-class that may be used to work with *.config and *.sml files.

SML files provide the same semantics and functionality as JSON encoded files, are as easy to read and understand, but they stick with XML-style markup, which is widely used and understood by most people.

since: 2.8.5
access: public
name: SML

Object
   |
   --FileSystemResource
      |
      --FileReadonly
         |
         --File
            |
            --SML

Method Summary

SML SML (string $filename, [int $case_sensitive = CASE_MIXED])
array decode (string $input, [int $case_sensitive = CASE_MIXED])
void encode (scalar|array|object $data, [string $name = null], [int $case_sensitive = CASE_MIXED], int $indent)
bool exists ([string $key = '*'])
mixed get ([string $key = "*"])
array getFile (array|string $input, [int $case_sensitive = CASE_MIXED])
string getFileContent ()
mixed getVar ([string $key = "*"])
mixed &getVarByReference ([string $key = "*"])
bool insert (array $array)
int length ([string $key = "*"])
mixed read ()
bool remove ([string $key = "*"])
void reset ()
bool set (array $array)
bool setVar (string $key, mixed $value)
bool setVarByReference (string $key, mixed &$value)
string toString ()

Direct descendents

Class	Description
DbStructure	database structure file

Methods

constructor

SML SML (

string $filename, [int $case_sensitive = CASE_MIXED]

)

List of parameters:

Name	Type	Description
$filename	string
$case_sensitive	int

Description:

Create a new instance of this class. This extends the super class constructor.

Note the additional parameter $case_sensitive. This parameter decides on how to return key names.

It's value can be one of the following constants:

CASE_UPPER upper-case all keys
CASE_LOWER lower-case all keys
CASE_MIXED leave keys in mixed case

Read variables from an encoded string

array decode (

string $input, [int $case_sensitive = CASE_MIXED]

)

List of parameters:

Name	Type	Description
$input	string
$case_sensitive	int

Description:

This function is pretty much the same as SML::getFile() except for the fact that it is working on strings rather than files.

Returns NULL on error.

The argument $input has to be a string, that has been encoded using SML::encode().

The argument $case_sensitive can be used to decide how keys should be treated.

Valid values for $case_sensitive are:

CASE_UPPER upper-case all keys
CASE_LOWER lower-case all keys
CASE_MIXED leave keys in mixed case

Note: to reaccess an encoded value look at the following examples.

Handling boolean values:

$input_bool = true;
$encoded = SML::encode($input_bool, 'MY_VAR');
$decoded = SML::decode($encoded);
// the following returns true
$input_bool === $decoded['MY_VAR'];

... or shorter:

$input_bool = true
// the following returns true
$input_bool === array_pop(SML::decode(SML::encode($input_bool)));

Handling string values and nummerics:

$input_string = 'foo';
// the following returns true
$input_string === array_pop(SML::decode(SML::encode($input_string)));
$input_int = 123;
// the following returns true
$input_int == array_pop(SML::decode(SML::encode($input_int)));

Handling the 'NULL' value:

$input_null = null;
// the following returns true
is_null( array_pop(SML::decode(SML::encode($input_string))) );

Arrays (were key case does matter):

$input_array = array(1,2,3,array(4,5),'a'=>6,'B'=>7);
$output_array = SML::decode(SML::encode($input_array));
// the following returns true
$input_array == $output_array;

When dealing with nummeric arrays, or associative arrays where all keys should be uppercase, or if you just don't care, you may set the $case_sensitive parameter to CASE_UPPER.

$input_array = array(1,2,3,array(4,5),'A'=>6,'B'=>7);
$output_array = SML::decode(SML::encode($input_array,null,CASE_UPPER),CASE_UPPER);
// the following returns true
$input_array == $output_array;

The obvious advantage of doing so is: you can rely on the writing of keys with no need to care for case-sensitivity.

see: SML::encode()
see: SML::getFile()
access: public
name: SML::decode()

Create a SML string from a scalar variable, an object, or an array of data.

void encode (

scalar|array|object $data, [string $name = null], [int $case_sensitive = CASE_MIXED], int $indent

)

List of parameters:

Name	Type	Description
$data	scalar\|array\|object	data to encode
$name	string	name of root-tag
$case_sensitive	int	one of: CASE_UPPER, CASE_LOWER, CASE_MIXED
$indent	int	internal value (ignore)

Description:

The argument $name can be used to specify the name of the root node. If $name is omitted, no root node is created.

Note that this function will issue an E_USER_NOTICE if $name is omitted and $data is a scalar value. In this case the scalar variable will be named '0' by default.

The argument $case_sensitive can be used to decide how keys should be treated.

Note that any tags from string inputs will be stripped. You should convert tags to entities, before submiting the input.

Valid values for $case_sensitive are:

CASE_UPPER upper-case all keys
CASE_LOWER lower-case all keys
CASE_MIXED leave keys in mixed case

see: SML::getFile()
access: public
name: SML::encode()

test if a certain value exists

bool exists (

[string $key = '*']

)

List of parameters:

Name	Type	Description
$key	string	(optional)

Description:

This function has two synopsis:

1st: if parameter $key is provided.

returns bool(true) if the file exists, is loaded and the variable identified by $key is set
returns bool(false) otherwise.

2nd: if parameter $key is missing, == '' or the wildcard '*'.

returns bool(true) if the file exists and is loaded
returns bool(false) otherwise.

access: public
name: SML::exists()

Redefinition of: FileSystemResource::exists()

get a value from the file

mixed get (

[string $key = "*"]

)

List of parameters:

Name	Type	Description
$key	string	address of the var to get (use wildcard '*' to get all)

Description:

Returns the value at the position specified by $key. If key is the character '*' or empty, than the whole document is returned.

Example: use "foo1.foo2" to get the contents of the "foo2" child tag inside the "foo1" root tag. Or, more technical speaking, to get the "foo2" element of the "foo1" array.

access: public
name: SML::get()

Redefinition of: FileReadonly::get()

Read a file in SML syntax and return its contents

array getFile (

array|string $input, [int $case_sensitive = CASE_MIXED]

)

List of parameters:

Name	Type	Description
$input	array\|string	filename or file content
$case_sensitive	int	CASE_UPPER\|CASE_LOWER\|CASE_MIXED

Description:

The argument $input can wether be a filename or a numeric array of strings created by file($filename).

The argument $case_sensitive can be used to decide how keys should be treated.

Valid values for $case_sensitive are:

CASE_UPPER upper-case all keys
CASE_LOWER lower-case all keys
CASE_MIXED leave keys in mixed case

see: SML::encode()
access: public
name: SML::getFile()

return file contents as string

string getFileContent ()

Description:

access: public

Redefinition of: FileReadonly::getFileContent()

Alias of SML->get(string $key)

mixed getVar (

[string $key = "*"]

)

List of parameters:

Name	Type	Description
$key	string	address of the var to get (use wildcard '*' to get all)

Description:

Get a value from the file.

see: SML::get()
since: 2.9.4
access: public

Alias of SML->getByReference(string $key)

mixed &getVarByReference (

[string $key = "*"]

)

List of parameters:

Name	Type	Description
$key	string	address of the var to get (use wildcard '*' to get all)

Description:

Returns the value at the position specified by $key. The value is returned by reference.

see: SML::get()
since: 2.9.5
access: public

insert an array into the file

bool insert (

array $array

)

List of parameters:

Name	Type	Description
$array	array

Description:

This merges the current file content with the provided array. New values will replace old ones.

Returns bool(true) on success and bool(false) on error.

Since version 2.9 this function has two synopsis:

SML->insert(array $content)
SML->insert(string $key, mixed $value)

The first one merges the current content with the new content, by merging both arrays. Existing elements in the old array get replaced by new ones.

The second sets a new value at the address provided in $key to $value. If the key already exists, it's value gets updated. As an alternative, if you like to be more accurate, you may choose to use SML->setVar(), which offers only the second synopsis.

access: public
name: SML::insert()

Redefinition of: File::insert()

get the number of elements

int length (

[string $key = "*"]

)

List of parameters:

Name	Type	Description
$key	string	(optional)

Description:

This returns how many elements can be found inside the array at position $key. If $key points to a non-existing value, or an empty array, the function returns 0.

access: public
name: SML::length()

Redefinition of: File::length()

initialize file contents

mixed read ()

Description:

You should always call this before anything else. Returns the file content on success and bool(false) on error.

access: public
name: SML::read()

Redefinition of: FileReadonly::read()

Redefined in descendants as:

DbStructure::read() : read and initialize the file

remove an entry from the file

bool remove (

[string $key = "*"]

)

List of parameters:

Name	Type	Description
$key	string	(optional)

Description:

access: public
name: SML::remove()

Redefinition of: File::remove()

reset the file

void reset ()

Description:

Changes to the file will not be safed unless you explicitely call $configFile->write(). So if you want or need to revert your changes just call $configFile->reset() and all will be fine.

access: public
name: SML::reset()

Redefinition of: FileReadonly::reset()

set the content of the file

bool set (

array $array

)

List of parameters:

Name	Type	Description
$array	array	new file content

Description:

Replaces the file content with the provided array.

Returns bool(true) on success and bool(false) on error.

access: public
name: SML::set()

Alias of SML->insert(string $key, mixed $value)

bool setVar (

string $key, mixed $value

)

List of parameters:

Name	Type	Description
$key	string	adress of old data
$value	mixed	new data

Description:

Create or update new key / value pair.

see: SML::insert()
since: 2.9 RC3
access: public

Set var by reference

bool setVarByReference (

string $key, mixed &$value

)

List of parameters:

Name	Type	Description
$key	string	adress of old data
&$value	mixed	new data

Description:

Create or update new key / value pair by reference.

see: SML::insert()
since: 2.9.5
access: public

get a string representation

string toString ()

Description:

access: public
name: SML::toString()

Redefinition of: FileReadonly::toString()

inherited from base classes

Inherited From File

Inherited From FileReadonly

Inherited From FileSystemResource

Inherited From Object

Documentation generated on Sat, 03 Jan 2009 22:22:34 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyer Homepage: www.yanaframework.net