finish the batch interface

Author: jcupitt

CHANGELOG.md

@@ -16,7 +16,8 @@
 - fix an infobar race
 - program: add find unresolved syms
 - lots more vips7 compat macros
-- fix nip4-batch as a shebang interpreter
+- fix up nip4-batch
+- add some man pages
 
 ## 9.0.12 2025/08/21
 

TODO

@@ -1,6 +1,10 @@
-- test other nip4-batch options
+- main_shutdown() takes a LONG time
 
-	benchmark on banana
+	can we just del temp files maybe? just call vips_shutdown()?
+
+- stop menu loading when we're not in workspace mode?
+
+ 	or maybe we do this already?
 
 - add tab completion ... somewhat like VS intellisense
 

man/meson.build

@@ -0,0 +1,4 @@
+install_man(
+    'nip4.1',
+    'nip4-batch.1',
+)

man/nip4-batch.1

@@ -0,0 +1,115 @@
+.TH NIP4-BATCH 1 "Oct 4 2025"
+
+.SH NAME
+.PP
+nip4-batch - command-line interface to the nip4 image processing spreadsheet
+
+.SH SYNOPSIS
+.B nip4-batch
+.I filename
+.RI [ arg1.. ]
+.br
+.B nip4-batch -e
+.I expression
+.RI [ arg1.. ]
+.br
+.B nip4-batch -w
+.RI [ filename1.. ]
+
+.SH DESCRIPTION
+.B nip4-batch
+is a command-line interface to the
+.B nip4(1)
+image processing spreadsheet.
+
+There are three principal modes:
+
+.TP
+.B nip4-batch filename [ arg1.. ]
+Load filename as a set of definitions and pass in any other arguments as
+argc and argv. This is the default mode and is suitable for writing scripts
+in nip4's programming language.
+
+.TP
+.B nip4-batch -e expression [ arg1.. ]
+Set main = expression, set argc and argc to any remaining arguments, and
+print the value of symbol "main" to stdout.
+
+.TP
+.B nip4-batch -w [ filename1.. ]
+Load the named files as workspaces or images. You can use the options below
+to pass the workspace parameters and control what workspace results are
+saved or printed.
+
+.SS "Command Line Options"
+.PP
+These options give more precise control over nip4-batch's behaviour.
+
+.TP
+.B --workspace
+Load arguments as workspaces.
+
+.TP
+.BI --expression= expression
+Evaluate
+.I expression
+and print the result to stdout. Any other arguments are loaded as argc and
+argv.
+
+.TP
+.BI --output= filename
+The value of main is written to
+.I filename.
+If main is a
+list, the filename is incremented between objects. You can use
+the suffix to specify the format and options to write in.
+
+.TP
+.B --print-main
+Print the value of main on exit. nip4-batch will check for a top-level
+symbol called main, and also check each workspace for a main.
+
+.SS "Debugging Options"
+.PP
+Some other options are useful for debugging, benchmarking, and for generating
+strings for internationalisation.
+
+.TP
+.B --verbose
+Produce verbose error messages: handy for debugging in batch mode.
+
+.TP
+.B --i18n
+Output strings from .def files for internationalisation.
+
+.TP
+.B --version
+Print version information.
+
+.TP
+.B --test
+Start up (including any arg processing), test for any errors,
+and exit with an error code if any occurred. Useful for running
+automated tests.
+
+.TP
+.BI --prefix= PREFIX
+Set install prefix. Start up as if nip4-batch had been installed to PREFIX.
+Useful for running automated tests without installing the thing.
+
+.SH EXAMPLES
+
+.TP
+.B nip4-batch -e "2 + 2"
+Prints 4 to stdout.
+
+.TP
+.B nip4-batch -e "99 + Image_file argv?1" -o result.png fred.jpg
+Load argv1 (fred.jpg), add 99, output to result.png.
+
+.TP
+.B nip4-batch -e "Matrix [[1,2],[4,5]] ** -1" -o poop.mat
+Invert the 2x2 matrix and write the result to poop.mat.
+
+.SH COPYRIGHT
+2025 (c) libvips.org

man/nip4.1

@@ -0,0 +1,33 @@
+.TH NIP4 1 "Oct 4 2025"
+.SH NAME
+nip4 \- image processing spreadsheet
+
+.SH SYNOPSIS
+.B nip4
+.RI [ filename1.. ]
+
+.SH DESCRIPTION
+.B nip4
+is a spreadsheet-like tool for scientific image processing. You can develop
+large image processing pipelines interactively, then execute them batch-style
+with the separate
+.B nip4-batch(1)
+program. It is fast and uses relatively little memory.
+
+A full manual is available online.
+
+.SH EXAMPLES
+
+.TP
+.B nip4 fred.jpg
+Start nip4, loading the image fred.jpg.
+
+.TP
+.B nip4 sample.ws
+Start nip4, loading a previous saved workspace.
+
+.SH SEE ALSO
+nip4-batch(1)
+
+.SH COPYRIGHT
+2025 (c) libvips.org

meson.build

@@ -116,3 +116,4 @@ meson.add_install_script('meson_post_install.py')
 subdir('src')
 subdir('share')
 subdir('test')
+subdir('man')

src/heap.c

@@ -2531,11 +2531,12 @@ graph_pointer(PElement *root)
 
 /* Fwd ref.
  */
-static void shell_pelement(PElement *base);
+static gboolean shell_pelement(PElement *base);
 
-/* Print a graph shell-style.
+/* Print a graph shell-style. TRUE for node is a concrete, printable or
+ * saveable thing.
  */
-static void
+static gboolean
 shell_node(HeapNode *hn)
 {
 	PElement p1, p2;
@@ -2544,10 +2545,14 @@ shell_node(HeapNode *hn)
 	 */
 	if (hn->flgs & FLAG_PRINT) {
 		printf("<*circular*>");
-		return;
+		return TRUE;
 	}
 	hn->flgs |= FLAG_PRINT;
 
+	gboolean concrete;
+
+	concrete = FALSE;
+
 	switch (hn->type) {
 	case TAG_CLASS:
 	case TAG_APPL:
@@ -2563,15 +2568,17 @@ shell_node(HeapNode *hn)
 		string_mode = PEISCHAR(&p1);
 
 		for (;;) {
-			if (string_mode)
+			if (string_mode) {
 				printf("%c", PEGETCHAR(&p1));
+				concrete = TRUE;
+			}
 			else
-				shell_pelement(&p1);
+				concrete = shell_pelement(&p1);
 
 			PEPOINTRIGHT(hn, &p2);
 			if (PEISMANAGEDSTRING(&p2)) {
-				printf("%s\n",
-					PEGETMANAGEDSTRING(&p2)->string);
+				printf("%s\n", PEGETMANAGEDSTRING(&p2)->string);
+				concrete = TRUE;
 				break;
 			}
 			else if (PEISELIST(&p2))
@@ -2584,28 +2591,37 @@ shell_node(HeapNode *hn)
 			if (string_mode && !PEISCHAR(&p1))
 				string_mode = FALSE;
 		}
-	} break;
+	}
+		break;
 
 	case TAG_DOUBLE:
 		printf("%g", hn->body.num);
+		concrete = TRUE;
 		break;
 
 	case TAG_COMPLEX:
 		printf("%g %g",
 			GETLEFT(hn)->body.num, GETRIGHT(hn)->body.num);
+		concrete = TRUE;
 		break;
 
 	case TAG_FREE:
 	default:
 		g_assert(FALSE);
 	}
+
+	return concrete;
 }
 
 /* Print a pelement shell-style.
  */
-static void
+static gboolean
 shell_pelement(PElement *base)
 {
+	gboolean concrete;
+
+	concrete = FALSE;
+
 	switch (PEGETTYPE(base)) {
 	/* Only allow concrete base types.
 	 */
@@ -2618,35 +2634,40 @@ shell_pelement(PElement *base)
 	case ELEMENT_TAG:
 	case ELEMENT_SYMBOL:
 	case ELEMENT_NOVAL:
-		printf("no-value");
 		break;
 
 	case ELEMENT_NODE:
-		shell_node(PEGETVAL(base));
+		concrete = shell_node(PEGETVAL(base));
 		break;
 
 	case ELEMENT_CHAR:
 		printf("%c", (int) PEGETCHAR(base));
+		concrete = TRUE;
 		break;
 
 	case ELEMENT_BOOL:
 		printf("%s", bool_to_char(PEGETBOOL(base)));
+		concrete = TRUE;
 		break;
 
 	case ELEMENT_ELIST:
 		printf("[ ]");
+		concrete = TRUE;
 		break;
 
 	case ELEMENT_MANAGED:
 		if (PEISIMAGE(base))
 			printf("%s", PEGETIMAGE(base)->filename);
 		else if (PEISMANAGEDSTRING(base))
 			printf("%s", PEGETMANAGEDSTRING(base)->string);
+		concrete = TRUE;
 		break;
 
 	default:
 		g_assert(FALSE);
 	}
+
+	return concrete;
 }
 
 /* Print a pelement shell-style.
@@ -2660,6 +2681,6 @@ graph_value(PElement *root)
 		error_alert(NULL);
 
 	heap_clear(reduce_context->heap, FLAG_PRINT);
-	shell_pelement(root);
-	printf("\n");
+	if (shell_pelement(root))
+		printf("\n");
 }