стандартное представление Perl-программы

Question

Я хочу стандартный способ программирования на Perl. Я пишу Perl-скрипты, но мне нужно написать некоторую информацию до запуска программы. какова цель этого сценария и организация, а также время, дата и местоположение файла ... e.t.c. например, на языке c мы пишем так

  /*!
 *****************************************************************************
 *
 * @file code.c
 * @brief
 * @b Description: temperature measurement
 * @ university of east london, All rights reserved.
 *
 * $Header: //data/name/source/code.c#10 $
 * $DateTime: 2011/01/18 16:06:25 $
 *
 ****************************************************************************/
 /* Include files:                                                           */
 #include "stdio.h"

, как и выше, комментарии используются на языке c. Мне нужно написать то же описание, прежде чем Perl-скрипт. есть ли формат. я очень начинающий в Perl.

Answer 1

Я использую встроенную документацию Perl.pod

http://perldoc.perl.org/perlpod.html

Пример простого класса, который я бы написал, -

#!/bin/perl
#---------------------------------------------------------------------------------
=head1 Temperature.pm

This class records temperatures ant converts between celcius and ferenheit

university of east london, All rights reserved.

    $Id$
    $Url$

=head2 Constants

=over

=item Temperature units

These constants are used to indicate the units temperature is recorded in.

=cut
#---------------------------------------------------------------------------------
use constant UNIT_CELSUIS   => 1;
use constant UNIT_FARENHEIT => 2;

#---------------------------------------------------------------------------------
=item Attribute indexes

Our object is an array ref, so these private constants are the indexes
of the attributes of our class

=cut
#---------------------------------------------------------------------------------
my $IDX_DEGREES = 0;
my $IDX_UNITS   = 1;

#---------------------------------------------------------------------------------
=back

=head2 Methods

=over

=item new

This is the constructor creates the object. Default is 0 degrees celsius

=cut
#---------------------------------------------------------------------------------
sub new
{
    my( $class, $degrees, $units ) = @_;
    my $self = bless( [], ref($class) || $class );
    $self->[$IDX_DEGREES] = $degrees || 0;
    $self->[$IDX_UNITS]   = $units   || UNIT_CELSIUS;
    return $self;
} # END new

#---------------------------------------------------------------------------------
=item asCelsius

Returns the temperature in degrees celsius

=cut
#---------------------------------------------------------------------------------
sub asCelsius
{
    my( $self ) = @_;
    if( $self->[$IDX_UNITS] == UNIT_CELSIUS )
    {
        return $self->[$IDX_DEGREES];
    }
    else
    {
        return ( $self->[$IDX_DEGREES]  − 32 ) * (5⁄9);
    }
} # END as Celsius

#---------------------------------------------------------------------------------
=back

End of module

=cut
#---------------------------------------------------------------------------------
1;

Answer 2

На самом деле в Perl есть стандарт для встраивания документации в ваш скрипт, но это не то, что вы думаете. Взгляните на формат POD Perl . Это стандартный способ документации, встроенной в программу Perl. Вы можете использовать программу perldoc для просмотра этой документации:

$ perldoc myscript.pl

И вы можете использовать различные команды pod2xxx для форматирования этой информации:

$ pod2html myscript.pl > myscript.html  #HTML format
$ pod2text myscript.pl > myscript.txt   #Text format
$ pod2wiki myscript.pl > wikitext.txt   #For embedding into various Wikis (not part of std Perl dist)

Формат POD довольно прост и легок в освоении. Самое сложное для понимания - у вас должна быть пустая строка между каждой командой и разделом.

Это неправильно:

 =pod
 =head1 PROGRAM NAME
 myscript.pl
 =head1 DESCRIPTION
 My Program is nice.
 =head1 SYNOPSIS
 My program does things

Вместо того, чтобы:

 =pod

 =head1 PROGRAM NAME

 myscript.pl

 =head1 DESCRIPTION

 My Program is nice.

 =head1 SYNOPSIS

 My program does things

См. Также Стиль стручка и Характеристики стручка .

Вся информация, которую вы видите на странице CPAN , генерируется POD, встроенным в модули. То же самое с документацией ActiveState ActivePerl.

Формат POD обычно совпадает с форматом MANPAGES. Таким образом, вы должны иметь следующие разделы как =head1:

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
• OPTIONS
• СМОТРИТЕ ТАКЖЕ
• ОШИБКА
• АВТОР
• COPYRIGHT

Кроме того, я также склонен вставлять переменную $USAGE, которая показывает, как используется команда:

my $USAGE =<<USAGE;
    myscript.pl -foo <foo> [-bar <bar>] <barfoo>

    or

    myscript.pl -help
USAGE

[...]

if ($help) {
   say $USAGE;
   exit 0;
}

Однако это действительно не нужно, поскольку вы можете использовать модуль Pod :: Usage (который является частью стандартного дистрибутива Perl), чтобы распечатать раздел SYNOPSIS нашего документа Pod.

Answer 3

А как насчет POD (или см. perldoc )?

Это - в значительной степени стандарт для сообщества Perl, и, по моему опыту, это хороший и последовательный способ документировать сценарии и модули.

Answer 4

По моему опыту, это не распространенная практика в мире Perl, так что нет, я не могу рекомендовать вам использовать какой-либо формат. Впрочем, достаточно просто использовать существующий формат с небольшими изменениями:

#!/usr/bin/env perl

 #############################################################################
 #
 # @file code.c
 # @brief
 # @b Description: temperature measurement
 # @ university of east london, All rights reserved.
 #
 # $Header: //data/name/source/code.c#10 $
 # $DateTime: 2011/01/18 16:06:25 $
 #
 #############################################################################

use strict;
use warnings;

Обратите внимание, что в Perl нет блочных комментариев как таковых, но строчные комментарии в любом случае соответствуют вашему существующему формату. Также помните, что строка #!, если она присутствует, должна быть абсолютно первой строкой файла, иначе она ничего не будет делать.