X::Protocol - Perl6 Exception superclass for protocol result codes

NAME

SYNOPSIS



    # A simple example for a protocol that just has error codes
    class X::Protocol::SneakerNet is X::Protocol {
        method protocol { "SneakerNet" }
    }
    my @errors = X::Protocol::SneakerNet.new(:status(10)),
                 X::Protocol::SneakerNet.new(:status("11")),
                 X::Protocol::SneakerNet.new(:status("12.5")),
                 X::Protocol::SneakerNet.new(:status("13W")),
                 X::Protocol::SneakerNet.new(:status("XL")),
                 X::Protocol::SneakerNet.new(:status("XXL"));

    # A default .Numeric and .Str are provided based on :status,
    # so you can handle the above errors like this:
    for @errors {
        when 10     { say "Matches the first one" }
        when 11     { say "Matches the second one" }
        when 12.5   { say "Matches the third one" }
        when "13W"  { say "Matches the fourth one" }
        when /XL/   { say "Matches the fifth and sixth one" }
    }
    #-> Matches the first one
    #-> Matches the second one
    #-> Matches the third one
    #-> Matches the fourth one
    #-> Matches the fifth and sixth one
    #-> Matches the fifth and sixth one

    # This shows several of the more useful tweaks available:
    # 1) human-readable strings via a "codes" method
    # 2) custom "severity" levels and mapping from status to severity.
    # 3) custom "toss" method to perform actions like throw or fail.

    class X::Protocol::IPoUSPO is X::Protocol {
        method protocol { "IPoUSPO" }
        method codes {
            {
                500 => "Chased away by dog",
                400 => "A snowy, rainy, hot and gloomy night",
                200 => "Delivered"
            }
	}
        method severity { ~$.status ~~ /\d/ // "unknown" }
        method toss {
            if self.severity > 4 { self.fail }
            elsif self.severity > 2 { self.throw }
            else { note self.gist }
        }
    }

    # The default message shows protocol, severity, status, human-friendly text
    X::Protocol::IPoUSPO.new(:200status).say;
    #-> IPoUSPO 2: 200 -- Delivered

    # The default .Str is just the stringified status.
    print X::Protocol::IPoUSPO.new(:400status), "\n";
    #-> 400

    # For one-offs you must supply a per-instance protocol name
    # The human readable text is optional 
    X::Protocol.new(:404status :protocol<HTTP> :human<Oops>).say;
    #-> "HTTP error: 404 -- Oops"

    # One-offs can also provide an override for the human message
    X::Protocol::IPoUSPO.new(:200status :human<OK>).say;
    #-> IPoUSPO 2: 200 -- OK

    # By default unknown codes produce no human text
    X::Protocol::IPoUSPO.new(:201status).say;
    #-> IPoUSPO 2: 200

ATTRIBUTES

An instance of this base class has only three actual attributes:

.status -- the machine-friendly status code a protocol produced.
.human -- an optional override to the human-readable message.
!protocol -- the name of the protocol, usually set by default.

AUTHOR

Brian S. Julin

COPYRIGHT

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License 2.0.

SEE-ALSO

Exception::(pm3)