From denis.howe@gmail.com

This is a bug report for perl from denis.howe@​gmail.com,
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'

From @ysth

On Tue, October 30, 2007 8​:01 am, denis.howe@​gmail.com 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?

The RT System itself - Status changed from 'new' to 'open'

From @davidnicol

On 10/30/07, denis.howe@​gmail.com (via RT) <perlbug-followup@​perl.org> 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.

From @richardfoley

On Wednesday 31 October 2007 07​:53, David Nicol wrote​:

On 10/30/07, denis.howe@​gmail.com (via RT) <perlbug-followup@​perl.org>
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/

From @davidnicol

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

Richard Foley

short entries in perlfunc.pod would also make sense

From @jkeenan

On Tue Oct 30 08​:01​:32 2007, denis.howe@​gmail.com wrote​:

This is a bug report for perl from denis.howe@​gmail.com,
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.

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

Reviewing this older ticket tonight, I note that there was some
back-and-forth as to a better place to put documentation of these named
blocks​: perlsyn, perlsub and perlcompile were all mentioned.

However, the facts that (a) no one ever submitted any patches for any of
these ideas; (b) the thread petered out over four years ago suggest that
we don't have a compelling reason to move this out of perlmod.

Do people agree with that argument? If so, we can put this ticket out
of its misery.

Thank you very much.
Jim Keenan

From @rjbs

* James E Keenan via RT <perlbug-followup@​perl.org> [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

@cpansprout - Status changed from 'open' to 'rejected'

From @bulk88

On Thu May 03 19​:29​:24 2012, perl.p5p@​rjbs.manxome.org wrote​:

* James E Keenan via RT <perlbug-followup@​perl.org> [2012-05-03T21​:50​:55]

Do people agree with that argument? If so, we can put this ticket out
of its misery.

I agree.

I disagree. The BEGIN/END blocks are part of the language, they are not
exclusive to using the symbol table or to 'use'ing a .pm file. The
BEGIN/END blocks should go in perlsyn. Putting them in perlsub doesnt
seem right.

@cpansprout - Status changed from 'rejected' to 'open'

From denis.howe@gmail.com

On 2007-10-30 at 08​:01​:32, denis.howe@​gmail.com 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?

From @cpansprout

On Fri May 04 07​:13​:17 2012, denis.howe@​gmail.com wrote​:

On 2007-10-30 at 08​:01​:32, denis.howe@​gmail.com 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?

I don’t know; something like 80%, maybe? :-)

--

Father Chrysostomos

From tchrist@perl.com

On Fri May 04 07​:13​:17 2012, denis.howe@​gmail.com 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

From @bulk88

On Fri May 04 09​:23​:17 2012, tom christiansen wrote​:

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.

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.

Sorry if this reply appears twice.

From tchrist@perl.com

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

From denis.howe@gmail.com

On Fri 2012-05-04 07​:13​:17, denis.howe@​gmail.com 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@​perl.org> 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.

From @rurban

On Sat, May 5, 2012 at 3​:15 AM, Denis Howe <denis.howe@​gmail.com> wrote​:

On Fri 2012-05-04 07​:13​:17, denis.howe@​gmail.com 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/

From @bulk88

On Sun May 06 06​:32​:23 2012, rurban wrote​:

Any reasonable person is expected to find it the file where it was
for the last 20 years or so.
Age is not a reason not to change or improve the PODs.

From @nwc10

On Sat, May 05, 2012 at 09​:15​:29AM +0100, Denis Howe wrote​:

On Fri 2012-05-04 07​:13​:17, denis.howe@​gmail.com 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

From dcmertens.perl@gmail.com

On Tue, May 8, 2012 at 5​:25 AM, Nicholas Clark <nick@​ccl4.org> wrote​:

On Sat, May 05, 2012 at 09​:15​:29AM +0100, Denis Howe wrote​:

On Fri 2012-05-04 07​:13​:17, denis.howe@​gmail.com 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

From @cpansprout

On Tue May 08 08​:21​:21 2012, dcmertens.perl@​gmail.com wrote​:

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.

#!perl

use 5.15.9;

sub MODIFY_CODE_ATTRIBUTES { $_[1](); undef *DESTROY; () }

warn "run time";

sub DESTROY :foo { warn "hello" }
sub DESTROY :bar { warn "good bye" }
sub DESTROY :baz { warn "hello again" }

__END__
hello at - line 9.
good bye at - line 10.
hello again at - line 11.
run time at - line 7.

This makes named blocks just that​: blocks, not
subroutines.

They might be special, but they are still subroutines. You can goto&
out of them. You can return from them.

#!perl

DESTROY { warn "destroy" }
BEGIN { warn "begin 1" }
BEGIN { goto &DESTROY }

__END__
begin 1 at - line 4.
destroy at - line 3.

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.

I don’t consider them warts, but I wouldn’t mind better documentation,
including the fact that DESTROY and AUTOLOAD are also special, in that
‘sub’ can be omitted.

--

Father Chrysostomos

@rjbs - Status changed from 'open' to 'resolved'