Macro definition

To facilitate the process of solving the cube, macros have been provided for cubes of all available sizes. The term macro as used in computer science is a rule or pattern that specifies how a certain input sequence should be mapped into an output sequence. If, for example, the character x is never used for basic input we could create a macro x = abcd. Whenever the user types x, the program would substitute abcd for that. Macros simplify things in Unravel by providing short-cuts for long sets (or frequently used short sets) of instructions on how to rearrange the cube. In Rubik's cube parlance, command sequences that perform non-trivial transformations are often referred to as algorithms. Such algorithms are prime candidates for macro implementation.

Default macros are internally generated in the Unravel program with the aid of the urvmac.txt text file. Macros are created within a pure text file that is subsequently decoded for internal use. For the standard cube with unmarked centres, the default filename for a macro command file is urvcmdnn.txt (where nn represents the cube size and ranges from 02 to MaxCubeSize). While many macros are the same for cubes of different size, some differences apply and hence a different macro command file is required for each cube size. Cubes with marked centres involve command file variations that also mean that distinguishing names are required for the files.

A macro is defined in the following manner:
     * MacroName = MacroDefinition

Character * at the start of a line signifies that the line defines a macro.

The MacroName can be either Alphabetical or Numerical. An Alphabetical MacroName consists of a single alphabetical character except F, B, L, R, U, D, W and M (reserved symbols). There are thus 18 allowable Alphabetical MacroNames:

A, C, E, G, H, I, J, K, N, O, P, Q, S, T, V, X, Y, and Z.

Numerical MacroNames are formed by placing a number within angle brackets (or without brackets if the character M precedes the number). Numerical MacroNames conform to the arrangement <(Row)(Column)> where Row and Column conform to a coordinate structure that facilitates the use of such macros particularly for centre cubie placement. For convenience, designate a row digit as R and a column digit as C. For cubes of size less than 17, a total of two digits is used, whereas for cubes of size greater than 16, a total of four digits is used. That results in numerical macros of the form <RC> (two-digit MacroName) and <RRCC> (four digit MacroName) respectively. For the two-digit MacroName, R and C are hexadecimal digits. The hexadecimal row and column numbers follow the standard hexadecimal sequence 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F. For the four-digit MacroName, all digits are decimal with Row and Column numbers below 10 required to have leading zeros.

Most people are likely to utilize the default numerical macros rather than generate their own, and the aim here is to describe how those macros are to be used. The default numerical macros are used for final edge cube set and centre cubie placement on the front face. The origin to be used for numerical macros is the top left corner cube on the front face. The Program Settings dialog allows the user to define the origin as (Row 0, Column 0) or (Row 1, Column 1) with the latter being the default. The optional origins will be referred to as base 0 and base 1 respectively. The base 1 origin corresponds with the number system used for multi-layer rotations. When applying numerical macros the user needs to count rows and columns relative to the origin. If the program is run in applet mode, a change in origin will be reflected only in macro command files subsequently generated during the session. To change any existing default macro command files stored on the user's computer, when running in application (non-applet) mode, the files need to be deleted and the program will regenerate them according to the changed origin, provided the default macro load option "Read macro files from user's computer" is in use.

Sample alphabetical, and two and four-digit numerical macros, are shown below:
  * P = FUURU-RUU-F
  * Q = P-UP
  * <7C> = #12B#7U-#12BU#12B-#7U-#12BUU
  * <1214> = #14B#12U-#14BU#14B-#12U-#14BUU

If users develop numerical macros of their own, the valid range for Numerical MacroNames needs to be known. Define cube size as n, and for that size cube define Colmax as the maximum allowable column number and Rowmax as the maximum allowable row number. For both unmarked and marked versions the following limits apply:
    Colmax = n
    Rowmax = n

The example below for cube size 14 indicates the MacroNames that will be accepted for that cube size. Most macros are used for centre cubie placement. The MacroNames shown in black are used for centre cubie placement in the default macro set for base equal to 1 for cube size 14.

<00> <01> <02> .... <07> <08> .... <0C> <0D>
<10> <11> <12> .... <17> <18> .... <1C> <1D>
<20> <21> <22> .... <27> <28> .... <2C> <2D>
.... .... .... .... .... .... .... .... ....
<D0> <D1> <D2> .... <D7> <D8> .... <DC> <DD>

The example below for cube size 25 indicates the MacroNames that will be accepted for that cube size. The MacroNames shown in black are used for centre cubie placement in the default macro set for base equal to 1.

<0000> <0001> <0002> ...... <0023> <0024>
<0100> <0101> <0102> ...... <0123> <0124>
<0200> <0201> <0202> ...... <0223> <0224>
...... ...... ...... ...... ...... ......
<2400> <2401> <2402> ...... <2423> <2424>

Brackets (round, square or curly) can be used after the "=" in macro definitions but will result in an error message if used before the "=". The brackets are ignored when macros are decoded.

Differences when running in Application Program Mode and Applet Program Mode are detailed below.

Application Program Mode

In application mode the Unravel Options dialog allows a choice between unconditional loading the default macro set via the program using option "Use default macros" and loading from an external file using the "Read macro files from user's computer" option. The former is the default option. If the latter option is in use, the program will look for a macro command (definition) file as soon as the cube size has been set, when operating in Auto mode. The macro command file has name urvcmdnny.txt where "nn" represents cube size and "y" represents an identifier that is added if marked centres are in use.

When operating in Menu mode the macros can be loaded at any time a valid cube size has been set. The user will be prompted to load the macros (if they have not been previously loaded) before the Command Sequence input dialog, used for unravelling the cube, is opened.

If the macro command file for the selected cube size is not found, the user will be granted the option of generating the default macro command file and loading the macros. Macros can be changed or extended by editing the urvcmdnny.txt file on-line, or off-line with a text editor. By deleting the urvcmdnny.txt file (or retaining it under a different name), the default macro set can be automatically re-invoked.

Applet Program Mode

When operating in applet program mode, the program default is to load the program's default macro set. It is recommended that the default macro set be used when operating in applet program mode. However, users can generate their own macro set by editing the default macro set on-line and utilizing the Macro Input Text dialog to copy the new macro file to the clipboard and then pasting that in a file and directory of their choosing on their computer. The recommended name is urvcmdnny.txt where nn and "y" have meanings as indicated above.