view release on metacpan or  search on metacpan

lib/ACME/2026.pm  view on Meta::CPAN

package ACME::2026;

use 5.008003;
use strict;
use warnings;

use Carp qw(croak);
use Exporter 'import';
use File::Temp qw(tempfile);
use JSON::PP ();
use POSIX qw(strftime);

=head1 NAME

ACME::2026 - Checklists for glorious 2026 goals

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';

our @EXPORT_OK = qw(
  plan_new plan_load plan_save
  add_item update_item delete_item get_item
  add_note complete_item skip_item reopen_item
  items stats
);

our %EXPORT_TAGS = ( all => \@EXPORT_OK );

=head1 SYNOPSIS

  use ACME::2026 qw(:all);

  my $plan = plan_new(
    title => '2026',
    storage => '2026.json',
    autosave => 1,
  );

  my $id = add_item($plan, 'Run a marathon',
    list => 'Health',
    due => '2026-10-01',
    tags => [qw/fitness endurance/],
    priority => 2,
  );

  complete_item($plan, $id, note => 'Signed up for NYC');
  my @open = items($plan, status => 'todo', list => 'Health', sort => 'due');

  plan_save($plan);

=head1 DESCRIPTION

ACME::2026 is a tiny functional API for keeping 2026 checklists. It stores
plans as plain Perl hashrefs and can persist them to JSON.

=head1 DATA MODEL

Plan hashref:

  {
    title       => '2026',
    items       => [ ... ],
    next_id     => 1,
    created_at  => '2026-01-01T12:00:00Z',
    updated_at  => '2026-01-01T12:00:00Z',
    storage     => '2026.json',
    autosave    => 1,
  }

Item hashref:

  {
    id         => 1,
    title      => 'Run a marathon',
    status     => 'todo',
    list       => 'Health',
    tags       => ['fitness'],
    priority   => 2,
    due        => '2026-10-01',
    notes      => [ { note => 'Signed up', at => '2026-02-10T09:00:00Z' } ],
    created_at => '2026-01-01T12:00:00Z',
    updated_at => '2026-02-10T09:00:00Z',
  }

Status values are C<todo>, C<done>, or C<skipped>. Dates are ISO 8601 strings
(C<YYYY-MM-DD> or C<YYYY-MM-DDTHH:MM:SSZ>).

=head1 FUNCTIONS

=head2 plan_new

  my $plan = plan_new(%opts);

Creates a new plan hashref. Supported options:

  title    - plan title (default: 2026)
  storage  - JSON path used by plan_save and autosave
  autosave - boolean, save after mutating operations

=head2 plan_load

  my $plan = plan_load($path, %opts);

Loads a JSON file from C<$path>. The plan is normalized to ensure required
fields exist. You can override C<title> or C<autosave> with C<%opts>.

=head2 plan_save

  plan_save($plan);
  plan_save($plan, $path);

Writes the plan as JSON. Uses C<$plan-E<gt>{storage}> if no path is provided.

=head2 add_item

  my $id = add_item($plan, $title, %opts);