package yocaml

  1. Overview
  2. Docs

Centralization of the effects that can be performed.

A bad faith preamble

To be beautiful and modern, this project separates the description of the programme from its interpretation. But as the composition is not really to my taste in Preface, I decided to centralize all the effects, like the errors, in one module.

Ugh, that sounds perfectly stupid... it would be like considering that you can only express one family of effects (you could call it ... IO). Don't panic, the first parameter of type effect allows you to make a selective choice when defining Freer. One could say that one takes advantage of the non-surjective aspect of the constructors of a sum (thanks to the GADTs!). Well, I'd be lying if I said I was convinced it was a good approach, but at least it seems viable.

Effects list

Boy, this type sounds like a hell of a lot of trouble to read! don't read it and go a little lower, there are kind of smarts constructors.

type (_, 'a) effects =
  1. | File_exists : Filepath.t -> (< file_exists : unit.. >, bool) effects
  2. | Target_exists : Filepath.t -> (< target_exists : unit.. >, bool) effects
  3. | Get_modification_time : Filepath.t -> (< get_modification_time : unit.. >, int Try.t) effects
  4. | Target_modification_time : Filepath.t -> (< target_modification_time : unit.. >, int Try.t) effects
  5. | Read_file : Filepath.t -> (< read_file : unit.. >, string Try.t) effects
  6. | Content_changes : (string * Filepath.t) -> (< content_changes : unit.. >, (string, unit) Either.t Try.t) effects
  7. | Write_file : (Filepath.t * string) -> (< write_file : unit.. >, unit Try.t) effects
  8. | Read_dir : (Filepath.t * [< `Files | `Directories | `Both ] * Filepath.t Preface.Predicate.t) -> (< read_dir : unit.. >, Filepath.t list) effects
  9. | Command : string -> (< command : unit.. >, int) effects
  10. | Log : (Log.level * string) -> (< log : unit.. >, unit) effects
  11. | Throw : Error.t -> (< throw : unit.. >, 'a) effects
  12. | Raise : exn -> (< raise_ : unit.. >, 'a) effects

Global definition

Complete mechanism for describing programs by description and providing them with handlers (interpreters/runtime) for all effects modelled in type t. (So absolutely not taking advantage of the slicing capability... It was well worth it!)

Freer monad over effects

All the plumbing for effects description/interpretation resides through a Freer monad (thanks Preface). Although this module is included below, I have taken the liberty of displaying it... for documentation purposes only.

module Freer : Preface.Specs.FREER_MONAD with type 'a f = (< file_exists : unit ; target_exists : unit ; get_modification_time : unit ; target_modification_time : unit ; read_file : unit ; write_file : unit ; content_changes : unit ; read_dir : unit ; log : unit ; command : unit ; throw : unit ; raise_ : unit >, 'a) effects

Performing effects

Once described (or/and specialised), the effects must be produced in a programme description. To transform the description of an effect (a value of type Effect.effect) into the execution of this effect, thus a value of type Effect.t), the perform function is used.

Filesystem

In generating a static blog, having control over the file system seems to be a minimum!

val file_exists : Filepath.t -> bool Freer.t

file_exists path should be interpreted as returning true if the file denoted by the file path path exists, false otherwise.

val target_exists : Filepath.t -> bool Freer.t

target_exists path should be interpreted as returning true if the file denoted by the file path path exists, false otherwise.

val get_modification_time : Filepath.t -> int Try.t Freer.t

get_modification_time path should be interpreted as returning, as an integer, the Unix time (mtime corresponding to the modification date of the file denoted by the file path path.

val target_modification_time : Filepath.t -> int Try.t Freer.t

target_modification_time path should be interpreted as returning, as an integer, the Unix time (mtime corresponding to the modification date of the file denoted by the file path path.

val read_file : Filepath.t -> string Try.t Freer.t

read_file path should be interpreted as trying to read the contents of the file denoted by the file path path. At the moment I'm using strings mainly out of laziness, and as I'll probably be the only user of this library... it doesn't matter!

val content_changes : Filepath.t -> string -> (string, unit) Either.t Try.t Freer.t

content_changes content filepath should be interpreted as trying to check if the content of the file is different from the given content. (In order to reduce the mtime modification)

val write_file : Filepath.t -> string -> unit Try.t Freer.t

write_file path content should be interpreted as trying to write content to the file denoted by the file path path. In my understanding of the system, the file will be completely overwritten if it already exists. Once again I am using strings, but this time it is not laziness, it is to be consistent with read_file.

Get a list of all children of a path.

val read_child_files : Filepath.t -> Filepath.t Preface.Predicate.t -> Filepath.t list Freer.t

Get a list of all child files of a path (exclude dirs).

val read_child_directories : Filepath.t -> Filepath.t Preface.Predicate.t -> Filepath.t list Freer.t

Get a list of all child directories of a path (exclude files).

val collect_children : Filepath.t list -> Filepath.t Preface.Predicate.t -> Filepath.t list Freer.t

Same of read_children but searching through a list of directories.

val collect_child_files : Filepath.t list -> Filepath.t Preface.Predicate.t -> Filepath.t list Freer.t

Same of read_child_files but searching through a list of directories.

val collect_child_directories : Filepath.t list -> Filepath.t Preface.Predicate.t -> Filepath.t list Freer.t

Same of read_child_directories but searching through a list of directories.

val process_files : Filepath.t list -> Filepath.t Preface.Predicate.t -> (Filepath.t -> unit Freer.t) -> unit Freer.t

process_files path predicate action performs sequentially action on each files which satisfies predicate.

val command : string -> int Freer.t

command cmd performs a shell commands and returns the exit code.

Logging

Even if it would be possible to limit our feedback with the user to simply returning an integer (El famoso Unix Return)... it would still be more convenient to display feedback to the user on the stage the program is in, right?

val log : Log.level -> string -> unit Freer.t

log level message should be interpreted as writing (probably to standard output) a message associated with a log level. To look good, the colour should change according to the log level, it would look more professional!

val trace : string -> unit Freer.t

trace message is an alias of log Aliases.Trace.

val debug : string -> unit Freer.t

debug message is an alias of log Aliases.Debug.

val info : string -> unit Freer.t

info message is an alias of log Aliases.Info.

val warning : string -> unit Freer.t

warning message is an alias of log Aliases.Warning.

val alert : string -> unit Freer.t

alert message is an alias of log Aliases.Alert.

Open bar

When we are in the context of an IO, ahem, effect execution, it's open bar, we can do whatever we want, like throwing exceptions galore!

val throw : Error.t -> 'a Freer.t

throw error should be interpreted as... "fire, fire, what to do using an Error!".

val raise_ : exn -> 'a Freer.t

raise_ exn should be interpreted as... "fire, fire, what to do using an exception!".

Effects composition

val sequence : 'a list Freer.t -> ('a -> 'b -> 'b Freer.t) -> 'b Freer.t -> 'b Freer.t

Collapses sequentially YOCaml program. sequence ps f p produces a program which performs p followed by f ps. A common usage is p |> sequences ps f.

Included Freer combinators

As mentioned above, the plumbing of program description and program handling is provided through a Freer Monad, a technique that aims to describe a free build over a Left Kan extension. Although the presence of slicing allows for the construction of specialised effects handlers, in the use case of this blog generator, the effects I propagate turn out to be exactly those I have described in my complete effects list. Coicindance, I don't think so!

It therefore seems logical (not to say ergonomic) to introduce the Freer interface in the toplevel of the Effect module. But as the interface is long and tiring to read, I place it at the end of the module!

module Infix : sig ... end
module Syntax : sig ... end
include Preface.Specs.FREER_MONAD with type 'a f = 'a Freer.f and type 'a t = 'a Freer.t and module Infix := Freer.Infix and module Syntax := Freer.Syntax
type 'a f = 'a Freer.f

The parametric type (which, unlike a Preface_specs.Free_monad don't need to be a Preface_specs.Functor).

type 'a t = 'a Freer.t =
  1. | Return : 'a -> 'a t
  2. | Bind : 'b f * ('b -> 'a t) -> 'a t

The type held by Freer monad.

type ('a, 'b) handle = ('a -> 'b) -> 'a f -> 'b
type 'a handler = {
  1. handler : 'b. ('b, 'a) handle;
}

The handler type. Which is a Natural transformation from the Freer Monad to an unwrapped Identity monad.

val perform : 'a f -> 'a t

Create a new 'a t from a 'a f.

val run : 'a handler -> 'a t -> 'a

Execute a given handler for given data

module To_monad (Monad : Preface_specs.Monad.CORE) : Preface_specs.Freer_monad.TO_MONAD with type 'a t := 'a t and type 'a f := 'a f and type 'a monad := 'a Monad.t

Functor API

A Freer monad is also an Preface_specs.Functor.

module Functor : Preface_specs.Functor.API with type 'a t = 'a t

Applicative API

A Freer monad is also an Preface_specs.Applicative.

module Applicative : Preface_specs.Applicative.API with type 'a t = 'a t

Selective API

A Freer monad is also an Preface_specs.Selective.

module Selective : Preface_specs.Selective.API with type 'a t = 'a t

Monad API

A Freer monad is also (obviously) a Preface_specs.Monad.

module Monad : Preface_specs.Monad.API with type 'a t = 'a t

Type

Functions

include Preface_specs.Monad.WITH_RETURN with type 'a t := 'a t
include Preface_specs.Bind.WITH_BIND with type 'a t := 'a t
val bind : ('a -> 'b t) -> 'a t -> 'b t

bind f m passes the result of computation m to function f.

include Preface_specs.Monad.WITH_RETURN with type 'a t := 'a t
include Preface_specs.Bind.WITH_MAP_AND_JOIN with type 'a t := 'a t
val map : ('a -> 'b) -> 'a t -> 'b t

Mapping over from 'a to 'b over 'a t to 'b t.

val join : 'a t t -> 'a t

join remove one level of monadic structure, projecting its bound argument into the outer level.

include Preface_specs.Monad.WITH_RETURN with type 'a t := 'a t
val return : 'a -> 'a t

Lift a value from 'a into a new 'a t.

include Preface_specs.Bind.WITH_KLEISLI_COMPOSITION with type 'a t := 'a t
val compose_left_to_right : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

Composing monadic functions using Kleisli Arrow (from left to right).

val compose_right_to_left : ('b -> 'c t) -> ('a -> 'b t) -> 'a -> 'c t

Composing monadic functions using Kleisli Arrow (from right to left).

val lift : ('a -> 'b) -> 'a t -> 'b t

Mapping over from 'a to 'b over 'a t to 'b t.

val lift2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t

Mapping over from 'a and 'b to 'c over 'a t and 'b t to 'c t.

val lift3 : ('a -> 'b -> 'c -> 'd) -> 'a t -> 'b t -> 'c t -> 'd t

Mapping over from 'a and 'b and 'c to 'd over 'a t and 'b t and 'c t to 'd t.

val replace : 'a -> 'b t -> 'a t

Create a new 'a t, replacing all values in the 'b t by given a value of 'a.

val void : 'a t -> unit t

Create a new unit t, replacing all values in the 'a t by unit.

Infix operators

Syntax

module Traverse : Preface.Specs.TRAVERSABLE with type 'a t = 'a Freer.t and type 'a iter = 'a list
include module type of Infix with type 'a t := 'a Freer.t
include Preface.Specs.Applicative.INFIX with type 'a t := 'a Freer.t
include Preface_specs.Apply.INFIX with type 'a t := 'a Freer.t
val (<*>) : ('a -> 'b) Freer.t -> 'a Freer.t -> 'b Freer.t

Applicative functor of ('a -> 'b) t over 'a t to 'b t.

val (<**>) : 'a Freer.t -> ('a -> 'b) Freer.t -> 'b Freer.t

Flipped Applicative functor of ('a -> 'b) t over 'a t to 'b t.

val (*>) : unit Freer.t -> 'a Freer.t -> 'a Freer.t

Discard the value of the first argument.

val (<*) : 'a Freer.t -> unit Freer.t -> 'a Freer.t

Discard the value of the second argument.

include Preface.Specs.Monad.INFIX with type 'a t := 'a Freer.t
val (=|<) : ('a -> 'b) -> 'a Freer.t -> 'b Freer.t

Infix version of CORE.map.

val (>|=) : 'a Freer.t -> ('a -> 'b) -> 'b Freer.t

Infix flipped version of CORE.map.

val (>>=) : 'a Freer.t -> ('a -> 'b Freer.t) -> 'b Freer.t

Infix flipped version of CORE.bind.

val (=<<) : ('a -> 'b Freer.t) -> 'a Freer.t -> 'b Freer.t

Infix version of CORE.bind.

val (>=>) : ('a -> 'b Freer.t) -> ('b -> 'c Freer.t) -> 'a -> 'c Freer.t

Infix version of CORE.compose_left_to_right.

val (<=<) : ('b -> 'c Freer.t) -> ('a -> 'b Freer.t) -> 'a -> 'c Freer.t

Infix version of OPERATION.compose_right_to_left.

val (>>) : unit Freer.t -> 'b Freer.t -> 'b Freer.t

Sequentially compose two actions, discarding any value produced by the first.

val (<<) : 'a Freer.t -> unit Freer.t -> 'a Freer.t

Sequentially compose two actions, discarding any value produced by the second.

val (<$>) : ('a -> 'b) -> 'a Freer.t -> 'b Freer.t
val (<&>) : 'a Freer.t -> ('a -> 'b) -> 'b Freer.t

Flipped and infix version of Preface_specs.Functor.CORE.map.

val (<$) : 'a -> 'b Freer.t -> 'a Freer.t
val ($>) : 'a Freer.t -> 'b -> 'b Freer.t

Flipped and infix version of Preface_specs.Functor.OPERATION.replace.

include module type of Syntax with type 'a t := 'a Freer.t
include Preface.Specs.Applicative.SYNTAX with type 'a t := 'a Freer.t
include Preface_specs.Apply.SYNTAX with type 'a t := 'a Freer.t
val and+ : 'a Freer.t -> 'b Freer.t -> ('a * 'b) Freer.t

Product functor mapping from 'a t and 'b t to ('a * 'b) t.

include Preface.Specs.Monad.SYNTAX with type 'a t := 'a Freer.t
val let* : 'a Freer.t -> ('a -> 'b Freer.t) -> 'b Freer.t

Syntactic shortcuts for flipped version of CORE.bind:

let* x = e in f is equals to bind (fun x -> f) e.

val let+ : 'a Freer.t -> ('a -> 'b) -> 'b Freer.t

Syntactic shortcuts for flipped version of CORE.map:

let+ x = e in f is equals to map (fun x -> f) e.

OCaml

Innovation. Community. Security.