rjsaulakh has asked for the wisdom of the Perl Monks concerning the following question:

Hi please can any one explain me what does the following code does , what is the use of USAGEMSG or USAGE 

use constant USAGEMSG => <<USAGE;
Usage:ftp.pl  [options] host:/path/to/directory 
Options:
         --user <user> Login name 
         --pass <pass> password 
USAGE

[download]

Retitled by Steve_p from 'use of Usage'.

Replies are listed 'Best First'.
Re: Meaning of 'use constant USAGEMSG = > ...'
by ikegami (Patriarch) on Feb 08, 2005 at 16:16 UTC

    USAGEMSG is the name of the constant being created:

    use constant PI => 3.14;

    [download]

    <<USAGE indicates the presence of a "here-doc". All the lines that follow are treated as a string literal. The string is ended by the keyword, alone on a line (no spaces or anything in front or after).

    $Greeting = 'Hello';
$World    = 'Earth';
print(<<EOI, <<"End of Input", <<'EOI');
Foo!
Bar!
EOI
$Greeting
End of Input
$World
EOI

print(<<"==== End of Template ====");
<html>
... some long piece of hardcoded HTML ...
</html>
==== End of Template ====


# Prints:
# =======
# Foo!
# Bar!
# Hello
# $World
# <html>
# ... some long piece of hardcoded HTML ...
# </html>

    [download]
[reply]
[d/l]
[select]
Re: Meaning of 'use constant USAGEMSG = > ...'
by blazar (Canon) on Feb 08, 2005 at 16:30 UTC
    Hi please can any one explain me what does the following code does , what is the use of USAGEMSG or USAGE 
    use constant USAGEMSG => <<USAGE;
Usage:ftp.pl  [options] host:/path/to/directory

    [download]
    Having a 'Seekers of Perl Wisdom' IMHO is not an excuse for not trying to search for obvious info by oneself. In particular since you see use constant you should really check perldoc constant. Then you would find out that 'USAGEMSG' is a constant (a sub, really, you may have done 
    sub USAGEMSG () { ... }

    [download]
    instead).

    'USAGE' is "nothing but" a "tag", but this is basic perl syntax. Please check perldoc perlop and look for "here-document".

[reply]
[d/l]
[select]
      Having a 'Seekers of Perl Wisdom' IMHO is not an excuse for not trying to search for obvious info by oneself.

      I disagree to some extent. While it would be nice if people spent a bit more time searching documentation for the answer, some beginners may not even know perldoc exists, or that answers to these questions could be found there. Perl is so diverse that a piece of code that looks 'simple' and 'fundamental' to you may seem completely foreign to someone else.

      You can get a long way in Perl without using (or possibly even knowing about) constants and here docs.

[reply]
        I disagree to some extent. While it would be nice if people spent a bit more time searching documentation for the answer, some beginners may not even know perldoc exists, or that answers to these questions could be found there. Perl is so diverse that a piece of code that looks 'simple' and 'fundamental' to you may seem completely foreign to someone else.
        And in turn I partly agree with your disagreement! To reply to your cmt: in fact I think (and I heartily hope!) that I have kindly pointed him to the correct entry points in the documentation, underlining clearly enough that most of what he may need to know is already there...
[reply]
      Howdy!

      While RTFM can be a productive activity, 'perldoc constant' would have only gotten half the answer. If you aren't familiar with here-documents, you might not even recognize the construct, let along have the vocabulary. Finding here-document fu in perldoc is not as straightforward as it might be as well.

      In short, I don't think the question at hand is necessarily as obvious as you make it out to be.

      yours,
      Michael
[reply]
        Finding here-document fu in perldoc is not as straightforward as it might be as well.
        I must admit this is true. In some sense it is true of all quote-like operators...
        In short, I don't think the question at hand is necessarily as obvious as you make it out to be.
        I think you're right, in fact I didn't give him a completely RTFM kinda answer, but I explained which two constructs were involved in that statement and pointed to the possibly not so obvious entry points in the docs for both.
[reply]
Re: Meaning of 'use constant USAGEMSG = > ...'
by Mutant (Priest) on Feb 08, 2005 at 16:22 UTC
    USAGEMSG is a constant. A simpler example would be: 
    use constant MYCONST => 'hi';

print MYCONST;

__END__

output:
hi

    [download]
    The '<<USAGE' part is a here document. It's basically a way of defining your own quotes, so everything between the '<<USAGE;' and the final 'USAGE' is a quoted string.
[reply]
[d/l]
Re: Meaning of 'use constant USAGEMSG = > ...'
by holli (Abbot) on Feb 08, 2005 at 16:19 UTC
    It defines a constant with the string in the HERE-doc as value.
    to make it clearer one could write that in two steps: 
    my $c = <<USAGE;
Usage:ftp.pl  [options] host:/path/to/directory 
Options:
         --user <user> Login name 
         --pass <pass> password 
USAGE 

#$c now holds the text between <USAGE and USAGE.
print $c;

use constant USAGEMSG => $c;

    [download]
     Update:
    as igekami pointed out, the above wonīt work. That happens when you donīt test your posts :(.


    holli, /regexed monk/
[reply]
[d/l]

      Your code won't work because use is executed before the assignment to $c. Even if $c was initialized in a BEGIN block, it would still be too late.

[reply]
[d/l]
[select]
        #!/usr/bin/perl

use strict;
use warnings;

my $c;

BEGIN {
    $c = <<USAGE;
What do you mean, too late?
USAGE
}

use constant USAGEMSG => $c;
print +USAGEMSG;

__END__
What do you mean, too late?

        [download]
[reply]
[d/l]
Re: Meaning of 'use constant USAGEMSG = > ...'
by dorward (Curate) on Feb 08, 2005 at 16:25 UTC

    USAGEMSG is the name of the constant being defined.

    USAGE is a string of characters being used to mark the end of the Heredoc (a way of defining the value of a string) block. You can read about the syntax in perldoc perlop. Grep for "<<EOF".

[reply]

Back to Seekers of Perl Wisdom