DNA.
wyrm-assoc
Version.
2.1.9
Namespace.
::wyrm
Command.
::wyrm::assoc
Language.
c
Manpage.
assoc (1WY)
Manpage.
wyrm_assocNew (3WY)
Manpage.
wyrm_assocEmpty (3WY)
Manpage.
wyrm_assocFirst (3WY)
Manpage.
wyrm_assocGet (3WY)
Manpage.
wyrm_assocFilter (3WY)
Manpage.
WyrmAssocMapType (4WY)
Testbase.
Test Script
Test Report
Import.
Interface.
wyrm-assoc-btree
wyrm-assoc-hash
wyrm-assoc-splay
Object.
wyrm-assoc-btree
wyrm-assoc-hash
wyrm-assoc-splay
wyrm-oav
Package.
wyrmwif
Export.
Implementation.
wyrm-assoc.c
Interface.
wyrm-assoc.h
Object.
wyrm-assoc.o
Package.
wyrmassoc.dylib
System.
wyrm-assoc.sys

Associative Maps

Sections.
WyrmAssocMapType
Assign Mapping Type
Pass Through Interface
Auxillary I/O Routines
Wyrmassoc Tcl Package
Man Pages
Safe Interpretters
Test Base
Make.
Object.
set declares ""
set calls ""
foreach header [import interface] {
  set header [file tail [file root $header]]
  if {![string match wyrm-assoc-* $header]} continue
  set init wyrm_assoc[string totitle [string map {wyrm-assoc- ""} $header]]Init
  append declares "int ${init}(Intr intr); "
  append calls "if (${init}(intr)!=TCL_OK) return TCL_ERROR; "
}
compile "'-DASSOCDECLARES=$declares'" "'-DASSOCCALLS=$calls'" -c -o [
  export object
] [
  export implementation
] -- -list [
  import interface
] [
  export interface
] $include/unix/$base.sys
Package.
compile -ld -o [export package] -list [import object] [export object]
Script.
rule clean :: {} "
  -rm [export object] [import object]
  -rm $test/wyrm-assoc.TESTING
  -rm $test/wyrm-assoc-btree.TESTING
  -rm $test/wyrm-assoc-hash.TESTING
  -rm $test/wyrm-assoc-splay.TESTING
  -rm $test/wyrm-oav.TESTING
"
    

WyrmAssocMapType

 
    
top 

1 :: Generic interface to associative maps.

Copyright (C) 2002, 2004 SM Ryan

Wyrmwif Tcl extensions. For non-profit uses only, provided this copyright is preserved on all copies, this work may be freely copied, modified, redistributed, compiled, and incorporated in other works. This work is distributed with no warranty of any kind; no author or distributor accepts any responsibility for the consequences of using it, or for whether it serves any particular purpose or works at all, unless he or she says so in writing.

^
 
section    top 

2. Description :: Associations map an arbitrary key string into a data string. The map may be internal, stored entirely in main memory, or external, in a file read and written as needed. An internal map is represented by a list of an even number of elements, key value pairs, such as produced by [array get arrayname] (with optional intermingled flags). Such a list can be passed to associative map routines, and it will be converted internally to a map. An external map representation is a list of exactly one element which is the path to the file. A string representation which cannot be a list, or has an odd number of elements greater than one is an invalid representation.

Unlike lists, associative map objects in the C api can be shared; modifications to a map in one variable can change the value of another variable without notice. The Tcl assoc and vassoc commands duplicate a shared mapping before modifying it, so that the Tcl api does not permit sharing.

^
Referenced at: 57, 58, 59, 60, 61, 62, 63.
 
 
section    top 

3. Associative map type :: The string representation of an associative map is a one element or even numberred element list. The internal representation is specific to the map implementation. The object type is a pointer to the WyrmAssocMapType structure for the implementation which includes the Tcl object type as a prefix. The type name always begins with "wyrm.assoc. ...".

wyrm-assoc does not implement a mapping itself. Rather it provides a common interface to the variety of implementations.

Properties of associative mappings:

Internal or external.
An internal mapping exist only memory and one process; an external mapping is in file and can be shared by other processes.
String representation.
An internal mapping string representation of an even number of elements; an external mapping string representation is a one element list which is the file path.
Entries.
A mapping has zero or more entries. An entry is a unique key string, a data string, and flags packed into an integer. The string representation of an internal mapping is a list of key-value pairs. If an element has nonzero flags, that is included in the string representation with the pseudo key '[]'.
Sorting and Traversal.
A mapping can be unsorted, sorted, or sorted and reverse sorted. A nonempty sorted mapping has a first and last key. Given any key except the last key, a sorted mapping can return the next key; a reverse sorted mapping can also give the previous key of any key except the first. An sorted mapping can find approximate keys: the greatest key, if any, less than or equal a given key, otherwise the first key. Unsorted mappings do not have to define first, last, next, and previous keys, but if they do, first-next-last must traverse all keys in an implementation defined order; if previous is defined, last-previous-first must also traverse all keys.
Enumeration.
Sorted and unsorted mappings must provide an enumerator of all the elements. (Sorting mappings may use a generic first-next-last enumeration.) During an enumeration only the enumerate and enumerateEnd methods will be called; the mapping is allowed to place itself in a special enumeration state that is incompatiable with normal operations.
Modifiable.
Internal mappings are modifiable. External mappings can be modifiable or read only, depending on the implementation and how the mapping is created.
type struct WyrmAssocMapType—Associative map type
type struct tcl—Tcl object type
chars name—Type name, must begin with "wyrm.assoc."...
proc void freeIntRepProc—Release all storage, close files, etc.
io Obj objPtr—The mapping being freed.
Memory. All internal allocation not accessible any other way are freed.
proc void dupIntRepProc—Duplicate internal storage from srcPtr to dupPtr.
input Obj srcPtr—Original mapping.
output Obj dupPtr—Duplicate mapping.
proc void updateStringProc—Update the string representation.
io Obj mapping—The mapping being displayed.
Memory. String representation is heap allocated.
proc int setFromAnyProc—Construct the internal representation from the string.
output Intr intr—Error message return; may be NULL.
io Obj objPtr—The mapping being synthesised.
proc Obj update—Update string from wyrm_assocUpdate. NULL if updateStringProc is not wyrm_assocUpdate.
input Obj obj—The mapping being displayed.
output Tcl_DString* S—Receives string representation.
proc Obj internal—Update internal representation from wyrm_assocInternal. NULL if setFromAnyProc does not call wyrm_assocInternal.
output Intr intr—Error message return; may be NULL.
io Obj mapping—The mapping being updated.
io ptr cookie—Passed through to wyrm_assocInternalEntry.
proc Obj dump—Format the mapping in some implementation fashion.
Memory. Caller decrements reference count when done.
output Intr intr—Error message return; may be NULL.
input Obj base—The mapping being dumped.
input int N—Number of additional arguments. May be zero.
input Obj* P—Additional arguments. May be null if N is zero.
long magic—Type positive magic number if an external mapping, used to identify files. Must be zero for an internal mapping.
proc Obj new—Construct the internal representation from the base and return it; return NULL on error.
Memory. Caller decrements reference count when done.
output Intr intr—Error message return; may be NULL.
io Obj base—The base object mapping being synthesised.
input int N—Number of additional arguments. May be zero.
input Obj* P—Additional arguments. May be null if N is zero.
proc int empty—If the mapping is currently empty; TCL_OK if true, TCL_BREAK if not, or TCL_ERROR.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
proc int first—Return the key of the first element, or NULL if error.
Memory. Caller decrements.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
proc int last—Return the key of the last element, or NULL if error.
Memory. Caller decrements.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
proc int next—Return the key of the next element after the given one, or NULL if error.
Memory. Caller decrements.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
input Obj key—Key to search for.
proc int previous—Return the key of the previous element before the given one, or NULL if error.
Memory. Caller decrements.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
input Obj key—Key to search for.
proc int enumerateBegin—Begin an enumeration of the mapping; returns an enumeration cooke or NULL if error.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
input Obj firstHint—Suggested first key if nonnull. The enumerator expects no key less than this.
output bool* sorted—Keys are enumerated strictly increasing.
proc int enumerate—Get the next element of the mapping; return TCL_OK. TCL_ERROR, or TCL_BREAK at end.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
io ptr cookie—Enumeration magic cookie.
output Obj* key—Enumerated key if TCL_OK.
Memory. Caller decrements refcount.
output Obj* data—Enumerated data if TCL_OK.
Memory. Caller decrements refcount.
output int* flags—Enumerated flags if TCL_OK.
proc int enumerateEnd—End an enumeration of the mapping; returns TCL_ERROR or TCL_OK.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
input ptr cookie—Enumeration magic cookie.
proc int get—Get information from the keyed element; TCL_OK or TCL_ERROR.
output Intr intr—Error message return; may be NULL.
input Obj mapping—The mapping being queried.
input Obj seek—The key of the element to get. If the mapping is sorted, this may be an approximate key.
output Obj *key—The key of the position if not NULL.
Memory. Decrement reference count to release.
output Obj *data—The data of the position or NULL.
Memory. Decrement reference count to release.
output int *flags—The flags of the position or -1.
proc int put—Put information into the mapping; TCL_OK or TCL_ERROR.
output Intr intr—Error message return; may be NULL.
io Obj mapping—The mapping being modified.
input Obj key—Store in this key's position, adding the key if necessary. If null, store in the current position; NULL if error.
Memory. Reference count incremented if the mapping retains this object.
input Obj data—If nonnull, store this data.
Memory. Reference count incremented if the mapping retains this object.
input int flags—If nonnegative, store these flags.
proc int delete—Delete the key and data; TCL_OK or TCL_ERROR.
output Intr intr—Error message return; may be NULL.
io Obj mapping—The mapping being modified.
input Obj key—Key to search for.
typedef int (*WyrmAssocEnumerator)(ptr context,Obj key,Obj data,int flags,bool sorted);
typedef struct {
	<Tcl object type prefix>
	<Mapping identification protocol>
	<Mapping status>
	<Traversing the map protocol>
	<Enumeration protocol>
	<Input/output protocol>
} WyrmAssocMapType;
<Flags>
^
Referenced at: 14, 63.
 
 
section    top 
type enum WyrmAssocFlags
wyrm_assocFlagCompressKey—Request key compression.
Enumeration. 0x01
wyrm_assocFlagCompressData—Request data compression.
Enumeration. 0x02
wyrm_oavFlagDelegate—OAV delegation.
Enumeration. 0x04
wyrm_oavFlagSubst—Do OAV %-substitutions.
Enumeration. 0x08
wyrm_oavFlagActive—Data is active string.
Enumeration. 0x10
wyrm_oavResumption—Data is an OAV resumption.
Enumeration. 0x20
enum WyrmAssocFlags {
	wyrm_assocFlagCompressKey = 0x01,
	wyrm_assocFlagCompressData = 0x02,
	wyrm_oavFlagDelegate = 0x04,
	wyrm_oavFlagSubst = 0x08,
	wyrm_oavFlagActive = 0x010,
	wyrm_oavResumption = 0x20,
};
^
Referenced at: 3, 58, 61.
 
 
section    top 
Tcl_ObjType tcl;
void (*update)(Obj obj,Tcl_DString *S);
int (*internal)(Intr intr,Obj obj,ptr cookie,ptr*);
Obj (*dump)(Intr intr,Obj mapping,int N,Obj *P);
^
Referenced at: 3.
 
 
section    top 

6. Mapping identification protocol :: wyrm-assoc requires a mapping to have associative map type, coerced from the string representation if necessary. Internal mappings are coerced to splay trees by default. New external mappings (the file does not exist), are created as (a,b)-trees. if the file in the external mapping already exists, the first sizeof(long) bytes are the magic number for the file; each external mapping implementation has its own unique magic number.

A mapping can also be openned explicitly for string representation for a specific mapping implementation. In this case additional parameters can be specified, such open modes or node sizes. The implementation is responsible for parsing additional arguments after the base value.

The names of type can omit the initial "wyrm.assoc."; it is prefixed to given names if omitted.

The magic number for internal mappings must be zero, and positive for external mappings. (Four ASCII characters will be a positive number.) Negative values are used internally.

protocol mapping identification
protocol internal mapping identification—when an even numbered length list is used as a mapping
proc wyrm_assoc...
mapping—Key/data pairs list
proc (wyrm.assoc.splay).setFromAnyProc—Find the type
protocol external mapping identification—when a one element list is used as a mapping
proc wyrm_assoc...
mapping—Path in list
proc (wyrm.assoc.btree).setFromAnyProc—Find the type
protocol external mapping identification—when a one element list is used as a mapping
proc wyrm_assoc...
mapping—Path in list
proc (wyrm.assoc.btree).setFromAnyProc
protocol open mapping—explicitly open a mapping
proc wyrm_assocNew
name—Type name.
base—The object to convert to a mapping.
proc type.open
objPtr—base object
long magic;
Obj (*new)(Intr intr,Obj base,int N,Obj *P);
^
Referenced at: 3, 58.
 
 
section    top 

7 :: Mappings are not explicitly closed, but are released when the last reference is cleared. What exactly is released is specific to the implementation.

protocol release mapping
proc Tcl_DecrRefCount
proc obj->typePtr->freeIntRepProc
^
 
section    top 

8 :: As part of the Tcl type, the implementation must include a method to rebuild the string implementation. Internal mappings can define the method update and use the routine wyrm_assocUpdate in the Tcl type. wyrm_assocUpdate handles the mechanics of the string representation. The update method can then use wyrm_assocUpdateEntry to format a key, data, and flags into the string representation.

protocol update mapping with wyrm_assocUpdateEntry
proc Tcl_GetStringFromObj
proc obj->typePtr->updateStringProc is wyrm_assocUpdate
proc obj->wyrm assoc typePtr->update
proc wyrm_assocUpdateEntry
^
 
section    top 

9 :: As part of the Tcl type, the implementation must include a method to build the internal implementation from the string. Internal mappings can define the method internal and use the routine wyrm_assocInternal called from its setFromAnyProc. wyrm_assocInternal handles the mechanics of the internal representations. The internal method then uses wyrm_assocInternalEntry to get the key, data, and flags of each entry.

protocol update mapping with wyrm_assocInternalEntry
proc obj->typePtr->setFromAnyProc calls wyrm_assocInternal
proc obj->wyrm assoc typePtr->internal
proc wyrm_assocInternalEntry
^
 
section    top 
int (*empty)(Intr intr,Obj mapping);
^
Referenced at: 3, 59.
 
 
section    top 
protocol traverse mapping
protocol random positionning—All mappings.
proc get
protocol approximate random positionning—The mapping is sorted.
proc get
proc next
proc previous
protocol forward scan
proc first
proc next
protocol reverse scan—The mapping is reverse sorted.
proc last
proc previous
Obj (*first)(Intr intr,Obj mapping);
Obj (*last)(Intr intr,Obj mapping);
Obj (*next)(Intr intr,Obj mapping,Obj key);
Obj (*previous)(Intr intr,Obj mapping,Obj key);
^
Referenced at: 3, 60.
 
 
section    top 
protocol enumerate mapping
protocol enumerate to end—All mappings.
proc enumerateBegin—Nonnull cookie: begin enumeration; all other protocols may be disabled.
proc enumerate—Returns TCL_OK.
cookie
key—Nonnull.
data—Nonnull.
flags—Nonnull.
proc enumerate—Continued....
proc enumerate—Returns TCL_BREAK.
cookie
key—Null.
data—Null.
flags—Null.
proc enumerateEnd—All other protocols are enabled.
cookie
protocol enumerate to error—All mappings.
proc enumerateBegin—Nonnull cookie: begin enumeration; all other protocols may be disabled.
proc enumerate—Returns TCL_OK.
cookie
key—Nonnull.
data—Nonnull.
flags—Nonnull.
proc enumerate—Continued....
proc enumerate—Returns TCL_ERROR.
cookie
key—Null.
data—Null.
flags—Null.
proc enumerateEnd—All other protocols are enabled.
cookie
protocol enumeration failure—All mappings.
proc enumerateBegin—Null cookie: enumeration failed; all other protocols remain enabled.
ptr (*enumerateBegin)(Intr intr,Obj mapping,Obj firstHint,bool *sorted);
int (*enumerate)(Intr intr,Obj mapping,ptr cookie,Obj *key,Obj *data,int *flags);
int (*enumerateEnd)(Intr intr,Obj mapping,ptr cookie);
^
Referenced at: 3, 62.
 
 
section    top 

13. Input/output protocol :: An associative mapping is always readable, but it might not be writable.

The contents of a mapping can be gotten if the mapping is non-empty. Each I/O access has the key of the mapped item that accessed; for a sorted get, if the key does not exactly exist, a nearby key can be returned instead. A put will modify an existing item with the same key, or it will create a new item with the key; a delete can only refer to an existing item. The get may return the same object as is already in the mapping; in this case its reference count will be at least two, once for owned by the mapping, and once for the returned value. The Tcl_IsShared will detect these cases, and modifiers of Tcl object can duplicate it and then modift the duplicate.

If a Tcl shared object is modified, wyrm-assoc does not guarentee the modifications will be retained. If the mapping is read-only, it is not guarenteed the modification will even be possible.

On a put the collection will first position itself at the given key, and modify the data at that position. If the key is not in the mapping, it will be added, and position of that added key modified. The mapping may retain the put object or a duplicate ofit, in which case the object will have a reference count of at least two (for the mapping and the caller) which signals it is shared.

To update data, it should be gotten, duplicated as necessary, and then put, rather than trying to modify the gotten data and hoping the changes propagate into the mapping.

An item can be deleted; the key will no longer appear in a traversal, a get of the key will fail, and if the key or data were objects their reference counts are decremented to note they are no longer shared by the mapping.

protocol input/output
protocol read approximate—The mapping is sorted.
proc get
input seek—Approximate sought key.
output key—key = seek or nearby
protocol get exact
proc get
input seek—Sought key
output key—key = seek
protocol put at key
proc put
input key—Put key.
input data—Put data.
input flags—Put flags.
protocol delete key
proc delete
input key—Delete key.
int (*get)(Intr intr,Obj mapping,Obj seek,Obj *key,Obj *data,int *flags);
int (*put)(Intr intr,Obj mapping,Obj key,Obj data,int flags);
int (*delete)(Intr intr,Obj mapping,Obj key);
^
Referenced at: 3, 61.
 
 
section    top 

#ifndef WYRM_ASSOC_H
#define WYRM_ASSOC_H

	//	wyrm-assoc.dna - Copyright (C) 2002, 2004 SM Ryan.  All rights reserved.'

	#include "wyrmwif.h"

	<Associative map type>
	<New mapping interface>
	<Mapping status interface>
	<Mapping traversal interface>
	<Mapping I/O interface>
	<Mapping enumeration interface>
	<Package initialisation interface>
	<wyrm-assoc.h for implementors>
#endif
^
Interface wyrm-assoc.h
 
 
section    top 

#ifdef WYRM_ASSOC_H_IMPLEMENTORS
	<Declare implementor interface>
#endif
^
Referenced at: 14.
 
 
section    top 

static const char COPYRIGHT[] = "wyrm-assoc.dna - Copyright (C) 2002, 2004 SM Ryan.  All rights reserved.";

#define WYRM_ASSOC_H_IMPLEMENTORS
#include "wyrm-assoc.h"
#include "wyrm-assoc.sys"
#include "wyrm-io.h"

<Static declarations>
static bool RW = 1,RO = 0;
<wyrm_assocUpdate>
<wyrm_assocInternal>
<wyrm_sortedEnumerate>
<wyrm_assocNew>
<coerceToMapping>
<Pass through interface routines>
<wyrm_assocKey>
<wyrm_assocData>
<wyrm_assocFlags>
<wyrm_assocFilter>
<wyrm_assocFilterGlob>
<wyrm_assocFilterRE>
<Verify a path is allowed in a slave interpretter>
<package>
<assoc command>
^
Implementation wyrm-assoc.c
 
 
section    top 
void wyrm_assocUpdate(Obj mapping);
void wyrm_assocUpdateEntry(Tcl_DString *S,chars key,Obj data,int flags);
^
Definition continued at: 19, 21, 66.
Referenced at: 15, 63.
 
 
section    top 

void wyrm_assocUpdate(Obj mapping) {
	Tcl_DString D; Tcl_DStringInit(&D);
	((WyrmAssocMapType*)(mapping->typePtr))->update(mapping,&D);
	mapping->length = Tcl_DStringLength(&D);
	mapping->bytes = nheap(mapping->length+1,char);
	strcpy(mapping->bytes,Tcl_DStringValue(&D));
	Tcl_DStringFree(&D);
}

void wyrm_assocUpdateEntry(Tcl_DString *S,chars key,Obj data,int flags) {
	chars d = data ? Tcl_GetString(data) : "";
	bool flagged = flags>0 || streq(key,"[]");
	if (flagged) {
		char B[20];
		Tcl_DStringAppendElement(S,"[]");
		sprintf(B,"%d",flags<0?0:flags);
		Tcl_DStringAppendElement(S,B);
	}
	Tcl_DStringAppendElement(S,key);
	Tcl_DStringAppendElement(S,d);
}
^
Referenced at: 16.
 
 
section    top 
typedef int (*WyrmAssocScanner)(ptr context,ptr cookie);

int wyrm_assocInternal(Intr intr,Obj mapping,Tcl_ObjType *requiredType);
int wyrm_assocParseList(Intr intr,int N,Obj *P,WyrmAssocScanner scanner,ptr context);
bool wyrm_assocInternalEntry(ptr cookie,Obj *key,Obj *data,int *flags);
^
Defined at: 17.
Definition continued at: 21, 66.
Referenced at: 15, 63.
 
 
section    top 

typedef struct {
	int N; chars *P; Obj *Q; int i;
} InternalCookie;

int wyrm_assocInternal(Intr intr,Obj mapping,Tcl_ObjType *requiredType) {
	int rc;
	if (mapping->typePtr!=requiredType) {
		InternalCookie cookie; zero(1,InternalCookie,&cookie);
		if ((rc=Tcl_SplitList(intr,Tcl_GetString(mapping),&cookie.N,(CONST char***)&cookie.P))!=TCL_OK) {
			;
		}else if (cookie.N%2) {
			rc = TCL_ERROR;
			rprintf(intr,"mapping has an odd number of elements");
		}else {
			ptr internal; rc = ((WyrmAssocMapType*)requiredType)->internal(intr,mapping,&cookie,&internal);
			if (rc==TCL_OK) {
				if ((mapping)->typePtr && (mapping)->typePtr->freeIntRepProc)
					(mapping)->typePtr->freeIntRepProc((mapping));
				(mapping)->typePtr = requiredType;
				mapping->internalRep.otherValuePtr = internal;
			}
		}
		dispose(cookie.P);
	}else {
		rc = TCL_OK;
	}
	return rc;
}

int wyrm_assocParseList(Intr intr,int N,Obj *P,WyrmAssocScanner scanner,ptr context) {
	if (N%2) {
		rprintf(intr,"mapping has an odd number of elements");
		return TCL_ERROR;
	}else {
		InternalCookie cookie; zero(1,InternalCookie,&cookie);
		cookie.N = N; cookie.Q = P; cookie.i = 0;
		return scanner(context,&cookie);
	}
}

bool wyrm_assocInternalEntry(ptr cookie0,Obj *key,Obj *data,int *flags) {
	InternalCookie *cookie = cookie0;
	if (cookie->i>=cookie->N) return false;
	if (cookie->P) {
		if (streq(cookie->P[cookie->i],"[]")) {
			*flags = strtol(cookie->P[cookie->i],0,0);
			cookie->i += 2;
		}else
			*flags = 0;
	}else {
		chars q = Tcl_GetString(cookie->Q[cookie->i]);
		if (streq(q,"[]")) {
			*flags = strtol(q,0,0);
			cookie->i += 2;
		}else
			*flags = 0;
	}
	if (cookie->i>=cookie->N) {
		*key = incr(Tcl_NewObj());
		*data = incr(Tcl_NewObj());
	}else if (cookie->P) {
		*key = incr(Tcl_NewStringObj(cookie->P[cookie->i],-1));
		*data = incr(Tcl_NewStringObj(cookie->P[cookie->i+1],-1));
		cookie->i += 2;
	}else {
		*key = incr(cookie->Q[cookie->i]);
		*data = incr(cookie->Q[cookie->i+1]);
		cookie->i += 2;
	}
	return true;
}
^
Referenced at: 16.
 
 
section    top 
ptr wyrm_sortedEnumerateBegin(Intr intr,Obj mapping,Obj firstHint,bool *sorted);
int wyrm_sortedEnumerate(Intr intr,Obj mapping,ptr cookie,Obj *key,Obj *data,int *flags);
int wyrm_sortedEnumerateEnd(Intr intr,Obj mapping,ptr cookie);
^
Defined at: 17.
Definition continued at: 66.
Referenced at: 15, 63.
 
 
section    top 

ptr wyrm_sortedEnumerateBegin(Intr intr,Obj mapping,Obj firstHint,bool *sorted) {
	Obj first,last;
	*sorted = true;
	if (firstHint) {
		if (wyrm_assocGet(intr,mapping,firstHint,&first,0,0)!=TCL_OK) first = 0;
	}else {
		first = wyrm_assocFirst(intr,mapping);
	}
	last = first ? wyrm_assocLast(intr,mapping) : 0;
	if (first) {
		Obj *context = nheap(2,Obj); context[0] = first; context[1] = last;
		return context;
	}else {
		return 0;
	}
}
int wyrm_sortedEnumerate(Intr intr,Obj mapping,ptr cookie,Obj *key,Obj *data,int *flags) {
	Obj *context = cookie;
	*key = *data = 0; *flags = -1;
	if (!context || !context[0]) {
		return TCL_BREAK;
	}else {
		int rc = wyrm_assocGet(intr,mapping,context[0],key,data,flags); Obj next;
		if (rc==TCL_ERROR) next = 0;
		else if (streq(Tcl_GetString(context[0]),Tcl_GetString(context[1]))) next = 0;
		else {next = wyrm_assocNext(intr,mapping,context[0]); if (!next) rc = TCL_ERROR;}
		decr(context[0]); context[0] = next;
		return rc;
	}
}
int wyrm_sortedEnumerateEnd(Intr intr,Obj mapping,ptr cookie) {
	Obj *context = cookie;
	if (context) {decr(context[0]); decr(context[1]);}
	return TCL_OK;
}
^
Referenced at: 16.
 
 
   ^
    

Assign Mapping Type

 
    
top 
Obj wyrm_assocNew(Intr intr,chars typename,Obj base,int N,Obj *P);
^
Referenced at: 14, 58.
 
 
section    top 
proc Obj wyrm_assocNew—Construct the internal representation from the base and return it; return NULL on error.
Memory. Caller decrements reference count when done.
output Intr intr—Error message return; may be NULL.
io Obj base—The base object mapping being synthesised.
input int N—Number of additional arguments. May be zero.
input Obj* P—Additional arguments. May be null if N is zero.

Obj wyrm_assocNew(Intr intr,chars typename,Obj base,int N,Obj *P) {
	static char prefix[] = "wyrm.assoc.";
	chars typename0 = typename;
	WyrmAssocMapType *type;
	bool inventedBase = base==0;
	Obj result = 0;
	if (!strbegins(prefix,typename)) {
		typename0 = nheap(strlen(typename)+sizeof prefix,char);
		sprintf(typename0,"%s%s",prefix,typename);
	}
	type = (WyrmAssocMapType*)Tcl_GetObjType(typename0);
	if (!type) {
		rprintf(intr,"%s type not found",typename);
	}else {
		if (inventedBase) {
			base = incr(Tcl_NewObj());
		}else if (Tcl_IsShared(base)) {
			base = incr(Tcl_DuplicateObj(base));
			inventedBase = true;
		}
		result = type->new(intr,base,N,P);
	}
	if (inventedBase) decr(base);
	if (typename!=typename0) dispose(typename0);
	return result;
}
^
Referenced at: 16.
 
 
section    top 
protocol
input obj—Object being queried.
input obj—Object being queried.

static Obj coerceToMapping(Intr intr,Obj obj) {
	int N; chars *P = 0; Obj fn = 0; Tcl_Channel channel = 0; int rc;
	long magic; int n; Obj *q,T=0; Tcl_ObjType *type;
	
	if (obj->typePtr && strbegins("wyrm.assoc.",obj->typePtr->name)) {
		type = (obj->typePtr);
	}else if ((rc=Tcl_SplitList(0,Tcl_GetString(obj),&N,(CONST char***)&P))!=TCL_OK) {
		rprintf(intr,"mapping is not a list");
		type = 0;
	}else if (N%2==0) {
		type = Tcl_GetObjType("wyrm.assoc.splay");
		if (!type) rprintf(intr,"wyrm.assoc.splay type not found");
	}else if (N>1) {
		rprintf(intr,"mapping has an odd number of elements");
		type = 0;
	}else if (fn=incr(Tcl_NewStringObj(P[0],-1)), Tcl_FSAccess(fn,0)!=0) {
		type = Tcl_GetObjType("wyrm.assoc.btree");
		if (!type) rprintf(intr,"wyrm.assoc.btree type not found");
	}else if ((channel=Tcl_OpenFileChannel(intr,*P,"r",0))==0) {
		rprintf(intr,"could not open file for reading: %s",*P);
		type = 0;
	}else if ((n=cread(channel,&magic,sizeof(long)))<sizeof(long)) {
		rprintf(intr,"cannot read file magic number: %s",*P);
		type = 0;
	}else if (T=incr(Tcl_NewObj()),Tcl_AppendAllObjTypes(0,T)==TCL_OK
			&& Tcl_ListObjGetElements(0,T,&n,&q)==TCL_OK
	) {
		magic = ntohl(magic);
		for (; n>0; n--,q++) {
			if (strbegins("wyrm.assoc.",Tcl_GetString(*q))) {
				type = Tcl_GetObjType(Tcl_GetString(*q));
				if (((WyrmAssocMapType*)type)->magic==magic) break;
				type = 0;
			}
		}
		if (!type) rprintf(intr,"cannot identify the magic: %04X",magic);
	}else {
		rprintf(intr,"could not get tcl types");
		type = 0;
	}
	
	dispose(P); decr(fn); decr(T);
	if (channel) Tcl_Close(intr,channel);

	if (!type) return 0;
	else if (type==obj->typePtr) return obj;
	else if (Tcl_ConvertToType(intr,obj,type)==TCL_OK) return obj;
	else return 0;
}
^
Referenced at: 16.
 
 
   ^
    

Pass Through Interface

 
    
top 
int wyrm_assocEmpty(Intr intr,Obj mapping);
Obj wyrm_assocDump(Intr intr,Obj mapping,int N,Obj *P);
^
Referenced at: 14, 59.
 
 
section    top 
Obj wyrm_assocFirst(Intr intr,Obj mapping);
Obj wyrm_assocLast(Intr intr,Obj mapping);
Obj wyrm_assocNext(Intr intr,Obj mapping,Obj key);
Obj wyrm_assocPrevious(Intr intr,Obj mapping,Obj key);
^
Referenced at: 14, 60.
 
 
section    top 
int wyrm_assocGet(Intr intr,Obj mapping,Obj seek,Obj *key,Obj *data,int *flags);
int wyrm_assocPut(Intr intr,Obj mapping,Obj key,Obj data,int flags);
int wyrm_assocDelete(Intr intr,Obj mapping,Obj key);
^
Definition continued at: 30.
Referenced at: 14, 61.
 
 
section    top 

Obj wyrm_assocDump(Intr intr,Obj mapping,int N,Obj *P) {
	return (mapping=coerceToMapping(intr,mapping))
		? ((WyrmAssocMapType*)(mapping->typePtr))->dump(intr,mapping,N,P)
		: 0;
}

int wyrm_assocEmpty(Intr intr,Obj mapping) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->empty(intr,mapping);
	}
}
Obj wyrm_assocFirst(Intr intr,Obj mapping) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return 0;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->first(intr,mapping);
	}
}
Obj wyrm_assocLast(Intr intr,Obj mapping) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return 0;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->last(intr,mapping);
	}
}
Obj wyrm_assocNext(Intr intr,Obj mapping,Obj key) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return 0;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->next(intr,mapping,key);
	}
}
Obj wyrm_assocPrevious(Intr intr,Obj mapping,Obj key) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return 0;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->previous(intr,mapping,key);
	}
}

int wyrm_assocGet(Intr intr,Obj mapping,Obj seek,Obj *key,Obj *data,int *flags) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->get(intr,mapping,seek,key,data,flags);
	}
}
int wyrm_assocPut(Intr intr,Obj mapping,Obj key,Obj data,int flags) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->put(intr,mapping,key,data,flags);
	}
}
int wyrm_assocDelete(Intr intr,Obj mapping,Obj key) {
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		return ((WyrmAssocMapType*)(mapping->typePtr))->delete(intr,mapping,key);
	}
}
^
Referenced at: 16.
 
 
   ^
    

Auxillary I/O Routines

 
    
top 
Obj wyrm_assocKey(Intr intr,Obj mapping,Obj key);
Obj wyrm_assocData(Intr intr,Obj mapping,Obj key);
int wyrm_assocFlags(Intr intr,Obj mapping,Obj key);
^
Defined at: 28.
Referenced at: 14, 61.
 
 
section    top 
int wyrm_assocFilter(Intr intr,Obj mapping,bool name,Obj first,Obj *list,int *N,Obj **P);
int wyrm_assocFilterGlob(Intr intr,Obj mapping,bool name,Obj pattern,Obj *list,int *N,Obj **P);
int wyrm_assocFilterRE(Intr intr,Obj mapping,bool name,Obj pattern,Obj *list,int *N,Obj **P);
^
Referenced at: 14, 62.
 
 
section    top 
proc Obj wyrm_assocKey—Return the actual key at or near the key.
Memory. Caller decrements reference count when done.
input Obj mapping—Mapping being queried.
input Obj key—Key to seek.

Obj wyrm_assocKey(Intr intr,Obj mapping,Obj key) {
	Obj actualkey = 0;
	int rc = wyrm_assocGet(intr,mapping,key,&actualkey,0,0);
	if (rc==TCL_ERROR) {decr(actualkey); return 0;}
	else return actualkey;
}
^
Referenced at: 16.
 
 
section    top 
proc Obj wyrm_assocData—Return the actual data at the key or NULL.
Memory. Caller decrements reference count when done.
input Obj mapping—Mapping being queried.
input Obj key—Key to seek, or NULL for current position.

Obj wyrm_assocData(Intr intr,Obj mapping,Obj key) {
	Obj actualkey = 0;
	Obj data = 0;
	int rc = wyrm_assocGet(intr,mapping,key,&actualkey,&data,0);
	if (rc==TCL_ERROR) {
		decr(actualkey); decr(data); return 0;
	}else if (!streq(Tcl_GetString(key),Tcl_GetString(actualkey))) {
		rprintf(intr,"missing: %{y}s",key);
		decr(actualkey); decr(data); return 0;
	} else {
		decr(actualkey); return data;
	}
}
^
Referenced at: 16.
 
 
section    top 
proc Obj wyrm_assocFlags—Return the actual flags at the key or -1.
input Obj mapping—Mapping being queried.
input Obj key—Key to seek.

int wyrm_assocFlags(Intr intr,Obj mapping,Obj key) {
	Obj actualkey = 0;
	int flags = -1;
	int rc = wyrm_assocGet(intr,mapping,key,&actualkey,0,&flags);
	if (rc==TCL_ERROR) {
		decr(actualkey); return -1;
	}else if (!streq(Tcl_GetString(key),Tcl_GetString(actualkey))) {
		rprintf(intr,"missing: %{y}s",key);
		decr(actualkey); return -1;
	} else {
		decr(actualkey); return flags;
	}
}
^
Referenced at: 16.
 
 
section    top 
proc int wyrm_assocFilter—Return a list of keys and data or TCL_ERROR if error.
output Intr intr—For error messages.
input Obj mapping—Mapping being queried.
input bool name—Only names.
input Obj* list—Returned list.
input int* N—Returned list length.
input Obj** P—Returned list elements.

int wyrm_assocFilter(Intr intr,Obj mapping,bool name,Obj first,Obj *list,int *N,Obj **P) {
	*list = 0;
	if (N) *N = 0;
	if (P) *P = 0;
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		Obj result = 0;
		ptr cookie = 0;
		bool sorted;
		int rc;
		cookie = ((WyrmAssocMapType*)(mapping->typePtr))->enumerateBegin(intr,mapping,first,&sorted);
		if (cookie) {
			Obj key,data; int flags;
			result = incr(Tcl_NewObj());
			while ((rc=((WyrmAssocMapType*)(mapping->typePtr))->
						enumerate(intr,mapping,cookie,&key,&data,&flags))==TCL_OK) {
				if (Tcl_ListObjAppendElement(intr,result,key)!=TCL_OK
						|| !name && Tcl_ListObjAppendElement(intr,result,data)!=TCL_OK
				) {
					rc = TCL_ERROR;
				}
				decr(key); decr(data);
				if (rc==TCL_ERROR) break;
			}
			if (rc==TCL_BREAK) rc = TCL_OK;
			if (((WyrmAssocMapType*)(mapping->typePtr))->enumerateEnd(intr,mapping,cookie)!=TCL_OK)
				rc = TCL_ERROR;
		}else {
			rc = TCL_ERROR;
		}
		if (rc!=TCL_OK) {decr(result); result = 0;}
		*list = result;
		if (result && (N || P))  {
			int N1; Obj *P1; if (!N) N = &N1; if (!P) P = &P1;
			Tcl_ListObjGetElements(0,result,N,P);
		}
		return rc;
	}
}
^
Referenced at: 16.
 
 
section    top 
proc Obj wyrm_assocFilterGlob—Return a list of keys and data or TCL_ERROR if error.
output Intr intr—For error messages.
input Obj mapping—Mapping being queried.
input bool name—Only names.
input Obj pattern—Filter pattern.
input Obj* list—Returned list.
input int* N—Returned list length.
input Obj** P—Returned list elements.

int wyrm_assocFilterGlob(Intr intr,Obj mapping,bool name,Obj pattern,Obj *list,int *N,Obj **P) {
	*list = 0;
	if (N) *N = 0;
	if (P) *P = 0;
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		chars glob = Tcl_GetString(pattern);
		Obj result = 0;
		Obj prefix = 0;
		ptr cookie = 0;
		bool sorted;
		int rc;
		chars p; for (p=glob; *p; p++) if (*p=='*' || *p=='?' || *p=='\\' || *p=='[' || *p==']') break;
		if (p>glob) prefix = incr(Tcl_NewStringObj(glob,p-glob));
		cookie = ((WyrmAssocMapType*)(mapping->typePtr))->enumerateBegin(intr,mapping,prefix,&sorted);
		if (cookie) {
			Obj key,data; int flags;
			if (!sorted) {decr(prefix); prefix = 0;}
			result = incr(Tcl_NewObj());
			while ((rc=((WyrmAssocMapType*)(mapping->typePtr))->
						enumerate(intr,mapping,cookie,&key,&data,&flags))==TCL_OK) {
				if (sorted && prefix && strcmp(Tcl_GetString(prefix),Tcl_GetString(key))>0) break;
				rc = Tcl_StringMatch(Tcl_GetString(key),glob);
				if (rc>0 && Tcl_ListObjAppendElement(intr,result,key)!=TCL_OK) rc = -1;
				if (!name && rc>0 && Tcl_ListObjAppendElement(intr,result,data)!=TCL_OK) rc = -1;
				decr(key); decr(data);
				rc = rc<0 ? TCL_ERROR : TCL_OK;
				if (rc==TCL_ERROR) break;
			}
			if (rc==TCL_BREAK) rc = TCL_OK;
			if (((WyrmAssocMapType*)(mapping->typePtr))->enumerateEnd(intr,mapping,cookie)!=TCL_OK)
				rc = TCL_ERROR;
		}else {
			rc = TCL_ERROR;
		}
		decr(prefix);
		if (rc!=TCL_OK) {decr(result); result = 0;}
		*list = result;
		if (result && (N || P))  {
			int N1; Obj *P1; if (!N) N = &N1; if (!P) P = &P1;
			Tcl_ListObjGetElements(0,result,N,P);
		}
		return rc;
	}
}
^
Referenced at: 16.
 
 
section    top 
proc Obj wyrm_assocFilterRE—Return a list of keys and data or TCL_ERROR if error.
output Intr intr—For error messages.
input Obj mapping—Mapping being queried.
input bool name—Only names.
input Obj pattern—Filter pattern.
input Obj* list—Returned list.
input int* N—Returned list length.
input Obj** P—Returned list elements.

int wyrm_assocFilterRE(Intr intr,Obj mapping,bool name,Obj regexp,Obj *list,int *N,Obj **P) {
	*list = 0;
	if (N) *N = 0;
	if (P) *P = 0;
	if (!(mapping=coerceToMapping(intr,mapping))) {
		return TCL_ERROR;
	}else {
		Obj result = 0;
		Obj prefix = 0;
		ptr cookie = 0;
		bool sorted;
		int rc;
		chars re = Tcl_GetString(regexp);
		if (*re=='^') {
			chars p; for (p= re; *p; p++)
				if (
						*p=='*' || *p=='+' || *p=='?' || *p=='\\' || *p=='.' || *p=='$'
						|| *p=='[' || *p==']' || *p=='{' || *p=='}' || *p=='(' || *p==')'
				) break;
			if (p>re+1) prefix = incr(Tcl_NewStringObj(re+1,p-re));
		}
		cookie = ((WyrmAssocMapType*)(mapping->typePtr))->enumerateBegin(intr,mapping,prefix,&sorted);
		if (cookie) {
			Obj key,data; int flags;
			if (!sorted) {decr(prefix); prefix = 0;}
			result = incr(Tcl_NewObj());
			while ((rc=((WyrmAssocMapType*)(mapping->typePtr))->
						enumerate(intr,mapping,cookie,&key,&data,&flags))==TCL_OK) {
				if (sorted && prefix && !strbegins(Tcl_GetString(prefix),Tcl_GetString(key))) break;
				rc =Tcl_RegExpMatchObj(intr,key,regexp);
				if (rc>0 && Tcl_ListObjAppendElement(intr,result,key)!=TCL_OK) rc = -1;
				if (!name && rc>0 && Tcl_ListObjAppendElement(intr,result,data)!=TCL_OK) rc = -1;
				decr(key); decr(data);
				rc = rc<0 ? TCL_ERROR : TCL_OK;
				if (rc==TCL_ERROR) break;
			}
			if (rc==TCL_BREAK) rc = TCL_OK;
			if (((WyrmAssocMapType*)(mapping->typePtr))->enumerateEnd(intr,mapping,cookie)!=TCL_OK)
				rc = TCL_ERROR;
		}else {
			rc = TCL_ERROR;
		}
		decr(prefix);
		if (rc!=TCL_OK) {decr(result); result = 0;}
		*list = result;
		if (result && (N || P))  {
			int N1; Obj *P1; if (!N) N = &N1; if (!P) P = &P1;
			Tcl_ListObjGetElements(0,result,N,P);
		}
		return rc;
	}
}
^
Referenced at: 16.
 
 
   ^
    

Wyrmassoc Tcl Package

 
    
top 
proc int Wyrmassoc_Init—Initialise the wyrm-assoc package; returns TCL_OK or TCL_ERROR.
io Intr intr—Package initialised in the interpretter.

int Wyrmassoc_Init(Intr intr) {
	ASSOCDECLARES;
	if (Tcl_PkgProvide(intr,"wyrmassoc",VERSION)!=TCL_OK) return TCL_ERROR;
	if (!Tcl_PkgRequire(intr,"wyrmwif","1",false)) return TCL_ERROR;
	Tcl_CreateObjCommand(intr,"::wyrm::assoc",assoc,0,0);
	Tcl_CreateObjCommand(intr,"::wyrm::vassoc",assoc,"vassoc",0);
	ASSOCCALLS;
	if (Tcl_VarEval(intr,
			"namespace eval ::wyrm {namespace export assoc vassoc}\n",
			0)!=TCL_OK) return TCL_ERROR;
	if (wyrm_oavCommandInit(intr)!=TCL_OK) return TCL_ERROR;
	return TCL_OK;
}

int Wyrmassoc_SafeInit(Intr intr) {
	return Wyrmassoc_Init(intr);
}
^
Referenced at: 16.
 
 
section    top 
int Wyrmassoc_Init(Intr intr);
int Wyrmassoc_SafeInit(Intr intr);
^
Referenced at: 14.
 
 
section    top 
static int assoc(ClientData clientData,Intr intr,int N,Tcl_Obj *const P[]);
^
Referenced at: 16.
 
 
section    top 
proc int assoc—assoc command evaluator; returns TCL_OK or TCL_ERROR.
io Intr intr—Command result; sometimes variables can be defined in the current scope.
input int N—Number of command parameters.
input Obj* P—Command parameters.

static int assoc(ClientData clientData,Intr intr,int N,Tcl_Obj *const P[]) {
	int N0 = N; Obj *P0 = P; int rc,index;
	bool vassoc = streq(clientData,"vassoc"),changed = false,shared; Obj var = 0,mapping = 0;
	static chars subcommand[] = {
			"new","dump",
			"empty","first","last","next","previous",
			"filter","names",
			"get","key","data","flags","put","delete","update",
			"allow",
			0
	};
	enum {
			o_new,o_dump,
			o_empty,o_first,o_last,o_next,o_previous,
			o_filter,o_names,
			o_get,o_key,o_data,o_flags,o_put,o_delete,o_update,
			o_allow
	};
	if (N<=1) {
		Tcl_WrongNumArgs(intr,1,P0,"subcommand ..."); return TCL_ERROR;
	}
	if (Tcl_GetIndexFromObj(intr,P[1],(CONST char**)subcommand,"subcommand",0,&index)!=TCL_OK) {
		return TCL_ERROR;
	}
	N -= 2; P += 2;
	if (index==o_allow) {
		if (N==2 || N==3) {
			Obj intrpath = P[0]; int M; Obj *Q; Intr master,slave = intr;
			Obj path = P[1];
			chars pem = N==2 ? "w" : Tcl_GetString(P[2]);
			bool writable = false;
			while (*pem && !writable) if (*pem++=='w') writable = true;
			if (Tcl_ListObjGetElements(intr,intrpath,&M,&Q)!=TCL_OK) return TCL_ERROR;
			if (M==0) return rprintf(intr,"%!no interpretter path",TCL_ERROR);
			while (M-->0) {
				master = slave;
				slave = Tcl_GetSlave(intr,Tcl_GetString(*P));
				if (!slave) return rprintf(intr,"%!unknown slave: %{y}s",TCL_ERROR,*P);
				P++;
			}
			<External mapping paths in safe interpretters>
		}else {
			Tcl_WrongNumArgs(intr,2,P0,"variable-name ...");
			return TCL_ERROR;
		}
		Tcl_ResetResult(intr);
		return TCL_OK;
	}
	if (index==o_new) {
		if (vassoc) {
			if (N>0) {
				var = *P++; N--;
			}else {
				Tcl_WrongNumArgs(intr,N0,P0,"variable-name ...");
				return TCL_ERROR;
			}
		}
	}else {
		if (vassoc) {
			if (N>0) {
				var = *P++; N--;
			}else {
				Tcl_WrongNumArgs(intr,N0,P0,"variable-name ...");
				return TCL_ERROR;
			}
			mapping = Tcl_ObjGetVar2(intr,var,0,TCL_LEAVE_ERR_MSG);
			if (!mapping && index!=o_new) return TCL_ERROR;
			changed = !mapping;
		}else {
			if (N>0) {
				mapping = *P++; N--;
			}else {
				Tcl_WrongNumArgs(intr,N0,P0,"mapping ...");
				return TCL_ERROR;
			}
		}
	}
	switch (index) {
		case o_put: case o_delete: case o_update: {
			if (mapping && Tcl_IsShared(mapping)) {
				mapping = Tcl_DuplicateObj(mapping);
				incr (mapping);
				changed = true;
			}else {
				incr (mapping);
			}
		}	break;
	}
	switch (index) {
		case o_new: <assoc new typename [base [p1 p2 ...]]> break;
		case o_dump: <assoc dump mapping [p1 p2 ...]> break;
		case o_empty: <assoc empty mapping> break;
		case o_first: <assoc first mapping> break;
		case o_last: <assoc last mapping> break;
		case o_next: <assoc next mapping key> break;
		case o_previous: <assoc previous mapping key> break;
		case o_filter: case o_names: <assoc filter|names mapping [[glob|re] pattern]> break;
		case o_get: <assoc get mapping> break;
		case o_key: <assoc key mapping key> break;
		case o_data: <assoc data mapping key> break;
		case o_flags: <assoc flags mapping key> break;
		case o_put: <assoc put mapping> break;
		case o_delete: <assoc delete mapping key> break;
		case o_update: <assoc update mapping key var [initial] {script}> break;
	}
	switch (index) {
		case o_new: case o_put: case o_delete: case o_update:
			if (vassoc && rc==TCL_OK && changed && mapping) {
				if (!Tcl_ObjSetVar2(intr,var,0,mapping,TCL_LEAVE_ERR_MSG)) rc = TCL_ERROR;
			}
			decr(mapping);
			break;
	}
	return rc;
}
^
Referenced at: 16.
 
 
section    top 

if (N==0) {
	Tcl_WrongNumArgs(intr,N0,P0,"typename"); rc = TCL_ERROR;
}else if (N==1) {
	Obj empty = incr(Tcl_NewObj());
	changed = true;
	mapping = wyrm_assocNew(intr,Tcl_GetString(P[0]),empty,0,0);
	decr(empty);
	if (mapping) {Tcl_SetObjResult(intr,mapping); rc = TCL_OK;}
	else {rc = TCL_ERROR;}
}else {
	changed = true;
	mapping = wyrm_assocNew(intr,Tcl_GetString(P[0]),P[1],N-2,P+2);
	if (mapping) {Tcl_SetObjResult(intr,mapping); rc = TCL_OK;}
	else {rc = TCL_ERROR;}
}
^
Referenced at: 41, 57.
 
 
section    top 

{
	Obj result = wyrm_assocDump(intr,mapping,N,P);
	if (result) {Tcl_SetObjResult(intr,result); decr(result); rc = TCL_OK;}
	else {rc = TCL_ERROR;}
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==0) {
	int pos = wyrm_assocEmpty(intr,mapping);
	if (pos==TCL_ERROR) rc = pos;
	else {Tcl_SetObjResult(intr,Tcl_NewBooleanObj(pos==TCL_OK)); rc = TCL_OK;}
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping");
	rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==0) {
	Obj key = wyrm_assocFirst(intr,mapping);
	if (key) {Tcl_SetObjResult(intr,key); rc = TCL_OK;}
	else rc = TCL_ERROR;
	decr(key);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==0) {
	Obj key = wyrm_assocLast(intr,mapping);
	if (key) {Tcl_SetObjResult(intr,key); rc = TCL_OK;}
	else rc = TCL_ERROR;
	decr(key);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==1) {
	Obj oldkey = *P;
	Obj newkey = wyrm_assocNext(intr,mapping,oldkey);
	if (newkey) {Tcl_SetObjResult(intr, newkey); rc = TCL_OK;}
	else rc = TCL_ERROR;
	decr(newkey);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping key"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==1) {
	Obj oldkey = *P;
	Obj newkey = wyrm_assocPrevious(intr,mapping,oldkey);
	if (newkey) {Tcl_SetObjResult(intr, newkey); rc = TCL_OK;}
	else rc = TCL_ERROR;
	decr(newkey);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping key"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (!(mapping=coerceToMapping(intr,mapping))) {
	rc = TCL_ERROR;
} else if (N>2) {
	Tcl_WrongNumArgs(intr,2,P0,"mapping [[-glob|-re] pattern]"); rc = TCL_ERROR;
}else {
	Obj glob = 0;
	Obj regexp = 0;
	Obj result = 0;
	Obj prefix = 0;
	ptr cookie = 0;
	bool sorted;
	if (N==1) {
		glob = *P;
	}else if (N==2) {
		static chars matcher[] = {
			"-glob","glob","-regexp","regexp",0
		};
		enum {glob1,glob2,re1,re2};
		int kind;
		if (Tcl_GetIndexFromObj(intr,*P,(CONST char**)matcher,"kind of pattern",0,&kind)!=TCL_OK) {
			rc = TCL_ERROR;
			break;
		}
		switch (kind) {
			case glob1: case glob2: glob = P[1]; break;
			case re1: case re2: regexp = P[1]; break;
		}
	}
	rc = glob ? wyrm_assocFilterGlob(intr,mapping,index==o_names,glob,&result,0,0)
			: regexp ? wyrm_assocFilterRE(intr,mapping,index==o_names,regexp,&result,0,0)
			: wyrm_assocFilter(intr,mapping,index==o_names,0,&result,0,0);
	if (rc==TCL_OK) Tcl_SetObjResult(intr,result);
	decr(result);
}
^
Referenced at: 41, 57.
 
 
section    top 
50. assoc get mapping ::
wyrm::assoc get mapping [ -key keyvar ] [ -flags flagsvar ] [ -data datavar ] [ -exact exactvar ] [ -- ] key [ datavar ]
Get the data from the element with the (approximate) key. If mapping is sorted and exactvar or keyvar are specified, the key does not have to exist in the mapping; it can be the approximate position, with the actual key returned in keyvar. If the mapping is unsorted or exactvar and keyvar are not specified, the key must be the mapping or it is an error. If keyvar is specified, it is set to the key of the position. If datavar is specified, it is set to the data of the position. If flagsvar is specified, it is set to the flags of the position. If exactvar is specified, it is set to true if key was exactly in the mapping and false if only the approximate key was found. Always returns the data or error. 

{
	Obj keyvar=0,datavar=0,flagsvar=0,exactvar=0,key=0,actualkey=0,data=0; int flags = -1,exact;
	rc = TCL_OK;
	while (N>=2) {
		if (strbegins("-k",Tcl_GetString(P[0]))) {
			keyvar = P[1]; N -= 2; P += 2;
		}else if (strbegins("-d",Tcl_GetString(P[0]))) {
			datavar = P[1]; N -= 2; P += 2;
		}else if (strbegins("-f",Tcl_GetString(P[0]))) {
			flagsvar = P[1]; N -= 2; P += 2;
		}else if (strbegins("-e",Tcl_GetString(P[0]))) {
			exactvar = P[1]; N -= 2; P += 2;
		}else if (streq("--",Tcl_GetString(P[0]))) {
			N -= 1; P += 1; break;
		}else if (strbegins("-",Tcl_GetString(P[0]))) {
			rprintf(intr,"unknown option: assoc get ... %{y}s",*P);
			rc = TCL_ERROR; break;
		}else {
			break;
		}
	}
	if (rc==TCL_OK) switch (N) {
		case 2:	datavar = P[1];
		case 1:	key = P[0];
			break;
		default:
			Tcl_WrongNumArgs(intr,2,P0,"mapping [vars] key [datavar]"); rc = TCL_ERROR;
			break;
	}
	if (rc!=TCL_OK) break;
	rc = wyrm_assocGet(intr,mapping,key,&actualkey,&data,&flags);
	if (rc==TCL_OK) {
		exact = actualkey  && streq(Tcl_GetString(key),Tcl_GetString(actualkey));
	}else if (exactvar
			&& (strbegins("missing: ",Tcl_GetStringResult(intr))
				|| streq("empty mapping",Tcl_GetStringResult(intr)))
	) {
		rc = TCL_OK; exact = false;
	}else {
		break;
	}
	if (!exact && !keyvar && !exactvar) {
		rprintf(intr,"missing: %{y}s",key); rc = TCL_ERROR;
	}
	if (keyvar && rc==TCL_OK && actualkey) {
		if (!Tcl_ObjSetVar2(intr,keyvar,0,actualkey,TCL_LEAVE_ERR_MSG)) rc = TCL_ERROR;
	}
	if (datavar && rc==TCL_OK && data) {
		if (!Tcl_ObjSetVar2(intr,datavar,0,data,TCL_LEAVE_ERR_MSG)) rc = TCL_ERROR;
	}
	if (flagsvar && rc==TCL_OK && flags>=0) {
		Obj FLAGS = incr(Tcl_NewIntObj(flags));
		if (!Tcl_ObjSetVar2(intr,flagsvar,0,FLAGS,TCL_LEAVE_ERR_MSG)) rc = TCL_ERROR;
		decr(FLAGS);
	}
	if (exactvar && rc==TCL_OK) {
		Obj EXACT = incr(Tcl_NewBooleanObj(exact));
		if (!Tcl_ObjSetVar2(intr,exactvar,0,EXACT,TCL_LEAVE_ERR_MSG)) rc = TCL_ERROR;
		decr(EXACT);
	}
	if (rc==TCL_OK) {
		if (data) Tcl_SetObjResult(intr,data);
		else Tcl_ResetResult(intr);
	}
	decr(actualkey); decr(data);
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==1) {
	Obj oldkey = *P;
	Obj newkey = wyrm_assocKey(intr,mapping,oldkey);
	if (newkey) {Tcl_SetObjResult(intr,newkey); rc = TCL_OK;}
	else rc = TCL_ERROR;
	decr(newkey);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping key"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==1) {
	Obj key = *P;
	Obj data = wyrm_assocData(intr,mapping,key);
	if (data) {Tcl_SetObjResult(intr,data); rc = TCL_OK;}
	else rc = TCL_ERROR;
	decr(data);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping key"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==1) {
	Obj key = *P;
	int flags = wyrm_assocFlags(intr,mapping,key);
	if (flags>=0) {Tcl_SetObjResult(intr,Tcl_NewIntObj(flags)); rc = TCL_OK;}
	else rc = TCL_ERROR;
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping key"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 

{
	Obj key=0,data=0; int flags = -1;
	rc = TCL_OK;
	while (N>=2) {
		if (strbegins("-k",Tcl_GetString(P[0]))) {
			key = P[1]; N -= 2; P += 2;
		}else if (strbegins("-d",Tcl_GetString(P[0]))) {
			data = P[1]; N -= 2; P += 2;
		}else if (strbegins("-f",Tcl_GetString(P[0]))) {
			if (Tcl_GetIntFromObj(intr,P[1],&flags)==TCL_OK) {
				N -= 2; P += 2;
			}else {
				rc = TCL_ERROR; break;
			}
		}else if (streq("--",Tcl_GetString(P[0]))) {
			N -= 1; P += 1; break;
		}else if (strbegins("-",Tcl_GetString(P[0]))) {
			rprintf(intr,"unknown option: assoc put ... %{y}s",*P);
			rc = TCL_ERROR; break;
		}else {
			break;
		}
	}
	if (rc==TCL_OK) switch (N) {
		case 2: key = P[0]; data = P[1]; break;
		case 1:	key = P[0];
			break;
		case 0:
			if (key) break;
		default:
			Tcl_WrongNumArgs(intr,2,P0,"mapping [vars] key [data]"); rc = TCL_ERROR;
	}
	if (rc==TCL_OK) {
		rc = wyrm_assocPut(intr,mapping,key,data,flags);
		if (rc==TCL_OK) Tcl_SetObjResult(intr,mapping);
	}
}
^
Referenced at: 41, 57.
 
 
section    top 

if (N==1) {
	rc = wyrm_assocDelete(intr,mapping,*P);
	if (rc==TCL_OK) Tcl_SetObjResult(intr,mapping);
}else {
	Tcl_WrongNumArgs(intr,2,P0,"mapping key"); rc = TCL_ERROR;
}
^
Referenced at: 41, 57.
 
 
section    top 
56. assoc update mapping key var [initial] {script} ::
wyrm::assoc update mapping key var [ initial-value ] script
Update a mapping element in an optimised fashion. If an element with the given key exists, it is assigned to var; if it does not exist, the variable is assigned initial-value (if specified) or an empty string. The script is evaluated. The resulting value of var is put back into the mapping. The update is done whether the script throws an error or not; it is suggested the variable not be modified until the script knows it can complete without error. Unless an error, the modified mapping is returned. The script evaluates in the caller's scope, sharing any local variables defined within and without the script. In particular the var retains the value put back into the mapping.
For example, to increment a counter in a mapping,
vassoc update mapping counter-key counter 0 {incr counter}
To append a string,
vassoc update mapping v-key v {append v $x}
To replace a list element (v is not directly assigned to ensure the lreplace completes without error before updating the variable value),
vassoc update mapping v-key v {set w [lreplace $v $i $i $x]; set v $w}

if (N<3) {
	Tcl_WrongNumArgs(intr,3,P0,"key var [default] {script}"); rc = TCL_ERROR;
}else if (N>4) {
	Tcl_WrongNumArgs(intr,7,P0,"...: too many"); rc = TCL_ERROR;
}else {
	Obj key = P[0];
	Obj actualkey;
	Obj data;
	Obj var = P[1];
	Obj val = 0;
	Obj initial = N==3 ? 0 : P[2];
	Obj script = N==3 ? P[2] : P[3];
	bool atrisk = false;
	rc = wyrm_assocGet(intr,mapping,key,&actualkey,&data,0);
	if (rc==TCL_ERROR || !streq(Tcl_GetString(key),Tcl_GetString(actualkey))) {
		if (initial) {
			val = Tcl_ObjSetVar2(intr,var,0,initial,TCL_LEAVE_ERR_MSG);
		}else {
			initial = incr(Tcl_NewObj());
			val = Tcl_ObjSetVar2(intr,var,0,initial,TCL_LEAVE_ERR_MSG);
			decr(initial); initial = 0;
		}
	}else {
		if (Tcl_IsShared(data)) {
			atrisk = true;
			rc = wyrm_assocPut(intr,mapping,key,(val=incr(Tcl_NewObj())),-1);
			decr(val);
		}
		if (rc==TCL_OK && Tcl_IsShared(data)) {
			val = incr(Tcl_DuplicateObj(data)); decr(data); data = val;
		}
		val = rc==TCL_OK ? Tcl_ObjSetVar2(intr,var,0,data,TCL_LEAVE_ERR_MSG) : 0;
	}
	rc = val ? TCL_OK : TCL_ERROR;
	decr(actualkey);
	decr(data);
	if (rc==TCL_OK) rc = Tcl_EvalObjEx(intr,script,0);
	val = Tcl_ObjGetVar2(intr,var,0,0);
	if (val && wyrm_assocPut(intr,mapping,key,val,-1)==TCL_OK) atrisk = false;
	if (!val) rc = TCL_ERROR;
	if (rc==TCL_OK) {
		Tcl_SetObjResult(intr,mapping);
	}else if (atrisk) {
		Tcl_AppendResult(intr," (The original value of '",Tcl_GetString(key),"' has been lost.)",0);
	}
}
^
Referenced at: 41, 57.
 
 
   ^
    

Man Pages

 
    
top 
^
Manpage assoc (1WY)
 
 
section    top 
^
Manpage wyrm_assocNew (3WY)
 
 
section    top 
^
Manpage wyrm_assocEmpty (3WY)
 
 
section    top 
^
Manpage wyrm_assocFirst (3WY)
 
 
section    top 
^
Manpage wyrm_assocGet (3WY)
 
 
section    top 
^
Manpage wyrm_assocFilter (3WY)
 
 
section    top 
^
Manpage WyrmAssocMapType (4WY)
 
 
   ^
    

Safe Interpretters

 
    
top 
64. External mapping paths in safe interpretters ::
wyrm::assoc allow interpretter-path mapping [ rw|ro ]
Internal mappings are unrestricted in safe interpretters. External mappings can be accessed, if allowed. The master of a safe interpretter uses this command to allow the safe interpretter to open the mapping file. The allowance can further restrict it to a read-only mapping. A safe interpretter can only allow to its slaves those paths it itself is allowed.
Examples:
Trusted interpretter with safe slave.
assoc allow slave /actual/file/path w
slave eval assoc put /actual/file/path key value
Safe interpretter with safe slave.
assoc allow {one} /actual/file/path w
interp eval {one} assoc allow two /actual/file/path r
interp eval {one} assoc put /actual/file/path key value
interp eval {one two} assoc get /actual/file/path key

{
	Obj key = oprintf("wyrm.assoc.safe.path.%{y}s",path);
	if (Tcl_IsSafe(master)) {
		ClientData *o = Tcl_GetAssocData(master,Tcl_GetString(key),0);
		if (o) {
			Tcl_SetAssocData(slave,Tcl_GetString(key),0,writable?o:(ClientData)&RO);
		}else {
			decr(key); return rprintf(intr,"%!unknown mapping: %{y}s",TCL_ERROR,path);
		}
	}else {
		Tcl_SetAssocData(slave,Tcl_GetString(key),0,writable?&RW:&RO);
	}
	decr(key); return TCL_OK;
}
^
Referenced at: 41, 57.
 
 
section    top 

bool wyrm_assocAllowedPath(Intr intr,Obj path,bool *writable) {
	if (Tcl_IsSafe(intr)) {
		Obj key = oprintf("wyrm.assoc.safe.path.%{y}s",path),actualpath = 0;
		bool *RX = Tcl_GetAssocData(intr,Tcl_GetString(key),0);
		decr(key);
		if (RX) {
			if (RX==&RO) *writable = false;
			return true;
		}else {
			rprintf(intr,"unknown external associative mapping");
			return false;
		}
	}else {
		return true;
	}
}
^
Referenced at: 16.
 
 
section    top 
bool wyrm_assocAllowedPath(Intr intr,Obj path,bool *writable);
^
Defined at: 17.
Referenced at: 15, 63.
 
 
   ^
    

Test Base

 
    
top 
    MAP Associative mappings.
      MAP000
      Missing operation.
        MAP0AA
        MAP0AB
        MAP0AC
      New operation.
        Syntax.
          MAP0BA
          MAP0BB
        Semantics.
          MAP0BC
          MAP0BD
          MAP0BE
          MAP0BF
          MAP0BK
          MAP0BL
      Empty operation.
        Syntax.
          MAP0CJ
          MAP0CK
        Semantics.
          MAP0CL
          MAP0CM
      Dump operation.
        Syntax.
          MAP0CS
        Semantics.
          MAP0CT
          MAP0CU
      First operation.
        Syntax.
          MAP0DN
          MAP0DO
        Semantics.
          MAP0DP
          MAP0DQ
      Last operation.
        Syntax.
          MAP0DU
          MAP0DV
        Semantics.
          MAP0DW
          MAP0DX
      Next operation.
        Syntax.
          MAP0EAA
          MAP0EAB
          MAP0EB
        Semantics.
          MAP0EC
          MAP0ED
          MAP0EE
          MAP0EF
      Previous operation.
        Syntax.
          MAP0EKA
          MAP0EKN
          MAP0EL
        Semantics.
          MAP0EM
          MAP0EN
          MAP0EO
          MAP0EP
      Filter operation.
        Syntax.
          Mapping
            Mapping specified.'>
              MAP0QA
            Mapping not specified.
              MAP0QB
          Pattern kind.
            Explicit -glob.
              MAP0QC
            Implicit -glob.
              MAP0QD
              MAP0QW
            Explicit -regexp.
              MAP0QE
            Unknown pattern kind.
              MAP0QF
          Pattern.
            Glob pattern.
              MAP0QG
            Regexp pattern.
              MAP0QH
            No pattern.
              MAP0QI
          MAP0QJ
        Semantics.
          Mapping.
            Empty mapping.
              MAP0QK
            One element mapping.
              MAP0QL
            Multiple element mapping.
              MAP0QM
          Pattern.
            No pattern.
              MAP0QN
            Glob pattern.
              All matched.
              MAP0QO
              Some matched.
                MAP0QP
              None matched.
                MAP0QQ
              Erroneous pattern.
                MAP0QR
            Regexp pattern.
              All matched.
                MAP0QS
              Some matched.
                MAP0QT
              None matched.
                MAP0QU
              Erroneous pattern.
                MAP0QV
      Names operation.
        Syntax.
          Mapping
            Mapping specified.'>
              MAP0RA
            Mapping not specified.
              MAP0RB
          Pattern kind.
            Explicit -glob.
              MAP0RC
            Implicit -glob.
              MAP0RD
              MAP0RW
            Explicit -regexp.
              MAP0RE
            Unknown pattern kind.
              MAP0RF
          Pattern.
            Glob pattern.
              MAP0RG
            Regexp pattern.
              MAP0RH
            No pattern.
              MAP0RI
          MAP0RJ
        Semantics.
          Mapping.
            Empty mapping.
              MAP0RK
            One element mapping.
              MAP0RL
            Multiple element mapping.
              MAP0RM
          Pattern.
            No pattern.
              MAP0RN
            Glob pattern.
              All matched.
              MAP0RO
              Some matched.
                MAP0RP
              None matched.
                MAP0RQ
              Erroneous pattern.
                MAP0RR
            Regexp pattern.
              All matched.
                MAP0RS
              Some matched.
                MAP0RT
              None matched.
                MAP0RU
              Erroneous pattern.
                MAP0RV
      Get operation.
        Syntax.
          parameter count.
            MAP0FA
            MAP0FB
          Flag syntax.
            MAP0FD
            MAP0FE
            MAP0FF
            MAP0FG
            MAP0FH
          Positional syntax.
            MAP0FJ
            MAP0FK
        Semantics.
          MAP0FN
          MAP0FOA
          MAP0FOB
          MAP0FOC
          MAP0FPA
          MAP0FPB
          MAP0FPC
          Invalid variables.
            MAP0FQ
            MAP0FR
            MAP0FS
            MAP0FT
        Stress tests.
          MAP0FV
          MAP0FW
          MAP0FX
          MAP0FY
          MAP0FZ
      Put operation.
        Syntax.
          parameter count.
            MAP0GA
            MAP0GB
          Flag syntax.
            MAP0GD
            MAP0GE
            MAP0GF
            MAP0GG
          Positional syntax.
            MAP0GJ
            MAP0GK
        Semantics.
          MAP0GN
          MAP0GO
          MAP0GP
        Stress tests.
          MAP0GV
          MAP0GW
          MAP0GX
          MAP0GY
          MAP0GZ
      Key operation.
        Syntax.
          Number of parameters.
            MAP0HA
            MAP0HB
            MAP0HC
        Semantics.
          MAP0HF
          MAP0HG
      Data operation.
        Syntax.
          Number of parameters.
            MAP0HN
            MAP0HO
            MAP0HQ
        Semantics.
          MAP0HR
          MAP0HS
      Flags operation.
        Syntax.
          Number of parameters.
            MAP0IA
            MAP0IB
            MAP0ID
        Semantics.
          MAP0IG
          MAP0IH
      Delete operation.
        Syntax.
          Number of parameters.
            MAP0JA
            MAP0JB
            MAP0JC
        Semantics.
          MAP0JF
          MAP0JG
^
Testbase wyrm-assoc.test
 
 
   ^