YocamlSourceHere is the list of modules exposed by the YOCaml library. The concept behind this project is to offer, as a library, a set of tools to build pages. In other words, the end user, in this case me, would only have to build a new project in which Preface and YOCaml would be dependencies and then easily create his own static blog generator. It's likely that it won't be efficient or ergonomic, but it's a fun project to do in your spare time.
Please refer to the documentation index for an example.
Build is the main module of YOCaml. It is used to describe rules attached to dependencies. A static site generator is a collection of ordered rules. (So it is probably not useful to use this project and it would be better to write everything with make, sed and awk).
Deps is an attempt to represent (without much effort) a set of dependencies to build a file.
In order to take advantage of Preface (for fun and profit) YOCaml describes a list of effects to manage. As for errors, executable effects are centralised.
Errors handling is mainly based on a biased version of Result and Validation offered by Preface.
Describes the list of errors that can occur in the process of creating a blog.
A specialised version of Result (with Error.t as Error part). Try is very useful for producing sequential validations, where as soon as a step produces an error, the computation sequence is interrupted.
A specialised version of Validation (with a nonempty list of Error.t as Invalid part). Validate is very useful to produce parallel validations, where each error is accumulated, as opposed to Try which stops the computation at the first error.
When we generate pages statically, we often want to be able to attach metadata to them to give the documents more context.
This module describes operations to query key-value objects abstractly. The Yocaml_yaml plugin is an example implementation of this protocol. (Or more precisely the module Yocaml.Key_value.Jsonm_object).
To attach additional content to documents, YOCaml uses a Metadata mechanism. Generally, the formats used for this kind of metadata (Yaml, JSON or even TOML) can be abstractly represented as abstract objects, like a key-value table.
Deploying RSS feeds should be standard in all blogs. This is why minimal support for RSS is possible without using a plugin.
An almost exhaustive list of MIME types extracted from MDN: Common MIME types
Useful tools for developing a YOCaml generator.
As Wordpress is mainly used to move files, having some functions to work with file names can be a very good idea!
A YOCaml program is a pure application that has, a priori, no dependence on the operating system. These dependencies are provided when a program is run (as declared in the yocaml_unix package).
Describes a dedicated runtime for varying the execution context of YOCaml.
There are always lots of little unreadable tools that I want to use... sometimes it improves readability... sometimes not.
include module type of UtilAs I was not very serious... strings occupy a very large place in Wordpress... so it is necessary to be able to work correctly with them.
Even if sometimes, infix operators can seem unreadable... the immoderate use of Arrows has already made the code incomprehensible... so why deprive yourself?
f $ x is f @@ x which is f x... but I don't like @@.
include module type of Filepatht |> into dir describes a t into a dir.
with_extension ext path returns true if path ends with ext false otherwise, ie: with_extension "html" "index.html" returns true but with_extenstion "html" "foohtml" returns false.
Keep the filename and remove the path.
Add an extension to a t. For example: add_extension "index.txt" "html" will produce "index.txt.html".
Remove the extension of a path.
Replace the extension of a path.
A page generation process usually involves composing and executing effects, so rather than constantly forcing the Effect module into user space, the module is injected into the high-level API.
include module type of EffectTo 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 = (_, 'a) Effect.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 = Effect.FreerOnce 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!
file_exists path should be interpreted as returning true if the file denoted by the file path path exists, false otherwise.
target_exists path should be interpreted as returning true if the file denoted by the file path path exists, false otherwise.
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.
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.
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!
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)
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.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.
command 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!
trace message is an alias of log Aliases.Trace.
debug message is an alias of log Aliases.Debug.
info message is an alias of log Aliases.Info.
warning message is an alias of log Aliases.Warning.
alert 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!".
raise_ 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!
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.Syntaxtype (!'a, !'b) handle = ('a -> 'b) -> 'a f -> 'bmodule To_monad = Effect.To_monadmodule Functor = Effect.Functormodule Applicative = Effect.Applicativemodule Selective = Effect.Selectivemodule Monad = Effect.Monadval return : 'a -> 'a tmodule Traverse = Effect.Traverse