Mailing List Archive: Perl: porters

[perl #47027] Documentation: BEGIN, END docs in wrong section

Index | Next | Previous | View Threaded

perlbug-followup at perl

Oct 30, 2007, 8:01 AM

Post #1 of 13 (388 views)
Permalink

[perl #47027] Documentation: BEGIN, END docs in wrong section

# New Ticket Created by denis.howe [at] gmail
# Please include the string: [perl #47027]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=47027 >

This is a bug report for perl from denis.howe [at] gmail,
generated with the help of perlbug 1.35 running under perl v5.8.8.

-----------------------------------------------------------------

The section "BEGIN, CHECK, INIT and END" in the
"perlmod" docs has nothing to do with modules and should
be moved to the "perlsyn" "Compound Statements" section
where any reasonable person would expect to find it.

-----------------------------------------------------------------
---
Flags:
category=docs
severity=low
---
Site configuration information for perl v5.8.8:

Configured by Debian Project at Sat Sep 29 06:08:51 GMT 2007.

Summary of my perl5 (revision 5 version 8 subversion 8) configuration:
Platform:
osname=linux, osvers=2.6.15.7, archname=i486-linux-gnu-thread-multi
uname='linux palmer 2.6.15.7 #1 smp thu sep 7 19:42:20 utc 2006
i686 gnulinux'

sthoenna at efn

Oct 30, 2007, 10:14 PM

Post #2 of 13 (378 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On Tue, October 30, 2007 8:01 am, denis.howe [at] gmail wrote:
> The section "BEGIN, CHECK, INIT and END" in the
> "perlmod" docs has nothing to do with modules and should
> be moved to the "perlsyn" "Compound Statements" section where any
> reasonable person would expect to find it.

But they aren't statements, they are subroutines. perlsub? A new
perlcompile.pod, dealing with execution/compilation phases in general?

davidnicol at gmail

Oct 30, 2007, 11:53 PM

Post #3 of 13 (374 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On 10/30/07, denis.howe [at] gmail (via RT) <perlbug-followup [at] perl> wrote:
>
> The section "BEGIN, CHECK, INIT and END" in the
> "perlmod" docs has nothing to do with modules

The thing that the time shifting keywords have to do with modules is
that since modules are compiled within an implied BEGIN block,
the discussion of modules is a fine time to document all of them.

Richard.Foley at rfi

Oct 31, 2007, 1:07 AM

Post #4 of 13 (374 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On Wednesday 31 October 2007 07:53, David Nicol wrote:
> On 10/30/07, denis.howe [at] gmail (via RT) <perlbug-followup [at] perl>
wrote:
> >
> > The section "BEGIN, CHECK, INIT and END" in the
> > "perlmod" docs has nothing to do with modules
>
> The thing that the time shifting keywords have to do with modules is
> that since modules are compiled within an implied BEGIN block,
> the discussion of modules is a fine time to document all of them.
>
Might it not be more intuitive to mention, in perlmod, that these specially
named subroutines are compiled at different times, possibly mentioning them,
and then refer the reader to perlsub, where the details are explained in
depth and where one might expect to find the info coming to the question
cold?

--
Richard Foley
Ciao - shorter than aufwiedersehen

http://www.rfi.net/

davidnicol at gmail

Oct 31, 2007, 2:10 PM

Post #5 of 13 (368 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

> where one might expect to find the info coming to the question
> cold?
>
> Richard Foley

short entries in perlfunc.pod would also make sense

perl.p5p at rjbs

May 3, 2012, 7:28 PM

Post #6 of 13 (147 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

* James E Keenan via RT <perlbug-followup [at] perl> [2012-05-03T21:50:55]
> Do people agree with that argument? If so, we can put this ticket out
> of its misery.

I agree.

--
rjbs

Attachments:

signature.asc (0.48 KB)

denis.howe at gmail

May 4, 2012, 12:03 AM

Post #7 of 13 (145 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On 2007-10-30 at 08:01:32, denis.howe [at] gmail wrote:

>> The section "BEGIN, CHECK, INIT and END" in the
>> "perlmod" docs has nothing to do with modules and should
>> be moved to the "perlsyn" "Compound Statements" section
>> where any reasonable person would expect to find it.

If I create a patch, what are the chances of it being accepted?

tchrist at perl

May 4, 2012, 9:22 AM

Post #8 of 13 (142 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

>On Fri May 04 07:13:17 2012, denis.howe [at] gmail wrote:
>> The section "BEGIN, CHECK, INIT and END" in the
>> "perlmod" docs has nothing to do with modules and should
>> be moved to the "perlsyn" "Compound Statements" section
>> where any reasonable person would expect to find it.

That's not quite true.

Things like UNITCHECK and END are used as per-module
setup and cleanup code that are called implicitly; hence
the all-caps. This makes for more robust module design
that making people call mod_setup() and mod_cleanup()
type functions, which they might forget to do.

END works as a classwide destructor, just as DESTROY
works as a per-object destructor.

So I disagree that those functions have nothing to
do with modules.

And they really *don't* belong in perlsyn. There is
an argument to be made that they belong in perlsub, but
you cannot say they are unrelated to modules.

--tom

tchrist at perl

May 4, 2012, 7:17 PM

Post #9 of 13 (141 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

>> So I disagree that those functions have nothing to
>> do with modules.

>Although textbook usage of the BEGIN/END blocks is with modules, there
>is no reason to only use them with modules. Here is an example of the
>END block, no packages, no modules, no symbol table, no blessed objects.
>______________________________________
>use strict;
>use warnings;
>sub createHandle {
> return int(rand(5999))+1;
>}
>sub destroyHandle{
> my $handle = shift;
> die "handle is invalid" if $handle > 6000 || $handle < 0;
> print "handle destroyed\n";
>}
>my $newHandle = createHandle();
>die "time to die";
>END{
> if($newHandle) {destroyHandle($newHandle);}
>}
>________________________________________
>If I want to clean up resources in Perl on a die/croak, and don't want
>to write a class, which is 1-3 (OOP ones) very challanging PODs (for a
>beginner) which a user must read, the simplest thing is to use an END
>block. An END block is much easier for a beginning Perl programmer to
>use than making a package, writing a new sub (includes choosing whether
>to bless a scalar, a hash, or an array, or more!), writing a DESTROY
>sub, switch back to main package, and creating an instance of the class,
>and repeat the previous steps half a dozen times. With END they can use
>die without having to call a C-ish destructor sub before each die
>statement in their code.

Well that may be, but these are *subroutines*. They are not
control statements like if, while, .... Only control stuctures
go in perlsyn.

As I said, there is an argument that they should go in perlsub.

But perlsyn makes no sense.

--tom

denis.howe at gmail

May 5, 2012, 1:15 AM

Post #10 of 13 (145 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On Fri 2012-05-04 07:13:17, denis.howe [at] gmail wrote:

> The section "BEGIN, CHECK, INIT and END" in the
> "perlmod" docs has nothing to do with modules and should
> be moved to the "perlsyn" "Compound Statements" section
> where any reasonable person would expect to find it.

tchrist1 via RT <perlbug-followup [at] perl> wrote:

> Things like UNITCHECK and END are used as per-module setup and cleanup code

I can't believe I'm arguing with Tom :-) but...

Many Perl features are relevant to good module design but that doesn't
mean they should all be documented in perlmod. These special blocks
are not specific to modules, they can be used in "eval" strings for
example.

> these are *subroutines*.

So why does the doc say that it is not good style to prefix them with
"sub"? Because they don't behave like subroutines in any way - you
can't call them, they don't take arguments or return anything. (In
fact the option to prefix them with sub sounds like a confusing,
historic wart that should be retired.)

> They are not control statements like if, while, ....

That is quite clearly exactly what they are - special control
statements. They are all about flow of control, just like if, while
and the rest. The only difference is that these special blocks
control flow around the parsing and compilation phases as well as just
during execution. If anything they are like the mythical "come from"
statements (http://foldoc.org/come+from).

> control stuctures go in perlsyn.

Exactly.

> There is an argument to be made that they belong in perlsub

Only if you can convince us they are subroutines.

> but you cannot say they are unrelated to modules.

Not unrelated, but not specific to modules.

rurban at x-ray

May 6, 2012, 6:31 AM

Post #11 of 13 (142 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On Sat, May 5, 2012 at 3:15 AM, Denis Howe <denis.howe [at] gmail> wrote:
> On Fri 2012-05-04 07:13:17, denis.howe [at] gmail wrote:
>
>> The section "BEGIN, CHECK, INIT and END" in the
>> "perlmod" docs has nothing to do with modules and should
>> be moved to the "perlsyn" "Compound Statements" section
>> where any reasonable person would expect to find it.

Any reasonable person is expected to find it the file where it was
for the last 20 years or so.
Moving it to perlsyn sounds wrong. perlmod is not ideal, but it's the
nearest match we have.

And its referenced in multiple pods on CPAN this way.
--
Reini Urban
http://cpanel.net/ � http://www.perl-compiler.org/

nick at ccl4

May 8, 2012, 3:25 AM

Post #12 of 13 (141 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On Sat, May 05, 2012 at 09:15:29AM +0100, Denis Howe wrote:
> On Fri 2012-05-04 07:13:17, denis.howe [at] gmail wrote:

> > these are *subroutines*.
>
> So why does the doc say that it is not good style to prefix them with
> "sub"? Because they don't behave like subroutines in any way - you
> can't call them, they don't take arguments or return anything. (In
> fact the option to prefix them with sub sounds like a confusing,
> historic wart that should be retired.)

Not quite true. The default array for shift is on @_, not @ARGV, inside them.
Yes, @_ is empty. But if you use shift; expecting it to be on @ARGV, you will
be confused. This is a trap I've fallen into.

> > There is an argument to be made that they belong in perlsub
>
> Only if you can convince us they are subroutines.

You're not phrasing that correctly. They *are* subroutines. That's what they
are internally.

What matters is whether from a language user perspective whether they are so
far from subroutines that they have more in common with some other part of
the language than with subroutines.

Nicholas Clark

dcmertens.perl at gmail

May 8, 2012, 8:20 AM

Post #13 of 13 (139 views)
Permalink

Re: [perl #47027] Documentation: BEGIN, END docs in wrong section [In reply to]

On Tue, May 8, 2012 at 5:25 AM, Nicholas Clark <nick [at] ccl4> wrote:

> On Sat, May 05, 2012 at 09:15:29AM +0100, Denis Howe wrote:
> > On Fri 2012-05-04 07:13:17, denis.howe [at] gmail wrote:
>
> > > these are *subroutines*.
> >
> > So why does the doc say that it is not good style to prefix them with
> > "sub"? Because they don't behave like subroutines in any way - you
> > can't call them, they don't take arguments or return anything. (In
> > fact the option to prefix them with sub sounds like a confusing,
> > historic wart that should be retired.)
>
> Not quite true. The default array for shift is on @_, not @ARGV, inside
> them.
> Yes, @_ is empty. But if you use shift; expecting it to be on @ARGV, you
> will
> be confused. This is a trap I've fallen into.
>
> > > There is an argument to be made that they belong in perlsub
> >
> > Only if you can convince us they are subroutines.
>
> You're not phrasing that correctly. They *are* subroutines. That's what
> they
> are internally.
>
> What matters is whether from a language user perspective whether they are
> so
> far from subroutines that they have more in common with some other part of
> the language than with subroutines.
>
> Nicholas Clark
>

I can have arbitrarily many BEGIN blocks in the same package, and they are
called in the order that they are declared. I can only have one DESTROY
subroutine in a given package, and only the last executed definition is
used when I call it. This makes named blocks just that: blocks, not
subroutines.

If BEGIN and other named blocks are implemented as subroutines, with sundry
ramifications on @_ and other things (caller?), that is an implementation
detail, or even an implementation wart. These warts (if so deemed) should
definitely be made clear in the docs, or done away with if possible.

FWIW, I have round tuits, maybe even enough to write docs for said wart,
but not nearly enough to modify Perl's handling of these blocks.

David

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads