Image

head

code

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

use v6.d;

#---- role to mix into Associative class ---------------------------------------
my role LockedHash {
    has int $!lock_hash;
    has int $!lock_keys;

    #---- original Associative candidates --------------------------------------
    has $!EXISTS-KEY;
    has $!AT-KEY;
    has $!ASSIGN-KEY;
    has $!BIND-KEY;
    has $!DELETE-KEY;

    #---- shortcuts to exceptions ----------------------------------------------
    sub disallowed($key --> Nil) is hidden-from-backtrace {
       die "Attempt to access disallowed key '$key' in a restricted hash"
    }
    sub readonly($key --> Nil) is hidden-from-backtrace {
       die "Modification of a read-only value attempted"
    }
    sub missed(@missed --> Nil) is hidden-from-backtrace {
       die @missed == 1
         ?? "Hash has key '@missed[0]' which is not in the new key set"
         !! "Hash has keys '@missed.join(q/','/)' which are not in the new key set"
    }
    sub delete($key,$type --> Nil) is hidden-from-backtrace {
       die "Attempt to delete $type key '$key' from a restricted hash"
    }

    #---- initialization -------------------------------------------------------
    my constant HIDDEN = Mu.new
      but role { method defined { False } };     # sentinel for hidden keys

    method initialize(
      $!EXISTS-KEY,$!AT-KEY,$!ASSIGN-KEY,$!BIND-KEY,$!DELETE-KEY
    ) {
        self
    }

    #---- helper methods -------------------------------------------------------
    method !delete_key(\key) {
        my $value = $!AT-KEY(self,key);
        $!ASSIGN-KEY(self,key,HIDDEN);
        $value
    }

    #---- standard Associative interface ---------------------------------------
    method EXISTS-KEY(\key) {
        use nqp;  # we need nqp::decont here for some reason
        $!EXISTS-KEY(self,key) && !(nqp::decont($!AT-KEY(self,key)) =:= HIDDEN)
    }
    method AT-KEY(\key) is raw {
        $!EXISTS-KEY(self,key)
          ?? $!lock_hash                   # key exists
            ?? $!AT-KEY(self,key)<>          # and locked hash, so decont
            !! $!AT-KEY(self,key)            # and NO locked hash, so pass on
          !! $!lock_hash || $!lock_keys    # key does NOT exist
            ?? disallowed(key)               # and locked hash/keys, forget it
            !! $!AT-KEY(self,key)            # and NO lock, so pass on
    }

    method ASSIGN-KEY(\key, \value) is raw {
        $!EXISTS-KEY(self,key)
          ?? $!lock_hash                   # key exists
            ?? readonly(key)                 # and locked hash, so forget it
            !! $!ASSIGN-KEY(self,key,value)  # and NO locked hash, so pass on
          !! $!lock_hash || $!lock_keys    # key does NOT exist
            ?? disallowed(key)               # and locked hash/keys, forget it
            !! $!ASSIGN-KEY(self,key,value)  # and NO lock, so pass on
    }

    method BIND-KEY(\key, \value) is raw {
        $!EXISTS-KEY(self,key)
          ?? $!lock_hash                   # key exists
            ?? readonly(key)                 # and locked hash, so forget it
            !! $!BIND-KEY(self,key,value)    # and NO locked hash, so pass on
          !! $!lock_hash || $!lock_keys    # key does NOT exist
            ?? disallowed(key)               # and locked hash/keys, forget it
            !! $!BIND-KEY(self,key,value)    # and NO lock, so pass on
    }

    method DELETE-KEY(\key) is raw {
        $!EXISTS-KEY(self,key)
          ?? $!lock_hash                   # key exists
            ?? delete(key,'readonly')        # and locked hash, forget it
            !! $!lock_keys                   # and NO locked hash
              ?? self!delete_key(key)          # but locked keys, so fake it
              !! $!DELETE-KEY(self,key)        # no locked keys, so do it
          !! $!lock_hash || $!lock_keys    # key does NOT exist
            ?? delete(key,'disallowed')      # and locked hash/keys, forget it
            !! Nil                           # not locked, so just show absence
    }

    #---- behaviour modifiers --------------------------------------------------
    method lock_hash()   { $!lock_hash = 1; self }
    method unlock_hash() { $!lock_hash = 0; self }

    method lock_keys(@keys,:$plus)   {
        if @keys {
            $!ASSIGN-KEY(self,$_,HIDDEN) unless $!EXISTS-KEY(self,$_) for @keys;

            unless $plus {
                missed( (self (-) @keys).keys ) if self.elems > @keys;
            }
        }

        $!lock_keys = 1;
        self
    }
    method unlock_keys() { $!lock_keys = 0; self }

    method lock_value(\key) {
        $!BIND-KEY(self,key,$!AT-KEY(self,key)<>);
        self
    }
    method unlock_value(\key) {
        my \value := $!AT-KEY(self,key);
        $!DELETE-KEY(self,key);
        $!ASSIGN-KEY(self,key,value);
        self
    }

    #---- introspection --------------------------------------------------------
    method hash_locked()   {  so $!lock_hash || $!lock_keys }
    method hash_unlocked() { not $!lock_hash || $!lock_keys }

    method legal_keys() {
        self.keys.List
    }
    method hidden_keys() {
        use nqp;  # we need nqp::decont here for some reason
        self.pairs.map({ .key if nqp::decont(.value) =:= HIDDEN }).List
    }
    method all_keys(\existing,\hidden) {
        use nqp;  # we need nqp::decont here for some reason
        nqp::decont(.value) =:= HIDDEN
          ?? hidden.push(.key)
          !! existing.push(.key)
          for self.pairs;
        self
    }
}

#---- actual module with exportable subs ---------------------------------------
module Hash::Util:ver<0.0.5>:auth<zef:lizmat> {

    #---- helper subs ----------------------------------------------------------
    my List %candidates;
    my $lock = Lock.new;

    sub candidates(\the-hash) {
        $lock.protect: {
            %candidates{the-hash.^name} //= (
              the-hash.can('EXISTS-KEY').head,
              the-hash.can(    'AT-KEY').head,
              the-hash.can('ASSIGN-KEY').head,
              the-hash.can(  'BIND-KEY').head,
              the-hash.can('DELETE-KEY').head,
            )
        }
    }

    #---- lock_hash / unlock_hash ----------------------------------------------
    our proto sub lock_hash(|) is export(:all) {*}
    multi sub lock_hash(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).lock_hash
    }
    multi sub lock_hash(LockedHash:D \the-hash) is default {
        the-hash.lock_hash
    }
    our constant &lock_hashref is export(:all) = &lock_hash;

    our proto sub unlock_hash(|) is export(:all) {*}
    multi sub unlock_hash(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).unlock_hash
    }
    multi sub unlock_hash(LockedHash:D \the-hash) is default {
        the-hash.unlock_hash
    }
    our constant &unlock_hashref is export(:all) = &unlock_hash;

    #---- lock_hash_recurse / unlock_hash_recurse ------------------------------
    our proto sub lock_hash_recurse(|) is export(:all) {*}
    multi sub lock_hash_recurse(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        lock_hash_recurse((the-hash does LockedHash).initialize(|@candidates))
    }
    multi sub lock_hash_recurse(LockedHash:D \the-hash) is default {
        lock_hash_recurse($_) if $_ ~~ Associative for the-hash.values;
        the-hash.lock_hash
    }
    our constant &lock_hashref_recurse is export(:all) = &lock_hash_recurse;

    our proto sub unlock_hash_recurse(|) is export(:all) {*}
    multi sub unlock_hash_recurse(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        unlock_hash_recurse((the-hash does LockedHash).initialize(|@candidates))
    }
    multi sub unlock_hash_recurse(LockedHash:D \the-hash) is default {
        unlock_hash_recurse($_) if $_ ~~ LockedHash for the-hash.values;
        the-hash.unlock_hash
    }
    our constant &unlock_hashref_recurse is export(:all) = &unlock_hash_recurse;

    #---- lock_keys / lock_keys_plus / unlock_keys -----------------------------
    our proto sub lock_keys(|) is export(:all) {*}
    multi sub lock_keys(Associative:D \the-hash, *@keys) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).lock_keys(@keys)
    }
    multi sub lock_keys(LockedHash:D \the-hash, *@keys) is default {
        the-hash.lock_keys(@keys)
    }
    our constant &lock_ref_keys is export(:all) = &lock_keys;

    our proto sub lock_keys_plus(|) is export(:all) {*}
    multi sub lock_keys_plus(Associative:D \the-hash, *@keys) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash)
          .initialize(|@candidates).lock_keys(@keys,:plus)
    }
    multi sub lock_keys_plus(LockedHash:D \the-hash, *@keys) is default {
        the-hash.lock_keys(@keys,:plus)
    }
    our constant &lock_ref_keys_plus is export(:all) = &lock_keys_plus;

    our proto sub unlock_keys(|) is export(:all) {*}
    multi sub unlock_keys(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).unlock_keys
    }
    multi sub unlock_keys(LockedHash:D \the-hash) is default {
        the-hash.unlock_keys
    }
    our constant &unlock_ref_keys is export(:all) = &unlock_keys;

    #---- lock_value / unlock_value --------------------------------------------
    our proto sub lock_value(|) is export(:all) {*}
    multi sub lock_value(Associative:D \the-hash, \key) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).lock_value(key)
    }
    multi sub lock_value(LockedHash:D \the-hash, \key) is default {
        the-hash.lock_value(key)
    }
    our constant &lock_ref_value is export(:all) = &lock_value;

    our proto sub unlock_value(|) is export(:all) {*}
    multi sub unlock_value(Associative:D \the-hash, \key) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates),unlock_value(key)
    }
    multi sub unlock_value(LockedHash:D \the-hash, \key) is default {
        the-hash.unlock_value(key)
    }
    our constant &unlock_ref_value is export(:all) = &unlock_value;

    #---- hash_locked / hash_unlocked ------------------------------------------
    our proto sub hash_locked(|) is export(:all) {*}
    multi sub hash_locked(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).hash_locked
    }
    multi sub hash_locked(LockedHash:D \the-hash) is default {
        the-hash.hash_locked
    }
    our constant &hashref_locked is export(:all) = &hash_locked;

    our proto sub hash_unlocked(|) is export(:all) {*}
    multi sub hash_unlocked(Associative:D \the-hash) {
        my @candidates := candidates(the-hash);
        (the-hash does LockedHash).initialize(|@candidates).hash_unlocked
    }
    multi sub hash_unlocked(LockedHash:D \the-hash) is default {
        the-hash.hash_unlocked
    }
    our constant &hashref_unlocked is export(:all) = &hash_unlocked;

    #---- introspection --------------------------------------------------------
    our proto sub legal_keys(|) is export(:all) {*}
    multi sub legal_keys(Associative:D \the-hash) {
        the-hash.keys.List
    }
    multi sub legal_keys(LockedHash:D \the-hash) is default {
        the-hash.legal_keys
    }
    our constant &legal_ref_keys is export(:all) = &legal_keys;

    our proto sub hidden_keys(|) is export(:all) {*}
    multi sub hidden_keys(Associative:D \the-hash) {
        ()
    }
    multi sub hidden_keys(LockedHash:D \the-hash) is default {
        the-hash.hidden_keys
    }
    our constant &hidden_ref_keys is export(:all) = &hidden_keys;

    our proto sub all_keys(|) is export(:all) {*}
    multi sub all_keys(Associative:D \the-hash,\existing,\hidden) {
        existing = the-hash.keys;
        hidden = ();
        the-hash
    }
    multi sub all_keys(LockedHash:D \the-hash,\existing,\hidden) is default {
        the-hash.all_keys(existing,hidden)
    }
    our constant &all_ref_keys is export(:all) = &all_keys;
}

sub EXPORT(*@args, *%_) {

    if @args {
        my $imports := Map.new( |(EXPORT::all::{ @args.map: '&' ~ * }:p) );
        if $imports != @args {
            die "Hash::Util doesn't know how to export: "
              ~ @args.grep( { !$imports{$_} } ).join(', ')
        }
        $imports
    }
    else {
        Map.new
    }
}



Raku port of Perl's Hash::Util module 0.23


use Hash::Util <
  lock_hash unlock_hash lock_hash_recurse unlock_hash_recurse
  lock_keys lock_keys_plus unlock_keys
  lock_value unlock_value
  hash_locked hash_unlocked
  hidden_keys legal_keys all_keys
>;


# Ways to restrict a hash
lock_keys(%hash);
lock_keys(%hash, @keyset);
lock_keys_plus(%hash, @additional_keys);


# Ways to inspect the properties of a restricted hash
my @legal = legal_keys(%hash);
my @hidden = hidden_keys(%hash);
all_keys(%hash,@keys,@hidden);
my $is_locked = hash_locked(%hash);


# Remove restrictions on the hash
unlock_keys(%hash);


# Lock individual values in a hash
lock_value(  %hash, 'foo');
unlock_value(%hash, 'foo');


# Ways to change the restrictions on both keys and values
lock_hash  (%hash);
unlock_hash(%hash);


This module tries to mimic the behaviour of Perl's C<Hash::Util> module
as closely as possible in the Raku Programming Language.


Hash::Util contains a set of functions that support restricted hashes.
It introduces the ability to restrict a hash to a certain set of keys.
No keys outside of this set can be added. It also introduces the ability
to lock an individual key so it cannot be deleted and the ability to ensure
that an individual value cannot be changed.


By default Hash::Util does not export anything.


If you want to use this module for the sole purpose of only once locking
a hash into an immutable state (calling only C<lock_hash> once on a hash),
then it is much better to turn your hash into a C<Map> upon initialization
by adding the C<is Map> trait:


This will have exactly the same effect as:


my %hash = foo => 42, bar => 23;
lock_hash(%hash);


but won't need to load the C<Hash::Util> module and will be much better
performant because it won't need any additional run-time checks, because
C<Map> is the immutable version of C<Hash> in Raku.


Functions that pertain to the unique implementation of Perl hashes, have
B<not> been ported.  These include:


hash_seed hash_value hv_store bucket_stats
bucket_info bucket_array hash_traversal_mask


Also field hashes (the tools to create inside-out objects) have not been
ported is these were deemed rather useless in the Raku environment where
everything is a true object.  This pertains to the functions:


Since the concept of references does not exist as such in Raku, it didn't
make sense to separately port the "_ref" versions of the subroutines.  They
are however available as aliases to the non "_ref" versions::


lock_hashref unlock_hashref lock_hashref_recurse unlock_hashref_recurse
lock_ref_keys lock_ref_keys_plus unlock_ref_keys
lock_ref_value unlock_ref_value
hashref_locked hashref_unlocked


lock_keys(%hash);
lock_keys(%hash, @keys);


Restricts the given %hash's set of keys to @keys.  If @keys is not
given it restricts it to its current keyset.  No more keys can be
added. C<:delete> and C<:exists> will still work, but will not alter
the set of allowed keys.  Returns the hash it worked on.


Removes the restriction on the %hash's keyset.


B<Note> that if any of the values of the hash have been locked they will not
be unlocked after this sub executes.  Returns the hash it worked on.


Similar to C<lock_keys>, with the difference being that the optional key list
specifies keys that may or may not be already in the hash. Essentially this is
an easier way to say


lock_keys(%hash,@additional_keys,%hash.keys);


Locks the value for an individual key of a hash.  The value of a locked key
cannot be changed.  Unless %hash has already been locked the key/value could
be deleted regardless of this setting.  Returns the hash on which it operated.


Unlocks the value for an individual key of a hash.  Returns the hash on
which it operated.


Locks an entire hash, making all keys and values read-only.  No value can be
changed, no keys can be added or deleted.  Returns the hash it operated on.
If you only want to lock a hash only once after it has been initialized, it's
better to make it a C<Map>:


This will have the same effect as C<lock_hash>, but will be much more
performant as no extra overhead is needed for checking access at runtime.


Util

#!/usr/bin/env raku

use Hash::Agnostic;

role Hash::Timeout:ver<0.0.2>:auth<zef:FRITH>[$timeout = 3600] does Hash::Agnostic
{
  has %!hash;
  has %!cancel;

  method AT-KEY($key) is raw {
    Proxy.new(
      FETCH => { %!hash{$key} },
      STORE => -> $, \v is raw { %!hash{$key} = v }
    );
  }
  method EXISTS-KEY($key) {
    %!hash.{$key}.DEFINITE
  }
  method ASSIGN-KEY(\key, \value) {
    .cancel with %!cancel{key};
    %!cancel{key} := $*SCHEDULER.cue({ %!hash{key}:delete }, :in($timeout));
    %!hash{key} = value;
  }
  method BIND-KEY(\key, \value) {
    .cancel with %!cancel{key};
    %!cancel{key} := $*SCHEDULER.cue({ %!hash{key}:delete }, :in($timeout));
    %!hash{key} := value;
  }
  method DELETE-KEY(\key) {
    .cancel with %!cancel{key};
    %!hash{key}:delete
  }
  method CLEAR() {
    for %!cancel.keys -> \k {
      .cancel with %!cancel{k}
    }
    %!hash = Hash.new;
    %!cancel = Hash.new;
  }
  multi method STORE(::?ROLE:D: \values, :$initialize) {
    self.CLEAR;
    given values.WHAT {
      when List { self!STOREL(values) }
      when Hash { self!STOREH(values) }
    }
    self;
  }
  method !STOREH(%hash --> Int:D) {
    for %hash.kv -> \k, \v {
      self.ASSIGN-KEY(k, v);
    }
  }
  method !STOREL(@values --> Int:D) {
    my $last := Mu;
    my int $found;

    for @values {
      if $_ ~~ Pair {
        self.ASSIGN-KEY(.key, .value);
        ++$found;
      } elsif $_ ~~ Failure {
        .throw
      } elsif !$last =:= Mu {
        self.ASSIGN-KEY($last, $_);
        ++$found;
        $last := Mu;
      } elsif $_ ~~ Map {
        $found += self!STOREL([.pairs])
      } else {
        $last := $_;
      }
    }
    $last =:= Mu
      ?? $found
      !! X::Hash::Store::OddNumber.new(:$found, :$last).throw
  }
  method keys { %!hash.keys }
  method iterator() { %!hash.pairs.iterator }
  method timeout { $timeout }
  method debug { %!hash.elems, %!cancel.elems }
}



Hash::Timeout - Role for hashes whose elements timeout and disappear


my %cookies does Hash::Timeout[0.5];
%cookies<user001> = 'id';
sleep 1;
say %cookies.elems; # prints 0


Hash::Timeout provides a C<role> that can be mixed with a C<Hash>.


There's just one optional parameter, the timeout, which accepts fractional seconds and defaults to 1 hour.


Fernando Santagata <nando.santagata@gmail.com>


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


Timeout

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

COPYRIGHT AND LICENSE

Hash::Timeout v0.0.2

Authors

License

Dependencies

Test Dependencies

Provides

Documentation