### ----------------------------------------------------
### -- IRC::Utils
### -- Licenses: Artistic-2.0
### -- Authors: 
### -- File: lib/IRC/Utils.rakumod
### ----------------------------------------------------
### -- Chunk 2 of 2
/server mask.

Returns C<$mask> as a fully qualified mask.

Example:

=begin code :lang<raku>

    my Str $mask = normalize_mask('*@*');

    say $mask;
    # Output: *!*@*

=end code

=head2 numeric_to_name(Int $code)

Converts an IRC reply or error code to its corresponding string representation.
This includes all values defined by RFC 1459 and also a few network-specific
extensions.

The C<$code> parameter is an integer representing the numeric code to convert.
For instance, 461 which is C<ERR_NEEDMOREPARAMS>.

Returns the string representation of C<$code>.

Example:

=begin code :lang<raku>

my Str $topic = numeric_to_name(332);

say $topic;
# Output: RPL_TOPIC

=end code

=head2 name_to_numeric(Str $name)

Converts a string representation of an IRC reply or error code into its
corresponding numeric code. This includes all values defined by RFC 1459 and
also a few network-specific extensions.

The C<$name> parameter is a string representing the reply or error code. For
instance, C<ERR_NEEDMOREPARAMS> is 461.

Returns the numerical representation of C<$name>.

Example:

=begin code :lang<raku>

my Int $topic name_to_numeric('RPL_TOPIC');

say $topic;
# Output: 332

=end code

=head2 is_valid_nick_name(Str $nick)

Checks if an IRC nickname is valid. That is, it conforms to the allowable
characters defined in RFC 1459.

The C<$nick> parameter is a string representing the nickname to validate.

Returns C<Bool::True> if C<$nick> is a valid IRC nickname and C<Bool::False>
otherwise.

Example:

=begin code :lang<raku>

my Bool $valid_nick = is_valid_nick_name('{foo_bar_baz}');

say 'Nickname is valid!' if $valid_nick;
# Output: Nickname is valid!

=end code

=head2 is_valid_chan_name(Str $chan, Str @types?)

Checks if an IRC channel name is valid. That is, it conforms to the allowable
characters defined in RFC 1459.

The C<$chan> parameter is a string representing the channel name to check.

The C<@types> parameter is an optional anonymous list of channel types. For
instance, '#'. If not given, it defaults to C<['#', '&']>.

Returns C<Bool::True> if C<$nick> is a valid IRC channel name and C<Bool::False>
otherwise.

Example:

=begin code :lang<raku>

my Bool $valid_chan = is_valid_chan_name('#foobar');

say 'Channel name is valid!' if $valid_chan;
# Output: Channel name is valid!

=end code

=head2 unparse_mode_line(Str $line)

Condenses or "unparses" an IRC mode line.

The C<$line> parameter is a string representing an arbitrary number of mode
changes.

Returns the condensed version of C<$line> as a string.

Example:

=begin code :lang<raku>

my Str $mode = unparse_mode_line('+m+m+m-i+i');

say $mode;
# Output: +mmm-i+i

=end code

=head2 gen_mode_change(Str $before, Str $after)

Determines the changes made between two IRC user modes.

The C<$before> parameter is a string representing the user mode before the
change.

The C<$after> parameter is a string representing the user mode after the
change.

Returns a string representing the modes that changed between C<$before> and
C<$after>. That is, any modes that were added or removed from C<$before> to
create C<$after>.

Example:

=begin code :lang<raku>

my Str $mode_change = gen_mode_change('abcde', 'befmZ');

say $mode_change;
# Output: -acd+fmZ

=end code

=head2 matches_mask(Str $mask, Str $match, Str $mapping?)

Determines whether a particular user/server matches an IRC mask.

The C<$mask> parameter is a string representing the IRC mask to match against.

The C<$match> parameter is a string representing the user/server to check.

The C<$mapping> parameter is an optional string that specifies which
casemapping to use for C<$mask> and C<$match>. It can be 'rfc1459',
'strict-rfc1459', or 'ascii'. If not given, it defaults to 'rfc1459'.

Example:

=begin code :lang<raku>

my Str  $banmask = 'foobar*!*@*';
my Str  $user    = 'foobar!baz@qux.net';
my Bool $matches = matches_mask($banmask, $user);

say "The user $user is banned" if $matches;
# Output: The user foobar!baz@qux.net is banned

=end code

=head2 parse_user(Str $user)

Parses a fully-qualified IRC username and splits it into the parts representing
the nickname, username, and hostname.

The C<$user> parameter is a string representing the fully-qualified username to
parse. It must be of the form C<nick!user@host>.

Returns a list containing the nickname, username, and hostname parts of
C<$user>.

Example:

=begin code :lang<raku>

my Str ($nick, $user, $host) = parse_user('foo!bar@baz.net');

say $nick
# Output: foo

say $user
# Output: bar

say $host
# Output: baz.net

=end code

=head2 has_color(Str $string)

Checks if a string contains any embedded color codes.

The C<$string> parameter is the string to check.

Returns C<Bool::True> if C<$string> contains any embedded color codes and
C<Bool::False> otherwise.

Example:

=begin code :lang<raku>

my Bool $color = has_color("\x0304,05This is a colored message\x03");

say 'Oh, pretty colors!' if $color;
# Output: Oh, pretty colors!

=end code

=head2 has_formatting(Str $string)

Checks if a string contains any embedded text formatting codes.

The C<$string> parameter is the string to check.

Returns C<Bool::True> if C<$string> contains any embedded formatting codes and
C<Bool::False> otherwise.

Example:

=begin code :lang<raku>

my Bool $fmt_text = has_formatting("This message has \x1funderlined\x0f text");

say 'I got some formatted text!' if $fmt_text;
# Output: I got some formatted text!

=end code

=head2 strip_color(Str $string)

Strips a string of all embedded color codes (if any).

The C<$string> parameter is the string to strip.

Returns the string given in C<$string> with all embedded color codes removed.
If the given string does not contain any color codes, the original string is
returned as is.

Example:

=begin code :lang<raku>

my Str $stripped = strip_color("\x03,05Look at the pretty colors!\x03");

say $stripped;
# Output: Look at the pretty colors!

=end code

=head2 strip_formatting(Str $string)

Strips a string of all embedded text formatting codes (if any).

The C<$string> parameter is the string to strip.

Returns the string given in C<$string> with all embedded text formatting codes
removed. If the given string does not contain any text formatting codes, the
original string is returned as is.

Example:

=begin code :lang<raku>

my Str $stripped = strip_formatting('This is \x02strong\x0f!");

say $stripped;
# Output: This is strong!

=end code

=head1 CONSTANTS

The following constants are provided to embed color and formatting codes in IRC
messages.

=head2 Normal text

    NORMAL

=head2 Formatting

    BOLD
    UNDERLINE
    REVERSE
    ITALIC
    FIXED

=head2 Colors

    WHITE
    BLACK
    BLUE
    GREEN
    RED
    BROWN
    PURPLE
    ORANGE
    YELLOW
    LIGHT_GREEN
    TEAL
    LIGHT_CYAN
    LIGHT_BLUE
    PINK
    GREY
    LIGHT_GREY

To terminate a single formatting code, you must use its respective constant.
Additionally, you may use the C<NORMAL> constant to terminate I<all> formatting
codes (including colors).

Conversely, a single color code must be terminated with the C<NORMAL> constant.
However, this has the side effect of also terminating any other formatting
codes.

Example:

=begin code :lang<raku>

my Str $foo = 'Oh hai! I haz ' ~ GREEN ~ 'green ' ~ NORMAL ~ 'text!';
my Str $bar = BOLD ~ UNDERLINE ~ 'K thx bye!' ~ NORMAL;

=end code

=head1 AUTHOR

Kevin Polulak

=head1 COPYRIGHT AND LICENSE

Copyright 2011 Kevin Polulak

Copyright 2012 - 2022 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4


