txt: ## dist_cpan-HOLLI-Scalar-History.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 );
  
  ```
  