—

              
package ICANN::RST::Spec;
# ABSTRACT: an object representing the RST test specifications.
use Carp;
use Data::Mirror qw(mirror_file mirror_json);
use ICANN::RST::Case;
use ICANN::RST::ChangeLog;
use ICANN::RST::DataProvider;
use ICANN::RST::Error;
use ICANN::RST::Input;
use ICANN::RST::Plan;
use ICANN::RST::Resource;
use ICANN::RST::Suite;
use ICANN::RST::Text;
use List::Util qw(pairmap);
use URI;
use YAML::XS;
use constant SCHEMA_VERSION => q{1.14.0};
use feature qw(say);
use strict;
$YAML::XS::Boolean = q{JSON::PP};
sub url_from_release {
    my ($package, $release) = @_;
    return URI->new(sprintf(q{https://github.com/icann/rst-test-specs/releases/download/%s/rst-test-specs.yaml}, $release));
}
sub current_version { shift->url_from_release(mirror_json(q{https://api.github.com/repos/icann/rst-test-specs/releases/latest})->{name}) }
sub new_from_version {
    my ($package, $version) = @_;
    my $file = mirror_file($package->url_from_release($version));
    return $file ? $package->new($file) : undef;
}
sub new {
    my ($package, $file) = @_;
    $file ||= mirror_file($package->current_version);
    my $self = bless(
        {
            'spec' => YAML::XS::LoadFile($file),
            'file' => $file
        },
        $package,
    );
    my $v = version->parse($self->spec->{'RST-Test-Plan-Schema-Version'});
    croak(sprintf("Unsupported schema version '%s', must be '%s'", $v, SCHEMA_VERSION)) unless (SCHEMA_VERSION == $v);
    #
    # precompile everything
    #
    $self->{'_preamble'}    = ICANN::RST::Text->new($self->spec->{'Preamble'});
    $self->{'_plans'}       = [ sort { $a->order <=> $b->order  } pairmap {     ICANN::RST::Plan     -> new($a, $b, $self) } %{$self->spec->{'Test-Plans'}}       ];
    $self->{'_suites'}      = [ sort { $a->order <=> $b->order  } pairmap {     ICANN::RST::Suite    -> new($a, $b, $self) } %{$self->spec->{'Test-Suites'}}      ];
    $self->{'_cases'}       = [ sort {    $a->id cmp $b->id     } pairmap {     ICANN::RST::Case     -> new($a, $b, $self) } %{$self->spec->{'Test-Cases'}}       ];
    $self->{'_inputs'}      = [ sort {    $a->id cmp $b->id     } pairmap {     ICANN::RST::Input    -> new($a, $b, $self) } %{$self->spec->{'Input-Parameters'}} ];
    $self->{'_resources'}   = [ sort {    $a->id cmp $b->id     } pairmap {   ICANN::RST::Resource   -> new($a, $b, $self) } %{$self->spec->{'Resources'}}        ];
    $self->{'_errors'}      = [ sort {    $a->id cmp $b->id     } pairmap {    ICANN::RST::Error     -> new($a, $b, $self) } %{$self->spec->{'Errors'}}           ];
    $self->{'_providers'}   = [ sort {    $a->id cmp $b->id     } pairmap { ICANN::RST::DataProvider -> new($a, $b, $self) } %{$self->spec->{'Data-Providers'}}   ];
    return $self;
}
sub changelog {
    my $self = shift;
    my @log;
    foreach my $date (reverse(sort(keys(%{$self->spec->{'ChangeLog'}})))) {
        push(@log, ICANN::RST::ChangeLog->new($date, $self->spec->{'ChangeLog'}->{$date}, $self));
    }
    return @log;
}
sub spec            { $_[0]->{'spec'}                                                   }
sub schemaVersion   { $_[0]->spec->{'RST-Test-Plan-Schema-Version'}                     }
sub version         { $_[0]->spec->{'Version'}                                          }
sub lastUpdated     { $_[0]->spec->{'Last-Updated'}                                     }
sub contactName     { $_[0]->spec->{'Contact'}->{'Name'}                                }
sub contactOrg      { $_[0]->spec->{'Contact'}->{'Organization'}                        }
sub contactEmail    { $_[0]->spec->{'Contact'}->{'Email'}                               }
sub preamble        { $_[0]->{'_preamble'}                                              }
sub plans           { @{ $_[0]->{'_plans'} }                                            }
sub suites          { @{ $_[0]->{'_suites'} }                                           }
sub cases           { @{ $_[0]->{'_cases'} }                                            }
sub inputs          { @{ $_[0]->{'_inputs'} }                                           }
sub resources       { @{ $_[0]->{'_resources'} }                                        }
sub errors          { @{ $_[0]->{'_errors'} }                                           }
sub providers       { @{ $_[0]->{'_providers'} }                                        }
sub plan            { my ($self, $id) = @_ ; return $self->find($id, $self->plans)      }
sub suite           { my ($self, $id) = @_ ; return $self->find($id, $self->suites)     }
sub case            { my ($self, $id) = @_ ; return $self->find($id, $self->cases)      }
sub resource        { my ($self, $id) = @_ ; return $self->find($id, $self->resources)  }
sub error           { my ($self, $id) = @_ ; return $self->find($id, $self->errors)     }
sub input           { my ($self, $id) = @_ ; return $self->find($id, $self->inputs)     }
sub provider        { my ($self, $id) = @_ ; return $self->find($id, $self->providers)  }
sub find {
    my ($self, $needle, @haystack) = @_;
    foreach my $stick (@haystack) {
        return $stick if ($stick->id eq $needle);
    }
    carp("object '$needle' not found");
    return undef;
}
1;
__END__
HideShow 128 lines of Pod
=pod
=encoding UTF-8
=head1 NAME
ICANN::RST::Spec - an object representing the RST test specifications.
=head1 VERSION
version 0.03
=head1 METHODS
=head2 new($file)
Constructor. C<$file> is the YAML file. If not provided, the most recent
version will be retrieved from
L<GitHub|https://github.com/icann-rst-test/specs/releases>.
=head2 new_from_version($version);
Returns an L<ICANN::RST::Spec> object corresponding to the version of the test
specs identified by C<$version>.
=head2 schemaVersion()
Returns a string containing the schema version of the spec file.
=head2 version()
Returns a string containing the version of the spec file.
=head2 lastUpdated()
Returns a string containing the date the spec was last updated.
=head2 preamble()
Returns a L<ICANN::RST::Text> object containing the preamble.
=head2 changelog()
Returns an array of L<ICANN::RST::ChangeLog> objects.
=head2 contactName()
Returns a string containing the contact name.
=head2 contactOrg()
Returns a string containing the contact organisation.
=head2 contactEmail()
Returns a string containing the contact email.
=head2 plans()
Returns an array of L<ICANN::RST::Plan> objects.
=head2 plan($id)
Returns the L<ICANN::RST::Plan> object with the given ID.
=head2 suites()
Returns an array of L<ICANN::RST::Suite> objects.
=head2 suite($id)
Returns the L<ICANN::RST::Suite> object with the given ID.
=head2 resources()
Returns an array of L<ICANN::RST::Resource> objects.
=head2 resource($id)
Returns the L<ICANN::RST::Resource> object with the given ID.
=head2 cases()
Returns an array of L<ICANN::RST::Case> objects.
=head2 case($id)
Returns the L<ICANN::RST::Case> object with the given ID.
=head2 inputs()
Returns an array of L<ICANN::RST::Input> objects.
=head2 input($id)
Returns the L<ICANN::RST::Input> object with the given ID.
=head2 errors()
Returns an array of L<ICANN::RST::Error> objects.
=head2 error($id)
=head2 providers()
Returns an array of L<ICANN::RST::Error> objects.
=head2 provider($id)
Returns the L<ICANN::RST::DataProvider> object with the given ID.
=head2 spec()
Returns a hashref of the specification data structure.
=head1 AUTHOR
Gavin Brown <gavin.brown@icann.org>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2025 by Internet Corporation for Assigned Names and Number (ICANN).
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut