mirror of
https://github.com/gentoo-mirror/guru.git
synced 2025-04-21 07:52:21 -04:00
241 lines
7.7 KiB
Groff
241 lines
7.7 KiB
Groff
.\" Automatically generated by Pandoc 3.5
|
|
.\"
|
|
.TH "lua\-psl" "" "" ""
|
|
.SH Introduction
|
|
lua\-psl is a set of \c
|
|
.UR https://www.lua.org
|
|
lua
|
|
.UE \c
|
|
\ bindings to \c
|
|
.UR https://github.com/rockdaboot/libpsl
|
|
libpsl
|
|
.UE \c
|
|
, a C library that handles the Public Suffix List (PSL).
|
|
.PP
|
|
The PSL is a list of domains where there may be sub\-domains outside of
|
|
the administrator\[cq]s control.
|
|
e.g.\ the administrator of `.com' does not manage `github.com'.
|
|
.PP
|
|
This list has found use in many internet technologies including:
|
|
.IP \[bu] 2
|
|
preventing cross\-domain cookie leakage
|
|
.IP \[bu] 2
|
|
allowance of issuing wild\-card TLS certificates
|
|
.PP
|
|
More information can be found at \c
|
|
.UR https://publicsuffix.org/
|
|
publicsuffix.org
|
|
.UE \c
|
|
.SH API
|
|
.SS psl library
|
|
Load with \f[CR]require \[dq]psl\[dq]\f[R]
|
|
.SS \f[CR]psl.load_file(path)\f[R]
|
|
Loads a psl from the given file path.
|
|
On success, returns a psl object.
|
|
On failure, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.load_fp(file)\f[R]
|
|
Loads a psl from the given \c
|
|
.UR https://www.lua.org/manual/5.3/manual.html#6.8
|
|
lua file object
|
|
.UE \c
|
|
\&.
|
|
On success, returns a psl object.
|
|
On failure, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.builtin()\f[R]
|
|
Returns the psl built in to libpsl.
|
|
If it exists, returns a psl object.
|
|
If libpsl was compiled without one, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.builtin_file_time()\f[R]
|
|
Returns the time\-stamp of the file used to build the built in psl.
|
|
If it exists, returns the time\-stamp as an integer.
|
|
If libpsl was compiled without one, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.builtin_sha1sum()\f[R]
|
|
Returns the SHA1 checksum of the file used to build the built in psl.
|
|
If it exists, returns the checksum as a string of lower\-case hex
|
|
digits.
|
|
If libpsl was compiled without one, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.builtin_filename()\f[R]
|
|
Returns the file name of the file used to build the built in psl.
|
|
If it exists, returns a string.
|
|
If libpsl was compiled without one, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.builtin_outdated()\f[R]
|
|
Returns a boolean indicating if the built\-in data is older than the
|
|
file currently at \f[CR]psl.builtin_filename()\f[R].
|
|
.PP
|
|
Note: This function will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.dist_filename()\f[R]
|
|
Returns a string containing the path to your computer\[cq]s default psl
|
|
database location.
|
|
If libpsl was not configured with one or was configured with an empty
|
|
path, returns \f[CR]nil\f[R].
|
|
.PP
|
|
Note: This function will not exist if lua\-psl is compiled against
|
|
libpsl 0.15 or earlier.
|
|
.SS \f[CR]psl.latest(filename)\f[R]
|
|
This function loads the the latest available PSL data from the following
|
|
locations:
|
|
.IP "1." 3
|
|
\f[CR]filename\f[R] (application specific filename, may be
|
|
\f[CR]nil\f[R])
|
|
.IP "2." 3
|
|
default psl database location (as returned from
|
|
\f[CR]psl.dist_filename()\f[R])
|
|
.IP "3." 3
|
|
built\-in PSL data (as returned from \f[CR]psl.builtin()\f[R])
|
|
.IP "4." 3
|
|
location of built\-in data (as returned from
|
|
\f[CR]psl.builtin_filename()\f[R])
|
|
.PP
|
|
If none of the locations contain a valid psl object then returns
|
|
\f[CR]nil\f[R].
|
|
.PP
|
|
Note: This function will not exist if lua\-psl is compiled against
|
|
libpsl 0.15 or earlier.
|
|
.SS \f[CR]psl.get_version()\f[R]
|
|
Returns a string containing the version of libpsl.
|
|
.SS \f[CR]psl.check_version_number(version)\f[R]
|
|
Check if the given version number is at least the current library
|
|
version number.
|
|
.PP
|
|
Returns the current library version number if the given version number
|
|
is at least the version of the library, otherwise returns
|
|
\f[CR]false\f[R].
|
|
If the \f[CR]version\f[R] argument is missing, \f[CR]nil\f[R] or
|
|
\f[CR]0\f[R] then returns the current library version number without
|
|
performing a check.
|
|
.PP
|
|
Note: This function will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.str_to_utf8lower(str, encoding, locale)\f[R]
|
|
Converts a string to UTF\-8 lower\-case + NFKC representation.
|
|
.PP
|
|
\f[CR]encoding\f[R] (optional) is the charset encoding of
|
|
\f[CR]str\f[R].
|
|
\f[CR]locale\f[R] (optional) is the locale of \f[CR]str\f[R].
|
|
.PP
|
|
On success, returns a string.
|
|
On failure, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl.VERSION\f[R]
|
|
The libpsl version as a string.
|
|
.PP
|
|
Note: This constant will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.VERSION_NUMBER\f[R]
|
|
The libpsl version as an integer.
|
|
.PP
|
|
Note: This constant will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.VERSION_MAJOR\f[R]
|
|
The libpsl major version as an integer.
|
|
.PP
|
|
Note: This constant will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.VERSION_MINOR\f[R]
|
|
The libpsl minor version as an integer.
|
|
.PP
|
|
Note: This constant will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.VERSION_PATCH\f[R]
|
|
The libpsl patch version as an integer.
|
|
.PP
|
|
Note: This constant will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl.TYPE\f[R]
|
|
A table containing constants for \f[CR]psl:is_public_suffix()\f[R].
|
|
.IP \[bu] 2
|
|
\f[CR]ANY\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]ICANN\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]PRIVATE\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]NO_STAR_RULE\f[R] (if compiled against libpsl 0.20 or newer)
|
|
.PP
|
|
Note: This table will not exist if lua\-psl is compiled against libpsl
|
|
0.11 or earlier.
|
|
.SS psl object
|
|
.SS \f[CR]psl:free()\f[R]
|
|
Manually free the resources used by the psl object.
|
|
.PP
|
|
Will be called automatically if the psl object is collected.
|
|
.SS \f[CR]psl:is_public_suffix(domain, type)\f[R]
|
|
Checks if \f[CR]domain\f[R] is on the public suffix list.
|
|
.PP
|
|
\f[CR]domain\f[R] should be a UTF\-8 string.
|
|
.PP
|
|
\f[CR]type\f[R] (optional) should be one of the \f[CR]psl.TYPE\f[R]
|
|
constants; the default behaviour is \f[CR]psl.TYPE.ANY\f[R].
|
|
This argument is only supported if compiled against libpsl 0.12.0 or
|
|
above.
|
|
.PP
|
|
Returns a boolean.
|
|
.SS \f[CR]psl:unregistrable_domain(domain)\f[R]
|
|
\f[CR]domain\f[R] should be a UTF\-8 string.
|
|
.PP
|
|
Returns the longest public suffix part of \f[CR]domain\f[R] as a string.
|
|
If \f[CR]domain\f[R] does not contain a public suffix, returns
|
|
\f[CR]nil\f[R].
|
|
.SS \f[CR]psl:registrable_domain(domain)\f[R]
|
|
\f[CR]domain\f[R] should be a UTF\-8 string.
|
|
.PP
|
|
Returns the shortest private suffix part of \f[CR]domain\f[R] as a
|
|
string.
|
|
If \f[CR]domain\f[R] does not contain a private suffix, returns
|
|
\f[CR]nil\f[R].
|
|
.SS \f[CR]psl:suffix_count()\f[R]
|
|
Returns the number of public suffixes as an integer.
|
|
.PP
|
|
When the count is unknown, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl:suffix_exception_count()\f[R]
|
|
Returns the number of public suffix exceptions as an integer.
|
|
.PP
|
|
When the count is unknown, returns \f[CR]nil\f[R].
|
|
.SS \f[CR]psl:suffix_wildcard_count()\f[R]
|
|
Returns the number of public suffix wild\-cards as an integer.
|
|
.PP
|
|
When the count is unknown, returns \f[CR]nil\f[R].
|
|
.PP
|
|
Note: This function will not exist if lua\-psl is compiled against
|
|
libpsl 0.10 or earlier.
|
|
.SS \f[CR]psl:is_cookie_domain_acceptable(hostname, cookie_domain)\f[R]
|
|
Checks whether \f[CR]cookie_domain\f[R] is an acceptable cookie domain
|
|
value for the request \f[CR]hostname\f[R].
|
|
.PP
|
|
\f[CR]hostname\f[R] and \f[CR]cookie_domain\f[R] should be UTF\-8
|
|
strings.
|
|
.PP
|
|
Returns a boolean.
|
|
.SS Example
|
|
.IP
|
|
.EX
|
|
\f[B]local\f[R] psl = assert(require \[dq]psl\[dq].builtin())
|
|
assert(psl:is_cookie_domain_acceptable(\[dq]www.example.com\[dq], \[dq]example.com\[dq]))
|
|
assert(\f[B]not\f[R] psl:is_cookie_domain_acceptable(\[dq]example.com\[dq], \[dq]com\[dq]))
|
|
.EE
|
|
.SH Links
|
|
.IP \[bu] 2
|
|
\c
|
|
.UR https://github.com/daurnimator/lua-psl
|
|
Github
|
|
.UE \c
|
|
.IP \[bu] 2
|
|
\c
|
|
.UR https://github.com/daurnimator/lua-psl/issues
|
|
Issue tracker
|
|
.UE \c
|
|
.IP \[bu] 2
|
|
\c
|
|
.UR https://github.com/rockdaboot/libpsl
|
|
libpsl
|
|
.UE \c
|
|
.IP \[bu] 2
|
|
\c
|
|
.UR https://publicsuffix.org/
|
|
publicsuffix.org
|
|
.UE \c
|
|
.SH AUTHORS
|
|
Daurnimator \c
|
|
.MT quae@daurnimator.com
|
|
.ME \c.
|