### ----------------------------------------------------
### -- Scalar::History
### -- Licenses: BSD-3
### -- Authors: Markus 'Holli' Holzer
### -- File: README.md
### ----------------------------------------------------
NAME
====

Scalar::History - A personal history for any scalar

DESCRIPTION
===========

This module implements the history variable pattern, that is variables which store not only their current value, but also the values they have contained in the past.

You can make a history variable by calling the `create` function and bind (not assign) it to a scalar. All assignments to the variable will be stored in a history and can be fetched at any point in your program.

SYNOPSIS
========

    use Scalar::History;

    # This adds a history to $abc
    my $abc := Scalar::History.create("a");

    # We can now assign new values
    $abc = "b";
    $abc = "d";

    # At any point we can ask for past values, here: ("a", "b")
    $abc.VAR.get-history.say;

    # Oh my, we forgot "c", we must rewind
    $abc.VAR.rewind-history( 1 );

    # So the current value is now "b" again
    $abc.say; 

    # rewinding only moves a pointer and you can
    # call `forward-history($steps)` to move into the
    # other (future) direction, no values get deleted.

    # But when we ask for the history we only get
    # historic values up to the current value, here ("a")
    $abc.VAR.get-history().say;

    # You can specify the :all adverb to get all historic
    # values, regardless. Here ("a", "b")
    say $abc.VAR.get-history( :all );

    # Notice there is no "d" in the history, it is here:
    say $abc.VAR.latest-value;

    # When assigning in a rewound state however, 
    # everything after the rewind point gets forgotten

    $abc = "c";
    $abc = "d";
    $abc = "e";

    $abc.say;                      # "e"
    $abc.VAR.get-history.say;      # ("a", "b", "c", "d")

    # You can enforce a type by passing it into `create`
    my Int $int := Scalar::History.create(1, Int);

    # The history variables behave just like normal ones
    $int++;

    # You can pass it to functions, but you need to use the `is raw`
    # in order to not lose the magic
    sub count-to-ten (Int $n is raw)
    {
        $n++;
        return-rw $n if $n == 10;
        return-rw count-to-ten( $n );
    }

    # Also, don't forget to bind the return value
    my $new := count-to-ten($int);

    $new.say;                      # 10
    $new.VAR.get-history.say;      # (1,2,3,4,5,6,7,8,9)

INSTALLATION
============

    $ zef install Scalar::History

HINT
====

If you want to make sure, you forward to the last known value, or rewind to the very first, you can call the respective methods using `Inf` as argument.

        $history.VAR.rewind-history( Inf );



