C# Functional Programming Language Extensions

This library uses and abuses the features of C# to provide a pure functional-programming 'Base Class Library' that, if you squint, can look like extensions to the language itself. The desire here is to make programming in C# much more robust by helping the engineer's inertia flow in the direction of declarative and pure functional code rather than imperative. Using these techniques for large code-bases can bring tangible benefits to long-term maintenance by removing hidden complexity and by easing the engineer's cognitive load.

Author on...

• Blog: Notes from a Small Functional Island
• Twitter: @paullouth
• Mastodon: @[email protected]
• Github ReadME project: 'Functional programming is finally going mainstream'

Contents

• Reference
• Nu-get package
• Getting started
• Prologue
• Features
  • Functional effects and IO
  • Atomic concurrency, shared state, and collections
  • Immutable collections
  • Optional and Alternative value monads
  • State managing monads
  • Parser combinators
  • Type aliasing
  • Pretty: Produce nicely formatted text with smart layouts
  • Differencing
  • Traits
  • Value traits
• Contributing & Code of Conduct

Reference

• API Reference
• Issues that contain documentation and examples

Nu-get

Nu-get package	Description
LanguageExt.Core	All of the core types and functional 'prelude'. This is all that's needed to get started.
LanguageExt.FSharp	F# to C# interop package. Provides interop between the LanguageExt.Core types (like Option, List and Map) to the F# equivalents, as well as interop between core BCL types and F#
LanguageExt.Parsec	Port of the Haskell parsec library
LanguageExt.Rx	Reactive Extensions support for various types within the Core
LanguageExt.Sys	Provides an effects wrapper around the .NET System namespace making common IO operations pure and unit-testable

Getting started

To use this library, simply include LanguageExt.Core.dll in your project or grab it from NuGet. It is also worth setting up some global using for your project. This is the full list that will cover the key functionality and bring it into scope:

global using LanguageExt;
global using LanguageExt.Common;
global using static LanguageExt.Prelude;
global using LanguageExt.Traits;
global using LanguageExt.Effects;
global using LanguageExt.Pipes;
global using LanguageExt.Pretty;
global using LanguageExt.Traits.Domain;

A minimum, might be:

global using LanguageExt;
global using LanguageExt.Common;
global using static LanguageExt.Prelude;
global using LanguageExt.Traits;

The namespace LanguageExt contains most of the core types; LanguageExt.Prelude contains the functions that bring into scope the prelude functions that behave like standalone functions in ML style functional programming languages; LanguageExt.Traits brings in the higher-kinded trait-types and many extensions; LanguageExt.Common brings in the Error type and predefined Errors.

Prologue

From C# 6 onwards we got the ability to treat static classes like namespaces. This means that we can use static methods without qualifying them first. That instantly gives us access to single term method names that look exactly like functions in ML-style functional languages. i.e.

    using static System.Console;
    
    WriteLine("Hello, World");

This library tries to bring some of the functional world into C#. It won't always sit well with the seasoned C# OO programmer, especially the choice of camelCase names for a lot of functions and the seeming 'globalness' of a lot of the library.

I can understand that much of this library is non-idiomatic, but when you think of the journey C# has been on, is "idiomatic" necessarily right? A lot of C#'s idioms are inherited from Java and C# 1.0. Since then we've had generics, closures, Func, LINQ, async... C# as a language is becoming more and more like a functional language on every release. In fact, the bulk of the new features are either inspired by or directly taken from features in functional languages. So perhaps it's time to move the C# idioms closer to the functional world's idioms?

My goal with this library is very much to create a whole new community within the larger C# community. This community is not constrained by the dogma of the past or by the norms of C#. It understands that the OOP approach to programming has some problems and tries to address them head-on.

And for those that say "just use F#" or "just use Haskell", sure, go do that. But it's important to remember that C# has a lot going for it:

• Incredible investment into a state-of-the art compiler
• Incredible tooling (Visual Studio and Rider)
• A large ecosystem of open-source libraries
• A large community of developers already using it
  • This is also very important for companies that hire engineers
• It is a functional programming language! It has first-class functions, lambdas, etc.
  • And with this library it has a functional-first Base Class Library

A note about naming

One of the areas that's likely to get seasoned C# heads worked up is my choice of naming style. The intent is to try and make something that feels like a functional language rather than following rules of naming conventions (mostly set out by the BCL).

There is, however, a naming guide that will keep you in good stead while reading through this documentation:

• Type names are PascalCase in the normal way
• The types all have constructor functions rather than public constructors that you instantiate with new. They will always be PascalCase:

    Option<int> x = Some(123);
    Option<int> y = None;
    Seq<int> items = Seq(1,2,3,4,5);
    List<int> items = List(1,2,3,4,5);
    HashMap<int, string> dict = HashMap((1, "Hello"), (2, "World"));
    Map<int, string> dict = Map((1, "Hello"), (2, "World"));

• Any (non-type constructor) static function that can be used on its own by using static LanguageExt.Prelude are camelCase.

    var x = map(opt, v => v * 2);

• Any extension methods, or anything "fluent" are PascalCase in the normal way

    var x = opt.Map(v => v * 2);

Even if you disagree with this non-idiomatic approach, all of the camelCase static functions have fluent variants, so you never actually have to see the non-standard stuff.

Features

Functional effects and IO

Location	Feature	Description
Core	IO<A>	A synchronous and asynchronous side-effect: an IO monad
Core	Eff<A>	A synchronous and asynchronous side-effect with error handling
Core	Eff<RT, A>	Same as Eff<A> but with an injectable runtime for dependency-injection: a unit testable IO monad
Core	Pipes	A clean and powerful stream processing system that lets you build and connect reusable streaming components

Atomic concurrency and collections

Location	Feature	Description
Core	Atom<A>	A lock-free atomically mutable reference for working with shared state
Core	Ref<A>	An atomic reference to be used in the transactional memory system
Core	AtomHashMap<K, V>	An immutable HashMap with a lock-free atomically mutable reference
Core	AtomSeq<A>	An immutable Seq with a lock-free atomically mutable reference
Core	VectorClock<A>	Understand distributed causality
Core	VersionVector<A>	A vector clock with some versioned data
Core	VersionHashMap <ConflictV, K, V>	Distrubuted atomic versioning of keys in a hash-map

Immutable collections

Location	Feature	Description
Core	Arr<A>	Immutable array
Core	Seq<A>	Lazy immutable list, evaluate at-most-once - very, very fast!
Core	EnumerableM<A>	Wrapper around IEnumerable - enables the higher-kinded traits to work with enumerables.
Core	Lst<A>	Immutable list - use Seq over Lst unless you need InsertAt
Core	Map<K, V>	Immutable map
Core	Map<OrdK, K, V>	Immutable map with Ord constraint on K
Core	HashMap<K, V>	Immutable hash-map
Core	HashMap<EqK, K, V>	Immutable hash-map with Eq constraint on K
Core	Set<A>	Immutable set
Core	Set<OrdA, A>	Immutable set with Ord constraint on A
Core	HashSet<A>	Immutable hash-set
Core	HashSet<EqA, A>	Immutable hash-set with Eq constraint on A
Core	Que<A>	Immutable queue
Core	Stck<A>	Immutable stack

Optional and alternative value monads

Location	Feature	Description
Core	Option<A>	Option monad
Core	OptionT<M, A>	Option monad-transformer
Core	Either<L,R>	Right/Left choice monad
Core	EitherT<L, M, R>	Right/Left choice monad-transformer
Core	Try<A>	Exception handling monad
Core	TryT<M, A>	Exception handling monad-transformer
Core	Validation<FAIL ,SUCCESS>	Validation applicative and monad for collecting multiple errors before aborting an operation
Core	ValidationT<FAIL, M, SUCCESS>	Validation applicative and monad-transformer

State managing monads

Location	Feature	Description
Core	Reader<E, A>	Reader monad
Core	ReaderT<E, M, A>	Reader monad-transformer
Core	Writer<W, A>	Writer monad that logs to a W constrained to be a Monoid
Core	WriterT<W, M, A>	Writer monad-transformer
Core	State<S, A>	State monad
Core	StateT<S, M, A>	State monad-transformer

Parser combinators

Location	Feature	Description
Parsec	Parser<A>	String parser monad and full parser combinators library
Parsec	Parser<I, O>	Parser monad that can work with any input stream type

New types - Type aliasing

Location	Feature	Description
Core	NewType<SELF, A, PRED>	Haskell newtype equivalent i.e: class Hours : NewType<Hours, double> { public Hours(double value) : base(value) { } }. The resulting type is: equatable, comparable, foldable, a functor, monadic, and iterable
Core	NumType<SELF, NUM, A, PRED>	Haskell newtype equivalent but for numeric types i.e: class Hours : NumType<Hours, TDouble, double> { public Hours(double value) : base(value) { } }. The resulting type is: equatable, comparable, foldable, a functor, a monoid, a semigroup, monadic, iterable, and can have basic artithmetic operations performed upon it.
Core	FloatType<SELF, FLOATING, A, PRED>	Haskell newtype equivalent but for real numeric types i.e: class Hours : FloatType<Hours, TDouble, double> { public Hours(double value) : base(value) { } }. The resulting type is: equatable, comparable, foldable, a functor, a monoid, a semigroup, monadic, iterable, and can have complex artithmetic operations performed upon it.

Pretty

Location	Feature	Description
Core	Doc<A>	Produce nicely formatted text with smart layouts

Differencing

Location	Feature	Description
Core	Patch<EqA, A>	Uses patch-theory to efficiently calculate the difference (Patch.diff(list1, list2)) between two collections of A and build a patch which can be applied (Patch.apply(patch, list)) to one to make the other (think git diff).

Traits

The traits are major feature of v5+ language-ext that makes generic programming with higher-kinds a reality. Check out Paul's series on Higher Kinds to get a deeper insight.

Location	Feature	Description
Core	Alternative<F>	A monoid on applicative functors
Core	Applicative<F>	Applicative functor
Core	Eq<A>	Ad-hoc equality trait
Core	Foldable<T>	Aggregation over a structure
Core	Functor<F>	Functor Map
Core	Has<M, TRAIT>	Used in runtimes to enable DI-like capabilities
Core	Hashable<A>	Ad-hoc has-a-hash-code trait
Core	Monad<M>	Monad trait
Core	MonadT<M, N>	Monad transformer trait
Core	Monoid<A>	A monoid is a type with an identity Empty and an associative binary operation +
Core	MonoidK<M>	Equivalent of monoids for working on higher-kinded types
Core	Mutates<M, OUTER_STATE, INNER_STATE>	Used in runtimes to enable stateful operations
Core	Ord<A>	Ad-hoc ordering / comparisons
Core	Range<SELF, NumOrdA, A>	Abstraction of a range of values
Core	ReaderM<M, Env>	Generalised Reader monad abstraction
Core	Reads<M, OUTER_STATE, INNER_STATE>	Used in runtimes to enable environment value access
Core	SemiAlternative<F>	A semigroup on functors
Core	Semigroup<A>	Provides an associative binary operation +
Core	SemigroupK<M>	Equivalent of semigroups for working with higher-kinded types
Core	StateM<M, S>	Generalised State monad abstraction
Core	Traversable<T>	Traversable structures support element-wise sequencing of Applicative effects
Core	Writer<M, W>	Generalised Writer monad abstraction

Value traits

These work a little like NewType but they impart semantic meaning and some common operators for the underlying value.

Location	Feature	Description
Core	DomainType<SELF, REPR>	Provides a mapping from SELF to an underlying representation: REPR
Core	IdentifierLike <SELF, REPR>	Identifiers (like IDs in databases: PersonId for example), they are equivalent to DomaintType with equality.
Core	VectorSpace<SELF, SCALAR>	Scalable values; can add and subtract self, but can only multiply and divide by a scalar. Can also negate.
Core	AmountLike <SELF, REPR, SCALAR>	Quantities, such as the amount of money in USD on a bank account or a file size in bytes. Derives VectorSpace, IdentifierLike, DomainType, and is orderable (comparable).
Core	LocusLike <SELF, REPR, SCALAR, DISTANCE>	Works with space-like structures. Spaces have absolute and relative distances. Has an origin/zero point and derives DomainType, IdentifierLike, AmountLike and VectorSpace. DISTANCE must also be an AmountLike<SELF, REPR, SCALAR>.
Core	QuantityLike	WIP - derives DomainType, VectorSpace, IdentifierLike, AmountLike

These features are still a little in-flux as of 17th May 2024 - they may evolve, be renamed, or removed - but I like the idea!

Further

For some non-reference like documentation:

• Paul's blog: Notes from a Small Functional Island does deep dives into the philosophy of FP and the inner-workings of language-ext.
• The wiki has some additional documentation, some might be a little out of date since the big v5 refactor, but should give some good insights.

Contributing & Code of Conduct

If you would like to get involved with this project, please first read the Contribution Guidelines and the Code of Conduct.