Bug #53754 for Variable-Magic: [PATCH] Correct some typos and reformat.

This patch corrects some typos and fixes some of the nasty formatting of the .pm module. I noticed it after working on the Variable-Magic Mandriva package.

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm index 04ed9df..1cece7e 100644 --- a/lib/Variable/Magic.pm +++ b/lib/Variable/Magic.pm @@ -50,15 +50,22 @@ BEGIN { =head1 DESCRIPTION -Magic is Perl way of enhancing objects. -This mechanism lets the user add extra data to any variable and hook syntaxical operations (such as access, assignment or destruction) that can be applied to it. -With this module, you can add your own magic to any variable without having to write a single line of XS. - -You'll realize that these magic variables look a lot like tied variables. -It's not surprising, as tied variables are implemented as a special kind of magic, just like any 'irregular' Perl variable : scalars like C<$!>, C<$(> or C<$^W>, the C<%ENV> and C<%SIG> hashes, the C<@ISA> array, C<vec()> and C<substr()> lvalues, L<threads::shared> variables... -They all share the same underlying C API, and this module gives you direct access to it. - -Still, the magic made available by this module differs from tieing and overloading in several ways : +Magic is Perl's way of enhancing objects. +This mechanism lets the user add extra data to any variable and hook +syntactical operations (such as access, assignment or destruction) that can be +applied to it. +With this module, you can add your own magic to any variable without having to +write a single line of XS. + +You'll realize that these magic variables look a lot like tied variables. It's +not surprising, as tied variables are implemented as a special kind of magic, +just like any 'irregular' Perl variable : scalars like C<$!>, C<$(> or C<$^W>, +the C<%ENV> and C<%SIG> hashes, the C<@ISA> array, C<vec()> and C<substr()> +lvalues, L<threads::shared> variables... They all share the same underlying C +API, and this module gives you direct access to it. + +Still, the magic made available by this module differs from tieing and +overloading in several ways: =over 4 @@ -72,28 +79,34 @@ You attach it to variables, not values (as for blessed references). It doesn't replace the original semantics. -Magic callbacks usually trigger before the original action take place, and can't prevent it to happen. -This also makes catching individual events easier than with C<tie>, where you have to provide fallbacks methods for all actions by usually inheriting from the correct C<Tie::Std*> class and overriding individual methods in your own class. +Magic callbacks usually get triggered before the original action takes place, +and can't prevent it from happening. This also makes catching individual +events easier than with C<tie>, where you have to provide fallbacks methods +for all actions by usually inheriting from the correct C<Tie::Std*> class +and overriding individual methods in your own class. =item * It's type-agnostic. The same magic can be applied on scalars, arrays, hashes, subs or globs. -But the same hook (see below for a list) may trigger differently depending on the the type of the variable. +But the same hook (see below for a list) may trigger differently depending on +the the type of the variable. =item * It's mostly invisible at the Perl level. -Magical and non-magical variables cannot be distinguished with C<ref>, C<tied> or another trick. +Magical and non-magical variables cannot be distinguished with C<ref>, C<tied> +or another trick. =item * It's notably faster. -Mainly because perl's way of handling magic is lighter by nature, and because there's no need for any method resolution. -Also, since you don't have to reimplement all the variable semantics, you only pay for what you actually use. +Mainly because perl's way of handling magic is lighter by nature, and because +there's no need for any method resolution. Also, since you don't have to +reimplement all the variable semantics, you only pay for what you actually use. =back @@ -119,16 +132,21 @@ It is called for array subscripts and slices, but never for hashes. C<len> -This magic is a little special : it is called when the 'size' or the 'length' of the variable has to be known by Perl. -Typically, it's the magic involved when an array is evaluated in scalar context, but also on array assignment and loops (C<for>, C<map> or C<grep>). -The callback has then to return the length as an integer. +This magic is a little special : it is called when the 'size' or the 'length' +of the variable has to be known by Perl. Typically, it's the magic involved +when an array is evaluated in scalar context, but also on array assignment and +loops (C<for>, C<map> or C<grep>). The callback has then to return the length +as an integer. =item * C<clear> -This magic is invoked when the variable is reset, such as when an array is emptied. -Please note that this is different from undefining the variable, even though the magic is called when the clearing is a result of the undefine (e.g. for an array, but actually a bug prevent it to work before perl 5.9.5 - see the L<history|/PERL MAGIC HISTORY>). +This magic is invoked when the variable is reset, such as when an array is +emptied. Please note that this is different from undefining the variable, even +though the magic is called when the clearing is a result of the undefine (e.g. +for an array, but actually a bug prevent it to work before perl 5.9.5 - see +the L<history|/PERL MAGIC HISTORY>). =item * @@ -156,13 +174,14 @@ Currently not available. C<local> -When this magic is set on a variable, all subsequent localizations of the variable will trigger the callback. -It is available on your perl iff C<MGf_LOCAL> is true. +When this magic is set on a variable, all subsequent localizations of the +variable will trigger the callback. It is available on your perl iff +C<MGf_LOCAL> is true. =back -The following actions only apply to hashes and are available iff C<VMG_UVAR> is true. -They are referred to as C<uvar> magics. +The following actions only apply to hashes and are available iff C<VMG_UVAR> is +true. They are referred to as C<uvar> magics. =over 4 @@ -188,14 +207,20 @@ This magic fires when a key is tested for existence in the hash. C<delete> -This last one triggers when a key is deleted in the hash, regardless of whether the key actually exists in it. +This last one triggers when a key is deleted in the hash, regardless of whether +the key actually exists in it. =back -You can refer to the tests to have more insight of where the different magics are invoked. +You can refer to the tests to have more insight of where the different magics +are invoked. -To prevent any clash between different magics defined with this module, an unique numerical signature is attached to each kind of magic (i.e. each set of callbacks for magic operations). -At the C level, magic tokens owned by magic created by this module have their C<< mg->mg_private >> field set to C<0x3891> or C<0x3892>, so please don't use these magic (sic) numbers in other extensions. +To prevent any clash between different magics defined with this module, an +unique numerical signature is attached to each kind of magic (i.e. each set of +callbacks for magic operations). At the C level, magic tokens owned by +magic created by this module have their C<< mg->mg_private >> field set to +C<0x3891> or C<0x3892>, so please don't use these magic (sic) numbers in +other extensions. =head1 FUNCTIONS @@ -223,8 +248,8 @@ BEGIN { copy_key => $bool, op_info => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ] -This function creates a 'wizard', an opaque type that holds the magic information. -It takes a list of keys / values as argument, whose keys can be : +This function creates a 'wizard', an opaque type that holds the magic +information. It takes a list of keys / values as argument, whose keys can be : =over 4 @@ -232,20 +257,27 @@ It takes a list of keys / values as argument, whose keys can be : C<data> -A code (or string) reference to a private data constructor. -It is called each time this magic is cast on a variable, and the scalar returned is used as private data storage for it. -C<$_[0]> is a reference to the magic object and C<@_[1 .. @_-1]> are all extra arguments that were passed to L</cast>. +A code (or string) reference to a private data constructor. It is called each +time this magic is cast on a variable, and the scalar returned is used as +private data storage for it. C<$_[0]> is a reference to the magic object and +C<@_[1 .. @_-1]> are all extra arguments that were passed to L</cast>. =item * -C<get>, C<set>, C<len>, C<clear>, C<free>, C<copy>, C<local>, C<fetch>, C<store>, C<exists> and C<delete> +C<get>, C<set>, C<len>, C<clear>, C<free>, C<copy>, C<local>, C<fetch>, +C<store>, C<exists> and C<delete> -Code (or string) references to the corresponding magic callbacks. -You don't have to specify all of them : the magic associated with undefined entries simply won't be hooked. -In those callbacks, C<$_[0]> is always a reference to the magic object and C<$_[1]> is always the private data (or C<undef> when no private data constructor was supplied). +Code (or string) references to the corresponding magic callbacks. You don't +have to specify all of them : the magic associated with undefined entries +simply won't be hooked. In those callbacks, C<$_[0]> is always a reference to +the magic object and C<$_[1]> is always the private data (or C<undef> when no +private data constructor was supplied). -Moreover, when you pass C<< op_info => $num >> to C<wizard>, the last element of C<@_> will be the current op name if C<$num == VMG_OP_INFO_NAME> and a C<B::OP> object representing the current op if C<$num == VMG_OP_INFO_OBJECT>. -Both have a performance hit, but just getting the name is lighter than getting the op object. +Moreover, when you pass C<< op_info => $num >> to C<wizard>, the last element +of C<@_> will be the current op name if C<$num == VMG_OP_INFO_NAME> and a +C<B::OP> object representing the current op if C<$num == VMG_OP_INFO_OBJECT>. +Both have a performance hit, but just getting the name is lighter than getting +the op object. Other arguments are specific to the magic hooked : @@ -255,15 +287,17 @@ Other arguments are specific to the magic hooked : C<len> -When the variable is an array or a scalar, C<$_[2]> contains the non-magical length. -The callback can return the new scalar or array length to use, or C<undef> to default to the normal length. +When the variable is an array or a scalar, C<$_[2]> contains the non-magical +length. The callback can return the new scalar or array length to use, or +C<undef> to default to the normal length. =item * C<copy> -C<$_[2]> is a either a copy or an alias of the current key, which means that it is useless to try to change or cast magic on it. -C<$_[3]> is an alias to the current element (i.e. the value). +C<$_[2]> is a either a copy or an alias of the current key, which means that it +is useless to try to change or cast magic on it. C<$_[3]> is an alias to the +current element (i.e. the value). =item *