Add ByteArray type

Changes

@@ -1,6 +1,6 @@
 Revision history for Neo4j::Types
 
-1.10  UNRELEASED
+1.11  UNRELEASED
 
  - Define scalar context for list methods to yield number of elements
  - Define properties() to behave the same in list context as in scalar context.
@@ -13,6 +13,7 @@ Revision history for Neo4j::Types
  - Fix loading of DateTime and Duration with "use Neo4j::Types".
  - Define methods and behaviour for the Neo4j 5 element ID.
  - Raise minimum required version of Perl to v5.10.1.
+ - Add ByteArray type.
 
 1.00  2021-01-18
 

dist.ini

@@ -6,7 +6,7 @@ license = Artistic_2_0
 copyright_holder = Arne Johannessen
 copyright_year   = 2021-2023
 
-version = 1.10
+version = 1.11
 release_status = unstable
 
 [@Author::AJNN]
@@ -16,7 +16,7 @@ PodWeaver.skip = Neo4j/Types/[^/]+\.pm
 [AutoPrereqs]
 ; don't mention modules that have been in core since the minimum supported Perl version
 skip = ^(?:lib|parent|strict|warnings|warnings::register)$
-skip = ^Carp$
+skip = ^(?:Carp|Encode)$
 
 [Git::Check]
 build_warnings = 1

lib/Neo4j/Types.pm

@@ -8,6 +8,7 @@ package Neo4j::Types;
 
 use warnings::register;
 
+use Neo4j::Types::ByteArray;
 use Neo4j::Types::DateTime;
 use Neo4j::Types::Duration;
 use Neo4j::Types::Node;

lib/Neo4j/Types/ByteArray.pm

@@ -0,0 +1,9 @@
+use v5.10.1;
+use strict;
+use warnings;
+
+package Neo4j::Types::ByteArray;
+# ABSTRACT: Represents a Neo4j byte array value
+
+
+1;

lib/Neo4j/Types/ByteArray.pod

@@ -0,0 +1,40 @@
+# PODNAME: Neo4j::Types::ByteArray
+# ABSTRACT: Represents a Neo4j byte array value
+
+=encoding UTF-8
+
+=head1 SYNOPSIS
+
+ $bytes = $bytearray->as_string;
+
+=head1 DESCRIPTION
+
+Represents a byte array value in Neo4j.
+Byte arrays are not a regular Cypher type, but are supported
+in Neo4j as a pass-through property type.
+
+Neo4j byte arrays may be returned from a Neo4j database server.
+Generic Neo4j byte array values may also be created locally.
+See L<Neo4j::Types::Generic/"ByteArray">.
+
+=head1 METHODS
+
+L<Neo4j::Types::ByteArray> specifies the following method.
+
+=head2 as_string
+
+ $bytes = $bytearray->as_string;
+
+Return the contents of the byte array as a scalar string.
+
+=head1 SEE ALSO
+
+=over
+
+=item * L<Neo4j::Types::Generic/"ByteArray">
+
+=item * L<Neo4j::Types::ImplementorNotes/"Byte array">
+
+=item * L<"Property types" in Neo4j Cypher Manual|https://neo4j.com/docs/cypher-manual/5/values-and-types/property-structural-constructed/#_property_types>
+
+=back

lib/Neo4j/Types/Generic.pod

@@ -16,6 +16,18 @@ be better optimised for use with the respective driver.
 As long as each of them performs the appropriate role
 from L<Neo4j::Types>, they should all be interchangeable.
 
+=head1 ByteArray
+
+Neo4j::Types::Generic::ByteArray offers the following method
+in addition to the one defined in L<Neo4j::Types::ByteArray>.
+
+=head2 new
+
+ $bytearray = Neo4j::Types::Generic::ByteArray->new( $bytes );
+
+Create a new generic Neo4j byte array value.
+The parameter C<$bytes> is expected to be a scalar string.
+
 =head1 DateTime
 
 Neo4j::Types::Generic::DateTime offers the following methods
@@ -129,6 +141,8 @@ dimensions, this method returns C<undef>.
 
 =item * L<Neo4j::Types>
 
+=item * L<Neo4j::Types::ByteArray>
+
 =item * L<Neo4j::Types::DateTime>
 
 =item * L<Neo4j::Types::Duration>

lib/Neo4j/Types/Generic/ByteArray.pm

@@ -0,0 +1,26 @@
+use v5.10.1;
+use strict;
+use warnings;
+
+package Neo4j::Types::Generic::ByteArray;
+# ABSTRACT: Generic representation of a Neo4j byte array
+
+
+use parent 'Neo4j::Types::ByteArray';
+
+use Encode ();
+
+
+sub new {
+	my ($class, $bytes) = @_;
+
+	$bytes .= '';
+	Encode::_utf8_off $bytes;
+	return bless \$bytes, $class;
+}
+
+
+sub as_string { ${$_[0]} }
+
+
+1;

lib/Neo4j/Types/ImplementorNotes.pod

@@ -248,20 +248,6 @@ and then follow whichever approach those other modules chose.
 
 The Cypher C<null> value can be neatly implemented as Perl C<undef>.
 
-=head2 Byte array
-
-Byte arrays are not actually Cypher types, but still have some
-limited support as pass-through values in Neo4j. In Perl, byte
-arrays are most efficiently represented as string scalars with
-their C<UTF8> flag turned off (though there may be some gotchas;
-see L<perlguts/"Working with SVs"> for details).
-
-However, it usually isn't possible to determine whether such a
-scalar actually is supposed to be a byte array or a string; see
-L<perlguts/"How can I recognise a UTF-8 string?">. In the future,
-the L<Neo4j::Types> distribution might be extended to offer ways
-to handle this.
-
 =head1 SPATIAL TYPES
 
 The only spatial type currently offered by Neo4j is the point.
@@ -386,6 +372,28 @@ Constructed types, formerly known as composite types, are:
 In Perl, these types match simple unblessed array and hash
 references very nicely.
 
+=head1 BYTE ARRAY
+
+Byte arrays are not first-class Cypher values, but still have some
+limited support as pass-through values in Neo4j.
+They may be represented as L<Neo4j::Types::ByteArray>.
+
+The recommended way to have your own module perform this role
+is to write an implementation for the following method,
+then declare L<Neo4j::Types::ByteArray> as a parent type.
+
+ package Local::ByteArray;
+ use parent 'Neo4j::Types::ByteArray';
+
+ sub as_string ($self) {...}
+
+You are free in your choice of the internal data structure.
+In Perl, byte arrays are most efficiently represented as string
+scalars with their C<UTF8> flag turned off.
+
+Additionally, you may wish to provide a C<new()> constructor
+for your module.
+
 =head1 SEE ALSO
 
 =over

t/types.t

@@ -6,11 +6,12 @@ use lib qw(lib);
 use Test::More 0.88;
 use Test::Warnings;
 
-plan tests => 8 + 1;
+plan tests => 9 + 1;
 
 
 require_ok 'Neo4j::Types';
 ok $INC{'Neo4j/Types.pm'}, 'use types';
+ok $INC{'Neo4j/Types/ByteArray.pm'}, 'use byte array';
 ok $INC{'Neo4j/Types/DateTime.pm'}, 'use node';
 ok $INC{'Neo4j/Types/Duration.pm'}, 'use node';
 ok $INC{'Neo4j/Types/Node.pm'}, 'use node';