This question already has answers here:
Closed 12 years ago.
Possible Duplicate:
What are the common workarounds for multi-line comments in Perl?
How do I add a multi-line comment to Perl source code?
POD is the official way to do multi line comments in Perl,
see Multi-line comments in perl
code and
Better ways to make multi-line comments in Perl for more
detail.
From faq.perl.org[perlfaq7]
How can I comment out a large block
of Perl code?
The quick-and-dirty way to comment out more than one line of Perl is
to surround those lines with Pod directives. You have to put these
directives at the beginning of the line and somewhere where Perl
expects a new statement (so not in the middle of statements like the #
comments). You end the comment with =cut, ending the Pod section:
=pod
my $object = NotGonnaHappen->new();
ignored_sub();
$wont_be_assigned = 37;
=cut
The quick-and-dirty method only works well when you don't plan to
leave the commented code in the source. If a Pod parser comes along,
your multiline comment is going to show up in the Pod translation. A
better way hides it from Pod parsers as well.
The =begin directive can mark a section for a particular purpose. If
the Pod parser doesn't want to handle it, it just ignores it. Label
the comments with comment. End the comment using =end with the
same label. You still need the =cut to go back to Perl code from the
Pod comment:
=begin comment
my $object = NotGonnaHappen->new();
ignored_sub();
$wont_be_assigned = 37;
=end comment
=cut
I found it. Perl has multi-line comments:
#!/usr/bin/perl
use strict;
use warnings;
=for comment
Example of multiline comment.
Example of multiline comment.
=cut
print "Multi Line Comment Example \n";
Related
I have this POD file:
=head1 Create professional slideshows with Mojolicious::Plugin::RevealJS
=head2 Install and run a Mojolicious server
Santa's elf had a problem. He had to write very fast a presentation and show it to a bunch of new elf's.
The email assigning this to him was sent by Santa himself.
The elf started to look on Metacpan and found this module: L<Mojolicious::Plugin::RevealJS|https://metacpan.org/pod/Mojolicious::Plugin::RevealJS>
He quickly typed the following commands:
C<cpanm Mojolicius Mojolicious::Plugin::RevealJS>
Now he could generate an mojo lite app using:
C<mojo generate lite-app slide_show>
Because the elf was trained in the ancient arts of the elders
he cloud open new file with vim and paste this code in:
=begin perl
use Mojolicious::Lite -signatures;
app->static->paths(['.']);
plugin 'RevealJS';
any '/' => { template => 'presentation', layout => 'revealjs' };
app->start;
=end perl
When I run perldoc t.pod, the code between '=begin perl' and '=end perl' is not visible. I don't understand what I'm doing wrong.
The perlpod documentation says ...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
The formatter in this case is the thing that perldoc uses to render your POD into text. I suspect it doesn't know what to do with the format perl, so it ignores it.
A formatter that produces HTML might know what to do with the perl format, and might replace this with a code block that has syntax highlighting.
If you want your code examples in the POD to always show up as code, use a verbatim paragraph instead. This is done by adding indentation at the front.
=head2 frobnicate($foo)
This function frobnicates the C<$foo>.
my $bar = frobnicate($foo)
=cut
sub frobnicate { ... }
The description of a =begin <format>/=end <format> in perlpod starts by saying this:
=begin formatname
=end formatname
=for formatname text...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
Anything between =begin perl and =end perl is ignored by the standard Pod formatter and will only be processed by a specialised "perl" formatter (and no such formatter exists in the standard Perl toolset - you'd need to write your own).
You don't say what you expect this syntax to achieve, but it seems likely that you're looking for a verbatim paragraph.
Verbatim Paragraph
Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped.
A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else.
I use Pod to write manuals for my program. And I ran into a problem. Please tell me how to solve it.
I have the following code:
#include <myhead.h>
I<void> myfunc (I<int arg1>, I<int arg2>);
I would like the text to be written from the next line after the word 'void'. Moreover, it is with the next line, and not through one.
Pod is "plain ol' documentation" and doesn't have fancy features. It sounds like you want the text after void to be on the next line. In that case, you have to put that text on the next line and make it verbatim text so it retains the formatting:
=pod
#include <myhead.h>
I<void>
myfunc (I<int arg1>, I<int arg2>);
=cut
If you need something else, improve your questions by showing exactly what you expect.
But, I expect that you probably want to write your own Pod formatter. Then you can do exactly what you want. Fo what it's worth, I write all of my books in Pod and use several custom formatters to get them into their end states.
Pod has paragraph breaks and preformatted text, but no line breaks.
If you are targeting a particular output format, you can do, for example:
=begin html
One line
Another line
=end html
Or you could do some kind of post-processing on the file.
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
Help me understand this Perl statement with <<'ESQ'
What is the statement in https://stackoverflow.com/questions/4151279/perl-print-eof doing exactly? I came across the previous post but didn't understand what he is trying to explain. What is that PETE? Can anyone explain every line? How is the code is working?
print <<EOF;
This is
a multiline
string
EOF
print <<PETE;
This is
a multiline
string
PETE
What is the difference and similarity between these two? In place of PETE I have used many other words like DOG and it works the same every time.
This is called a here-doc. It basically grabs everything from the next line up until an end marker line and presents that as standard input to the program you're running. The end marker line is controlled by the text following the <<.
As an example, in bash (which I'm more familiar with than Perl), the command:
cat <<EOF
hello
goodbye
EOF
will run cat and then send two lines to its standard input (the hello and goodbye lines). Perl also has this feature though the syntax is slightly different (as you would expect, given it's a different language). Still, it's close enough for the explanation to still hold.
Wikipedia has an entry for this which you probably would have found had you known it was called a here-doc, but otherwise it would be rather hard to figure it out.
In your particular cases, there is no difference between using EOF and PETE, there's a relationship between the heredoc marker (the bit following <<) and the end of standard input.
For example, if one of your input lines was EOF, you couldn't really use that as a marker since the standard input would be terminated prematurely:
cat <<EOF
This section contains the line ...
EOF
but then has more stuff
and this line following is the real ...
EOF
In that case, you could use PETE (or anything else that doesn't appear in the text on its own line).
There are other options such as using quotes around the marker (so the indentation can look better) and the use of single or double quotes to control variable substitution.
If you go to the perlop page and search for <<EOF, it will hopefully all become clear.
See Quote and Quote-like Operators (it's pretty well explained).
I know different methods of introducing multi-line comments in Perl. But I want to know why it doesn't have something simpler multi-line comment feature such /* comment */, which would make it much easier.
I currently follow http://www.perlmonks.org/?node_id=560985 to achieve multi-line comments. Are there any plans to include this feature in Perl anytime soon?
C-style comments come with a variety of difficult problems, including the inability to comment-out comments. Additionally, convenient syntax for one-line encourages concise writing, which makes your code easier to read. The absence of 10-line "Author: ... Input: ... Output: ... Favorite Color: ..." blocks that you see from time to time in C and C++ is another benefit.
Multi-line comments encourage long writing that is better expressed more concisely or as documentation, so this is what Perl encourages with its # and =pod operators (respectively).
Finally, if you are having trouble with Perl's style of commenting, you should configure your editor to edit programs, not text. In Emacs, if you start writing something like # this is a comment that is getting longer and longer and longer and oh my goodness we are out of space on this line what to do now and type M-q, Emacs will automatically insert the # at the beginning of each line that it creates.
If you just want to comment-out a block of code, then you need look no further than M-x comment-region and M-x uncomment-region, which will comment out the region in pretty-much any language; including Perl.
Don't stress about the syntax of comments; that's the computer's job!
There was a discussion regarding this on the perl6-language#perl.org mailing list. Although in the end the discussion was inconclusive, the summary posted here makes for interesting reading.
As with any multiline comment structure, there will be a "open" and a "close" comment condition, and that leads to problems with nested comments.
for example, C uses /* as the open and */ as the close. How does a multiline comment system handle comments within comments? C will fail if you try to comment a block that is already commented.
Note that line-based comments (e.g. c++ // comments) do not suffer this problem.
Simplicity is in the eye of the beholder. That said, there are already a number of ways to do multi-line comments. First, void string literals:
q{This text won't do anything.
Neither will this.};
This has the unfortunate side effect of triggering a warning:
Useless use of a constant in void context at - line 4.
Another option is using a heredoc in void context - for some reason this doesn't cause a warning:
<<ENDCOMMENT;
Foo comment bar.
ENDCOMMENT
As you can see, the problem isn't the lack of syntax as such (python doc comments look vaugely similar to the q{} method in fact) - it's more just that the community of perl programmers has settled on line comments using # and POD. Using a different method at this point will just confuse people who have to read your code later.
This RFC mentions
Unlike many programming languages Perl does not currently implement true multiline comments. This, and the workarounds that are in common use can be problematic. This could be solved by adding a new syntax to allow for comments to span more than one line, like the variation on here-documentation cited below.
What are the common workarounds?
Two techniques I found here are
if (0) {
<comment>
}
and
=pod
<comment>
=cut
Are these safe to use? Are there others that work better?
The downside of the "if" solution is that the commented out code still has to be compiled (and therefore still has to be syntax checked).
The downside of your pod solution is that your comments will appear in any documentation generated from the pod.
I use a version of the pod solution that doesn't have that problem. Pod supports =begin format ... =end format paragraphs that are handled by specific formatters. I just invent a "comment" format that isn't handled by any of the formatters I use.
#!/usr/bin/perl
print "This line is executed\n";
=begin comment
print "This line isn't\n";
=end comment
=cut
print "This line is\n";
The Perl documentation tells you how to do it in perlfaq7. It's plenty safe, and since we can do it with Pod, we don't need additional syntax to do it:
How can I comment out a large block of perl code?
You can use embedded POD to discard it. Enclose the blocks you want to
comment out in POD markers. The =begin directive marks a section for
a specific formatter. Use the "comment" format, which no formatter
should claim to understand (by policy). Mark the end of the block with
=end.
# program is here
=begin comment
all of this stuff
here will be ignored
by everyone
=end comment
=cut
# program continues
The pod directives cannot go just anywhere. You must put a pod
directive where the parser is expecting a new statement, not just in
the middle of an expression or some other arbitrary grammar production.
See perlpod for more details.
Although it's non-standard, I just use
=ignore
sub blah { ... }
my $commented_out_var = 3.14;
=cut
It works just as well, and reminds me that it is not POD.
Aside: It is an interesting thing that POD gives us a flexible framework for including various regions that should not regarded as code, specifying what that region means. Clearly we "comment things out" because comments work this way. Yet, it is clear from the term that comments are meant to be words, not instructions; documentation not alterations.
An editor with a "Comment Region" function.
For example, Komodo Edit. I'm pretty sure Eclipse and JEdit do it as well, but I don't have them handy to check.
The feature usually inserts a "Comment this line" symbol at the start of every line in the selected region. It has the benefit of not conflicting with existing comments (which is a risk if you wrap an area containing a multi-line comment in most languages)
My favorite multi-line comment device is __END__.
print "Hello world\n";
__END__
The script has ended. Perl does not treat this part of the file as code.
I can put whatever I want down here. Very handy.
This works too:
q^
This is another way to
add multi-line comments
to your code
^ if 0;
In addition to the
=begin comment
multi-paragraph comments here
=end comment
=cut
form in other answers, you can also do this:
=for comment
this is a single pod paragraph comment do
not put extra blank lines after =for. the
comment ends after the first blank line and
regular pod continues until =cut
Hello! C<Yay!>
=cut
the comment paragraph will not appear in the pod output, but the Hello "Yay!" will.
One special use-case is commenting out several lines of code. But if you use a version control system, you can just delete unwanted code rather than commenting it out, and if you ever need it back, just fetch the old revision.
Something like works too:
q{
my comment
};
THis is an expression I guess evaluated while running Perl.
This even simpler construct worked for me
=comment
It was hard in the Moonta Mines that year
For the miners, down in the pit,
It wasn’t a place for a weak man, but
The Cornish Miners had grit,
They burrowed deeper with every day
Extracting the copper ore,
And the skimps grew high in the heaps that piled
Not far from the Moonta shore.
=cut
I use that way and works for me
=head
"your code to comment
monkey
banana"
=cut
Yet another helpful way!
=begin GHOSTCODE
whatever you want to uncomment
=end GHOSTCODE
=cut
This isn't a Perl syntactical way to do it, but in most editors (like Notepad++) you can highlight code you want to be commented out, and then press CTRL+K. To remove the comments you can highlight them and press CTRL+Shift+K.