Fix spaceship operator bugs, document, add tests

Remove some erroneously added brackets_increment() calls.

Reject <=> in preprocessor expressions with a clear error message (it
seems it isn't supported here - clang and gcc don't at least).

The type returned by `<=>` is not `bool`.  We pretend it's
`int` for now, which should work for how it's likely to be used
in constant expressions.

Fixes #1622

Doc/Devel/scanner.html

@@ -204,6 +204,7 @@ SWIG_TOKEN_LESSTHAN          <
 SWIG_TOKEN_GREATERTHAN       > 
 SWIG_TOKEN_LTEQUAL           <= 
 SWIG_TOKEN_GTEQUAL           >= 
+SWIG_TOKEN_LTEQUALGT         <=>
 SWIG_TOKEN_NOT               ~ 
 SWIG_TOKEN_LNOT              ! 
 SWIG_TOKEN_LBRACKET          [ 

Doc/Manual/CPlusPlus20.html

@@ -34,6 +34,21 @@ Work has only just begun on adding C++20 support.
 
 <H2><a name="CPlusPlus20_core_language_changes">10.2 Core language changes</a></H2>
 
+<H3><a name="CPlusPlus20_spaceship_operator">10.2.1 Spaceship operator</a></H3>
+
+<p>
+SWIG supports the spaceship operator <tt>&lt;=&gt;</tt> in constant
+expressions.  To simplifying handling the return value is currently
+treated as an integer rather than <tt>std::strong_ordering</tt>, etc.
+In practice we think that should do the right thing in most cases.
+</p>
+
+<p>
+SWIG also recognises <tt>operator&lt;=&gt;</tt> which can be wrapped
+if renamed.  There's not currently any default renaming for the operator
+or attempts to automatically map it to a three-way comparison operator
+in any target languages that have one.
+</p>
 
 <H2><a name="CPlusPlus20_standard_library_changes">10.3 Standard library changes</a></H2>
 

Examples/test-suite/common.mk

@@ -649,6 +649,7 @@ CPP17_TEST_BROKEN = \
 
 # C++20 test cases.
 CPP20_TEST_CASES += \
+	cpp20_spaceship_operator \
 
 # Broken C++20 test cases.
 CPP20_TEST_BROKEN = \

Examples/test-suite/cpp20_spaceship_operator.i

@@ -0,0 +1,28 @@
+%module cpp20_spaceship_operator
+
+%rename(spaceship) operator<=>;
+
+%inline %{
+#include <compare>
+
+int v = (-1 <=> 1 > 0) ? 7 : 42;
+
+// We use !(a >= b) here due to limited support for (a < b) in SWIG's parser.
+#define ALIEN !(0 <=> 1 >= 0)
+
+const int SPACE = 3 <=> 3 == 0;
+
+struct A {
+  int v;
+
+  explicit A(int v_) : v(v_) { }
+};
+
+int operator<=>(const A& a, const A& b) {
+  return a.v - b.v;
+}
+
+int f(int v = (-1 <=> 1 > 0) ? 7 : 42) { return v; }
+%}
+
+%constant int COMET = (4 <=> 2 > 0);

Examples/test-suite/errors/pp_expressions_bad.i

@@ -66,3 +66,7 @@
 /* Unary + was a no-op and so this didn't give an error in SWIG < 4.1.0. */
 #if "1" == +"1"
 #endif
+
+/* Spaceship operator doesn't seem to be allowed in preprocessor expressions. */
+#if (4 <=> 2) < 0
+#endif

Examples/test-suite/errors/pp_expressions_bad.stderr

@@ -31,3 +31,5 @@ pp_expressions_bad.i:64: Warning 202: Could not evaluate expression '"1" == ~"1"
 pp_expressions_bad.i:64: Warning 202: Syntax error: attempt to apply unary operator to string
 pp_expressions_bad.i:67: Warning 202: Could not evaluate expression '"1" == +"1"'
 pp_expressions_bad.i:67: Warning 202: Syntax error: attempt to apply unary operator to string
+pp_expressions_bad.i:71: Warning 202: Could not evaluate expression '(4 <=> 2) < 0'
+pp_expressions_bad.i:71: Warning 202: Spaceship operator (<=>) not allowed in preprocessor expression

Examples/test-suite/php/cpp20_spaceship_operator_runme.php

@@ -0,0 +1,23 @@
+<?php
+
+require "tests.php";
+
+check::functions(array('f', 'spaceship'));
+check::classes(array('cpp20_spaceship_operator','A'));
+check::globals(array('v', 'SPACE'));
+
+//check::equal(ALIEN, true);
+check::equal(SPACE_get(), 1);
+check::equal(COMET, 1);
+check::equal(v_get(), 42);
+
+$x = new A(1);
+$y = new A(2);
+
+check::equal(spaceship($x, $y) < 0, true);
+check::equal(spaceship($x, $x), 0);
+check::equal(spaceship($y, $x) > 0, true);
+
+check::equal(f(), 42);
+
+check::done();

Source/CParse/parser.y

@@ -1647,7 +1647,8 @@ static String *add_qualifier_to_declarator(SwigType *type, SwigType *qualifier)
 %left  XOR
 %left  AND
 %left  EQUALTO NOTEQUALTO
-%left  GREATERTHAN LESSTHAN GREATERTHANOREQUALTO LESSTHANOREQUALTO LESSEQUALGREATER
+%left  GREATERTHAN LESSTHAN GREATERTHANOREQUALTO LESSTHANOREQUALTO
+%left  LESSEQUALGREATER
 %left  LSHIFT RSHIFT
 %left  PLUS MINUS
 %left  STAR SLASH MODULO
@@ -6844,9 +6845,14 @@ exprcompound   : expr PLUS expr {
 		 $$.val = NewStringf("%s <= %s", COMPOUND_EXPR_VAL($1), COMPOUND_EXPR_VAL($3));
 		 $$.type = cparse_cplusplus ? T_BOOL : T_INT;
 	       }
-               | expr LESSEQUALGREATER expr {
+	       | expr LESSEQUALGREATER expr {
 		 $$.val = NewStringf("%s <=> %s", COMPOUND_EXPR_VAL($1), COMPOUND_EXPR_VAL($3));
-		 $$.type = T_BOOL;
+		 // Really `<=>` returns one of `std::strong_ordering`,
+		 // `std::partial_ordering` or `std::weak_ordering`, but we
+		 // fake it by treating the return value as `int`.  The main
+		 // thing to do with the return value in this context is to
+		 // compare it with 0, for which `int` does the job.
+		 $$.type = T_INT;
 	       }
 	       | expr QUESTIONMARK expr COLON expr %prec QUESTIONMARK {
 		 $$.val = NewStringf("%s?%s:%s", COMPOUND_EXPR_VAL($1), COMPOUND_EXPR_VAL($3), COMPOUND_EXPR_VAL($5));

Source/Preprocessor/expr.c

@@ -445,6 +445,8 @@ int Preprocessor_expr(DOH *s, int *error) {
 	stack[sp - 1].svalue = stack[sp].svalue;
 	sp--;
 	break;
+      case SWIG_TOKEN_LTEQUALGT:
+	goto spaceship_not_allowed;
       default:
 	goto syntax_error_expected_operator;
 	break;
@@ -476,6 +478,11 @@ extra_rparen:
   errmsg = "Extra \')\'";
   *error = 1;
   return 0;
+
+spaceship_not_allowed:
+  errmsg = "Spaceship operator (<=>) not allowed in preprocessor expression";
+  *error = 1;
+  return 0;
 }
 
 /* -----------------------------------------------------------------------------

Source/Swig/scanner.c

@@ -895,17 +895,14 @@ static int look(Scanner *s) {
 	state = 240;
       else if (c == '=') {
 	if ((c = nextchar(s)) == 0) {
-	  brackets_increment(s);
 	  return SWIG_TOKEN_LTEQUAL;
 	} else if (c == '>') { /* Spaceship operator */
 	  return SWIG_TOKEN_LTEQUALGT;
 	} else {
 	  retract(s, 1);
-	  brackets_increment(s);
 	  return SWIG_TOKEN_LTEQUAL;
 	}
-      }
-      else {
+      } else {
 	retract(s, 1);
 	brackets_increment(s);
 	return SWIG_TOKEN_LESSTHAN;