We consider to use Minilla or Dist::Milla for our perl development. Declaring dependencies is done via cpanfile. I expected to find an exact definintion of what and how can be declared. But
perldoc cpanfile :
Shows only the principal usage. 'SEE ALSO' section does not help.
perldoc Module::CPANfile: same as cpanfile.
perldoc cpanfile-faq: no explanation of the exact syntax or a link to it, only
Familiar DSL syntax
This is a new file type, but the format and syntax isn't entirely new.
The metadata it can declare is exactly a subset of "Prereqs" in
CPAN Meta Spec.
The syntax borrows a lot from Module::Install. Module::Install is a
great way to easily declare module metadata such as name, author and
dependencies. cpanfile format is simply to extract the dependencies
into a separate file, which means most of the developers are
familiar with the syntax.
Web : I found ( but does not answer my question )
https://speakerdeck.com/miyagawa/cpanfile
http://weblog.bulknews.net/post/44963580392/what-is-cpanfile-and-why-do-i-want-to-use-it
http://blogs.perl.org/users/lestrrat/2013/03/the-main-problem-with-cpan-modules-on-github.html
Does anybody know where to find an exact description of the cpanfile syntax/format ?
I installed Module::CPANFile and perldoc cpanfile and perldoc cpanfile-faq were available.
The POD for cpanfile states:
[the] cpanfile specification (this document) is based on Ruby's
Gemfile http://gembundler.com/man/gemfile.5.html specification.
The link in the cpanfile manual page is broken. It should point to: http://bundler.io/v1.3/man/gemfile.5.html
cpanfile is designed to "backwards compatible" with Module::Install DSL syntax and is "convertible to CPAN::Meta::Prereqs" and inspired by CPAN::Meta Spec v.2 etc.
As I understand it cpanfile is somewhat of a "meta-format" and fits into a range of TIMTOWTDI approaches (see miyagawa's blog describing cpanfile), compatible with Module::Install and mostly self-documenting. For example if you run mymeta-cpanfile inside a directory with META files it will build a cpanfile for you; you can write a script that describes prerequisites from CPAN::Meta::Prereqs and then $file->save('cpanfile'); to write a cpanfile.
As for Dist::Milla, in the tutorial (see the POD included with Dist::Milla) miyagawa points out that
"If you decide to manually construct [a] new cpanfile, the format is mostly compatible to Module::Install's requirement DSL". The tutorial also gives a short example.
I think it would be fair to ask miyagawa to clarify the status and use cases of the cpanfile specification/format in the documentation for the distribution. That and a few more examples would answer questions like yours. He has mostly done the work on this already - it is just not all in one place.
Related
Suppose that, as a private project, I have implemented a Perl package, and tested it, both formally and through extensive everyday use. I find the package useful and solid enough to warrant submitting it to CPAN.
Up to this point, since the package has been a private project, I have not worried too much about the package's name, but now that I want to submitted to CPAN, however, I would like the package's name to fit well within the ecology of package names already in CPAN.
In order to find a suitable "CPAN name" for my package, I would have to inspect a comprehensive listing of all these package names1.
What is the simplest way to get this comprehensive listing of names of packages in CPAN?
ObPedantry
(IOW, if the question above is already clear enough for you, you may safely ignore what follows.)
I don't think that I can give a technically correct formal definition of what I mean here by "package name", so let me at least give an "operational definition".
If, for example, the one-liner
$ perl -MFoo::Bar::Baz -c -e 1
fails with an error beginning with
Can't locate Foo/Bar/Baz.pm in #INC ...
..., but after installing some distributions from CPAN, the same oneliner succeeds with
-e syntax OK
...then I'll say that "Foo::Bar::Baz is a package name in CPAN".
(We could split hairs over the package/module distinction, and consider scenarios in which the distinction matters, but please let's not.)
Furthermore, if after inspecting the list this question asks about I discover that, on the one hand, there are in fact many eminent package names in CPAN that begin with the prefix Foo::Bar::, and on the other, there are none (or negligibly few) that begin with the prefix Fubar::, then this would be a good enough reason for me to change the name of my Fubar::Frobozz package to Foo::Bar::Frobozz before submitting it to CPAN.
1 Of course, after inspecting such a list, I may discover that my package does not add sufficiently new functionality relative to what's already available in CPAN to warrant submitting my package to CPAN after all.
If you have run cpan before, you have downloaded a comprehensive package and distribution list under <cpan-home>/sources/modules/02packages.details.txt.gz.
A fresh copy is available on any CPAN mirror, e.g.
http://www.cpan.org/modules/02packages.details.txt.gz .
PAUSE::Packages can do what you want, however you probably want to use this list, but http://prepan.org/ can provide advice/review before submission to cpan, with of course reading on the naming of modules first.
Are you sure that's a thing you want? There are 33,623 distributions on CPAN at the time of writing. Within cpan you can enter
cpan> d /./
That's d for distributions followed by a regex pattern that matches the names you're interested in
If you're really interested in packages -- and a distribution may contain multiple package names -- you need
cpan> m/./
where m is for modules. There are 163,136 of those, which means there's an average of four or five packages per distribution, and it takes cpan a few minutes to generate the list. (I'm sorry, I didn't monitor the exact time.)
You could use MetaCPAN::Client
I found this article which gives the idea about using this module.
#!/usr/bin/perl
use strict; use warnings; use MetaCPAN::Client;
my $mcpan = MetaCPAN::Client->new();
my $release_results = $mcpan->release({ status => 'latest' } );
while ( my $release = $release_results->next ) {
printf "%s v%s\n", $release->distribution, $release->version;
}
Currently this gave me 32601 result like this:
Proc-tored v0.11
Locale-Utils-PlaceholderBabelFish v0.004
Perinci-To-Doc v0.83
Mojolicious-Plugin-Qooxdoo v0.905
App-cdnget v0.05
Baal-Parser v0.01
Acme-DoOrDie v0.001
Net-Shadowsocks v0.9.0
MetaCPAN-Client v2.006000
This modules also gives information about release, module, author, and file & uses Elasticsearch.
It also get updated regularly on every MetaCPAN API change.
Searching for Devel::Peek at metacpan.org gives the following screen shot:
Why is the module listed three times? (It looks a little bit strange, and could easily confuse the user..)
Oddly enough, there's one missing. The following are Devel::Peek's official distributions:
perl
Devel-Peek
These two distributions are returned when searching search.cpan.org, and the only two distributions returned when searching search.cpan.org.
Being part of the perl distribution and part of its own distribution is called being a "dual-lifed" module. It allows the module to be bundled with Perl without having to upgrade Perl to upgrade the module.
I don't know why meta::cpan doesn't pick up the official distribution, and I don't know why it doesn't flag the other distributions as unofficial. You could alert the site's maintainers of the problem.
Conversely, I don't know why search.cpan.org doesn't return CookBookA and CookBookB, and why it doesn't flag theses other distributions as unofficial when one goes to it directly. I think it has to do with the fact that Devel::Peek is only present as a documentation file (.pod) —not a module (.pm)— in them.
This is naive question for which I struggled to find an elegant solution. I write perl scripts that as they mature, grow in the number of options passed to GetOptions. The important options for the script, I add on top as POD documentation, but I rely on giving meaningful names to the other options, and I don't bother to document them explicitly.
I would like to pass the hash in GetOptions somehow to the content printed by perldoc, so that the non-documented options is listed there. Any option?
perldoc parses pod. You'd have to write a script to modify your .pl's pod based on values obtained by running your .pl... Yeah, that doesn't sound like a good idea.
You might be interested in Getopt::Euclid, Docopt, Getopt::Auto or Getopt::AsDocumented. These take the opposite approach: You define the options in the documentation, and they parse the documentation to determine how to process the command line.
I ralize that your point of view is code first and document later the things that become stable. That is fair when you need to write twice docs and code. But nowadays that is not true. My recomendation for prototyping is write the manpage and use a module that create the code of the options for you.
My favorite in perl and python is docopt (and has implementations for many other languages). Here you can find the Perl Docopt
I asked about perl implementatios for docopt long time ago in stackoverflow and I was pointed to the docopt module and other options like Getopt::Euclid, Getopt::Auto and Getopt::AsDocumented
Related with your concern about not incrementing cpan dependencies,
in python Docopt is selfcontained but I think it is not true for perl implementation which depends on
boolean,
Class::Accessor::Lite,
List::MoreUtils,
List::Util,
parent,
Pod::Usage
and
Scalar::Util; and the dependencies of the dependencies....
If the perl Docopt implementation is not as small and selfcontained as the original Python then probably is time to give it wider usage and start to fill feature/implementation requests because, IMHO, the doctopt way of doing things is ONE of the many ways of doing the things right.
Finally here you have a talk about the why of docopt. It is about python but command line interfaces logic and UX are the same for all the languages: PyCon UK 2012: Create beautiful command-line interfaces with Python
Is there any way to write multilanguage documentation using POD? If no, what should I write it in (I already have POD documentation in English, so I will want to convert it and then translate)?
If you're asking whether POD supports non-English encoding, the answer is a resounding YES. Here's an example of brian d foy's article (in POD format) translated into Russian: http://perlrussia.ru/article/brians-guide/brian%27s_guide.ru.pod
If you are wondering if it's possible to stick multi-language POD into the same file, there's a fairly curious example here:
http://cpansearch.perl.org/src/HIO/Unicode-Japanese-0.47/lib/Unicode/Japanese.mlpod
It uses Pod::Multilang
However, i'm not entirely certain how (or even if) it works, as I could not find two examples of html generated straight from that mlpod.
See http://perldoc2.sourceforge.net/ - this is a project for international perldoc
If you're preparing your module for distribution on CPAN, create separate .pod files for the translations of your documentation.
For example, if you have included the English documentation in My/Module.pm, you could create the files My/Module-jp.pod, My/Module-ru.pod, etc.:
=head1 NAME
My::Module-pl - Atin-lay Ig-pay ocumentation-day or-fay y-may odule-may
=head1 ERSION-VAY
1.01
=head1 ESCRIPTION-DAY
...
How can I list all CPAN modules depending on a given module? For example, create a list of modules using Class::Workflow?
There's two valid questions about dependencies:
What modules does the given module require?
The reversed question: Which modules depend on the given module?
For the former, the authoritative but non-recursive answer is usually to look at the META.yml file that's part of most modern distributions. If there is no such file, you may try looking at the Makefile.PL or Build.PL build tools that ship with it. If you want to know all dependencies and not just the direct ones, cf. ghostdog74's answer. Specifically, David Cantrell's 'CPANDeps' is very, very handy.
Obviously, the latter question is impossible to answer by inspecting the module itself. If you don't want to grep an unpacked minicpan, the best solution is something like the "used by" section of a module's CPANTS entry.
you can use a module such as CPAN::Dependency, or try this online , among many others.
I’ve found CPAN::Dependency and CPAN::FindDependencies on CPAN, they might help you.
Some other options:
Module::ScanDeps
Perl::PrereqScanner