source/texk/web2c/luatexdir/tex/equivalents.w

   1 % equivalents.w
   2 %
   3 % Copyright 2009-2010 Taco Hoekwater <taco@@luatex.org>
   4 %
   5 % This file is part of LuaTeX.
   6 %
   7 % LuaTeX is free software; you can redistribute it and/or modify it under
   8 % the terms of the GNU General Public License as published by the Free
   9 % Software Foundation; either version 2 of the License, or (at your
  10 % option) any later version.
  11 %
  12 % LuaTeX is distributed in the hope that it will be useful, but WITHOUT
  13 % ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 % FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  15 % License for more details.
  16 %
  17 % You should have received a copy of the GNU General Public License along
  18 % with LuaTeX; if not, see <http://www.gnu.org/licenses/>.
  19
  20 @ @c
  21
  22 #include "ptexlib.h"
  23
  24 halfword last_cs_name = null_cs;
  25
  26 /* |eqtb[p]| has just been restored or retained */
  27
  28 static void diagnostic_trace(halfword p, const char *s)
  29 {
  30     begin_diagnostic();
  31     print_char('{');
  32     tprint(s);
  33     print_char(' ');
  34     show_eqtb(p);
  35     print_char('}');
  36     end_diagnostic(false);
  37 }
  38
  39 @ @c
  40 #define par_shape_ptr equiv(par_shape_loc)
  41
  42 void show_eqtb_meaning(halfword n);     /* forward */
  43
  44 @ Now that we have studied the data structures for \TeX's semantic routines,
  45 we ought to consider the data structures used by its syntactic routines. In
  46 other words, our next concern will be
  47 the tables that \TeX\ looks at when it is scanning
  48 what the user has written.
  49
  50 The biggest and most important such table is called |eqtb|. It holds the
  51 current ``equivalents'' of things; i.e., it explains what things mean
  52 or what their current values are, for all quantities that are subject to
  53 the nesting structure provided by \TeX's grouping mechanism. There are six
  54 parts to |eqtb|:
  55
  56 \yskip\hang 1) |eqtb[null_cs]| holds the current equivalent of the
  57 zero-length control sequence.
  58
  59 \yskip\hang 2) |eqtb[hash_base..(glue_base-1)]| holds the current
  60 equivalents of single- and multiletter control sequences.
  61
  62 \yskip\hang 3) |eqtb[glue_base..(local_base-1)]| holds the current
  63 equivalents of glue parameters like the current baselineskip.
  64
  65 \yskip\hang 4) |eqtb[local_base..(int_base-1)]| holds the current
  66 equivalents of local halfword quantities like the current box registers,
  67 the current ``catcodes,'' the current font, and a pointer to the current
  68 paragraph shape.
  69
  70 \yskip\hang 5) |eqtb[int_base..(dimen_base-1)]| holds the current
  71 equivalents of fullword integer parameters like the current hyphenation
  72 penalty.
  73
  74 \yskip\hang 6) |eqtb[dimen_base..eqtb_size]| holds the current equivalents
  75 of fullword dimension parameters like the current hsize or amount of
  76 hanging indentation.
  77
  78 \yskip\noindent Note that, for example, the current amount of
  79 baselineskip glue is determined by the setting of a particular location
  80 in region~3 of |eqtb|, while the current meaning of the control sequence
  81 `\.{\\baselineskip}' (which might have been changed by \.{\\def} or
  82 \.{\\let}) appears in region~2.
  83
  84 @ The last two regions of |eqtb| have fullword values instead of the
  85 three fields |eq_level|, |eq_type|, and |equiv|. An |eq_type| is unnecessary,
  86 but \TeX\ needs to store the |eq_level| information in another array
  87 called |xeq_level|.
  88
  89 @c
  90 memory_word *eqtb;
  91 halfword eqtb_top;              /* maximum of the |eqtb| */
  92 quarterword xeq_level[(eqtb_size + 1)];
  93
  94 @ @c
  95 void initialize_equivalents(void)
  96 {
  97     int k;
  98     for (k = int_base; k <= eqtb_size; k++)
  99         xeq_level[k] = level_one;
 100 }
 101
 102 @ The nested structure provided by `$\.{\char'173}\ldots\.{\char'175}$' groups
 103 in \TeX\ means that |eqtb| entries valid in outer groups should be saved
 104 and restored later if they are overridden inside the braces. When a new |eqtb|
 105 value is being assigned, the program therefore checks to see if the previous
 106 entry belongs to an outer level. In such a case, the old value is placed
 107 on the |save_stack| just before the new value enters |eqtb|. At the
 108 end of a grouping level, i.e., when the right brace is sensed, the
 109 |save_stack| is used to restore the outer values, and the inner ones are
 110 destroyed.
 111
 112 Entries on the |save_stack| are of type |save_record|. The top item on
 113 this stack is |save_stack[p]|, where |p=save_ptr-1|; it contains three
 114 fields called |save_type|, |save_level|, and |save_value|, and it is
 115 interpreted in one of four ways:
 116
 117 \yskip\hang 1) If |save_type(p)=restore_old_value|, then
 118 |save_value(p)| is a location in |eqtb| whose current value should
 119 be destroyed at the end of the current group and replaced by |save_word(p-1)|
 120 (|save_type(p-1)==saved_eqtb|).
 121 Furthermore if |save_value(p)>=int_base|, then |save_level(p)| should
 122 replace the corresponding entry in |xeq_level| (if |save_value(p)<int_base|,
 123 then the level is part of |save_word(p-1)|).
 124
 125 \yskip\hang 2) If |save_type(p)=restore_zero|, then |save_value(p)|
 126 is a location in |eqtb| whose current value should be destroyed at the end
 127 of the current group, when it should be
 128 replaced by the current value of |eqtb[undefined_control_sequence]|.
 129
 130 \yskip\hang 3) If |save_type(p)=insert_token|, then |save_value(p)|
 131 is a token that should be inserted into \TeX's input when the current
 132 group ends.
 133
 134 \yskip\hang 4) If |save_type(p)=level_boundary|, then |save_level(p)|
 135 is a code explaining what kind of group we were previously in, and
 136 |save_value(p)| points to the level boundary word at the bottom of
 137 the entries for that group. Furthermore, |save_value(p-1)| contains the
 138 source line number at which the current level of grouping was entered,
 139 this field has itself a type: |save_type(p-1)==saved_line|.
 140
 141 Besides this `official' use, various subroutines push temporary
 142 variables on the save stack when it is handy to do so. These all have
 143 an explicit |save_type|, and they are:
 144
 145 |saved_adjust| signifies an adjustment is beging scanned,
 146 |saved_insert| an insertion is being scanned,
 147 |saved_disc| the \.{\\discretionary} sublist we are working on right now,
 148 |saved_boxtype| whether a \.{\\localbox} is \.{\\left} or \.{\\right},
 149 |saved_textdir| a text direction to be restored,
 150 |saved_eqno| diffentiates between \.{\\eqno} and \.{\\leqno},
 151 |saved_choices| the \.{\\mathchoices} sublist we are working on right now,
 152 |saved_math| and interrupted math list,
 153 |saved_boxcontext| the box context value,
 154 |saved_boxspec| the box \.{to} or \.{spread} specification,
 155 |saved_boxdir| the box \.{dir} specification,
 156 |saved_boxattr| the box \.{attr} specification,
 157 |saved_boxpack| the box \.{pack} specification.
 158
 159 @ The global variable |cur_group| keeps track of what sort of group we are
 160 currently in. Another global variable, |cur_boundary|, points to the
 161 topmost |level_boundary| word.  And |cur_level| is the current depth of
 162 nesting. The routines are designed to preserve the condition that no entry
 163 in the |save_stack| or in |eqtb| ever has a level greater than |cur_level|.
 164
 165 @c
 166 save_record *save_stack;
 167 int save_ptr;                        /* first unused entry on |save_stack| */
 168 int max_save_stack;                  /* maximum usage of save stack */
 169 quarterword cur_level = level_one;   /* current nesting level for groups */
 170 group_code cur_group = bottom_level; /* current group type */
 171 int cur_boundary;                    /* where the current level begins */
 172
 173 @ At this time it might be a good idea for the reader to review the introduction
 174 to |eqtb| that was given above just before the long lists of parameter names.
 175 Recall that the ``outer level'' of the program is |level_one|, since
 176 undefined control sequences are assumed to be ``defined'' at |level_zero|.
 177
 178
 179
 180 @ The following macro is used to test if there is room for up to eight more
 181 entries on |save_stack|. By making a conservative test like this, we can
 182 get by with testing for overflow in only a few places.
 183
 184 @c
 185 #define check_full_save_stack() do { \
 186     if (save_ptr>max_save_stack) { \
 187         max_save_stack=save_ptr; \
 188         if (max_save_stack>save_size-8) \
 189             overflow("save size",(unsigned)save_size); \
 190     } \
 191 } while (0)
 192
 193 @ Procedure |new_save_level| is called when a group begins. The
 194 argument is a group identification code like `|hbox_group|'. After
 195 calling this routine, it is safe to put six more entries on |save_stack|.
 196
 197 In some cases integer-valued items are placed onto the
 198 |save_stack| just below a |level_boundary| word, because this is a
 199 convenient place to keep information that is supposed to ``pop up'' just
 200 when the group has finished.
 201 For example, when `\.{\\hbox to 100pt}' is being treated, the 100pt
 202 dimension is stored on |save_stack| just before |new_save_level| is
 203 called.
 204
 205 @c
 206 void new_save_level(group_code c)
 207 {   /* begin a new level of grouping */
 208     check_full_save_stack();
 209     set_saved_record(0, saved_line, 0, line);
 210     incr(save_ptr);
 211     save_type(save_ptr) = level_boundary;
 212     save_level(save_ptr) = cur_group;
 213     save_value(save_ptr) = cur_boundary;
 214     if (cur_level == max_quarterword)
 215         overflow("grouping levels", max_quarterword - min_quarterword);
 216     /* quit if |(cur_level+1)| is too big to be stored in |eqtb| */
 217     cur_boundary = save_ptr;
 218     cur_group = c;
 219     if (int_par(tracing_groups_code) > 0)
 220         group_trace(false);
 221     incr(cur_level);
 222     incr(save_ptr);
 223 }
 224
 225 @ @c
 226 static const char *save_stack_type(int v)
 227 {
 228     const char *s = "";
 229     switch (save_type(v)) {
 230         case restore_old_value: s = "restore_old_value"; break;
 231         case restore_zero:      s = "restore_zero";      break;
 232         case insert_token:      s = "insert_token";      break;
 233         case level_boundary:    s = "level_boundary";    break;
 234         case saved_line:        s = "saved_line";        break;
 235         case saved_adjust:      s = "saved_adjust";      break;
 236         case saved_insert:      s = "saved_insert";      break;
 237         case saved_disc:        s = "saved_disc";        break;
 238         case saved_boxtype:     s = "saved_boxtype";     break;
 239         case saved_textdir:     s = "saved_textdir";     break;
 240         case saved_eqno:        s = "saved_eqno";        break;
 241         case saved_choices:     s = "saved_choices";     break;
 242         case saved_math:        s = "saved_math";        break;
 243         case saved_boxcontext:  s = "saved_boxcontext";  break;
 244         case saved_boxspec:     s = "saved_boxspec";     break;
 245         case saved_boxdir:      s = "saved_boxdir";      break;
 246         case saved_boxattr:     s = "saved_boxattr";     break;
 247         case saved_boxpack:     s = "saved_boxpack";     break;
 248         case saved_eqtb:        s = "saved_eqtb";        break;
 249         default: break;
 250     }
 251     return s;
 252 }
 253
 254 @ @c
 255 void print_save_stack(void)
 256 {
 257     int i;
 258     begin_diagnostic();
 259     selector = term_and_log;
 260     print_ln();
 261     for (i = (save_ptr - 1); i >= 0; i--) {
 262         tprint("save_stack[");
 263         if (i < 100)
 264             print_char(' ');
 265         if (i < 10)
 266             print_char(' ');
 267         print_int(i);
 268         tprint("]: ");
 269         tprint(save_stack_type(i));
 270         switch (save_type(i)) {
 271             case restore_old_value:
 272                 tprint(", ");
 273                 show_eqtb_meaning(save_value(i));
 274                 tprint("=");
 275                 if (save_value(i) >= int_base) {
 276                     print_int(save_word(i - 1).cint);
 277                 } else {
 278                     print_int(eq_type_field(save_word(i - 1)));
 279                     print_char(',');        /* |print_int(eq_level_field(save_word(i-1)));| */
 280                     print_int(equiv_field(save_word(i - 1)));
 281                 }
 282                 i--;
 283                 break;
 284             case restore_zero:
 285                 tprint(", ");
 286                 show_eqtb_meaning(save_value(i));
 287                 break;
 288             case insert_token:
 289                 tprint(", ");
 290                 {
 291                     halfword p = get_avail();
 292                     set_token_info(p, save_value(i));
 293                     show_token_list(p, null, 1);
 294                     free_avail(p);
 295                 }
 296                 break;
 297             case level_boundary:
 298                 tprint(", old group=");
 299                 print_int(save_level(i));
 300                 tprint(", boundary = ");
 301                 print_int(save_value(i));
 302                 tprint(", line = ");
 303                 print_int(save_value(i - 1));
 304                 i--;
 305                 break;
 306             case saved_adjust:
 307                 tprint(", ");
 308                 print_int(save_level(i));   /* vadjust vs vadjust pre */
 309                 break;
 310             case saved_insert:
 311                 tprint(", ");
 312                 print_int(save_value(i));   /* insert number */
 313                 break;
 314             case saved_boxtype:    /* \.{\\localleftbox} vs \.{\\localrightbox} */
 315                 tprint(", ");
 316                 print_int(save_value(i));
 317                 break;
 318             case saved_eqno:       /* \.{\\eqno} vs \.{\\leqno} */
 319                 tprint(", ");
 320                 print_int(save_value(i));
 321                 break;
 322             case saved_disc:
 323             case saved_choices:
 324                 tprint(", ");
 325                 print_int(save_value(i));
 326                 break;
 327             case saved_math:
 328                 tprint(", listptr=");
 329                 print_int(save_value(i));
 330                 break;
 331             case saved_boxcontext:
 332                 tprint(", ");
 333                 print_int(save_value(i));
 334                 break;
 335             case saved_boxspec:
 336                 tprint(", spec=");
 337                 print_int(save_level(i));
 338                 tprint(", dimen=");
 339                 print_int(save_value(i));
 340                 break;
 341             case saved_textdir:
 342             case saved_boxdir:
 343                 tprint(", ");
 344                 print_dir(dir_dir(save_value(i)));
 345                 break;
 346             case saved_boxattr:
 347             case saved_boxpack:
 348                 tprint(", ");
 349                 print_int(save_value(i));
 350                 break;
 351             case saved_line:
 352             case saved_eqtb:
 353                 break;
 354             default:
 355                 break;
 356         }
 357         print_ln();
 358     }
 359     end_diagnostic(true);
 360 }
 361
 362 @ The \.{\\showgroups} command displays all currently active grouping
 363   levels.
 364
 365 @ The modifications of \TeX\ required for the display produced by the
 366   |show_save_groups| procedure were first discussed by Donald~E. Knuth in
 367   {\sl TUGboat\/} {\bf 11}, 165--170 and 499--511, 1990.
 368   @^Knuth, Donald Ervin@>
 369
 370   In order to understand a group type we also have to know its mode.
 371   Since unrestricted horizontal modes are not associated with grouping,
 372   they are skipped when traversing the semantic nest.
 373
 374 @c
 375 void show_save_groups(void)
 376 {
 377     int p = nest_ptr;           /* index into |nest| */
 378     int m;                      /* mode */
 379     save_pointer v = save_ptr;  /* saved value of |save_ptr| */
 380     quarterword l = cur_level;  /* saved value of |cur_level| */
 381     group_code c = cur_group;   /* saved value of |cur_group| */
 382     int a = 1;                  /* to keep track of alignments */
 383     int i;
 384     quarterword j;
 385     const char *s = NULL;
 386     save_ptr = cur_boundary;
 387     decr(cur_level);
 388     tprint_nl("");
 389     print_ln();
 390     while (1) {
 391         tprint_nl("### ");
 392         print_group(true);
 393         if (cur_group == bottom_level)
 394             goto DONE;
 395         do {
 396             m = nest[p].mode_field;
 397             if (p > 0)
 398                 decr(p);
 399             else
 400                 m = vmode;
 401         } while (m == hmode);
 402         tprint(" (");
 403         switch (cur_group) {
 404             case simple_group:
 405                 incr(p);
 406                 goto FOUND2;
 407                 break;
 408             case hbox_group:
 409             case adjusted_hbox_group:
 410                 s = "hbox";
 411                 break;
 412             case vbox_group:
 413                 s = "vbox";
 414                 break;
 415             case vtop_group:
 416                 s = "vtop";
 417                 break;
 418             case align_group:
 419                 if (a == 0) {
 420                     if (m == -vmode)
 421                         s = "halign";
 422                     else
 423                         s = "valign";
 424                     a = 1;
 425                     goto FOUND1;
 426                 } else {
 427                     if (a == 1)
 428                         tprint("align entry");
 429                     else
 430                         tprint_esc("cr");
 431                     if (p >= a)
 432                         p = p - a;
 433                     a = 0;
 434                     goto FOUND;
 435                 }
 436                 break;
 437             case no_align_group:
 438                 incr(p);
 439                 a = -1;
 440                 tprint_esc("noalign");
 441                 goto FOUND2;
 442                 break;
 443             case output_group:
 444                 tprint_esc("output");
 445                 goto FOUND;
 446                 break;
 447             case math_group:
 448                 goto FOUND2;
 449                 break;
 450             case disc_group:
 451                 tprint_esc("discretionary");
 452                 for (i = 1; i < 3; i++)
 453                     if (i <= saved_value(-2))
 454                         tprint("{}");
 455                 goto FOUND2;
 456                 break;
 457             case math_choice_group:
 458                 tprint_esc("mathchoice");
 459                 for (i = 1; i < 4; i++)
 460                     if (i <= saved_value(-3))       /* different offset because |-2==saved_textdir| */
 461                         tprint("{}");
 462                 goto FOUND2;
 463                 break;
 464             case insert_group:
 465                 if (saved_type(-1) == saved_adjust) {
 466                     tprint_esc("vadjust");
 467                     if (saved_level(-1) != 0)
 468                         tprint(" pre");
 469                 } else {
 470                     tprint_esc("insert");
 471                     print_int(saved_value(-1));
 472                 }
 473                 goto FOUND2;
 474                 break;
 475             case vcenter_group:
 476                 s = "vcenter";
 477                 goto FOUND1;
 478                 break;
 479             case semi_simple_group:
 480                 incr(p);
 481                 tprint_esc("begingroup");
 482                 goto FOUND;
 483                 break;
 484             case math_shift_group:
 485                 if (m == mmode) {
 486                     print_char('$');
 487                 } else if (nest[p].mode_field == mmode) {
 488                     print_cmd_chr(eq_no_cmd, saved_value(-2));
 489                     goto FOUND;
 490                 }
 491                 print_char('$');
 492                 goto FOUND;
 493                 break;
 494             case math_left_group:
 495                 if (subtype(nest[p + 1].eTeX_aux_field) == left_noad_side)
 496                     tprint_esc("left");
 497                 else
 498                     tprint_esc("middle");
 499                 goto FOUND;
 500                 break;
 501             default:
 502                 confusion("showgroups");
 503                 break;
 504         }
 505         /* Show the box context */
 506         i = saved_value(-5);
 507         if (i != 0) {
 508             if (i < box_flag) {
 509                 if (abs(nest[p].mode_field) == vmode)
 510                     j = hmove_cmd;
 511                 else
 512                     j = vmove_cmd;
 513                 if (i > 0)
 514                     print_cmd_chr(j, 0);
 515                 else
 516                     print_cmd_chr(j, 1);
 517                 print_scaled(abs(i));
 518                 tprint("pt");
 519             } else if (i < ship_out_flag) {
 520                 if (i >= global_box_flag) {
 521                     tprint_esc("global");
 522                     i = i - (global_box_flag - box_flag);
 523                 }
 524                 tprint_esc("setbox");
 525                 print_int(i - box_flag);
 526                 print_char('=');
 527             } else {
 528                 print_cmd_chr(leader_ship_cmd, i - (leader_flag - a_leaders));
 529             }
 530         }
 531       FOUND1:
 532         tprint_esc(s);
 533         /* Show the box packaging info */
 534         {
 535             /* offsets may vary */
 536             int ii = -1;
 537             while (saved_type(ii) != saved_boxspec)
 538                 ii--;
 539             if (saved_value(ii) != 0) {
 540                 print_char(' ');
 541                 if (saved_level(ii) == exactly)
 542                     tprint("to");
 543                 else
 544                     tprint("spread");
 545                 print_scaled(saved_value(ii));
 546                 tprint("pt");
 547             }
 548         }
 549       FOUND2:
 550         print_char('{');
 551       FOUND:
 552         print_char(')');
 553         decr(cur_level);
 554         cur_group = save_level(save_ptr);
 555         save_ptr = save_value(save_ptr);
 556     }
 557   DONE:
 558     save_ptr = v;
 559     cur_level = l;
 560     cur_group = c;
 561 }
 562
 563 @ Just before an entry of |eqtb| is changed, the following procedure should
 564 be called to update the other data structures properly. It is important
 565 to keep in mind that reference counts in |mem| include references from
 566 within |save_stack|, so these counts must be handled carefully.
 567 @^reference counts@>
 568
 569 @c
 570 void eq_destroy(memory_word w)
 571 {                               /* gets ready to forget |w| */
 572     halfword q;                 /* |equiv| field of |w| */
 573     switch (eq_type_field(w)) {
 574         case call_cmd:
 575         case long_call_cmd:
 576         case outer_call_cmd:
 577         case long_outer_call_cmd:
 578             delete_token_ref(equiv_field(w));
 579             break;
 580         case glue_ref_cmd:
 581             delete_glue_ref(equiv_field(w));
 582             break;
 583         case shape_ref_cmd:
 584             q = equiv_field(w);     /* we need to free a \.{\\parshape} block */
 585             if (q != null)
 586                 flush_node(q);
 587             break;                  /* such a block is |2n+1| words long, where |n=vinfo(q)| */
 588         case box_ref_cmd:
 589             flush_node_list(equiv_field(w));
 590             break;
 591         default:
 592             break;
 593     }
 594 }
 595
 596 @ To save a value of |eqtb[p]| that was established at level |l|, we
 597 can use the following subroutine.
 598
 599 @c
 600 void eq_save(halfword p, quarterword l)
 601 {                               /* saves |eqtb[p]| */
 602     check_full_save_stack();
 603     if (l == level_zero) {
 604         save_type(save_ptr) = restore_zero;
 605     } else {
 606         save_word(save_ptr) = eqtb[p];
 607         save_type(save_ptr) = saved_eqtb;
 608         incr(save_ptr);
 609         save_type(save_ptr) = restore_old_value;
 610     }
 611     save_level(save_ptr) = l;
 612     save_value(save_ptr) = p;
 613     incr(save_ptr);
 614 }
 615
 616 @ The procedure |eq_define| defines an |eqtb| entry having specified
 617 |eq_type| and |equiv| fields, and saves the former value if appropriate.
 618 This procedure is used only for entries in the first four regions of |eqtb|,
 619 i.e., only for entries that have |eq_type| and |equiv| fields.
 620 After calling this routine, it is safe to put four more entries on
 621 |save_stack|, provided that there was room for four more entries before
 622 the call, since |eq_save| makes the necessary test.
 623
 624 @ new data for |eqtb|
 625 @c
 626 void eq_define(halfword p, quarterword t, halfword e)
 627 {
 628     boolean trace = int_par(tracing_assigns_code) > 0;
 629     if ((eq_type(p) == t) && (equiv(p) == e)) {
 630         if (trace)
 631             diagnostic_trace(p, "reassigning");
 632         eq_destroy(eqtb[p]);
 633         return;
 634     }
 635     if (trace)
 636         diagnostic_trace(p, "changing");
 637     if (eq_level(p) == cur_level)
 638         eq_destroy(eqtb[p]);
 639     else if (cur_level > level_one)
 640         eq_save(p, eq_level(p));
 641     set_eq_level(p, cur_level);
 642     set_eq_type(p, t);
 643     set_equiv(p, e);
 644     if (trace)
 645         diagnostic_trace(p, "into");
 646 }
 647
 648 @ The counterpart of |eq_define| for the remaining (fullword) positions in
 649 |eqtb| is called |eq_word_define|. Since |xeq_level[p]>=level_one| for all
 650 |p|, a `|restore_zero|' will never be used in this case.
 651
 652 @c
 653 void eq_word_define(halfword p, int w)
 654 {
 655     boolean trace = int_par(tracing_assigns_code) > 0;
 656     if (eqtb[p].cint == w) {
 657         if (trace)
 658             diagnostic_trace(p, "reassigning");
 659         return;
 660     }
 661     if (trace)
 662         diagnostic_trace(p, "changing");
 663     if (xeq_level[p] != cur_level) {
 664         eq_save(p, xeq_level[p]);
 665         xeq_level[p] = cur_level;
 666     }
 667     eqtb[p].cint = w;
 668     if (trace)
 669         diagnostic_trace(p, "into");
 670 }
 671
 672
 673 @ The |eq_define| and |eq_word_define| routines take care of local definitions.
 674 @^global definitions@>
 675 Global definitions are done in almost the same way, but there is no need
 676 to save old values, and the new value is associated with |level_one|.
 677
 678 @c
 679 void geq_define(halfword p, quarterword t, halfword e)
 680 {                               /* global |eq_define| */
 681     boolean trace = int_par(tracing_assigns_code) > 0;
 682     if (trace)
 683         diagnostic_trace(p, "globally changing");
 684     eq_destroy(eqtb[p]);
 685     set_eq_level(p, level_one);
 686     set_eq_type(p, t);
 687     set_equiv(p, e);
 688     if (trace)
 689         diagnostic_trace(p, "into");
 690 }
 691
 692 void geq_word_define(halfword p, int w)
 693 {                               /* global |eq_word_define| */
 694     boolean trace = int_par(tracing_assigns_code) > 0;
 695     if (trace)
 696         diagnostic_trace(p, "globally changing");
 697     eqtb[p].cint = w;
 698     xeq_level[p] = level_one;
 699     if (trace)
 700         diagnostic_trace(p, "into");
 701 }
 702
 703 @ Subroutine |save_for_after| puts a token on the stack for save-keeping.
 704
 705 @c
 706 void save_for_after(halfword t)
 707 {
 708     if (cur_level > level_one) {
 709         check_full_save_stack();
 710         save_type(save_ptr) = insert_token;
 711         save_level(save_ptr) = level_zero;
 712         save_value(save_ptr) = t;
 713         incr(save_ptr);
 714     }
 715 }
 716
 717 @ The |unsave| routine goes the other way, taking items off of |save_stack|.
 718 This routine takes care of restoration when a level ends; everything
 719 belonging to the topmost group is cleared off of the save stack.
 720
 721 @c
 722 void unsave(void)
 723 {                               /* pops the top level off the save stack */
 724     halfword p;                 /* position to be restored */
 725     quarterword l = level_one;  /* saved level, if in fullword regions of |eqtb| */
 726     boolean a = false;          /* have we already processed an \.{\\aftergroup} ? */
 727     unsave_math_codes(cur_level);
 728     unsave_cat_codes(int_par(cat_code_table_code), cur_level);
 729     unsave_text_codes(cur_level);
 730     unsave_math_data(cur_level);
 731     if (cur_level > level_one) {
 732         boolean trace = int_par(tracing_restores_code) > 0;
 733         decr(cur_level);
 734         /* Clear off top level from |save_stack| */
 735         while (true) {
 736             decr(save_ptr);
 737             if (save_type(save_ptr) == level_boundary)
 738                 break;
 739             p = save_value(save_ptr);
 740             if (save_type(save_ptr) == insert_token) {
 741                 reinsert_token(a, p);
 742                 a = true; /* always ... always etex now */
 743             } else {
 744                 if (save_type(save_ptr) == restore_old_value) {
 745                     l = save_level(save_ptr);
 746                     decr(save_ptr);
 747                 } else {
 748                     save_word(save_ptr) = eqtb[undefined_control_sequence];
 749                 }
 750                 /* Store |save_stack[save_ptr]| in |eqtb[p]|, unless
 751                    |eqtb[p]| holds a global value */
 752                 /* A global definition, which sets the level to |level_one|,
 753                    will not be undone by |unsave|. If at least one global definition of
 754                    |eqtb[p]| has been carried out within the group that just ended, the
 755                    last such definition will therefore survive.
 756                  */
 757                 if (p < int_base || p > eqtb_size) {
 758                     if (eq_level(p) == level_one) {
 759                         eq_destroy(save_word(save_ptr));        /* destroy the saved value */
 760                         if (trace)
 761                             diagnostic_trace(p, "retaining");
 762                     } else {
 763                         eq_destroy(eqtb[p]);    /* destroy the current value */
 764                         eqtb[p] = save_word(save_ptr);  /* restore the saved value */
 765                         if (trace)
 766                             diagnostic_trace(p, "restoring");
 767                     }
 768                 } else if (xeq_level[p] != level_one) {
 769                     eqtb[p] = save_word(save_ptr);
 770                     xeq_level[p] = l;
 771                     if (trace)
 772                         diagnostic_trace(p, "restoring");
 773                 } else {
 774                     if (trace)
 775                         diagnostic_trace(p, "retaining");
 776                 }
 777             }
 778         }
 779         if (int_par(tracing_groups_code) > 0)
 780             group_trace(true);
 781         if (grp_stack[in_open] == cur_boundary)
 782             group_warning();    /* groups possibly not properly nested with files */
 783         cur_group = save_level(save_ptr);
 784         cur_boundary = save_value(save_ptr);
 785         decr(save_ptr);
 786     } else {
 787         confusion("curlevel");  /* |unsave| is not used when |cur_group=bottom_level| */
 788     }
 789     attr_list_cache = cache_disabled;
 790 }
 791
 792 @ Most of the parameters kept in |eqtb| can be changed freely, but there's
 793 an exception:  The magnification should not be used with two different
 794 values during any \TeX\ job, since a single magnification is applied to an
 795 entire run. The global variable |mag_set| is set to the current magnification
 796 whenever it becomes necessary to ``freeze'' it at a particular value.
 797
 798 @c
 799 int mag_set; /* if nonzero, this magnification should be used henceforth */
 800
 801 @ The |prepare_mag| subroutine is called whenever \TeX\ wants to use |mag|
 802 for magnification.
 803
 804 @c
 805 #define mag int_par(mag_code)
 806
 807 void prepare_mag(void)
 808 {
 809     if ((mag_set > 0) && (mag != mag_set)) {
 810         print_err("Incompatible magnification (");
 811         print_int(mag);
 812         tprint(");");
 813         tprint_nl(" the previous value will be retained");
 814         help2("I can handle only one magnification ratio per job. So I've",
 815               "reverted to the magnification you used earlier on this run.");
 816         int_error(mag_set);
 817         geq_word_define(int_base + mag_code, mag_set);  /* |mag:=mag_set| */
 818     }
 819     if ((mag <= 0) || (mag > 32768)) {
 820         print_err("Illegal magnification has been changed to 1000");
 821         help1("The magnification ratio must be between 1 and 32768.");
 822         int_error(mag);
 823         geq_word_define(int_base + mag_code, 1000);
 824     }
 825     if ((mag_set == 0) && (mag != mag_set)) {
 826         if (mag != 1000)
 827             one_true_inch = xn_over_d(one_hundred_inch, 10, mag);
 828         else
 829             one_true_inch = one_inch;
 830     }
 831     mag_set = mag;
 832 }
 833
 834 @ Let's pause a moment now and try to look at the Big Picture.
 835 The \TeX\ program consists of three main parts: syntactic routines,
 836 semantic routines, and output routines. The chief purpose of the
 837 syntactic routines is to deliver the user's input to the semantic routines,
 838 one token at a time. The semantic routines act as an interpreter
 839 responding to these tokens, which may be regarded as commands. And the
 840 output routines are periodically called on to convert box-and-glue
 841 lists into a compact set of instructions that will be sent
 842 to a typesetter. We have discussed the basic data structures and utility
 843 routines of \TeX, so we are good and ready to plunge into the real activity by
 844 considering the syntactic routines.
 845
 846 Our current goal is to come to grips with the |get_next| procedure,
 847 which is the keystone of \TeX's input mechanism. Each call of |get_next|
 848 sets the value of three variables |cur_cmd|, |cur_chr|, and |cur_cs|,
 849 representing the next input token.
 850 $$\vbox{\halign{#\hfil\cr
 851   \hbox{|cur_cmd| denotes a command code from the long list of codes
 852    given above;}\cr
 853   \hbox{|cur_chr| denotes a character code or other modifier of the command
 854    code;}\cr
 855   \hbox{|cur_cs| is the |eqtb| location of the current control sequence,}\cr
 856   \hbox{\qquad if the current token was a control sequence,
 857    otherwise it's zero.}\cr}}$$
 858 Underlying this external behavior of |get_next| is all the machinery
 859 necessary to convert from character files to tokens. At a given time we
 860 may be only partially finished with the reading of several files (for
 861 which \.{\\input} was specified), and partially finished with the expansion
 862 of some user-defined macros and/or some macro parameters, and partially
 863 finished with the generation of some text in a template for \.{\\halign},
 864 and so on. When reading a character file, special characters must be
 865 classified as math delimiters, etc.; comments and extra blank spaces must
 866 be removed, paragraphs must be recognized, and control sequences must be
 867 found in the hash table. Furthermore there are occasions in which the
 868 scanning routines have looked ahead for a word like `\.{plus}' but only
 869 part of that word was found, hence a few characters must be put back
 870 into the input and scanned again.
 871
 872 To handle these situations, which might all be present simultaneously,
 873 \TeX\ uses various stacks that hold information about the incomplete
 874 activities, and there is a finite state control for each level of the
 875 input mechanism. These stacks record the current state of an implicitly
 876 recursive process, but the |get_next| procedure is not recursive.
 877 Therefore it will not be difficult to translate these algorithms into
 878 low-level languages that do not support recursion.
 879
 880 @c
 881 int cur_cmd;                    /* current command set by |get_next| */
 882 halfword cur_chr;               /* operand of current command */
 883 halfword cur_cs;                /* control sequence found here, zero if none found */
 884 halfword cur_tok;               /* packed representative of |cur_cmd| and |cur_chr| */
 885
 886 @ Here is a procedure that displays the current command.
 887
 888 @c
 889 #define mode cur_list.mode_field
 890
 891 void show_cur_cmd_chr(void)
 892 {
 893     int n;                      /* level of \.{\\if...\\fi} nesting */
 894     int l;                      /* line where \.{\\if} started */
 895     halfword p;
 896     begin_diagnostic();
 897     tprint_nl("{");
 898     if (mode != shown_mode) {
 899         print_mode(mode);
 900         tprint(": ");
 901         shown_mode = mode;
 902     }
 903     print_cmd_chr((quarterword) cur_cmd, cur_chr);
 904     if (int_par(tracing_ifs_code) > 0) {
 905         if (cur_cmd >= if_test_cmd) {
 906             if (cur_cmd <= fi_or_else_cmd) {
 907                 tprint(": ");
 908                 if (cur_cmd == fi_or_else_cmd) {
 909                     print_cmd_chr(if_test_cmd, cur_if);
 910                     print_char(' ');
 911                     n = 0;
 912                     l = if_line;
 913                 } else {
 914                     n = 1;
 915                     l = line;
 916                 }
 917                 p = cond_ptr;
 918                 while (p != null) {
 919                     incr(n);
 920                     p = vlink(p);
 921                 }
 922                 tprint("(level ");
 923                 print_int(n);
 924                 print_char(')');
 925                 print_if_line(l);
 926             }
 927         }
 928     }
 929     print_char('}');
 930     end_diagnostic(false);
 931 }
 932
 933 @ Here is a procedure that displays the contents of |eqtb[n]| symbolically.
 934
 935 @c
 936 void show_eqtb(halfword n)
 937 {
 938     if (n < null_cs) {
 939         /* this can't happen */
 940         print_char('?');
 941     } else if ((n < glue_base) || ((n > eqtb_size) && (n <= eqtb_top))) {
 942         /*
 943             Show equivalent |n|, in region 1 or 2
 944
 945             Here is a routine that displays the current meaning of an |eqtb| entry
 946             in region 1 or~2. (Similar routines for the other regions will appear
 947             below.)
 948         */
 949
 950         sprint_cs(n);
 951         print_char('=');
 952         print_cmd_chr(eq_type(n), equiv(n));
 953         if (eq_type(n) >= call_cmd) {
 954             print_char(':');
 955             show_token_list(token_link(equiv(n)), null, 32);
 956         }
 957     } else if (n < local_base) {
 958         /*
 959             Show equivalent |n|, in region 3
 960
 961             All glue parameters and registers are initially `\.{0pt plus0pt minus0pt}'.
 962         */
 963         if (n < skip_base) {
 964             if (n < glue_base + thin_mu_skip_code)
 965                 print_cmd_chr(assign_glue_cmd, n);
 966             else
 967                 print_cmd_chr(assign_mu_glue_cmd, n);
 968             print_char('=');
 969             if (n < glue_base + thin_mu_skip_code)
 970                 print_spec(equiv(n), "pt");
 971             else
 972                 print_spec(equiv(n), "mu");
 973         } else if (n < mu_skip_base) {
 974             tprint_esc("skip");
 975             print_int(n - skip_base);
 976             print_char('=');
 977             print_spec(equiv(n), "pt");
 978         } else {
 979             tprint_esc("muskip");
 980             print_int(n - mu_skip_base);
 981             print_char('=');
 982             print_spec(equiv(n), "mu");
 983         }
 984
 985     } else if (n < int_base) {
 986         /*
 987             Show equivalent |n|, in region 4
 988
 989             We initialize most things to null or undefined values. An undefined font
 990             is represented by the internal code |font_base|.
 991
 992             However, the character code tables are given initial values based on the
 993             conventional interpretation of ASCII code. These initial values should
 994             not be changed when \TeX\ is adapted for use with non-English languages;
 995             all changes to the initialization conventions should be made in format
 996             packages, not in \TeX\ itself, so that global interchange of formats is
 997             possible.
 998         */
 999         if ((n == par_shape_loc) || ((n >= etex_pen_base) && (n < etex_pens))) {
1000             if (n == par_shape_loc)
1001                 print_cmd_chr(set_tex_shape_cmd, n);
1002             else
1003                 print_cmd_chr(set_etex_shape_cmd, n);
1004             print_char('=');
1005             if (equiv(n) == null) {
1006                 print_char('0');
1007             } else if (n > par_shape_loc) {
1008                 print_int(penalty(equiv(n)));
1009                 print_char(' ');
1010                 print_int(penalty(equiv(n) + 1));
1011                 if (penalty(equiv(n)) > 1)
1012                     tprint_esc("ETC.");
1013             } else {
1014                 print_int(vinfo(par_shape_ptr + 1));
1015             }
1016         } else if (n < toks_base) {
1017             print_cmd_chr(assign_toks_cmd, n);
1018             print_char('=');
1019             if (equiv(n) != null)
1020                 show_token_list(token_link(equiv(n)), null, 32);
1021         } else if (n < box_base) {
1022             tprint_esc("toks");
1023             print_int(n - toks_base);
1024             print_char('=');
1025             if (equiv(n) != null)
1026                 show_token_list(token_link(equiv(n)), null, 32);
1027         } else if (n < cur_font_loc) {
1028             tprint_esc("box");
1029             print_int(n - box_base);
1030             print_char('=');
1031             if (equiv(n) == null) {
1032                 tprint("void");
1033             } else {
1034                 depth_threshold = 0;
1035                 breadth_max = 1;
1036                 show_node_list(equiv(n));
1037             }
1038         } else if (n == cur_font_loc) {
1039             /* Show the font identifier in |eqtb[n]| */
1040             tprint("current font");
1041             print_char('=');
1042             print_esc(hash[font_id_base + equiv(n)].rh);        /* that's |font_id_text(equiv(n))| */
1043         }
1044     } else if (n < dimen_base) {
1045         /* Show equivalent |n|, in region 5 */
1046         if (n < dir_base) {
1047             print_cmd_chr(assign_int_cmd, n);
1048             print_char('=');
1049             print_int(eqtb[n].cint);
1050         } else if (n < count_base) {
1051             print_cmd_chr(assign_dir_cmd, n);
1052             print_char(' ');
1053             print_dir(eqtb[n].cint);
1054         } else if (n < attribute_base) {
1055             tprint_esc("count");
1056             print_int(n - count_base);
1057             print_char('=');
1058             print_int(eqtb[n].cint);
1059         } else if (n < del_code_base) {
1060             tprint_esc("attribute");
1061             print_int(n - attribute_base);
1062             print_char('=');
1063             print_int(eqtb[n].cint);
1064         }
1065     } else if (n <= eqtb_size) {
1066         /* Show equivalent |n|, in region 6 */
1067         if (n < scaled_base) {
1068             print_cmd_chr(assign_dimen_cmd, n);
1069         } else {
1070             tprint_esc("dimen");
1071             print_int(n - scaled_base);
1072         }
1073         print_char('=');
1074         print_scaled(eqtb[n].cint);
1075         tprint("pt");
1076     } else {
1077         /* this can't happen either */
1078         print_char('?');
1079     }
1080 }
1081
1082 @ @c
1083 void show_eqtb_meaning(halfword n)
1084 {
1085     if (n < null_cs) {
1086         /* this can't happen */
1087         print_char('?');
1088     } else if ((n < glue_base) || ((n > eqtb_size) && (n <= eqtb_top))) {
1089         /*
1090             Show equivalent |n|, in region 1 or 2
1091
1092             Here is a routine that displays the current meaning of an |eqtb| entry
1093             in region 1 or~2. (Similar routines for the other regions will appear
1094             below.)
1095         */
1096         sprint_cs(n);
1097     } else if (n < local_base) {
1098         /*
1099             Show equivalent |n|, in region 3
1100
1101             All glue parameters and registers are initially `\.{0pt plus0pt minus0pt}'.
1102         */
1103         if (n < skip_base) {
1104             if (n < glue_base + thin_mu_skip_code)
1105                 print_cmd_chr(assign_glue_cmd, n);
1106             else
1107                 print_cmd_chr(assign_mu_glue_cmd, n);
1108         } else if (n < mu_skip_base) {
1109             tprint_esc("skip");
1110             print_int(n - skip_base);
1111         } else {
1112             tprint_esc("muskip");
1113             print_int(n - mu_skip_base);
1114         }
1115
1116     } else if (n < int_base) {
1117         /*
1118             Show equivalent |n|, in region 4
1119
1120             We initialize most things to null or undefined values. An undefined font
1121             is represented by the internal code |font_base|.
1122
1123             However, the character code tables are given initial values based on the
1124             conventional interpretation of ASCII code. These initial values should
1125             not be changed when \TeX\ is adapted for use with non-English languages;
1126             all changes to the initialization conventions should be made in format
1127             packages, not in \TeX\ itself, so that global interchange of formats is
1128             possible.
1129         */
1130         if ((n == par_shape_loc) || ((n >= etex_pen_base) && (n < etex_pens))) {
1131             if (n == par_shape_loc)
1132                 print_cmd_chr(set_tex_shape_cmd, n);
1133             else
1134                 print_cmd_chr(set_etex_shape_cmd, n);
1135         } else if (n < toks_base) {
1136             print_cmd_chr(assign_toks_cmd, n);
1137         } else if (n < box_base) {
1138             tprint_esc("toks");
1139             print_int(n - toks_base);
1140         } else if (n < cur_font_loc) {
1141             tprint_esc("box");
1142             print_int(n - box_base);
1143         } else if (n == cur_font_loc) {
1144             /* Show the font identifier in |eqtb[n]| */
1145             tprint("current font");
1146         }
1147     } else if (n < dimen_base) {
1148         /* Show equivalent |n|, in region 5 */
1149         if (n < dir_base) {
1150             print_cmd_chr(assign_int_cmd, n);
1151         } else if (n < count_base) {
1152             print_cmd_chr(assign_dir_cmd, n);
1153         } else if (n < attribute_base) {
1154             tprint_esc("count");
1155             print_int(n - count_base);
1156         } else if (n < del_code_base) {
1157             tprint_esc("attribute");
1158             print_int(n - attribute_base);
1159         }
1160     } else if (n <= eqtb_size) {
1161         /* Show equivalent |n|, in region 6 */
1162         if (n < scaled_base) {
1163             print_cmd_chr(assign_dimen_cmd, n);
1164         } else {
1165             tprint_esc("dimen");
1166             print_int(n - scaled_base);
1167         }
1168     } else {
1169         /* this can't happen either */
1170         print_char('?');
1171     }
1172 }