Merge pull request #10 from JesseCoretta/v1.0.4

v1.0.4 release prep

README.md

@@ -1,6 +1,6 @@
 # go-stackage
 
-[![Go Report Card](https://goreportcard.com/badge/github.com/JesseCoretta/go-stackage)](https://goreportcard.com/report/github.com/JesseCoretta/go-stackage) [![Go Reference](https://pkg.go.dev/badge/github.com/JesseCoretta/go-stackage.svg)](https://pkg.go.dev/github.com/JesseCoretta/go-stackage) [![CodeQL](https://github.com/JesseCoretta/go-stackage/workflows/CodeQL/badge.svg)](https://github.com/JesseCoretta/go-stackage/actions/workflows/github-code-scanning/codeql) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-stackage/blob/main/LICENSE) [![codecov](https://codecov.io/gh/JesseCoretta/go-stackage/graph/badge.svg?token=RLW4DHLKQP)](https://codecov.io/gh/JesseCoretta/go-stackage) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-stackage/issues) [![Experimental](https://img.shields.io/badge/experimental-blue?logoColor=blue&label=%F0%9F%A7%AA%20%F0%9F%94%AC&labelColor=blue&color=gray)](https://github.com/JesseCoretta/JesseCoretta/blob/main/EXPERIMENTAL.md) [![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/jessecoretta/go-stackage/go.yml?event=push)](https://github.com/JesseCoretta/go-stackage/actions/workflows/go.yml) [![Author](https://img.shields.io/badge/author-Jesse_Coretta-darkred?label=%F0%9F%94%BA&labelColor=indigo&color=maroon)](mailto:[email protected]) [![GitHub release (with filter)](https://img.shields.io/github/v/release/JesseCoretta/go-stackage)](https://github.com/JesseCoretta/go-stackage/releases) [![Help Animals](https://img.shields.io/badge/help_animals-gray?label=%F0%9F%90%BE%20%F0%9F%98%BC%20%F0%9F%90%B6&labelColor=yellow)](https://github.com/JesseCoretta/JesseCoretta/blob/main/DONATIONS.md)
+[![Go Report Card](https://goreportcard.com/badge/github.com/JesseCoretta/go-stackage)](https://goreportcard.com/report/github.com/JesseCoretta/go-stackage) [![Go Reference](https://pkg.go.dev/badge/github.com/JesseCoretta/go-stackage.svg)](https://pkg.go.dev/github.com/JesseCoretta/go-stackage) [![CodeQL](https://github.com/JesseCoretta/go-stackage/workflows/CodeQL/badge.svg)](https://github.com/JesseCoretta/go-stackage/actions/workflows/github-code-scanning/codeql) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-stackage/blob/main/LICENSE) [![codecov](https://codecov.io/gh/JesseCoretta/go-stackage/graph/badge.svg?token=RLW4DHLKQP)](https://codecov.io/gh/JesseCoretta/go-stackage) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/JesseCoretta/go-stackage/issues) [![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/jessecoretta/go-stackage/go.yml?event=push)](https://github.com/JesseCoretta/go-stackage/actions/workflows/go.yml) [![Author](https://img.shields.io/badge/author-Jesse_Coretta-darkred?label=%F0%9F%94%BA&labelColor=indigo&color=maroon)](mailto:[email protected]) [![GitHub release (with filter)](https://img.shields.io/github/v/release/JesseCoretta/go-stackage)](https://github.com/JesseCoretta/go-stackage/releases) [![Help Animals](https://img.shields.io/badge/help_animals-gray?label=%F0%9F%90%BE%20%F0%9F%98%BC%20%F0%9F%90%B6&labelColor=yellow)](https://github.com/JesseCoretta/JesseCoretta/blob/main/DONATIONS.md)
 
 ![stacks03](https://github.com/JesseCoretta/go-stackage/assets/74126726/ec6429ac-d698-413b-8c1c-0ac8dc1e301c)
 
@@ -17,7 +17,7 @@ The main goal of this package is provide an extremely reliable and accommodating
   - Stack instances are either LIFO (stack based, default) or FIFO (queue based)
     - FIFO is First-In/First-Out (like a line at your favorite deli: first come, first serve)
     - LIFO is Last-In/First-Out (like those plate-stacking apparatuses found in restaurant kitchens, in which the first plate inserted shall be the last plate removed)
-  - Flexible Stack configuration controls, allowing custom stringer presentation, push controls and validity-checking policies to be imposed
+  - Flexible Stack configuration controls, allowing custom stringer presentation, sorting closures, push controls and validity-checking policies to be imposed
   - Recursive design - Stacks can reside in Stacks. Conditions can reside in Stacks. Conditions can contain other Stacks. Whatever!
     - Eligible values are easily navigated using the Stack.Traverse method using an ordered sequence of indices, or slice index numbers
     - Conversely, recursion capabilities can also be easily disabled per instance!
@@ -36,7 +36,7 @@ The main goal of this package is provide an extremely reliable and accommodating
 
 ## Status
 
-Although fairly well-tested, this package is in its early stages and is undergoing active development. It should only be used in production environments while under heavy scrutiny and with great care.
+This package is no longer considered experimental, as it is currently in use in the wild with impressive results.
 
 ## License
 
@@ -75,6 +75,14 @@ func (r MyStack) String() string {
  	// return the result from a "TYPE CAST -> EXEC" call
 	return stackage.Stack(r).String()
 }
+
+// For added convenience, adopters can write their own private "cast"
+// method for quick transformation back to the derived Stack type.
+// This allows easy access to base methods which the adopter has not
+// explicitly wrapped.
+func (r MyStack) cast() stackage.Stack {
+	return stackage.Stack(r)
+}
 ```
 
 The procedure would be identical for a Condition alias -- just change the name and the derived stackage type from the first example line and modify as desired.

cfg.go

@@ -28,32 +28,34 @@ type nodeConfig struct {
 	err error              // error pertaining to the outer type state (Condition/Stack)
 	aux Auxiliary          // auxiliary admin-related object storage, user managed
 
-	typ stackType   // stacks only: defines the typ/kind of stack
-	sym string      // stacks only: user-controlled symbol char(s)
-	ljc string      // [list] stacks only: joining delim
-	mtx *sync.Mutex // stacks only: optional locking system
-	ldr *time.Time  // for lock duration; ephemeral, nil if not locked / no locking capabilities
-	ord bool        // true = FIFO, false = LIFO (default); applies to stacks only
+	lss func(int, int) bool // stacks only: for sort.Interface qualification
+	typ stackType           // stacks only: defines the typ/kind of stack
+	sym string              // stacks only: user-controlled symbol char(s)
+	ljc string              // [list] stacks only: joining delim
+	mtx *sync.Mutex         // stacks only: optional locking system
+	ldr *time.Time          // for lock duration; ephemeral, nil if not locked / no locking capabilities
+	ord bool                // true = FIFO, false = LIFO (default); applies to stacks only
 }
 
 /*
 Auxiliary is a map[string]any type alias extended by this package. It
-can be created within any Stack instance when [re]initialized using
-the SetAuxiliary method extended through instances of the Stack type,
-and can be accessed using the Auxiliary() method in similar fashion.
+can be created within any [Stack] instance when [re]initialized using
+the [Stack.SetAuxiliary] method extended through instances of the [Stack]
+type, and can be accessed using the [Stack.Auxiliary] method in similar
+fashion.
 
-The Auxiliary type extends four (4) methods: Get, Set, Len and Unset.
-These are purely for convenience. Given that instances of this type
-can easily be cast to standard map[string]any by the user, the use of
-these methods is entirely optional.
+The [Auxiliary] type extends four (4) methods: [Auxiliary.Get], [Auxiliary.Set],
+[Auxiliary.Len] and [Auxiliary.Unset]. These are purely for convenience.  Given
+that instances of this type can easily be cast to standard map[string]any by the
+user, the use of these methods is entirely optional.
 
-The Auxiliary map instance is available to be leveraged in virtually
+The [Auxiliary] map instance is available to be leveraged in virtually
 any way deemed appropriate by the user. Its primary purpose is for
 storage of any instance(s) pertaining to the *administration of the
 stack*, as opposed to the storage of content normally submitted *into*
-said stack.
+said [Stack].
 
-Examples of suitable instance types for storage within the Auxiliary
+Examples of suitable instance types for storage within the [Auxiliary]
 map include, but are certainly not limited to:
 
   - HTTP server listener / mux
@@ -66,7 +68,7 @@ map include, but are certainly not limited to:
   - text/template instances
   - channels
 
-Which instances are considered suitable for storage within Auxiliary map
+Which instances are considered suitable for storage within [Auxiliary] map
 instances is entirely up to the user. This package shall not impose ANY
 controls or restrictions regarding the content within this instances of
 this type, nor its behavior.
@@ -100,7 +102,7 @@ func (r Auxiliary) Get(key string) (value any, ok bool) {
 
 /*
 Set associates key with value, and assigns to receiver instance. See
-also the Unset method.
+also the [Auxiliary.Unset] method.
 
 If the receiver is not initialized, a new allocation is made.
 */
@@ -113,7 +115,7 @@ func (r Auxiliary) Set(key string, value any) Auxiliary {
 
 /*
 Unset removes the key/value pair, identified by key, from the receiver
-instance, if found. See also the Set method.
+instance, if found. See also the [Auxiliary.Set] method.
 
 This method internally calls the following builtin: