Low-level output
Functions belonging to this set let you print, colorize, and format different output elements and define the whole look of the output.
PrintType(String) PrintName(String) PrintPunctuation(String) PrintNumber(String) TypeWidth NameWidth CrLf() UnCrLf() StartFolding() EndFolding() HideFoldings(Hide) IncIndent() DecIndent() HideAddressBar() UpdateAddress() AlignToColumn(Column) PrintDoubleQuotedString(String) PrintSingleQuotedString(String) BlockComment(Comment, IsWarning) PrintSLCommentNA(Comment) PrintSLComment(Comment) PrintWarningComment(Comment) PrintMLComment(Comment) PrintComment(String) Warning CommentPos StartType(Type, Name) EndType(Comment) StartStruct(Type, Name, Comment) EndStruct(Comment) State = SaveState() RestoreState(State)
PrintType(String)
PrintName(String)
PrintPunctuation(String)
PrintNumber(String)
TypeWidth
NameWidth
These functions print different parts of a type definition. Intention of each function is clearly understandable from its name. Here's an example how the TempLuator output usually looks for basic types:
LONG e_lfanew = 0x00000080;I hope it is clear that in this example "LONG" is printed using the PrintType() function, "e_lfanew" using the PrintName() function, "0x00000080" using the PrintNumber() function, and all the punctuation marks ("=" and ";") are printed using the PrintPunctuation() function.
All these function require a single mandatory parameter which must evaluate to a string. Quite naturally, it is OK to feed them with numbers because as usually Lua does the necessary conversion.
Two global variables - TypeWidth and NameWidth - define the widths (in characters) of type and name fields printed by the PrintType() and PrintName() functions correspondingly. For example, if you call PrintType("LONG") and TypeWidth is 8, then the type will be padded with 4 spaces (that is, "LONG____", where underscores means spaces). These variables allow neat alignment of the output.
Exactly as the name suggests, this function moves the caret (and therefore the current output position) to the next line.
This function deletes the current line and the caret goes to the previous line. As far as I remember, there were some anomalies with this function so please use it with care.
StartFolding()
EndFolding()
HideFoldings(Hide)
These functions let you manage folding, which is the possibility to collapse/expand a part of the output, for example, a structure. The StartFolding() function starts new folding and EndFolding() ends the current folding. It is perfectly OK to use nested foldings. The only thing you should keep in mind is that each call to StartFolding() must be followed by the corresponding EndFolding() call, otherwise you will get an error at the end of your script. Also, please consider that there is a limit for nested foldings. However, since it is set to a pretty big value (255 or something), I don't think this is going to become an important issue.
The HideFoldings() function expects one boolean parameter, which, if set to true, tells TempLuator to automatically collapse all subsequent foldings. If this parameter is omitted or evaluates to false, all subsequent foldings will be in expanded state.
These functions let you manage indentation, that is, amount of tabs inserted at the beginning of each new line before the very first output character. When TempLuator starts, indentation is reset to zero so there is no additional tabs. It is not possible to overcome some indentation limits: indentation cannot become greater than some value (255 or something similar) and without any doubts indentation cannot become negative. Each tab is equivalent to 4 spaces.
HideAddressBar()
UpdateAddress()
The first function lets you - surprise, surprise! - hide the Address Bar, which is a separate column placed at the left side of the screen that contains hexadecimal addresses. You cannot turn it on back again without restarting your script so please be careful. The second function looks for the current offset in the input file and sets address of the current line to this address. Usually, you don't have to call this function because all high-level output functions update this address automatically (when the CrLf() function is somehow called, to be precise). However, there may be situations when you want to skip a part of the input file so in this case this function may be handy. Try the following code with and without UpdateAddress() and you will immediately realize what this function is intended for.
-- let's suppose the current file position is 0x0 -- we want to process a DWORD, then skip 0x80 bytes and then process another DWORD DWORD "Qwerty" -- now we are at the new line and the current address is 0x4 -- however, we don't need it because we're going to skip the next 0x80 bytes SkipBytes(0x80) -- now the current file position is 0x84 and we want to process a DWORD at this address -- comment the next line to see the effect of UpdateAddress() UpdateAddress() DWORD "Asdfg"
As the name suggests, this function inserts necessary amount of spaces so that the caret (and therefore the current output position) goes to the given column thus making the output horizontally aligned. The only mandatory numerical parameter defines the column to align to. If this parameter is less than the current output position, no alignment occurs at all. Internally this function is used for alignment of commentaries in order to make the output look neat.
PrintDoubleQuotedString(String)
PrintSingleQuotedString(String)
These two functions allow printing of text strings in compliance with C rules for strings of characters. The whole string printed by these functions gets enclosed either with single or double quotes depending on the function. All non-printable characters are printed either as standard escape sequences (like "\r\n") or as hex codes (like \x01). If a string passed to these functions is way too long (longer than 512 characters), only the first part of the string gets printed followed by an ellipsis (...): "This is a very long string that cannot be typed in its entir...".
BlockComment(Comment, IsWarning)
This function prints given text (the mandatory Comment parameter) as a specially aligned and formatted commentary. For example, if Comment is "\rThis is a commentary\rthat is neatly aligned\r\r" and indentation is set to 1 , then the output will look like this:
// // This is a commentary // that is neatly aligned //The second (optional) boolean parameter, if evaluates to true, makes the function to print the comment with color used for printing error/warning messages. This color is usually red but you can change it using the SetWarningCommentColors() function.
PrintSLCommentNA(Comment)
PrintSLComment(Comment)
These functions let you print C-style single line (therefore SL in the function names) comments (defined in C using the "//" notation). The NA variant does not perform any alignment, that is, it outputs the commentary right there where the current caret position is. The other function performs commentary alignment. See CommentPos. The only mandatory parameter must evaluate to a string. The "// " part gets inserted automatically so it is not necessary in the input string.
This is basically the same as the PrintSLComment() function above with the only exception that this function highlights the comment with the error/warning color set via the SetWarningCommentColors() function (usually red).
This function prints C-style multiline (see ML in the name) comments (defined in C using the "/* ... */" notation). The single mandatory parameter (which must evaluate to string) can contain '\r' and '\n' characters. Both will move caret to the next line, however, the '\n' character unlike '\r' will ignore indentation.
Basically, this function is equivalent to PrintSLComment(). This is absolutely true if the value of the global variable Warning is nil (which is the default). However, when this is not true and you assign a string to the Warning wariable, the function does the following: it appends the text of Warning to the string passed to the function, sets Warning back to nil and prints the whole string using the PrintWarningComment() function. This may be convenient, for example, in the following situation:
-- we want to check if this is really a 'MZ' file. However, even when this is not the case, -- we want to process the rest of the file normally and just inform the user about wrong file type if PeekUI16() ~= IMAGE_DOS_SIGNATURE then Warning = "should be 'MZ'" end WORD("e_magic", "Magic number")In the example above if the file is really an executable, the comment for e_magic is going to be "// Magic number". Otherwise, the comment will be "// Magic number should be 'MZ'" and the whole comment will be marked with red color. Please note that the function resets Warning to nil each time it is called so the next invocation of the function will not mark comments with red color until you set the Warning variable again.
This global variable defines alignment of single-line comments. By default is is equal to 70 but you may change it to anything you want. When a single-line comment ("// blah-blah-blah") is ready to be printed, TempLuator checks the current column and, if necessary, inserts the proper amount of spaces so that all comments start in the same column and are therefore vertically aligned. Please note that the CommentPos variable does not affect single line comments printed by the PrintSLCommentNA() function.
StartType(Type, Name)
EndType(Comment)
These two internal functions are used for printing types. The StartType() function expects type and name of the current type and prints them using the PrintType() and PrintName() functions correspondingly. Also, this function prints the "=" sign before the actual value of the type. The EndType() expects optional parameter which is printed using the PrintComment() function. In addition, this function prints the ";" sign after the actual value of the type and moves the caret to the next line.
StartStruct(Type, Name, Comment)
EndStruct(Comment)
These two internal functions start and end structures defined using the struct() function. The StartStruct() function does the following: prints type and name of the instance using the StartType() function, prints comment if necessary, moves the caret to the next line, starts new folding, prints the "{" sign, increments indentation and moves the caret to the next line. The EndStruct() function decreases indentation, types the "}" sign, ends the current folding and prints the supplied comment using the EndType() function.
State = SaveState()
RestoreState(State)
These two functions let save and later restore current output state. The SaveState() returns a table containing the snapshot of the current output state. The RestoreState() expects this snapshot as the only mandatory parameter. The snapshot contains the following information: current number output mode as returned by the SaveNumberOutputMode() function and values of the TypeWidth, NameWidth, and CommentPos global variables.