gott

README

= gott
apiote <me@apiote.xyz>
v2.0.3 2022-04-12
:toc:

gott is a Railway Oriented Programming library for Go.

In ROP a program is a chain of functions wrapped in blocks resembling track switches. It’s a simplification of an Either monad.

gott provides N types of blocks:

* Bind, which wraps a function that continues on the happy track or switches to the sad track

    >------+-------->
            \
             \
    >---------+----->

* Map, which wraps a function that will alwayc continue on the happy track

    >--------------->
    >--------------->

* Tee, which wraps a function performing side effects and can switch to the sad track

             _
             |
    >--------++----->
               \
                \
    >------------+-->

* SafeTee, which is to Tee what Map is to Bind

             _
             |
    >--------+------>
    >--------------->

* Recover, which wraps a function that tries to return to the happy Path

    >--------+------>
            /
           /
    >-----+--------->

* Catch, which switches to the sad track in case of a panic
* Handle, which does different things depending on which track the processing is

== Usage

Provided functions are methods of `R[T any]` generic and return `R[T]` so that they can be chained.

Usage can be seen in tests, the simplest being

    import (
    	"apiote.xyz/p/gott/v2"
    )
    func divide5(by int) (int, error) {
    	if by == 0 {
    		return by, errors.New("divideByZero")
    	} else {
    		return 5 / by, nil
    	}
    }
    func main() {
    	r := R[int]{S: 5}.Bind(divide5)
    	// r.S == 1; r.E == nil
    }

== Contribute

This project is finished; no more functions will be implemented; all feature requests will be ignored.

This project uses The Code of Merit, which is available as CODE_OF_CONDUCT file.

Fixes and patches are welcome; please send them to `gott@git.apiote.xyz` using `git send-email`. They must include a sign-off to certify agreement to https://developercertificate.org/[Developer Certificate of Origin].

All communication—questions, bugs, etc.—should go through the mailing list available at `gott@git.apiote.xyz`. Note that all communication will be made public at https://asgard.apiote.xyz/.

== Mirrors

The canonical repository for this project is https://git.apiote.xyz/gott.git it’s mirrored at https://notabug.org/apiote/gott

Mirrors exist solely for the sake of the code and any additional functions provided by third-party services (including but not limited to issues and pull requests) will not be used and will be ignored.

== License

----
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/.
----

Documentation

Index

• type Exception
  • func (e Exception) Error() string
• type LogLevel
• type R
  • func (r R[T]) Bind(f func(T) (T, error)) R[T]
  • func (r R[T]) Catch(f func(T) T) (r2 R[T])
  • func (r R[T]) Handle(onSuccess func(T), onError func(error)) R[T]
  • func (r R[T]) Map(f func(T) T) R[T]
  • func (r R[T]) Recover(f func(T, error) (T, error)) R[T]
  • func (r R[T]) SafeTee(f func(T)) R[T]
  • func (r R[T]) Tee(f func(T) error) R[T]

Types

type Exception

type Exception struct {
	E interface{}
}

Exception is a type encapsulating anything contained in panic. It implements Error() and therefore can be used as error.

func (Exception) Error

func (e Exception) Error() string

type LogLevel

type LogLevel int

const (
	Quiet LogLevel = iota
	Error
	Debug
	Info
)

LogLevel specifies what to log: Quiet logs nothing, Error logs only errors, Debug logs functions that run, Info logs run and skipped functions

type R

type R[T any] struct {
	S        T
	E        error
	LogLevel LogLevel
}

R is a simplification of Either monad. It’s either succesful—when its error is nil—or unsuccessful otherwise.

func (R[T]) Bind

func (r R[T]) Bind(f func(T) (T, error)) R[T]

Bind performs f on the receiver’s success value and assigns the returned value and error to the receiver if it’s is successful. In either case, Bind returns the receiver. Bind operates on functions that return value and error.

func (R[T]) Catch

func (r R[T]) Catch(f func(T) T) (r2 R[T])

Catch performs f on the receiver’s success value and assigns the returned vale to the receiver if it’s successful. If f panics, Catch recovers and stores the value passed to panic in receiver’s error as Exception. In either case, Catch returns the receiver.

func (R[T]) Handle

func (r R[T]) Handle(onSuccess func(T), onError func(error)) R[T]

Handle performs onSuccess on the receiver’s success value if the receiver is successful, or onError on the receiver’s error otherwise. In either case, Handle returns the receiver.

func (R[T]) Map

func (r R[T]) Map(f func(T) T) R[T]

Map performs f on the receiver’s success value and assigns the returned value to the receiver if it’s is successful. In either case, Map returns the receiver. Map operates on functions that are always successful and return only one value.

func (R[T]) Recover

func (r R[T]) Recover(f func(T, error) (T, error)) R[T]

Revover tries to put processing back on the happy track. If receiver is not successful, Recover calls the passed function and assignes the returned value and error to the receiver. In either case, Recover returns the receiver.

func (R[T]) SafeTee

func (r R[T]) SafeTee(f func(T)) R[T]

SafeTee performs f on the receiver’s success value if the receiver is successful. In either case, SafeTee returns the receiver. SafeTee operates on functions that only perform side effects and are always successful.

func (R[T]) Tee

func (r R[T]) Tee(f func(T) error) R[T]

Tee performs f on the receiver’s success value and assigns the returned error to the receiver if it’s is successful. In either case, Tee returns the receiver. Tee operates on functions that only perform side effects and might return an error