txt: ## dist_zef-raku-community-modules-IRC-Utils.md
  [![Actions Status](https://github.com/raku-community-modules/IRC-Utils/actions/workflows/test.yml/badge.svg)](https://github.com/raku-community-modules/IRC-Utils/actions)
  
  # NAME
  
  IRC::Utils - handy IRC utilities for use in other IRC-related modules
  
  # SYNOPSIS
  
  ```
  use IRC::Utils;
  
  my Str $nick    = '[foo]^BAR^[baz]';
  my Str $uc_nick = uc_irc($nick);
  my Str $lc_nick = lc_irc($nick);
  
  # Check equivalence of two nicknames
  if eq_irc($uc_nick, $lc_nick) {
      say "These nicknames are the same!";
  }
  
  # Check if nickname conforms to RFC1459
  if is_valid_nick_name($nick) {
      say "Nickname is valid!";
  }
  
  ```
  
  # DESCRIPTION
  
  The `IRC::Utils` module provides a procedural interface for performing many common IRC-related tasks such as comparing nicknames, changing user modes, normalizing ban masks, etc. It is meant to be used as a base module for creating other IRC-related modules.
  
  Internet Relay Chat (IRC) is a teleconferencing system used for real-time Internet chatting and conferencing. It is primarily used for group communication but also allows private one-to-one messages. The protocol is published in RFC 1459 <https://www.rfc-editor.org/rfc/rfc1459.txt>.
  
  # SUBROUTINES
  
  Unlike the `IRC::Utils` module for Perl 5, you do not need to specify the `:ALL` tag when importing the module. Therefore, the following subroutines are exported into the caller's namespace by default.
  
  ## uc\_irc(Str $value, Str $type?)
  
  Converts a string to uppercase that conforms to the allowable characters as defined by RFC 1459.
  
  The `$value` parameter represents the string to convert to uppercase.
  
  The `$type` parameter is an optional string that represents `$value`'s casemapping. It can be 'rfc1459', 'strict-rfc1459', or 'ascii'. If not given, it defaults to 'rfc1459'.
  
  Returns the value of `$value` converted to uppercase according to `$type`.
  
  Example:
  
  ```
  my Str $uc_hello = uc_irc('Hello world!');
  
  say $hello;
  # Output: HELLO WORLD!
  
  ```
  
  -head2 lc\_irc(Str $value, Str $type?)
  
  Converts a string to lowercase that conforms to the allowable characters as defined by RFC 1459.
  
  The `$value` parameter represents the string to convert to lowercase.
  
  The `$type` parameter is an optional string that represents `$value`'s casemapping. It can be 'rfc1459', 'strict-rfc1459', or 'ascii'. If not given, it defaults to 'rfc1459'.
  
  Returns the value of `$value` converted to lowercase according to `$type`.
  
  Example:
  
  ```
  my Str $lc_hello = lc_irc('HELLO WORLD!');
  
  say $lc_irc;
  # Output: hello world!
  
  ```
  
  ## eq\_irc(Str $first, Str $second, Str $type?)
  
  Checks the equivalence of two strings that conform to the allowable characters as defined by RFC 1459.
  
  The `$first` parameter is the first string to compare.
  
  The `$second` parameter is the second string to compare.
  
  The `$type` parameter is an optional string that represents the casemapping of `$first` and `$second`. It can be 'rfc1459', 'strict-rfc1459', or 'ascii'. If not given, it defaults to 'rfc1459'.
  
  Returns `Bool::True` if the two strings are equivalent and `Bool::False` otherwise.
  
  Example:
  
  ```
  my Str  $upper = '[F00~B4R~B4Z]';
  my Str  $lower = '{f00~b4r~b4z}';
  my Bool $equal =  eq_irc();
  
  say 'They're equal!' if $equal;
  # Output: They're equal!
  
  ```
  
  ## parse\_mode\_line(@mode)
  
  Parses a list representing an IRC status mode line.
  
  The `@mode` parameter is an array representing the status mode line to parse. You may also pass an array or hash to specify valid channel and status modes. If not given, the valid channel modes default to `<beI k l imnpstaqr>` and the valid status modes default to `{o => '@', h => '%', v => '+'}` .
  
  Returns a hash containing two keys: `modes` and `args`. The `modes` key is an array of normalized modes. The `args` key is an array that represents the relevant arguments to the modes in `modes`.
  
  If for any reason the mode line in `@mode` can not be parsed, a `Nil` hash will be returned.
  
  Example:
  
  ```
  my %hash = parse_mode_line(<ov foo bar>);
  
  say %hash<modes>[0];  # +o
  
  say %hash<modes>[1];  # +v
  
  say %hash<args>[0];   # foo
  
  say %hash<args>[1];   # bar
  
  ```
  
  ## normalize\_mask(Str $mask)
  
  Fully qualifies or "normalizes" an IRC host/server mask.
  
  The `$mask` argument is a string representing a host/server mask.
  
  Returns `$mask` as a fully qualified mask.
  
  Example:
  
  ```
      my Str $mask = normalize_mask('*@*');
  
      say $mask;
      # Output: *!*@*
  
  ```
  
  ## 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 `$code` parameter is an integer representing the numeric code to convert. For instance, 461 which is `ERR_NEEDMOREPARAMS`.
  
  Returns the string representation of `$code`.
  
  Example:
  
  ```
  my Str $topic = numeric_to_name(332);
  
  say $topic;
  # Output: RPL_TOPIC
  
  ```
  
  ## 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 `$name` parameter is a string representing the reply or error code. For instance, `ERR_NEEDMOREPARAMS` is 461.
  
  Returns the numerical representation of `$name`.
  
  Example:
  
  ```
  my Int $topic name_to_numeric('RPL_TOPIC');
  
  say $topic;
  # Output: 332
  
  ```
  
  ## 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 `$nick` parameter is a string representing the nickname to validate.
  
  Returns `Bool::True` if `$nick` is a valid IRC nickname and `Bool::False` otherwise.
  
  Example:
  
  ```
  my Bool $valid_nick = is_valid_nick_name('{foo_bar_baz}');
  
  say 'Nickname is valid!' if $valid_nick;
  # Output: Nickname is valid!
  
  ```
  
  ## 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 `$chan` parameter is a string representing the channel name to check.
  
  The `@types` parameter is an optional anonymous list of channel types. For instance, '#'. If not given, it defaults to `['#', '&']`.
  
  Returns `Bool::True` if `$nick` is a valid IRC channel name and `Bool::False` otherwise.
  
  Example:
  
  ```
  my Bool $valid_chan = is_valid_chan_name('#foobar');
  
  say 'Channel name is valid!' if $valid_chan;
  # Output: Channel name is valid!
  
  ```
  
  ## unparse\_mode\_line(Str $line)
  
  Condenses or "unparses" an IRC mode line.
  
  The `$line` parameter is a string representing an arbitrary number of mode changes.
  
  Returns the condensed version of `$line` as a string.
  
  Example:
  
  ```
  my Str $mode = unparse_mode_line('+m+m+m-i+i');
  
  say $mode;
  # Output: +mmm-i+i
  
  ```
  
  ## gen\_mode\_change(Str $before, Str $after)
  
  Determines the changes made between two IRC user modes.
  
  The `$before` parameter is a string representing the user mode before the change.
  
  The `$after` parameter is a string representing the user mode after the change.
  
  Returns a string representing the modes that changed between `$before` and `$after`. That is, any modes that were added or removed from `$before` to create `$after`.
  
  Example:
  
  ```
  my Str $mode_change = gen_mode_change('abcde', 'befmZ');
  
  say $mode_change;
  # Output: -acd+fmZ
  
  ```
  
  ## matches\_mask(Str $mask, Str $match, Str $mapping?)
  
  Determines whether a particular user/server matches an IRC mask.
  
  The `$mask` parameter is a string representing the IRC mask to match against.
  
  The `$match` parameter is a string representing the user/server to check.
  
  The `$mapping` parameter is an optional string that specifies which casemapping to use for `$mask` and `$match`. It can be 'rfc1459', 'strict-rfc1459', or 'ascii'. If not given, it defaults to 'rfc1459'.
  
  Example:
  
  ```
  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
  
  ```
  
  ## parse\_user(Str $user)
  
  Parses a fully-qualified IRC username and splits it into the parts representing the nickname, username, and hostname.
  
  The `$user` parameter is a string representing the fully-qualified username to parse. It must be of the form `nick!user@host`.
  
  Returns a list containing the nickname, username, and hostname parts of `$user`.
  
  Example:
  
  ```
  my Str ($nick, $user, $host) = parse_user('foo!bar@baz.net');
  
  say $nick
  # Output: foo
  
  say $user
  # Output: bar
  
  say $host
  # Output: baz.net
  
  ```
  
  ## has\_color(Str $string)
  
  Checks if a string contains any embedded color codes.
  
  The `$string` parameter is the string to check.
  
  Returns `Bool::True` if `$string` contains any embedded color codes and `Bool::False` otherwise.
  
  Example:
  
  ```
  my Bool $color = has_color("\x0304,05This is a colored message\x03");
  
  say 'Oh, pretty colors!' if $color;
  # Output: Oh, pretty colors!
  
  ```
  
  ## has\_formatting(Str $string)
  
  Checks if a string contains any embedded text formatting codes.
  
  The `$string` parameter is the string to check.
  
  Returns `Bool::True` if `$string` contains any embedded formatting codes and `Bool::False` otherwise.
  
  Example:
  
  ```
  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!
  
  ```
  
  ## strip\_color(Str $string)
  
  Strips a string of all embedded color codes (if any).
  
  The `$string` parameter is the string to strip.
  
  Returns the string given in `$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:
  
  ```
  my Str $stripped = strip_color("\x03,05Look at the pretty colors!\x03");
  
  say $stripped;
  # Output: Look at the pretty colors!
  
  ```
  
  ## strip\_formatting(Str $string)
  
  Strips a string of all embedded text formatting codes (if any).
  
  The `$string` parameter is the string to strip.
  
  Returns the string given in `$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:
  
  ```
  my Str $stripped = strip_formatting('This is \x02strong\x0f!");
  
  say $stripped;
  # Output: This is strong!
  
  ```
  
  # back
  
  # CONSTANTS
  
  The following constants are provided to embed color and formatting codes in IRC messages.
  
  ## Normal text
  
  ```
  NORMAL
  
  ```
  
  ## Formatting
  
  ```
  BOLD
  UNDERLINE
  REVERSE
  ITALIC
  FIXED
  
  ```
  
  ## 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 `NORMAL` constant to terminate *all* formatting codes (including colors).
  
  Conversely, a single color code must be terminated with the `NORMAL` constant. However, this has the side effect of also terminating any other formatting codes.
  
  Example:
  
  ```
  my Str $foo = 'Oh hai! I haz ' ~ GREEN ~ 'green ' ~ NORMAL ~ 'text!';
  my Str $bar = BOLD ~ UNDERLINE ~ 'K thx bye!' ~ NORMAL;
  
  ```
  
  # AUTHOR
  
  Kevin Polulak
  
  # 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.
  