You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@perl.apache.org by Per Einar Ellefsen <pe...@skynet.be> on 2002/04/24 13:44:47 UTC
[PATCH] Apache::Constants docs
Hi,
After some discussion on the mod_perl list with Perrin Harkins, it seemed
to me like it would be goot having a warning about problems with using
constant subroutines (in hash constructs, where barewords get stringified,
etc).
I added this, and as the docs have also been ported to the new site, and we
changed style with that (removed ALLCAPS in titles), I changed the whole
thing to make it match the site one. Constants.pm is attached.
All the other Apache:: core modules docs have been integrated into the site
and changed style there too. Should these be re-submitted into the core?
If the style change isn't appropriate for the modules, please tell me and
I'll just send you a patch with the new section.
--
Per Einar Ellefsen
per.einar@skynet.be
Re: [PATCH] Apache::Constants docs
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
>
> Here is the patch again, to make Doug's life easier.
>
> Index: Constants/Constants.pm
committed with some tweaks. Thanks!
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [PATCH] Apache::Constants docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
Here is the patch again, to make Doug's life easier.
Index: Constants/Constants.pm
===================================================================
RCS file: /home/cvspublic/modperl/Constants/Constants.pm,v
retrieving revision 1.22
diff -u -r1.22 Constants.pm
--- Constants/Constants.pm 24 Mar 2002 02:07:58 -0000 1.22
+++ Constants/Constants.pm 27 Apr 2002 09:43:01 -0000
@@ -66,19 +66,20 @@
Apache::Constants - Constants defined in apache header files
-=head1 SYNOPSIS
+=head1 Synopsis
use Apache::Constants;
use Apache::Constants ':common';
use Apache::Constants ':response';
-=head1 DESCRIPTION
+=head1 Description
Server constants used by apache modules are defined in
B<httpd.h> and other header files, this module gives Perl access
-to those constants.
+to those constants.
-=head1 EXPORT TAGS
+
+=head1 Export Tags
=over 4
@@ -92,12 +93,12 @@
NOT_FOUND
FORBIDDEN
AUTH_REQUIRED
- SERVER_ERROR
+ SERVER_ERROR
=item response
This tag imports the B<common> response codes, plus these
-response codes:
+response codes:
DOCUMENT_FOLLOWS
MOVED
@@ -125,7 +126,7 @@
M_OPTIONS
M_POST
M_PUT
- M_TRACE
+ M_TRACE
M_PATCH
M_PROPFIND
M_PROPPATCH
@@ -137,12 +138,12 @@
=item options
-These constants are most commonly used with
+These constants are most commonly used with
the Apache B<allow_options> method:
OPT_NONE
OPT_INDEXES
- OPT_INCLUDES
+ OPT_INCLUDES
OPT_SYM_LINKS
OPT_EXECCGI
OPT_UNSET
@@ -153,7 +154,7 @@
=item satisfy
-These constants are most commonly used with
+These constants are most commonly used with
the Apache B<satisfies> method:
SATISFY_ALL
@@ -162,7 +163,7 @@
=item remotehost
-These constants are most commonly used with
+These constants are most commonly used with
the Apache B<get_remote_host> method:
REMOTE_HOST
@@ -178,14 +179,14 @@
HTTP_OK
HTTP_MOVED_TEMPORARILY
HTTP_MOVED_PERMANENTLY
- HTTP_METHOD_NOT_ALLOWED
+ HTTP_METHOD_NOT_ALLOWED
HTTP_NOT_MODIFIED
HTTP_UNAUTHORIZED
HTTP_FORBIDDEN
HTTP_NOT_FOUND
HTTP_BAD_REQUEST
HTTP_INTERNAL_SERVER_ERROR
- HTTP_NOT_ACCEPTABLE
+ HTTP_NOT_ACCEPTABLE
HTTP_NO_CONTENT
HTTP_PRECONDITION_FAILED
HTTP_SERVICE_UNAVAILABLE
@@ -243,6 +244,55 @@
=back
-=head1 AUTHORS
+=head1 Warnings
+
+You should be aware of the issues relating to using constant
+subroutines in Perl. For example, look at this example:
+
+ $r->custom_response(FORBIDDEN => "File size exceeds quota.");
+
+This will not set a custom response for C<FORBIDDEN>, but for the
+string C<"FORBIDDEN">, which clearly isn't what is expected. You'll
+get an error like this:
+
+ [Tue Apr 23 19:46:14 2002] null: Argument "FORBIDDEN" isn't numeric in
subroutine entry at ...
+
+Therefore, you can avoid this by not using the hash notation for
+things that don't require it.
+
+ $r->custom_response(FORBIDDEN, "File size exceeds quota.");
+
+Another important note is that you should be using the correct
+constants defined here, and not direct HTTP codes. For example:
+
+ sub handler {
+ return 200;
+ }
+
+Is not correct. The correct use is:
+
+ use Apache::Constants qw(OK);
+
+ sub handler {
+ return OK;
+ }
+
+Also remember that C<OK != HTTP_OK>.
+
+
+=head1 Authors
+
+=over
+
+=item * Doug MacEachern
+
+=item * Gisle Aas
+
+=item * h2xs
+
+=back
+
+Only the major authors are listed above. For contributors see the
+Changes file.
-Doug MacEachern, Gisle Aas and h2xs
+=cut
At 14:55 24.04.2002, Geoffrey Young wrote:
>>>personally, I think that FORBIDDEN() is just as bad as $FORBIDDEN - it's
>>>removing the constant idea behind constant subroutines (though sometimes
>>>you just have to do things that way to get past the compiler or
>>>whatnot). it's a matter of personal choice, I suppose...
>>
>>Yes, I agree. I just seem to remember that that was what is suggested in
>>the perl docs. Anyway, there is no reason to use hash notation here.
>>However, there might be for some other functions (don't ask me which).
>
>
>I think that the hash notation is a carryover from other functions like
>notes() and the other Apache::Table based functions where the shortcut
>makes sense.
>
>
>>
>>>oh, and C<OK == 1> is wrong - OK is 0 (which is another reason to just
>>>use constants and forget about their values ;)
>>
>>Thanks for spotting that one :) I still think that warning is important
>>though, as I've seen that a couple of times on the list.
>
>
>yes :)
>
>--Geoff
>
>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
>For additional commands, e-mail: dev-help@perl.apache.org
>
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [PATCH] Apache::Constants docs
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
>> personally, I think that FORBIDDEN() is just as bad as $FORBIDDEN -
>> it's removing the constant idea behind constant subroutines (though
>> sometimes you just have to do things that way to get past the compiler
>> or whatnot). it's a matter of personal choice, I suppose...
>
>
> Yes, I agree. I just seem to remember that that was what is suggested in
> the perl docs. Anyway, there is no reason to use hash notation here.
> However, there might be for some other functions (don't ask me which).
I think that the hash notation is a carryover from other functions like
notes() and the other Apache::Table based functions where the shortcut
makes sense.
>
>> oh, and C<OK == 1> is wrong - OK is 0 (which is another reason to just
>> use constants and forget about their values ;)
>
>
> Thanks for spotting that one :) I still think that warning is important
> though, as I've seen that a couple of times on the list.
yes :)
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [PATCH] Apache::Constants docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 14:28 24.04.2002, Geoffrey Young wrote:
>>Hi,
>>After some discussion on the mod_perl list with Perrin Harkins, it seemed
>>to me like it would be goot having a warning about problems with using
>>constant subroutines (in hash constructs, where barewords get
>>stringified, etc).
>
>the warning looks good. I'd only take exception to the following:
>
>Therefore, you can avoid this by either not using the has notation
>C<=E<gt>>, or by doing steps like this:
>
> $r->custom_response(FORBIDDEN() => "File size exceeds quota.");
> $r->custom_response(+FORBIDDEN => "File size exceeds quota.");
>
>
>probably the best and most simple solution is the one I gave to Isaac,
>which is the one from the Apache.pm documentation for custom_response():
>
>$r->custom_response(AUTH_REQUIRED, "/error.html");
>
>personally, I think that FORBIDDEN() is just as bad as $FORBIDDEN - it's
>removing the constant idea behind constant subroutines (though sometimes
>you just have to do things that way to get past the compiler or whatnot).
>it's a matter of personal choice, I suppose...
Yes, I agree. I just seem to remember that that was what is suggested in
the perl docs. Anyway, there is no reason to use hash notation here.
However, there might be for some other functions (don't ask me which).
>oh, and C<OK == 1> is wrong - OK is 0 (which is another reason to just use
>constants and forget about their values ;)
Thanks for spotting that one :) I still think that warning is important
though, as I've seen that a couple of times on the list.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: syncing the site docs with modperl-1.x
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 15:02 24.04.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>
>>All the other Apache:: core modules docs have been integrated into the
>>site and changed style there too. Should these be re-submitted into the core?
>
>What we can do is to go the modperl-2.0 way for modperl-1.0, i.e. strip
>the pm files from pod and let the modperl-docs/src/docs/1.0 be checked out
>into the modperl tree.
Would this make them usable by just doing 'perldoc Apache::*' ? I think
that's needed, becausae it's the first place anyone looks.
>The drawback (or the benefit :) is the size of this directory, mostly
>added by the size of the guide:
>
>du -s src/docs/1.0/*
>184 src/docs/1.0/api
>16 src/docs/1.0/CVS
>172 src/docs/1.0/faqs
>1460 src/docs/1.0/guide
>56 src/docs/1.0/win32
>
>which compressed becomes 531k, bringing the dist tar.gz from 380k to about
>800k (twice more).
That's bad. Too big probably.
>The biggest benefit is that we will have all the docs in one place and
>they will be searchable/browsable on the site, without needed to sync with
>the core every time there is a change.
What we can do instead: DocSet supports .pm files. So we could get
docs/1.0/api aliased in some way to all the modperl-1 modules, so that when
you check out you get the Perl Module files. The problem is that these are
very spread out in the mod_perl source tree, so it'll be hard to extract
them correctly.
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
syncing the site docs with modperl-1.x
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> All the other Apache:: core modules docs have been integrated into the
> site and changed style there too. Should these be re-submitted into the
> core?
What we can do is to go the modperl-2.0 way for modperl-1.0, i.e. strip
the pm files from pod and let the modperl-docs/src/docs/1.0 be checked
out into the modperl tree.
The drawback (or the benefit :) is the size of this directory, mostly
added by the size of the guide:
du -s src/docs/1.0/*
184
src/docs/1.0/api
16
src/docs/1.0/CVS
172
src/docs/1.0/faqs
1460
src/docs/1.0/guide
56
src/docs/1.0/win32
which compressed becomes 531k, bringing the dist tar.gz from 380k to
about 800k (twice more).
The biggest benefit is that we will have all the docs in one place and
they will be searchable/browsable on the site, without needed to sync
with the core every time there is a change.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: [PATCH] Apache::Constants docs
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
Per Einar Ellefsen wrote:
>
> Hi,
>
> After some discussion on the mod_perl list with Perrin Harkins, it
> seemed to me like it would be goot having a warning about problems with
> using constant subroutines (in hash constructs, where barewords get
> stringified, etc).
the warning looks good. I'd only take exception to the following:
Therefore, you can avoid this by either not using the has notation
C<=E<gt>>, or by doing steps like this:
$r->custom_response(FORBIDDEN() => "File size exceeds quota.");
$r->custom_response(+FORBIDDEN => "File size exceeds quota.");
probably the best and most simple solution is the one I gave to Isaac,
which is the one from the Apache.pm documentation for custom_response():
$r->custom_response(AUTH_REQUIRED, "/error.html");
personally, I think that FORBIDDEN() is just as bad as $FORBIDDEN - it's
removing the constant idea behind constant subroutines (though sometimes
you just have to do things that way to get past the compiler or
whatnot). it's a matter of personal choice, I suppose...
oh, and C<OK == 1> is wrong - OK is 0 (which is another reason to just
use constants and forget about their values ;)
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org