Image

head

code

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

use v6.*;

role IRC::Log:ver<0.0.10>:auth<zef:lizmat> {
    has Date $.date;
    has Str  $.raw;
    has      $.entries;
    has Int  $.nr-control-entries;
    has Int  $.nr-conversation-entries;
    has      $.last-topic-change;
    has      @.problems;
    has      %.nicks;
    has      %!state;  # hash with final state of internal parsing

#-------------------------------------------------------------------------------
# Main log parser logic

    method !INIT() {
        $!entries := IterationBuffer.CREATE;
        self
    }

    method parse(::?CLASS:D: Str:D $slurped, Date:D $date) is implementation-detail {
        ...
    }

#-------------------------------------------------------------------------------
# Class methods

    method IO2Date(::?CLASS:U: IO:D $path) {
        try $path.basename.split(".").head.Date
    }

    proto method new(|) {*}
    multi method new(::?CLASS:U:
      IO:D $path,
      Date() $date = self.IO2Date($path)
    ) {
        my $instance := self.CREATE!INIT;
        $instance.parse($path.slurp(:enc("utf8-c8")), $date);
        $instance
    }

    multi method new(::?CLASS:U:
      Str:D $slurped,
      Date() $date
    ) {
        my $instance := self.CREATE!INIT;
        $instance.parse($slurped, $date);
        $instance
    }

#-------------------------------------------------------------------------------
# Instance methods

    method first-target(::?CLASS:D:) {
        $!entries[0].target
    }
    method last-target(::?CLASS:D:) {
        $!entries[$!entries.elems - 1].target
    }
    method this-target(::?CLASS:D: Str:D $target) {
        $!entries.List.first($target eq *.target)
    }

    multi method update(::?CLASS:D: IO:D $path) {
        self.parse($path.slurp(:enc("utf8-c8")), $!date)
    }
    multi method update(::?CLASS:D: Str:D $slurped) {
        self.parse($slurped, $!date)
    }
}

#-------------------------------------------------------------------------------
# Expected messsage types

role IRC::Log::Entry {
    has     $.log  is built(:bind);
    has int $!hmop is built(:bind);
    has str $.nick is built(:bind);

    method TWEAK(int :$hour, int :$minute, int :$ordinal, int :$pos) {
        $!hmop = $hour +< 56 + $minute +< 48 + $ordinal +< 32 + $pos;
    }

    method target() {
        my int $hour    = $.hour;
        my int $minute  = $.minute;
        my int $ordinal = $.ordinal;

        my $target = self.date
          ~ 'Z'
          ~ ($hour < 10 ?? "0$hour" !! $hour)
          ~ ':'
          ~ ($minute < 10 ?? "0$minute" !! $minute);

        $target = $target ~ '-' ~ ($ordinal < 10
          ?? "000$ordinal"
          !! $ordinal < 100
            ?? "00$ordinal"
            !! $ordinal < 1000
              ?? "0$ordinal"
              !! $ordinal
        ) if $ordinal;
        $target
    }

    method hour()     { $!hmop +> 56 +&   0xff }
    method minute()   { $!hmop +> 48 +&   0xff }
    method ordinal()  { $!hmop +> 32 +& 0xffff }
    method pos()      { $!hmop       +& 0xffff }
    method date()     { $!log.date     }
    method entries()  { $!log.entries  }
    method problems() { $!log.problems }

    method prev() {
        if self.pos -> int $pos {
            $!log.entries[$pos - 1]
        }
    }
    method next() {
        $!log.entries[self.pos + 1] // Empty
    }

    method prefix(--> '*** ') { }
    method gist() {
        '[' ~ self.hh-mm ~ '] ' ~ self.prefix ~ self.message
    }

    method sender(--> '') { }
    method control(      --> True) { }
    method conversation(--> False) { }

    method hhmm() { 
        my int $hour   = $.hour;
        my int $minute = $.minute;
        ($hour < 10 ?? "0$hour" !! $hour)
          ~ ($minute < 10 ?? "0$minute" !! $minute)
    }
    method hh-mm() { 
        my int $hour   = $.hour;
        my int $minute = $.minute;
        ($hour < 10 ?? "0$hour" !! $hour)
          ~ ":"
          ~ ($minute < 10 ?? "0$minute" !! $minute)
    }
}

class IRC::Log::Joined does IRC::Log::Entry {
    method message() { "$!nick joined" }
}
class IRC::Log::Left does IRC::Log::Entry {
    method message() { "$!nick left" }
}
class IRC::Log::Kick does IRC::Log::Entry {
    has Str $.kickee is built(:bind);
    has Str $.spec   is built(:bind);

    method message() { "$!kickee was kicked by $!nick $!spec" }
}
class IRC::Log::Message does IRC::Log::Entry {
    has Str $.text is built(:bind);

    method gist() { '[' ~ self.hh-mm ~ '] <' ~ $.nick ~ '> ' ~ $.message }
    method sender() { $!nick }
    method message() { $!text }
    method prefix(--> '') { }
    method control(    --> False) { }
    method conversation(--> True) { }
}
class IRC::Log::Mode does IRC::Log::Entry {
    has Str $.flags is built(:bind);
    has Str @.nicks is built(:bind);

    method message() { "$!nick sets mode: $!flags @.nicks.join(" ")" }
}
class IRC::Log::Nick-Change does IRC::Log::Entry {
    has Str $.new-nick is built(:bind);

    method message() { "$!nick is now known as $!new-nick" }
}
class IRC::Log::Self-Reference does IRC::Log::Entry {
    has Str $.text is built(:bind);

    method prefix(--> '* ') { }
    method message() { "$!nick $!text" }
    method control(    --> False) { }
    method conversation(--> True) { }
}
class IRC::Log::Topic does IRC::Log::Entry {
    has Str $.text is built(:bind);

    method message() { "$!nick changes topic to: $!text" }
    method conversation(--> True) { }
}

#-------------------------------------------------------------------------------
# Documentation



IRC::Log - role providing interface to IRC logs


=begin code :lang<raku>

use IRC::Log;

class IRC::Log::Foo does IRC::Log {
    method parse($slurped, $date) {
        # Nil for already parsed and no change
        #   0 for initial parse
        # > 0 number of entries added after update
    }
}

my $log = IRC::Log::Foo.new($filename.IO);

say "Logs from $log.date()";
.say for $log.entries.List;

my $log = IRC::Log::Foo.new($text, $date);

=end code


IRC::Log provides a role providing an interface to IRC logs in various
formats.  Each log is supposed to contain all messages from a given
date.


The C<parse> method must be provided by the consuming class.


=begin code :lang<raku>

my $log = IRC::Log::Foo.new($filename.IO);

my $log = IRC::Log::Foo.new($text, $date);

=end code


The C<new> class method either takes an C<IO> object as the first parameter,
and a C<Date> object as the optional second parameter (eliding the C<Date>
from the basename if not specified), and returns an instantiated object
representing the entries in that log file.


Or it will take a C<Str> as the first parameter for the text of the log,
and a C<Date> as the second parameter.


Any lines that can not be interpreted, are ignored: they are available
with the C<problems> method.


=begin code :lang<raku>

with IRC::Log::Foo.IO2Date($path) -> $date {
    say "the date of $path is $date";
}
else {
    say "$path does not appear to be a log file";
}

=end code


The C<IO2Date> class method interpretes the given C<IO::Path> object
and attempts to elide a C<Date> object from it.  It returns C<Nil> if
it could not.


=begin code :lang<raku>

.say for $log.entries.List;                      # all entries

.say for $log.entries.Seq.grep(*.conversation);  # only actual conversation

=end code


The C<entries> instance method returns an IterationBuffer with entries from
the log.  It contains instances of one of the following classes:


IRC::Log::Joined
IRC::Log::Left
IRC::Log::Kick
IRC::Log::Message
IRC::Log::Mode
IRC::Log::Nick-Change
IRC::Log::Self-Reference
IRC::Log::Topic


=begin code :lang<raku>

say $log.date;

=end code


The C<date> instance method returns the C<Date> object for this log.


=begin code :lang<raku>

say $first-target;  # 2021-04-23

=end code


The C<first-target> instance method returns the C<target> of the first entry.


=begin code :lang<raku>

say $last-target;  # 2021-04-29

=end code


The C<last-target> instance method returns the C<target> of the last entry.


=begin code :lang<raku>

say $last-topic-change;  # liz changed topic to "hello world"

=end code


The C<last-topic-change> instance method returns the entry that contains the
last change of topic.  Returns C<Nil> if there wasn't any topic change.


=begin code :lang<raku>

for $log.nicks.sort(*.key) -> (:key($nick), :value($entries)) {
    say "$nick has $entries.elems() entries";
}

=end code


The C<nicks> instance method returns a C<Map> with the nicks seen
for this log as keys, and an C<IterationBuffer> with entries that originated
by that nick.


=begin code :lang<raku>

say $log.nr-control-entries;

=end code


The C<nr-control-entries> instance method returns an integer representing
the number of control entries in this log.  It is calculated lazily


=begin code :lang<raku>

say $log.nr-conversation-entries;

=end code


The C<nr-conversation-entries> instance method returns an integer representing
the number of conversation entries in this log.


=begin code :lang<raku>

.say for $log.problems;

=end code


The C<problems> instance method returns an array with C<Pair>s of
lines that could not be interpreted in the log.  The key is a string
with the line number and a reason it could not be interpreted.  The
value is the actual line.


=begin code :lang<raku>

say "contains 'foo'" if $log.raw.contains('foo');

=end code


The C<raw> instance method returns the raw text version of the log.  It can
e.g. be used to do a quick check whether a string occurs in the raw text,
before checking C<entries> for a given string.


=begin code :lang<raku>

$log.update($filename.IO);  # add any entries added to file

$log.update($slurped);      # add any entries added to string

=end code


use v6.*;

use IRC::Log:ver<0.0.10>:auth<zef:lizmat>;

class IRC::Log::Textual:ver<0.0.6>:auth<zef:lizmat> does IRC::Log {

    multi method new(IRC::Log::Textual:U:
      IO:D $path,
      Date() $Date = self.IO2Date($path)
    ) {
        my str $basename = $path.basename;
        my str $date     = $Date.Str;

        my $before :=
          $path.sibling($Date.earlier(:1day) ~ $basename.substr(10));
        my $after :=
          $path.sibling($Date.later(:1day) ~ $basename.substr(10));

        my $slurped :=
          ($before.slurp   if $before.e)
          ~ ($path.slurp   if $path.e)
          ~ ($after.slurp  if $after.e);
        
        self.new($slurped, $Date)
    }

    method parse(IRC::Log::Textual:D:
      Str:D $slurped,
      Date:D $Date
    ) is implementation-detail {
        $!date = $Date;

        # assume spurious event without change that caused update
        return Empty if $!raw && $!raw eq $slurped;

        my $to-parse;
        my int $last-hour;
        my int $last-minute;
        my int $ordinal;
        my int $linenr;
        my int $pos;

        # done a parse before for this object
        if %!state -> %state {

            # adding new lines on log
            if $slurped.starts-with($!raw) {
                $last-hour   = %state<last-hour>;
                $last-minute = %state<last-minute>;
                $ordinal     = %state<ordinal>;
                $linenr      = %state<linenr>;
                $pos         = $!entries.elems;
                $to-parse   := $slurped.substr($!raw.chars);
            }

            # log appears to be altered, run it from scratch!
            else {
                $!entries.clear;
                %!nicks = @!problems = ();
                $!nr-control-entries = $!nr-conversation-entries = 0;
                $last-hour = $last-minute = $linenr = -1;
                $to-parse  = $slurped;
            }
        }

        # first parse
        else {
            $last-hour = $last-minute = $linenr = -1;
            $to-parse = $slurped;
        }

        # we need a "push" that does not containerize
        my int $initial-nr-entries = $!entries.elems;
        my int $accepted = $initial-nr-entries - 1;

        # accept an entry
        method !accept(\entry --> Nil) {
            with %!nicks{entry.nick} -> $entries-by-nick {
                $entries-by-nick.push($!entries.push(entry));
            }
            else {
                (%!nicks{entry.nick} := IterationBuffer.CREATE)
                  .push($!entries.push(entry));
            }
            ++$pos;
        }

        method !problem(Str:D $line, Str:D $reason --> Nil) {
            @!problems[@!problems.elems] := "Line $linenr: $reason" => $line;
        }

        for $to-parse.split("\n").grep({ ++$linenr; .chars }) -> $line {

            if $line.starts-with('[') && $line.substr-eq('] ',25)
              && $line.substr(1,24).DateTime -> $DateTime {
                my $utc := $DateTime.utc;
                next if $utc.Date ne $Date;

                # Textual session markers
                my $text := $line.substr(27);
                next
                  if $text eq ' '
                  || $text eq 'Disconnected'
                  || $text.starts-with('------------- ')
                  || $text.starts-with('Mode is ')
                  || $text.starts-with('Topic is ')
                  || $text.starts-with('Set by ');
                  || $text.starts-with("You're now known as ");

                my int $hour   = $utc.hour;
                my int $minute = $utc.minute;
                if $minute == $last-minute && $hour == $last-hour {
                    ++$ordinal;
                }
                else {
                    $last-hour   = $hour;
                    $last-minute = $minute;
                    $ordinal     = 0;
                }

                if $text.starts-with('<') {
                    with $text.index('> ') -> $index {
                        self!accept: IRC::Log::Message.new:
                          :log(self), :$hour, :$minute, :$ordinal, :$pos,
                          :nick($text.substr(1,$index - 1)),
                          :text($text.substr($index + 2));
                        ++$!nr-conversation-entries;
                    }
                    orwith $text.index('> ', :ignoremark) -> $index {
                        self!accept: IRC::Log::Message.new:
                          :log(self), :$hour, :$minute, :$ordinal, :$pos,
                          :nick($text.substr(1,$index - 1)),
                          :text($text.substr($index + 2));
                        ++$!nr-conversation-entries;
                    }
                    else {
                        self!problem($line,"could not find nick delimiter");
                    }
                }
                elsif $text.starts-with('• ') {
                    with $text.index(': ',2) -> $index {
                        self!accept: IRC::Log::Self-Reference.new:
                          :log(self), :$hour, :$minute, :$ordinal, :$pos,
                          :nick($text.substr(2,$index - 2)),
                          :text($text.substr($index + 2));
                        ++$!nr-conversation-entries;
                    }
                    else {
                        self!problem($line, "self-reference nick");
                    }
                }

                # assume some type control message
                else {
                    with $text.index(' (') -> $par-open {
                        my $nick := $text.substr(0,$par-open);
                        with $text.index(') ',$par-open) -> $par-close {
                            my $message := $text.substr($par-close + 2);
                            if $message.starts-with('joined ') {
                                self!accept: IRC::Log::Joined.new:
                                  :log(self), :$hour, :$minute, :$ordinal,
                                  :$pos, :$nick;
                                ++$!nr-control-entries;
                            }
                            elsif $message.starts-with('left ') {
                                self!accept: IRC::Log::Left.new:
                                  :log(self), :$hour, :$minute, :$ordinal,
                                  :$pos, :$nick;
                                ++$!nr-control-entries;
                            }
                            else {
                                self!problem($line, 'unclear control message');
                            }
                            next;
                        }
                    }

                    # not a verbose control message
                    with $text.index(' is now known as ') -> $index {
                        self!accept: IRC::Log::Nick-Change.new:
                          :log(self), :$hour, :$minute, :$ordinal, :$pos,
                          :nick($text.substr(0,$index)),
                          :new-nick($text.substr($index + 17));
                        ++$!nr-control-entries;
                    }
                    orwith $text.index(' sets mode ') -> $index {
                        my @nicks  = $text.substr($index + 11).words;
                        my $flags := @nicks.shift;
                        self!accept: IRC::Log::Mode.new:
                          :log(self), :$hour, :$minute, :$ordinal, :$pos,
                          :nick($text.substr(0,$index)),
                          :$flags, :@nicks;
                        ++$!nr-control-entries;
                    }
                    orwith $text.index(' changed the topic to ') -> $index {
                        my $topic := IRC::Log::Topic.new:
                          :log(self), :$hour, :$minute, :$ordinal, :$pos,
                          :nick($text.substr(0,$index)),
                          :text($text.substr($index + 22));
                        self!accept: $topic;
                        $!last-topic-change = $topic;
                        ++$!nr-conversation-entries;
                    }
                    orwith $text.index(' kicked ') -> $index {
                        with $text.index(
                          ' from the channel ', $index
                        ) -> $spec {
                            self!accept: IRC::Log::Kick.new:
                              :log(self), :$hour, :$minute, :$ordinal,
                              :$pos, :nick($text.substr(0,$index)),
                              :kickee($text.substr(
                                $index + 8, $spec - $index - 8
                              )),
                              :spec($text.substr($spec + 18));
                            ++$!nr-control-entries;
                        }
                        else {
                            self!problem($line, "unclear kick message");
                        }
                    }
                    else {
                        self!problem($line, "unclear control message");
                    }
                }
            }
            elsif $line.trim.chars {
                self!problem($line, "no timestamp found");
            }
        }

        # save current state in case of updates
        $!raw   = $slurped;
        %!state = :parsed($slurped.chars),
          :$last-hour, :$last-minute, :$ordinal, :$linenr;

        $!entries.Seq.skip($initial-nr-entries)
    }
}

#my $log = IRC::Log::Textual.new:
#  '/Users/liz/Documents/Textual/Libera (192C2)/Channels/#raku/2021-05-26.txt'.IO
#;
#.say for $log.entries;
#dd $_ for $log.problems;

#-------------------------------------------------------------------------------
# Documentation



IRC::Log::Textual - interface to IRC logs from Textual


=begin code :lang<raku>

use IRC::Log::Textual;

my $log = IRC::Log::Textual.new($filename.IO);

say "Logs from $log.date()";
.say for $log.entries.List;

my $log = IRC::Log::Textual.new($text, $date);

=end code


IRC::Log::Textual provides an interface to the IRC logs that are generated by
the Textual application on MacOS.  Please see L<IRC::Log> for more information.


Since Textual stores its daily file in the local time zone, specifying a
path with C<.new> will B<also> read the files in the same directory that are
one day before it and one day after it to make sure all entries of the date
in UTC are captured.


Source can be located at: https://github.com/lizmat/IRC-Log-Textual .
Comments and Pull Requests are welcome.


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


Textual

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

COPYRIGHT AND LICENSE

IRC::Log::Textual v0.0.6

Authors

License

Dependencies

Test Dependencies

Provides

Documentation