view release on metacpan or  search on metacpan

lib/Crypt/SecretBuffer/Span.pm  view on Meta::CPAN

this only removes the pattern once, unless you provide the C<MATCH_MULTI> flag or specify '+' on
the end of your regex.

The default pattern is C<< qr/[\s]+/ >>.

See L<Crypt::SecretBuffer/Match Flags> for the list of flags.

=over

=item ltrim

Only remove from the start of the Span

=item rtrim

Only remove from the end of the Span

=back

=head2 parse_lenprefixed

  $span= $span->parse_lenprefixed # count=1
    or croak $span->last_error;
  @spans= $span->parse_lenprefixed($count)
    or croak $span->last_error;
  @spans= $span->parse_lenprefixed(-1);

Parse one or more length-prefixed spans from the start of this span, returning a list of Span
objects and updating C<pos> if fully successful.  This first parses a variable-length
Base128-BigEndian integer, then ensures that there are that many bytes remaining in the span,
then creates a Span object describing those bytes and advances C<pos> and possibly repeats.
If the variable-length intgeer is malformed, or not enough bytes remain for the span, the method
returns an empty list and sets the L</last_error> attribute.
If you request a count greater than one, all the attempts must succeed or the method returns an
empty list and sets C<last_error>.  Requesting a count of C<-1> means to consume the remainder
of the span, which must terminate cleanly at the end of a length-prefixed string.

=head2 parse_base128be

  $len= $span->parse_base128be;

Parse a big-endian base128 encoding where the high-bit indicates continuation, same as
C<< unpack 'w' >>.  On failure, returns C<undef> and sets L</last_error>.

=head2 parse_base128le

  $len= $span->parse_base128le;

Parse a little-endian base128 encoding where the high-bit indicates continuation, such as used
by Google Protocol Buffers.  On failure, returns C<undef> and sets L</last_error>.

=head2 parse_asn1_der_length

  $len= $span->parse_asn1_der_length;

Parse the variable-length integer used by ASN.1 DER encoding for the length of an element.
On failure, returns C<undef> and sets L</last_error>.

=head2 consume_bom

  # On a buffer which may begin with a BOM:
  $span->consume_bom->cmp("\x{100}");

Look for an optional L<Byte-Order-Mark|https://en.wikipedia.org/wiki/Byte_order_mark> at the
start of the span, and if found, change the encoding and advance the span start to the next
character.

  First bytes       Encoding
  -----------       --------
  FE FF             UTF16BE
  FF FE             UTF16LE
  EF BB BF          UTF8

This returns the original Span object, with C<pos> and C<encoding> modified if a BOM was found.
This allows you to chain methods on a span object while conveniently processing the BOM.

This does not work if another encoding is being used to see those bytes, such as decoding BASE64.
A Span can have only one encoding, so if you need to decode BASE64 and then process a BOM, you
need to use L</copy> to create a new SecretBuffer of raw bytes, then decode the BOM.

=over

=item set_up_us_the_bom

Provided as an alias, for fun.

=back

=head2 starts_with

  $bool= $span->starts_with($pattern);

Return a boolean of whether $pattern matches from the start of the Span.

=head2 ends_with

  $bool= $span->ends_with($pattern);

Return a boolean of whether $pattern matches ending at the end of the Span.

=head2 scan

  $span= $span->scan($pattern, $flags=0);

Look for the first occurrence of a pattern in this Span.  Return a new Span describing where it
was found, or undef if not found.  The current Span is unchanged.
See L<Crypt::SecretBuffer/Match Flags> for the list of flags.

=head2 copy

=head2 copy_to

=head2 append_to

  $secret= $span->copy(%options);
  $span->copy_to($scalar_or_secret, %options);
  $span->append_to($scalar_or_secret, %options);

Copy the current span of bytes.  C<copy> returns a new SecretBuffer object.  C<copy_to> replaces
the content of a SecretBuffer or scalar.  C<append_to> appends to a SecretBuffer or scalar.
(There is intentionally I<not> a method to I<return> a scalar, to avoid easily leaking secrets)

Options:

=over

=item encoding => $encoding

Specify the encoding for the destination.  The bytes/characters are read from the current buffer
using the Span's C<encoding> attribute.  The default is to assume the same destination encoding
as the source and simply duplicate the byte string, *unless* the destination is a Perl scalar
and the source encoding was a type of unicode, in which case the default is to copy as Perl
"wide characters" (which is internally UTF-8).  If you specify UTF-8 here, you will receive
bytes of UTF-8 rather than perl wide characters.

=back

=head2 memcmp