#!/usr/bin/env perl
################################################################################
## TIMEZONE_ID -- List IANA timezone IDs.
##
## - $Revision: 1.20 $
## - Note: This uses bundled IANA data instead of the host system's timezone data.
##
## - Author: 2026, tomyama
## - Intended primarily for personal use, but BSD license permits redistribution.
##
## BSD 2-Clause License:
## Copyright (c) 2026, tomyama
## All rights reserved.
################################################################################

use 5.014_000;
use strict;                         # first released with perl 5
use warnings;                       # first released with perl v5.6.0
use File::Basename qw();            # first released with perl 5
use Getopt::Long qw();              # first released with perl 5
use POSIX qw();                     # first released with perl 5
use utf8;                           # first released with perl v5.6.0
use Encode qw();                    # first released with perl v5.7.3


##########
## スクリプトのエントリポイント
sub pl_main( @ )
{
    ## 初期化処理
    init_script();

    ## 引数解析
    parse_arg( @_ );

    param_print();

    if( $main::banner ){
        $main::banner = 0;
        my $banner_msg = '' .
            qq{--------------------------------------------------\n} .
            uc( $main::appname ) . qq{ -- List IANA timezone IDs\n} .
            qq{- This uses bundled IANA data instead of the host system's timezone data.\n} .
            qq{- Version: } . GetVersion() . "\n" .
            qq{- Document: https://github.com/tomyama-code/tomyama_script_collection/blob/main/docs/$main::appname.md\n} .
            qq{--------------------------------------------------\n};
        print( $banner_msg );
    }

    if( $main::help || $main::version ){
        if( $main::help ){
            $main::help = 0;
            usage( 0 );
        }
        if( $main::version ){
            $main::version = 0;
            PrintVersion();
        }
        return 0;
    }

    my @data_loc = ();
    for my $datafile_loc( @main::datafile_loc ){
        if( -f $datafile_loc || $datafile_loc eq 'Non-existent-file' ){
            #print( qq{\$datafile_loc="$datafile_loc" ( exists )\n} );
            open( DATF_LOC, '<', $datafile_loc ) ||
                die( qq{$datafile_loc: could not open file: $!} );
            my $idx = 0;
            while( <DATF_LOC> ){
                my $line = $_;
                $line =~ s/\r?\n$//o;
                if( defined( $data_loc[ $idx ] ) ){
                    my @items = split( /\t/, $line, -1 );
                    my @items_src = split( /\t/, $data_loc[ $idx ], -1 );
                    my $items_len = scalar( @items );
                    for( my $field=0; $field<$items_len; $field++ ){
                        if( $items[ $field ] eq '' ){
                            $items[ $field ] = $items_src[ $field ];
                        }
                    }
                    $line = join( "\t", @items );
                }
                $data_loc[ $idx ] = $line;
                $idx++;
            }
            close( DATF_LOC );
        }
    }

    my $re_flag = '';
    $re_flag .= 'i' if( $main::ignorecase );

    open( DATFILE, '<', $main::datafile ) ||
        die( qq{$main::datafile: could not open file: $!} );
    my $line_row = 0;
    my @matched = ();
    my $tz_id_len_max = 0;
    while( <DATFILE> ){
        my $line_loc = "\t";
        if( defined( $data_loc[ $line_row ] ) ){
            $line_loc = $data_loc[ $line_row ];
        }
        $line_row++;
        my $line = $_;
        $line =~ s/\r?\n$//o;
        my $concat_line = "$line\t$line_loc";
        #print( qq{$concat_line\n} );
        my $concat_line_s = utf82perlstr( $concat_line );

        my $b_disp = 1;
        if( $line_row > 1 && $main::use_filter ){
            for my $filter( @main::filters ){
                my $filter_s = utf82perlstr( $filter );
                # インライン修飾子 (?imsx) を埋め込んだ正規表現
                if( !( $concat_line_s =~ m/(?$re_flag)$filter_s/ ) ){
                    $b_disp = 0;
                    last;
                }
            }
        }

        if( $b_disp ){
            # SDT: Standard Time, 標準時（冬時間、平時）
            # DST: Daylight Saving Time, 夏時間（日光節約時間）
            my( $sdt, $dst, $sdt2, $dst2, $tz_id, $type, $note, $cmt, $lat, $lon, $cc, $cname ) =
                split( /\t/, $line, -1 );
            my $tz_id_len = length( $tz_id );
            $tz_id_len_max = $tz_id_len if( $tz_id_len > $tz_id_len_max );
            push( @matched, $concat_line );
        }
    }
    close( DATFILE );

    my @sorted = @matched;
    if( $main::sort_order_by ne '' ){
        my $sort_order_by = lc( $main::sort_order_by );
        if( $sort_order_by eq 'lat' ){
            @sorted = sort { ( split( /\t/, $a, -1 ) )[ 8 ] <=> ( split( /\t/, $b, -1 ) )[ 8 ] } ( @matched[ 1..$#matched ] );
        }elsif( $sort_order_by eq 'lon' ){
            @sorted = sort { ( split( /\t/, $a, -1 ) )[ 9 ] <=> ( split( /\t/, $b, -1 ) )[ 9 ] } ( @matched[ 1..$#matched ] );
        }elsif( $sort_order_by eq 'id' ){
            @sorted = sort { ( split( /\t/, $a, -1 ) )[ 4 ] cmp ( split( /\t/, $b, -1 ) )[ 4 ] } ( @matched[ 1..$#matched ] );
        }else{
            die( qq{$main::appname: --sort-order-by "$main::sort_order_by": Unsupported field name.\n} );
        }
        unshift( @sorted, $matched[ 0 ] );
    }

    for my $line( @sorted ){
        my( $sdt, $dst, $sdt2, $dst2, $tz_id, $type, $note, $cmt, $lat, $lon, $cc, $cname, $id_loc, $cname_loc ) =
            split( /\t/, $line, -1 );

        sub coord_fmt( $ )
        {
            my( $coord ) = @_;
            $coord = "+$coord" if( $coord =~ m/^\d[\d\.]+$/o );
            my $padding = 6;
            if( $coord =~ m/\.(\d+)$/o ){
                my $digit = length( $1 );
                $padding = 5 - $digit;
            }
            $coord = $coord . ' ' x $padding;
            return $coord;
        }
        $lat = coord_fmt( $lat );
        $lon = coord_fmt( $lon );
        my $coordinate = sprintf( qq{%9s, %10s}, $lat, $lon );

        if( $main::verbose ){
            printf( qq{%-6s %-5s  %-6s %-5s  %-22s %-*s  %-9s  "%s"  "%s"  "%s"  "%s"  "%s"  %s\n},
                $sdt, $sdt2, $dst, $dst2, $coordinate, $tz_id_len_max, $tz_id, $type, $note, $cmt, $cc, $cname, $cname_loc, $id_loc );
        }else{
            printf( qq{%-6s %-5s  %-22s %-*s  %-9s  %s\n},
                $sdt, $sdt2, $coordinate, $tz_id_len_max, $tz_id, $type, $cc );
        }
    }

    return 0;
}

##########
## 初期化処理
## Revision: 1.3
sub init_script()
{
    my $exec_file = $0;
    $exec_file =~ s!^.*tests/(.*)\.t$!$1!;

    ### GLOBAL ###
    $main::apppath = File::Basename::dirname( $exec_file );
    $main::appname = File::Basename::basename( $exec_file );
    $main::argc = 0;
    @main::argv = ();
    $main::banner = 0;
    $main::datafile = "$main::apppath/$main::appname.tab";
    $main::datafile_loc_specify = undef;
    $main::debug = 0;
    @main::filters = ();
    $main::help = 0;
    $main::ignorecase = 0;
    $main::LC_CTYPE = set_locale();
    set_locale_datafilename( $main::datafile, $main::LC_CTYPE );
    $main::set_locale = undef;
    $main::sort_order_by = '';
    $main::use_filter = 0;
    $main::verbose = 0;
    $main::version = 0;
    ## ［ANSIエスケープシーケンス］を使うか否かの判定で使う
#    $main::bUseAnsiEscSeqColor = -t STDOUT;
#    $main::bIsStdinATty = -t STDIN;
    ##############
}

sub param_print()
{
    dPrintf( qq{Parameter Print\n} .
             qq{     \$main::apppath = "%s"\n} .
             qq{     \$main::appname = "%s"\n} .
             qq{     \$main::argc = %d\n} .
             qq{     \@main::argv = (%s)\n} .
             qq{     \$main::banner = %d\n} .
             qq{     \$main::datafile = "%s"\n} .
             qq{     \@main::datafile_loc = (%s)\n} .
             qq{     \$main::debug = %d\n} .
             qq{     \@main::filters = (%s)\n} .
             qq{     \$main::help = %d\n} .
             qq{     \$main::ignorecase = %d\n} .
             qq{     \$main::LC_CTYPE = "%s"\n} .
             qq{     \$main::sort_order_by = "%s"\n} .
             qq{     \$main::use_filter = %d\n} .
             qq{     \$main::verbose = %d\n} .
             qq{     \$main::version = %d\n},
        $main::apppath,
        $main::appname,
        $main::argc,
        array_to_str( @main::argv ),
        $main::banner,
        $main::datafile,
        array_to_str( @main::datafile_loc ),
        $main::debug,
        array_to_str( @main::filters ),
        $main::help,
        $main::ignorecase,
        $main::LC_CTYPE,
        $main::sort_order_by,
        $main::use_filter,
        $main::verbose,
        $main::version );
}

sub array_to_str( @ )
{
    return q{ '} . join( q{', '}, @_ ) . q{' } if( scalar( @_ ) > 0 );
    return '';
}

##########
## 引数解析
sub parse_arg( @ )
{
    @main::argv = @_;
    $main::argc = scalar( @main::argv );

    # Getopt::Long が動くように局所的に変更して騙す
    local @ARGV = @main::argv;

    # 設定: ショートオプションのまとめ指定（バンドリング）を有効化
    Getopt::Long::Configure("bundling");

    Getopt::Long::GetOptions(
        'banner|b'        => \$main::banner,
        'datafile=s'      => \$main::datafile,
        'datafile-loc=s'  => \$main::datafile_loc_specify,
        'debug|d'         => \$main::debug,
        'help|h'          => \$main::help,
        'ignorecase|i'    => \$main::ignorecase,
        'set-locale=s'    => \$main::set_locale,
        'sort-order-by=s' => \$main::sort_order_by,
        'verbose|v'       => \$main::verbose,
        'version'         => \$main::version,
    ) || die( qq{parse_arg(): error: Failed to parse option switches.\n} );

    while( my $myparam = shift( @ARGV ) ){
        push( @main::filters, $myparam );
        #dPrint( qq{filters += "$myparam"\n} );
    }

    if( defined( $main::set_locale ) ){
        $main::LC_CTYPE = set_locale( $main::set_locale );
        set_locale_datafilename( $main::datafile, $main::LC_CTYPE );
        $main::set_locale = undef;
    }
    if( defined( $main::datafile_loc_specify ) ){
        push( @main::datafile_loc, $main::datafile_loc_specify );
        $main::datafile_loc_specify = undef;
    }

    $main::use_filter = 1 if( scalar( @main::filters ) > 0 );
}

##########
## 書式表示
## Revision: 1.2
sub usage( $ )
{
    my $msg = "usage: " .
        qq{$main::appname [ <OPTIONS> ] [ <PATTERN>... ]\n} .
        qq{\n} .
        qq{  List IANA timezone IDs.\n} .
        qq{\n} .
        qq{<PATTERN>:\n} .
        qq{  The PATTERN can be described by the Regular-Expression equal with Perl.\n} .
        qq{\n} .
        qq{<OPTIONS>:\n} .
        qq{  -b, --banner:\n} .
        qq{    Show script banner.\n} .
        qq{  -h, --help:\n} .
        qq{    Display this help and exit\n} .
        qq{  -i, --ignorecase:\n} .
        qq{    Ignore case distinctions in the <PATTERN>.\n} .
        qq{  --sort-order-by <FIELD_NAME>:\n} .
        qq{    "Lat", "Lon", and "ID" can be specified for <FIELD_NAME>.\n} .
        qq{    By default, they are sorted by the magnitude of the offset time difference.\n} .
        qq{  -v, --verbose:\n} .
        qq{    The intermediate steps of the calculation will also be displayed.\n} .
        qq{  --version:\n} .
        qq{    Print the version of this script and Perl and exit.\n} .
        qq{\n} .
        qq{How to use:\n} .
        qq{\n} .
        qq{  * Show all IDs:\n} .
        qq{    \$ $main::appname\n} .
        qq{\n} .
        qq{  * Filter by a single keyword:\n} .
        qq{    \$ $main::appname JST\n} .
        qq{\n} .
        qq{  * Filter by AND condition:\n} .
        qq{    \$ $main::appname 'America/' 'Fr'\n} .
        qq{\n} .
        qq{  * Filter by OR condition:\n} .
        qq{    \$ $main::appname 'France|French'\n} .
        qq{\n} .
        qq{Try `perldoc $main::apppath/$main::appname' for more information.\n};

#    if( $_[0] ){
#        print STDERR ( $msg );
#    } else {
        print STDOUT ( $msg );
#    }

    return 0;
}

use constant STR_CHAR_CODE => 'utf8';
## UTF-8 → Perl内部文字列
sub utf82perlstr( $ )
{
    my( $octets  ) = @_;
    return Encode::decode( STR_CHAR_CODE, $octets );
#    return $octets;
}

#sub dPrint( @ )
#{
#    if( $main::debug ){
#        print( 'dbg: ', @_ );
#    }
#}

sub dPrintf( @ )
{
    if( $main::debug ){
        print( 'dbg: ' );
        printf( @_ );
    }
}

## Revision: 1.2
sub PrintVersion()
{
    my $ver = GetVersion();
    my $v = qq{Version: $ver\n} .
            qq{   Perl: $^V\n};
    print( $v );
}
sub GetVersion()
{
    my $rev = GetRevision();

    my $major = 1;
    my( $minor, $revision ) = split( /\./, $rev );
    my $version = sprintf( '%d.%02d.%03d', $major, $minor, $revision );

    return $version;
}
sub GetRevision()
{
    my $rev = q{$Revision: 1.20 $};
    $rev =~ s!^\$[R]evision: (\d+\.\d+) \$$!$1!o;
    return $rev;
}

sub set_locale( ;$ )
{
    my( $locale ) = @_;

    my $b_need_check = 0;
    my $is_this_a_getter = 0;
    my $refer_to_LANG = 0;
    my $lc_ctype = '';
    if( defined( $locale ) ){
        ## 空文字の場合はセッターではなくゲッターだが、
        ## このツールでは非サポート。
        if( $locale eq '' ){
            die( qq{set_locale(): error: "$locale": Specifying an empty string is not supported.\n} );
        }

        $lc_ctype = POSIX::setlocale( POSIX::LC_CTYPE, $locale );

        if( !defined( $lc_ctype ) ){
            ## システムでは $locale に対応していなくてもツールとしてサポート。
            $lc_ctype = $locale;
        }
    }else{
        $lc_ctype = POSIX::setlocale( POSIX::LC_CTYPE );

        # Android Termux環境では C と en_US のロケールしか使えない。
        # これ以外を LC_xxx に設定すると setlocale がエラーを出すので
        # このスクリプトでは LANG を参照することに。
        if( $lc_ctype =~ m/^C($|\.)/o ){
            if( defined( $ENV{LANG} ) ){
                $lc_ctype = $ENV{LANG};
            }
        }
    }

    return $lc_ctype;
}

sub set_locale_datafilename( $$ )
{
    my( $base, $locale ) = @_;
    $locale =~ s!\.utf-?8$!!oi;
    @main::datafile_loc = ();
    if( $locale =~ m/^([a-z]{2})_/o ){
        my $language = $1;
        push( @main::datafile_loc, "$base.$language" );
    }
    push( @main::datafile_loc, "$base.$locale" );
}

# uncoverable branch false
exit( pl_main( @ARGV ) ) unless caller();

__END__

=pod

=encoding utf8

=head1 NAME

TIMEZONE_ID -- List IANA timezone IDs.

=head1 DESCRIPTION

This uses the data bundled with the script rather than the host system's time zone data.
This design was chosen because the goal was to use the data simply as regional information from around the world, without relying on the system.

The data (table) was created using IANA Timezone IDs as keys.
It does not contain information such as the dates for transitions between daylight saving time and standard time. Since this tool only identifies the ID itself, the assumption is that you will use other tools—such as the `zdump` command—to look up further details.

Note: How to list the time zone definitions implemented in the system

  Linux:
    $ timedatectl list-timezones

    $ tzselect

    $ find /usr/share/zoneinfo -type f

  Windows:
    > tzutil /l

  Mac:
    # systemsetup -listtimezones

Note: How to check when the time zone switches between daylight saving time and standard time:

  # If you want to check for Paris in 2025
  $ zdump -v -c 2025,2026 Europe/Paris
  Europe/Paris  -9223372036854775808 (gmtime failed) = -9223372036854775808 (localtime failed)
  Europe/Paris  -67768040609741362 (gmtime failed) = -67768040609741362 (localtime failed)
  Europe/Paris  -67768040609741361 (gmtime failed) = Mon Jan  1 00:00:00 -2147481748 LMT isdst=0 gmtoff=561
  Europe/Paris  -67768040609740801 (gmtime failed) = Mon Jan  1 00:09:20 -2147481748 LMT isdst=0 gmtoff=561
  Europe/Paris  Mon Jan  1 00:00:00 -2147481748 UT = Mon Jan  1 00:09:21 -2147481748 LMT isdst=0 gmtoff=561
  Europe/Paris  Sun Mar 30 00:59:59 2025 UT = Sun Mar 30 01:59:59 2025 CET isdst=0 gmtoff=3600
  Europe/Paris  Sun Mar 30 01:00:00 2025 UT = Sun Mar 30 03:00:00 2025 CEST isdst=1 gmtoff=7200
  Europe/Paris  Sun Oct 26 00:59:59 2025 UT = Sun Oct 26 02:59:59 2025 CEST isdst=1 gmtoff=7200
  Europe/Paris  Sun Oct 26 01:00:00 2025 UT = Sun Oct 26 02:00:00 2025 CET isdst=0 gmtoff=3600
  Europe/Paris  67768036191673199 (gmtime failed) = Wed Dec 31 23:59:59 2147485547 CET isdst=0 gmtoff=3600
  Europe/Paris  67768036191673200 (gmtime failed) = 67768036191673200 (localtime failed)
  Europe/Paris  9223372036854775807 (gmtime failed) = 9223372036854775807 (localtime failed)

=head1 SYNOPSIS

$ timezone_id [ I<OPTIONS> ] [ I<PATTERN>... ]

=head1 PATTERN

Each I<PATTERN> can be:

=over 4

=item *

Filter by a single keyword:

  $ timezone_id JST
  SDT    SDT    Lat, Lon               IANA TZ id  Type       Country Code
  +09:00 JST    +35.67642, +139.65002  Asia/Tokyo  Canonical  JP; AU
  +09:00 JST    +34.64938, +135.00147  Japan       Link       JP

=item *

Specifying multiple keywords results in an AND condition:

  $ timezone_id 'America/' 'Fr'
  SDT    SDT    Lat, Lon               IANA TZ id           Type       Country Code
  −04:00 AST    +18.22083,  -66.59014  America/Puerto_Rico  Canonical  PR; AG; CA; AI; AW; BL; BQ; CW; DM; GD; GP; KN; LC; MF; MS; SX; TT; VC; VG; VI
  −04:00 AST    +18.06751,  -63.08246  America/Marigot      Link       MF
  −03:00 -3      +4.93797,  -52.33543  America/Cayenne      Canonical  GF

=item *

Use a vertical bar (|) to specify multiple keywords with an OR condition:

  $ timezone_id 'France|French'
  SDT    SDT    Lat, Lon               IANA TZ id           Type       Country Code
  −10:00 -10    -17.65091, -149.42604  Pacific/Tahiti       Canonical  PF
  −09:30 -930    -9.78121, -139.08171  Pacific/Marquesas    Canonical  PF
  −09:00 -9     -23.10965, -134.97434  Pacific/Gambier      Canonical  PF
  −04:00 AST    +18.22083,  -66.59014  America/Puerto_Rico  Canonical  PR; AG; CA; AI; AW; BL; BQ; CW; DM; GD; GP; KN; LC; MF; MS; SX; TT; VC; VG; VI
  −04:00 AST    +18.06751,  -63.08246  America/Marigot      Link       MF
  −03:00 -3      +4.93797,  -52.33543  America/Cayenne      Canonical  GF
  +01:00 CET    +48.85754,   +2.35137  Europe/Paris         Canonical  FR; MC
  +04:00 +4     +25.20484,  +55.27078  Asia/Dubai           Canonical  AE; OM; RE; SC; TF
  +05:00 +5      +3.20277,  +73.22068  Indian/Maldives      Canonical  MV; TF
  +05:00 +5     -55.19908,  +76.10015  Indian/Kerguelen     Link       TF

=back

=head1 OPTIONS

=over 4

=item -b, --banner

Show script banner.

=item -d, --debug

Enable debug output.

=item -h, --help

Display simple help and exit.

=item -i, --ignorecase

Ignore case distinctions in the I<PATTERN>.

=item --sort-order-by I<FIELD_NAME>

C<Lat>, C<Lon>, and C<ID> can be specified for I<FIELD_NAME>.
By default, they are sorted by the magnitude of the offset time difference.

Sort by longitude:

  $ timezone_id --sort-order-by 'Lon' 'Antarctica/' 'Link'
  SDT    SDT    Lat      ,  Lon        IANA TZ id                 Type       Country Code
  +12:00 NZST   -90      ,    0        Antarctica/South_Pole      Link       AQ
  +03:00 +3     -69.00439,  +39.5822   Antarctica/Syowa           Link       AQ
  +10:00 +10    -66.66359, +140.00325  Antarctica/DumontDUrville  Link       AQ
  +12:00 NZST   -77.84551, +166.66976  Antarctica/McMurdo         Link       AQ

=item -v, --verbose

Additional columns will be displayed.

  $ timezone_id 'Antarctica/' 'Link' --verbose
  SDT    SDT    DST    DST    Lat      ,  Lon        IANA TZ id                 Type       "Notes"  "Embedded comments"  "Country Code"  "Country Name"  ""
  +03:00 +3     +03:00 +3     -69.00439,  +39.5822   Antarctica/Syowa           Link       "Link to Asia/Riyadh"  "Syowa"  "AQ"  "Antarctica"  ""
  +10:00 +10    +10:00 +10    -66.66359, +140.00325  Antarctica/DumontDUrville  Link       "Link to Pacific/Port_Moresby"  "Dumont-d'Urville"  "AQ"  "Antarctica"  ""
  +12:00 NZST   +13:00 NZDT   -77.84551, +166.66976  Antarctica/McMurdo         Link       "Link to Pacific/Auckland"  "New Zealand time – McMurdo, South Pole"  "AQ"  "Antarctica"  ""
  +12:00 NZST   +13:00 NZDT   -90      ,    0        Antarctica/South_Pole      Link       "Link to Pacific/Auckland"  ""  "AQ"  "Antarctica"  ""

If LC_CTYPE is set to C<ja_JP.UTF-8>, Japanese information will also be displayed.

  $ timezone_id 'Antarctica/' 'Link' --verbose
  SDT    SDT    DST    DST    Lat      ,  Lon        IANA TZ id                 Type       "Notes"  "Embedded comments"  "Country Code"  "Country Name"  "Countries"  ID
  +03:00 +3     +03:00 +3     -69.00439,  +39.5822   Antarctica/Syowa           Link       "Link to Asia/Riyadh"  "Syowa"  "AQ"  "Antarctica"  "南極大陸"  南極大陸/昭和基地
  +10:00 +10    +10:00 +10    -66.66359, +140.00325  Antarctica/DumontDUrville  Link       "Link to Pacific/Port_Moresby"  "Dumont-d'Urville"  "AQ"  "Antarctica"  "南極大陸"  南極大陸/デュモン・デュルヴィル基地
  +12:00 NZST   +13:00 NZDT   -77.84551, +166.66976  Antarctica/McMurdo         Link       "Link to Pacific/Auckland"  "New Zealand time – McMurdo, South Pole"  "AQ"  "Antarctica"  "南極大陸"  南極大陸/マクマード基地
  +12:00 NZST   +13:00 NZDT   -90      ,    0        Antarctica/South_Pole      Link       "Link to Pacific/Auckland"  ""  "AQ"  "Antarctica"  "南極大陸"  南極大陸/南極点

=item --version

Print the version of this script and Perl and exit.

=back

=head1 ADVANCED USAGE

=over 4

=item *

Run the clock set to French time.

Search for France's time zone:

  $ timezone_id France
  SDT    SDT    Lat, Lon               IANA TZ id    Type       Country Code
  +01:00 CET    48.85754, 2.35137      Europe/Paris  Canonical  FR; MC

Change the time zone only for the duration of execution: (shell feature)

  $ TZ='Europe/Paris' date && date
  Sat Aug 22 18:06:02 CEST 2026
  Sun Aug 23 01:06:02 JST 2026

Run the clock:

  $ TZ='Europe/Paris' cl

Using latitude and longitude in a C<c script>:

  $ timezone_id 'Tokyo|Paris'
  SDT    SDT    Lat      ,  Lon        IANA TZ id     Type       Country Code
  +01:00 CET    +48.85754,   +2.35137  Europe/Paris   Canonical  FR; MC
  +01:00 CET    +43.73841,   +7.42461  Europe/Monaco  Link       MC
  +09:00 JST    +35.67642, +139.65002  Asia/Tokyo     Canonical  JP; AU
  +09:00 JST    +34.64938, +135.00147  Japan          Link       JP

  $ Paris='+48.85754,   +2.35137'
  $ Tokyo='+35.67642, +139.65002'

  # What's the distance?
  $ c "geo_distance_km( deg2rad( $Paris, $Tokyo ) )"
  9735.22180919

  # Which direction?
  $ c "geo_azimuth( deg2rad( $Paris, $Tokyo ) )"
  33.4304455215
  # Since the Earth is a sphere, the shortest route (great-circle route)
  # follows a northerly course passing near the North Pole.

=back

=head1 DEPENDENCIES

The minimum version of Perl required to run this script is Perl 5.14.0 or later.
If run on an older version, it will terminate safely with an error (specifically, a compilation error).

This script uses only B<core Perl modules>. No external modules from CPAN are required.

=head2 Core Modules Used

=over 4

=item * L<constant> - first released with perl 5.004

=item * L<Encode> - first released with perl v5.7.3

=item * L<File::Basename> — first included in perl 5

=item * L<Getopt::Long> - first released with perl 5

=item * L<POSIX> - first released with perl 5

=item * L<strict> — first included in perl 5

=item * L<utf8> - first released with perl v5.6.0

=item * L<warnings> — first included in perl v5.6.0

=back

=head2 Survey methodology

=over 4

=item 1. Preparation

Define the script name:

  $ target_script=timezone_id

=item 2. Extract used modules

Generate a list of modules from C<use> statements:

  $ grep '^use ' $target_script | sed 's!^use \([^ ;{][^ ;{]*\).*$!\1!' | \
      sort | uniq | tee ${target_script}.uselist

=item 3. Check core module status

Run C<corelist> for each module to find the first Perl version it appeared in:

  $ cat ${target_script}.uselist | while read line; do
      corelist $line
    done

=back

=head1 SEE ALSO

=over 4

=item L<C<c -- The Flat-Text Calculator (Perl Script)>|https://github.com/tomyama-code/tomyama_script_collection/blob/main/docs/c.md>

=item L<C<cl -- CLOCK PROGRAM>|https://github.com/tomyama-code/tomyama_script_collection/blob/main/docs/cl.md>

=item L<C<perl(1)>>

=back

=head1 AUTHOR

2026, tomyama

=head1 LICENSE

Copyright (c) 2026, tomyama

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

3. Neither the name of tomyama nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=cut