Don't show declarator blocks with p6doc - documentation

I've written a small example file to learn more about Perl 6 POD, and I'm using p6doc to render a small manual page from the POD document. However, p6doc also tries to parse the declarator blocks outside the POD document. This doesn't look particularly great in the output. Is there a way to ignore the declarator blocks when using p6doc?
The code sample I'm using is:
#! /usr/bin/env perl6
use v6.c;
#| Greet people on the command line.
sub MAIN (
#| A name to greet.
$names,
#| Optional. Additional names to greet.
*#names,
) {
*
}
=begin pod
=NAME greeter
=AUTHOR Patrick Spek
=VERSION 0.0.1
The greeter application greets someone via a terminal. At least 1 name is
required, but multiple names can be given to greet many people in one go.
=end pod
And the output given by p6doc is:
sub MAIN(
$names, # A name to greet.
*#names, # Optional. Additional names to greet.
)
Greet people on the command line.
class $names
A name to greet.
class *#names
Optional. Additional names to greet.
NAME
greeter
AUTHOR
Patrick Spek
VERSION
0.0.1
The greeter application greets someone via a terminal. At least 1 name is
required, but multiple names can be given to greet many people in one go.
Everything before the NAME part is what I want to remove from the p6doc output.

declarator blocks outside the POD document.
A couple minor things that still seem worth a quick mention first:
It's considered best practice to call it pod (or Pod or Pod6 or POD6) rather than POD to distinguish it from P5's POD because it's not backwards compatible, in the same way P6 isn't backwards compatible with P5;
The syntax =begin pod ... =end pod doesn't declare "the pod document". It declares a pod block that's one of many that comprise the overall pod document. You can have several of them. And the reason for mentioning this is because declarator blocks are also pod blocks. This is why they get included.
Is there a way to ignore the declarator blocks when using p6doc?
You could run the output through a filter at the shell command level.
But see my next comment for what's likely a better way.
I'm using p6doc
p6doc is a wrapper around perl6 --doc.
perl6 --doc provides exactly the same result as you've shown in your question, but has an output post-processing option (and isn't limited to installed modules only).
Assuming you can switch to using perl6 --doc instead:
perl6 -doc, without an argument to the --doc option, uses the default pod output filter.
Using perl6 --doc=MyFilter.pm6 you can run the pod through an installed custom filter module Pod::To::MyFilter.pm6.
See a search of modules.perl6.org for pod::to for a full list of filters that you can use as examples.

Related

When to use inline backticks in documentation

When writing documentation, what things should be put in inline backticks?
For example I use inline backticks for the following,
commands
E.g. "To run the program, run python3 helloworld.py"
example output
E.g. "python3 helloworld.py should return hello world"
specific kubernetes resources
E.g. "Every pod except cache-deployer should be running"
However, should I also use it for e.g. group membership?
E.g. "User must be member of leet_users"
How do I do this consistently?

raku run('find .', :out); not working on MacOS

While testing around this issue, Can raku avoid this Malformed UTF-8 error? it was suggested that I try using the built in MacOS 'find .' command with the raku run function.
1 #!/usr/local/bin/raku
2
3 shell('find .'); #works
4
5 my $proc = run('find .', :out); #fails with
6 $proc.out.lines(:close).say; #() [ie. ().Seq]
Turns out that raku shell works fine, but raku run fails. I am not entirely sure if this is a bug with raku on MacOS (if so, I am happy to report it) ...?
[MacOS Catalina 10.15.17 ... Welcome to 𝐑𝐚𝐤𝐮𝐝𝐨™ v2020.10. Implementing the 𝐑𝐚𝐤𝐮™ programming language v6.d. Built on MoarVM version 2020.10.]
The issue you're running encountering isn't related to MacOS – it's caused by the difference in how &shell and &run work. Consulting the docs, we can see that shell's signature includes $cmd – the command as a Str, exactly as you provided.
In contrast, run's signature specifies that it takes *#args – that is, a list of zero or more arguments to execute.
To match this signature, you should change your code as shown below:
# my $proc = run('find .', :out); # doesn't work
my $proc = run('find', '.', :out); # works
my $p2 = run <find .>, :out; # also works (using word-splitting)
(Your version asked your computer to run the program find ., which doesn't exist in your $PATH, which explains why it produced no output.)

Print embedded Pod as formatted text with termcap escapes

I am trying to output embedded Pod as ANSI text to the terminal. In Perl 5 I can use Pod::Text::Termcap:
use strict;
use warnings;
use Pod::Text::Termcap;
my $str = do {local $/; <DATA>};
my $parser = Pod::Text::Termcap->new();
$parser->parse_string_document( $str, \*STDERR );
__DATA__
=head1 SYNOPSIS
my_test_command I<filename> [OPTIONS]
=head1 ARGUMENTS
=over 4
=item I<filename>
File name to test
=back
=head1 OPTIONS
=over 4
=item B<--help>
Prints help
=back
=head1 DESCRIPTION
A sample test command with embedded Pod
Output:
I tried to achieve the same in Perl 6:
use v6;
%*ENV<POD_TO_TEXT_ANSI> = 1;
my #lines;
for $=pod -> $pod-block {
for $pod-block.contents -> $pod-item {
use Pod::To::Text;
push #lines, pod2text($pod-item);
}
}
say #lines.join("\n\n");
=begin pod
=head1 SYNOPSIS
my_test_command I<filename> [OPTIONS]
=head1 ARGUMENTS
=item I<filename>
File name to test
=head1 OPTIONS
=item B<--help>
Prints help
=head1 DESCRIPTION
A sample test command with embedded Pod
=end pod
Output:
As seen the ANSI termcap escapes are missing in the Perl 6 output. How can I get ANSI features like bold face and underlined text in Perl 6?
Pod::To::Text accepts an environment variable POD_TO_TEXT_ANSI that turns this on. Setting that env var inside of a DOC phaser might be too late, though, if the selected Pod::To module is loaded before the perl 6 code is parsed however.
Regarding your question:
How can I get ANSI features like bold face and underlined text in Perl 6?
You might want to give Terminal::ANSIColor a try but you will need to add the ANSI escape codes yourself; it's not going to work automatically on PODs

Do Perl 6 programs have to compile to read embedded docs?

Perl 6 Plain-Old-Documentation (perhaps Fancy-New-Documentation) has some features that allow it to construct documentation for things it sees, and the documentation shows up in the $=pod variable at runtime.
However, I was surprised when I couldn't read the docs when I'd made an error in the program text. Here I've left out a statement separator between two statements:
use v6;
BEGIN { put "BEGIN" }
INIT { put "INIT" }
CHECK { put "CHECK" }
"foo" "bar";
DOC INIT { put "DOC INIT" }
DOC BEGIN { put "DOC BEGIN" }
DOC CHECK { put "DOC CHECK" }
=begin pod
=head1 This is a title
This is a bit of pod
=end pod
When I run it with the --doc switch, the program syntax matters (and BEGIN runs):
$ perl6 --doc doc.p6
BEGIN
===SORRY!=== Error while compiling ...
Two terms in a row
------> "foo"⏏ "bar";
expecting any of:
infix
infix stopper
statement end
statement modifier
statement modifier loop
When I fix it, I get some warnings (so, perl6 is compiling) and the compilation-time phasers run:
BEGIN
DOC BEGIN
DOC CHECK
CHECK
WARNINGS for /Users/brian/Desktop/doc.p6:
Useless use of constant string "bar" in sink context (line 9)
Useless use of constant string "foo" in sink context (line 9)
INIT
DOC INIT
This is a title
This is a bit of pod
We already know this is a bit dangerous in Perl 5. A perl -c and a BEGIN block can run code. See How to check if a Perl script doesn't have any compilation errors?. I don't think this is any more dangerous than something we already know, but now it's happening at a time when I'm not explicitly asking something to compile program statements.
I haven't delved into the details of Perl 6 pod and why this might be necessary outside of declarator blocks and .WHY (a cool feature), but it seems like this can lead to trouble. Is there perhaps an external program that might extract the Pod? Or a way to do without the declarators unless the program will run?
Yes, the whole file has to be parsed, which in turn requires running BEGIN and use statements and such.
The Perl 6 language is designed for one-pass parsing from top to bottom, so that at any given point the parser understands what it is parsing based on what it has parsed so far.
Consider code like the following:
say "
=begin pod
Not POD, just a string!
";
If you'd just grep the file for POD statements without parsing all of it, it would misinterpret this piece of code.
I.e. you can't parse only the POD parts without parsing the normal Perl 6 code parts, because without parsing it all from top to bottom you can't know which is which.
PS: In theory, the Perl 6 designers could have accommodated POD-only parsing, by making it illegal for normal Perl 6 code to contain lines that look like they start a POD block. In this scenario, the above code snippet would be a syntax error when the whole file is parsed, because starting a line inside a string literal with =begin pod would be disallowed, so the --pod switch could rely on all lines that begin with =begin foo actually starting a POD block.
Such a restriction probably wouldn't be a major burden for normal Perl 6 code (after all, who needs to write =begin pod at the start of a line in a multi-line string literal), but note that one of the reasons for the one-pass top-to-bottom parsing architecture is to facilitate language extensibility via slangs.
E.g. CPAN modules could add support for users writing a single subroutine (or other lexical scope) in another language or DSL. (Implementing such modules isn't actually possible yet without hacking into Rakudo internals via NQP, but once the macro/slang design is complete, it will be).
The burden for disallowing lines that look like they start a POD block, would then be passed on to all those slang parsers.
You could always submit a feature request for Larry and the other Perl 6 designers to consider this, though.

Git - how do I view the change history of a method/function?

So I found the question about how to view the change history of a file, but the change history of this particular file is huge and I'm really only interested in the changes of a particular method. So would it be possible to see the change history for just that particular method?
I know this would require git to analyze the code and that the analysis would be different for different languages, but method/function declarations look very similar in most languages, so I thought maybe someone has implemented this feature.
The language I'm currently working with is Objective-C and the SCM I'm currently using is git, but I would be interested to know if this feature exists for any SCM/language.
Recent versions of git log learned a special form of the -L parameter:
-L :<funcname>:<file>
Trace the evolution of the line range given by "<start>,<end>" (or the function name regex <funcname>) within the <file>. You may not give any pathspec limiters. This is currently limited to a walk starting from a single revision, i.e., you may only give zero or one positive revision arguments. You can specify this option more than once.
...
If “:<funcname>” is given in place of <start> and <end>, it is a regular expression that denotes the range from the first funcname line that matches <funcname>, up to the next funcname line. “:<funcname>” searches from the end of the previous -L range, if any, otherwise from the start of file. “^:<funcname>” searches from the start of file.
In other words: if you ask Git to git log -L :myfunction:path/to/myfile.c, it will now happily print the change history of that function.
Using git gui blame is hard to make use of in scripts, and whilst git log -G and git log --pickaxe can each show you when the method definition appeared or disappeared, I haven't found any way to make them list all changes made to the body of your method.
However, you can use gitattributes and the textconv property to piece together a solution that does just that. Although these features were originally intended to help you work with binary files, they work just as well here.
The key is to have Git remove from the file all lines except the ones you're interested in before doing any diff operations. Then git log, git diff, etc. will see only the area you're interested in.
Here's the outline of what I do in another language; you can tweak it for your own needs.
Write a short shell script (or other program) that takes one argument -- the name of a source file -- and outputs only the interesting part of that file (or nothing if none of it is interesting). For example, you might use sed as follows:
#!/bin/sh
sed -n -e '/^int my_func(/,/^}/ p' "$1"
Define a Git textconv filter for your new script. (See the gitattributes man page for more details.) The name of the filter and the location of the command can be anything you like.
$ git config diff.my_filter.textconv /path/to/my_script
Tell Git to use that filter before calculating diffs for the file in question.
$ echo "my_file diff=my_filter" >> .gitattributes
Now, if you use -G. (note the .) to list all the commits that produce visible changes when your filter is applied, you will have exactly those commits that you're interested in. Any other options that use Git's diff routines, such as --patch, will also get this restricted view.
$ git log -G. --patch my_file
Voilà!
One useful improvement you might want to make is to have your filter script take a method name as its first argument (and the file as its second). This lets you specify a new method of interest just by calling git config, rather than having to edit your script. For example, you might say:
$ git config diff.my_filter.textconv "/path/to/my_command other_func"
Of course, the filter script can do whatever you like, take more arguments, or whatever: there's a lot of flexibility beyond what I've shown here.
The closest thing you can do is to determine the position of your function in the file (e.g. say your function i_am_buggy is at lines 241-263 of foo/bar.c), then run something to the effect of:
git log -p -L 200,300:foo/bar.c
This will open less (or an equivalent pager). Now you can type in /i_am_buggy (or your pager equivalent) and start stepping through the changes.
This might even work, depending on your code style:
git log -p -L /int i_am_buggy\(/,+30:foo/bar.c
This limits the search from the first hit of that regex (ideally your function declaration) to thirty lines after that. The end argument can also be a regexp, although detecting that with regexp's is an iffier proposition.
git log has an option '-G' could be used to find all differences.
-G Look for differences whose added or removed line matches the
given <regex>.
Just give it a proper regex of the function name you care about. For example,
$ git log --oneline -G'^int commit_tree'
40d52ff make commit_tree a library function
81b50f3 Move 'builtin-*' into a 'builtin/' subdirectory
7b9c0a6 git-commit-tree: make it usable from other builtins
The correct way is to use git log -L :function:path/to/file as explained in eckes answer.
But in addition, if your function is very long, you may want to see only the changes that various commit had introduced, not the whole function lines, included unmodified, for each commit that maybe touch only one of these lines. Like a normal diff does.
Normally git log can view differences with -p, but this not work with -L.
So you have to grep git log -L to show only involved lines and commits/files header to contextualize them. The trick here is to match only terminal colored lines, adding --color switch, with a regex. Finally:
git log -L :function:path/to/file --color | grep --color=never -E -e "^(^[\[[0-9;]*[a-zA-Z])+" -3
Note that ^[ should be actual, literal ^[. You can type them by pressing ^V^[ in bash, that is Ctrl + V, Ctrl + [. Reference here.
Also last -3 switch, allows to print 3 lines of output context, before and after each matched line. You may want to adjust it to your needs.
Show function history with git log -L :<funcname>:<file> as showed in eckes's answer and git doc
If it shows nothing, refer to Defining a custom hunk-header to add something like *.java diff=java to the .gitattributes file to support your language.
Show function history between commits with git log commit1..commit2 -L :functionName:filePath
Show overloaded function history (there may be many function with same name, but with different parameters) with git log -L :sum\(double:filepath
git blame shows you who last changed each line of the file; you can specify the lines to examine so as to avoid getting the history of lines outside your function.