This page is about (the features that should be produced within) an ongoing project of the [Google Summer Of Code] 2011.

----

The idea (abstractly): Suppose you've got some value ''X'', and you know you'll need to know f(''X'') quite often, where f is some function. Then a [stasher] can let you compute f(''X'') '''once''' and then "stash" the result within the [Tcl_Obj] that is ''X'', so that when subsequently you need to know f(''X''), computing it is "free".

The Tcl core uses this idea in a number of cases, usually when ''X'' is a piece of code written by a programmer and ''f'' is the operation of compiling that code: Tcl scripts can be bytecompiled, [expr]essions can be bytecompiled too, and [regexp]s compile to a finite automaton. But traditionally, you could only do that if you had implemented ''f'' in [C]. A [stasher] makes it possible to use any Tcl command as an ''f'' here, and additionally it lets you cache g(''X''), h(''X''), etc. for as many functions ''g'', ''h'', … as you bother to define.


**Interface**

(The details below are preliminary.)

Small glossary:
   stash:   Where cached values are stored. Technically this is going to reside within the internal representation of a [Tcl_Obj], so that when the original value is forgotten, everything that was cached for it goes away too.
   ''stasher'':   A command used to access a stash.
   '''stasher''':   The command used to create ''stasher''s.
   property:   A computed value that can be cached within a stash.

Stashers are created using the '''stasher''' command, which has the syntax
    :   '''stasher''' ''name'' ''setup-script''

A ''stasher'' has a number of subcommands, the most important of which are
    :   ''stasher'' '''get''' ''value'' ''property''
that returns the ''property'' of the give ''value'', e.g.
  strange get {some stupid() #computer<program>using*strange@programming<language>} bytecode
that would return the bytecode for `some stupid() #computer<program>using*strange@programming<language>` in the `strange` programming language.

When called, the '''get''' subcommand does one of two things:
   1. It passes the ''value'' on to the '''property''' ''property'' subsubcommand, and uses whatever it returns.
   2. It may return some result obtained previously when doing 1.
Doing 1 may be expensive, but doing 2 is essentially free (time-wise).


''(To be continued)''

***Example***

First, an example to illustrate the idea of "properties" of a value.
 stasher complexnumber {
    # Lots of code defining properties of complex numbers in various formats
 }
 complexnumber get 3+4i real                    ; # => 3
 complexnumber get 3+4i imag                    ; # => 4
 complexnumber get 3+4i abs                     ; # => 5
 complexnumber get 3+4i arg                     ; # => 0.9272952180016122
 complexnumber get 3+4i parsed                  ; # => rect 3 4
 complexnumber get 5cis0.92 parsed              ; # => polar 5 0.92
 complexnumber get 5cis0.9272952180016122 real  ; # => 3.0000000000000004
 complexnumber get 5cis0.9272952180016122 imag  ; # => 3.9999999999999996
 complexnumber get 3 real                       ; # => 3
 complexnumber get 3 imag                       ; # => 0
 complexnumber get 3 parsed                     ; # => rect 3 0


Next, an example to illustrate how stashing can make a difference for speed
 stasher book {
    # Lots of code defining properties of "book"s and how to compute or look them up
 }
 set pptt isbn:0-13-038560-3
 book get $pptt title
Some delay when '''book''' retrieves a library catalog entry for the book with ISBN 0-13-038560-3, and then returns: `Practical programming in Tcl/Tk`.
 book get $pptt authors
No delay before returning: `{Welch, Brent B.} {Hobbs, Jeffrey} {Jones, Ken}`, as the full catalog entry is stashed within the $pptt value.
 set pptt
Returns: `isbn:0-13-038560-3`. We're not automagically mutating values, we're doing things to the internal representation that supplements that value.
 book get isbn:0-13-038560-3 authors
Returns `{Welch, Brent B.} {Hobbs, Jeffrey} {Jones, Ken}` as above, but after a delay. Though the two strings are equal, they are not stored in the same [Tcl_Obj], so when '''book''' is handed one it cannot access the data stashed within the other.




<<categories>>Internals