tribool

package module
v0.0.0-...-0ec0f00 Latest Latest
Warning

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

 Go to latest Published: Dec 8, 2019 License: Apache-2.0 Imports: 2 Imported by: 1

README

tribool - a little golang library

Package tribool implements a tri-state boolean where the extra state is indeterminate.

Getting started

To get the package, execute:

go get gopkg.in/grignaak/tribool.v1

To import this package, add the following line to your code:

import "gopkg.in/grignaak/tribool.v1"

Refer to it as tribool.

For more details, see the API documentation

Maybe

A tri-state boolean has the values False, True, and Maybe. Maybe represents a value that is either true or false but it is inderminate which it is. For example, you don't know if an http POST was successful if the connection is dropped after the request was made but before the response came back. This can be modeled with the indeterminate Maybe value.

Tribool provides tri-state logical operators that act like their boolean counterparts. The logic tables are documented below.

Parsing

The tribool package is especially useful for parsing flags that may need a default value. For example:

var x string // from somehere
var flag bool = tribool.FromString(x).WithMaybeAsFalse()

Parsing is case insensitive. The following table shows what will be parsed to true and false values, anything else (including the empty string) results in the indeterminate value.

case insensitive | result
-----------------+-------
               t | Yes
               y | Yes
               1 | Yes
              on | Yes
             yes | Yes
            true | Yes
               f | No
               n | No
               0 | No
              no | No
             off | No
           false | No
 <anything else> | Maybe

Truth Tables

Tribool supports the following binary operations:

	    |  and      or       nand        nor      xor    iff   implies 
	    | a ∧ b   a ∨ b   ¬(a ∧ b)   ¬(a ∨ b)   a ⊕ b  a ⇔ b  a ⇒ b    
	a b | b ∧ a   b ∨ a   ¬(b ∧ a)   ¬(b ∨ a)   b ⊕ a  b ⇔ a    —      
	----+-----------------------------------------------------------------
	N N |   N       N          Y          Y        N       Y      Y    
	N ? |   N       ?          Y          ?        ?       ?      Y    
	N Y |   N       Y          Y          N        Y       N      Y    
	? N |   N       ?          Y          ?        ?       ?      ?    
	? ? |   ?       ?          ?          ?        ?       ?      ?    
	? Y |   ?       Y          ?          N        ?       ?      Y    
	Y N |   N       Y          Y          N        Y       N      N    
	Y ? |   ?       Y          ?          N        ?       ?      ?    
	Y Y |   Y       Y          N          N        N       Y      Y

Tribool supports the following unary operations:

	a | not   upgrade    downgrade
	--+----------------------------
	N |  Y       N          N
	? |  ?       Y          N
	Y |  N       Y          Y

Documentation

Overview

Package tribool implements a tri-state boolean where the extra state is indeterminate.

Maybe

A tri-state boolean has the values False, True, and Maybe. Maybe represents a value that is neither true or false but it is inderminate. For example, you don't know if an http POST was successful if the connection is dropped after the request was made but before the response came back. This can be modeled with the indeterminate Maybe value.

Tribool provides tri-state logical operators that act like their boolean counterparts. The logic tables are documented below and on each method. There are also methods for mixed Tribool and bool operations.

Parsing

The tribool package is especially useful for parsing flags that may need a default value. For example: 

var x string // from somehere
var flag bool = tribool.FromString(x).WithMaybeAsFalse()

Parsing is case insensitive. The following table shows what will be parsed to true and false values, anything else (including the empty string) results in the indeterminate value. 

case insensitive | result
-----------------+-------
               t | Yes
               y | Yes
               1 | Yes
              on | Yes
             yes | Yes
            true | Yes
               f | No
               n | No
               0 | No
              no | No
             off | No
           false | No
 <anything else> | Maybe

Truth Tables

Tribool supports the following binary operations: 

    |  and      or       nand        nor      xor    iff   implies
    | a ∧ b   a ∨ b   ¬(a ∧ b)   ¬(a ∨ b)   a ⊕ b  a ⇔ b  a ⇒ b
a b | b ∧ a   b ∨ a   ¬(b ∧ a)   ¬(b ∨ a)   b ⊕ a  b ⇔ a    —
----+-----------------------------------------------------------------
N N |   N       N          Y          Y        N       Y      Y
N ? |   N       ?          Y          ?        ?       ?      Y
N Y |   N       Y          Y          N        Y       N      Y
? N |   N       ?          Y          ?        ?       ?      ?
? ? |   ?       ?          ?          ?        ?       ?      ?
? Y |   ?       Y          ?          N        ?       ?      Y
Y N |   N       Y          Y          N        Y       N      N
Y ? |   ?       Y          ?          N        ?       ?      ?
Y Y |   Y       Y          N          N        N       Y      Y

Tribool supports the following unary operations: 

a | not   upgrade    downgrade
--+----------------------------
N |  Y       N          N
? |  ?       Y          N
Y |  N       Y          Y

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Tribool 

type Tribool int

Tribool is a tri-state boolean where the extra state is indeterminate.

The default value for a Tribool is False, just like a boolean.

Example 
var u User // initialized elsewhere

// The user may not have given their age.
canVote1 := u.isOlderThan(18).
	OrBool(u.isDev()).
	AndBool(!u.isContestJudge()).
	WithMaybeAsFalse()

canVote2 :=
	(u.isOlderThan(18).WithMaybeAsFalse() || u.isDev()) &&
		!u.isContestJudge()

fmt.Println(canVote1, canVote2)
Example (Other) 
var n Node // initialized elsewhere

// Don't know if a node is activated or not
ok1 := Maybe.
	And(n.IsActive.ImplyBool(n.ID >= 0)).
	And(n.IsActive.Not().ImplyBool(n.ID == -1)).
	WithMaybeAsTrue()

ok2 := Maybe.
	Or(n.IsActive.AndBool(n.ID >= 0)).
	Or(n.IsActive.Not().AndBool(n.ID == -1)).
	WithMaybeAsTrue()

fmt.Println(ok1, ok2)
Example (Parsing) 
fmt.Println(
	FromString("true"),
	FromString("false"),

	FromString("yes"),
	FromString("no"),

	FromString("on"),
	FromString("off"),

	FromString("1"),
	FromString("0"),

	FromString("y"),
	FromString("n"),

	FromString(""),
	FromString("huh?"),
)

fmt.Println(
	FromString("true").WithMaybeAsTrue(),
	FromString("false").WithMaybeAsTrue(),
	FromString("").WithMaybeAsTrue(),
)

Output:
yes no yes no yes no yes no yes no maybe maybe
true false true

const (

	// No is equivalent to boolean false
	No Tribool = no

	// False is equivalent to boolean false
	False

	// Off is equivalent to boolean false
	Off
)
const (

	// Maybe represents a value either true or false, but don't know which.
	Maybe Tribool = maybe

	// Perhaps is a synonym for Maybe
	Perhaps

	// Indeterminate is a synonym for Maybe
	Indeterminate
)
const (

	// Yes is equivalent to boolean true
	Yes Tribool = yes

	// True is equivalent to boolean true
	True

	// On is equivalent to boolean true
	On
)

func FromBool 

func FromBool(b bool) Tribool

FromBool converts a bool to an equivalent Tribool.

func FromString 

func FromString(s string) Tribool

FromString converts a string to a Tribool. 

case insensitive | result
-----------------+-------
               t | Yes
               y | Yes
               1 | Yes
              on | Yes
             yes | Yes
            true | Yes
               f | No
               n | No
               0 | No
              no | No
             off | No
           false | No
 <anything else> | Maybe

func (Tribool) And 

func (a Tribool) And(b Tribool) Tribool

And implements logical and. 

    | a.And(b)
a b | b.And(a)
----+---------
N N | N
N ? | N
N Y | N
? N | N
? ? | ?
? Y | ?
Y N | N
Y ? | ?
Y Y | Y

func (Tribool) AndBool 

func (a Tribool) AndBool(b bool) Tribool

AndBool is equivalent to a.And(FromBool(b))

func (Tribool) Equiv 

func (a Tribool) Equiv(b Tribool) Tribool

Equiv implements logical equivalence. 

    | a.Equiv(b)
a b | b.Equiv(a)
----+------
N N | Y
N ? | ?
N Y | N
? N | ?
? ? | ?
? Y | ?
Y N | N
Y ? | ?
Y Y | Y

func (Tribool) EquivBool 

func (a Tribool) EquivBool(b bool) Tribool

EquivBool is equivalent to a.Equiv(FromBool(b))

func (Tribool) Imply 

func (a Tribool) Imply(b Tribool) Tribool

Imply implements logical implication.

Implication is not reflexive. That is a.Imply(b) is not the same as b.Imply(a) 

a b | a.Imply(b)
----+------------
N N | Y
N ? | Y
N Y | Y
? N | ?
? ? | ?
? Y | Y
Y N | N
Y ? | ?
Y Y | Y

func (Tribool) ImplyBool 

func (a Tribool) ImplyBool(b bool) Tribool

ImplyBool is equivalent to a.Imply(FromBool(b))

func (Tribool) MarshalJSON 

func (a Tribool) MarshalJSON() ([]byte, error)

MarshalJSON marshals tribools to strings, using the Tribool.String() method.

func (Tribool) Nand 

func (a Tribool) Nand(b Tribool) Tribool

Nand implements logical nand. 

    | a.Nand(b)
a b | b.Nand(a)
----+----------
N N | Y
N ? | Y
N Y | Y
? N | Y
? ? | ?
? Y | ?
Y N | Y
Y ? | ?
Y Y | N

func (Tribool) NandBool 

func (a Tribool) NandBool(b bool) Tribool

NandBool is equivalent to a.Nand(FromBool(b))

func (Tribool) Nor 

func (a Tribool) Nor(b Tribool) Tribool

Nor implements logical nor. 

    | a.Nor(b)
a b | b.Nor(a)
----+------------
N N | Y
N ? | ?
N Y | N
? N | ?
? ? | ?
? Y | N
Y N | N
Y ? | N
Y Y | N

func (Tribool) NorBool 

func (a Tribool) NorBool(b bool) Tribool

NorBool is equivalent to a.Nor(FromBool(b))

func (Tribool) Not 

func (a Tribool) Not() Tribool

Not implements logical not. 

a | a.Not()
--+--------
N | Y
? | ?
Y | N

func (Tribool) Or 

func (a Tribool) Or(b Tribool) Tribool

Or implements logical inclusive-or. 

    | a.Or(b)
a b | b.Or(a)
----+----------
N N | N
N ? | ?
N Y | Y
? N | ?
? ? | ?
? Y | Y
Y N | Y
Y ? | Y
Y Y | Y

func (Tribool) OrBool 

func (a Tribool) OrBool(b bool) Tribool

OrBool is equivalent to a.Or(FromBool(b))

func (Tribool) String 

func (a Tribool) String() string

String converts a Tribool to a string that can be parsed with FromString

func (*Tribool) UnmarshalJSON 

func (a *Tribool) UnmarshalJSON(data []byte) error

UnmarshalJSON supports unmarshalling from a json string (using `FromString()`), a json boolean (using `FromBool()`), and treats anything else as `maybe`.

func (Tribool) WithMaybeAsFalse 

func (a Tribool) WithMaybeAsFalse() bool

WithMaybeAsFalse converts the Tribool to a boolean by coercing Maybe to false. 

a | a.WithMaybeAsFalse()
--+----------------------
N | N
? | N
Y | Y

func (Tribool) WithMaybeAsTrue 

func (a Tribool) WithMaybeAsTrue() bool

WithMaybeAsTrue converts the Tribool to a boolean by coercing Maybe to true. 

a | a.WithMaybeAsTrue()
--+----------------------
N | N
? | Y
Y | Y

func (Tribool) Xor 

func (a Tribool) Xor(b Tribool) Tribool

Xor implements logical exclusive-or. 

    | a.Xor(b)
a b | b.Xor(a)
----+---------
N N | N
N ? | ?
N Y | Y
? N | ?
? ? | ?
? Y | ?
Y N | Y
Y ? | ?
Y Y | N

func (Tribool) XorBool 

func (a Tribool) XorBool(b bool) Tribool

XorBool is equivalent to a.Xor(FromBool(b))

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.