Document all the functions (mostly). Also, ensure a few functions do not alter in place.

Author: genio

LICENSE

@@ -292,21 +292,21 @@ Definitions:
 
   - "Package" refers to the collection of files distributed by the Copyright
     Holder, and derivatives of that collection of files created through
-    textual modification. 
+    textual modification.
   - "Standard Version" refers to such a Package if it has not been modified,
     or has been modified in accordance with the wishes of the Copyright
-    Holder. 
+    Holder.
   - "Copyright Holder" is whoever is named in the copyright or copyrights for
-    the package. 
+    the package.
   - "You" is you, if you're thinking about copying or distributing this Package.
   - "Reasonable copying fee" is whatever you can justify on the basis of media
     cost, duplication charges, time of people involved, and so on. (You will
     not be required to justify it to the Copyright Holder, but only to the
-    computing community at large as a market that must bear the fee.) 
+    computing community at large as a market that must bear the fee.)
   - "Freely Available" means that no fee is charged for the item itself, though
     there may be fees involved in handling the item. It also means that
     recipients of the item may redistribute it under the same conditions they
-    received it. 
+    received it.
 
 1. You may make and give away verbatim copies of the source form of the
 Standard Version of this Package without restriction, provided that you
@@ -373,7 +373,7 @@ products derived from this software without specific prior written permission.
 
 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
-MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
 The End
 

META.json

@@ -4,7 +4,7 @@
       "Chase Whitener <[email protected]>"
    ],
    "dynamic_config" : 1,
-   "generated_by" : "Dist::Zilla version 6.014, CPAN::Meta::Converter version 2.150010",
+   "generated_by" : "Dist::Zilla version 6.024, CPAN::Meta::Converter version 2.150010",
    "license" : [
       "perl_5"
    ],
@@ -102,8 +102,8 @@
    "x_contributors" : [
       "Chase Whitener <[email protected]>"
    ],
-   "x_generated_by_perl" : "v5.26.1",
-   "x_serialization_backend" : "Cpanel::JSON::XS version 4.19",
+   "x_generated_by_perl" : "v5.30.0",
+   "x_serialization_backend" : "Cpanel::JSON::XS version 4.27",
    "x_spdx_expression" : "Artistic-1.0-Perl OR GPL-1.0-or-later"
 }
 

Makefile.PL

@@ -1,5 +1,5 @@
 # This Makefile.PL for Sodium-FFI was generated by
-# Dist::Zilla::Plugin::MakeMaker::Awesome 0.48.
+# Dist::Zilla::Plugin::MakeMaker::Awesome 0.49.
 # Don't edit it but the dist.ini and plugins used to construct it.
 
 use strict;

README.md

@@ -6,8 +6,139 @@ Sodium::FFI - FFI implementation of libsodium
 
 ```perl
 use strict;
+use warnings;
+use v5.34;
+
+use Sodium::FFI ();
+
+my $text = "1234";
+my $padded = Sodium::FFI::pad($text, 16);
+say Sodium::FFI::unpad($padded);
+```
+
+# DESCRIPTION
+
+[Sodium::FFI](https://metacpan.org/pod/Sodium%3A%3AFFI) is a set of Perl bindings for the [LibSodium](https://doc.libsodium.org/)
+C library. These bindings have been created using FFI via [FFI::Platypus](https://metacpan.org/pod/FFI%3A%3APlatypus) to make
+building and maintaining the bindings easier than was done via [Crypt::NaCl::Sodium](https://metacpan.org/pod/Crypt%3A%3ANaCl%3A%3ASodium).
+While we also intend to fixup [Crypt::NaCl::Sodium](https://metacpan.org/pod/Crypt%3A%3ANaCl%3A%3ASodium) so that it can use newer versions
+of LibSodium, the FFI method is faster to build and release.
+
+# Utility/Helper Functions
+
+LibSodium provides a few [Utility/Helper Functions](https://doc.libsodium.org/helpers)
+to assist you in getting your data ready for encryption, decryption, or hashing.
+
+## sodium\_add
+
+```perl
+use Sodium::FFI qw(sodium_add);
+my $left = "111";
+$left = sodium_add($left, 111);
+say $left; # bbb
+```
+
+The [sodium\_add](https://doc.libsodium.org/helpers#adding-large-numbers)
+function adds 2 large numbers.
+
+## sodium\_bin2hex
+
+```perl
+use Sodium::FFI qw(sodium_bin2hex);
+my $binary = "ABC";
+my $hex = sodium_bin2hex($binary);
+say $hex; # 414243
+```
+
+The [sodium\_bin2hex](https://doc.libsodium.org/helpers#hexadecimal-encoding-decoding)
+function takes a binary string and turns it into a hex string.
+
+## sodium\_compare
+
+```perl
+use Sodium::FFI qw(sodium_compare);
+say sodium_compare("\x01", "\x02"); # -1
+say sodium_compare("\x02", "\x01"); # 1
+say sodium_compare("\x01", "\x01"); # 0
+```
+
+The [sodium\_compare](https://doc.libsodium.org/helpers#comparing-large-numbers)
+function compares two large numbers encoded in little endian format.
+Results in `-1` when `$left < $right`
+Results in `0` when `$left eq $right`
+Results in `1` when `$left > $right`
+
+## sodium\_hex2bin
+
+```perl
+use Sodium::FFI qw(sodium_hex2bin);
+my $hex = "414243";
+my $bin = sodium_hex2bin($hex);
+say $bin; # ABC
+```
+
+The [sodium\_hex2bin](https://doc.libsodium.org/helpers#hexadecimal-encoding-decoding)
+function takes a hex string and turns it into a binary string.
+
+## sodium\_increment
+
+```perl
+use Sodium::FFI qw(sodium_increment);
+my $x = "\x01";
+$x = sodium_increment($x); # "\x02";
+```
+
+The [sodium\_increment](https://doc.libsodium.org/helpers#incrementing-large-numbers)
+function takes an arbitrarily long unsigned number and increments it.
+
+## sodium\_library\_minimal
+
+```perl
+use Sodium::FFI qw(sodium_library_minimal);
+say sodium_library_minimal; # 0 or 1
+```
+
+The `sodium_library_minimal` function lets you know if this is a minimal version.
+
+## sodium\_library\_version\_major
+
+```perl
+use Sodium::FFI qw(sodium_library_version_major);
+say sodium_library_version_major; # 10
+```
+
+The `sodium_library_version_major` function returns the major version of the library.
+
+## sodium\_library\_version\_minor
+
+```perl
+use Sodium::FFI qw(sodium_library_version_minor);
+say sodium_library_version_minor; # 3
+```
+
+The `sodium_library_version_minor` function returns the minor version of the library.
+
+## sodium\_pad
+
+```perl
+use Sodium::FFI qw(sodium_pad);
+say sodium_pad; # 3
 ```
 
+The [sodium\_pad](https://doc.libsodium.org/padding) function adds
+padding data to a buffer in order to extend its total length to a
+multiple of blocksize.
+
+## sodium\_version\_string
+
+```perl
+use Sodium::FFI qw(sodium_version_string);
+say sodium_version_string; # 1.0.18
+```
+
+The `sodium_version_string` function returns the stringified version information
+for the version of LibSodium that you have installed.
+
 # COPYRIGHT
 
 ```

lib/Sodium/FFI.pm

@@ -35,7 +35,9 @@ our %function = (
             my ($xsub, $bin_string1, $bin_string2, $len) = @_;
             return unless $bin_string1 && $bin_string2;
             $len //= length($bin_string1);
-            $xsub->($bin_string1, $bin_string2, $len);
+            my $copy = substr($bin_string1, 0);
+            $xsub->($copy, $bin_string2, $len);
+            return $copy;
         }
     ],
 
@@ -98,7 +100,9 @@ our %function = (
             my ($xsub, $bin_string, $len) = @_;
             return unless $bin_string;
             $len //= length($bin_string);
-            $xsub->($bin_string, $len);
+            my $copy = substr($bin_string, 0);
+            $xsub->($copy, $len);
+            return $copy;
         }
     ],
 
@@ -261,6 +265,117 @@ Sodium::FFI - FFI implementation of libsodium
 =head1 SYNOPSIS
 
   use strict;
+  use warnings;
+  use v5.34;
+
+  use Sodium::FFI ();
+
+  my $text = "1234";
+  my $padded = Sodium::FFI::pad($text, 16);
+  say Sodium::FFI::unpad($padded);
+
+=head1 DESCRIPTION
+
+L<Sodium::FFI> is a set of Perl bindings for the L<LibSodium|https://doc.libsodium.org/>
+C library. These bindings have been created using FFI via L<FFI::Platypus> to make
+building and maintaining the bindings easier than was done via L<Crypt::NaCl::Sodium>.
+While we also intend to fixup L<Crypt::NaCl::Sodium> so that it can use newer versions
+of LibSodium, the FFI method is faster to build and release.
+
+=head1 Utility/Helper Functions
+
+LibSodium provides a few L<Utility/Helper Functions|https://doc.libsodium.org/helpers>
+to assist you in getting your data ready for encryption, decryption, or hashing.
+
+=head2 sodium_add
+
+    use Sodium::FFI qw(sodium_add);
+    my $left = "111";
+    $left = sodium_add($left, 111);
+    say $left; # bbb
+
+The L<sodium_add|https://doc.libsodium.org/helpers#adding-large-numbers>
+function adds 2 large numbers.
+
+=head2 sodium_bin2hex
+
+    use Sodium::FFI qw(sodium_bin2hex);
+    my $binary = "ABC";
+    my $hex = sodium_bin2hex($binary);
+    say $hex; # 414243
+
+The L<sodium_bin2hex|https://doc.libsodium.org/helpers#hexadecimal-encoding-decoding>
+function takes a binary string and turns it into a hex string.
+
+=head2 sodium_compare
+
+    use Sodium::FFI qw(sodium_compare);
+    say sodium_compare("\x01", "\x02"); # -1
+    say sodium_compare("\x02", "\x01"); # 1
+    say sodium_compare("\x01", "\x01"); # 0
+
+The L<sodium_compare|https://doc.libsodium.org/helpers#comparing-large-numbers>
+function compares two large numbers encoded in little endian format.
+Results in C<-1> when C<< $left < $right >>
+Results in C<0> when C<$left eq $right>
+Results in C<1> when C<< $left > $right >>
+
+=head2 sodium_hex2bin
+
+    use Sodium::FFI qw(sodium_hex2bin);
+    my $hex = "414243";
+    my $bin = sodium_hex2bin($hex);
+    say $bin; # ABC
+
+The L<sodium_hex2bin|https://doc.libsodium.org/helpers#hexadecimal-encoding-decoding>
+function takes a hex string and turns it into a binary string.
+
+=head2 sodium_increment
+
+    use Sodium::FFI qw(sodium_increment);
+    my $x = "\x01";
+    $x = sodium_increment($x); # "\x02";
+
+The L<sodium_increment|https://doc.libsodium.org/helpers#incrementing-large-numbers>
+function takes an arbitrarily long unsigned number and increments it.
+
+=head2 sodium_library_minimal
+
+    use Sodium::FFI qw(sodium_library_minimal);
+    say sodium_library_minimal; # 0 or 1
+
+The C<sodium_library_minimal> function lets you know if this is a minimal version.
+
+=head2 sodium_library_version_major
+
+    use Sodium::FFI qw(sodium_library_version_major);
+    say sodium_library_version_major; # 10
+
+The C<sodium_library_version_major> function returns the major version of the library.
+
+=head2 sodium_library_version_minor
+
+    use Sodium::FFI qw(sodium_library_version_minor);
+    say sodium_library_version_minor; # 3
+
+The C<sodium_library_version_minor> function returns the minor version of the library.
+
+=head2 sodium_pad
+
+    use Sodium::FFI qw(sodium_pad);
+    say sodium_pad; # 3
+
+The L<sodium_pad|https://doc.libsodium.org/padding> function adds
+padding data to a buffer in order to extend its total length to a
+multiple of blocksize.
+
+=head2 sodium_version_string
+
+    use Sodium::FFI qw(sodium_version_string);
+    say sodium_version_string; # 1.0.18
+
+The C<sodium_version_string> function returns the stringified version information
+for the version of LibSodium that you have installed.
 
 =head1 COPYRIGHT
 

t/00-report-prereqs.t

@@ -3,7 +3,7 @@
 use strict;
 use warnings;
 
-# This test was generated by Dist::Zilla::Plugin::Test::ReportPrereqs 0.027
+# This test was generated by Dist::Zilla::Plugin::Test::ReportPrereqs 0.028
 
 use Test::More tests => 1;
 
@@ -188,6 +188,6 @@ if ( @dep_errors ) {
     );
 }
 
-pass;
+pass('Reported prereqs');
 
 # vim: ts=4 sts=4 sw=4 et:

t/11-utils.t

@@ -35,11 +35,17 @@ is($readable, 'cafe6942', "hex2bin: maxlen 4, ignore ': ': readable; Cafe : 6942
 # sodium_add, sodium_increment
 {
     my $left = "\xFF\xFF\x80\x01\x02\x03\x04\x05\x06\x07\x08";
-    sodium_increment($left);
+    is(sodium_bin2hex($left), 'ffff800102030405060708', 'bin2hex: Got the right answer');
+    $left = sodium_increment($left);
     is(sodium_bin2hex($left), '0000810102030405060708', 'increment, bin2hex: Got the right answer');
     my $right = "\x01\x02\x03\x04\x05\x06\x07\x08\xFA\xFB\xFC";
-    sodium_add($left, $right);
+    $left = sodium_add($left, $right);
     is(sodium_bin2hex($left), '0102840507090b0d000305', 'add, bin2hex: Got the right answer');
+    my $foo = 111;
+    is(sodium_add($foo, "111"), "bbb", 'add: non-lvalue test');
+    is($foo, 111, 'left side was unaltered');
+    $foo = sodium_add($foo, 111);
+    is($foo, 'bbb', 'sodium_add: right value');
 }
 
 # sodium_compare
@@ -48,9 +54,9 @@ SKIP: {
     my $v1 = "\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F";
     my $v2 = "\x02\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F";
     is(sodium_compare($v1, $v2), -1, 'sodium_compare: v1 < v2');
-    sodium_increment($v1);
+    $v1 = sodium_increment($v1);
     is(sodium_compare($v1, $v2), 0, 'sodium_compare: increment sets v1 == v2');
-    sodium_increment($v1);
+    $v1 = sodium_increment($v1);
     is(sodium_compare($v1, $v2), 1, 'sodium_compare: increment sets v1 > v2');
 };