MDN::API(3pm) · carta

NAME

MDN::API - Perl interface to domain name conversion methods of libmdn

SYNOPSIS

  use MDN::API;

  $idn_domain_name = MDN::API->encode_name($local_domain_name);
  $local_domain_name = MDN::API->decode_name($idn_domain_name);

DESCRIPTION

"MDN::API" provides a Perl object interface to domain name conversion methods of libmdn, the multilingual domain name library included in the mDNkit.

This module provides high-level conversion interface to the library. It can encode or decode a domain name according with libmdn configuration (e.g. "/usr/local/etc/mdn.conf").

CLASS METHODS

Although this module does not provide object interface, all the functions should be called as class methods, in order to be consistent with other modules in "MDN::".

        MDN::API->encode_name($domain_name);  # OK
        MDN::API::encode_name($domain_name);  # NG

encode_name($from [, @actions...])

Encodes domain name of $from according with @actions, and returns the result.

Each element in @actions is a string as follows:

    'localconv'     convert the local encoding string to UTF-8.
    'delimmap'      covnert local delimiters to periods ('.').
    'localmap'      perfrom local mapping.
    'nameprep'      perform NAMEPREP (mapping, normalization,
                    prohibit character check and unassigned
                    codepoint check).
    'idnconv'       convert the UTF-8 string to ACE.

    'encode_app'    perform 'localconv', 'delimmap', 'localmap',
                    'nameprep' and 'idnconv'.  This is the default
                    value of @actions.

Regardless of the order of elements in @actions, the actions are always performed in the following order; 'localconv', 'delimmap', 'localmap', 'nameprep' and 'idnconv'.

If an error occurs, this method returns "undef".

decode_name($from [, @actions...])

Decodes domain name of $from according with @actions, and returns the result. This is the reverse of "encode_name".

Each element in @actions is a string as follows:

    'idnconv'       convert the ACE string to UTF-8.
    'nameprep'      inspect if NAMEPREP has been performed to the
                    string.  If hasn't, convert the string to ACE.
    'localconv'     convert the UTF-8 string to the local encoding.

    'decode_app'    perform 'idnconv', 'nameprep' and 'localconv'.
                    This is the default value of @actions.

Regardless of the order of elements in @actions, those actions are always performed in the following order; 'idnconv', 'nameprep' and 'localconv'.

If an error occurs, this method returns "undef".

enable($on_off)

Enable or disable mulitilingual domain name support provided by libmdn. If $on_off is zero, the support is disabled, otherwise enabled. If this method has not been called, the "MDN_DISABLE" environment variabe is used to determine whether mulitilingual domain name support is enabled. The support is disabled if that variable is defined,

In disabled condition, conversion methods (e.g. "encode_name()" and "decode_name()") simply return a copy of input string as the result of conversion.

lasterror(): Returns the error message string corresponding to the last error occurred in this module.

local_to_utf8($from): Is equivalent to "encode_name($from, 'localconv')".

utf8_to_local($from): Is equivalent to "decode_name($from, 'localconv')".

delimiter_map($from): Is equivalent to "encode_name($from, 'delimmap')".

local_map($from): Is equivalent to "encode_name($from, 'localmap')".

nameprep($from): Is equivalent to "encode_name($from, 'nameprep')".

nameprep_check($from): Is equivalent to "decode_name($from, 'nameprep')".

utf8_to_idn($from): Is equivalent to "encode_name($from, 'idnconv')".

idn_to_utf8($from): Is equivalent to "decode_name($from, 'idnconv')".

local_to_idn($from): Is equivalent to "encode_name($from)".

idn_to_local($from): Is equivalent to "decode_name($from)".

COMPATIBILITY

Beginning with version 2.4, the action 'nameprep' of "encode_name()" and "decode_name()" also performs unassigned codepoint check. The 'unascheck' action and the "unassigned_check()" method are no longer supported.

ISSUE OF HANDLING UNICODE CHARACTERS