Centralization of the effects that can be performed.
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.
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 = | File_exists : Filepath.t -> (< file_exists : unit.. >, bool) effects| Target_exists : Filepath.t -> (< target_exists : unit.. >, bool) effects| Get_modification_time : Filepath.t -> (< get_modification_time : unit.. >,
int Try.t)
effects| Target_modification_time : Filepath.t -> (< target_modification_time : unit.. >,
int Try.t)
effects| Read_file : Filepath.t -> (< read_file : unit.. >, string Try.t) effects| Content_changes : (string * Filepath.t) -> (< content_changes : unit.. >,
(string, unit) Either.t Try.t)
effects| Write_file : (Filepath.t * string) -> (< write_file : unit.. >, unit Try.t)
effects| Read_dir : (Filepath.t
* [< `Files | `Directories | `Both ]
* Filepath.t Preface.Predicate.t) -> (< read_dir : unit.. >,
Filepath.t list)
effects| Command : string -> (< command : unit.. >, int) effects| Log : (Log.level * string) -> (< log : unit.. >, unit) effects| Throw : Error.t -> (< throw : unit.. >, 'a) effects| Raise : exn -> (< raise_ : unit.. >, 'a) effectsComplete 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!)
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)
effectsOnce 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.
In generating a static blog, having control over the file system seems to be a minimum!
val file_exists : Filepath.t -> bool Freer.tfile_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.ttarget_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.tget_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.ttarget_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.tread_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.tcontent_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.twrite_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.
val read_children :
Filepath.t ->
Filepath.t Preface.Predicate.t ->
Filepath.t list Freer.tGet a list of all children of a path.
val read_child_files :
Filepath.t ->
Filepath.t Preface.Predicate.t ->
Filepath.t list Freer.tGet 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.tGet 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.tSame 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.tSame 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.tSame 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.tprocess_files path predicate action performs sequentially action on each files which satisfies predicate.
val command : string -> int Freer.tcommand cmd performs a shell commands and returns the exit code.
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?
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.ttrace message is an alias of log Aliases.Trace.
val debug : string -> unit Freer.tdebug message is an alias of log Aliases.Debug.
val info : string -> unit Freer.tinfo message is an alias of log Aliases.Info.
val warning : string -> unit Freer.twarning message is an alias of log Aliases.Warning.
val alert : string -> unit Freer.talert message is an alias of log Aliases.Alert.
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!
throw error should be interpreted as... "fire, fire, what to do using an Error!".
val raise_ : exn -> 'a Freer.traise_ exn should be interpreted as... "fire, fire, what to do using an exception!".
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.
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 ... endmodule Syntax : sig ... endinclude 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.Syntaxtype 'a f = 'a Freer.fThe parametric type (which, unlike a Preface_specs.Free_monad don't need to be a Preface_specs.Functor).
The type held by Freer monad.
type ('a, 'b) handle = ('a -> 'b) -> 'a f -> 'bThe handler type. Which is a Natural transformation from the Freer Monad to an unwrapped Identity monad.
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.tA Freer monad is also an Preface_specs.Functor.
module Functor : Preface_specs.Functor.API with type 'a t = 'a tA Freer monad is also an Preface_specs.Applicative.
module Applicative : Preface_specs.Applicative.API with type 'a t = 'a tA Freer monad is also an Preface_specs.Selective.
module Selective : Preface_specs.Selective.API with type 'a t = 'a tA Freer monad is also (obviously) a Preface_specs.Monad.
module Monad : Preface_specs.Monad.API with type 'a t = 'a tinclude Preface_specs.Monad.WITH_RETURN with type 'a t := 'a tinclude Preface_specs.Monad.WITH_RETURN with type 'a t := 'a tinclude Preface_specs.Monad.WITH_RETURN with type 'a t := 'a tval return : 'a -> 'a tLift a value from 'a into a new 'a t.
Composing monadic functions using Kleisli Arrow (from right to left).
Mapping over from 'a and 'b to 'c over 'a t and 'b t to 'c t.
Mapping over from 'a and 'b and 'c to 'd over 'a t and 'b t and 'c t to 'd t.
Create a new 'a t, replacing all values in the 'b t by given a value of 'a.
module Traverse :
Preface.Specs.TRAVERSABLE
with type 'a t = 'a Freer.t
and type 'a iter = 'a listinclude module type of Infix with type 'a t := 'a Freer.tinclude Preface.Specs.Applicative.INFIX with type 'a t := 'a Freer.tinclude Preface_specs.Apply.INFIX with type 'a t := 'a Freer.tApplicative functor of ('a -> 'b) t over 'a t to 'b t.
Flipped Applicative functor of ('a -> 'b) t over 'a t to 'b t.
include Preface.Specs.Monad.INFIX with type 'a t := 'a Freer.tInfix version of CORE.compose_left_to_right.
Infix version of OPERATION.compose_right_to_left.
Sequentially compose two actions, discarding any value produced by the first.
Sequentially compose two actions, discarding any value produced by the second.
Infix version of Preface_specs.Functor.CORE.map.
Flipped and infix version of Preface_specs.Functor.CORE.map.
Infix version of Preface_specs.Functor.OPERATION.replace.
Flipped and infix version of Preface_specs.Functor.OPERATION.replace.
include module type of Syntax with type 'a t := 'a Freer.tinclude Preface.Specs.Applicative.SYNTAX with type 'a t := 'a Freer.tinclude Preface.Specs.Monad.SYNTAX with type 'a t := 'a Freer.tSyntactic shortcuts for flipped version of CORE.bind:
let* x = e in f is equals to bind (fun x -> f) e.