Require a main program (fix #2785)

Makefile.am

@@ -222,7 +222,8 @@ EXTRA_DIST = $(DOC_FILES) $(man_MANS) $(TESTS) $(TEST_LOG_COMPILER)     \
         tests/setup tests/torture/input0.json                           \
         tests/optional.test tests/man.test tests/manonig.test           \
         tests/jq.test tests/onig.test tests/base64.test                 \
-        tests/utf8-truncate.jq tests/jq-f-test.sh
+        tests/utf8-truncate.jq tests/jq-f-test.sh                       \
+        tests/no-main-program.jq tests/yes-main-program.jq
 
 AM_DISTCHECK_CONFIGURE_FLAGS=--with-oniguruma=builtin
 

docs/content/manual/manual.yml

@@ -81,9 +81,18 @@ sections:
       output(s) of the filter are written to standard output, as a
       sequence of newline-separated JSON data.
 
+      The simplest and most common filter (or jq program) is `.`,
+      which is the identity operator, copying the inputs of the jq
+      processor to the output stream.  Because the default behavior of
+      the jq processor is to read JSON texts from the input stream,
+      and to pretty-print outputs, the `.` program's main use is to
+      validate and pretty-print the inputs.  The jq programming
+      language is quite rich and allows for much more than just
+      validation and pretty-printing.
+
       Note: it is important to mind the shell's quoting rules.  As a
       general rule it's best to always quote (with single-quote
-      characters) the jq program, as too many characters with special
+      characters on Unix shells) the jq program, as too many characters with special
       meaning to jq are also shell meta-characters.  For example, `jq
       "foo"` will fail on most Unix shells because that will be the same
       as `jq foo`, which will generally fail because `foo is not
@@ -100,6 +109,9 @@ sections:
       * Powershell: `jq '.[\"foo\"]'`
       * Windows command shell: `jq ".[\"foo\"]"`
 
+      Note: jq allows user-defined functions, but every jq program
+      must have a top-level expression.
+
       You can affect how jq reads and writes its input and output
       using some command-line options:
 

jq.1.prebuilt

@@ -35,7 +35,10 @@ But that\'s getting ahead of ourselves\. :) Let\'s start with something simpler:
 jq filters run on a stream of JSON data\. The input to jq is parsed as a sequence of whitespace\-separated JSON values which are passed through the provided filter one at a time\. The output(s) of the filter are written to standard output, as a sequence of newline\-separated JSON data\.
 .
 .P
-Note: it is important to mind the shell\'s quoting rules\. As a general rule it\'s best to always quote (with single\-quote characters) the jq program, as too many characters with special meaning to jq are also shell meta\-characters\. For example, \fBjq "foo"\fR will fail on most Unix shells because that will be the same as \fBjq foo\fR, which will generally fail because \fBfoo is not defined\fR\. When using the Windows command shell (cmd\.exe) it\'s best to use double quotes around your jq program when given on the command\-line (instead of the \fB\-f program\-file\fR option), but then double\-quotes in the jq program need backslash escaping\. When using the Powershell (\fBpowershell\.exe\fR) or the Powershell Core (\fBpwsh\fR/\fBpwsh\.exe\fR), use single\-quote characters around the jq program and backslash\-escaped double\-quotes (\fB\e"\fR) inside the jq program\.
+The simplest and most common filter (or jq program) is \fB\.\fR, which is the identity operator, copying the inputs of the jq processor to the output stream\. Because the default behavior of the jq processor is to read JSON texts from the input stream, and to pretty\-print outputs, the \fB\.\fR program\'s main use is to validate and pretty\-print the inputs\. The jq programming language is quite rich and allows for much more than just validation and pretty\-printing\.
+.
+.P
+Note: it is important to mind the shell\'s quoting rules\. As a general rule it\'s best to always quote (with single\-quote characters on Unix shells) the jq program, as too many characters with special meaning to jq are also shell meta\-characters\. For example, \fBjq "foo"\fR will fail on most Unix shells because that will be the same as \fBjq foo\fR, which will generally fail because \fBfoo is not defined\fR\. When using the Windows command shell (cmd\.exe) it\'s best to use double quotes around your jq program when given on the command\-line (instead of the \fB\-f program\-file\fR option), but then double\-quotes in the jq program need backslash escaping\. When using the Powershell (\fBpowershell\.exe\fR) or the Powershell Core (\fBpwsh\fR/\fBpwsh\.exe\fR), use single\-quote characters around the jq program and backslash\-escaped double\-quotes (\fB\e"\fR) inside the jq program\.
 .
 .IP "\(bu" 4
 Unix shells: \fBjq \'\.["foo"]\'\fR
@@ -49,6 +52,9 @@ Windows command shell: \fBjq "\.[\e"foo\e"]"\fR
 .IP "" 0
 .
 .P
+Note: jq allows user\-defined functions, but every jq program must have a top\-level expression\.
+.
+.P
 You can affect how jq reads and writes its input and output using some command\-line options:
 .
 .TP

src/linker.c

@@ -407,6 +407,12 @@ int load_program(jq_state *jq, struct locfile* src, block *out_block) {
   if (nerrors)
     return nerrors;
 
+  if (!block_has_main(program)) {
+    jq_report_error(jq, jv_string("jq: error: Top-level program not given (try \".\")"));
+    block_free(program);
+    return 1;
+  }
+
   char* home = getenv("HOME");
   if (home) {    // silently ignore no $HOME
     /* Import ~/.jq as a library named "" found in $HOME */

tests/no-main-program.jq

@@ -0,0 +1 @@
+def a: .;

tests/shtest

@@ -516,4 +516,34 @@ if command -v script >/dev/null 2>&1; then
   cmp $d/color $d/expect
 fi
 
+# #2785
+if $VALGRIND $Q $JQ -n -f "$JQTESTDIR/no-main-program.jq" > $d/out 2>&1; then
+  echo "jq -f $JQTESTDIR/no-main-program.jq succeeded"
+  exit 1
+else
+  EC=$?
+  if [ $EC -eq 1 ]; then
+    echo "jq -f $JQTESTDIR/no-main-program.jq failed with memory errors"
+    exit 1
+  fi
+  if [ $EC -ne 3 ]; then
+    echo "jq -f $JQTESTDIR/no-main-program.jq failed with wrong exit code ($EC)"
+    exit 1
+  fi
+fi
+cat > $d/expected <<EOF
+jq: error: Top-level program not given (try ".")
+
+jq: 1 compile error
+EOF
+if ! diff $d/expected $d/out; then
+  echo "jq -f $JQTESTDIR/no-main-program.jq failed but its error message is not the expected one"
+  exit 1
+fi
+
+if ! $VALGRIND $Q $JQ -n -f "$JQTESTDIR/yes-main-program.jq" > $d/out 2>&1; then
+  echo "jq -f $JQTESTDIR/yes-main-program.jq failed"
+  exit 1
+fi
+
 exit 0

tests/yes-main-program.jq

@@ -0,0 +1,2 @@
+def a: .;
+0