Re: Name space for XML Invoice Parser

[Johannes Grassler]

Hello,

Thanks for your response!

On Tue, Jun 11, 2024 at 03:28:58PM +0100, Neil Bowers wrote:
> I think the namespace XML::Invoice is fine.

Ok, that's a start.

> I thought it would be helpful to mention a namespace / permissions
> constraint you should be aware of, for CPAN.  I'm guessing that your
> parser produces objects that are instances of XML::Invoice?

Not quite. It produces instances of XML::Invoice::Parser because I may
add another package XML::Invoice::Generator in the future.

> I would call the CPAN distribution XML-Invoice, and assume it would
> contain at least two classes: XML::Invoice and XML::Invoice::Parser?

The top level class is XML::Invoice::Parser with various subclasses such
as XML::Invoice::Parser::CrossIndustryInvoice or
XML::Invoice::Parser::UBL. There is no XML::Invoice class right now.

> And a later release might also include XML::Invoice::Generator.

Yes.

> When you release something to CPAN (by uploading it to PAUSE), you
> must have a module with a name that corresponds to the distribution
> name.

Yes...right now I have a module XML::Invoice::Parser (residing in
lib/XML/Invoice/Parser.pm) in there. The distribution is called
XML-Invoice-Parser.

> So if you release a distribution XML-Invoice, it has to contain a
> module XML::Invoice, and either (a) there are currently no indexing
> permissions on XML:::Invoice (in which case you'll be granted the
> first-come indexing permission), or (b) you already have an indexing
> permission (either first-come or co-maint) on XML::Invoice.

So this is where I am probably running into the constraint you
mention:

> We occasionally see problems where someone releases a distribution
> with a name like Image-Formats which contains Image::Formats::PNG,
> Image::Formats::JPEG, etc, but no Image::Formats module.

I do indeed not have a lib/XML/Invoice.pm right now:

  https://github.com/jgrassler/XML-Invoice-Parser/tree/master/lib/XML/Invoice

> This constraint was added to PAUSE so that people couldn't jump in and
> snatch the first-come indexing permission on a module name that
> clearly should be associated with some existing module names.

...and this is kind of what I am planning on doing right now. So do you
think it would be ok to snatch the XML::Invoice name space with bare
lib/XML/Invoice.pm that merely declares the package XML::Invoice?

> The other option is that you could call your parser
> XML::InvoiceParser, and have XML::InvoiceParser::Invoice for the
> invoice objects. But I think that's clunky, and leaves XML::Invoice
> unclaimed, for someone else to bag.

Yeah, that's clunky indeed. I'd rather avoid that.

So just to make sure I understand: if I released the module as-is with
XML::Invoice::Parser being the top level module, I'd leave XML::Invoice
for someone else to bag, right?

Cheers,

Johannes

-- 
Phone:   +49 176 24 24 20 83 WWW: http://btw23.de/johannes/

GPG Key fingerprint: 2A3F 5FEC D752 944C BD9C  B25A 651A B200 1434 C358

Re: Name space for XML Invoice Parser

[Neil Bowers]

Hi Johannes,

I think the namespace XML::Invoice is fine. I thought it would be helpful to 
mention a namespace / permissions constraint you should be aware of, for CPAN.

I'm guessing that your parser produces objects that are instances of 
XML::Invoice?

I would call the CPAN distribution XML-Invoice, and assume it would contain at 
least two classes: XML::Invoice and XML::Invoice::Parser? And a later release 
might also include XML::Invoice::Generator.

When you release something to CPAN (by uploading it to PAUSE), you must have a 
module with a name that corresponds to the distribution name. So if you release 
a distribution XML-Invoice, it has to contain a module XML::Invoice, and either 
(a) there are currently no indexing permissions on XML:::Invoice (in which case 
you'll be granted the first-come indexing permission), or (b) you already have 
an indexing permission (either first-come or co-maint) on XML::Invoice. We 
occasionally see problems where someone releases a distribution with a name 
like Image-Formats which contains Image::Formats::PNG, Image::Formats::JPEG, 
etc, but no Image::Formats module. This constraint was added to PAUSE so that 
people couldn't jump in and snatch the first-come indexing permission on a 
module name that clearly should be associated with some existing module names.

The other option is that you could call your parser XML::InvoiceParser, and 
have XML::InvoiceParser::Invoice for the invoice objects. But I think that's 
clunky, and leaves XML::Invoice unclaimed, for someone else to bag.

Neil
On Jun 11, 2024 at 2:20 PM +0100, Johannes Grassler , wrote:
> Hello,
>
> I wrote a parser module for various XML based invoice formats, mainly
> EN16931[0] ones, that turns them into Perl objects:
>
> https://github.com/jgrassler/XML-Invoice-Parser
>
> I originally contributed this module to the ERP system Kivitendo[3].
> Subsequently, I have been getting a bit tired of copying and pasting
> the code from that module into various command line tools I've written
> for personal use. Since others may also find it similarly useful, I'd
> like to release it as a standalone module.
>
> Now I've been pondering what name space to put it in. I've settled on
> XML::Invoice::Parser for now since it's designed to be extensible to
> cover other XML based invoice formats[2]. Also, the XML::Invoice
> namespace can at a later stage be used for a generator module I am
> toying with the idea of writing.
>
> Does that sound sensible or does anyone have a better suggestion?
>
> Cheers,
>
> Johannes
>
>
> Footnotes:
>
> [0] A EU standard that's either already law or being legislated
> as mandatory format for B2B invoices in EU member states.
> [1] https://github.com/kivitendo/kivitendo-erp/tree/master/SL/XMLInvoice
> [2] I am quite sure there is going to be no shortage of committees
> itching to come up with additional formats and new revisions in
> the foreseeable future.
>
> --
> WWW: http://btw23.de/johannes/
> GPG Key fingerprint: 2A3F 5FEC D752 944C BD9C B25A 651A B200 1434 C358