The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-CheckDigitsUtils-0.002
River stage one • 1 direct dependent • 1 total dependent
/ App::CheckDigitsUtils

NAME

App::CheckDigitsUtils - Utilities related to check digits (CLI for Algorithm::CheckDigits)

VERSION

This document describes version 0.002 of App::CheckDigitsUtils (from Perl distribution App-CheckDigitsUtils), released on 2023-01-28.

SYNOPSIS

DESCRIPTION

This distribution includes several utilities related to check digits. They provide CLIs for Algorithm::CheckDigits.

FUNCTIONS

calc_check_digits

Usage:

calc_check_digits(%args) -> [$status_code, $reason, $payload, \%result_meta]

Calculate check digit(s) of number(s).

Examples:

  • Calculate a single EAN-8 number:

    calc_check_digits(numbers => ["9638-507"], method => "ean"); # -> [200, "OK", [96385074], {}]

Given a number without the check digit(s), e.g. the first 12 digits of an EAN-13, generate/complete the check digits.

Keywords: complete

This function is not exported.

Arguments ('*' denotes required arguments):

  • method* => str

    (No description)

  • numbers* => array[str]

    Numbers without the check digit(s).

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

check_check_digits

Usage:

check_check_digits(%args) -> [$status_code, $reason, $payload, \%result_meta]

Check the check digit(s) of numbers.

Examples:

  • Check a single EAN-8 number (valid, exit code will be zero, message output to STDOUT):

    check_check_digits(numbers => ["9638-5074"], method => "ean");

    Result:

    [
  200,
  "All success",
  undef,
  {
    results => [{ item_id => 96385074, message => "OK", status => 200 }],
  },
]

  • Check a single EAN-8 number (valid, exit code will be zero, no message):

    check_check_digits(numbers => ["9638-5074"], method => "ean", quiet => 1);

    Result:

    [
  200,
  "All success",
  undef,
  {
    results => [{ item_id => 96385074, message => "OK", status => 200 }],
  },
]

  • Check a single EAN-8 number (invalid, exit code is non-zero, message output to STDOUT):

    check_check_digits(numbers => ["9638-5070"], method => "ean");

    Result:

    [
  400,
  "Incorrect check digit(s)",
  undef,
  {
    results => [
      {
        item_id => 96385070,
        message => "Incorrect check digit(s)",
        status  => 400,
      },
    ],
  },
]

  • Check a single EAN-8 number (invalid, exit code is non-zero, no message):

    check_check_digits(numbers => ["9638-5070"], method => "ean", quiet => 1);

    Result:

    [
  400,
  "Incorrect check digit(s)",
  undef,
  {
    results => [
      {
        item_id => 96385070,
        message => "Incorrect check digit(s)",
        status  => 400,
      },
    ],
  },
]

Given a list of numbers, e.g. EAN-8 numbers, will check the check digit(s) of each number.

Exit code will be non-zero all numbers are invalid. To check for individual numbers, use the JSON output.

This function is not exported.

Arguments ('*' denotes required arguments):

  • method* => str

    (No description)

  • numbers* => array[str]

    (No description)

  • quiet => bool

    If set to true, don't output message to STDOUT.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

list_check_digits_methods

Usage:

list_check_digits_methods(%args) -> [$status_code, $reason, $payload, \%result_meta]

List methods supported by Algorithm::CheckDigits.

Examples:

  • List methods:

    list_check_digits_methods();

    Result:

    [
  200,
  "OK",
  [
    "2aus5",
    "aba_rn",
    "ahv_ch",
    "amex",
    "bahncard",
    "betriebsnummer",
    "blutbeutel",
    "bwpk_de",
    "bzue_de",
    "cas",
    "ccc_es",
    "code_39",
    "cpf",
    "cusip",
    "dem",
    "diners",
    "discover",
    "dni_es",
    "ean",
    "ecno",
    "einecs",
    "elincs",
    "enroute",
    "esr5_ch",
    "esr9_ch",
    "eurocard",
    "euronote",
    "happydigits",
    "hkid",
    "iban",
    "identcode_dp",
    "iln",
    "imei",
    "imeisv",
    "isan",
    "isbn",
    "isbn13",
    "isin",
    "ismn",
    "issn",
    "jcb",
    "klubkarstadt",
    "leitcode_dp",
    "mastercard",
    "miles&more",
    "nhs_gb",
    "nip",
    "nric_sg",
    "nve",
    "pa_de",
    "pkz",
    "postcheckkonti",
    "pzn",
    "rentenversicherung",
    "sedol",
    "sici",
    "siren",
    "siret",
    "tin_ie",
    "titulo_eleitor",
    "upc",
    "ups",
    "ustid_at",
    "ustid_be",
    "ustid_de",
    "ustid_dk",
    "ustid_fi",
    "ustid_gr",
    "ustid_ie",
    "ustid_lu",
    "ustid_nl",
    "ustid_pl",
    "ustid_pt",
    "vat_sl",
    "vatrn_at",
    "vatrn_be",
    "vatrn_dk",
    "vatrn_fi",
    "vatrn_gr",
    "vatrn_ie",
    "vatrn_lu",
    "vatrn_nl",
    "vatrn_pl",
    "vatrn_pt",
    "verhoeff",
    "visa",
    "wagonnr_br",
  ],
  {},
]

  • List methods with their summaries/descriptions:

    list_check_digits_methods(detail => 1);

    Result:

    [
  200,
  "OK",
  [
    { method => "2aus5", summary => "2 aus 5, 2 of 5, 2/5" },
    {
      method  => "aba_rn",
      summary => "American Bankers Association routing number (ABA RN)",
    },
    {
      method  => "ahv_ch",
      summary => "Alters- und Hinterlassenenversicherungsnummer, AHV (CH)",
    },
    { method => "amex", summary => "American Express credit cards" },
    { method => "bahncard", summary => "DB Bahncard (DE)" },
    { method => "betriebsnummer", summary => "Betriebsnummer (DE)" },
    { method => "blutbeutel", summary => "Eurocode, blood bags" },
    {
      method  => "bwpk_de",
      summary => "Personenkennummer der Bundeswehr (DE)",
    },
    {
      method  => "bzue_de",
      summary => "Beleglose Zahlschein\xC3\xBCberweisung, BZ\xC3\x9C (DE)",
    },
    { method => "cas", summary => "Chemical abstract service, CAS" },
    {
      method  => "ccc_es",
      summary => "C\xC3\xB3digo de Cuenta Corriente, CCC (ES)",
    },
    { method => "code_39", summary => "Code39, 3 of 9" },
    {
      method  => "cpf",
      summary => "Cadastro de Pessoas F\xC3\xADsicas, CPF (BR)",
    },
    {
      method  => "cusip",
      summary => "Committee on Uniform Security Identification Procedures, CUSIP (US)",
    },
    { method => "dem", summary => "Deutsche Mark Banknoten, DEM" },
    { method => "diners", summary => "Diner's club credit cards" },
    { method => "discover", summary => "Discover credit cards" },
    {
      method  => "dni_es",
      summary => "Documento nacional de identidad (ES)",
    },
    { method => "ean", summary => "European Article Number, EAN" },
    {
      method  => "ecno",
      summary => "European Commission number, EC-No (for chemicals)",
    },
    {
      method  => "einecs",
      summary => "European Inventory of Existing Commercial Chemical Substances, EINECS",
    },
    {
      method  => "elincs",
      summary => "European List of Notified Chemical Substances, ELINCS",
    },
    { method => "enroute", summary => "EnRoute credit cards" },
    {
      method  => "esr5_ch",
      summary => "Einzahlungsschein mit Referenz, ESR5 (CH)",
    },
    {
      method  => "esr9_ch",
      summary => "Einzahlungsschein mit Referenz, ESR9 (CH)",
    },
    { method => "eurocard", summary => "Eurocard credit cards" },
    { method => "euronote", summary => "Euro bank notes, EUR" },
    { method => "happydigits", summary => "Happy Digits (DE)" },
    { method => "hkid", summary => "Hong Kong Identity Card, HKID (HK)" },
    {
      method  => "iban",
      summary => "International Bank Account Number (IBAN)",
    },
    {
      method  => "identcode_dp",
      summary => "Identcode Deutsche Post AG (DE)",
    },
    { method => "iln", summary => "Global Location Number, GLN" },
    {
      method  => "imei",
      summary => "International Mobile Station Equipment Identity, IMEI",
    },
    {
      method  => "imeisv",
      summary => "International Mobile Station Equipment Identity and Software Version Number",
    },
    {
      method  => "isan",
      summary => "International Standard Audiovisual Number, ISAN",
    },
    {
      method  => "isbn",
      summary => "International Standard Book Number, ISBN10",
    },
    {
      method  => "isbn13",
      summary => "International Standard Book Number, ISBN13",
    },
    {
      method  => "isin",
      summary => "International Securities Identifikation Number, ISIN",
    },
    {
      method  => "ismn",
      summary => "International Standard Music Number, ISMN",
    },
    {
      method  => "issn",
      summary => "International Standard Serial Number, ISSN",
    },
    { method => "jcb", summary => "JCB credit cards" },
    { method => "klubkarstadt", summary => "Klub Karstadt (DE)" },
    {
      method  => "leitcode_dp",
      summary => "Leitcode Deutsche Post AG (DE)",
    },
    { method => "mastercard", summary => "Mastercard credit cards" },
    { method => "miles&more", summary => "Miles & More, Lufthansa (DE)" },
    { method => "nhs_gb", summary => "National Health Service, NHS (GB)" },
    { method => "nip", summary => "numer identyfikacji podatkowej, NIP" },
    {
      method  => "nric_sg",
      summary => "National Registration Identity Card, NRIC (SG)",
    },
    { method => "nve", summary => "Nummer der Versandeinheit, NVE, SSCC" },
    { method => "pa_de", summary => "Personalausweis (DE)" },
    { method => "pkz", summary => "Personenkennzahl der DDR" },
    { method => "postcheckkonti", summary => "Postscheckkonti (CH)" },
    { method => "pzn", summary => "Pharmazentralnummer (DE)" },
    {
      method  => "rentenversicherung",
      summary => "Rentenversicherungsnummer, VSNR (DE)",
    },
    {
      method  => "sedol",
      summary => "Stock Exchange Daily Official List, SEDOL (GB)",
    },
    { method => "sici", summary => "Value Added Tax number, VAT (DE)" },
    { method => "siren", summary => "SIREN (FR)" },
    { method => "siret", summary => "SIRET (FR)" },
    { method => "tin_ie", summary => "Tax Identification Number (IE)" },
    {
      method  => "titulo_eleitor",
      summary => "T\xC3\xADtulo Eleitoral (BR)",
    },
    { method => "upc", summary => "Universal Product Code, UPC (US, CA)" },
    { method => "ups", summary => "United Parcel Service, UPS" },
    {
      method  => "ustid_at",
      summary => "Umsatzsteuer-Identifikationsnummer (AT)",
    },
    {
      method  => "ustid_be",
      summary => "Umsatzsteuer-Identifikationsnummer (BE)",
    },
    {
      method  => "ustid_de",
      summary => "Umsatzsteuer-Identifikationsnummer (DE)",
    },
    {
      method  => "ustid_dk",
      summary => "Umsatzsteuer-Identifikationsnummer (DK)",
    },
    {
      method  => "ustid_fi",
      summary => "Umsatzsteuer-Identifikationsnummer (FI)",
    },
    {
      method  => "ustid_gr",
      summary => "Umsatzsteuer-Identifikationsnummer (GR)",
    },
    {
      method  => "ustid_ie",
      summary => "Umsatzsteuer-Identifikationsnummer (IE)",
    },
    {
      method  => "ustid_lu",
      summary => "Umsatzsteuer-Identifikationsnummer (LU)",
    },
    {
      method  => "ustid_nl",
      summary => "Umsatzsteuer-Identifikationsnummer (NL)",
    },
    {
      method  => "ustid_pl",
      summary => "Umsatzsteuer-Identifikationsnummer (PL)",
    },
    {
      method  => "ustid_pt",
      summary => "Umsatzsteuer-Identifikationsnummer (PT)",
    },
    { method => "vat_sl", summary => "Value Added Tax number, VAT (SL)" },
    { method => "vatrn_at", summary => "Value Added Tax number, VAT (AT)" },
    { method => "vatrn_be", summary => "Value Added Tax number, VAT (BE)" },
    { method => "vatrn_dk", summary => "Value Added Tax number, VAT (DK)" },
    { method => "vatrn_fi", summary => "Value Added Tax number, VAT (FI)" },
    { method => "vatrn_gr", summary => "Value Added Tax number, VAT (GR)" },
    { method => "vatrn_ie", summary => "Value Added Tax number, VAT (IE)" },
    { method => "vatrn_lu", summary => "Value Added Tax number, VAT (LU)" },
    { method => "vatrn_nl", summary => "Value Added Tax number, VAT (NL)" },
    { method => "vatrn_pl", summary => "Value Added Tax number, VAT (PL)" },
    { method => "vatrn_pt", summary => "Value Added Tax number, VAT (PT)" },
    { method => "verhoeff", summary => "Verhoeff scheme" },
    { method => "visa", summary => "VISA credit cards" },
    {
      method  => "wagonnr_br",
      summary => "Codifica\xC3\xA7\xC3\xA3o dos vag\xC3\xB5es (BR)",
    },
  ],
  { "table.fields" => ["method", "summary"] },
]

This function is not exported.

Arguments ('*' denotes required arguments):

  • detail => bool

    (No description)

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-CheckDigitsUtils.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-CheckDigitsUtils.

SEE ALSO

Algorithm::CheckDigits

For EAN-8 and EAN-13 only, there is App::EANUtils.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-CheckDigitsUtils

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.