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 );