Merge pull request praat#2787 from PaulBoersma/master

plug-ins: `runNotebook()` can pop up a custom manual

dwtools/VowelEditor.cpp

@@ -535,7 +535,7 @@ static void Table_addColumnIfNotExists_colour (Table me, conststring32 colour) {
 
 static void VowelEditor_getVowelMarksFromFile (VowelEditor me) {
 	autoTable marks;
-	structMelderFile file = {};
+	structMelderFile file { };
 	Melder_pathToFile (my instancePref_marks_fileName(), & file);
 	if (! isValidVowelMarksTableFile (& file, & marks))
 		return;
@@ -1345,7 +1345,7 @@ void structVowelEditor :: v9_repairPreferences () {
 			our setInstancePref_marks_dataSet (our default_marks_dataSet());
 			our setInstancePref_marks_speakerType (our default_marks_speakerType());
 		} else {
-			structMelderFile file = {};
+			structMelderFile file { };
 			Melder_pathToFile (our instancePref_marks_fileName(), & file);
 			if (! isValidVowelMarksTableFile (& file, nullptr)) {
 				Melder_warning (U"The file '", our instancePref_marks_fileName(), U"' which was specified in your preferences "

sys/Formula.cpp

@@ -146,7 +146,7 @@ enum { NO_SYMBOL_,
 		DO_, DOSTR_,
 		WRITE_INFO_, WRITE_INFO_LINE_, APPEND_INFO_, APPEND_INFO_LINE_,
 		WRITE_FILE_, WRITE_FILE_LINE_, APPEND_FILE_, APPEND_FILE_LINE_,
-		PAUSE_SCRIPT_, EXIT_SCRIPT_, RUN_SCRIPT_,
+		PAUSE_SCRIPT_, EXIT_SCRIPT_, RUN_SCRIPT_, RUN_NOTEBOOK_,
 		RUN_SYSTEM_, RUN_SYSTEM_STR_, RUN_SYSTEM_NOCHECK_, RUN_SUBPROCESS_, RUN_SUBPROCESS_STR_,
 		MIN_, MIN_E_, MIN_IGNORE_UNDEFINED_,
 		MAX_, MAX_E_, MAX_IGNORE_UNDEFINED_,
@@ -305,7 +305,7 @@ static const conststring32 Formula_instructionNames [1 + highestSymbol] = { U"",
 	U"do", U"do$",
 	U"writeInfo", U"writeInfoLine", U"appendInfo", U"appendInfoLine",
 	U"writeFile", U"writeFileLine", U"appendFile", U"appendFileLine",
-	U"pauseScript", U"exitScript", U"runScript",
+	U"pauseScript", U"exitScript", U"runScript", U"runNotebook",
 	U"runSystem", U"runSystem$", U"runSystem_nocheck", U"runSubprocess", U"runSubprocess$",
 	U"min", U"min_e", U"min_removeUndefined",
 	U"max", U"max_e", U"max_removeUndefined",
@@ -4409,6 +4409,31 @@ static void do_runScript () {
 	}
 	pushNumber (1);
 }
+static void do_runNotebook () {
+	const Stackel narg = pop;
+	Melder_assert (narg->which == Stackel_NUMBER);
+	const integer numberOfArguments = Melder_iround (narg->number);
+	if (numberOfArguments < 1)
+		Melder_throw (U"The function “runNotebook” requires at least one argument, namely the file name.");
+	stackPointer -= numberOfArguments;
+	const Stackel fileName = & theStack [stackPointer + 1];
+	Melder_require (fileName->which == Stackel_STRING,
+		U"The first argument to “runNotebook” should be a string (the file name), not ", fileName->whichText());
+	theLevel += 1;
+	if (theLevel > MAXIMUM_NUMBER_OF_LEVELS) {
+		theLevel -= 1;
+		Melder_throw (U"Cannot call runNotebook() more than ", MAXIMUM_NUMBER_OF_LEVELS, U" levels deep.");
+	}
+	try {
+		const Editor optionalNewInterpreterOwningWindow = theInterpreter -> optionalDynamicEnvironmentEditor();
+		praat_runNotebook (fileName->getString(), numberOfArguments - 1, & theStack [stackPointer + 1], optionalNewInterpreterOwningWindow);
+		theLevel -= 1;
+	} catch (MelderError) {
+		theLevel -= 1;
+		throw;
+	}
+	pushNumber (1);
+}
 static void do_runSystem () {
 	Melder_require (praat_commandsWithExternalSideEffectsAreAllowed (),
 		U"The function “runSystem” is not available inside manuals.");
@@ -8755,6 +8780,7 @@ CASE_NUM_WITH_TENSORS (LOG10_, do_log10)
 } break; case PAUSE_SCRIPT_: { do_pauseScript ();
 } break; case EXIT_SCRIPT_: { do_exitScript ();
 } break; case RUN_SCRIPT_: { do_runScript ();
+} break; case RUN_NOTEBOOK_: { do_runNotebook ();
 } break; case RUN_SYSTEM_: { do_runSystem ();
 } break; case RUN_SYSTEM_STR_: { do_runSystem_STR ();
 } break; case RUN_SYSTEM_NOCHECK_: { do_runSystem_nocheck ();

sys/ManPages_toHtml.cpp

@@ -136,7 +136,7 @@ static void writeParagraphsAsHtml (ManPages me, Interpreter optionalInterpreterR
 
 		if (paragraph -> type == kManPage_type::PICTURE) {
 			numberOfPictures ++;
-			structMelderFile pngFile;
+			structMelderFile pngFile { };
 			MelderFile_copy (file, & pngFile);
 			pngFile. path [Melder_length (pngFile. path) - 5] = U'\0';   // delete extension ".html"
 			str32cat (pngFile. path, Melder_cat (U"_", numberOfPictures, U".png"));
@@ -268,7 +268,7 @@ static void writeParagraphsAsHtml (ManPages me, Interpreter optionalInterpreterR
 			if (paragraph -> height == 0.001)
 				continue;
 			numberOfPictures ++;
-			structMelderFile pngFile;
+			structMelderFile pngFile { };
 			MelderFile_copy (file, & pngFile);
 			pngFile. path [Melder_length (pngFile. path) - 5] = U'\0';   // delete extension ".html"
 			str32cat (pngFile. path, Melder_cat (U"_", numberOfPictures, U".png"));

sys/NotebookEditor.cpp

@@ -199,7 +199,7 @@ autoNotebookEditor NotebookEditor_createFromText (conststring32 initialText) {
 
 autoNotebookEditor NotebookEditor_createFromNotebook_canBeNull (Notebook notebook) {
 	try {
-		structMelderFile notebookFile;
+		structMelderFile notebookFile { };
 		for (integer ieditor = 1; ieditor <= theReferencesToAllOpenNotebookEditors.size; ieditor ++) {
 			NotebookEditor editor = theReferencesToAllOpenNotebookEditors.at [ieditor];
 			if (Melder_equ (notebook -> string.get(), editor -> file. path)) {

sys/ScriptEditor.cpp

@@ -373,7 +373,7 @@ autoScriptEditor ScriptEditor_createFromText (Editor optionalOwningEditor, const
 
 autoScriptEditor ScriptEditor_createFromScript_canBeNull (Editor optionalOwningEditor, Script script) {
 	try {
-		structMelderFile scriptFile;
+		structMelderFile scriptFile { };
 		for (integer ieditor = 1; ieditor <= theReferencesToAllOpenScriptEditors.size; ieditor ++) {
 			ScriptEditor editor = theReferencesToAllOpenScriptEditors.at [ieditor];
 			if (Melder_equ (script -> string.get(), editor -> file. path)) {

sys/praat_objectMenus.cpp

@@ -396,13 +396,15 @@ FORM_SAVE (GRAPHICS_saveDemoWindowAsPdfFile, U"Save Demo window as PDF file", nu
 FORM (SETTINGS__debug, U"Set debugging options", nullptr) {
 	COMMENT (U"If you switch Tracing on, Praat will write lots of detailed ")
 	COMMENT (U"information about what goes on in Praat")
-	structMelderFile file;
-	#ifdef UNIX
-		MelderFolder_getFile (Melder_preferencesFolder(), U"tracing", & file);
-	#else
-		MelderFolder_getFile (Melder_preferencesFolder(), U"Tracing.txt", & file);
-	#endif
-	COMMENT (Melder_cat (U"to ", Melder_fileToPath (& file), U"."))
+	{// scope
+		structMelderFile file { };
+		#ifdef UNIX
+			MelderFolder_getFile (Melder_preferencesFolder(), U"tracing", & file);
+		#else
+			MelderFolder_getFile (Melder_preferencesFolder(), U"Tracing.txt", & file);
+		#endif
+		COMMENT (Melder_cat (U"to ", Melder_fileToPath (& file), U"."))
+	}
 	BOOLEAN (tracing, U"Tracing", false)
 	COMMENT (U"Setting the following to anything other than zero")
 	COMMENT (U"will alter the behaviour of Praat")

sys/praat_script.cpp

@@ -595,6 +595,45 @@ void praat_runScript (conststring32 fileName, integer narg, Stackel args, Editor
 	}
 }
 
+void praat_runNotebook (conststring32 fileName, integer narg, Stackel args, Editor optionalInterpreterOwningEditor) {
+	structMelderFile file { };
+	Melder_relativePathToFile (fileName, & file);
+	try {
+		autostring32 text = MelderFile_readText (& file);
+		if (! Melder_startsWith (text.get(), U"\""))
+			Melder_throw (U"File ", & file, U" is not a Praat notebook.");
+		/*
+			We switch between default directories no fewer than four times:
+			1. runScript() tends to be called from a script that we call the "caller";
+			   when we enter runScript(), the default directory is the caller's folder,
+			   as was appropriate for the use of file names in the caller before runScript(),
+			   which had to be interpreted relative to the caller's folder.
+			2. runScript() will call a script that we call the "callee";
+			   include files have to be included from the callee's folder.
+			3. For expanding any infile/outfile/folder arguments to runScript(),
+			   we have to be back in the caller's folder.
+			4. Inside the callee, file names will have to be interpreted relative to the callee's folder.
+			5. After runScript() finishes, we will have to be back in the caller's folder,
+			   so that the use of file names in the caller after runScript()
+			   will be interpreted relative to the caller's folder again.
+		*/
+		{// scope
+			autoMelderSaveCurrentFolder saveFolder;
+			autoMelderFileSetCurrentFolder folder (& file);   // so that callee-relative file names can be used for including include files
+			Melder_includeIncludeFiles (& text);
+		}   // back to the default directory of the caller
+		autoInterpreter interpreter = Interpreter_createFromEnvironment (optionalInterpreterOwningEditor);
+		Interpreter_readParameters (interpreter.get(), text.get());
+		autoMelderReadText readText = MelderReadText_createFromText (text.move());
+		autoManPages manPages = ManPages_createFromText (readText.get(), & file);
+		ManPage firstPage = manPages -> pages.at [1];
+		autoManual manual = Manual_create (firstPage -> title.get(), interpreter.get(), manPages.releaseToAmbiguousOwner(), true, true);
+		manual.releaseToUser ();
+	} catch (MelderError) {
+		Melder_throw (U"Notebook ", & file, U" not completed.");   // don't refer to 'fileName', because its contents may have changed
+	}
+}
+
 void praat_executeScriptFromCommandLine (conststring32 fileName, integer argc, char **argv) {
 	structMelderFile file { };
 	Melder_relativePathToFile (fileName, & file);

sys/praat_script.h

@@ -2,7 +2,7 @@
 #define _praat_script_h_
 /* praat_script.h
  *
- * Copyright (C) 1992-2005,2007,2009-2016,2018,2021-2023 Paul Boersma
+ * Copyright (C) 1992-2005,2007,2009-2016,2018,2021-2024 Paul Boersma
  *
  * This code is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -24,6 +24,7 @@ bool praat_executeCommand (Interpreter me, char32 *command);   // returns false
 void praat_executeCommandFromStandardInput (conststring32 programName);
 void praat_executeScriptFromFile (MelderFile file, conststring32 arguments, Editor optionalInterpreterOwningEditor);
 void praat_runScript (conststring32 fileName, integer narg, Stackel args, Editor optionalInterpreterOwningEditor);   // called only from Formula as `runScript` (last checked 2022-10-07)
+void praat_runNotebook (conststring32 fileName, integer narg, Stackel args, Editor optionalInterpreterOwningEditor);
 void praat_executeScriptFromCommandLine (conststring32 fileName, integer argc, char **argv);   // called only from `praat_run` (last checked 2022-10-07)
 void praat_executeScriptFromFileNameWithArguments (conststring32 nameAndArguments);   // called only from `execute` (deprecated) and external man pages with \SC (last checked 2022-10-07)
 void praat_executeScriptFromText (conststring32 text);