/ 
Tie-Gzip-0.03
River stage zero No dependents
/ Data::Secs2

NAME

Data::Secs2 - canoncial string for nested data

SYNOPSIS

#####
# Subroutine interface
#  
use Data::Secs2 qw(stringify arrayify_walk arrayify);

$string = stringify( @arg );
@array = arrayify( @arg );
@array = arrayify_var( @arg );

#####
# Class interface
#
use Data::Secs2;

$string = Data::Secs2->stringify( @arg );
@array = Data::Secs2->listify( @arg );
@array = Data::Secs2->arrayify( $var );

##### 
# Inherit by another class
#
use Data::Secs2
use vars qw(@ISA);
@ISA = qw(Data::Secs2);

$string = __PACKAGE__->stringify( @arg );
@array = __PACKAGE__->listify( @arg );
@array = __PACKAGE__->arrayify( $var );

DESCRIPTION

The 'Data::SECSII' module provides a canoncial string for data no matter how many nests of arrays and hashes it contains.

arrayify subroutine/method

The purpose of the 'arrayify_var' subroutine/method is to provide a canoncial representation of hashes with the keys sorted. This is accomplished by converting a hash to an array of key value pairs with the keys sorted. The variable reference is added as the first member of a arary or arrayified hash to distinguish a hash from a array in the unlikely event there are two data structures, one an array and the other a hash where the array has the same member as an arrayified hash.

The 'arrayify' subroutine/method converts $var into an array as follows:

reference with underlying 'HASH' data type

Converts a reference whose underlying data type is a 'HASH' to array whose first member is ref($var), and the rest of the members the hash key, value pairs, sorted by key

reference with underlying 'ARRAY' data type

Converts a reference whose underlying data type is a 'ARRAY' to array whose first member is ref($var), and the rest of the members the members of the array

otherwise

Leaves $var as is.

secsify subroutine/method

The 'secsify' subroutine/method walks a data structure and converts all underlying array and hash references to arrays by applying the 'arrayify' subroutine/method.

The secsification of the nested data is in accordance with SEMI E5-94, Semiconductor Equipment Communications Standard 2 (SECS-II), pronounced 'sex two' with gussto and a perverted smile. The SEMI E4 SECS-I standard addresses transmitting SECSII messages from one machine to another machine (all most always host to equipment) serially via RS-232. And, there is another SECS standard for TCP/IP, the SEMI E37 standard, High-Speed SECS Message Services (HSMS) Generic Services.

In order not to plagarize college students, credit must be given where credit is due. Tony Blair, when he was a college intern at Intel Fab 4, in London invented the SEMI SECS standards. When the Intel Fab 4 management discovered Tony's secsification of their host and equipment, they elected to have security to escort Tony out the door. This was Mr. Blair's introduction to elections which he leverage into being elected prime minister. In this new position he used the skills he learned at the Intel fab to secsify intelligence reports on Iraq's weopons of mass distruction.

The SEMI E5 SECS-II standard is a method of forming listified packed messages from nested data. It consists of elements where each element is a format code, number of elements followed by the elements.

unpacked   binary  octal    description
----------------------------------------
L          000000   00      List (length in elements)
B          001000   10      Binary
T          001001   11      Boolean
A          010000   20      ASCII
J          010001   21      JIS-8
I8         011000   30      8-byte integer
I1         011001   31      1-byte integer
I2         011010   32      2-byte integer
I4         011100   34      4-byte floating
F4         100000   40      8-byte floating
F8         100400   48      8-byte integer (unsigned)
U8         101000   50      8-byte integer (unsigned)
U1         101001   51      1-byte integer (unsigned)
U2         101010   52      2-byte integer (unsigned)
U4         101100   54      4-byte integer (unsigned)

Notes:

  1. ASCII format - Non-printing characters are equipment specific

  2. Integer formats - most significant byte sent first

  3. floating formats - IEEE 753 with the byte containing the sign sent first.

In this module, there are only three Perlified SECSII elements that will be listified into SECSII message as follows:

OBJECT, INDEX OBJECT, and SCALAR

OBJECT => 'L', $number-of-elements, 
          'A', $class,
          'A', $built-in-class,
          @elements

@elements may contain a Perlified OBJECT, REFERENCE or SCALAR)

INDEX OBJECT => 'L' '2', 'A' 'Index', 'U4', $number-of-indices, @indices 

(reference is index into the nested list of lists)

SCALAR = 'A', $scalar  (Perl built-in class)

stringify subroutine/method

The 'stringify' subroutine/method stringifies a data structure by applying '&Dump::Dumper' to a data structure arrayified by the 'arrayify' subroutine/method

new method

The new method establishes an object to configure the variables in the 'Data::Dumper' module used by 'Data::Secs2'.

REQUIREMENTS

The requirements are coming.

DEMONSTRATION

~~~~~~ Demonstration overview ~~~~~

Perl code begins with the prompt

=>

The selected results from executing the Perl Code follow on the next lines. For example,

=> 2 + 2
4

~~~~~~ The demonstration follows ~~~~~

=>     use File::Package;
=>     my $fp = 'File::Package';

=>     use Data::Secs2 qw(list2str);

=>     my $uut = 'Data::Secs2';
=>     my $loaded;
=> $uut->import( 'stringify' )
=> stringify( 'string' )
'string'

=> stringify( 2 )
2

=> stringify( '2', 'hello', 4 )
'A[1] 2
A[5] hello
A[1] 4
'

=> stringify( ['2', 'hello', 4] )
'L[5]
  A[0] 
  A[5] ARRAY
  A[1] 2
  A[5] hello
  A[1] 4
'

=> stringify( {header => 'To: world', body => 'hello'})
'L[6]
  A[0] 
  A[4] HASH
  A[4] body
  A[5] hello
  A[6] header
  A[9] To: world
'

=> stringify( '2', ['hello', 'world'], 4 )
'A[1] 2
L[4]
  A[0] 
  A[5] ARRAY
  A[5] hello
  A[5] world
A[1] 4
'

=> my $obj = bless { To => 'nobody', From => 'nobody'}, 'Class::None'
=> stringify( '2', { msg => ['hello', 'world'] , header => $obj } )
'A[1] 2
L[6]
  A[0] 
  A[4] HASH
  A[6] header
  L[6]
    A[11] Class::None
    A[4] HASH
    A[4] From
    A[6] nobody
    A[2] To
    A[6] nobody
  A[3] msg
  L[4]
    A[0] 
    A[5] ARRAY
    A[5] hello
    A[5] world
'

=> stringify( { msg => ['hello', 'world'] , header => $obj }, 
=>                {msg => [ 'body' ], header => $obj} )
'L[6]
  A[0] 
  A[4] HASH
  A[6] header
  L[6]
    A[11] Class::None
    A[4] HASH
    A[4] From
    A[6] nobody
    A[2] To
    A[6] nobody
  A[3] msg
  L[4]
    A[0] 
    A[5] ARRAY
    A[5] hello
    A[5] world
L[6]
  A[0] 
  A[4] HASH
  A[6] header
  L[2]
    A[5] Index
    U4[2] 0, 3
  A[3] msg
  L[3]
    A[0] 
    A[5] ARRAY
    A[4] body
'

QUALITY ASSURANCE

Running the test script 'Secs2.t' found in the "Data-Secs2-$VERSION.tar.gz" distribution file verifies the requirements for this module.

All testing software and documentation stems from the Software Test Description (STD) program module 't::Data::Secs2', found in the distribution file "Data-Secs2-$VERSION.tar.gz".

The 't::Data::Secs2' STD POD contains a tracebility matix between the requirements established above for this module, and the test steps identified by a 'ok' number from running the 'Secs2.t' test script.

The t::Data::Secs2' STD program module '__DATA__' section contains the data to perform the following:

  • to generate the test script 'Secs2.t'

  • generate the tailored STD POD in the 't::Data::Secs2' module,

  • generate the 'Secs2.d' demo script,

  • replace the POD demonstration section herein with the demo script 'Secs2.d' output, and

  • run the test script using Test::Harness with or without the verbose option,

To perform all the above, prepare and run the automation software as follows:

  • Install "Test_STDmaker-$VERSION.tar.gz" from one of the respositories only if it has not been installed:

    • http://www.softwarediamonds/packages/

    • http://www.perl.com/CPAN-local/authors/id/S/SO/SOFTDIA/

  • manually place the script tmake.pl in "Test_STDmaker-$VERSION.tar.gz' in the site operating system executable path only if it is not in the executable path

  • place the 't::Data::Secs2' at the same level in the directory struture as the directory holding the 'Data::Secs2' module

  • execute the following in any directory:

    tmake -test_verbose -replace -run -pm=t::Data::Secs2

NOTES

FILES

The installation of the "Data-Secs2-$VERSION.tar.gz" distribution file installs the 'Docs::Site_SVD::Data_Secs2' SVD program module.

The __DATA__ data section of the 'Docs::Site_SVD::Data_Secs2' contains all the necessary data to generate the POD section of 'Docs::Site_SVD::Data_Secs2' and the "Data-Secs2-$VERSION.tar.gz" distribution file.

To make use of the 'Docs::Site_SVD::Data_Secs2' SVD program module, perform the following:

  • install "ExtUtils-SVDmaker-$VERSION.tar.gz" from one of the respositories only if it has not been installed:

    • http://www.softwarediamonds/packages/

    • http://www.perl.com/CPAN-local/authors/id/S/SO/SOFTDIA/

  • manually place the script vmake.pl in "ExtUtils-SVDmaker-$VERSION.tar.gz' in the site operating system executable path only if it is not in the executable path

  • Make any appropriate changes to the __DATA__ section of the 'Docs::Site_SVD::Data_Secs2' module. For example, any changes to 'Data::Secs2' will impact the at least 'Changes' field.

  • Execute the following:

    vmake readme_html all -pm=Docs::Site_SVD::Data_Secs2

AUTHOR

The holder of the copyright and maintainer is

<support@SoftwareDiamonds.com>

Copyrighted (c) 2002 Software Diamonds

All Rights Reserved

BINDING REQUIREMENTS NOTICE

Binding requirements are indexed with the pharse 'shall[dd]' where dd is an unique number for each header section. This conforms to standard federal government practices, US DOD 490A 3.2.3.6. In accordance with the License, Software Diamonds is not liable for any requirement, binding or otherwise.

LICENSE

Software Diamonds permits the redistribution and use in source and binary forms, with or without modification, provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

SOFTWARE DIAMONDS, http::www.softwarediamonds.com, PROVIDES THIS SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING USE OF THIS SOFTWARE, EVEN IF ADVISED OF NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE POSSIBILITY OF SUCH DAMAGE.