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:
ASCII format - Non-printing characters are equipment specific
Integer formats - most significant byte sent first
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>
COPYRIGHT NOTICE
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:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.