I have had some difficulties to read the Perl documentation. I have tried to understand why. This describes some of my problems to understand the documentation of the function split. I also make some proposals to what could be changed.
Please note, I think I have understood most of what I need to understand, but it has taken a long time.
The definitions in perlglossary are rather general. Examples are:
The Perl's perspective is missing in perlglossary. The definition of the Perl specific meaning of a term when used in the documentation of the Perl language is often missing.
Meaning of terms used here are:
Are the more implementation mechanisms of functions in Perl?
I am aware of that a subroutine can be used as an operator and the reverse. In this post I have disregarded this.
(In the index of "Language reference" the description is called "perlsub - subroutine function". What is a subroutine function?)
I suppose the intention of perlsub is to describe the subroutine mechanism in Perl.
This is one of the key parts to understand the usage of a Perl subroutine: From perlsub:
The Perl model for function call and return values is simple: all functions are passed as parameters one single flat list of scalars, and all functions likewise return to their caller one single flat list of scalars. Any arrays or hashes in these call and return lists will collapse, losing their identities--but you may always use pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like. (Often a function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.)
(According to the glossary a function refers to a "subroutine or operator that returns a value". The sentence in parenthesis is a bit confusing.)
I have also been misled to think that the text above applies to all the functions described in index-functions.
My proposal is to change the text to:
The Perl model for subroutine call arguments and return values is simple: all subroutines are passed as arguments one single flat list of scalars. All subroutines return a return value, which is one single flat list of scalars. Any arrays or hashes in these call and return lists will collapse, losing their identities--but you may always use pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like.
And to add this:
The arguments and return values are transferred using the argument stack. The arguments in the script source code is processed (evaluated) to store them in the argument stack. This is done before the subroutine definition is called.
The syntax patterns in the beginning of the descriptions of functions implemented by subroutines, describe the content of the argument stack after the per-processing (evaluation) of the arguments.
(argument stack must be added to perlglossary. Argument stack is described in perlguts
In the description of the Perl functions it isn't always stated how a function is implemented.
Split is not implemented as a subroutine and does not behave like a subroutine. At least the differences in the processing of the arguments compared to the normal processing of those to a normal Perl subroutine must be described.
The syntax pattern for split describes the source code, not the result after per-processing of the arguments as it is for a subroutine.
If you call split like this @rv = split $_[0], @_[ 1 .. 2 ] you get the return value undef. This is_deeply [ $_[0], @_[ 1 .. 2 ] ], [ qr{(:)}, 'a:b:c', 99 ] is ok.
I had expected a warning or error exception.
All of this is perhaps errors in the implementation if split.
I understand that it is impossible to do big changes to the documentation of Perl.
Is there something small that can be done?
I believe that one of the first thing to do is to improve is perlglossary. Definitions of meanings from a Perl's perspective should be added.
Perhaps there could be two glossaries. One general and computer science focused and one with the Perl specific definitions used in the documentation of the Perl language.
In reply to My problems to understand the Perl documentation by bojinlund
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |