Module Yocaml.EffectSource

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.

Sourcetype (_, '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!

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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!

Sourceval 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)

Sourceval 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.

Sourceval read_children : Filepath.t -> Filepath.t Preface.Predicate.t -> Filepath.t list Freer.t

Get a list of all children of a path.

Sourceval 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).

Sourceval 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).

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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?

Sourceval 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!

Sourceval trace : string -> unit Freer.t

trace message is an alias of log Aliases.Trace.

Sourceval debug : string -> unit Freer.t

debug message is an alias of log Aliases.Debug.

Sourceval info : string -> unit Freer.t

info message is an alias of log Aliases.Info.

Sourceval warning : string -> unit Freer.t

warning message is an alias of log Aliases.Warning.

Sourceval 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!

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

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

Sourceval raise_ : exn -> 'a Freer.t

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

Effects composition

Sourceval 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!

Sourcemodule Infix : sig ... end
Sourcemodule 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
type !'a t = 'a Freer.t =
  1. | Return : 'b -> 'b t
  2. | Bind : 'c f * ('c -> 'd t) -> 'd t
type (!'a, !'b) handle = ('a -> 'b) -> 'a f -> 'b
type !'a handler = {
  1. handler : 'b. ('b, 'a) handle;
}
val perform : 'a f -> 'a t
val run : 'a handler -> 'a t -> 'a
module To_monad (Monad : sig ... end) : sig ... end
module Functor : sig ... end
module Applicative : sig ... end
module Selective : sig ... end
module Monad : sig ... end
val bind : ('a -> 'b t) -> 'a t -> 'b t
val map : ('a -> 'b) -> 'a t -> 'b t
val join : 'a t t -> 'a t
val return : 'a -> 'a t
val compose_left_to_right : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t
val compose_right_to_left : ('b -> 'c t) -> ('a -> 'b t) -> 'a -> 'c t
val lift : ('a -> 'b) -> 'a t -> 'b t
val lift2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
val lift3 : ('a -> 'b -> 'c -> 'd) -> 'a t -> 'b t -> 'c t -> 'd t
val replace : 'a -> 'b t -> 'a t
val void : 'a t -> unit t
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
val (<*>) : ('a -> 'b) Freer.t -> 'a Freer.t -> 'b Freer.t
val (<**>) : 'a Freer.t -> ('a -> 'b) Freer.t -> 'b Freer.t
val (*>) : unit Freer.t -> 'a Freer.t -> 'a Freer.t
val (<*) : 'a Freer.t -> unit Freer.t -> 'a Freer.t
include Preface.Specs.Monad.INFIX with type 'a t := 'a Freer.t
val (=|<) : ('a -> 'b) -> 'a Freer.t -> 'b Freer.t
val (>|=) : 'a Freer.t -> ('a -> 'b) -> 'b Freer.t
val (>>=) : 'a Freer.t -> ('a -> 'b Freer.t) -> 'b Freer.t
val (=<<) : ('a -> 'b Freer.t) -> 'a Freer.t -> 'b Freer.t
val (>=>) : ('a -> 'b Freer.t) -> ('b -> 'c Freer.t) -> 'a -> 'c Freer.t
val (<=<) : ('b -> 'c Freer.t) -> ('a -> 'b Freer.t) -> 'a -> 'c Freer.t
val (>>) : unit Freer.t -> 'b Freer.t -> 'b Freer.t
val (<<) : 'a Freer.t -> unit Freer.t -> 'a Freer.t
val (<$>) : ('a -> 'b) -> 'a Freer.t -> 'b Freer.t
val (<&>) : 'a Freer.t -> ('a -> 'b) -> 'b Freer.t
val (<$) : 'a -> 'b Freer.t -> 'a Freer.t
val ($>) : 'a Freer.t -> 'b -> 'b Freer.t
include module type of Syntax with type 'a t := 'a Freer.t
include Preface.Specs.Applicative.SYNTAX with type 'a t := 'a Freer.t
val (and+) : 'a Freer.t -> 'b Freer.t -> ('a * 'b) Freer.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
val (let+) : 'a Freer.t -> ('a -> 'b) -> 'b Freer.t