From 90881924d4f8331b7d4c67446dc9b9024bc2cf26 Mon Sep 17 00:00:00 2001 From: Yorhel Date: Fri, 21 Mar 2025 11:29:52 +0100 Subject: [PATCH] Doc fixes --- FU.pm | 32 ++++++++++++++++---------------- FU/Log.pm | 4 ++-- FU/MultipartFormData.pm | 4 ++-- FU/Pg.pm | 12 ++++++------ FU/SQL.pm | 4 ++-- FU/Util.pm | 25 +++++++++++++------------ FU/Validate.pm | 34 +++++++++++++++++----------------- FU/XMLWriter.pm | 8 ++++---- 8 files changed, 62 insertions(+), 61 deletions(-) diff --git a/FU.pm b/FU.pm index cf13473..02b1b8b 100644 --- a/FU.pm +++ b/FU.pm @@ -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 namespace is used for global configuration and utility functions, the C 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 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, 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 request header. Beware that, @@ -1365,7 +1365,7 @@ objects. Refer to L 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 and registering L, it should call C to actually start serving diff --git a/FU/Log.pm b/FU/Log.pm index 612ecd1..24dafbf 100644 --- a/FU/Log.pm +++ b/FU/Log.pm @@ -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 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 diff --git a/FU/MultipartFormData.pm b/FU/MultipartFormData.pm index 8c2542a..8441740 100644 --- a/FU/MultipartFormData.pm +++ b/FU/MultipartFormData.pm @@ -121,7 +121,7 @@ C, 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: diff --git a/FU/Pg.pm b/FU/Pg.pm index 0d5579f..83b2111 100644 --- a/FU/Pg.pm +++ b/FU/Pg.pm @@ -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. -=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 and I. 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 Methods to convert between the various formats. I Methods to query type info. -=head2 COPY support +=head1 COPY support You can use L for efficient @@ -816,7 +816,7 @@ silently discarded. An explicit C 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's C, including a full stack trace. diff --git a/FU/SQL.pm b/FU/SQL.pm index 6a30332..15adbb1 100644 --- a/FU/SQL.pm +++ b/FU/SQL.pm @@ -124,7 +124,7 @@ changes, see the main L module for details. =head1 DESCRIPTION -=head2 Compiling SQL +=head1 Compiling SQL All functions listed under L 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 method. All functions are exported by default. diff --git a/FU/Util.pm b/FU/Util.pm index 41d01f3..7b8c6ad 100644 --- a/FU/Util.pm +++ b/FU/Util.pm @@ -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. - +FU::Util - Miscellaneous Utility Functions =head1 EXPERIMENTAL @@ -113,7 +110,11 @@ changes, see the main L 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, @@ -281,7 +282,7 @@ functions, L and L are perfectly fine alternatives. L and L 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 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, which is old and not well optimized for modern systems. There's @@ -408,10 +409,10 @@ This function is B 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 and L in the core Perl distribution and -L on CPAN. +L, L and L on CPAN. -=head2 Brotli Compression +=head1 Brotli Compression Just a small wrapper around C's one-shot compression interface. @@ -428,7 +429,7 @@ Throws an error if C could not be found or loaded. =back -=head2 File Descriptor Passing +=head1 File Descriptor Passing UNIX sockets (see L) have the fancy property of letting you send file descriptors over them, allowing you to pass, for example, a socket diff --git a/FU/Validate.pm b/FU/Validate.pm index bc63845..da29a2e 100644 --- a/FU/Validate.pm +++ b/FU/Validate.pm @@ -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 below) and C<$validations> is an optional hashref containing +C<$schema> is the schema that describes the data to be validated (see L below) and C<$validations> is an optional hashref containing L 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-blessed hashref containing at least one key: I, 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 below. +validation. These are documented in L 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 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 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 option is validated separately for each custom validation. -Multiple I and I validations are merged into a single validation. -So if you have multiple custom validations that set the I option, a -single combined schema is created that validates all array elements. The same -applies to I: if the same key is listed in multiple custom validations, -then the key must conform to all schemas. With respect to the I -option, a key that is mentioned in any of the I options is considered -"known". +Multiple I, I and I validations are merged into a single +validation. So if you have multiple custom validations that set the I +option, a single combined schema is created that validates all array elements. +The same applies to I: if the same key is listed in multiple custom +validations, then the key must conform to all schemas. With respect to the +I option, a key that is mentioned in any of the I 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, you can also add custom validations to the global list of built-in validations: diff --git a/FU/XMLWriter.pm b/FU/XMLWriter.pm index 3fc8626..35e0702 100644 --- a/FU/XMLWriter.pm +++ b/FU/XMLWriter.pm @@ -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 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 call for the top-level C<< >> element. =back -=head2 Output functions +=head1 Output functions =over @@ -252,7 +252,7 @@ provided it defaults to C. =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: