Error handling: split stack frames over two lines; adjust more manual examples (#6263)

Render visible stack frames with numbered prefixes on one
line and an aligned location line below, and give compiled
GAP frames a stacktrace-specific format.

AI-assisted with Codex for implementation, tests, and
documentation.

Co-authored-by: Codex <codex@openai.com>

Author: fingolfin

doc/ref/debug.xml

@@ -915,41 +915,33 @@ to terminate the calculation, or enter <B>Return</B><C>;</C> to continue it.
 gap> dive:= function(depth) if depth>1 then dive(depth-1); fi; return; end;
 function( depth ) ... end
 gap> dive(100);
-gap> OnBreak:= function() Where(1); end; # shorter traceback
-function(  ) ... end
+gap> OnBreak:= function() Where(2); end;; # shorter traceback
 gap> dive(6000);
-recursion depth trap (5000)
- at
-dive( depth - 1 );
- called from
-dive( depth - 1 ); called from
-...
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you may 'return;' to continue
+Error, recursion depth trap (5000)
+*[1] dive( depth - 1 );
+   @ *stdin*:1
+ [2] dive( depth - 1 );
+   @ *stdin*:1
+...  at *stdin*:4
+you may 'return;'
 brk> return;
 gap> dive(11000);
-recursion depth trap (5000)
- at
-dive( depth - 1 );
- called from
-dive( depth - 1 ); called from
-...
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you may 'return;' to continue
+Error, recursion depth trap (5000)
+*[1] dive( depth - 1 );
+   @ *stdin*:1
+ [2] dive( depth - 1 );
+   @ *stdin*:1
+...  at *stdin*:5
+you may 'return;'
 brk> return;
-recursion depth trap (10000)
- at
-dive( depth - 1 );
- called from
-dive( depth - 1 ); called from
-...
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you may 'return;' to continue
-brk> return;
-gap>
+Error, recursion depth trap (10000)
+*[1] dive( depth - 1 );
+   @ *stdin*:1
+ [2] dive( depth - 1 );
+   @ *stdin*:1
+...  at *stdin*:5
+you may 'return;'
+brk> return;gap>
 ]]></Log>
 <P/>
 
@@ -979,39 +971,29 @@ gap> dive := function(depth)
 >  fi;
 > end;;
 gap> SetRecursionTrapInterval(1000);
+gap> OnBreak:= function() Where(2); end;; # shorter traceback
 gap> dive(100);
 Depth 100
 gap> dive(2500);
-recursion depth trap (1000)
- at
-dive( depth - 1 );
- called from
-dive( depth - 1 ); called from
-...
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you may 'return;' to continue
+Error, recursion depth trap (1000)
+*[1] dive( depth - 1 );
+   @ *stdin*:4
+ [2] dive( depth - 1 );
+   @ *stdin*:4
+...  at *stdin*:12
+you may 'return;'
 brk> return;
-recursion depth trap (2000)
- at
-dive( depth - 1 );
- called from
-dive( depth - 1 ); called from
-...
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you may 'return;' to continue
+Error, recursion depth trap (2000)
+*[1] dive( depth - 1 );
+   @ *stdin*:4
+ [2] dive( depth - 1 );
+   @ *stdin*:4
+...  at *stdin*:12
+you may 'return;'
 brk> GetRecursionDepth();
 0
 brk> return;
-gap> SetRecursionTrapInterval(-1);
-Error, SetRecursionTrapInterval: <interval> must be a small integer greater than 5 (n\
-ot the integer -1)
-not in any function
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you can replace <interval> via 'return <interval>;' to continue
-brk> return 0;
+gap> SetRecursionTrapInterval(2^50);
 gap> dive(20000);
 Depth 20000
 gap> dive(2000000);

doc/ref/grpperm.xml

@@ -652,11 +652,7 @@ gap> h:=Group(permutationlist);
 <permutation group with 5 generators>
 gap> StabChainOptions(h).random:=1;;
 gap> Size(h);
-exceeded the permitted memory (`-o' command line option) at
-mlimit := 1; called from
-SCRMakeStabStrong( S.stabilizer, [ g ], param, orbits, where, basesize,
- base, correct, missing, false ); called from
- SCRMakeStabStrong( S.stabilizer, [ g ], param, orbits, where, basesize,
+exceeded the permitted memory (`-o' command line option)
 ...
 ]]></Log>
 <P/>

doc/ref/language.xml

@@ -1556,24 +1556,19 @@ If the expression <A>expr</A> is a function call then this function must
 return a value.  If the function does not return a value an error is
 signalled and you enter a break loop (see <Ref Sect="Break Loops"/>).
 As usual you can leave the break  loop  with <C>quit;</C>.
-If you enter <C>return <A>return-expr</A>;</C> the value of the expression
-<A>return-expr</A> is assigned to the variable,
-and execution continues after the assignment.
 <P/>
 <Log><![CDATA[
 gap> f1:= function( x ) Print( "value: ", x, "\n" ); end;;
 gap> f2:= function( x ) return f1( x ); end;;
 gap> f2( 4 );
 value: 4
-Function Calls: <func> must return a value at
-return f1( x );
- called from
-<function>( <arguments> ) called from read-eval-loop
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you can supply one by 'return <value>;' to continue
-brk> return "hello";
-"hello"
+Error, Function Calls: <func> must return a value
+*[1] f1( x )
+   @ *stdin*:2
+<function "f2">( <arguments> )
+ called from read-eval loop at *stdin*:3
+type 'quit;' to quit to outer loop
+brk>
 ]]></Log>
 <P/>
 In the above example, the function <C>f2</C> calls <C>f1</C> with argument

doc/ref/methsel.xml

@@ -125,19 +125,15 @@ objecty, a "No Method Found" error will be returned.
 <Log><![CDATA[
 gap> XCons(IsFullTransformationMonoid,4);
 Error, no method found! For debugging hints type ?Recovery from NoMethodFound
-Error, no 1st choice method found for `XCons' on 2 arguments called from
-<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
- called from read-eval loop at line 8 of *stdin*
-you can 'quit;' to quit to outer loop, or
-you can 'return;' to continue
+Error, no 1st choice method found for `XCons' on 2 arguments
+called from read-eval loop at *stdin*:8
+type 'quit;' to quit to outer loop
 brk> quit;
 gap> XCons(IsNilpotentGroup,4);
 Error, no method found! For debugging hints type ?Recovery from NoMethodFound
-Error, no 1st choice method found for `XCons' on 2 arguments called from
-<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
- called from read-eval loop at line 9 of *stdin*
-you can 'quit;' to quit to outer loop, or
-you can 'return;' to continue
+Error, no 1st choice method found for `XCons' on 2 arguments
+called from read-eval loop at *stdin*:8
+type 'quit;' to quit to outer loop
 brk>
 ]]></Log>
 
@@ -435,4 +431,3 @@ the mathematical term <Q>centre</Q>.
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <!-- %% -->
 <!-- %E -->
-

doc/ref/mloop.xml

@@ -476,24 +476,20 @@ indicate that you are in a break loop.
 <P/>
 <Log><![CDATA[
 gap> 1/0;
-Rational operations: <divisor> must not be zero
-not in any function
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you can replace <divisor> via 'return <divisor>;' to continue
+Error, Rational operations: <divisor> must not be zero
+not in any function at *stdin*:2
+type 'quit;' to quit to outer loop
 ]]></Log>
 <P/>
 If errors occur within a break loop &GAP; enters another break loop at a
 <E>deeper level</E>. This is indicated by a number appended to <C>brk</C>:
 <P/>
 <Log><![CDATA[
 brk> 1/0;
-Rational operations: <divisor> must not be zero
-not in any function
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you can replace <divisor> via 'return <divisor>;' to continue
-brk_02>
+Error, Rational operations: <divisor> must not be zero
+not in any function at *stdin*:2
+type 'quit;' to quit to outer loop
+brk_2>
 ]]></Log>
 <P/>
 There are two ways to leave a break loop,
@@ -511,7 +507,7 @@ Note that &GAP; code between <C>quit;</C> and the end of the input line
 is ignored.
 <P/>
 <Log><![CDATA[
-brk_02> quit;
+brk_2> quit;
 brk>
 ]]></Log>
 <P/>
@@ -750,25 +746,30 @@ same as <Ref Func="Where"/> while also showing the arguments and local
 variables of each function.
 <P/>
 <Log><![CDATA[
-gap> StabChain(SymmetricGroup(100)); # After this we typed ^C
-user interrupt at
-bpt := S.orbit[1];
- called from
-SiftedPermutation( S, (g * rep) ^ -1 ) called from
-StabChainStrong( S.stabilizer, [ sch ], options ); called from
-StabChainStrong( S.stabilizer, [ sch ], options ); called from
-StabChainStrong( S, GeneratorsOfGroup( G ), options ); called from
-StabChainOp( G, rec(
-     ) ) called from
-...
-Entering break read-eval-print loop ...
-you can 'quit;' to quit to outer loop, or
-you can 'return;' to continue
+gap> StabChain(SymmetricGroup(1000)); # After this we typed ^C
+Error, user interrupt
+*[1] genlabels := Filtered( genlabels, function ( x )
+        return pnt ^ sgs[x] = pnt;
+    end );
+   @ GAPROOT/lib/stbc.gi:426
+ [2] StabChainBaseStrongGenerators( dom{[ 1 .. Length( dom ) - 1 ]}, sgs, () )
+   @ GAPROOT/lib/gpprmsya.gi:2006
+ [3] StabChainOp( G, rec(
+     ) )
+   @ GAPROOT/lib/stbc.gi:28
+ [4] StabChainImmutable( arg[1] )
+   @ GAPROOT/lib/stbc.gi:18
+<function "StabChain">( <arguments> )
+ called from read-eval loop at *stdin*:2
+you can 'return;'
 brk> Where(2);
- called from
-SiftedPermutation( S, (g * rep) ^ -1 ) called from
-StabChainStrong( S.stabilizer, [ sch ], options ); called from
-...
+*[1] genlabels := Filtered( genlabels, function ( x )
+        return pnt ^ sgs[x] = pnt;
+    end );
+   @ GAPROOT/lib/stbc.gi:426
+ [2] StabChainBaseStrongGenerators( dom{[ 1 .. Length( dom ) - 1 ]}, sgs, () )
+   @ GAPROOT/lib/gpprmsya.gi:2006
+...  at *errin*:1
 ]]></Log>
 <P/>
 Note that the variables displayed even in the first line of the
@@ -836,10 +837,14 @@ Error, !
 you can 'quit;' to quit to outer loop, or
 you can 'return;' to continue
 brk> Where();
-*[1] Error( "!\n" ); at *stdin*:3 called from
- [2] test( n + 1 ); at *stdin*:3 called from
- [3] test( n + 1 ); at *stdin*:3 called from
- [4] test( n + 1 ); at *stdin*:3 called from
+*[1] Error( "!\n" );
+   @ *stdin*:4
+ [2] test( n + 1 );
+   @ *stdin*:4
+ [3] test( n + 1 );
+   @ *stdin*:4
+ [4] test( n + 1 );
+   @ *stdin*:4
 <function "test">( <arguments> )
  called from read-eval loop at *errin*:1
 brk> n;
@@ -848,20 +853,28 @@ brk> DownEnv();
 brk> n;
 3
 brk> Where();
- [1] Error( "!\n" ); at *stdin*:3 called from
-*[2] test( n + 1 ); at *stdin*:3 called from
- [3] test( n + 1 ); at *stdin*:3 called from
- [4] test( n + 1 ); at *stdin*:3 called from
+ [1] Error( "!\n" );
+   @ *stdin*:4
+*[2] test( n + 1 );
+   @ *stdin*:4
+ [3] test( n + 1 );
+   @ *stdin*:4
+ [4] test( n + 1 );
+   @ *stdin*:4
 <function "test">( <arguments> )
  called from read-eval loop at *errin*:5
 brk> DownEnv( 2 );
 brk> n;
 1
 brk> Where();
- [1] Error( "!\n" ); at *stdin*:3 called from
- [2] test( n + 1 ); at *stdin*:3 called from
- [3] test( n + 1 ); at *stdin*:3 called from
-*[4] test( n + 1 ); at *stdin*:3 called from
+ [1] Error( "!\n" );
+   @ *stdin*:4
+ [2] test( n + 1 );
+   @ *stdin*:4
+ [3] test( n + 1 );
+   @ *stdin*:4
+*[4] test( n + 1 );
+   @ *stdin*:4
 <function "test">( <arguments> )
  called from read-eval loop at *errin*:8
 brk> DownEnv( -2 );
@@ -894,10 +907,13 @@ gap> fun := function() local x; x := 3; bar(); end;
 function(  ) ... end
 gap> fun();
 Error, !!
- called from
-bar(  ); called from
-<function>( <arguments> ) called from read-eval-loop
-Entering break read-eval-print loop ...
+Stack trace:
+*[1] Error( "!!\n" );
+   @ *stdin*:4
+ [2] bar(  );
+   @ *stdin*:7
+<function "fun">( <arguments> )
+ called from read-eval loop at *stdin*:8
 you can 'quit;' to quit to outer loop, or
 you can 'return;' to continue
 brk> x;

doc/tut/group.xml

@@ -927,11 +927,12 @@ gap> Size( Image( hom, DerivedSubgroup(s4) ) );
 <P/>
 <Log><![CDATA[
 gap> PreImage( hom, (1,2,3) );
-Error, <map> must be an inj. and surj. mapping called from
+Error, <map> must be an injective and surjective mapping
+*[1] ErrorNoReturn( "<map> must be an injective and surjective ", "mapping" );
+   @ GAPROOT/lib/mapping.gi:262
 <function "PreImage">( <arguments> )
- called from read-eval loop at line 4 of *stdin*
-you can 'quit;' to quit to outer loop, or
-you can 'return;' to continue
+ called from read-eval loop at *stdin*:7
+type 'quit;' to quit to outer loop
 brk> quit;
 ]]></Log>
 <P/>
@@ -1258,4 +1259,3 @@ Chapter&nbsp;<Ref Chap="Group Homomorphisms" BookName="ref"/>.
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <!-- %% -->
 <!-- %E -->
-

doc/tut/introduc.xml

@@ -253,8 +253,8 @@ We will no longer mention the <B>Return</B> key from now on.
 <Index>break loops</Index>
 Sometimes a syntax error will cause &GAP; to enter a <E>break loop</E>.  This
 is indicated by the special prompt <C>brk></C>. If another syntax error occurs
-while  &GAP; is in  a break loop, the prompt  will  change to <C>brk_02></C>,
-<C>brk_03></C> and so on. You can leave the current break loop and exit to the
+while  &GAP; is in  a break loop, the prompt  will  change to <C>brk_2></C>,
+<C>brk_3></C> and so on. You can leave the current break loop and exit to the
 next outer one by either typing <C>quit;</C> or by hitting <B>Ctrl-D</B>.
 Eventually &GAP; will return to its normal state and show its normal
 prompt <C>gap></C> again.