Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct a few typos and reformulate some sentences here and there. #3

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
64 changes: 34 additions & 30 deletions lib/Data/Util.pm
Expand Up @@ -142,8 +142,10 @@ This document describes Data::Util version 0.63
This module provides utility functions for data and data types,
including functions for subroutines and symbol table hashes (stashes).

The implementation of this module is both Pure Perl and XS, so if you have a C
compiler, all the functions this module provides are really faster.
This module makes for a pure Perl and XS implementation.

However, if you want to use the full capacity of it, we recommend you to opt
for the XS backend.

There are many benchmarks in the F<DIST-DIR/benchmark/> directory.

Expand All @@ -154,44 +156,44 @@ There are many benchmarks in the F<DIST-DIR/benchmark/> directory.
Check functions are introduced by the C<:check> import tag, which check
the argument type and return a bool.

These functions also checks overloading magic, e.g. C<${}> for a SCALAR reference.
These functions also check for overloading magic, e.g. C<${}> corresponds to a SCALAR reference.

=over 4

=item is_scalar_ref(value)

For a SCALAR reference.
Checks for a SCALAR reference.

=item is_array_ref(value)

For an ARRAY reference.
Checks for an ARRAY reference.

=item is_hash_ref(value)

For a HASH reference.
Checks for a HASH reference.

=item is_code_ref(value)

For a CODE reference.
Checks for a CODE reference.

=item is_glob_ref(value)

For a GLOB reference.
Checks for a GLOB reference.

=item is_rx(value)

For a regular expression reference generated by the C<qr//> operator.
Checks for a regular expression reference generated by the C<qr//> operator.

=item is_instance(value, class)

For an instance of I<class>.
Checks for an instance of I<class>.

It is equivalent to something like
It is equivalent to the following statement:
C<< Scalar::Util::blessed($value) && $value->isa($class) >>.

=item is_invocant(value)

For an invocant, i.e. a blessed reference or existent package name.
Checks for an invocant, i.e. a blessed reference or existent package name.

If I<value> is a valid class name but does not exist, it will return false.

Expand Down Expand Up @@ -235,8 +237,8 @@ This function has no counterpart for validation.

=head2 Validating functions

Validating functions are introduced by the C<:validate> tag which check the
argument and returns the first argument.
Validating functions are introduced by the C<:validate> tag which checks for
the argument and returns the first argument.
These are like the C<:check> functions but dies if the argument type
is invalid.

Expand All @@ -246,49 +248,49 @@ These functions also checks overloading magic, e.g. C<${}> for a SCALAR referenc

=item scalar_ref(value)

For a SCALAR reference.
Validates a SCALAR reference.

=item array_ref(value)

For an ARRAY reference.
Validates an ARRAY reference.

=item hash_ref(value)

For a HASH reference.
Validates a HASH reference.

=item code_ref(value)

For a CODE reference.
Validates a CODE reference.

=item glob_ref(value)

For a GLOB reference.
Validates a GLOB reference.

=item rx(value)

For a regular expression reference.
Validates a regular expression reference.

=item instance(value, class)

For an instance of I<class>.
Validates an instance of I<class>.

=item invocant(value)

For an invocant, i.e. a blessed reference or existent package name.
Validates an invocant, i.e. a blessed reference or existent package name.

If I<value> is a valid class name and the class exists, then it returns
the canonical class name, which is logically cleaned up. That is, it does
C<< $value =~ s/^::(?:main::)*//; >> before returns it.
the canonical class name, which is logically cleaned up. That is, it runs
C<< $value =~ s/^::(?:main::)*//; >> before returning it.

NOTE:
The canonization is because some versions of perl has an inconsistency
on package names:
Canonization is done so due to an inconsistency between Perl versions.
For instance:

package ::Foo; # OK
my $x = bless {}, '::Foo'; # OK
ref($x)->isa('Foo'); # Fatal

The last sentence causes a fatal error:
The last code snippet causes a fatal error:
C<Can't call method "isa" without package or object reference>.
However, C<< invocant(ref $x)->isa('Foo') >> is always OK.

Expand Down Expand Up @@ -460,14 +462,16 @@ For example:

=head2 DATA_UTIL_PUREPERL

If true, C<Data::Util> uses the Pure Perl implementation.
If true, C<Data::Util> uses the pure Perl implementation.

=head1 DEPENDENCIES

Perl 5.8.1 or later.

If you have a C compiler, you can use the XS backend,
but the Pure Perl backend is also available if you have no C compilers.
If you have a C compiler, you can use the XS backend.

A pure Perl backend/implementation is also made available in case you have no C
compiler handy (unlikely!).

=head1 BUGS AND LIMITATIONS

Expand Down