| 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 |