vndb/fu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doc fixes

Browse source
This commit is contained in:
Yorhel 2025-03-21 11:29:52 +01:00
parent 0925ae79a1
commit 90881924d4
8 changed files with 62 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

32
FU.pm
View file

@ -1046,7 +1046,7 @@ Unless specifically mentioned otherwise, all methods and functions taking or
returning strings deal with perl Unicode strings, not raw bytes.
=head2 Framework Configuration
=head1 Framework Configuration
=over
@ -1143,7 +1143,7 @@ restart loop.
=back
=head2 Handlers & Routing
=head1 Handlers & Routing
=over
@ -1211,7 +1211,7 @@ for a certain error code, C<500> is used as fallback.
=back
=head2 The 'fu' Object
=head1 The 'fu' Object
While the C<FU::> namespace is used for global configuration and utility
functions, the C<fu> object is intended for methods that deal with request
@ -1261,7 +1261,7 @@ Convenient short-hand for C<< fu->db->Q(@args) >>.
=back
=head2 Request Information
=head1 Request Information
=over
@ -1307,6 +1307,16 @@ Parse, validate and return the query parameter identified by C<$name> with the
given L<FU::Validate> schema. Calls C<< fu->error(400) >> with a useful error
message if validation fails.
To fetch a query parameter that may have multiple values, use:
my $arrayref = fu->query(q => {accept_scalar => 1});
# OR:
my $first_value = fu->query(q => {accept_array => 'first'});
# OR:
my $last_value = fu->query(q => {accept_array => 'last'});
=item fu->query($schema)
=item fu->query($name1 => $schema1, $name2 => $schema2, ..)
@ -1326,16 +1336,6 @@ To fetch all query paramaters as decoded by C<query_decode()>, use:
my $data = fu->query({type=>'any'});
To fetch a query parameter that may have multiple values, use:
my $arrayref = fu->query(q => {accept_scalar => 1});
# OR:
my $first_value = fu->query(q => {accept_array => 'first'});
# OR:
my $last_value = fu->query(q => {accept_array => 'last'});
=item fu->cookie(...)
Like C<< fu->query() >> but parses the C<Cookie> request header. Beware that,
@ -1365,7 +1365,7 @@ objects. Refer to L<FU::MultipartFormData> for more information.
=back
=head2 Generating Responses
=head1 Response Generation
=over
@ -1509,7 +1509,7 @@ one of the following status codes or an alias:
=head2 Running the Site
=head1 Running the Site
When your script is done setting L</"Framework Configuration"> and registering
L</"Handlers & Routing">, it should call C<FU::run> to actually start serving

4
FU/Log.pm
View file

@ -89,7 +89,7 @@ interface either; the entire point of this module is that it only handles
process-global logging. This module mainly exists for users of the L<FU>
framework.
=head2 Configuration
=head1 Configuration
=over
@ -119,7 +119,7 @@ is then used instead. This is to avoid recursion.
=back
=head2 Exportable function
=head1 Exportable function
=over

4
FU/MultipartFormData.pm
View file

@ -121,7 +121,7 @@ C<multipart/form-data>, which is typically used to handle file uploads.
The entire request body is assumed to be in memory as a Perl string, but this
module makes an attempt to avoid any further copies of data values.
=head2 Parsing
=head1 Parsing
=over
@ -138,7 +138,7 @@ tried.
=back
=head2 Field Object
=head1 Field Object
Each field is parsed into a field object that supports the following methods:

12
FU/Pg.pm
View file

@ -61,7 +61,7 @@ FU::Pg is a client module for PostgreSQL with a convenient high-level API and
support for flexible and complex type conversions. This module interfaces
directly with C<libpq>.
=head2 Connection setup
=head1 Connection setup
=over
@ -173,7 +173,7 @@ attempts to use C<$conn> throw an error.
=back
=head2 Querying
=head1 Querying
=over
@ -420,7 +420,7 @@ Returns the respective configuration parameters.
=head2 Transactions
=head1 Transactions
This module provides a convenient and safe API for I<scoped transactions> and
I<subtransactions>. A new transaction can be started with C<< $conn->txn >>,
@ -549,7 +549,7 @@ Just don't try to use transaction objects and manual transaction commands at
the same time, that won't end well.
=head2 Formats and Types
=head1 Formats and Types
The PostgreSQL wire protocol supports sending bind parameters and receiving
query results in two different formats: text and binary. While the exact wire
@ -752,7 +752,7 @@ I<TODO:> Methods to convert between the various formats.
I<TODO:> Methods to query type info.
=head2 COPY support
=head1 COPY support
You can use L<COPY
statements|https://www.postgresql.org/docs/current/sql-copy.html> for efficient
@ -816,7 +816,7 @@ silently discarded. An explicit C<close()> is recommended to catch errors.
=back
=head2 Errors
=head1 Errors
All methods can throw an exception on error. When possible, the error message
is constructed using L<Carp>'s C<confess()>, including a full stack trace.

4
FU/SQL.pm
View file

@ -124,7 +124,7 @@ changes, see the main L<FU> module for details.
=head1 DESCRIPTION
=head2 Compiling SQL
=head1 Compiling SQL
All functions listed under L</"Constructing SQL"> return an object that can be
passed to other construction functions or compiled into SQL and bind
@ -165,7 +165,7 @@ for details.
=back
=head2 Constructing SQL
=head1 Constructing SQL
All of the functions below return an object with a C<compile()> method. All
functions are exported by default.

25
FU/Util.pm
View file

@ -95,10 +95,7 @@ __END__
=head1 NAME
FU::Util - Miscellaneous utility functions that really should have been part of
a core Perl installation but aren't for some reason because the Perl community
doesn't believe in the concept of a "batteries included" standard library.
</rant>
FU::Util - Miscellaneous Utility Functions
=head1 EXPERIMENTAL
@ -113,7 +110,11 @@ changes, see the main L<FU> module for details.
=head1 DESCRIPTION
=head2 Boolean Stuff
A bunch of functions that are too small (or I'm too lazy) to split out into
separate modules. Some of these functions really ought to be part of Perl core.
=head1 Boolean Stuff
Perl has had a builtin boolean type since version 5.36 and FU uses that where
appropriate, but there's still a lot of older code out there using different
@ -137,7 +138,7 @@ value for C<$val>, due to C<\0> and C<\1> being considered booleans.
=back
=head2 JSON parsing & formatting
=head1 JSON Parsing & Formatting
This module comes with a custom C-based JSON parser and formatter. These
functions conform strictly to L<RFC-8259|https://tools.ietf.org/html/rfc8259>,
@ -281,7 +282,7 @@ functions, L<JSON::PP> and L<Cpanel::JSON::XS> are perfectly fine alternatives.
L<JSON::SIMD> and L<JSON::Tiny> also look like good and maintained candidates.)
=head2 URI-Related Functions
=head1 URI-Related Functions
While URIs are capable of encoding arbitrary binary data, the functions below
assume you're only dealing with text. This makes them more robust against weird
@ -343,7 +344,7 @@ then encoded.
=back
=head2 HTTP Date Formatting
=head1 HTTP Date Formatting
The HTTP date format is utter garbage, but with the right tools it doesn't
require I<too> much code to work with.
@ -368,7 +369,7 @@ This will not happen if your local timezone is UTC.
=back
=head2 Gzip Compression
=head1 Gzip Compression
Gzip compression can be done with a few different libraries. The canonical one
is I<zlib>, which is old and not well optimized for modern systems. There's
@ -408,10 +409,10 @@ This function is B<NOT> safe to use from multiple threads!
This module does not currently implement decompression. If you need that, or
streaming, or other functionality not provided here, there's
L<Compress::Raw::Zlib> and L<Compress::Zlib> in the core Perl distribution and
L<Gzip::Deflate> on CPAN.
L<Gzip::Faster>, L<Gzip::Zopfli> and L<Gzip::Libdeflate> on CPAN.
=head2 Brotli Compression
=head1 Brotli Compression
Just a small wrapper around C<libbrotlienc.so>'s one-shot compression
interface.
@ -428,7 +429,7 @@ Throws an error if C<libbrotlienc.so> could not be found or loaded.
=back
=head2 File Descriptor Passing
=head1 File Descriptor Passing
UNIX sockets (see L<IO::Socket::UNIX>) have the fancy property of letting you
send file descriptors over them, allowing you to pass, for example, a socket

34
FU/Validate.pm
View file

@ -419,15 +419,15 @@ parameters within Perl code. In fact, the correct answer to "how do I validate
function parameters?" is "don't, document your assumptions instead".
=head2 Validation API
=head1 Validation API
To validate some input, you first need a schema. A schema can be compiled as
follows:
my $validator = FU::Validate->compile($schema, $validations);
C<$schema> is the schema that describes the data to be validated (see L</SCHEMA
DEFINITION> below) and C<$validations> is an optional hashref containing
C<$schema> is the schema that describes the data to be validated (see L</Schema
Definition> below) and C<$validations> is an optional hashref containing
L<custom validations|/Custom validations> that C<$schema> can refer to. An
error is thrown if the C<$validations> or C<$schema> are invalid.
@ -443,10 +443,10 @@ An error is thrown if the input does not validate. The error object is a
C<FU::Validate::err>-blessed hashref containing at least one key:
I<validation>, which indicates the name of the validation that failed.
Additional keys with more detailed information may be present, depending on the
validation. These are documented in L</SCHEMA DEFINITION> below.
validation. These are documented in L</Schema Definition> below.
=head1 SCHEMA DEFINITION
=head1 Schema Definition
A schema is an arrayref or hashref, where each key is the name of a built-in
option or of a validation to be performed and the values are the arguments to
@ -473,7 +473,7 @@ Or to use the same validation multiple times:
[ regex => qr/^a/, regex => qr/z$/ ]
=head2 Built-in options
=head1 Built-in options
=over
@ -730,7 +730,7 @@ reporting.
=back
=head2 Standard validations
=head1 Standard validations
Standard validations are provided by the module. It is possible to override,
re-implement and supplement these with custom validations. Internally, these
@ -855,7 +855,7 @@ given the year and month.
=back
=head2 Custom validations
=head1 Custom validations
Custom validations can be passed to C<compile()> as the C<$validations> hashref
argument. A custom validation is, in simple terms, either a schema or a
@ -885,7 +885,7 @@ schema that contains the I<func> built-in option to do the actual validation.
my $schema = { prefix => 'Hello, ' };
my $result = FU::Validate->compile($schema, $validations)->validate('Hello, World!');
=head3 Custom validations and built-in options
=head2 Custom validations and built-in options
Custom validations can also set built-in options, but the semantics differ a
little depending on the option. First, be aware that many of the built-in
@ -909,13 +909,13 @@ error:
The I<func> option is validated separately for each custom validation.
Multiple I<keys> and I<elems> validations are merged into a single validation.
So if you have multiple custom validations that set the I<elems> option, a
single combined schema is created that validates all array elements. The same
applies to I<keys>: if the same key is listed in multiple custom validations,
then the key must conform to all schemas. With respect to the I<unknown>
option, a key that is mentioned in any of the I<keys> options is considered
"known".
Multiple I<keys>, I<values> and I<elems> validations are merged into a single
validation. So if you have multiple custom validations that set the I<elems>
option, a single combined schema is created that validates all array elements.
The same applies to I<keys>: if the same key is listed in multiple custom
validations, then the key must conform to all schemas. With respect to the
I<unknown> option, a key that is mentioned in any of the I<keys> options is
considered "known".
All other built-in options follow inheritance semantics: These options can be
set in a custom validation, and they are inherited by the top-level schema. If
@ -924,7 +924,7 @@ inherited. The top-level schema can always override options set by custom
validations.
=head3 Global custom validations
=head2 Global custom validations
Instead of passing a C<$validations> argument every time you call C<compile()>,
you can also add custom validations to the global list of built-in validations:

8
FU/XMLWriter.pm
View file

@ -138,7 +138,7 @@ other XML writing modules on CPAN that I tried, but whether this approach is
faster than typical templating solutions... I've no idea. Check out
L<FU::Benchmarks> for some benchmarks.
=head2 Top-level functions
=head1 Top-level functions
These functions all return a byte string with (UTF-8) encoded XML.
@ -170,7 +170,7 @@ passed to the C<tag_()> call for the top-level C<< <html> >> element.
=back
=head2 Output functions
=head1 Output functions
=over
@ -252,7 +252,7 @@ provided it defaults to C<undef>.
=back
=head2 Utility function
=head1 Utility function
=over
@ -263,7 +263,7 @@ and C<"> are replaced with their XML entity.
=back
=head2 Import options
=head1 Import options
All of the functions mentioned in this document can be imported individually.
There are also two import groups: