LanguageExt.Core ► Traits ► Alternative

Alternative<F> allows for propagation of 'failure' and 'choice' (in some appropriate sense, depending on the type), as well as provision of a unit/identity value (Empty).

Alternative is a Choice and MonoidK, which means it has a Choose method, a Combine method (which defaults to calling the Choose method), and an Empty method. That creates a semantic meaning for Choose, which is about choice propagation rather than the broader meaning of SemigroupK.Combine. It also allows for Choose and Combine to have separate implementations depending on the type.

The way to think about Choose and the inherited SemigroupK.Combine methods is:

Choose is the failure/choice propagation operator: |
Combine is the concatenation/combination/addition operator: +

Any type that supports the Alternative trait should also implement the | operator, to enable easy choice/failure propagation. If there is a different implementation of Combine (rather than accepting the default), then the type should also implement the + operator.

AlternativeLaw can help you test your implementation:

choose(Pure(a), Pure(b)) = Pure(a)
choose(Empty  , Pure(b)) = Pure(b)
choose(Pure(a), Empty  ) = Pure(a)
choose(Empty  , Empty  ) = Empty

It also tests the Applicative and Functor laws.

Contents

AlternativeExtensions

OneOf <F, A> (this Seq<K<F, A>> ms)

AlternativeLaw <F>

assert (Func<K<F, int>, K<F, int>, bool>? equals = null)
validate (Func<K<F, int>, K<F, int>, bool>? equals = null)
leftZeroLaw (Func<K<F, int>, K<F, int>, bool> equals)
rightZeroLaw (Func<K<F, int>, K<F, int>, bool> equals)
leftCatchLaw (Func<K<F, int>, K<F, int>, bool> equals)

Alternative

empty <F, A> ()
choice <F, A> (Seq<K<F, A>> ms)
choice <F, A> (params ReadOnlySpan<K<F, A>> ms)
some <F, A> (K<F, A> fa)
many <F, A> (K<F, A> fa)
endBy <F, A, SEP> (K<F, A> p, K<F, SEP> sep)
endBy1 <F, A, SEP> (K<F, A> p, K<F, SEP> sep)
either <F, A, B> (K<F, A> ma, K<F, B> mb)
manyUntil <F, A, END> (K<F, A> fa, K<F, END> fend)
manyUntil2 <F, A, END> (K<F, A> fa, K<F, END> fend)
someUntil <F, A, END> (K<F, A> fa, K<F, END> fend)
someUntil2 <F, A, END> (K<F, A> fa, K<F, END> fend)
option <F, A> (A value, K<F, A> fa)
sepBy <F, A, SEP> (K<F, A> fa, K<F, SEP> sep)
sepBy1 <F, A, SEP> (K<F, A> fa, K<F, SEP> sep)
sepByEnd <F, A, SEP> (K<F, A> fa, K<F, SEP> sep)
sepByEnd1 <F, A, SEP> (K<F, A> fa, K<F, SEP> sep)
skipMany <F, A> (K<F, A> fa)
skipSome <F, A> (K<F, A> fa)
skip <F, A> (int n, K<F, A> fa)
skipManyUntil <F, A, END> (K<F, A> fa, K<F, END> fend)
skipSomeUntil <F, A, END> (K<F, A> fa, K<F, END> fend)

Prelude

oneOf <F, A> (params K<F, A>[] ms)
oneOf <F, A> (Seq<K<F, A>> ms)

Alternative <F>

Empty <A> ()
Choice <A> (in Seq<K<F, A>> ms)
Choice <A> (in ReadOnlySpan<K<F, A>> ms)
Some <A> (K<F, A> fa)
Many <A> (K<F, A> fa)
EndBy <A, SEP> (K<F, A> p, K<F, SEP> sep)
EndBy1 <A, SEP> (K<F, A> p, K<F, SEP> sep)
Either <A, B> (K<F, A> fa, K<F, B> fb)
ManyUntil <A, END> (K<F, A> fa, K<F, END> fend)
ManyUntil2 <A, END> (K<F, A> fa, K<F, END> fend)
SomeUntil <A, END> (K<F, A> fa, K<F, END> fend)
SomeUntil2 <A, END> (K<F, A> fa, K<F, END> fend)
Option <A> (A value, K<F, A> fa)
SepBy <A, SEP> (K<F, A> fa, K<F, SEP> sep)
SepBy1 <A, SEP> (K<F, A> fa, K<F, SEP> sep)
SepByEnd <A, SEP> (K<F, A> fa, K<F, SEP> sep)
SepByEnd1 <A, SEP> (K<F, A> fa, K<F, SEP> sep)
SkipMany <A> (K<F, A> fa)
SkipSome <A> (K<F, A> fa)
Skip <A> (int n, K<F, A> fa)
SkipManyUntil <A, END> (K<F, A> fa, K<F, END> fend)
SkipSomeUntil <A, END> (K<F, A> fa, K<F, END> fend)

class AlternativeExtensions Source #

A monoid on applicative functors

Parameters

type

F

Applicative functor

Methods

method K<F, A> OneOf <F, A> (this Seq<K<F, A>> ms) Source #

where F : Alternative<F>

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

class AlternativeLaw <F> Source #

where F : Alternative<F>, Applicative<F>

Functions that test that Alternative laws hold for the F Alternative provided.

NOTE: Equals must be implemented for the K〈F, *〉 derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

Parameters

type

F

Alternative type

Methods

method Unit assert (Func<K<F, int>, K<F, int>, bool>? equals = null) Source #

Assert that the Alternative laws hold

NOTE: Equals must be implemented for the K〈F, *〉 derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> validate (Func<K<F, int>, K<F, int>, bool>? equals = null) Source #

Validate that the Alternative laws hold

NOTE: Equals must be implemented for the K〈F, *〉 derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> leftZeroLaw (Func<K<F, int>, K<F, int>, bool> equals) Source #

Left-zero law

choose(empty, pure(x)) = pure(x)

NOTE: Equals must be implemented for the K〈F, *〉 derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> rightZeroLaw (Func<K<F, int>, K<F, int>, bool> equals) Source #

Right-zero law

choose(pure(x), empty) = pure(x)

NOTE: Equals must be implemented for the K〈F, *〉 derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> leftCatchLaw (Func<K<F, int>, K<F, int>, bool> equals) Source #

Left catch law

choose(pure(x), pure(y)) = pure(x)

NOTE: Equals must be implemented for the K〈F, *〉 derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

class Alternative Source #

Methods

method K<F, A> empty <F, A> () Source #

where F : Alternative<F>

Empty / none state for the F structure

Parameters

type	F	Alternative trait implementation
type	A	Bound value type
returns	Empty

method K<F, A> choice <F, A> (Seq<K<F, A>> ms) Source #

where F : Alternative<F>

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

method K<F, A> choice <F, A> (params ReadOnlySpan<K<F, A>> ms) Source #

where F : Alternative<F>

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

method K<F, Seq<A>> some <F, A> (K<F, A> fa) Source #

where F : Alternative<F>

One or more...

Run the applicative functor repeatedly, collecting the results, until failure.

Will always succeed if at least one item has been yielded.

NOTE: It is important that the F applicative-type overrides Apply (the one with Func laziness) in its trait-implementations otherwise this will likely result in a stack-overflow.

Parameters

param	fa	Applicative functor
returns	One or more values

method K<F, Seq<A>> many <F, A> (K<F, A> fa) Source #

where F : Alternative<F>

Zero or more...

Run the applicative functor repeatedly, collecting the results, until failure. Will always succeed.

NOTE: It is important that the F applicative-type overrides ApplyLazy in its trait-implementations otherwise this will likely result in a stack-overflow.

Parameters

param	fa	Applicative functor
returns	Zero or more values

method K<F, Seq<A>> endBy <F, A, SEP> (K<F, A> p, K<F, SEP> sep) Source #

where F : Alternative<F>

endBy(p, sep) parses zero-or-more occurrences of p, separated and ended by sep. Returns a list of values returned by p.

Parameters

type	A	Value type
type	SEP	Separator type
param	p	Value parser
param	sep	Separator parser
returns

method K<F, Seq<A>> endBy1 <F, A, SEP> (K<F, A> p, K<F, SEP> sep) Source #

where F : Alternative<F>

endBy1(p, sep) parses one-or-more occurrences of p, separated and ended by sep. Returns a list of values returned by p.

Parameters

type	A	Value type
type	SEP	Separator type
param	p	Value parser
param	sep	Separator parser
returns

method K<F, Either<A, B>> either <F, A, B> (K<F, A> ma, K<F, B> mb) Source #

where F : Alternative<F>

Combine two alternatives

Parameters

type	A	Left value type
type	B	Right value type
param	ma	Left alternative
param	mb	Right alternative
returns	Alternative structure with an `Either` lifted into it

method K<F, Seq<A>> manyUntil <F, A, END> (K<F, A> fa, K<F, END> fend) Source #

where F : Alternative<F>

manyUntil(fa, end) applies fa zero or more times until fend succeeds. Returns the list of values returned byfa. fend result is consumed and lost. Use manyUntil2 if you wish to keep it.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, (Seq<A> Items, END End)> manyUntil2 <F, A, END> (K<F, A> fa, K<F, END> fend) Source #

where F : Alternative<F>

manyUntil2(fa, end) applies fa zero or more times until fend succeeds. Returns the list of values returned byfa plus the fend result.

Use manyUntil if you don't wish to keep the end result.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, Seq<A>> someUntil <F, A, END> (K<F, A> fa, K<F, END> fend) Source #

where F : Alternative<F>

someUntil(fa, end) applies fa one or more times until fend succeeds. Returns the list of values returned byfa. fend result is consumed and lost. Use someUntil2 if you wish to keep it.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, (Seq<A> Items, END End)> someUntil2 <F, A, END> (K<F, A> fa, K<F, END> fend) Source #

where F : Alternative<F>

someUntil2(fa, end) applies fa one or more times until fend succeeds. Returns the list of values returned byfa plus the fend result.

Use someUntil if you don't wish to keep the end result.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, A> option <F, A> (A value, K<F, A> fa) Source #

where F : Alternative<F>

option(x, fa) tries to apply fa. If fa fails without 'consuming' anything, it returns value, otherwise the value returned by fa.

The word 'consuming' is used here because this feature started life as a parser combinator, but it can be applied to any Alternative structure. Critically, most combinators only have a single flavour of failure. So, option just results in a default value being returned if fa fails.

Parameters

type	A
param	value	Default value to use if `fa` fails without 'consuming' anything
param	fa
returns

method K<F, Seq<A>> sepBy <F, A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

where F : Alternative<F>

sepBy(fa, sep) processes _zero_ or more occurrences of fa, separated by sep`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	sep	Separator structure
returns	List of values returned by `fa`

method K<F, Seq<A>> sepBy1 <F, A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

where F : Alternative<F>

sepBy(fa, sep) processes _one_ or more occurrences of fa, separated by sep`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	sep	Separator structure
returns	List of values returned by `fa`

method K<F, Seq<A>> sepByEnd <F, A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

where F : Alternative<F>

sepEndBy(fa, sep) processes _zero_ or more occurrences of fa, separated and optionally ended by sep. Returns a list of values returned by fa`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	sep	Separator structure
returns	List of values returned by `fa`

method K<F, Seq<A>> sepByEnd1 <F, A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

where F : Alternative<F>

sepEndBy1(fa, sep) processes _one_ or more occurrences of fa, separated and optionally ended by sep. Returns a list of values returned by fa`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	sep	Separator structure
returns	List of values returned by `fa`

method K<F, Unit> skipMany <F, A> (K<F, A> fa) Source #

where F : Alternative<F>

Process fa zero or more times and drop all yielded values.

Run the applicative functor repeatedly until failure. Will always succeed.

Parameters

param	fa	Applicative functor
returns	Unit

method K<F, Unit> skipSome <F, A> (K<F, A> fa) Source #

where F : Alternative<F>

Process fa one or more times and drop all yielded values.

Run the applicative functor repeatedly until failure. At least one item must be yielded for overall success.

Parameters

param	fa	Applicative functor
returns	Unit

method K<F, Unit> skip <F, A> (int n, K<F, A> fa) Source #

where F : Alternative<F>

skip(n, fa) processes n occurrences of fa, skipping its result. If n is not positive, the process equates to Pure(unit).

Parameters

type	A	Value type
param	n	Number of occurrences of `fa` to skip
param	fa	Applicative functor
returns

method K<F, END> skipManyUntil <F, A, END> (K<F, A> fa, K<F, END> fend) Source #

where F : Alternative<F>

skipManyUntil(fa, fend) applies the process fa zero or more times skipping results until process fend succeeds. The resulting value from fend is then returned.

Parameters

type	A	Value type
type	END	End value type
returns

method K<F, END> skipSomeUntil <F, A, END> (K<F, A> fa, K<F, END> fend) Source #

where F : Alternative<F>

skipManyUntil(fa, fend) applies the process fa one or more times skipping results until process fend succeeds. The resulting value from fend is then returned.

Parameters

type	A	Value type
type	END	End value type
returns

class Prelude Source #

Methods

method K<F, A> oneOf <F, A> (params K<F, A>[] ms) Source #

where F : Alternative<F>

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

method K<F, A> oneOf <F, A> (Seq<K<F, A>> ms) Source #

where F : Alternative<F>

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

interface Alternative <F> Source #

where F : Alternative<F>

Methods

method K<F, A> Empty <A> () Source #

Identity

method K<F, A> Choice <A> (in Seq<K<F, A>> ms) Source #

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

method K<F, A> Choice <A> (in ReadOnlySpan<K<F, A>> ms) Source #

Given a set of applicative functors, return the first one to succeed.

If none succeed, the last applicative functor will be returned.

method K<F, Seq<A>> Some <A> (K<F, A> fa) Source #

One or more...

Run the applicative functor repeatedly, collecting the results, until failure.

Will always succeed if at least one item has been yielded.

Parameters

param	fa	Applicative functor
returns	One or more values

method K<F, Seq<A>> Many <A> (K<F, A> fa) Source #

Zero or more...

Run the applicative functor repeatedly, collecting the results, until failure. Will always succeed.

Parameters

param	fa	Applicative functor
returns	Zero or more values

method K<F, Seq<A>> EndBy <A, SEP> (K<F, A> p, K<F, SEP> sep) Source #

endBy(p, sep) parses zero-or-more occurrences of p, separated and ended by sep. Returns a list of values returned by p.

Parameters

type	A	Value type
type	SEP	Separator type
param	p	Value parser
param	sep	Separator parser
returns

method K<F, Seq<A>> EndBy1 <A, SEP> (K<F, A> p, K<F, SEP> sep) Source #

endBy1(p, sep) parses one-or-more occurrences of p, separated and ended by sep. Returns a list of values returned by p.

Parameters

type	A	Value type
type	SEP	Separator type
param	p	Value parser
param	sep	Separator parser
returns

method K<F, Either<A, B>> Either <A, B> (K<F, A> fa, K<F, B> fb) Source #

Combine two alternatives

Parameters

type	A	Left value type
type	B	Right value type
param	fa	Left alternative
param	fb	Right alternative
returns	Alternative structure with an `Either` lifted into it

method K<F, Seq<A>> ManyUntil <A, END> (K<F, A> fa, K<F, END> fend) Source #

manyUntil(fa, end) applies fa zero or more times until fend succeeds. Returns the list of values returned byfa. fend result is consumed and lost. Use manyUntil2 if you wish to keep it.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, (Seq<A> Items, END End)> ManyUntil2 <A, END> (K<F, A> fa, K<F, END> fend) Source #

manyUntil2(fa, end) applies fa zero or more times until fend succeeds. Returns the list of values returned byfa plus the fend result.

Use manyUntil if you don't wish to keep the end result.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, Seq<A>> SomeUntil <A, END> (K<F, A> fa, K<F, END> fend) Source #

someUntil(fa, end) applies fa one or more times until fend succeeds. Returns the list of values returned byfa. fend result is consumed and lost. Use someUntil2 if you wish to keep it.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, (Seq<A> Items, END End)> SomeUntil2 <A, END> (K<F, A> fa, K<F, END> fend) Source #

someUntil2(fa, end) applies fa one or more times until fend succeeds. Returns the list of values returned byfa plus the fend result.

Use someUntil if you don't wish to keep the end result.

Parameters

type	A	Value type
type	END	End value type
param	fa	Structure to consume
param	fend	Terminating structure
returns

method K<F, A> Option <A> (A value, K<F, A> fa) Source #

option(x, fa) tries to apply fa. If fa fails without 'consuming' anything, it returns value, otherwise the value returned by fa.

The word 'consuming' is used here because this feature started life as a parser combinator, but it can be applied to any Alternative structure. Critically, most combinators only have a single flavour of failure. So, option just results in a default value being returned if fa fails.

Parameters

type	A
param	value	Default value to use if `fa` fails without 'consuming' anything
param	p
returns

method K<F, Seq<A>> SepBy <A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

sepBy(fa, sep) processes _zero_ or more occurrences of fa, separated by sep`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	fsep	Separator structure
returns	List of values returned by `fa`

method K<F, Seq<A>> SepBy1 <A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

sepBy(fa, sep) processes _one_ or more occurrences of fa, separated by sep`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	fsep	Separator structure
returns	List of values returned by `fa`

method K<F, Seq<A>> SepByEnd <A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

sepEndBy(fa, sep) processes _zero_ or more occurrences of fa, separated and optionally ended by sep. Returns a list of values returned by fa`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	fsep	Separator structure
returns	List of values returned by `fa`

method K<F, Seq<A>> SepByEnd1 <A, SEP> (K<F, A> fa, K<F, SEP> sep) Source #

sepEndBy1(fa, sep) processes _one_ or more occurrences of fa, separated and optionally ended by sep. Returns a list of values returned by fa`.

Parameters

type	A	Value type
type	SEP	Separator type
param	fa	Structure to yield return values
param	fsep	Separator structure
returns	List of values returned by `fa`

method K<F, Unit> SkipMany <A> (K<F, A> fa) Source #

Process fa zero or more times and drop all yielded values.

Run the applicative functor repeatedly until failure. Will always succeed.

Parameters

param	fa	Applicative functor
returns	Unit

method K<F, Unit> SkipSome <A> (K<F, A> fa) Source #

Process fa one or more times and drop all yielded values.

Run the applicative functor repeatedly until failure. At least one item must be yielded for overall success.

Parameters

param	fa	Applicative functor
returns	Unit

method K<F, Unit> Skip <A> (int n, K<F, A> fa) Source #

skip(n, fa) processes n occurrences of fa, skipping its result. If n is not positive, the process equates to Pure(unit).

Parameters

type	A	Value type
param	n	Number of occurrences of `fa` to skip
param	fa	Applicative functor
returns

method K<F, END> SkipManyUntil <A, END> (K<F, A> fa, K<F, END> fend) Source #

skipManyUntil(fa, fend) applies the process fa zero or more times skipping results until process fend succeeds. The resulting value from fend is then returned.

Parameters

type	A	Value type
param	n	Number of occurrences of `fa` to skip
param	fa	Applicative functor
returns

method K<F, END> SkipSomeUntil <A, END> (K<F, A> fa, K<F, END> fend) Source #

skipManyUntil(fa, fend) applies the process fa one or more times skipping results until process fend succeeds. The resulting value from fend is then returned.

Parameters

type	A	Value type
param	n	Number of occurrences of `fa` to skip
param	fa	Applicative functor
returns