Hyde: The Reversible Build Tool
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
Quick start: Reversible Markdown to HTML
In a blank folder, we'll create the following structure.
hydefile a.md b.html
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.
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:
You can now modify either
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
Editor to modify
Quick start: launch
Hyde can automatically launch Editor.
--serve both watches the files and launch Editor in the current or given directory:
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).
Content of the
hydefile or the
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).
List of commands
In a folder containing a file
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 resolve _displays the top-level list of tasks.
hyde resolve moduleor
hyde resolve module._displays all the tasks that are under
hyde resolve m_displays all the tasks that start with
hyde resolve module.sub_displays all the tasks in
modulethat start with
hyde 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).