blib/lib/SPVM/Packer.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 package SPVM::Packer;
2  
3  
4  
5 1;
6  
7 =head1 Name
8  
9 SPVM::Packer - Pack and Unpack Operations
10  
11 =head1 Description
12  
13 Packer class in L<SPVM> has methods for pack and unpack operations
14  
15 =head1 Usage
16  
17 use Packer;
18
19 my $packer = Packer->new;
20
21 {
22 my $objects = [(object)1, 2L, 0.5, [1, 2], "abc"];
23
24 my $binary = $packer->pack("lqdl2a128", $objects);
25
26 my $objects_unpack = $packer->unpack("lqdl2a128", $binary);
27 }
28
29 {
30 my $objects = [(object)[1, 2, 3]];
31
32 my $binary = $packer->pack("l*", $objects);
33
34 my $objects_unpack = $packer->unpack("l*", $binary);
35 }
36
37 =head1 Class Methods
38  
39 C<static method new : Packer ();>
40  
41 Creates a new L<Packer|SPVM::Packer> object.
42  
43 =head1 Instance Methods
44  
45 =head2 pack
46  
47 C<static method pack : string ($template : string, $objects : object[]);>
48  
49 Converts the objects $objects to a binary data according to the template $template, and returns it.
50  
51 Template Syntax:
52  
53 A template is a string. It consist of specifier parts.
54  
55 TEMPLATE := "SpecifierPart1SpecifierPart2SpecifierPartN"
56  
57 A specifier part is consist of a speficier, an endian, and a length. An endian and a length are optional.
58  
59 SpecifierPart := Specifier[Endian][Length]
60  
61 Here is the list of specifiers.
62  
63 [Specifiers] [Types] [An output binary in pack or an input binary in unpack]
64 a string string. It is null padded in pack method.
65
66 h string A hex string (low nybble first)
67
68 H string A hex string (high nybble first)
69
70 c Byte or byte[] Singed 8-bit integers
71
72 C Byte or byte[] Unsinged 8-bit integers
73
74 s Short or short[] Singed 16-bit integers
75
76 S Short or short[] Unsinged 16-bit integers
77
78 l Int or int[] Singed 32-bit integers
79
80 L Int or int[] Unsinged 32-bit integers
81
82 q Long or long[] Singed 64-bit integers
83
84 Q Long or long[] Unsinged 64-bit integers
85
86 f Float or float[] 32-bit floating point numbers.
87
88 d Double or double[] 64-bit floating point numbers.
89
90 An endian is big-endian C<E<gt>> or little-endian C<E<gt>>.
91  
92 If big-endian is specified, the binary data is converted from big-endian to system-endian in L</"pack"> method, or from system-endian to big-endian in L</"unpack"> method.
93  
94 If little-endian is specified, the binary data is converted from little-endian to system-endian in L</"pack"> method, or from system-endian to little-endian in L</"unpack"> method.
95  
96 A length must be a positive integer or a wildcard C<*>. If a length or a wildcard is specified, the type(such as C<Int>) becomes a corresponding array type(such as C<int[]>).
97  
98 Exceptions:
99  
100 If template syntax is invalid, an exception is thrown.
101  
102 The template $template must be defined. Otherwise an exception is thrown.
103  
104 The objects $objects must be defined. Otherwise an exception is thrown.
105  
106 The length of the specifiers in the template $template must be less than or equal to the lenght of the objects $objects. Otherwise an exception is thrown.
107  
108 The type of the element in the objects $objects is invalid, an exception is thrown.
109  
110 =head2 unpack
111  
112 C<static method unpack : object[] ($template : string, $binary : string);>
113  
114 Converts the binary data $binary to the objects $objects according to the template $template, and returns it.
115  
116 See L</"pack"> method about templates.
117  
118 Exceptions:
119  
120 If template syntax is invalid, an exception is thrown.
121  
122 The template $template must be defined. Otherwise an exception is thrown.
123  
124 The binary data $binary must be defined. Otherwise an exception is thrown.
125  
126 The current offset $binary_offset plus (the size $size * the length $length of the specifier) must be less than the length($binary_length) of the binary data $binary. Otherwise an exception is thrown.
127  
128 =head1 Copyright & License
129  
130 Copyright (c) 2024 Yuki Kimoto
131  
132 MIT License
133