StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POHow could you retrieve a method's POD from inside a REPL or debugger?
text
Body
copied!<p>I would like to be able to see the documentation of a method/function when using it inside REPL or debuger.</p> <p>Is there any module that allow you to see the documentation of a function when using REPL or a debuger?. </p> <p>Obviously if that module exist it would ask you to have your POD and code with a parseable structure in order to extract the docs. That is not a problem because I have all my code documented and I can adapt to whatever is needed. Currently I have all my methods with a preceding POD with a <code>=head2 method_name</code> and the typical lines for name, usage, example, args, return, exeptions etc</p> <p>The typical example is when you are in the debuger (or REPL) and you want to use a function and you don't remember the order of arguments or their types, or the type of the return element or you want a hint for the usage. </p> <p>I would like to have something like get_pod($moudle_bar, $method_foo), or even better being able to put a get_pod in a base module and being able to say <code>$bar->get_pod('foo')</code>. I know that this is not trivial and has a lot of corner cases. This is the reason that I am asking about a method-POD extractor module. </p> <p>I want to show the output inside the REPL or debuger so any pointer to an anchored html-pod in a browser is not convenient for me. </p> <p>It could be that there is something much more simple and I am obfuscated. </p> <p>My first <strong>brute force</strong> and expensive approach:</p> <pre><code>> $self = new MyModule > m $self # to see the available methods for double check the spelling > # method wanted '_connect_db' > $cmd = 'perldoc -t ' . ref($self) > x qx{$cmd}=~/(_connect_db.*?)\n\n/msg </code></pre> <pre> 0 '_connect_db Title : _connect_db Usage : Function: create a database conection and return the handler Example : $dbh = $self->_connect_db($user, $pass, $db_name) # host is FPrefect by default Returns : [0] DBI $dbh object Args : [0] $user, [1] $pass, [2] $db_name, [3] $host, [4] $db_brand # mysql, sqlite [5] $mode = (ro, rw) # not used now. in the future it would use this for read the user and password' </pre> <p>Obviously this works because I know that I don't have any empty lines in my method description PODs so I use <code>.*?)\n\n</code> in the regex to capture the rest of the method POD.</p> <p>Do someone have any good suggestion or advice for this task?</p> <p><strong>UPDATE:</strong></p> <p>Following <em>snoopy</em> suggestions I have taken a look at Pod::Coverage source code and I found that Pod::Coverage::Extractor (a package inside the file for Pod::Coverage) has the method <code>command</code> that look for Pods Item or head elements and extract them. I will take a look how to retrieve this items.</p> <pre><code># package Pod::Coverage::Extractor #extract subnames from a pod stream sub command { my $self = shift; my ( $command, $text, $line_num ) = @_; if ( $command eq 'item' || $command =~ /^head(?:2|3|4)/ ) { # take a closer look my @pods = ( $text =~ /\s*([^\s\|,\/]+)/g ); $self->{recent} = []; foreach my $pod (@pods) { print "Considering: '$pod'\n" if debug; # it's dressed up like a method cal $pod =~ /-E<\s*gt\s*>(.*)/ and $pod = $1; $pod =~ /->(.*)/ and $pod = $1; # it's used as a (bare) fully qualified name $pod =~ /\w+(?:::\w+)*::(\w+)/ and $pod = $1; # it's wrapped in a pod style B<> $pod =~ s/[A-Z]<//g; $pod =~ s/>//g; # has arguments, or a semicolon $pod =~ /(\w+)\s*[;\(]/ and $pod = $1; print "Adding: '$pod'\n" if debug; push @{ $self->{ $self->{nonwhitespace} ? "recent" : "identifiers" } }, $pod; } } </code></pre> <p><strong>UPDATE 2</strong></p> <p>Another place from where to take info is <a href="http://pdoc.sourceforge.net/scripts.html" rel="nofollow">pdoc</a>. This script generates html for browsing APIs and I use it in <a href="http://www.ensembl.org/info/docs/Pdoc/ensembl/index.html" rel="nofollow">Ensembl</a> and <a href="http://doc.bioperl.org/releases/bioperl-1.6.1/" rel="nofollow">BioPerl</a>. I am sure I will learn something reading the source code.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload