Add docs for Quark hooks

supercollider · Dec 23, 2022 · f9ad265 · f9ad265
1 parent 96d311b
commit f9ad265
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 0 deletions.
diff --git a/HelpSource/Classes/Quark.schelp b/HelpSource/Classes/Quark.schelp
@@ -139,6 +139,13 @@ After un/installing or checking out, state is set to changed.
 code smell: this is for the gui
 returns:: Boolean
 
+METHOD:: runHook
+Runs the function code::hook:: which is defined in the code::.quark:: file. This can be used for running a function before or after installation, see link::Guides/UsingQuarks#Hooks:: for more information.
+In case the function can not be executed properly a warning will be printed and the update or installation process will be stopped.
+argument:: hook
+Name of function to run.
+returns:: this
+
 METHOD:: printOn
 ARGUMENT:: stream
 returns:: this

diff --git a/HelpSource/Classes/Quarks.schelp b/HelpSource/Classes/Quarks.schelp
@@ -14,6 +14,7 @@ Show the interface for managing quarks
 returns:: QuarksGui
 
 METHOD:: install
+Will execute the link::Guides/UsingQuarks#Hooks#hooks:: code::\preInstall:: and code::\postInstall:: if defined.
 ARGUMENT:: name
 Name of a quark that is listed in the directory,
 or the url of a git repository
@@ -33,6 +34,7 @@ ARGUMENT:: quark
 returns:: this
 
 METHOD:: uninstall
+Will execute the link::Guides/UsingQuarks#Hooks#hooks:: code::\preUninstall:: and code::\postUninstall:: if defined.
 ARGUMENT:: name
 Name (String) of a quark that is listed in the directory,
 or url of a git repository
@@ -85,6 +87,7 @@ returns:: this
 
 METHOD:: update
 Runs 'git pull' on the checked out copy of the quark. The gui provides a more robust way to do updates.
+Will execute the link::Guides/UsingQuarks#Hooks#hooks:: code::\preUpdate:: and code::\postUpdate:: if defined.
 ARGUMENT:: name
 name of quark
 returns:: this

diff --git a/HelpSource/Guides/UsingQuarks.schelp b/HelpSource/Guides/UsingQuarks.schelp
@@ -251,6 +251,7 @@ list::
 ## country
 ## since
 ## ext_dependency - text describing external software like "PD" or "processing"
+## preInstall - a function / hook which will be called before installation - see link::Guides/UsingQuarks#Hooks::
 ::
 
 dependencies is a list of Quarks or git urls with optional an @refspec
@@ -260,6 +261,44 @@ Bjorklund
 cruciallib@tags/4.1.4
 ::
 
+subsection::Hooks
+
+note::
+Introduced in SuperCollider 3.13 and therefore only available if running at least this version.
+::
+
+It is possible to run a functions which are defined in the code::.quark:: file at specific points of installation or update process, so called "hooks".
+
+This can be used to setup or delete certain directory structures, check for hardware, etc.
+
+Upon execution, the hook function will be handled link::Classes/Quark#-data::, which is the parsed code::.quark:: file as an Link::Classes/Event::, as the first argument.
+
+The following hooks are available and will be executed by link::Classes/Quark#-runHook::
+
+table::
+    ## \preInstall || Will be executed before link::Classes/Quarks#*link:: ||
+    ## \postInstall || Will be executed after link::Classes/Quarks#*link:: ||
+    ## \preUpdate || Will be executed before link::Classes/Git#-pull:: || Upon execution this will have the old state of the code::.quark:: file
+    ## \postUpdate || Will be executed after link::Classes/Git#-pull:: || Upon execution this will have the new, updated state of the code::.quark:: file
+    ## \preUninstall || Will be executed before link::Classes/Quarks#*unlink:: ||
+    ## \postUninstall || Will be executed after link::Classes/Quarks#*unlink:: ||
+::
+
+An example to create a directory with samples for a Quark could look like
+
+code::
+(
+  name: "DemonWidgets",
+  // ...
+  preInstall: {|data|
+	File.mkdir("~/samples/%".format(data[\name]));
+  },
+  postUninstall: {
+	"Samples at '~/samples/DomenWidgets' must be deleted manually".warn;
+  },
+)
+::
+
 subsection::Deprecated/ignored fields
 
 teletype::path:: was used for SVN