.\" 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.