Hyde is an experimental reversible build tool for text-based generation.
It is based on Sketch-n-Sketch's reversible semantics.
Reversible means that it does not only compute and write the output files based on inputs files, but it can also listen to changes in these output files and back-propagate them to the input.
Hyde can be useful to:
- Reversibly generate a website based on templates and content. The Sketch-n-Sketch's website is now generated this way.
- Reversibly convert markdown files to HTML files.
- Reversibly create new files based on sources and regular expression replacements
- More generally, any computation producing new text files from old text files.
In combination with Editor, the following workflow makes it very easy to modify statically generated websites.
- Hyde generates a website statically from sources
- Editor displays the generated generated website in the Browser
- Editor automatically or interactively replicates the changes in the browser to the generated website.
- Hyde automatically or interactively back-propagates these changes to the sources.
npm install -g hyde-build-tool
This installs the executable hyde and the synonym hbt.
In a blank folder, we'll create the following structure.
hydefile
a.md
b.html
In a.txt, write the following content:
# Hello [world](https://en.wikipedia.org/wiki/World)[^world]
This is *a.md*.
[^world]: The world is the planet Earth and all life upon it.
In hydefile, write the following task (if no task is specified, all will be called)
all () =
fs.read "a.md"
|> Maybe.map (\content ->
"""<html><head></head><body>@(String.markdown content)</body></html>"""
|> Write "b.html")
|> Maybe.withDefault (Error "file a.md not found")
Open a command line and run:
hyde --watch
You can now modify either a.md or b.html, and see the changes to be back-propagated.
To witness the interaction Hyde provides in case of ambiguity, just insert "new text" and a newline right after <body> in b.html.
Quick start: launch Editor to modify b.html
Hyde can automatically launch Editor.
The parameter --serve both watches the files and launch Editor in the current or given directory:
hyde --serve
You can now enjoy visually editing b.html by pointing your browser at http://127.0.0.1:3000/b.html
When back-propagating changes, Hyde does not only modify the source files, it can actually modify the hydefile... This can be sneaky. However, with proper care, you should be fine.
If you want to avoid that, make sure to prefix parts you don't want to be modified with Update.expressionFreeze (allows variables to change but not the constants) or Update.freeze (fails if modifications are back-propagated to the argument).
A hydefile consist of top-level Elm definitions, some of which may be tasks.
If a function is not a task, its name should be in parentheses.
Tasks must return a List (Write name content | Error message) | Write name content | Error message.
Type safety is not enforced (yet).
In a folder containing a file hydefile:
hydeperforms once the forward pipeline computation and writes the output files.hyde --backwardperforms once the forward pipeline computation, compare with the existing outputs, and writes the input files. It might ask a question if it finds ambiguity. To auto-resolve ambiguities, just add the "--autosync" option.hyde --watchwatches the inputs and the outputs, propagating one to the other. To auto-resolve ambiguities, just add the "--autosync" option.hyde --watch --forwardonly watches the inputs and updates the outputs.hyde resolveorhyde resolve _displays the top-level list of tasks.hyde resolve moduleorhyde resolve module._displays all the tasks that are undermodulehyde resolve m_displays all the tasks that start withmhyde resolve module.sub_displays all the tasks inmodulethat start withsubhyde inspect [task]displays the input files and folders and output files of the task (if omitted, 'all' is the task).
Since version 1.0.43, hyde support plugins. Plugins are files named "hyde-plugin-NAME.leo" that should be placed in the hydefile directory. Each file should evaluate to a function taking two arguments:
- Options (e.g. a list or an object)
- A list of Write like [Write fileName fileContent, Write fileName2 fileContent2]
The function should then return a list of Write (usually the same files with a different content, but translation plug-ins can generate more files).