NAME
Convert::VLQ - Convert to and from VLQ base64 representation used in source maps
SYNOPSIS
use Convert::VLQ qw( encode_vlq decode_vlq );
my $encoded = encode_vlq( 15 );
my $AAAA = encode_vlq( [0,0,0,0] );
my( $int, $rest ) = decode_vlq( "A" );
my $array = decode_vlq( "AAAA" );DESCRIPTION
Functions to encode and decode base64 VLQ representations of line and column numbers used in browser source maps.
A variable-length quantity (VLQ) is a universal code that uses an arbitrary number of binary octets (eight-bit bytes) to represent an arbitrarily large integer. A VLQ is essentially a base-128 representation of an unsigned integer with the addition of the eighth bit to mark continuation of bytes.
- https://en.wikipedia.org/wiki/Variable-length_quantity
Base64 is a binary-to-text encoding that uses 64 printable characters to represent each 6-bit segment of a sequence of byte values.
- https://en.wikipedia.org/wiki/Base64
FUNCTIONS
encode_vlq
# 0 becomes "A"
my $encoded = encode_vlq( $number );
# [0,0,0,0] becomes "AAAA"
my $mapping = encode_vlq( [$src_row, $src_col, $dest_row, $dest_col] );Converts one or more numbers into a string.
If passed a single number, returns the VLQ base64 representation of that number.
If passed an array ref, it returns a concatination of the VLQ base64 represtation of all the numbers in the array.
Will return undef if you pass it undef.
decode_vlq
# "AAAA" becomes [0,0,0,0]
my $map = encode_vlq( $mapping );
my( $src_row, $src_col, $dest_row, $dest_col ) = @$map;
# "AAAA" becomes (0,"AAA")
my( $number, $remaining ) = encode_vlq( $mapping );Converts the VLQ base64 representation back to an arrayref of integers.
If called in an array context, decode_vlq returns the first integer and the remaining string as an array.
int2vlqs
use Convert::VLQ qw( int2vlqs );
my $vlqs = int2vlqs( $int );Converts an integer into a signed VLQ.
vlqs2int
use Convert::VLQ qw( int2vlqs );
my $int = vlqs2int( $vlqs );Converts a signed VLQ into an integer.
NOTES
Javascript integers are limited to 32 bits. We do not enforce this limit.
SEE ALSO
https://en.wikipedia.org/wiki/Variable-length_quantity, https://tc39.es/ecma426/#sec-base64-vlq
AUTHOR
Philip Gwyn, <gwyn -at- cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2026 by Philip Gwyn
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.26.3 or, at your option, any later version of Perl 5 you may have available.