File Coverage

blib/lib/Standup/Diary.pm

Criterion	Covered	Total	%
statement	37	41	90.2
branch	2	8	25.0
condition			n/a
subroutine	12	14	85.7
pod	5	7	71.4
total	56	70	80.0

package Standup::Diary;

use v5.28;

use Config::Tiny;
use Object::Pad ':experimental';
use Path::Tiny;

use Standup::Role::Project;
use Standup::Role::Date;
use Standup::Diary::Template;

our $VERSION = '0.07_03';
$VERSION =~ tr/_//d;

class Standup::Diary :does( Date ) :does( Project ) {

  field $config :accessor :param { Config::Tiny->read('diary.conf') };

  field $daily_data_path :accessor;

  field $data_dir :param :reader;

  field $template :writer :accessor;

  method init_daily_data_path ($path) {
    $daily_data_path = $data_dir ?
      path( $data_dir . '/' . $path ) :
      path( $config->{data}->{path} . '/' . $path );
  }

  method write {

    $self->set_template( Standup::Diary::Template->new(
      date         => $self->date,
      project_name => $self->project_name
    ));

    if ( $self->should_create_dir ) {
      say "$daily_data_path should be created";
      $self->create_directories_tree;
    } else {
      $self->init_daily_data_path($self->build_path($self->date->ymd('/')));
    }

    my $file_path = path($self->build_full_file_path);

    path($file_path)->spew_utf8($template->render) and say "Diary entry created $file_path"
      unless $file_path->exists and say "Entry already exist";

  }

  # TODO should have a Standup::Diary::Path object for those
  method build_full_file_path {
    return $daily_data_path .
      '/' .
      $self->date->ymd .
      '_' .
      lc $self->project_name .
      '.md';
  }

  method build_path ($date) {
    my ($path) = $date =~ m/ \d{4} \/ \d{2} /gx ;
    return $path;
  }

  method should_create_dir {
    $self->init_daily_data_path($self->build_path($self->date->ymd('/')));
    return $daily_data_path->exists ? 0 : 1;
  }

  method create_directories_tree {

    # Unimplemented, see #29
    if ($self->date->day_of_month == 1 ) {
      # TODO if first day of the month
      # Create a Priorities file
    }

    my @created = $daily_data_path->mkpath;
    say "Created $daily_data_path" if @created;
  }
}

=encoding utf8

=head1 NAME

Standup::Diary - Manage a simple Markdown journal for your daily standups

=head1 SYNOPSIS

  # From command line
  diary --data-dir /home/smonff/diary/ --project-name SeriousWork

  # Programmatic usage
  my $diary = Standup::Diary->new( data_dir => $data_dir, project_name => $project_name );

  $diary->write();


=head1 DESCRIPTION

This module is the implementation of the L command, that can help to keep
a directory of organized daily notes aimed at standup preparation and
presentation.

It provides a couple of ways to customize the notes template.

It use internal tools built with CPAN modules:

=over 2

=item Standup::Diary::Template

The Markdown template where your data are interpolated.

=item Standup::Role::Date

Provide date features for all the C uses.

=item Standup::Role::Project

Provide a project name, so far.

=back

=head1 MOTIVATIONS

Daily standups are a common, tried and tested modern work methodology. They are
I<"brief, daily collaboration meeting in which the team review progress from the
previous day, declares intentions for the current day, and highlights any
obstacles encountered or anticipated"> (L
meeting in which the team review progress from the previous day, declares
intentions for the current day, and highlights any obstacles encountered or
anticipated.>).

This tool is supposed to provide self-support for persons:

=over 2

=item Who struggle with daily standups presentations oral expression

=item Surely familiar with the Perl ecosystem

=back

=head2 How did it start?

Social anxiety can make my standup presentation very confusing. I also tend to
forget key points if improvising, due to the stress of having no talk notes
support. Keeping a diary of my thoughts drastically helped me to stay calm and
collaborate better with the various teams I worked with. And if they are well
sorted by year, month and day, it makes very easy to find old notes for eventual
later usage.

=head2 Ready for production

I have been using it at work since 2021 and it helped me to reduce the stress of
standups and meeting.

=head2 Methodology

Every morning, create the daily file by running C. It's template is a
simple 3 items list. Open the day file in C<$data_dir/$year/$month/> and stash
your thoughts by using the following methodology:

=over 2

=item C

List of tasks you accomplished in the previous day

=item C

List of tasks you plan to accomplish today

=item C

List of eventual blockers, so that your colleagues can support you

=back

Then just read the notes during the daily standup.

=head2 Experiment with Object::Pad

L is my pet project for Perl's Corinna implementation of the
core OOP features. C use L, not the C feature
introduced in Perl C<5.40>. L is the test bed for the new core OO
system.

=head1 INSTALLATION

=head2 For common usage

    cpanm Standup::Diary

It will make the C command available in the C<~/perl5/bin/> directory.
Should be available in your C.

See L for command line usage.

=head2 For development

  # Install a Perl module manager
  apt install carton

  git clone [e-mail]:smonff/Diary.git

  cd Diary

  # Install CPAN dependencies
  carton install

=head1 How to use it?

I set an alias in my C<.bashrc>. Should also work in your own-favorite-shell:

  alias diary="diary --data-dir /home/smonff/diary --project-name SeriousWork";

Each morning, before my work standup, I run C. It create a Markdown file
in the specified C<--project-name> directory. I then edit my thoughts with an
editor.

See L for command line usage.

=head1 FIELDS

=head2 config

=head2 daily_data_path

=head2 data_dir

=head2 template

A L object.

=head1 METHODS

=head2 build_full_file_path()

=head2 build_path($self->date->ymd('/'))

Use the date from C to build the final path file name.

=head2 create_directories_tree()

If C<$self->should_create_dir()> returns a true value, it would take care of the
directory creation using L C.

=head2 init_daily_data_path($file_path)

Helper that initialize C<$daily_data_path> with a C instance
for the current day diary entry.

  # foo/2022/03 (Path::Tiny)
  $self->init_daily_data_path($self->build_path)

=head2 should_create_dir()

Check if a new I or I directory should be created so that we can
store the standup file. In simplier words: are we the first day of the year, or
of the month?

=head2 write()

This is C entry point, AKA C.

=head1 TODOs

=over 2

=item Make the template configurable by setting it in a separate file

=item Retrieve TODOS from previous days

=back

See the L.

=head1 SEE ALSO

A couple of similar tools:

=over 2

=item L

On the CPAN, this is pretty much all what I found. I like the spirit of this
one.

=item L

A similar effort written in Bash.

=back

=head1 ACKNOWLEDGEMENTS

Thanks to the maintainers of L, L, L,
L, L.

=head1 LICENSE

Copyright 2022-2024 Sebastien Feugère

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

See L.

=head1 AUTHOR

Sébastien Feugère - [e-mail]

=cut