--- Convert-BER-XS/XS.pm	2019/04/20 13:48:53	1.18
+++ Convert-BER-XS/XS.pm	2019/04/20 14:45:03	1.19
@@ -75,6 +75,83 @@
 If is tuned for low memory and high speed, while still maintaining some
 level of user-friendlyness.
 
+=head2 EXPORT TAGS AND CONSTANTS
+
+By default this module doesn't export any symbols, but if you don't want
+to break your keyboard, editor or eyesigh with extreemly long names, I
+recommend importing the C<:all> tag. Still, you can selectively import
+things:
+
+=over
+
+=item :all
+
+All of the below. Really. Rcommended for at least first steps, or if you
+don't care about a few kilobytes of wasted memory (and namespace).
+
+=item :const
+
+All of the stricly ASN.1-related constants defined by this module, the
+same as C<:const_asn :const_index>. Notably, this does not contain
+C<:const_ber_type> and C<:const_snmp>.
+
+A good set to get everything you need to decode and match BER data would be
+C<:decode :const>.
+
+=item C<:const_index>>
+
+The BER tuple array index constants:
+
+        BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
+
+=item C<:const_asn>
+
+ASN class values (these are C<0>, C<1>, C<2> and C<3>, reespectively -
+exactly thw two topmost bits from the identifdier octet shifted 6 bits to
+the right):
+
+      ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
+
+ASN tag values (some of which are aliases, such as C<ASN_OID>). Their
+numerical value corresponds exactly to the numbers used in BER/X.690.
+
+      ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
+      ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
+      ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
+      ASN_PRINTABLE_STRING ASN_TELETEX_STRING ASN_T61_STRING ASN_VIDEOTEX_STRING ASN_IA5_STRING
+      ASN_ASCII_STRING ASN_UTC_TIME ASN_GENERALIZED_TIME ASN_GRAPHIC_STRING ASN_VISIBLE_STRING
+      ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
+
+=item C<:const_ber_type>
+
+The BER type constants, explained in the PROFILES section.
+
+      BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
+      BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
+      BER_TYPE_IPADDRESS BER_TYPE_CROAK
+
+=item C<:const_snmp>
+
+Constants only relevant to SNMP. These are the tag values used by SNMP in
+the C<ASN_APPLICATION> namespace and have the exact numerical value as in
+BER/RFC 2578.
+
+      SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
+
+=item C<:decode>
+
+C<ber_decode> and the match helper functions:
+
+      ber_decode ber_is ber_is_seq ber_is_i32 ber_is_oid
+
+=item C<:encode>
+
+C<ber_encode> and the construction helper functions:
+
+      ber_encode ber_i32
+
+=back
+
 =head2 ASN.1/BER/DER/... BASICS
 
 ASN.1 is a strange language that can be used to describe protocols and
@@ -296,9 +373,10 @@
 }
 
 our %EXPORT_TAGS = (
-   const => [qw(
+   const_index => [qw(
       BER_CLASS BER_TAG BER_CONSTRUCTED BER_DATA
-
+   )],
+   const_asn => [qw(
       ASN_BOOLEAN ASN_INTEGER32 ASN_BIT_STRING ASN_OCTET_STRING ASN_NULL ASN_OBJECT_IDENTIFIER
       ASN_OBJECT_DESCRIPTOR ASN_OID ASN_EXTERNAL ASN_REAL ASN_SEQUENCE ASN_ENUMERATED
       ASN_EMBEDDED_PDV ASN_UTF8_STRING ASN_RELATIVE_OID ASN_SET ASN_NUMERIC_STRING
@@ -307,7 +385,8 @@
       ASN_ISO646_STRING ASN_GENERAL_STRING ASN_UNIVERSAL_STRING ASN_CHARACTER_STRING ASN_BMP_STRING
 
       ASN_UNIVERSAL ASN_APPLICATION ASN_CONTEXT ASN_PRIVATE
-
+   )],
+   const_ber_type => [qw(
       BER_TYPE_BYTES BER_TYPE_UTF8 BER_TYPE_UCS2 BER_TYPE_UCS4 BER_TYPE_INT
       BER_TYPE_OID BER_TYPE_RELOID BER_TYPE_NULL BER_TYPE_BOOL BER_TYPE_REAL
       BER_TYPE_IPADDRESS BER_TYPE_CROAK
@@ -315,11 +394,11 @@
    const_snmp => [qw(
       SNMP_IPADDRESS SNMP_COUNTER32 SNMP_UNSIGNED32 SNMP_TIMETICKS SNMP_OPAQUE SNMP_COUNTER64
    )],
-   encode => [qw(
+   decode => [qw(
       ber_decode
       ber_is ber_is_seq ber_is_i32 ber_is_oid
    )],
-   decode => [qw(
+   encode => [qw(
       ber_encode
       ber_i32
    )],
@@ -328,6 +407,8 @@
 our @EXPORT_OK = map @$_, values %EXPORT_TAGS;
 
 $EXPORT_TAGS{all} = \@EXPORT_OK;
+$EXPORT_TAGS{const} = [map @{ $EXPORT_TAGS{$_} }, qw(const_index const_asn)];
+use Data::Dump; ddx \%EXPORT_TAGS;
 
 =head1 PROFILES
 
@@ -482,6 +563,7 @@
 our $DEFAULT_PROFILE = new Convert::BER::XS::Profile;
 our $SNMP_PROFILE    = new Convert::BER::XS::Profile;
 
+# additional SNMP application types
 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_IPADDRESS , BER_TYPE_IPADDRESS);
 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_COUNTER32 , BER_TYPE_INT);
 $SNMP_PROFILE->set (ASN_APPLICATION, SNMP_UNSIGNED32, BER_TYPE_INT);
@@ -493,15 +575,20 @@
 
 1;
 
-=head2 LIMITATIONS
+=head2 LIMITATIONS/NOTES
 
 This module can only en-/decode 64 bit signed and unsigned integers, and
 only when your perl supports those.
 
+This module does not generally care about ranges, i.e. it will happily
+de-/encode 64 bit integers into an C<ASN_INTEGER32> value, or a negative
+number into an C<SNMP_COUNTER64>.
+
 OBJECT IDENTIFIEERs cannot have unlimited length, although the limit is
-much larger than e.g. the one imposed by SNMP or other protocols.
+much larger than e.g. the one imposed by SNMP or other protocols,a nd is
+about 4kB.
 
-REAL values are not supported and will croak.
+REAL values are not supported and will currently croak.
 
 This module has undergone little to no testing so far.