<commit_before>=pod

=encoding iso8859-1

=head1 NAME

libeav - Email Address Validation Library

=head1 SYNOPSIS

#include <eav.h>

=over

=item B<void eav_init(eav_t *>I<eav>B<);>

=item B<void eav_free(eav_t *>I<eav>B<);>

=item B<int eav_setup(eav_t *>I<eav>B<);>

=item B<int eav_is_email(eav_t *>I<eav>B<, const char *>I<email>B<, size_t>
I<length>B<);>

=item B<const char * eav_errstr(eav_t *>I<eav>B<);>

=back

Link with I<-leav> { I<-lidn2> | I<-lidn> | I<-lidnkit> }.

When linking with B<idnkit> compile with I<-DHAVE_IDNKIT>.

=head1 DESCRIPTION

libeav is a small library which allows applications to validate
email addresses. An email address consists two parts separated
by "@" symbol: local-part "@" domain. The local-part usually identifies
a user and the domain is usually represents a Fully Qualified Domain Name
(FQDN).

The details of the API are described below. Also, the information may be
found in the header file.

=head1 HIGH-LEVEL API

First of all, you have to create the B<eav_t> structure. This structure
may be created on the stack or via B<malloc>(3). Then, you have to call
the B<eav_init>() function to initialize this structure.

After that you may use default settings or change them on
your decision. To confirm your choice you have to call
the B<eav_setup>() function.

You may change the settings in the B<eav_t> structure at any moment 
and later call again the B<eav_setup>() function. For details 
about possible options please look at the section 
L</HIGH-LEVEL API OPTIONS> below.

To check an email address call the B<eav_is_email>() function.
If this function returns false, that is, the specified email
address is invalid you may get an error message string 
by calling the B<eav_errstr>() function.

When you have finished working with libeav you have to call
the B<eav_free>() function.

The details about each of the mentioned functions above
are described in the section L</HIGH-LEVEL API FUNCTIONS>
below.

See examples below in the section L</HIGH-LEVEL API EXAMPLES>.

=head1 HIGH-LEVEL API OPTIONS

libeav is able to work in different modes, which represents
the implementation of the specific RFC. By default the 
high-level API is using the mode, which conforms to B<RFC 6531>.

The list of fields in the B<eav_t> structure you are able to change
is described below:

=over

=item *

B<rfc> - represents a mode to be used to. The possible values are:
B<EAV_RFC_822>, B<EAV_RFC_5321>, B<EAV_RFC_5322> and B<EAV_RFC_6531>.

Default value is: B<EAV_RFC_6531>.

=item *

B<tld_check> - enable/disable the TLD check. Also this options
enables or disables the FQDN check, because without it such 
a check became useless. The possible values are:
B<true> (enabled) and B<false> (disabled).

Default value is: B<true>.

=item *

B<allow_tld> - the list of TLD types, which will be considered good
or acceptable. That is, the B<eav_is_email>() function will return
true if a TLD type is listed in B<allow_tld>,
otherwise it will return false.

Note that this option will work only if the B<tld_check> option
is enabled.

libeav uses Top Level Domains (TLD for short) and their types,
which can be found at L<https://www.iana.org/domains/root/db>.
The list of possible values and their descriptions are present below:

=over

=item *

B<EAV_TLD_COUNTRY_CODE> - country-code TLDs.

=item *

B<EAV_TLD_GENERIC> - generic TLDs.

=item *

B<EAV_TLD_GENERIC_RESTRICTED> - generic-restricted TLDs.

=item *

B<EAV_TLD_INFRASTRUCTURE> - infrastructure TLDs.

=item *

B<EAV_TLD_NOT_ASSIGNED> - not assigned TLDs. At IANA website they are listed
as "Not assigned" in the "Sponsoring Organisation" field.

=item *

B<EAV_TLD_SPONSORED> - sponsored TLDs.

=item *

B<EAV_TLD_TEST> - test TLDs.
<commit_msg>docs: added information about retired domains<commit_after>=pod

=encoding iso8859-1

=head1 NAME

libeav - Email Address Validation Library

=head1 SYNOPSIS

#include <eav.h>

=over

=item B<void eav_init(eav_t *>I<eav>B<);>

=item B<void eav_free(eav_t *>I<eav>B<);>

=item B<int eav_setup(eav_t *>I<eav>B<);>

=item B<int eav_is_email(eav_t *>I<eav>B<, const char *>I<email>B<, size_t>
I<length>B<);>

=item B<const char * eav_errstr(eav_t *>I<eav>B<);>

=back

Link with I<-leav> { I<-lidn2> | I<-lidn> | I<-lidnkit> }.

When linking with B<idnkit> compile with I<-DHAVE_IDNKIT>.

=head1 DESCRIPTION

libeav is a small library which allows applications to validate
email addresses. An email address consists two parts separated
by "@" symbol: local-part "@" domain. The local-part usually identifies
a user and the domain is usually represents a Fully Qualified Domain Name
(FQDN).

The details of the API are described below. Also, the information may be
found in the header file.

=head1 HIGH-LEVEL API

First of all, you have to create the B<eav_t> structure. This structure
may be created on the stack or via B<malloc>(3). Then, you have to call
the B<eav_init>() function to initialize this structure.

After that you may use default settings or change them on
your decision. To confirm your choice you have to call
the B<eav_setup>() function.

You may change the settings in the B<eav_t> structure at any moment 
and later call again the B<eav_setup>() function. For details 
about possible options please look at the section 
L</HIGH-LEVEL API OPTIONS> below.

To check an email address call the B<eav_is_email>() function.
If this function returns false, that is, the specified email
address is invalid you may get an error message string 
by calling the B<eav_errstr>() function.

When you have finished working with libeav you have to call
the B<eav_free>() function.

The details about each of the mentioned functions above
are described in the section L</HIGH-LEVEL API FUNCTIONS>
below.

See examples below in the section L</HIGH-LEVEL API EXAMPLES>.

=head1 HIGH-LEVEL API OPTIONS

libeav is able to work in different modes, which represents
the implementation of the specific RFC. By default the 
high-level API is using the mode, which conforms to B<RFC 6531>.

The list of fields in the B<eav_t> structure you are able to change
is described below:

=over

=item *

B<rfc> - represents a mode to be used to. The possible values are:
B<EAV_RFC_822>, B<EAV_RFC_5321>, B<EAV_RFC_5322> and B<EAV_RFC_6531>.

Default value is: B<EAV_RFC_6531>.

=item *

B<tld_check> - enable/disable the TLD check. Also this options
enables or disables the FQDN check, because without it such 
a check became useless. The possible values are:
B<true> (enabled) and B<false> (disabled).

Default value is: B<true>.

=item *

B<allow_tld> - the list of TLD types, which will be considered good
or acceptable. That is, the B<eav_is_email>() function will return
true if a TLD type is listed in B<allow_tld>,
otherwise it will return false.

Note that this option will work only if the B<tld_check> option
is enabled.

libeav uses Top Level Domains (TLD for short) and their types,
which can be found at L<https://www.iana.org/domains/root/db>.
The list of possible values and their descriptions are present below:

=over

=item *

B<EAV_TLD_COUNTRY_CODE> - country-code TLDs.

=item *

B<EAV_TLD_GENERIC> - generic TLDs.

=item *

B<EAV_TLD_GENERIC_RESTRICTED> - generic-restricted TLDs.

=item *

B<EAV_TLD_INFRASTRUCTURE> - infrastructure TLDs.

=item *

B<EAV_TLD_NOT_ASSIGNED> - not assigned TLDs. At IANA website they are listed
as "Not assigned" in the "TLD MANAGER" field.

=item *

B<EAV_TLD_SPONSORED> - sponsored TLDs.

=item *

B<EAV_TLD_RETIRED> - retired TLDs. At IANA website they are listed
as "Retired" in the "TLD MANAGER" field.

=item *

B<EAV_TLD_TEST> - test TLDs.

{'fraction_non_alphanumeric': 0.0872870249017038, 'fraction_numerical': 0.009174311926605505, 'mean_word_length': 4.489928057553957, 'pattern_counts': {'":': 0, '<': 128, '<?xml version=': 0, '>': 128, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3552564', 'n_tokens_mistral': 2733, 'n_tokens_neox': 2653, 'n_words': 1048}