>> YANA 4 PHP Framework >> 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.

  • name: SML
  • since: 2.8.5
  • access: public

Located in /includes/class_sml.php

Object
   |
   --InputStream
      |
      --SecureInputStream
         |
         --SecureFileStream
            |
            --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],  $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)
  • 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)
  • string toString ()

Direct descendents

Class Description
ConfigFile ConfigFile (deprecated)
SmlFile SML Files (deprecated, upper-case only)
StructureFile database schema 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:

  1.  $input_bool true;
  2.  $encoded SML::encode($input_bool'MY_VAR');
  3.  $decoded SML::decode($encoded);
  4.  // the following returns true
  5.   $input_bool === $decoded['MY_VAR'];

... or shorter:

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

Handling string values and nummerics:

  1.  $input_string 'foo';
  2.  // the following returns true
  3.   $input_string === array_pop(SML::decode(SML::encode($input_string)));
  4.  
  5.  $input_int 123;
  6.  // the following returns true
  7.   $input_int == array_pop(SML::decode(SML::encode($input_int)));

Handling the 'NULL' value:

  1.  $input_null null;
  2.  // the following returns true
  3.   is_nullarray_pop(SML::decode(SML::encode($input_string))) );

Arrays (were key case does matter):

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

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

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],  $indent
)
List of parameters:
Name Type Description
$data scalar|array|object
$name string
$case_sensitive int
$indent
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

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.

  • name: SML::exists()
  • access: public

Redefinition of: InputStream::exists()

get a value from the file
mixed get (
[string $key = "*"]
)
List of parameters:
Name Type Description
$key string (optional)
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.

  • name: SML::get()
  • access: public

Redefinition of: SecureInputStream::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

return file contents as string
string getFileContent ()
Description:
  • access: public

Redefinition of: SecureInputStream::getFileContent()

Alias of SML->get(string $key)
mixed getVar (
string $key
)
List of parameters:
Name Type Description
$key string adress of data
Description:

Get a value from the file.

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:

  1. SML->insert(array $content)
  2. 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.

  • name: SML::insert()
  • access: public

Redefinition of: SecureFileStream::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.

  • name: SML::length()
  • access: public

Redefinition of: SecureFileStream::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.

  • name: SML::read()
  • access: public

Redefinition of: SecureInputStream::read()


Redefined in descendants as:
remove an entry from the file
bool remove (
[string $key = "*"]
)
List of parameters:
Name Type Description
$key string (optional)
Description:
  • name: SML::remove()
  • access: public

Redefinition of: SecureFileStream::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.

  • name: SML::reset()
  • access: public

Redefinition of: SecureInputStream::reset()

set the content of the file
bool set (
array $array
)
List of parameters:
Name Type Description
$array array
Description:

Replaces the file content with the provided array.

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

  • name: SML::set()
  • access: public
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.

get a string representation
string toString ()
Description:
  • name: SML::toString()
  • access: public

Redefinition of: SecureInputStream::toString()

inherited from base classes

Inherited From SecureFileStream

Inherited From SecureInputStream

Inherited From InputStream

Inherited From Object

Documentation generated on Sun, 11 Mar 2007 15:02:44 +0100 by phpDocumentor 1.3.1

yana author: Thomas MeyerHomepage: www.yanaframework.net