NAME

X500::DN::Marpa::DN - Backcompat module to emulate the DN part of X500::DN

Synopsis

This is scripts/back.compat.pl:

#!/usr/bin/env perl

use strict;
use warnings;

use X500::DN::Marpa::DN;
use X500::DN::Marpa::RDN;

# -----------------------

print "Part 1:\n";

my($dn)   = X500::DN::Marpa::DN -> new;
my($text) = 'foo=FOO + bar=BAR + frob=FROB, baz=BAZ';

$dn -> ParseRFC2253($text);

print "Parsing:     $text\n";
print 'RDN count:   ', $dn -> getRDNs, " (Expected: 2)\n";
print 'DN:          ', $dn -> getRFC2253String, " (Expected: baz=BAZ,foo=FOO+bar=BAR+frob=FROB)\n";
print 'X500 string: ', $dn -> getX500String, " (Expected: {foo=FOO+bar=BAR+frob=FROB+baz=BAZ})\n";
print '-' x 50, "\n";
print "Part 2:\n";

my($rdn)       = $dn -> getRDN(0);
my $type_count = $rdn -> getAttributeTypes;
my(@types)     = $rdn -> getAttributeTypes;

print 'RDN(0):      ', $rdn -> dn, "\n";
print "Type count:  $type_count (Expected: 3)\n";
print "Type [0]:    $types[0] (Expected: foo)\n";
print "Type [1]:    $types[1] (Expected: bar)\n";

my(@values) = $rdn -> getAttributeValue('foo');

print "Value [0]:   $values[0] (Expected: FOO+bar=BAR+frob=FROB)\n";

my($has_multi) = $dn -> hasMultivaluedRDNs;

print "hasMulti:    $has_multi (Expected: 1)\n";
print '-' x 50, "\n";
print "Part 2:\n";

$rdn = $dn -> getRDN(1);

@values = $rdn -> getAttributeValue('baz');

print 'RDN(1):      ', $rdn -> dn, "\n";
print "Value [0]:   $values[0] (Expected: BAZ)\n";
print '-' x 50, "\n";

Output of scripts/back.compat.pl:

Part 1:
Parsing:     foo=FOO + bar=BAR + frob=FROB, baz=BAZ
RDN count:   2 (Expected: 2)
DN:          baz=BAZ,foo=FOO+bar=BAR+frob=FROB (Expected: baz=BAZ,foo=FOO+bar=BAR+frob=FROB)
X500 string: {foo=FOO+bar=BAR+frob=FROB+baz=BAZ} (Expected: {foo=FOO+bar=BAR+frob=FROB+baz=BAZ})
--------------------------------------------------
Part 2:
RDN(0):      foo=FOO+bar=BAR+frob=FROB
Type count:  3 (Expected: 3)
Type [0]:    foo (Expected: foo)
Type [1]:    bar (Expected: bar)
Value [0]:   FOO+bar=BAR+frob=FROB (Expected: FOO+bar=BAR+frob=FROB)
hasMulti:    1 (Expected: 1)
--------------------------------------------------
Part 2:
RDN(1):      baz=BAZ
Value [0]:   BAZ (Expected: BAZ)
--------------------------------------------------

Description

X500::DN::Marpa::DN provides a Marpa::R2-based parser for parsing X.500 Distinguished Names.

This module emulates the DN parts of X500::DN.

Notes:

o X500::DN: This module was based on the obsolete RFC2253: Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names.
o X500::DN::Marpa and X500::DN::Marpa::DN: These modules are based on RFC4514: Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Installation

Install X500::DN::Marpa as you would any Perl module:

Run:

cpanm X500::DN::Marpa

or run:

sudo cpan X500::DN::Marpa

or unpack the distro, and then either:

perl Build.PL
./Build
./Build test
sudo ./Build install

or:

perl Makefile.PL
make (or dmake or nmake)
make test
make install

Constructor and Initialization

new() is called as my($parser) = X500::DN::Marpa::DN -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type X500::DN::Marpa::DN.

Key-value pairs accepted in the parameter list (see corresponding methods for details:

o (None)

Methods

This module is a subclass of X500::DN::Marpa and shares all its options to new(), and all its methods. See "Constructor and Initialization" in X500::DN::Marpa and "Methods" in X500::DN::Marpa.

Further, it has these methods:

getRFC2253String()

Returns the DN as a string.

And yes, it's really based on RFC4514, as it says in the "Description".

The DN is what was passed to "ParseRFC2253($dn)".

getRDN($n)

Returns an object of type X500::DN::Marpa::RDN, containing the $n-th RDN, or returns '' if $n is out of range.

$n counts from 0.

The returned object has already parsed the RDN, so you use that object via the methods documented in X500::DN::Marpa::RDN.

If the input is 'UID=nobody@example.com,DC=example,DC=com', rdn(0) returns an object which has parsed 'uid=nobody@example.com'. Note the lower-case 'uid'.

Warning: The parent class X500::DN::Marpa counts RDNs from 1.

getRDNs()

Returns the number of RDNs in the DN parsed.

getX500String()

Returns what X500::DN calls an X500 version of the DN.

hasMultivaluedRDNs()

Returns a Boolean, 0 meaning there are no multvalued RDNs, and 1 meaning there is at least 1 such RDN.

new()

See "Constructor and Initialization" for details on the parameters accepted by "new()".

ParseRFC2253($dn)

Parses $dn and returns $self (sic).

This has to be the first method (after "new()" of course) which you call on an object of type X500::DN::Marpa::DN.

So, you are expected to do this:

my($parser) = X500::DN::Marpa::DN -> new;

$parser -> ParseRFC2253($a_dn);

And to just ignore the return value. After this, you call methods on $parser.

If you do this:

my($parser) = X500::DN::Marpa::DN -> new;
my($dn)     = $parse -> ParseRFC2253($a_dn);

It will work of course, but you have 2 copies of $parser, and you (probably) call methods on $dn.

So, you could do this:

my($dn) = X500::DN::Marpa::DN -> new -> ParseRFC2253($a_dn);

And just ignore the intermediary copy, which has been discarded. After this, you call methods on $dn.

This means that to patch old code, just convert:

my($dn) = X500::DN -> ParseRFC2253

Into:

my($dn) = X500::DN::Marpa::DN -> new -> ParseRFC2253

FAQ

See "FAQ" in X500::DN::Marpa.

How to I transition to `X500::DN::Marpa::DN` before switching to `X500::DN::Marpa`?

See scripts/back.compat.pl.

How do I upgrade code from `X500::DN` to `X500::DN::Marpa`?

See scripts/synopsis.pl.

You can think of scripts/synopsis.pl as scripts/forward.compat.pl!

How do you handle attribute values in double-quotes?

RFC4514 does not discuss this topic.

So, I ignore the quotes, because I assume none of your other software accepts them anyway, since you're not using them any more, right?

References

See "References" in X500::DN::Marpa.

Machine-Readable Change Log

The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Repository

https://github.com/ronsavage/X500-DN-Marpa

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=X500::DN::Marpa.

Author

X500::DN::Marpa was written by Ron Savage <ron@savage.net.au> in 2015.

Marpa's homepage: http://savage.net.au/Marpa.html.

My homepage: http://savage.net.au/.

Copyright

All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License 2.0, a copy of which is available at:
http://opensource.org/licenses/alphabetical.

To install X500::DN::Marpa, copy and paste the appropriate command in to your terminal.

cpanm

cpanm X500::DN::Marpa

CPAN shell

perl -MCPAN -e shell
install X500::DN::Marpa

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)