This file is indexed.

/usr/share/gap/doc/ref/chap6.html is in gap-doc 4r8p6-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (ref) - Chapter 6: Main Loop and Break Loop</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap6"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap5.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap7.html">[Next Chapter]</a>&nbsp;  </div>

<p id="mathjaxlink" class="pcenter"><a href="chap6_mj.html">[MathJax on]</a></p>
<p><a id="X7DB71A2A841CADA5" name="X7DB71A2A841CADA5"></a></p>
<div class="ChapSects"><a href="chap6.html#X7DB71A2A841CADA5">6 <span class="Heading">Main Loop and Break Loop</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X81667F568237B232">6.1 <span class="Heading">Main Loop</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X866092F281910B74">6.2 <span class="Heading">Special Rules for Input Lines</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X8074A8387C9DB9A8">6.3 <span class="Heading">View and Print</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X8082880F824292E9">6.3-1 <span class="Heading">Default delegations in the library</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X87D445D37B31DADB">6.3-2 <span class="Heading">Recommendations for the implementation</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X851902C583B84CDC">6.3-3 View</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7AFA64D97A1F39A3">6.3-4 Print</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X815BF22186FD43C9">6.3-5 ViewObj</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X83A5C59278E13248">6.3-6 Display</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X87E546E27A1F1FAB">6.3-7 SetNameObject</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X8593B49F8705B486">6.4 <span class="Heading">Break Loops</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X83033EEB81CF4F49">6.4-1 <span class="Heading">quit from a break loop</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7A388B808167FE09">6.4-2 <span class="Heading">return from a break loop</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X82EBF01181C3C859">6.4-3 OnBreak</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X80711C807C99C220">6.4-4 OnBreakMessage</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7A7FFA2B7C1EF5A3">6.4-5 Where</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X7EE5CF2C8419F061">6.5 <span class="Heading">Variable Access in a Break Loop</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X79E66DA2875303B0">6.5-1 <span class="Heading">DownEnv and UpEnv</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X7BC8D2E37ADE9062">6.6 <span class="Heading">Error and ErrorCount</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7E7AD8D87EBA1A08">6.6-1 Error</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7A5C000D7E4984DD">6.6-2 ErrorNoReturn</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X86A11BCC7FECEEA4">6.6-3 ErrorCount</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X83704B1080FD9B40">6.7 <span class="Heading">Leaving GAP</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7ECC75048583853B">6.7-1 QUIT</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7F5DDF5A80CFE6C2">6.7-2 GAP_EXIT_CODE</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7B56D486842496DB">6.7-3 QUIT_GAP</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X85804CF082AFF6AE">6.7-4 FORCE_QUIT_GAP</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7A2C380986F46FEE">6.7-5 InstallAtExit</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X843C07A4869EAA1D">6.7-6 SaveOnExitFile</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X82234FD181899530">6.8 <span class="Heading">Line Editing</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X7E95EB017803F53C">6.9 <span class="Heading">Editing using the <code class="code">readline</code> library</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7C38F9E0783D9442">6.9-1 <span class="Heading">Readline customization</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X846C3DED84AD7593">6.9-2 <span class="Heading">The command line history</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7C1F4D04861C1197">6.9-3 SaveCommandLineHistory</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X87D4EA197A263FB7">6.9-4 <span class="Heading">Writing your own command line editing functions</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X7D8E1CF47E97A764">6.10 <span class="Heading">Editing Files</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X82E5859C8113BA4D">6.10-1 Edit</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X7B67FF1E87FE67D1">6.11 <span class="Heading">Editor Support</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X83279E897ACCFFFA">6.12 <span class="Heading">Changing the Screen Size</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X8723E0A1837894F3">6.12-1 SizeScreen</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap6.html#X87847E5087D6F47D">6.13 <span class="Heading">Teaching Mode</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap6.html#X7BE2515F82425404">6.13-1 TeachingMode</a></span>
</div></div>
</div>

<h3>6 <span class="Heading">Main Loop and Break Loop</span></h3>

<p>This chapter is a first of a series of chapters that describe the interactive environment in which you use <strong class="pkg">GAP</strong>.</p>

<p><a id="X81667F568237B232" name="X81667F568237B232"></a></p>

<h4>6.1 <span class="Heading">Main Loop</span></h4>

<p>The normal interaction with <strong class="pkg">GAP</strong> happens in the so-called <em>read-eval-print</em> loop. This means that you type an input, <strong class="pkg">GAP</strong> first reads it, evaluates it, and then shows the result. Note that the term <em>print</em> may be confusing since there is a <strong class="pkg">GAP</strong> function called <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) (see <a href="chap6.html#X8074A8387C9DB9A8"><span class="RefLink">6.3</span></a>) which is in fact <em>not</em> used in the read-eval-print loop, but traditions are hard to break. In the following, whenever we want to express that <strong class="pkg">GAP</strong> places some characters on the standard output, we will say that <strong class="pkg">GAP</strong> <em>shows</em> something.</p>

<p>The exact sequence in the read-eval-print loop is as follows.</p>

<p>To signal that it is ready to accept your input, <strong class="pkg">GAP</strong> shows the <em>prompt</em> <code class="code">gap&gt;</code>. When you see this, you know that <strong class="pkg">GAP</strong> is waiting for your input.</p>

<p>Note that every statement must be terminated by a semicolon. You must also enter <strong class="button">Return</strong> (i.e., strike the <strong class="button">Return</strong> key) before <strong class="pkg">GAP</strong> starts to read and evaluate your input. (The <strong class="button">Return</strong> key may actually be marked with the word <strong class="button">Enter</strong> and a returning arrow on your terminal.) Because <strong class="pkg">GAP</strong> does not do anything until you enter <strong class="button">Return</strong>, you can edit your input to fix typos and only when everything is correct enter <strong class="button">Return</strong> and have <strong class="pkg">GAP</strong> take a look at it (see <a href="chap6.html#X82234FD181899530"><span class="RefLink">6.8</span></a>). It is also possible to enter several statements as input on a single line. Of course each statement must be terminated by a semicolon.</p>

<p>It is absolutely acceptable to enter a single statement on several lines. When you have entered the beginning of a statement, but the statement is not yet complete, and you enter <strong class="button">Return</strong>, <strong class="pkg">GAP</strong> will show the <em>partial prompt</em> <code class="code">&gt;</code>. When you see this, you know that <strong class="pkg">GAP</strong> is waiting for the rest of the statement. This happens also when you forget the semicolon <code class="code">;</code> that terminates every <strong class="pkg">GAP</strong> statement. Note that when <strong class="button">Return</strong> has been entered and the current statement is not yet complete, <strong class="pkg">GAP</strong> will already evaluate those parts of the input that are complete, for example function calls that appear as arguments in another function call which needs several input lines. So it may happen that one has to wait some time for the partial prompt.</p>

<p>When you enter <strong class="button">Return</strong>, <strong class="pkg">GAP</strong> first checks your input to see if it is syntactically correct (see Chapter <a href="chap4.html#X7FE7C0C17E1ED118"><span class="RefLink">4</span></a> for the definition of syntactically correct). If it is not, <strong class="pkg">GAP</strong> prints an error message of the following form</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">1 * ;</span>
Syntax error: expression expected
1 * ;
    ^
</pre></div>

<p>The first line tells you what is wrong about the input, in this case the <code class="code">*</code> operator takes two expressions as operands, so obviously the right one is missing. If the input came from a file (see <code class="func">Read</code> (<a href="chap9.html#X8373AC6B7D5F9167"><span class="RefLink">9.7-1</span></a>)), this line will also contain the filename and the line number. The second line is a copy of the input. And the third line contains a caret pointing to the place in the previous line where <strong class="pkg">GAP</strong> realized that something is wrong. This need not be the exact place where the error is, but it is usually quite close.</p>

<p>Sometimes, you will also see a partial prompt after you have entered an input that is syntactically incorrect. This is because <strong class="pkg">GAP</strong> is so confused by your input, that it thinks that there is still something to follow. In this case you should enter <code class="code">;</code><strong class="button">Return</strong> repeatedly, ignoring further error messages, until you see the full prompt again. When you see the full prompt, you know that <strong class="pkg">GAP</strong> forgave you and is now ready to accept your next –hopefully correct– input.</p>

<p>If your input is syntactically correct, <strong class="pkg">GAP</strong> evaluates or executes it, i.e., performs the required computations (see Chapter <a href="chap4.html#X7FE7C0C17E1ED118"><span class="RefLink">4</span></a> for the definition of the evaluation).</p>

<p>If you do not see a prompt, you know that <strong class="pkg">GAP</strong> is still working on your last input. Of course, you can <em>type ahead</em>, i.e., already start entering new input, but it will not be accepted by <strong class="pkg">GAP</strong> until <strong class="pkg">GAP</strong> has completed the ongoing computation.</p>

<p>When <strong class="pkg">GAP</strong> is ready it will usually show the result of the computation, i.e., the value computed. Note that not all statements produce a value, for example, if you enter a <code class="keyw">for</code> loop, nothing will be printed, because the <code class="keyw">for</code> loop does not produce a value that could be shown.</p>

<p>Also sometimes you do not want to see the result. For example if you have computed a value and now want to assign the result to a variable, you probably do not want to see the value again. You can terminate statements by <em>two semicolons</em> to suppress showing the result.</p>

<p>If you have entered several statements on a single line <strong class="pkg">GAP</strong> will first read, evaluate, and show the first one, then read, evaluate, and show the second one, and so on. This means that the second statement will not even be checked for syntactical correctness until <strong class="pkg">GAP</strong> has completed the first computation.</p>

<p>After the result has been shown <strong class="pkg">GAP</strong> will display another prompt, and wait for your next input. And the whole process starts all over again. Note that if you have entered several statements on a single line, a new prompt will only be printed after <strong class="pkg">GAP</strong> has read, evaluated, and shown the last statement.</p>

<p>In each statement that you enter, the result of the previous statement that produced a value is available in the variable <code class="code">last</code>. The next to previous result is available in <code class="code">last2</code> and the result produced before that is available in <code class="code">last3</code>.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">1;2;3;</span>
1
2
3
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">last3 + last2 * last;</span>
7
</pre></div>

<p>Also in each statement the time spent by the last statement, whether it produced a value or not, is available in the variable <code class="func">time</code> (<a href="chap7.html#X7C0F91F982189624"><span class="RefLink">7.6-3</span></a>). This is an integer that holds the number of milliseconds.</p>

<p><a id="X866092F281910B74" name="X866092F281910B74"></a></p>

<h4>6.2 <span class="Heading">Special Rules for Input Lines</span></h4>

<p>The input for some <strong class="pkg">GAP</strong> objects may not fit on one line, in particular big integers, long strings or long identifiers. In these cases you can still type or paste them in long single lines. For nicer display you can also specify the input on several lines. This is achieved by ending a line by a backslash or by a backslash and a carriage return character, then continue the input on the beginning of the next line. When reading this <strong class="pkg">GAP</strong> will ignore such continuation backslashes, carriage return characters and newline characters. <strong class="pkg">GAP</strong> also prints long strings and integers this way.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">n := 1234\</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">567890;</span>
1234567890
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">"This is a very long string that does not fit on a line \</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">and is therefore continued on the next line.";</span>
"This is a very long string that does not fit on a line and is therefo\
re continued on the next line."
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">bla\</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">bla := 5;; blabla;</span>
5
</pre></div>

<p>There is a special rule about <strong class="pkg">GAP</strong> prompts in input lines: In line editing mode (usual user input and <strong class="pkg">GAP</strong> started without <code class="code">-n</code>) in lines starting with whitespace following <code class="code">gap&gt; </code>, <code class="code">&gt; </code> or <code class="code">brk&gt; </code> this beginning part is removed. This rule is very convenient because it allows to cut and paste input from other <strong class="pkg">GAP</strong> sessions or manual examples easily into your current session.</p>

<p><a id="X8074A8387C9DB9A8" name="X8074A8387C9DB9A8"></a></p>

<h4>6.3 <span class="Heading">View and Print</span></h4>

<p><strong class="pkg">GAP</strong> has three different operations to display or print objects: <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>), <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) and <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>), and these three have different purposes as follows. The first, <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>), should print the object to the standard output in a human-readable relatively complete and verbose form. The second, <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>), should print the object to the standard output in a short and concise form, it is used in the main read-eval-print loop to display the resulting object of a computation. The third, <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>), should print the object to the standard output in a complete form which is <strong class="pkg">GAP</strong>-readable if at all possible, such that reading the output into <strong class="pkg">GAP</strong> produces an object which is equal to the original one.</p>

<p>All three operations have corresponding operations which do not print anything to standard output but return the output as a string. These are <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>), <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) and <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) (corresponding to <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>)). Additionally, there is <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) which is very similar to <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) but does not insert control characters for line breaks.</p>

<p>For implementation convenience it is allowed that some of these operations have methods which delegate to some other of these operations. However, the rules for this are that a method may only delegate to another operation which appears further down in the following table:</p>

<div class="pcenter"><table class="GAPDocTable">
<tr>
<td class="tdcenter"><code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>)</td>
</tr>
<tr>
<td class="tdcenter"><code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>)</td>
</tr>
<tr>
<td class="tdcenter"><code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>)</td>
</tr>
<tr>
<td class="tdcenter"><code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>)</td>
</tr>
<tr>
<td class="tdcenter"><code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>)</td>
</tr>
<tr>
<td class="tdcenter"><code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>)</td>
</tr>
<tr>
<td class="tdcenter"><code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>)</td>
</tr>
</table><br /><p>&nbsp;</p><br />
</div>

<p>This is to avoid circular delegations.</p>

<p>Note in particular that none of the methods of the string producing operations may delegate to the corresponding printing operations. Note also that the above mentioned purposes of the different operations suggest that delegations between different operations will be sub-optimal in most scenarios.</p>

<p><a id="X8082880F824292E9" name="X8082880F824292E9"></a></p>

<h5>6.3-1 <span class="Heading">Default delegations in the library</span></h5>

<p>The library contains the following low ranked default methods:</p>


<ul>
<li><p>A method for <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) which returns the constant value of the global variable <code class="func">DEFAULTDISPLAYSTRING</code> (<a href="chap27.html#X8482132779EA7A23"><span class="RefLink">27.7-2</span></a>).</p>

</li>
<li><p>A method for <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) which returns the constant value of the global variable <code class="func">DEFAULTVIEWSTRING</code> (<a href="chap27.html#X7BBDF9D383595425"><span class="RefLink">27.7-4</span></a>).</p>

</li>
<li><p>A method for <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) which first calls <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) and prints the result, if it is a different object than <code class="func">DEFAULTDISPLAYSTRING</code> (<a href="chap27.html#X8482132779EA7A23"><span class="RefLink">27.7-2</span></a>). Otherwise the method delegates to <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>).</p>

</li>
<li><p>A method for <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) which first calls <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) and prints the result, if it is a different object than <code class="func">DEFAULTVIEWSTRING</code> (<a href="chap27.html#X7BBDF9D383595425"><span class="RefLink">27.7-4</span></a>). Otherwise the method delegates to <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>).</p>

</li>
<li><p>A method for <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) which prints the result of <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>).</p>

</li>
<li><p>A method for <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) which returns the result of <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>)</p>

</li>
</ul>
<p><a id="X87D445D37B31DADB" name="X87D445D37B31DADB"></a></p>

<h5>6.3-2 <span class="Heading">Recommendations for the implementation</span></h5>

<p>This subsection describes what methods for printing and viewing one should implement for new <strong class="pkg">GAP</strong> objects.</p>

<p>One should at the very least install a <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) method to allow printing. Using the standard delegations this enables a limited form of viewing, displaying and printing.</p>

<p>If, for larger objects, nicer line breaks are needed, one should install a separate <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) method which puts in positions for good line breaks using the control characters <code class="code">\&lt;</code> (ASCII 1) and <code class="code">\&gt;</code> (ASCII 2).</p>

<p>If, for even larger objects, output performance and memory usage matters, one should install a separate <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) method.</p>

<p>One should usually install a <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) method, unless the above <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) method is good enough for <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) purposes. Performance and memory should never matter here, so it is usually unnecessary to install a separate <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) method.</p>

<p>If the type of object calls for it one should install a <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) method. This is the case if a human readable verbose form is required.</p>

<p>If the performance and memory usage for <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) matters, one should install a separate <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) method.</p>

<p>Note that if only a <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) method is installed, then <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) works and <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) returns <code class="func">DEFAULTVIEWSTRING</code> (<a href="chap27.html#X7BBDF9D383595425"><span class="RefLink">27.7-4</span></a>). Likewise, <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) works and <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) returns <code class="func">DEFAULTDISPLAYSTRING</code> (<a href="chap27.html#X8482132779EA7A23"><span class="RefLink">27.7-2</span></a>). If you want to avoid this then install methods for these operations as well.</p>

<p><a id="X851902C583B84CDC" name="X851902C583B84CDC"></a></p>

<h5>6.3-3 View</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; View</code>( <var class="Arg">obj1</var>, <var class="Arg">obj2...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">View</code> shows the objects <var class="Arg">obj1</var>, <var class="Arg">obj2</var>... etc. <em>in a short form</em> on the standard output by calling the <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) operation on each of them. <code class="func">View</code> is called in the read-eval-print loop, thus the output looks exactly like the representation of the objects shown by the main loop. Note that no space or newline is printed between the objects.</p>

<p><a id="X7AFA64D97A1F39A3" name="X7AFA64D97A1F39A3"></a></p>

<h5>6.3-4 Print</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Print</code>( <var class="Arg">obj1</var>, <var class="Arg">obj2</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Also <code class="func">Print</code> shows the objects <var class="Arg">obj1</var>, <var class="Arg">obj2</var>... etc. on the standard output. The difference compared to <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) is in general that the shown form is not required to be short, and that in many cases the form shown by <code class="func">Print</code> is <strong class="pkg">GAP</strong> readable.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">z:= Z(2);</span>
Z(2)^0
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">v:= [ z, z, z, z, z, z, z ];</span>
[ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ConvertToVectorRep(v);; v;</span>
&lt;a GF2 vector of length 7&gt;
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Print( v, "\n" );</span>
[ Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0, Z(2)^0 ]
</pre></div>

<p>Another difference is that <code class="func">Print</code> shows strings without the enclosing quotes, so <code class="func">Print</code> can be used to produce formatted text on the standard output (see also chapter <a href="chap27.html#X7D28329B7EDB8F47"><span class="RefLink">27</span></a>). Some characters preceded by a backslash, such as <code class="code">\n</code>, are processed specially (see chapter <a href="chap27.html#X82E5F5AB818F32DB"><span class="RefLink">27.2</span></a>). <code class="func">PrintTo</code> (<a href="chap9.html#X86956C577FFEE1F9"><span class="RefLink">9.7-3</span></a>) can be used to print to a file.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">for i in [1..5] do</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     Print( i, " ", i^2, " ", i^3, "\n" );</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">   od;</span>
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">g:= SmallGroup(12,5);</span>
&lt;pc group of size 12 with 3 generators&gt;
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Print( g, "\n" );</span>
Group( [ f1, f2, f3 ] )
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">View( g );  Print( "\n" );</span>
&lt;pc group of size 12 with 3 generators&gt;
</pre></div>

<p><a id="X815BF22186FD43C9" name="X815BF22186FD43C9"></a></p>

<h5>6.3-5 ViewObj</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ViewObj</code>( <var class="Arg">obj</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PrintObj</code>( <var class="Arg">obj</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>The functions <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) and <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) actually call the operations <code class="func">ViewObj</code> and <code class="func">PrintObj</code>, respectively, for each argument. By installing special methods for these operations, it is possible to achieve special printing behavior for certain objects (see chapter <a href="chap78.html#X8058CC8187162644"><span class="RefLink">78</span></a>). The only exceptions are strings (see Chapter <a href="chap27.html#X7D28329B7EDB8F47"><span class="RefLink">27</span></a>), for which the default <code class="func">PrintObj</code> and <code class="func">ViewObj</code> methods as well as the function <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) print also the enclosing doublequotes, whereas <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) strips the doublequotes.</p>

<p>The default method for <code class="func">ViewObj</code> is to call <code class="func">PrintObj</code>. So it is sufficient to have a <code class="func">PrintObj</code> method for an object in order to <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) it. If one wants to supply a "short form" for <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>), one can install additionally a method for <code class="func">ViewObj</code>.</p>

<p><a id="X83A5C59278E13248" name="X83A5C59278E13248"></a></p>

<h5>6.3-6 Display</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Display</code>( <var class="Arg">obj</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>Displays the object <var class="Arg">obj</var> in a nice, formatted way which is easy to read (but might be difficult for machines to understand). The actual format used for this depends on the type of <var class="Arg">obj</var>. Each method should print a newline character as last character.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Display( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] * Z(5) );</span>
 2 4 1
 3 . 2
</pre></div>

<p>One can assign a string to an object that <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) will use instead of the default used by <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>), via <code class="func">SetName</code> (<a href="chap12.html#X85D6D47B83BD02A1"><span class="RefLink">12.8-1</span></a>). Also, <code class="func">Name</code> (<a href="chap12.html#X7F14EF9D81432113"><span class="RefLink">12.8-2</span></a>) returns the string previously assigned to the object for printing, via <code class="func">SetName</code> (<a href="chap12.html#X85D6D47B83BD02A1"><span class="RefLink">12.8-1</span></a>). The following is an example in the context of domains.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">g:= Group( (1,2,3,4) );</span>
Group([ (1,2,3,4) ])
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetName( g, "C4" ); g;</span>
C4
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Name( g );</span>
"C4"
</pre></div>

<p>When setting up examples, in particular if for beginning users, it sometimes can be convenient to hide the structure behind a printing name. For many objects, such as groups, this can be done using <code class="func">SetName</code> (<a href="chap12.html#X85D6D47B83BD02A1"><span class="RefLink">12.8-1</span></a>). If the objects however is represented internally, for example permutations representing group elements, this function is not applicable. Instead the function <code class="func">SetNameObject</code> (<a href="chap6.html#X87E546E27A1F1FAB"><span class="RefLink">6.3-7</span></a>) can be used to interface with the display routines on a lower level.</p>

<p><a id="X87E546E27A1F1FAB" name="X87E546E27A1F1FAB"></a></p>

<h5>6.3-7 SetNameObject</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SetNameObject</code>( <var class="Arg">o</var>, <var class="Arg">s</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">SetNameObject</code> sets the string <var class="Arg">s</var> as display name for object <var class="Arg">o</var> in an interactive session. When applying <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) to object <var class="Arg">o</var>, for example in the system's main loop, <strong class="pkg">GAP</strong> will print the string <var class="Arg">s</var>. Calling <code class="func">SetNameObject</code> for the same object <var class="Arg">o</var> with <var class="Arg">s</var> set to <code class="code">fail</code> deletes the special viewing setup. since use of this features potentially slows down the whole print process, this function should be used sparingly.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetNameObject(3,"three"); </span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Filtered([1..10],IsPrimeInt);</span>
[ 2, three, 5, 7 ]
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">SetNameObject(3,fail);   </span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Filtered([1..10],IsPrimeInt);</span>
[ 2, 3, 5, 7 ]
</pre></div>

<p><a id="X8593B49F8705B486" name="X8593B49F8705B486"></a></p>

<h4>6.4 <span class="Heading">Break Loops</span></h4>

<p>When an error has occurred or when you interrupt <strong class="pkg">GAP</strong> (usually by hitting <strong class="button">Ctrl-C</strong>) <strong class="pkg">GAP</strong> enters a break loop, that is in most respects like the main read eval print loop (see <a href="chap6.html#X81667F568237B232"><span class="RefLink">6.1</span></a>). That is, you can enter statements, <strong class="pkg">GAP</strong> reads them, evaluates them, and shows the result if any. However those evaluations happen within the context in which the error occurred. So you can look at the arguments and local variables of the functions that were active when the error happened and even change them. The prompt is changed from <code class="code">gap&gt;</code> to <code class="code">brk&gt;</code> to indicate that you are in a break loop.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">1/0;</span>
Rational operations: &lt;divisor&gt; 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 &lt;divisor&gt; via 'return &lt;divisor&gt;;' to continue
</pre></div>

<p>If errors occur within a break loop <strong class="pkg">GAP</strong> enters another break loop at a <em>deeper level</em>. This is indicated by a number appended to <code class="code">brk</code>:</p>


<div class="example"><pre>
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">1/0;</span>
Rational operations: &lt;divisor&gt; 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 &lt;divisor&gt; via 'return &lt;divisor&gt;;' to continue
<span class="GAPbrkprompt">brk_02&gt;</span>
</pre></div>

<p>There are two ways to leave a break loop, see <a href="chap6.html#X83033EEB81CF4F49"><span class="RefLink">6.4-1</span></a> and <a href="chap6.html#X7A388B808167FE09"><span class="RefLink">6.4-2</span></a>.</p>

<p><a id="X83033EEB81CF4F49" name="X83033EEB81CF4F49"></a></p>

<h5>6.4-1 <span class="Heading">quit from a break loop</span></h5>

<p>The first way to leave a break loop is to <em>quit</em> the break loop. To do this you enter <code class="code">quit;</code> or type the <em>eof</em> (<em>e</em>nd <em>o</em>f <em>f</em>ile) character, which is usually <strong class="button">Ctrl-D</strong> except when using the <code class="code">-e</code> option (see Section <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>). Note that <strong class="pkg">GAP</strong> code between <code class="code">quit;</code> and the end of the input line is ignored.</p>


<div class="example"><pre>
<span class="GAPbrkprompt">brk_02&gt;</span> <span class="GAPinput">quit;</span>
<span class="GAPbrkprompt">brk&gt;</span>
</pre></div>

<p>In this case control returns to the break loop one level above or to the main loop, respectively. So iterated break loops must be left iteratively. Note also that if you type <code class="code">quit;</code> from a <code class="code">gap&gt;</code> prompt, <strong class="pkg">GAP</strong> will exit (see <a href="chap6.html#X83704B1080FD9B40"><span class="RefLink">6.7</span></a>).</p>

<p><em>Note:</em> If you leave a break loop with <code class="keyw">quit</code> without completing a command it is possible (though not very likely) that data structures will be corrupted or incomplete data have been stored in objects. Therefore no guarantee can be given that calculations afterwards will return correct results! If you have been using options <code class="keyw">quit</code>ting a break loop generally leaves the options stack with options you no longer want. The function <code class="func">ResetOptionsStack</code> (<a href="chap8.html#X83D1190984DA3B85"><span class="RefLink">8.1-3</span></a>) removes all options on the options stack, and this is the sole intended purpose of this function.</p>

<p><a id="X7A388B808167FE09" name="X7A388B808167FE09"></a></p>

<h5>6.4-2 <span class="Heading">return from a break loop</span></h5>

<p>The other way to leave a break loop is to <em>return</em> from a break loop. To do this you type <code class="code">return;</code> or <code class="code">return <var class="Arg">obj</var>;</code>. If the break loop was entered because you interrupted <strong class="pkg">GAP</strong>, then you can continue by typing <code class="code">return;</code>. If the break loop was entered due to an error, you may have to modify the value of a variable before typing <code class="code">return;</code> (see the example for <code class="func">IsDenseList</code> (<a href="chap21.html#X870AA9D8798C93DD"><span class="RefLink">21.1-2</span></a>)) or you may have to return an object <var class="Arg">obj</var> (by typing: <code class="code">return <var class="Arg">obj</var>;</code>) to continue the computation; in any case, the message printed on entering the break loop will tell you which of these alternatives is possible. For example, if the break loop was entered because a variable had no assigned value, the value to be returned is often a value that this variable should have to continue the computation.</p>


<div class="example"><pre>
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">return 9;  # we had tried to enter the divisor 9 but typed 0 ...</span>
1/9
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput"></span>
</pre></div>

<p><a id="X82EBF01181C3C859" name="X82EBF01181C3C859"></a></p>

<h5>6.4-3 OnBreak</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; OnBreak</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>By default, when a break loop is entered, <strong class="pkg">GAP</strong> prints a trace of the innermost 5 commands currently being executed. This behaviour can be configured by changing the value of the global variable <code class="func">OnBreak</code>. When a break loop is entered, the value of <code class="func">OnBreak</code> is checked. If it is a function, then it is called with no arguments. By default, the value of <code class="func">OnBreak</code> is <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreak := function() Print("Hello\n"); end;</span>
function(  ) ... end
</pre></div>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Error("!\n");</span>
Error, !
Hello
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">quit;</span>
</pre></div>

<p>In cases where a break loop is entered during a function that was called with options (see Chapter <a href="chap8.html#X7FD84061873F72A2"><span class="RefLink">8</span></a>), a <code class="code">quit;</code> will also cause the options stack to be reset and an <code class="code">Info</code>-ed warning stating this is emitted at <code class="func">InfoWarning</code> (<a href="chap7.html#X7A28F77C82D6A3E0"><span class="RefLink">7.4-7</span></a>) level 1 (see Chapter <a href="chap7.html#X7A9C902479CB6F7C"><span class="RefLink">7.4</span></a>).</p>

<p>Note that for break loops entered by a call to <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>), the lines after "<code class="code">Entering break read-eval-print loop ...</code>" and before the <code class="code">brk&gt;</code> prompt can also be customised, namely by redefining <code class="func">OnBreakMessage</code> (<a href="chap6.html#X80711C807C99C220"><span class="RefLink">6.4-4</span></a>).</p>

<p>Also, note that one can achieve the effect of changing <code class="func">OnBreak</code> <em>locally</em>. As mentioned above, the default value of <code class="func">OnBreak</code> is <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>). Thus, a call to <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) generally gives a trace back up to five levels of calling functions. Conceivably, we might like to have a function like <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) that does not trace back without globally changing <code class="func">OnBreak</code>. Such a function we might call <code class="code">ErrorNoTraceBack</code> and here is how we might define it. (Note <code class="code">ErrorNoTraceBack</code> is <em>not</em> a <strong class="pkg">GAP</strong> function.)</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ErrorNoTraceBack := function(arg) # arg is special variable that GAP</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">                                     # knows to treat as list of arg's</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     local SavedOnBreak, ENTBOnBreak;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     SavedOnBreak := OnBreak;        # save current value of OnBreak</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput"></span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     ENTBOnBreak := function()       # our `local' OnBreak</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     local s;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       for s in arg do</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">         Print(s);</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       od;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">       OnBreak := SavedOnBreak;      # restore OnBreak afterwards</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     end;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput"></span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     OnBreak := ENTBOnBreak;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">     Error();</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">   end;</span>
function( arg... ) ... end
</pre></div>

<p>Here is a somewhat trivial demonstration of the use of <code class="code">ErrorNoTraceBack</code>.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ErrorNoTraceBack("Gidday!", " How's", " it", " going?\n");</span>
Error, Gidday! How's it going?
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">quit;</span>
</pre></div>

<p>Now we call <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) with the same arguments to show the difference.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Error("Gidday!", " How's", " it", " going?\n");</span>
Error, Gidday! How's it going?
Hello
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">quit;</span>
</pre></div>

<p>Observe that the value of <code class="func">OnBreak</code> before the <code class="code">ErrorNoTraceBack</code> call was restored. However, we had changed <code class="func">OnBreak</code> from its default value; to restore <code class="func">OnBreak</code> to its default value, we should do the following.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreak := Where;;</span>
</pre></div>

<p><a id="X80711C807C99C220" name="X80711C807C99C220"></a></p>

<h5>6.4-4 OnBreakMessage</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; OnBreakMessage</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p>When a break loop is entered by a call to <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) the message after the "<code class="code">Entering break read-eval-print loop ...</code>" line is produced by the function <code class="code">OnBreakMessage</code>, which just like <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>) is a user-configurable global variable that is a <em>function</em> with <em>no arguments</em>.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreakMessage(); # By default, OnBreakMessage prints the following</span>
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
</pre></div>

<p>Perhaps you are familiar with what's possible in a break loop, and so don't need to be reminded. In this case, you might wish to do the following (the first line just makes it easy to restore the default value later).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">NormalOnBreakMessage := OnBreakMessage;; # save the default value </span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreakMessage := function() end;        # do-nothing function</span>
function(  ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreakMessage();</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreakMessage := NormalOnBreakMessage;; # reset</span>
</pre></div>

<p>With <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>) still set away from its default value, calling <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) as we did above, now produces:</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Error("!\n");</span>
Error, !
Hello
Entering break read-eval-print loop ...
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">quit; # to get back to outer loop</span>
</pre></div>

<p>However, suppose you are writing a function which detects an error condition and <code class="code">OnBreakMessage</code> needs to be changed only <em>locally</em>, i.e., the instructions on how to recover from the break loop need to be specific to that function. The same idea used to define <code class="code">ErrorNoTraceBack</code> (see <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>)) can be adapted to achieve this. The function <code class="func">CosetTableFromGensAndRels</code> (<a href="chap47.html#X7DE601F179E6FD09"><span class="RefLink">47.6-5</span></a>) is an example in the <strong class="pkg">GAP</strong> code where the idea is actually used.</p>

<p><a id="X7A7FFA2B7C1EF5A3" name="X7A7FFA2B7C1EF5A3"></a></p>

<h5>6.4-5 Where</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Where</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>shows the last <var class="Arg">nr</var> commands on the execution stack during whose execution the error occurred. If not given, <var class="Arg">nr</var> defaults to 5. (Assume, for the following example, that after the last example <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>) has been set back to its default value.)</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">StabChain(SymmetricGroup(100)); # After this we typed ^C  </span>
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
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">Where(2);</span>
 called from
SiftedPermutation( S, (g * rep) ^ -1 ) called from
StabChainStrong( S.stabilizer, [ sch ], options ); called from
...
</pre></div>

<p>Note that the variables displayed even in the first line of the <code class="func">Where</code> list (after the <code class="code">called from</code> line) may be already one environment level higher and <code class="func">DownEnv</code> (<a href="chap6.html#X79E66DA2875303B0"><span class="RefLink">6.5-1</span></a>) may be necessary to access them.</p>

<p>At the moment this backtrace does not work from within compiled code (this includes the method selection which by default is compiled into the kernel). If this creates problems for debugging, call <strong class="pkg">GAP</strong> with the <code class="code">-M</code> option (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>) to avoid loading compiled code.</p>

<p>(Function calls to <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-5</span></a>) and methods installed for binary operations are handled in a special way. In rare circumstances it is possible therefore that they do not show up in a <code class="func">Where</code> log but the log refers to the <em>last</em> proper function call that happened before.)</p>

<p>The command line option <code class="code">-T</code> to <strong class="pkg">GAP</strong> disables the break loop. This is mainly intended for testing purposes and for special applications. If this option is given then errors simply cause <strong class="pkg">GAP</strong> to return to the main loop.</p>

<p><a id="X7EE5CF2C8419F061" name="X7EE5CF2C8419F061"></a></p>

<h4>6.5 <span class="Heading">Variable Access in a Break Loop</span></h4>

<p>In a break loop access to variables of the current break level and higher levels is possible, but if the same variable name is used for different objects or if a function calls itself recursively, of course only the variable at the lowest level can be accessed.</p>

<p><a id="X79E66DA2875303B0" name="X79E66DA2875303B0"></a></p>

<h5>6.5-1 <span class="Heading">DownEnv and UpEnv</span></h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DownEnv</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; UpEnv</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">DownEnv</code> moves down <var class="Arg">nr</var> steps in the environment and allows one to inspect variables on this level; if <var class="Arg">nr</var> is negative it steps up in the environment again; <var class="Arg">nr</var> defaults to 1 if not given. <code class="func">UpEnv</code> acts similarly to <code class="func">DownEnv</code> but in the reverse direction (the mnemonic rule to remember the difference between <code class="func">DownEnv</code> and <code class="func">UpEnv</code> is the order in which commands on the execution stack are displayed by <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>)).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreak := function() Where(0); end;; # eliminate back-tracing on</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">                                      # entry to break loop</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">test:= function( n )</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">   if n &gt; 3 then Error( "!\n" ); fi; test( n+1 ); end;;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">test( 1 );</span>
Error, !
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">Where();</span>
 called from
test( n + 1 ); called from
test( n + 1 ); called from
test( n + 1 ); called from
&lt;function&gt;( &lt;arguments&gt; ) called from read-eval-loop
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">n;</span>
4
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">DownEnv();</span>
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">n;</span>
3
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">Where();</span>
 called from
test( n + 1 ); called from
test( n + 1 ); called from
&lt;function&gt;( &lt;arguments&gt; ) called from read-eval-loop
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">DownEnv( 2 );</span>
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">n;</span>
1
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">Where();</span>
 called from
&lt;function&gt;( &lt;arguments&gt; ) called from read-eval-loop
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">DownEnv( -2 );</span>
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">n;</span>
3
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">quit;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">OnBreak := Where;; # restore OnBreak to its default value</span>
</pre></div>

<p>Note that the change of the environment caused by <code class="func">DownEnv</code> only affects variable access in the break loop. If you use <code class="keyw">return</code> to continue a calculation <strong class="pkg">GAP</strong> automatically jumps to the right environment level again.</p>

<p>Note also that search for variables looks first in the chain of outer functions which enclosed the definition of a currently executing function, before it looks at the chain of calling functions which led to the current invocation of the function.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">foo := function()</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">local x; x := 1;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">return function() local y; y := x*x; Error("!!\n"); end;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">end;</span>
function(  ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">bar := foo();</span>
function(  ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">fun := function() local x; x := 3; bar(); end;</span>
function(  ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">fun();</span>
Error, !!
 called from
bar(  ); called from
&lt;function&gt;( &lt;arguments&gt; ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">x;</span>
1
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">DownEnv(1);</span>
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">x;</span>
3
</pre></div>

<p>Here the <code class="code">x</code> of <code class="code">foo</code> which contained the definition of <code class="code">bar</code> is found before that of <code class="code">fun</code> which caused its execution. Using <code class="func">DownEnv</code> we can access the <code class="code">x</code> from <code class="code">fun</code>.</p>

<p><a id="X7BC8D2E37ADE9062" name="X7BC8D2E37ADE9062"></a></p>

<h4>6.6 <span class="Heading">Error and ErrorCount</span></h4>

<p><a id="X7E7AD8D87EBA1A08" name="X7E7AD8D87EBA1A08"></a></p>

<h5>6.6-1 Error</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Error</code>( <var class="Arg">messages</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">Error</code> signals an error from within a function. First the messages <var class="Arg">messages</var> are printed, this is done exactly as if <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) (see <a href="chap6.html#X8074A8387C9DB9A8"><span class="RefLink">6.3</span></a>) were called with these arguments. Then a break loop (see <a href="chap6.html#X8593B49F8705B486"><span class="RefLink">6.4</span></a>) is entered, unless the standard error output is not connected to a terminal. You can leave this break loop with <code class="code">return;</code> to continue execution with the statement following the call to <code class="func">Error</code>. <code class="func">ErrorNoReturn</code> (<a href="chap6.html#X7A5C000D7E4984DD"><span class="RefLink">6.6-2</span></a>) operates identically to <code class="func">Error</code>, except it does not allow using <code class="code">return;</code> to continue execution.</p>

<p><a id="X7A5C000D7E4984DD" name="X7A5C000D7E4984DD"></a></p>

<h5>6.6-2 ErrorNoReturn</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ErrorNoReturn</code>( <var class="Arg">messages</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">ErrorNoReturn</code> signals an error from within a function. First the messages <var class="Arg">messages</var> are printed, this is done exactly as if <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) (see <a href="chap6.html#X8074A8387C9DB9A8"><span class="RefLink">6.3</span></a>) were called with these arguments. Then a break loop (see <a href="chap6.html#X8593B49F8705B486"><span class="RefLink">6.4</span></a>) is entered, unless the standard error output is not connected to a terminal. This break loop can only be exited with <code class="code">quit;</code>. The function differs from <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) by not allowing execution to continue.</p>

<p><a id="X86A11BCC7FECEEA4" name="X86A11BCC7FECEEA4"></a></p>

<h5>6.6-3 ErrorCount</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ErrorCount</code>(  )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">ErrorCount</code> returns a count of the number of errors (including user interruptions) which have occurred in the <strong class="pkg">GAP</strong> session so far. This count is reduced modulo <span class="SimpleMath">2^28</span> on <span class="SimpleMath">32</span> bit systems, <span class="SimpleMath">2^60</span> on <span class="SimpleMath">64</span> bit systems. The count is incremented by each error, even if <strong class="pkg">GAP</strong> was started with the <code class="code">-T</code> option to disable the break loop.</p>

<p><a id="X83704B1080FD9B40" name="X83704B1080FD9B40"></a></p>

<h4>6.7 <span class="Heading">Leaving GAP</span></h4>

<p>The normal way to terminate a <strong class="pkg">GAP</strong> session is to enter either <code class="code">quit;</code> (note the semicolon) or an end-of-file character (usually <strong class="button">Ctrl-D</strong>) at the <code class="code">gap&gt; </code> prompt in the main read eval print loop.</p>

<p><a id="X7ECC75048583853B" name="X7ECC75048583853B"></a></p>

<h5>6.7-1 QUIT</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; QUIT</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>An emergency way to leave <strong class="pkg">GAP</strong> is to enter <code class="keyw">QUIT</code> at any <code class="code">gap&gt;</code> or <code class="code">brk&gt;</code> or <code class="code">brk_<var class="Arg">nn</var>&gt;</code> prompt.</p>

<p><a id="X7F5DDF5A80CFE6C2" name="X7F5DDF5A80CFE6C2"></a></p>

<h5>6.7-2 GAP_EXIT_CODE</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; GAP_EXIT_CODE</code>( <var class="Arg">ret</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>A <code class="code">GAP_EXIT_CODE</code> sets the return value which will be used when <strong class="pkg">GAP</strong> exits. This may be an integer, or a boolean (where <code class="keyw">true</code> is interpreted as 0, and <code class="keyw">false</code> is interpreted as 1.</p>

<p><a id="X7B56D486842496DB" name="X7B56D486842496DB"></a></p>

<h5>6.7-3 QUIT_GAP</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; QUIT_GAP</code>( [<var class="Arg">ret</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>A <code class="code">QUIT_GAP</code> acts similarly to the keyword <code class="code">quit</code>. It exits <strong class="pkg">GAP</strong> cleanly, calling any function installed using <code class="code">InstallAtExit</code>. The optional argument will be passed to <code class="code">GAP_EXIT_CODE</code>.</p>

<p><a id="X85804CF082AFF6AE" name="X85804CF082AFF6AE"></a></p>

<h5>6.7-4 FORCE_QUIT_GAP</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; FORCE_QUIT_GAP</code>( [<var class="Arg">ret</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>A <code class="code">FORCE_QUIT_GAP</code> is similar to <code class="code">QUIT_GAP</code>, except it ignores any functions installed with <code class="code">InstallAtExit</code>, or any other functions normally run at GAP exit, and exits GAP immediately. The optional argument will be passed to <code class="code">GAP_EXIT_CODE</code>.</p>

<p><a id="X7A2C380986F46FEE" name="X7A2C380986F46FEE"></a></p>

<h5>6.7-5 InstallAtExit</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; InstallAtExit</code>( <var class="Arg">func</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; QUITTING</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>Before actually terminating, <strong class="pkg">GAP</strong> will call (with no arguments) all of the functions that have been installed using <code class="code">InstallAtExit</code>. These typically perform tasks such as cleaning up temporary files created during the session, and closing open files. If an error occurs during the execution of one of these functions, that function is simply abandoned, no break loop is entered.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">InstallAtExit(function() Print("bye\n"); end);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">quit;</span>
bye
</pre></div>

<p>During execution of these functions, the global variable <code class="code">QUITTING</code> will be set to <code class="keyw">true</code> if <strong class="pkg">GAP</strong> is exiting because the user typed <code class="keyw">QUIT</code> and <code class="keyw">false</code> otherwise. Since <code class="keyw">QUIT</code> is considered as an emergency measure, different action may be appropriate.</p>

<p><a id="X843C07A4869EAA1D" name="X843C07A4869EAA1D"></a></p>

<h5>6.7-6 SaveOnExitFile</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SaveOnExitFile</code></td><td class="tdright">( global variable )</td></tr></table></div>
<p>If, when <strong class="pkg">GAP</strong> is exiting due to a <code class="keyw">quit</code> or end-of-file (i.e. not due to a <code class="keyw">QUIT</code>) the variable <code class="func">SaveOnExitFile</code> is bound to a string value, then the system will try to save the workspace to that file.</p>

<p><a id="X82234FD181899530" name="X82234FD181899530"></a></p>

<h4>6.8 <span class="Heading">Line Editing</span></h4>

<p>In most installations <strong class="pkg">GAP</strong> will be compiled to use the Gnu readline library (see the line <code class="code">Libs used:</code> on <strong class="pkg">GAP</strong> startup). In that case skip to the next section <a href="chap6.html#X7E95EB017803F53C"><span class="RefLink">6.9</span></a>. (The line editing commands described in the rest of this section were available in previous versions of <strong class="pkg">GAP</strong>, they will work almost the same in the standard configuration of the Gnu readline library.)</p>

<p><strong class="pkg">GAP</strong> allows one you to edit the current input line with a number of editing commands. Those commands are accessible either as <em>control keys</em> or as <em>escape keys</em>. You enter a control key by pressing the <strong class="button">Ctrl</strong> key, and, while still holding the <strong class="button">Ctrl</strong> key down, hitting another key <code class="code">key</code>. You enter an escape key by hitting <strong class="button">Esc</strong> and then hitting another key <code class="code">key</code>. Below we denote control keys by <strong class="button">Ctrl-</strong><code class="code">key</code> and escape keys by <strong class="button">Esc-</strong><code class="code">key</code>. The case of <code class="code">key</code> does not matter, i.e., <strong class="button">Ctrl-A</strong> and <strong class="button">Ctrl-a</strong> are equivalent.</p>

<p>Normally, line editing will be enabled if the input is connected to a terminal. Line editing can be enabled or disabled using the command line options <code class="code">-f</code> and <code class="code">-n</code> respectively (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>), however this is a machine dependent feature of <strong class="pkg">GAP</strong>.</p>

<p>Typing <strong class="button">Ctrl-key</strong> or <strong class="button">Esc-key</strong> for characters not mentioned below always inserts <strong class="button">Ctrl-</strong><code class="code">key</code> resp. <strong class="button">Esc-</strong><code class="code">key</code> at the current cursor position.</p>

<p>The first few commands allow you to move the cursor on the current line.</p>


<dl>
<dt><strong class="Mark"><strong class="button">Ctrl-A</strong></strong></dt>
<dd><p>move the cursor to the beginning of the line.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-B</strong></strong></dt>
<dd><p>move the cursor to the beginning of the previous word.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-B</strong></strong></dt>
<dd><p>move the cursor backward one character.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-F</strong></strong></dt>
<dd><p>move the cursor forward one character.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-F</strong></strong></dt>
<dd><p>move the cursor to the end of the next word.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-E</strong></strong></dt>
<dd><p>move the cursor to the end of the line.</p>

</dd>
</dl>
<p>The next commands delete or kill text. The last killed text can be reinserted, possibly at a different position, with the "yank" command <strong class="button">Ctrl-Y</strong>.</p>


<dl>
<dt><strong class="Mark"><strong class="button">Ctrl-H</strong> or <var class="Arg">del</var></strong></dt>
<dd><p>delete the character left of the cursor.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-D</strong></strong></dt>
<dd><p>delete the character under the cursor.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-K</strong></strong></dt>
<dd><p>kill up to the end of the line.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-D</strong></strong></dt>
<dd><p>kill forward to the end of the next word.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-del</strong></strong></dt>
<dd><p>kill backward to the beginning of the last word.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-X</strong></strong></dt>
<dd><p>kill entire input line, and discard all pending input.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-Y</strong></strong></dt>
<dd><p>insert (yank) a just killed text.</p>

</dd>
</dl>
<p>The next commands allow you to change the input.</p>


<dl>
<dt><strong class="Mark"><strong class="button">Ctrl-T</strong></strong></dt>
<dd><p>exchange (twiddle) current and previous character.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-U</strong></strong></dt>
<dd><p>uppercase next word.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-L</strong></strong></dt>
<dd><p>lowercase next word.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-C</strong></strong></dt>
<dd><p>capitalize next word.</p>

</dd>
</dl>
<p>The <strong class="button">Tab</strong> character, which is in fact the control key <strong class="button">Ctrl-I</strong>, looks at the characters before the cursor, interprets them as the beginning of an identifier and tries to complete this identifier. If there is more than one possible completion, it completes to the longest common prefix of all those completions. If the characters to the left of the cursor are already the longest common prefix of all completions hitting <strong class="button">Tab</strong> a second time will display all possible completions.</p>


<dl>
<dt><strong class="Mark"><strong class="button">tab</strong></strong></dt>
<dd><p>complete the identifier before the cursor.</p>

</dd>
</dl>
<p>The next commands allow you to fetch previous lines, e.g., to correct typos, etc.</p>


<dl>
<dt><strong class="Mark"><strong class="button">Ctrl-L</strong></strong></dt>
<dd><p>insert last input line before current character.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-P</strong></strong></dt>
<dd><p>redisplay the last input line, another <strong class="button">Ctrl-P</strong> will redisplay the line before that, etc. If the cursor is not in the first column only the lines starting with the string to the left of the cursor are taken.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-N</strong></strong></dt>
<dd><p>Like <strong class="button">Ctrl-P</strong> but goes the other way round through the history.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-&lt;</strong></strong></dt>
<dd><p>goes to the beginning of the history.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-&gt;</strong></strong></dt>
<dd><p>goes to the end of the history.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-O</strong></strong></dt>
<dd><p>accepts this line and perform a <strong class="button">Ctrl-N</strong>.</p>

</dd>
</dl>
<p>Finally there are a few miscellaneous commands.</p>


<dl>
<dt><strong class="Mark"><strong class="button">Ctrl-V</strong></strong></dt>
<dd><p>enter next character literally, i.e., enter it even if it is one of the control keys.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Ctrl-U</strong></strong></dt>
<dd><p>execute the next line editing command 4 times.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-</strong><code class="code">num</code></strong></dt>
<dd><p>execute the next line editing command <code class="code">num</code> times.</p>

</dd>
<dt><strong class="Mark"><strong class="button">Esc-Ctrl-L</strong></strong></dt>
<dd><p>redisplay input line.</p>

</dd>
</dl>
<p>The four arrow keys (cursor keys) can be used instead of <strong class="button">Ctrl-B</strong>, <strong class="button">Ctrl-F</strong>, <strong class="button">Ctrl-P</strong>, and <strong class="button">Ctrl-N</strong>, respectively.</p>

<p><a id="X7E95EB017803F53C" name="X7E95EB017803F53C"></a></p>

<h4>6.9 <span class="Heading">Editing using the <code class="code">readline</code> library</span></h4>

<p>The descriptions in this section are valid only if your <strong class="pkg">GAP</strong> installation uses the <code class="code">readline</code> library for command line editing. You can check by <code class="code">IsBound(GAPInfo.UseReadline);</code> if this is the case.</p>

<p>You can use all the features of <code class="code">readline</code>, as for example explained in <span class="URL"><a href="http://tiswww.case.edu/php/chet/readline/rluserman.html">http://tiswww.case.edu/php/chet/readline/rluserman.html</a></span>. Therefore the command line editing in <strong class="pkg">GAP</strong> is similar to the <code class="code">bash</code> shell and many other programs. On a Unix/Linux system you may also have a manpage, try <code class="code">man readline</code>.</p>

<p>Compared to the command line editing which was used in <strong class="pkg">GAP</strong> up to version 4.4 (or compared to not using the <code class="code">readline</code> library) using <code class="code">readline</code> has several advantages:</p>


<ul>
<li><p>Most keys still do the same as explained in <a href="chap6.html#X82234FD181899530"><span class="RefLink">6.8</span></a> (in the default configuration).</p>

</li>
<li><p>There are many additional commands, e.g. undoing (<strong class="button">Ctrl-_</strong>, keyboard macros (<strong class="button">Ctrl-x(</strong>, <strong class="button">Ctrl-x)</strong> and <strong class="button">Ctrl-xe</strong>), file name completion (hit <strong class="button">Esc</strong> two or four times), showing matching parentheses, <code class="code">vi</code>-style key bindings, deleting and yanking text, ...</p>

</li>
<li><p>Lines which are longer than a physical terminal row can be edited more conveniently.</p>

</li>
<li><p>Arbitrary unicode characters can be typed into string literals.</p>

</li>
<li><p>The key bindings can be configured, either via your <code class="file">~/.inputrc</code> file or by <strong class="pkg">GAP</strong> commands, see <a href="chap6.html#X7C38F9E0783D9442"><span class="RefLink">6.9-1</span></a>.</p>

</li>
<li><p>The command line history can be saved to and read from a file, see <a href="chap6.html#X846C3DED84AD7593"><span class="RefLink">6.9-2</span></a>.</p>

</li>
<li><p>Adventurous users can even implement completely new command line editing functions on <strong class="pkg">GAP</strong> level, see <a href="chap6.html#X87D4EA197A263FB7"><span class="RefLink">6.9-4</span></a>.</p>

</li>
</ul>
<p><a id="X7C38F9E0783D9442" name="X7C38F9E0783D9442"></a></p>

<h5>6.9-1 <span class="Heading">Readline customization</span></h5>

<p>You can use your readline init file (by default <code class="file">~/.inputrc</code> on Unix/Linux) to customize key bindings. If you want settings be used only within <strong class="pkg">GAP</strong> you can write them between lines containing <code class="code">$if GAP</code> and <code class="code">$endif</code>. For a detailed documentation of the available settings and functions see <span class="URL"><a href="http://tiswww.case.edu/php/chet/readline/rluserman.html">here</a></span>.</p>


<div class="example"><pre>
$if GAP
  set blink-matching-paren on
  "\C-n": dump-functions
  "\ep": kill-region
$endif
</pre></div>

<p>Alternatively, from within <strong class="pkg">GAP</strong> the command <code class="code">ReadlineInitLine(<var class="Arg">line</var>);</code> can be used, where <var class="Arg">line</var> is a string containing a line as in the init file.</p>

<p>Note that after pressing <strong class="button">Ctrl-v</strong> the next special character is input verbatim. This is very useful to bind keys or key sequences. For example, binding the function key <strong class="button">F3</strong> to the command <code class="code">kill-whole-line</code> by using the sequence <strong class="button">Ctrl-v</strong> <strong class="button">F3</strong> looks on many terminals like this: <code class="code">ReadlineInitLine("\"^[OR\":kill-whole-line");</code>. (You can get the line back later with <strong class="button">Ctrl-y</strong>.)</p>

<p>The <strong class="button">Ctrl-g</strong> key can be used to type any unicode character by its code point. The number of the character can either be given as a count, or if the count is one the input characters before the cursor are taken (as decimal number or as hex number which starts with <code class="code">0x</code>. For example, the double stroke character ℤ can be input by any of the three key sequences <strong class="button">Esc 8484 Ctrl-g</strong>, <strong class="button">8484 Ctrl-g</strong> or <strong class="button">0x2124 Ctrl-g</strong>.</p>

<p>Some terminals bind the <strong class="button">Ctrl-s</strong> and <strong class="button">Ctrl-q</strong> keys to stop and restart terminal output. Furthermore, sometimes <strong class="button">Ctrl-\</strong> quits a program. To disable this behaviour (and maybe use these keys for command line editing) you can use <code class="code">Exec("stty stop undef; stty start undef; stty quit undef");</code> in your <strong class="pkg">GAP</strong> session or your <code class="file">gaprc</code> file (see <a href="chap3.html#X7FD66F977A3B02DF"><span class="RefLink">3.2</span></a>).</p>

<p><a id="X846C3DED84AD7593" name="X846C3DED84AD7593"></a></p>

<h5>6.9-2 <span class="Heading">The command line history</span></h5>

<p><strong class="pkg">GAP</strong> can save your input lines for later reuse. The keys <strong class="button">Ctrl-p</strong> (or <strong class="button">Up</strong>), <strong class="button">Ctrl-n</strong> (or <strong class="button">Down</strong>), <strong class="button">ESC&lt;</strong> and <strong class="button">ESC&gt;</strong> work as documented in <a href="chap6.html#X82234FD181899530"><span class="RefLink">6.8</span></a>, that is they scroll backward and forward in the history or go to its beginning or end. Also, <strong class="button">Ctrl-o</strong> works as documented, it is useful for repeating a sequence of previous lines. (But <strong class="button">Ctrl-l</strong> clears the screen as in other programs.)</p>

<p>The command line history can be used across several instances of <strong class="pkg">GAP</strong> via the following two commands.</p>

<p><a id="X7C1F4D04861C1197" name="X7C1F4D04861C1197"></a></p>

<h5>6.9-3 SaveCommandLineHistory</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SaveCommandLineHistory</code>( [<var class="Arg">fname</var>, ][<var class="Arg">app</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: <code class="keyw">fail</code> or number of saved lines</p>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ReadCommandLineHistory</code>( [<var class="Arg">fname</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: <code class="keyw">fail</code> or number of added lines</p>

<p>The first command saves the lines in the command line history to the file given by the string <var class="Arg">fname</var>. The default for <var class="Arg">fname</var> is <code class="file">history</code> in the user's <strong class="pkg">GAP</strong> root path <code class="code">GAPInfo.UserGapRoot</code> or <code class="file">"~/.gap_hist"</code> if this directory does not exist. If the optional argument <var class="Arg">app</var> is <code class="keyw">true</code> then the lines are appended to that file otherwise the file is overwritten.</p>

<p>The second command is the converse, it reads the lines from file <var class="Arg">fname</var> and <em>prepends</em> them to the current command line history.</p>

<p>By default an arbitrary number of input lines is stored in the command line history. For very long <strong class="pkg">GAP</strong> sessions or if <code class="func">SaveCommandLineHistory</code> and <code class="func">ReadCommandLineHistory</code> are used repeatedly it can be sensible to restrict the number of saved lines via <code class="code">SetUserPreference("HistoryMaxLines", num);</code> to a non negative number <code class="code">num</code> (the default is <code class="keyw">infinity</code>). An automatic storing and restoring of the command line history can be configured via <code class="code">SetUserPreference("SaveAndRestoreHistory", true);</code>.</p>

<p>Note that these functions are only available if your <strong class="pkg">GAP</strong> is configured to use the <code class="code">readline</code> library.</p>

<p><a id="X87D4EA197A263FB7" name="X87D4EA197A263FB7"></a></p>

<h5>6.9-4 <span class="Heading">Writing your own command line editing functions</span></h5>

<p>It is possible to write new command line editing functions in <strong class="pkg">GAP</strong> as follows.</p>

<p>The functions have one argument <var class="Arg">l</var> which is a list with five entries of the form <code class="code">[count, key, line, cursorpos, markpos]</code> where <code class="code">count</code> and <code class="code">key</code> are the last pressed key and its count (these are not so useful here because users probably do not want to overwrite the binding of a single key), then <code class="code">line</code> is a string containing the line typed so far, <code class="code">cursorpos</code> is the current position of the cursor (point), and <code class="code">markpos</code> the current position of the mark.</p>

<p>The result of such a function must be a list which can have various forms:</p>


<dl>
<dt><strong class="Mark"><code class="code">[str]</code></strong></dt>
<dd><p>with a string <code class="code">str</code>. In this case the text <code class="code">str</code> is inserted at the cursor position.</p>

</dd>
<dt><strong class="Mark"><code class="code">[kill, begin, end]</code></strong></dt>
<dd><p>where <code class="code">kill</code> is <code class="keyw">true</code> or <code class="keyw">false</code> and <code class="code">begin</code> and <code class="code">end</code> are positions on the input line. This removes the text from the lower position to before the higher position. If <code class="code">kill</code> is <code class="keyw">true</code> the text is killed, i.e. put in the kill ring for later yanking.</p>

</dd>
<dt><strong class="Mark"><code class="code">[begin, end, str]</code></strong></dt>
<dd><p>where <code class="code">begin</code> and <code class="code">end</code> are positions on the input line and <code class="code">str</code> is a string. Then the text from position <code class="code">begin</code> to before <code class="code">end</code> is substituted by <code class="code">str</code>.</p>

</dd>
<dt><strong class="Mark"><code class="code">[1, lstr]</code></strong></dt>
<dd><p>where <code class="code">lstr</code> is a list of strings. Then these strings are displayed like a list of possible completions. The input line is not changed.</p>

</dd>
<dt><strong class="Mark"><code class="code">[2, chars]</code></strong></dt>
<dd><p>where <code class="code">chars</code> is a string. The characters from <code class="code">chars</code> are used as the next characters from the input. (At most 512 characters are possible.)</p>

</dd>
<dt><strong class="Mark"><code class="code">[100]</code></strong></dt>
<dd><p>This rings the bell as configured in the terminal.</p>

</dd>
</dl>
<p>In the first three cases the result list can contain a position as a further entry, this becomes the new cursor position. Or it can contain two positions as further entries, these become the new cursor position and the new position of the mark.</p>

<p>Such a function can be installed as a macro for <code class="code">readline</code> via <code class="code">InstallReadlineMacro(name, fun);</code> where <code class="code">name</code> is a string used as name of the macro and <code class="code">fun</code> is a function as above. This macro can be called by a key sequence which is returned by <code class="code">InvocationReadlineMacro(name);</code>.</p>

<p>As an example we define a function which puts double quotes around the word under or before the cursor position. The space character, the characters in <code class="code">"(,)"</code>, and the beginning and end of the line are considered as word boundaries. The function is then installed as a macro and bound to the key sequence <strong class="button">Esc</strong> <strong class="button">Q</strong>.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">EditAddQuotes := function(l)</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  local str, pos, i, j, new;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  str := l[3];</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  pos := l[4];</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  i := pos; </span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  while i &gt; 1 and (not str[i-1] in ",( ") do</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">    i := i-1;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  od;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  j := pos;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  while IsBound(str[j]) and not str[j] in ",) " do</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">    j := j+1;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  od;</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  new := "\"";</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  Append(new, str{[i..j-1]});</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  Append(new, "\"");</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">  return [i, j, new];</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">end;;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">InstallReadlineMacro("addquotes", EditAddQuotes);</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">invl := InvocationReadlineMacro("addquotes");;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">ReadlineInitLine(Concatenation("\"\\eQ\":\"",invl,"\""));;</span>
</pre></div>

<p><a id="X7D8E1CF47E97A764" name="X7D8E1CF47E97A764"></a></p>

<h4>6.10 <span class="Heading">Editing Files</span></h4>

<p>In most cases, it is preferable to create longer input (in particular <strong class="pkg">GAP</strong> programs) separately in an editor, and to read in the result via <code class="func">Read</code> (<a href="chap9.html#X8373AC6B7D5F9167"><span class="RefLink">9.7-1</span></a>). Note that <code class="func">Read</code> (<a href="chap9.html#X8373AC6B7D5F9167"><span class="RefLink">9.7-1</span></a>) by default reads from the directory in which <strong class="pkg">GAP</strong> was started (respectively under Windows the directory containing the <strong class="pkg">GAP</strong> binary), so you might have to give an absolute path to the file.</p>

<p>If you cannot create several windows, the <code class="func">Edit</code> (<a href="chap6.html#X82E5859C8113BA4D"><span class="RefLink">6.10-1</span></a>) command may be used to leave <strong class="pkg">GAP</strong>, start an editor, and read in the edited file automatically.</p>

<p><a id="X82E5859C8113BA4D" name="X82E5859C8113BA4D"></a></p>

<h5>6.10-1 Edit</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Edit</code>( <var class="Arg">filename</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">Edit</code> starts an editor with the file whose filename is given by the string <var class="Arg">filename</var>, and reads the file back into <strong class="pkg">GAP</strong> when you exit the editor again.</p>

<p><strong class="pkg">GAP</strong> will call your preferred editor if you call <code class="code">SetUserPreference("Editor", <var class="Arg">path</var>);</code> where <var class="Arg">path</var> is the path to your editor, e.g., <code class="file">/usr/bin/vim</code>. On Windows you can use <code class="code">edit.com</code>.</p>

<p>Under Mac OS X, you should use <code class="code">SetUserPreference("Editor", "open");</code>, this will open the file in the default editor. If you call <code class="code">SetUserPreference("EditorOptions", ["-t"]);</code>, the file will open in <code class="file">TextEdit</code>, and <code class="code">SetUserPreference("EditorOptions", ["-a", "&lt;appl&gt;"]);</code> will open the file using the application <code class="code">&lt;appl&gt;</code>.</p>

<p>This can for example be done in your <code class="file">gap.ini</code> file, see Section <a href="chap3.html#X87DF11C885E73583"><span class="RefLink">3.2-1</span></a>.</p>

<p><a id="X7B67FF1E87FE67D1" name="X7B67FF1E87FE67D1"></a></p>

<h4>6.11 <span class="Heading">Editor Support</span></h4>

<p>In the <code class="file">etc</code> subdirectory of the <strong class="pkg">GAP</strong> installation we provide some setup files for the editors <code class="code">vim</code> and <code class="code">emacs</code>/<code class="code">xemacs</code>.</p>

<p><code class="code">vim</code> is a powerful editor that understands the basic <code class="code">vi</code> commands but provides much more functionality. You can find more information about it (and download it) from <span class="URL"><a href="http://www.vim.org">http://www.vim.org</a></span>.</p>

<p>To get support for <strong class="pkg">GAP</strong> syntax in vim, create in your home directory a directory <code class="file">.vim</code> with subdirectories <code class="file">.vim/syntax</code> and <code class="file">.vim/indent</code> (If you are not using Unix, refer to the <code class="code">vim</code> documentation on where to place syntax files). Then copy the file <code class="file">etc/gap.vim</code> to <code class="file">.vim/syntax/gap.vim</code> and the file <code class="file">etc/gap_indent.vim</code> to <code class="file">.vim/indent/gap.vim</code>.</p>

<p>Then edit the <code class="file">.vimrc</code> file in your home directory. Add lines as in the following example:</p>


<div class="example"><pre>
if has("syntax")
  syntax on             " Default to no syntax highlightning 
endif

" For GAP files
augroup gap
  " Remove all gap autocommands
  au!
autocmd BufRead,BufNewFile *.g,*.gi,*.gd set filetype=gap comments=s:##\ \ ,m:##\ \ ,e:##\ \ b:#

" I'm using the external program `par' for formating comment lines starting
" with `##  '. Include these lines only when you have par installed.
  autocmd BufRead,BufNewFile *.g,*.gi,*.gd set formatprg="par w76p4s0j"
  autocmd BufWritePost,FileWritePost *.g,*.gi,*.gd set formatprg="par w76p0s0j"
augroup END
</pre></div>

<p>See the headers of the two mentioned files for additional comments and adjust details according to your personal taste. Send comments and suggestions to <span class="URL"><a href="mailto:support@gap-system.org">support@gap-system.org</a></span>. Setup files for <code class="code">emacs</code>/<code class="code">xemacs</code> are contained in the <code class="file">etc/emacs</code> subdirectory.</p>

<p><a id="X83279E897ACCFFFA" name="X83279E897ACCFFFA"></a></p>

<h4>6.12 <span class="Heading">Changing the Screen Size</span></h4>

<p><a id="X8723E0A1837894F3" name="X8723E0A1837894F3"></a></p>

<h5>6.12-1 SizeScreen</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SizeScreen</code>( [<var class="Arg">sz</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with no arguments, <code class="func">SizeScreen</code> returns the size of the screen as a list with two entries. The first is the length of each line, the second is the number of lines.</p>

<p>Called with one argument that is a list <var class="Arg">sz</var>, <code class="func">SizeScreen</code> sets the size of the screen; The first entry of <var class="Arg">sz</var>, if bound, is the length of each line, and the second entry of <var class="Arg">sz</var>, if bound, is the number of lines. The values for unbound entries of <var class="Arg">sz</var> are left unaffected. The function returns the new values.</p>

<p>Note that those parameters can also be set with the command line options <code class="code">-x</code> for the line length and <code class="code">-y</code> for the number of lines (see Section <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>).</p>

<p>To check/change whether line breaking occurs for files and streams see <code class="func">PrintFormattingStatus</code> (<a href="chap10.html#X8663FCD57E8BC390"><span class="RefLink">10.4-8</span></a>) and <code class="func">SetPrintFormattingStatus</code> (<a href="chap10.html#X8663FCD57E8BC390"><span class="RefLink">10.4-8</span></a>).</p>

<p>The line length must be between <span class="SimpleMath">20</span> and <span class="SimpleMath">4096</span> characters (inclusive) and the number of lines must be at least <span class="SimpleMath">10</span>. Values outside this range will be adjusted to the nearest endpoint of the range.</p>

<p><a id="X87847E5087D6F47D" name="X87847E5087D6F47D"></a></p>

<h4>6.13 <span class="Heading">Teaching Mode</span></h4>

<p>When using <strong class="pkg">GAP</strong> in the context of (undergraduate) teaching it is often desirable to simplify some of the system output and functionality defaults (potentially at the cost of making the printing of objects more expensive). This can be achieved by turning on a teaching mode:</p>

<p><a id="X7BE2515F82425404" name="X7BE2515F82425404"></a></p>

<h5>6.13-1 TeachingMode</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; TeachingMode</code>( [<var class="Arg">switch</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>When called with a boolean argument <var class="Arg">switch</var>, this function will turn teaching mode respectively on or off.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">a:=Z(11)^3;</span>
Z(11)^3
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">TeachingMode(true);</span>
#I  Teaching mode is turned ON
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">a;</span>
ZmodnZObj(8,11)
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">TeachingMode(false);</span>
#I  Teaching mode is turned OFF
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">a;</span>
Z(11)^3
</pre></div>

<p>At the moment, teaching mode changes the following things</p>


<dl>
<dt><strong class="Mark">Prime Field Elements</strong></dt>
<dd><p>Elements of fields of prime order are printed as <code class="func">ZmodnZObj</code> (<a href="chap14.html#X838F36507D985EDA"><span class="RefLink">14.5-3</span></a>) instead as power of a primitive root.</p>

</dd>
<dt><strong class="Mark">Quadratic Irrationalities</strong></dt>
<dd><p>Elements of a quadratic extension of the rationals are printed using the square root <code class="func">ER</code> (<a href="chap18.html#X813CF4327C4B4D29"><span class="RefLink">18.4-2</span></a>) instead of using roots of unity.</p>

</dd>
<dt><strong class="Mark">Creation of some small groups</strong></dt>
<dd><p>The group creator functions <code class="func">CyclicGroup</code> (<a href="chap50.html#X7A7C473D87B31F3B"><span class="RefLink">50.1-2</span></a>), <code class="func">AbelianGroup</code> (<a href="chap50.html#X81CCC3BF8005A2D7"><span class="RefLink">50.1-3</span></a>), <code class="func">ElementaryAbelianGroup</code> (<a href="chap50.html#X8778256286E50743"><span class="RefLink">50.1-4</span></a>), and <code class="func">DihedralGroup</code> (<a href="chap50.html#X838DE1AB7B3D70FF"><span class="RefLink">50.1-6</span></a>) create by default (if no other representation is specified) not a pc group, but a finitely presented group, which makes the generators easier to interpret.</p>

</dd>
</dl>

<div class="chlinkprevnextbot">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap5.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap7.html">[Next Chapter]</a>&nbsp;  </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>