stackage

package module
v0.0.2-alpha.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2023 License: MIT Imports: 8 Imported by: 4

README

go-stackage

Go Report Card GoDoc Software License

Package stackage implements a flexible Stack type with useful features.

Documentation

Overview

Package stackage implements a flexible stack type optimized for use in creating and presenting conditional Boolean statements, abstract mathematical constructs, LDAP filter abstractions or simple lists.

Features

• Flexible Stack configuration controls, allowing custom presentation, push and validity policies to be executed (instead of default behavior) through the use of closure signature functions

• Recursive design - Stacks can reside in Stacks. Conditions can reside in Stacks. Conditions can contain other Stacks. Whatever.

• Traversible - Recursive values are easily navigated using the Stack.Traverse method

• Fluent-style - types which offer methods for cumulative configuration are written in fluent-form, allowing certain commands to be optionally "chained" together

• Extensible logical operator framework, allowing custom operators to be added for specialized expressions instead of the package-provided ComparisonOperator constants

• MuTeX capable for each Stack instance independent of its parent or child (no recursive locking mechanisms)

• Adopters may wish to create a type alias of the Condition and/or Stack types; this is particularly easy, and will not impact normal operations when dealing with nested instances of derivative types

• Assertion capabilities; go beyond merely crafting the string representation of a formula -- add an Evaluator function to conduct an interrogation of a value, matching procedures, and more!

• Fast, reliable, useful

Status

This package is in its early stages, and is undergoing active development. It should NOT be used in any production capacity at this time.

License

The stackage (go-stackage) package, from http://github.com/JesseCoretta/go-stackage, is available under the terms of the MIT license. For further details, see the LICENSE file within the aforementioned repository.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ComparisonOperator 

type ComparisonOperator uint8

ComparisonOperator is a uint8 enumerated type used for abstract representation of the following well-known and package-provided operators:

• Equal (=)

• Not Equal (!=)

• Less Than (<)

• Greater Than (>)

• Less Than Or Equal (<=)

• Greater Than Or Equal (>=)

Instances of this type should be passed to Cond as the 'op' value. 

const (
	Eq ComparisonOperator // 1 (=)
	Ne                    // 2 (!=)
	Lt                    // 3 (<)
	Gt                    // 4 (>)
	Le                    // 5 (<=)
	Ge                    // 6 (>=)
)

ComparisonOperator constants are intended to be used in singular form when evaluating two (2) particular values.

func (ComparisonOperator) Context 

func (r ComparisonOperator) Context() string

Context returns the contextual label associated with instances of this type as a string value.

func (ComparisonOperator) String 

func (r ComparisonOperator) String() (op string)

String is a stringer method that returns the string representation of the receiver instance.

type Condition 

type Condition struct {
	// contains filtered or unexported fields
}

Condition describes a single evaluative statement, i.e.: 

       op
       |
       v
person = "Jesse"
   ^         ^
   |         |
   kw        ex

The keyword (kw) shall always represent an abstract user-defined string construct against which the expression value (ex) is to be evaluated in some manner.

The disposition of the evaluation is expressed through one (1) of several ComparisonOperator (op) instances made available through this package:

• Eq, or "equal to" (=)

• Ne, or "not equal to" (!=) !! USE WITH CAUTION !!

• Lt, or "less than" (<)

• Le, or "less than or equal" (<=)

• Gt, or "greater than" (>)

• Ge, or "greater than or equal" (>=)

... OR through a user-defined operator that conforms to the package defined Operator interface.

By default, permitted expression (ex) values must honor these guidelines:

• Must be a non-zero string, OR ...

• Must be a valid instance of Stack (or an *alias* of Stack that is convertible back to the Stack type), OR ...

• Must be a valid instance of any type that exports a stringer method (String()) intended to produce the Condition's final expression string representation

However when a PushPolicy function or method is added to an instance of this type, greater control is afforded to the user in terms of what values will be accepted, as well as the quality or state of such values.

Example (Basic) 
c := Cond(`person`, Eq, `Jesse`).Paren().Encap(`"`).NoPadding()
fmt.Printf("%s", c)

Output:

(person="Jesse")
Example (StepByStep) 
var c Condition
c.Paren()
c.SetKeyword(`myKeyword`)
c.SetOperator(Eq)
c.SetExpression(`value123`)

fmt.Printf("%s", c)

Output:

( myKeyword = value123 )

func Cond 

func Cond(kw any, op Operator, ex any) *Condition

Cond returns an instance of *Condition bearing the provided component values.

func (Condition) CanNest 

func (r Condition) CanNest() bool

CanNest returns a Boolean value indicative of whether the no-nesting bit is unset, thereby allowing a Stack or Stack type alias instance to be set as the value.

See also the IsNesting method.

func (Condition) Category 

func (r Condition) Category() string

Category returns the categorical label string value assigned to the receiver, if set, else a zero string.

func (*Condition) Encap 

func (r *Condition) Encap(x ...any) *Condition

Encap accepts input characters for use in controlled condition value encapsulation. Acceptable input types are:

• string - a single string value will be used for both L and R encapsulation.

• string slices - An instance of []string with two (2) values will be used for L and R encapsulation using the first and second slice values respectively. An instance of []string with only one (1) value is identical to providing a single string value, in that both L and R will use one value.

func (Condition) Evaluate 

func (r Condition) Evaluate(x ...any) error

Evaluate uses the Evaluator closure function to apply the value (x) to the receiver in order to conduct a matching/assertion test or analysis for some reason. This is entirely up to the user.

A Boolean value returned indicative of the result. Note that if an instance of Evaluator was not assigned to the Condition prior to execution of this method, the return value shall always be false.

func (Condition) Expression 

func (r Condition) Expression() any

Expression returns the expression value(s) stored within the receiver, or nil if unset. A valid receiver instance MUST always possess a non-nil expression value.

func (Condition) ID 

func (r Condition) ID() string

Name returns the name of the receiver instance, if set, else a zero string will be returned. The presence or lack of a name has no effect on any of the receiver's mechanics, and is strictly for convenience.

func (Condition) IsEncap 

func (r Condition) IsEncap() bool

IsEncap returns a Boolean value indicative of whether value encapsulation characters have been set within the receiver.

func (Condition) IsNesting 

func (r Condition) IsNesting() bool

IsNesting returns a Boolean value indicative of whether the underlying expression value is either a Stack or Stack type alias. If true, this indicates the expression value descends into another hierarchical (nested) context.

func (Condition) IsPadded 

func (r Condition) IsPadded() bool

IsPadded returns a Boolean value indicative of whether the receiver pads its contents with a SPACE char (ASCII #32).

func (Condition) IsParen 

func (r Condition) IsParen() bool

IsParen returns a Boolean value indicative of whether the receiver is parenthetical.

func (*Condition) IsZero 

func (r *Condition) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or unset.

func (Condition) Keyword 

func (r Condition) Keyword() string

Keyword returns the Keyword interface type instance found within the receiver.

func (*Condition) NoNesting 

func (r *Condition) NoNesting(state ...bool) *Condition

NoNesting sets the no-nesting bit within the receiver. If set to true, the receiver shall ignore any Stack or Stack type alias instance when assigned using the SetExpression method. In such a case, only primitives, etc., shall be honored during the SetExpression operation.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the nesting bit (i.e.: true->false and false->true)

func (*Condition) NoPadding 

func (r *Condition) NoPadding(state ...bool) *Condition

NoPadding sets the no-space-padding bit within the receiver. String values within the receiver shall not be padded using a single space character (ASCII #32).

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the quotation bit (i.e.: true->false and false->true)

func (Condition) Operator 

func (r Condition) Operator() Operator

Operator returns the Operator interface type instance found within the receiver.

func (*Condition) Paren 

func (r *Condition) Paren(state ...bool) *Condition

Paren sets the string-encapsulation bit for parenthetical expression within the receiver. The receiver shall undergo parenthetical encapsulation ( (...) ) during the string representation process. Individual string values shall not be encapsulated in parenthesis, only the whole (current) stack.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the encapsulation bit (i.e.: true->false and false->true)

func (*Condition) SetCategory 

func (r *Condition) SetCategory(cat string) *Condition

SetCategory assigns the provided string to the receiver internal category value. This allows for a means of identifying a particular kind of Condition in the midst of many.

func (*Condition) SetEvaluator 

func (r *Condition) SetEvaluator(x Evaluator) *Condition

SetEvaluator assigns the instance of Evaluator to the receiver. This will allow the Evaluate method to return a more meaningful result.

Specifying nil shall disable this capability if enabled.

func (*Condition) SetExpression 

func (r *Condition) SetExpression(ex any) *Condition

SetExpression sets the receiver's expression value(s) using the specified ex input argument.

func (*Condition) SetID 

func (r *Condition) SetID(n string) *Condition

SetID assigns the provided string value (or lack thereof) to the receiver. This is optional, and is usually only needed in complex Condition structures in which "labeling" certain components may be advantageous. It has no effect on an evaluation, nor should a name ever cause a validity check to fail.

func (*Condition) SetKeyword 

func (r *Condition) SetKeyword(kw any) *Condition

SetKeyword sets the receiver's keyword using the specified kw input argument.

func (*Condition) SetOperator 

func (r *Condition) SetOperator(op Operator) *Condition

SetOperator sets the receiver's comparison operator using the specified Operator-qualifying input argument (op).

func (*Condition) SetPresentationPolicy 

func (r *Condition) SetPresentationPolicy(x PresentationPolicy) *Condition

SetPresentationPolicy assigns the instance of PresentationPolicy to the receiver. This will allow the user to leverage their own "stringer" method for automatic use when this type's String method is called.

Specifying nil shall disable this capability if enabled.

func (*Condition) SetPushPolicy 

func (r *Condition) SetPushPolicy(x PushPolicy) *Condition

SetPushPolicy assigns the instance of PushPolicy to the receiver. This will allow the Set method to control what elements may (or may not) be set as the expression value within the receiver.

See the documentation for the Set method for information on the default behavior without the involvement of a PushPolicy instance.

Specifying nil shall disable this capability if enabled.

func (*Condition) SetValidityPolicy 

func (r *Condition) SetValidityPolicy(x ValidityPolicy) *Condition

SetValidityPolicy assigns the instance of ValidityPolicy to the receiver. This will allow the Valid method to return a more meaningful result.

Specifying nil shall disable this capability if enabled.

func (Condition) String 

func (r Condition) String() string

String is a stringer method that returns the string representation of the receiver instance. It will only function if the receiver is in good standing, and passes validity checks.

func (Condition) Valid 

func (r Condition) Valid() (err error)

Valid returns an instance of error, identifying any issues perceived with the state of the receiver.

If a ValidityPolicy was set within the receiver, it shall be executed here. If no ValidityPolicy was specified, only a nilness is checked

type Evaluator 

type Evaluator func(Condition, ...any) error

Evaluator is a first-class function signature type which may be leveraged by users in order to compose matching functions by which a given Condition shall be measured/compared, etc.

In other words, this type takes this package one step forward: it no longer merely creates various expressions in the abstract sense -- now it will actually *apply* them to real values, or to gauge their verisimilitude in some other manner. The catch is that the user will need to author the needed functions in order to make such determinations practical.

Use of this feature is totally optional, and may be overkill for most users.

type Message 

type Message struct {
	ID   string    `json:"id"`
	Msg  string    `json:"message"`
	Tag  string    `json:"message_tag"`
	Type string    `json:"message_type"`
	Addr string    `json:"memory_address"`
	Len  int       `json:"current_length"`
	Cap  int       `json:"maximum_length,omitempty"` // omit if zero, meaning no cap was set.
	Time time.Time `json:"current_time"`
}

Message is an optional type for use when a user-supplied Message channel has been initialized and provided to one (1) or more Stack or Condition instances.

Instances of this type shall contain diagnostic, error and debug information pertaining to current operations of the given Stack or Condition instance.

func (Message) String 

func (r Message) String() string

String is a stringer method that returns the string representation of the receiver instance.

func (Message) Valid 

func (r Message) Valid() bool

Valid returns a Boolean value indicative of whether the receiver is perceived to be valid.

type Operator 

type Operator interface {
	// String should return the preferred string
	// representation of the Operator instance.
	// This is ultimately the value that shall be
	// used during the string representation of
	// the instance of Condition to which the
	// Operator is assigned. Generally, this will
	// be something short and succinct (e.g.: `~=`)
	// but can conceivably be anything you want.
	String() string

	// Context returns the string representation
	// of the context behind the operator. As an
	// example, the Context for an instance of
	// ComparisonOperator is `comparison`. Users
	// should choose intuitive, helpful context
	// names for custom types when defining them.
	Context() string
}

Operator is an interface type that allows user-defined operators to be used within instances of Condition. In rare cases, users may wish to utilize operators that go beyond the package provided ComparisonOperator definitions (or just represent the same operators in a different way). Defining types that conform to the signature of this interface type allows just that.

type PresentationPolicy 

type PresentationPolicy func(any) string

PresentationPolicy is a first-class (closure) function signature that may be leveraged by users in order to better control value presentation during the string representation process. Essentially, one may write their own "stringer" (String()) function or method and use it to override the default behavior of the package based String method(s).

Note that basic Stack instances are ineligible for the process of string representation, thus no PresentationPolicy may be set.

type PushPolicy 

type PushPolicy func(any) error

PushPolicy is a first-class (closure) function signature that may be leveraged by users in order to control what types instances may be pushed into a Stack instance when using its 'Push' method.

When authoring functions or methods that conform to this signature, the idea is to return true for any value that should be pushed, and false for all others. This allows for an opportunity to interdict potentially undesirable Stack additions, unsupported types, etc.

A PushPolicy function or method is executed for each element being added to a Stack via its Push method.

type Stack 

type Stack struct {
	// contains filtered or unexported fields
}

Stack embeds slices of any ([]any) in pointer form and extends methods allowing convenient interaction with stack structures.

func And 

func And(capacity ...int) Stack

And initializes and returns a new instance of Stack configured as a Boolean ANDed stack.

Example (SymbolicAnd)

This example demonstrates ANDed stack values using the double ampersand (&&) symbol. 

and := And().
	Paren().                                       // Add parenthesis
	Symbol(`&&`).                                  // Use double pipes for OR
	Push(`condition1`, `condition2`, `condition3`) // Push these values now

fmt.Printf("%s\n", and)

Output:

( condition1 && condition2 && condition3 )

func Basic 

func Basic(capacity ...int) Stack

Basic initializes and returns a new instance of Stack, set for basic operation only.

Please note that instances of this design are not eligible for string representation, value encaps, delimitation, and other presentation-related string methods. As such, a zero string (“) shall be returned should String() be executed.

PresentationPolicy instances cannot be assigned to Stacks of this design.

Example

This example demonstrates the creation of a basic stack and a call to its first (0th) index. Type assertion is performed to reveal a float64 instance. 

b := Basic()
b.Push(
	float64(3.14159),
	float64(-9.378),
)
idx, _ := b.Index(0)       // call index
assert, _ := idx.(float64) // type assert to float64
fmt.Printf("%.02f", assert)

Output:

3.14
Example (SetAsReadOnly)

This example demonstrates the creation of a basic stack with (and without) read-only controls enabled. 

b := Basic()
b.Push(
	float64(3.14159),
	float64(-9.378),
)
b.ReadOnly() // set readonly
b.Remove(1)  // this ought to fail ...
//b.Pop()	 // alternative to b.Remove(1) in this case
first := b.Len() // record len

b.ReadOnly()      // unset readonly
b.Remove(1)       // retry removal
second := b.Len() // record len again

fmt.Printf("first try: %d vs. second try: %d", first, second)

Output:

first try: 2 vs. second try: 1
Example (WithCapacity)

This example demonstrates the creation of a basic stack and an enforced capacity constraint. 

b := Basic(2)
b.Push(
	float64(3.14159),
	float64(-9.378),
	float64(139.104),
)
fmt.Printf("%d", b.Len())

Output:

2

func List 

func List(capacity ...int) Stack

List initializes and returns a new instance of Stack configured as a simple list. Stack instances of this design can be delimited using the SetDelimiter method.

func Not 

func Not(capacity ...int) Stack

Not initializes and returns a new instance of Stack configured as a Boolean NOTed stack.

func Or 

func Or(capacity ...int) Stack

Or initializes and returns a new instance of Stack configured as a Boolean ORed stack.

Example (SymbolicOr)

This example demonstrates ORed stack values using the double pipe (||) symbol and custom value encapsulation. 

or := Or().
	Paren().                                            // Add parenthesis
	Symbol(`||`).                                       // Use double pipes for OR
	Encap(` `, `"`).                                    // Encapsulate individual vals with double-quotes surrounded by spaces
	Push(`cn`, `sn`, `givenName`, `objectClass`, `uid`) // Push these values now

fmt.Printf("%s\n", or)

Output:

( "cn" || "sn" || "givenName" || "objectClass" || "uid" )

func (Stack) Avail 

func (r Stack) Avail() int

Avail returns the available number of slices as an integer value by subtracting the current length from a non-zero capacity.

If no capacity is set, this method returns minus one (-1), meaning infinite capacity is available.

If the receiver (r) is uninitialized, zero (0) is returned.

func (Stack) CanMutex 

func (r Stack) CanMutex() bool

CanMutex returns a Boolean value indicating whether the receiver instance has been equipped with mutual exclusion locking features.

This does NOT indicate whether the receiver is actually locked.

func (Stack) CanNest 

func (r Stack) CanNest() bool

CanNest returns a Boolean value indicative of whether the no-nesting bit is unset, thereby allowing the Push of Stack and/or Stack type alias instances.

See also the IsNesting method.

func (Stack) Cap 

func (r Stack) Cap() int

func (Stack) CapReached 

func (r Stack) CapReached() bool

CapReached returns a Boolean value indicative of whether the receiver has reached the maximum configured capacity.

func (Stack) Category 

func (r Stack) Category() string

Category returns the categorical label string value assigned to the receiver, if set, else a zero string.

func (Stack) Delimiter 

func (r Stack) Delimiter() string

Delimiter returns the delimiter string value currently set within the receiver instance.

Example

This example demonstrates the creation of a list stack using comma delimitation and the retrieval of the same delimiter value. 

// note: one could also use a rune
// e.g: ',' or rune(44) for comma.
L := List().SetDelimiter(`,`).Push(
	`item1`,
	`item2`,
)
fmt.Printf("%s", L.Delimiter())

Output:

,

func (Stack) Encap 

func (r Stack) Encap(x ...any) Stack

Encap accepts input characters for use in controlled stack value encapsulation. Acceptable input types are:

• string - a single string value will be used for both L and R encapsulation.

• string slices - An instance of []string with two (2) values will be used for L and R encapsulation using the first and second slice values respectively. An instance of []string with only one (1) value is identical to providing a single string value, in that both L and R will use one value.

func (Stack) Fold 

func (r Stack) Fold(state ...bool) Stack

Stack will fold the case of logical Boolean operators which are not represented through symbols. For example, `AND` becomes `and`, or vice versa. This won't have any effect on List-based receivers, or if symbols are used in place of said Boolean words.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the case-folding bit (i.e.: true->false and false->true)

func (Stack) ForwardIndices 

func (r Stack) ForwardIndices(state ...bool) Stack

ForwardIndices will enable forward index support when using the Index method extended by this type. See the method documentation for further details.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the forward indices bit (i.e.: true->false and false->true)

func (Stack) ID 

func (r Stack) ID() string

ID returns the assigned identifier string, if set, from within the underlying stack configuration.

func (Stack) Index 

func (r Stack) Index(idx int) (slice any, ok bool)

Index returns the Nth slice within the given receiver alongside the true index number and a Boolean value indicative of a successful call of a non-nil value.

This method supports the use of the following index values depending on the configuration of the receiver.

• Negatives: When negative index support is enabled, a negative index will not panic, rather the index number will be increased such that it becomes positive and within the bounds of the stack length, and (perhaps most importantly) aligned with the relative (intended) slice. To offer an example, -2 would return the second-to-last slice. When negative index support is NOT enabled, nil is returned for any index out of bounds along with a Boolean value of false, although no panic will occur.

• Positives: When forward index support is enabled, an index greater than the length of the stack shall be reduced to the highest valid slice index. For example, if an index of twenty (20) were used on a stack instance of a length of ten (10), the index would transform to nine (9). When forward index support is NOT enabled, nil is returned for any index out of bounds along with a Boolean value of false, although no panic will occur.

In any scenario, a valid index within the bounds of the stack's length returns the intended slice along with Boolean value of true.

func (Stack) Insert 

func (r Stack) Insert(x any, left int) bool

Insert will insert value x to become the left index. For example, using zero (0) as left shall result in value x becoming the first slice within the receiver.

This method returns a Boolean value indicative of success. A value of true indicates the receiver length became longer by one (1).

This method does not currently respond to forward/negative index support. An integer value less than or equal to zero (0) shall become zero (0). An integer value that exceeds the length of the receiver shall become index len-1. A value that falls within the bounds of the receiver's current length is inserted as intended.

func (Stack) IsEncap 

func (r Stack) IsEncap() bool

IsEncap returns a Boolean value indicative of whether value encapsulation characters have been set within the receiver.

func (Stack) IsInit 

func (r Stack) IsInit() bool

IsInit returns a Boolean value indicative of whether the receiver has been initialized.

func (Stack) IsNesting 

func (r Stack) IsNesting() bool

IsNesting returns a Boolean value indicative of whether at least one (1) slice member is either a Stack or Stack type alias. If true, this indicates the relevant slice descends into another hierarchical (nested) context.

func (Stack) IsPadded 

func (r Stack) IsPadded() bool

IsPadded returns a Boolean value indicative of whether the receiver pads its contents with a SPACE char (ASCII #32).

func (Stack) IsParen 

func (r Stack) IsParen() bool

IsParen returns a Boolean value indicative of whether the receiver is parenthetical.

func (Stack) IsReadOnly 

func (r Stack) IsReadOnly() bool

IsReadOnly returns a Boolean value indicative of whether the receiver is set as read-only.

func (Stack) IsZero 

func (r Stack) IsZero() bool

IsZero returns a Boolean value indicative of whether the receiver is nil, or uninitialized.

func (Stack) Kind 

func (r Stack) Kind() string

Kind returns the string name of the type of receiver configuration.

func (Stack) LeadOnce 

func (r Stack) LeadOnce(state ...bool) Stack

LeadOnce sets the lead-once bit within the receiver. This causes two (2) things to happen:

• Only use the configured operator once in a stack, and ...

• Only use said operator at the very beginning of the stack string value.

Execution without a Boolean input value will *TOGGLE* the current state of the lead-once bit (i.e.: true->false and false->true)

Example

This example demonstrates the LeadOnce feature, which limits a given Stack's logical operator usage to once-per, and only at the beginning (i.e.: the form of an LDAP Search Filter's operators when conditions are nested). 

maker := func(r Stack) Stack {
	return r.Paren().LeadOnce().NoPadding()
}

Ands := maker(And().Symbol('&'))
Ors := maker(Or().Symbol('|')).Push(
	Cond(`objectClass`, Eq, `engineeringLead`).NoPadding().Paren(), // OR condition #1
	Cond(`objectClass`, Eq, `shareholder`).NoPadding().Paren(),     // OR condition #1
)

// Begin filter at AND
filter := Ands.Push(
	Cond(`objectClass`, Eq, `employee`).NoPadding().Paren(), // AND condition #1
	Ors, // Begin OR (which is AND condition #2)
)

fmt.Printf("%s", filter)

Output:

(&(objectClass=employee)(|(objectClass=engineeringLead)(objectClass=shareholder)))

func (Stack) Len 

func (r Stack) Len() int

Len returns the integer length of the receiver.

func (Stack) Mutex 

func (r Stack) Mutex()

Mutex enables the receiver's mutual exclusion locking capabilities.

func (Stack) NegativeIndices 

func (r Stack) NegativeIndices(state ...bool) Stack

NegativeIndices will enable negative index support when using the Index method extended by this type. See the method documentation for further details.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the negative indices bit (i.e.: true->false and false->true)

func (Stack) NoNesting 

func (r Stack) NoNesting(state ...bool) Stack

NoNesting sets the no-nesting bit within the receiver. If set to true, the receiver shall ignore any Stack or Stack type alias instance when pushed using the Push method. In such a case, only primitives, Conditions, etc., shall be honored during the Push operation.

Note this will only have an effect when not using a custom PushPolicy. When using a custom PushPolicy, the user has total control -- and full responsibility -- in deciding what may or may not be pushed.

Also note that setting or unsetting this bit shall not, in any way, have an impact on pre-existing Stack or Stack type alias instances within the receiver. This bit only has an influence on the Push method and only when set to true.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the nesting bit (i.e.: true->false and false->true)

func (Stack) NoPadding 

func (r Stack) NoPadding(state ...bool) Stack

NoPadding sets the no-space-padding bit within the receiver. String values within the receiver shall not be padded using a single space character (ASCII #32).

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the padding bit (i.e.: true->false and false->true)

func (Stack) Paren 

func (r Stack) Paren(state ...bool) Stack

Paren sets the string-encapsulation bit for parenthetical expression within the receiver. The receiver shall undergo parenthetical encapsulation ( (...) ) during the string representation process. Individual string values shall not be encapsulated in parenthesis, only the whole (current) stack.

A Boolean input value explicitly sets the bit as intended. Execution without a Boolean input value will *TOGGLE* the current state of the encapsulation bit (i.e.: true->false and false->true)

func (Stack) Pop 

func (r Stack) Pop() (any, bool)

Pop removes and returns the final slice value from the receiver instance. A Boolean value is returned alongside, indicative of whether an actual slice value was found. Note that if the receiver is in an invalid state, or has a zero length, nothing will be removed, and a meaningless value of true will be returned alongside a nil slice value.

func (Stack) Push 

func (r Stack) Push(y ...any) Stack

Push appends the provided value(s) to the receiver, and returns the receiver in fluent form.

Note that if the receiver is in an invalid state, or if maximum capacity has been set and reached, each of the values intended for append shall be ignored.

func (Stack) ReadOnly 

func (r Stack) ReadOnly(state ...bool) Stack

ReadOnly sets the receiver bit 'ronly' to a positive state. This will prevent any writes to the receiver or its underlying configuration.

func (Stack) Remove 

func (r Stack) Remove(idx int) (slice any, ok bool)

Remove will remove and return the Nth slice from the index, along with a success-indicative Boolean value. A value of true indicates the receiver length became shorter by one (1).

func (Stack) Replace 

func (r Stack) Replace(x any, idx int) bool

Replace will overwrite slice idx using value x and returns a Boolean value indicative of success.

If slice i does not exist (e.g.: idx > receiver len), then nothing is altered and a false Boolean value is returned.

func (Stack) Reset 

func (r Stack) Reset()

Reset will silently iterate and delete each slice found within the receiver, leaving it unpopulated but still retaining its active configuration. Nothing is returned.

func (Stack) SetCategory 

func (r Stack) SetCategory(cat string) Stack

SetCategory assigns the provided string to the stack's internal category value. This allows for a means of identifying a particular kind of stack in the midst of many.

func (Stack) SetDelimiter 

func (r Stack) SetDelimiter(x any) Stack

SetDelimiter accepts input characters (as string, or a single rune) for use in controlled stack value joining when the underlying stack type is a LIST. In such a case, the input value shall be used for delimitation of all slice values during the string representation process.

A zero string, the NTBS (NULL) character -- ASCII #0 -- or nil, shall unset this value within the receiver.

If this method is executed using any other stack type, the operation has no effect. If using Boolean AND, OR or NOT stacks and a character delimiter is preferred over a Boolean WORD, see the Stack.Symbol method.

Example

This example demonstrates the creation of a list stack using comma delimitation. 

// note: one could also use a rune
// e.g: ',' or rune(44) for comma.
L := List().SetDelimiter(`,`).Push(
	`item1`,
	`item2`,
)
fmt.Printf("%s", L)

Output:

item1,item2

func (Stack) SetID 

func (r Stack) SetID(id string) Stack

SetID assigns the provided string to the stack's internal identifier value. This allows for a means of identifying a particular stack in the midst of many.

func (Stack) SetMessageChan 

func (r Stack) SetMessageChan(mchan chan Message) Stack

SetMessageChan assigns the provided Message channel instance to the receiver. Error and debug information will be sent to the channel in Message form. The user will need to listen on the channel and actually read messages.

func (Stack) SetPresentationPolicy 

func (r Stack) SetPresentationPolicy(ppol PresentationPolicy) Stack

SetPresentationPolicy assigns the provided PresentationPolicy closure function to the receiver, thereby enabling full control over the stringification of the receiver. Execution of this type's String() method will execute the provided policy instead of the package-provided routine.

func (Stack) SetPushPolicy 

func (r Stack) SetPushPolicy(ppol PushPolicy) Stack

SetPushPolicy assigns the provided PushPolicy closure function to the receiver, thereby enabling protection against undesired appends to the Stack. The provided function shall be executed by the Push method for each individual item being added.

func (Stack) SetValidityPolicy 

func (r Stack) SetValidityPolicy(vpol ValidityPolicy) Stack

SetValidityPolicy assigns the provided ValidityPolicy closure function instance to the receiver, thereby allowing users to introduce inline verification checks of a Stack to better gauge its validity. The provided function shall be executed by the Valid method.

func (Stack) String 

func (r Stack) String() string

String is a stringer method that returns the string representation of the receiver.

Note that invalid Stack instances, as well as basic Stacks, are not eligible for string representation.

func (Stack) Symbol 

func (r Stack) Symbol(c ...any) Stack

Symbol sets the provided symbol expression, which will be a sequence of any characters desired, to represent various Boolean operators without relying on words such as "AND". If a non-zero sequence of characters is set, they will be used to supplant the default word-based operators within the given stack in which the symbol is configured.

Acceptable input types are string and rune.

Execution of this method with no arguments empty the symbol store within the receiver, thereby returning to the default word-based behavior.

This method has no effect on list-style stacks.

func (Stack) Transfer 

func (r Stack) Transfer(dest Stack) bool

Transfer will iterate the receiver (r) and add all slices contained therein to the destination instance.

The following circumstances will result in a false return:

- Capacity constraints are in-force within the destination instance, and the transfer request (if larger than the sum number of available slices) cannot proceed as a result

- The destination instance is nil, or has not been properly initialized

- The receiver instance (r) contains no slices to transfer

The receiver instance (r) is not modified in any way as a result of calling this method. If the receiver undergoes a call to its Reset() method, only the receiver instance will be emptied, and the transferred slices within the submitted destination instance shall remain.

func (Stack) Traverse 

func (r Stack) Traverse(indices ...int) (slice any, ok bool)

Traverse will "walk" a structure of stack elements using the path indices provided. It returns the slice found at the final index, or nil, along with a success-indicative Boolean value.

The semantics of "traversability" are as follows:

• Any "nesting" instance must be a Stack or Stack type alias

• Condition instances must either be the final requested element, OR must contain a Stack or Stack type alias instance through which to continue the traversal process

• All other value types are returned as-is

If the traversal ended at any given value, it will be returned along with a positive ok value letting the user know they arrived at the coordinates they defined and that "something" was found.

If, however, any path elements remained and further traversal was NOT possible, the last slice is returned but ok is not set positive, thereby letting the user know they took a wrong turn somewhere.

As the return type is any, the slice value must be manually type asserted.

Example

This example demonstrates traversing a Stack instance containing Condition slice instances. We use a path sequence of []int{1, 1} to target slice #1 on the first level, and value #1 of the second level. 

// An optional Stack "maker" for configuring
// a specific kind of Stack. Just looks neater
// than doing fluent execs over and over ...
sMaker := func(r Stack) Stack {
	// encapsulate in parens, use symbol rune
	// for logical operators only once, and
	// use no padding between kw, op and value
	return r.Paren().LeadOnce().NoPadding()
}

// An optional Condition "maker", same logic
// as above ...
cMaker := func(r *Condition) *Condition {
	// encapsulate in parens, no padding between
	// kw, op and value ...
	return r.Paren().NoPadding()
}

// Let's make a faux LDAP Search Filter ...
//
// This will be our top level, which is an AND
Ands := sMaker(And().Symbol('&'))

// This will be our second level Stack, which
// is an OR containing a couple of Condition
// instances in Equality form.
Ors := sMaker(Or().Symbol('|')).Push(
	cMaker(Cond(`objectClass`, Eq, `engineeringLead`)), // OR condition #1
	cMaker(Cond(`objectClass`, Eq, `shareholder`)),     // OR condition #2 // **our traversal target**
)

// Begin filter at AND, and push our
// desired elements into the Stack.
filter := Ands.Push(
	cMaker(Cond(`objectClass`, Eq, `employee`)), // AND condition #1
	Ors, // Begin OR (which is AND's condition #2)
)

// Bool returns shadowed only for brevity.
// Generally you should not do that ...
slice, _ := filter.Traverse(1, 1)   // Enter coordinates
condAssert, _ := slice.(*Condition) // The return is any, so assert to what we expect
fmt.Printf("%s", condAssert)        // use its String method automagically

Output:

(objectClass=shareholder)

func (Stack) Valid 

func (r Stack) Valid() (err error)

Valid returns an error if the receiver lacks a configuration value, or is unset as a whole.

type ValidityPolicy 

type ValidityPolicy func(any) error

ValidityPolicy is a first-class (closure) function signature that may be leveraged by users in order to better gauge the validity of a stack based on its configuration and/or values.

A ValidityPolicy function or method is executed via the Stack method Valid.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.