src.elv.sh – src.elv.sh/pkg/eval/vals Index | Files

package vals

import "src.elv.sh/pkg/eval/vals"

Package vals contains basic facilities for manipulating values used in the Elvish runtime.

Index

Variables 

var EmptyList = vector.Empty

EmptyList is an empty list. 

var EmptyMap = hashmap.New(Equal, Hash)

EmptyMap is an empty map. 

var ErrConcatNotImplemented = errors.New("concat not implemented")

ErrConcatNotImplemented is a special error value used to signal that concatenation is not implemented. See Concat for how it is used.

Functions

func Assoc 

func Assoc(a, k, v any) (any, error)

Assoc takes a container, a key and value, and returns a modified version of the container, in which the key associated with the value. It is implemented for the builtin type string, List and Map types, StructMap types, and types satisfying the Assocer interface. For other types, it returns an error.

func Bool 

func Bool(v any) bool

Bool converts a value to bool. It is implemented for nil, the builtin bool type, and types implementing the Booler interface. For all other values, it returns true.

func CanIterate 

func CanIterate(v any) bool

CanIterate returns whether the value can be iterated. If CanIterate(v) is true, calling Iterate(v, f) will not result in an error.

func Collect 

func Collect(it any) ([]any, error)

Collect collects all elements of an iterable value into a slice.

func Concat 

func Concat(lhs, rhs any) (any, error)

Concat concatenates two values. If both operands are strings, it returns lhs + rhs, nil. If the left operand implements Concatter, it calls lhs.Concat(rhs). If lhs doesn't implement the interface or returned ErrConcatNotImplemented, it then calls rhs.RConcat(lhs). If all attempts fail, it returns nil and an error.

func ConvertToFloat64 

func ConvertToFloat64(num Num) float64

ConvertToFloat64 converts any number to float64. It panics if num is not a number value.

func Dissoc 

func Dissoc(a, k any) any

Dissoc takes a container and a key, and returns a modified version of the container, with the given key dissociated with any value. It is implemented for the Map type and types satisfying the Dissocer interface. For other types, it returns nil.

func Equal 

func Equal(x, y any) bool

Equal returns whether two values are equal. It is implemented for the builtin types bool and string, the File, List, Map types, StructMap types, and types satisfying the Equaler interface. For other types, it uses reflect.DeepEqual to compare the two values.

func Feed 

func Feed(f func(any) bool, values ...any)

Feed calls the function with given values, breaking earlier if the function returns false.

func FromGo 

func FromGo(a any) any

FromGo converts a Go value to an Elvish value.

Exact numbers are normalized to the smallest types that can hold them, and runes are converted to strings. Values of other types are returned unchanged.

func HasKey 

func HasKey(container, key any) bool

HasKey returns whether a container has a key. It is implemented for the Map type, StructMap types, and types satisfying the HasKeyer interface. It falls back to iterating keys using IterateKeys, and if that fails, it falls back to calling Len and checking if key is a valid numeric or slice index. Otherwise it returns false.

func Hash 

func Hash(v any) uint32

Hash returns the 32-bit hash of a value. It is implemented for the builtin types bool and string, the File, List, Map types, StructMap types, and types satisfying the Hasher interface. For other values, it returns 0 (which is OK in terms of correctness).

func Index 

func Index(a, k any) (any, error)

Index indexes a value with the given key. It is implemented for the builtin type string, *os.File, List, StructMap and PseudoStructMap types, and types satisfying the ErrIndexer or Indexer interface (the Map type satisfies Indexer). For other types, it returns a nil value and a non-nil error.

func Iterate 

func Iterate(v any, f func(any) bool) error

Iterate iterates the supplied value, and calls the supplied function in each of its elements. The function can return false to break the iteration. It is implemented for the builtin type string, the List type, and types satisfying the Iterator interface. For these types, it always returns a nil error. For other types, it doesn't do anything and returns an error.

func IterateKeys 

func IterateKeys(v any, f func(any) bool) error

IterateKeys iterates the keys of the supplied value, calling the supplied function for each key. The function can return false to break the iteration. It is implemented for the Map type, StructMap types, and types satisfying the IterateKeyser interface. For these types, it always returns a nil error. For other types, it doesn't do anything and returns an error.

func Kind 

func Kind(v any) string

Kind returns the "kind" of the value, a concept similar to type but not yet very well defined. It is implemented for the builtin nil, bool and string, the File, List, Map types, StructMap types, and types satisfying the Kinder interface. For other types, it returns the Go type name of the argument preceded by "!!".

TODO: Decide what `kind-of` should report for an external command object and document the rationale for the choice in the doc string for `func (ExternalCmd) Kind()` as well as user facing documentation. It's not obvious why this returns "fn" rather than "external" for that case.

func Len 

func Len(v any) int

Len returns the length of the value, or -1 if the value does not have a well-defined length. It is implemented for the builtin type string, StructMap types, and types satisfying the Lener interface. For other types, it returns -1.

func MakeList 

func MakeList(vs ...any) vector.Vector

MakeList creates a new List from values.

func MakeListSlice 

func MakeListSlice[T any](vs []T) vector.Vector

MakeListSlice creates a new List from a slice.

func MakeMap 

func MakeMap(a ...any) hashmap.Map

MakeMap creates a map from arguments that are alternately keys and values. It panics if the number of arguments is odd.

func NoSuchKey 

func NoSuchKey(k any) error

NoSuchKey returns an error indicating that a key is not found in a map-like value.

func Optional 

func Optional(ptr any) any

Optional wraps the last pointer passed to ScanListElementsToGo, to indicate that it is optional.

func PromoteToBigInt 

func PromoteToBigInt(n Num) *big.Int

PromoteToBigInt converts an int or *big.Int to a *big.Int. It panics if n is any other type.

func PromoteToBigRat 

func PromoteToBigRat(n Num) *big.Rat

PromoteToBigRat converts an int, *big.Int or *big.Rat to a *big.Rat. It panics if n is any other type.

func Repr 

func Repr(v any, indent int) string

Repr returns the representation for a value, a string that is preferably (but not necessarily) an Elvish expression that evaluates to the argument. The representation is pretty-printed, using indent as the initial level of indentation. It is implemented for the builtin types nil, bool and string, the File, List and Map types, StructMap types, and types satisfying the Reprer interface. For other types, it uses fmt.Sprint with the format "<unknown %v>".

func ReprPlain 

func ReprPlain(v any) string

ReprPlain is like Repr, but without pretty-printing.

func ScanListElementsToGo 

func ScanListElementsToGo(src List, ptrs ...any) error

ScanListElementsToGo unpacks elements from a list, storing the each element in the given pointers with ScanToGo.

The last pointer may be wrapped with Optional to indicate that it is optional.

func ScanListToGo 

func ScanListToGo(src List, ptr any) error

ScanListToGo converts a List to a slice, using ScanToGo to convert each element.

func ScanMapToGo 

func ScanMapToGo(src Map, ptr any) error

ScanMapToGo scans map elements into ptr, which must be a pointer to a struct. Struct field names are converted to map keys with CamelToDashed.

The map may contains keys that don't correspond to struct fields, and it doesn't have to contain all keys that correspond to struct fields.

func ScanToGo 

func ScanToGo(src any, ptr any) error

ScanToGo converts an Elvish value, and stores it in the destination of ptr, which must be a pointer.

If ptr has type *int, *float64, *Num or *rune, it performs a suitable conversion, and returns an error if the conversion fails. In other cases, this function just tries to perform "*ptr = src" via reflection and returns an error if the assignment can't be done.

func StructFieldsInfo 

func StructFieldsInfo(t reflect.Type) ([]string, map[string]int)

StructFieldsInfo takes a type for a struct, and returns a slice for each field name, converted with CamelToDashed, and a reverse index. Unexported fields result in an empty string in the slice, and is omitted from the reverse index.

func ToString 

func ToString(v any) string

ToString converts a Value to string. It is implemented for the builtin float64 and string types, and type satisfying the Stringer interface. It falls back to Repr(v).

func TypeOf 

func TypeOf(i any) reflect.Type

TypeOf is like reflect.TypeOf, except that when given an argument of nil, it does not return nil, but the Type for the empty interface.

func ValueOf 

func ValueOf(i any) reflect.Value

ValueOf is like reflect.ValueOf, except that when given an argument of nil, it does not return a zero Value, but the Value for the zero value of the empty interface.

Types

type Assocer 

type Assocer interface {
	// Assoc returns a slightly modified version of the receiver with key k
	// associated with value v.
	Assoc(k, v any) (any, error)
}

Assocer wraps the Assoc method.

type Booler 

type Booler interface {
	// Bool computes the truth value of the receiver.
	Bool() bool
}

Booler wraps the Bool method.

type Concatter 

type Concatter interface {
	// Concat concatenates the receiver with another value, the receiver being
	// the left operand. If concatenation is not supported for the given value,
	// the method can return the special error type ErrCatNotImplemented.
	Concat(v any) (any, error)
}

Concatter wraps the Concat method. See Concat for how it is used.

type Dissocer 

type Dissocer interface {
	// Dissoc returns a slightly modified version of the receiver with key k
	// dissociated with any value.
	Dissoc(k any) any
}

Dissocer wraps the Dissoc method.

type Equaler 

type Equaler interface {
	// Equal compares the receiver to another value. Two equal values must have
	// the same hash code.
	Equal(other any) bool
}

Equaler wraps the Equal method.

type ErrIndexer 

type ErrIndexer interface {
	// Index retrieves one value from the receiver at the specified index.
	Index(k any) (any, error)
}

ErrIndexer wraps the Index method.

type File 

type File = *os.File

File is an alias for *os.File.

type HasKeyer 

type HasKeyer interface {
	// HasKey returns whether the receiver has the given argument as a valid
	// key.
	HasKey(any) bool
}

HasKeyer wraps the HasKey method.

type Hasher 

type Hasher interface {
	// Hash computes the hash code of the receiver.
	Hash() uint32
}

Hasher wraps the Hash method.

type Indexer 

type Indexer interface {
	// Index retrieves the value corresponding to the specified key in the
	// container. It returns the value (if any), and whether it actually exists.
	Index(k any) (v any, ok bool)
}

Indexer wraps the Index method.

type Iterator 

type Iterator interface {
	// Iterate calls the passed function with each value within the receiver.
	// The iteration is aborted if the function returns false.
	Iterate(func(v any) bool)
}

Iterator wraps the Iterate method.

type KeysIterator 

type KeysIterator interface {
	// IterateKeys calls the passed function with each key within the receiver.
	// The iteration is aborted if the function returns false.
	IterateKeys(func(v any) bool)
}

KeysIterator wraps the IterateKeys method.

type Kinder 

type Kinder interface {
	Kind() string
}

Kinder wraps the Kind method.

type Lener 

type Lener interface {
	// Len computes the length of the receiver.
	Len() int
}

Lener wraps the Len method.

type List 

type List = vector.Vector

List is an alias for the underlying type used for lists in Elvish.

type ListIndex 

type ListIndex struct {
	Slice bool
	Lower int
	Upper int
}

ListIndex represents a (converted) list index.

func ConvertListIndex 

func ConvertListIndex(rawIndex any, n int) (*ListIndex, error)

ConvertListIndex parses a list index, check whether it is valid, and returns the converted structure.

type ListReprBuilder 

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

ListReprBuilder helps to build Repr of list-like Values.

func NewListReprBuilder 

func NewListReprBuilder(indent int) *ListReprBuilder

NewListReprBuilder makes a new ListReprBuilder.

func (*ListReprBuilder) String 

func (b *ListReprBuilder) String() string

String returns the representation that has been built. After it is called, the ListReprBuilder may no longer be used.

func (*ListReprBuilder) WriteElem 

func (b *ListReprBuilder) WriteElem(v string)

WriteElem writes a new element.

type Map 

type Map = hashmap.Map

Map is an alias for the underlying type used for maps in Elvish.

type MapReprBuilder 

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

MapReprBuilder helps building the Repr of a Map. It is also useful for implementing other Map-like values. The zero value of a MapReprBuilder is ready to use.

func NewMapReprBuilder 

func NewMapReprBuilder(indent int) *MapReprBuilder

NewMapReprBuilder makes a new MapReprBuilder.

func (*MapReprBuilder) String 

func (b *MapReprBuilder) String() string

String returns the representation that has been built. After it is called, the MapReprBuilder should no longer be used.

func (*MapReprBuilder) WritePair 

func (b *MapReprBuilder) WritePair(k string, indent int, v string)

WritePair writes a new pair.

type Num 

type Num any

Num is a stand-in type for int, *big.Int, *big.Rat or float64. This type doesn't offer type safety, but is useful as a marker; for example, it is respected when parsing function arguments.

func Int64ToNum 

func Int64ToNum(i64 int64) Num

Int64ToNum converts an int64 to a Num with a suitable underlying representation.

func NormalizeBigInt 

func NormalizeBigInt(z *big.Int) Num

NormalizeBigInt converts a big.Int to an int if it is within the range of int. Otherwise it returns n as is.

func NormalizeBigRat 

func NormalizeBigRat(z *big.Rat) Num

NormalizeBigRat converts a big.Rat to a big.Int (or an int if within the range) if its denominator is 1.

func ParseNum 

func ParseNum(s string) Num

ParseNum parses a string into a suitable number type. If the string does not represent a valid number, it returns nil.

func Uint64ToNum 

func Uint64ToNum(u64 uint64) Num

Uint64ToNum converts a uint64 to a Num with a suitable underlying representation.

func UnifyNums2 

func UnifyNums2(n1, n2 Num, typ NumType) (u1, u2 Num)

UnifyNums2 is like UnifyNums, but is optimized for two numbers.

type NumSlice 

type NumSlice any

NumSlice is a stand-in type for []int, []*big.Int, []*big.Rat or []float64. This type doesn't offer type safety, but is useful as a marker.

func UnifyNums 

func UnifyNums(nums []Num, typ NumType) NumSlice

UnifyNums unifies the given slice of numbers into the same type, converting those with lower NumType to the highest NumType present in the slice. The typ argument can be used to force the minimum NumType (use 0 if no minimal NumType is needed).

type NumType 

type NumType uint8

NumType represents a number type. 

const (
	Int NumType = iota
	BigInt
	BigRat
	Float64
)

PromoteToBigInt converts an int or *big.Int to a *big.Int. It panics if n is any other type. Possible values for NumType, sorted in the order of implicit conversion (lower types can be implicitly converted to higher types).

type Ordering 

type Ordering uint8

Ordering relationship between two Elvish values. 

const (
	CmpLess Ordering = iota
	CmpEqual
	CmpMore
	CmpUncomparable
)

Possible Ordering values.

func Cmp 

func Cmp(a, b any) Ordering

Cmp compares two Elvish values and returns the ordering relationship between them. Cmp(a, b) returns CmpEqual iff Equal(a, b) is true or both a and b are NaNs.

func CmpTotal 

func CmpTotal(a, b any) Ordering

CmpTotal is similar to Cmp, but uses an artificial total ordering to avoid returning CmpUncomparable:

All the underlying Go types of Elvish's number type are considered the same type.

This function is mainly useful for sorting Elvish values that are not considered comparable by Cmp. Using this function as a comparator groups values by their types and sorts types that are comparable.

type Pipe 

type Pipe struct{ R, W *os.File }

Pipe wraps a pair of *os.File that are the two ends of a pipe.

func (Pipe) IsStructMap 

func (Pipe) IsStructMap()

type PseudoMap 

type PseudoMap interface{ Fields() StructMap }

PseudoMap may be implemented by a type to support map-like introspection. The Repr, Index, HasKey and IterateKeys operations handle pseudo maps.

type RConcatter 

type RConcatter interface {
	RConcat(v any) (any, error)
}

RConcatter wraps the RConcat method. See Concat for how it is used.

type Reprer 

type Reprer interface {
	// Repr returns a string that represents a Value. The string either be a
	// literal of that Value that is preferably deep-equal to it (like `[a b c]`
	// for a list), or a string enclosed in "<>" containing the kind and
	// identity of the Value(like `<fn 0xdeadcafe>`).
	//
	// If indent is at least 0, it should be pretty-printed with the current
	// indentation level of indent; the indent of the first line has already
	// been written and shall not be written in Repr. The returned string
	// should never contain a trailing newline.
	Repr(indent int) string
}

Reprer wraps the Repr method.

type Stringer 

type Stringer interface {
	// Stringer converts the receiver to a string.
	String() string
}

Stringer wraps the String method.

type StructMap 

type StructMap interface{ IsStructMap() }

StructMap may be implemented by a struct to make it accessible to Elvish code as a map. Each exported, named field and getter method (a method taking no argument and returning one value) becomes a field of the map, with the name mapped to dash-case.

Struct maps are indistinguishable from normal maps for Elvish code. The operations Kind, Repr, Hash, Equal, Len, Index, HasKey and IterateKeys handle struct maps consistently with maps; the Assoc and Dissoc operations convert struct maps to maps.

Example: 

type someStruct struct {
    // Provides the "foo-bar" field
    FooBar int
    lorem  string
}

// Marks someStruct as a struct map
func (someStruct) IsStructMap() { }

// Provides the "ipsum" field
func (s SomeStruct) Ipsum() string { return s.lorem }

// Not a getter method; doesn't provide any field
func (s SomeStruct) OtherMethod(int) { }

type Tester 

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

Tester is a helper for testing properties of a value.

func TestValue 

func TestValue(t *testing.T, v any) Tester

TestValue returns a ValueTester.

func (Tester) AllKeys 

func (vt Tester) AllKeys(wantKeys ...any) Tester

AllKeys tests that the given keys match what the result of IterateKeys on the value.

NOTE: This now checks equality using reflect.DeepEqual, since all the builtin types have string keys. This can be changed in future to use Equal is the need arises.

func (Tester) Assoc 

func (vt Tester) Assoc(key, val, wantNew any) Tester

Assoc tests that Assoc'ing the value with the given key-value pair returns the wanted new value and no error.

func (Tester) AssocError 

func (vt Tester) AssocError(key, val any, wantErr error) Tester

AssocError tests that Assoc'ing the value with the given key-value pair returns the given error.

func (Tester) Bool 

func (vt Tester) Bool(wantBool bool) Tester

Bool tests the Boool of the value.

func (Tester) Equal 

func (vt Tester) Equal(others ...any) Tester

Equal tests that the value is Equal to every of the given values.

func (Tester) HasKey 

func (vt Tester) HasKey(keys ...any) Tester

HasKey tests that the value has each of the given keys.

func (Tester) HasNoKey 

func (vt Tester) HasNoKey(keys ...any) Tester

HasNoKey tests that the value does not have any of the given keys.

func (Tester) Hash 

func (vt Tester) Hash(wantHash uint32) Tester

Hash tests the Hash of the value.

func (Tester) Index 

func (vt Tester) Index(key, wantVal any) Tester

Index tests that Index'ing the value with the given key returns the wanted value and no error.

func (Tester) IndexError 

func (vt Tester) IndexError(key any, wantErr error) Tester

IndexError tests that Index'ing the value with the given key returns the given error.

func (Tester) Kind 

func (vt Tester) Kind(wantKind string) Tester

Kind tests the Kind of the value.

func (Tester) Len 

func (vt Tester) Len(wantLen int) Tester

Len tests the Len of the value.

func (Tester) NotEqual 

func (vt Tester) NotEqual(others ...any) Tester

NotEqual tests that the value is not Equal to any of the given values.

func (Tester) Repr 

func (vt Tester) Repr(wantRepr string) Tester

Repr tests the Repr of the value.

type WrongType 

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

WrongType is returned by ScanToGo if the source value doesn't have a compatible type.

func (WrongType) Error 

func (err WrongType) Error() string

Error implements the error interface.

Source Files

aliased_types.go assoc.go bool.go cmp.go concat.go conversion.go dissoc.go doc.go equal.go feed.go has_key.go hash.go index.go index_list.go index_string.go iterate.go iterate_keys.go kind.go len.go num.go pipe.go reflect_wrappers.go repr.go repr_helpers.go string.go struct_map.go tester.go

Version
v0.21.0 (latest)
Published
Aug 13, 2024
Platform
linux/amd64
Imports
20 packages
Last checked
7 hours ago –

Tools for package owners.