Difference between revisions of "System Macros/Scratch Variables"

From Wiki
Jump to navigation Jump to search
m (Basic navigation)
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
< '''Prev:''' [[System Macros/Mnemonics and Aliases|Mnemonics & Aliases]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/Expansion Control|Expansion Control]] >
 
< '''Prev:''' [[System Macros/Mnemonics and Aliases|Mnemonics & Aliases]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/Expansion Control|Expansion Control]] >
  
Because we often need counters on a temporary basis, we define the <''counter''> <code>\scratchcounter</code>. This is a real <''counter''>, and not a pseudo one, as we will meet further on. The others are analogous scratch registers.
+
=== Scratch registers ===
  
A warning is in order here. Yes, you can use these registers in your own macrocode. But '''not''' across calls to internal ConTeXt macros. While ConTeXt always makes sure that the registers are cleared on entry to the call, it usually doesn't bother to restore your user supplied value when it returns.
+
Because values often need to be saved only temporarily, ConTeXt defines the <''counter''> <code>\scratchcounter</code>. This is a real <''counter''>, and not a pseudo one, as we will meet further on. Analogous scratch registers are <code>\scratchdimen</code>, <code>\scratchskip</code>, <code>\scratchmuskip</code>, <code>\scratchtoks</code> and <code>\scratchbox</code>. You can use these registers in your own macro code, but a warning is in order:
  
ConTeXt also uses a rather large collection of other internal scratch registers. Their names all look like this: <code>\!!XXXXXY</code>, where <code>XXXXX</code> is something like 'count' or 'depth', and <code>Y</code> is a letter starting from <code>a</code> (e.g. <code>\!!counta</code>). The fact that their names start with <code>!!</code> is a clear statement: Don't touch them, it's dangerous. If you need scratch registers, define your own.
+
Do '''not''' expect it to be safe to use any of the scratch registers across any call to any internal ConTeXt macro. While ConTeXt is supposed to make sure that the scratch registers it needs are initialized on entry to the internal macro, it doesn't bother to restore the original value when it returns from that macro, so you never know what will be in any scratch register afterwards.
  
ConTeXt uses yet another set of constants and variables to store all sorts of string values in (macro names occupy less space in TeX's memory than the strings themselves).
+
ConTeXt uses a rather large collection of other scratch registers itself. Their names all look like this: <code>\!!XXXXXY</code>, where <code>XXXXX</code> is something like 'count' or 'depth', and <code>Y</code> is a letter starting from <code>a</code> (e.g. <code>\!!counta</code>). The fact that their names start with <code>!!</code> is a clear statement: Don't touch them, it's dangerous. If you need extra scratch registers, define your own.
  
For this reason, you should also not touch the definitions of macros that start with
+
=== Scratch commands ===
  
* <code>\s!</code> (constant string),
+
ConTeXt uses another large set of 'scratch' commands to store all sorts of string values in, because if you have to repeat them more than once inside a macro definition, then macro names occupy less space in TeX's memory than the strings themselves).
* <code>\c!</code> (constant),
 
* <code>\p!</code> (parameter),
 
* <code>\v!</code> (variable),
 
* <code>\@@</code> (multi-lingual interface parameter expansion),
 
* <code>\??</code> (multi-lingual interface parameter call).
 
  
Redefining these macros can have disastrous results.
+
For this reason, you should not define or alter macro names that start with
 +
 
 +
* <code>\s!</code>: These are macros holding ''system constants'', i.e. values that never change
 +
* <code>\c!</code>: These are macros holding ''constant keys'' in key-value pairs. The actual definitions depend on the multi-lingual interface that is currently being used
 +
* <code>\v!</code>: These are macros holding names of ''variable values'' in key-value pairs. The actual definitions depend on the multi-lingual interface that is currently being used
 +
* <code>\??</code>: These are multi-lingual interface constant calls.
 +
* <code>\@@</code>: These are results of a multi-lingual interface constant expansion.
 +
 
 +
By far the safest approach to defining your own scratch macros is to make them mixed case.
  
 
< '''Prev:''' [[System Macros/Mnemonics and Aliases|Mnemonics & Aliases]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/Expansion Control|Expansion Control]] >
 
< '''Prev:''' [[System Macros/Mnemonics and Aliases|Mnemonics & Aliases]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/Expansion Control|Expansion Control]] >

Revision as of 10:42, 9 October 2010

< Prev: Mnemonics & Aliases | Top: System Macros | Next: Expansion Control >

Scratch registers

Because values often need to be saved only temporarily, ConTeXt defines the <counter> \scratchcounter. This is a real <counter>, and not a pseudo one, as we will meet further on. Analogous scratch registers are \scratchdimen, \scratchskip, \scratchmuskip, \scratchtoks and \scratchbox. You can use these registers in your own macro code, but a warning is in order:

Do not expect it to be safe to use any of the scratch registers across any call to any internal ConTeXt macro. While ConTeXt is supposed to make sure that the scratch registers it needs are initialized on entry to the internal macro, it doesn't bother to restore the original value when it returns from that macro, so you never know what will be in any scratch register afterwards.

ConTeXt uses a rather large collection of other scratch registers itself. Their names all look like this: \!!XXXXXY, where XXXXX is something like 'count' or 'depth', and Y is a letter starting from a (e.g. \!!counta). The fact that their names start with !! is a clear statement: Don't touch them, it's dangerous. If you need extra scratch registers, define your own.

Scratch commands

ConTeXt uses another large set of 'scratch' commands to store all sorts of string values in, because if you have to repeat them more than once inside a macro definition, then macro names occupy less space in TeX's memory than the strings themselves).

For this reason, you should not define or alter macro names that start with

  • \s!: These are macros holding system constants, i.e. values that never change
  • \c!: These are macros holding constant keys in key-value pairs. The actual definitions depend on the multi-lingual interface that is currently being used
  • \v!: These are macros holding names of variable values in key-value pairs. The actual definitions depend on the multi-lingual interface that is currently being used
  • \??: These are multi-lingual interface constant calls.
  • \@@: These are results of a multi-lingual interface constant expansion.

By far the safest approach to defining your own scratch macros is to make them mixed case.

< Prev: Mnemonics & Aliases | Top: System Macros | Next: Expansion Control >