Difference between revisions of "Misc Functions"
(→logMessage) |
(→getFileName) |
||
Line 200: | Line 200: | ||
-- path should now contain "C:/testing" | -- path should now contain "C:/testing" | ||
</source> | </source> | ||
+ | |||
+ | |||
+ | == getDirectory == | ||
+ | '''dir getDirectory''' | ||
+ | |||
+ | Returns a table containing the file names (without path) of all files and/or directories in the specified directory. | ||
+ | |||
+ | '''Example''' | ||
+ | <source lang="lua"> | ||
+ | dir = getDirectory(getExecutionPath()); | ||
+ | |||
+ | printf("Files and directories in %s:\n", getExecutionPath()); | ||
+ | for i,v in pairs(dir) do | ||
+ | printf(" ==> %i:\t%s\n", i, v); | ||
+ | end | ||
+ | </source> | ||
+ | |||
+ | The above example will produce the following (example) output: | ||
+ | Files and directories in C:/MicroMacro/scripts: | ||
+ | ==> 1: script1.lua | ||
+ | ==> 2: script2.lua | ||
+ | ==> 3: script3.lua | ||
+ | ==> 4: subdirectory |
Revision as of 00:07, 13 November 2008
Contents
args
The 'args' table holds command-line-like data that is passed to the script when it is executed.
The first argument (args[1]) will always be the script name as typed by the user, while the rest of the arguments are tokenized by spaces. That is, if you run the script "test.lua testing 123", args[1] contains the script name ("test.lua"), args[2] contains "testing" and args[3] contains the number 123.
Example
-- Assume the user typed in: script.lua something
if( args[2] ) then
-- They have added an argument to the script call.
if( args[2] == "something" ) then
-- The user wants us to do something!
do_something();
end
end
rest
rest(time)
Causes the macro to pause for some 'time' milliseconds (1/1000th of a second).
Example
rest( 1000 ); -- 1 second will elapse before continuing.
pluginInstalled
pluginInstalled(name)
Returns true if a plugin with the given name is installed. You should not include the ".dll" extension. Plugin checks are not case sensitive.
Example
if( pluginInstalled("myplugin") ) then
printf("MyPlugin is successfully installed.\n");
end
setPriority
setPriority(priority)
Sets the macro interpreter's priority. You should pass in one of following variables: priority.high, priority.normal, or priority.low. Use this to overcome processes fighting over timeslice. If you don't understand what this does, you probably won't need it.
Example
setPriority(priority.high);
logMessage
logMessage(message)
Adds a formatted log message (string only) to the log file. Follows the format: "{time} : {message}\n", where {message} is a string containing the text you want logged. The newline marker is automatically appended.
If you would like to format your own messages, see logRaw().
Example
logMessage("This is an example logged message.");
This may at first seem restrictive as it only allows you to input a single string. If you would like to place strings, numbers, or other datas into the string that you want to log, you simply need to format it first using sprintf() or other string-formatting functions.
Example
local myStr = sprintf("PI: %0.4f", 3.1415926);
logMessage(myStr);
logRaw
logRaw(message)
Adds a message (string or number) directly to the log file without formatting. You may use this function to format your own messages.
Example
logRaw("My favorite number is ");
logRaw(12);
logRaw("\n");
getVersion
getVersion()
Returns MicroMacro's version number as an integer. A value of 100 would be equivilent to version 1.0, or a value of 95 would be equivilent to version 0.95. This can be used to check whether or not an end user's version of MicroMacro supports functions in a script you are designing. You can use division and modulo to separate the major and minor version numbers from the value returned, as done in the example.
Example
version = getVersion();
major = math.floor(version / 100);
minor = version % 100;
io.write("MicroMacro v", major, ".", minor, "\n");
-- This will print (assume we are using micromacro 1.0):
-- MicroMacro v1.0
setTextColor
setTextColor(cli.col)
Sets the color for output text. This will remain into effect until the text color is changed again using setTextColor, so you should probably use cprintf() to make your life easier. 'cli.col' must be an option from the cli module (lib/mods/cli.lua), and you may not use makeColor().
cli.lightgray is the default text color. If you decide to use this function, you should always return back to cli.lightgray when you are done outputting different colored text.
Example
setTextColor(cli.green);
printf("Green text!\n");
setTextColor(cli.lightgray);
showWarnings
showWarnings(bool)
This function enables or disables the showing of warnings such as memory read/write failures. Warnings should only be disabled on near-complete projects that have extensive error checking in place. By default, showing warnings is turned on (true).
Example
local err;
showWarnings(false); -- hide warnings.
err = memoryWriteInt(proc, location, value);
showWarnings(true); -- turn them back on.
if( err ) then
printf("Some error occured.\n");
end
getExectionPath
path getExectionPath()
Returns the 'working directory' or 'execution path' of the main(executed) script. That is, if you execute a script in C:/micromacro/scripts/, this function will return the string "C:/micromacro/scripts". The final "/" is not included.
Your working directory will not change when you include() or dofile() other scripts. Only when executing another script, or using setExecutionPath().
Example
local basepath = getExecutionPath();
printf("Base: %s\n", basepath);
setExectionPath
setExectionPath(path)
Changes the 'working directory' or 'execution path'. You may change your working path with this function to make your job easier when using the include() function.
Example
-- this will include the file C:/myscript.lua
setExecutionPath("C:/");
include("myscript.lua");
getFilePath
path getFilePath(fullpath)
Returns just the path segment (not including final slash and file name with extension) of a fully qualified path.
Example
local file = "C:/testing/myscript.lua";
local path = getFilePath(file);
printf("The path of \'file\' is \'%s\'\n", path);
-- path should now contain "C:/testing"
getFileName
path getFileName(fullpath)
Returns just the file name segment (including extension) of a fully qualified path.
Example
local fullpath = "C:/testing/myscript.lua";
local filename = getFileName(fullpath);
local path = getFilePath(fullpath);
-- filename should now contain "myscript.lua"
-- path should now contain "C:/testing"
getDirectory
dir getDirectory
Returns a table containing the file names (without path) of all files and/or directories in the specified directory.
Example
dir = getDirectory(getExecutionPath());
printf("Files and directories in %s:\n", getExecutionPath());
for i,v in pairs(dir) do
printf(" ==> %i:\t%s\n", i, v);
end
The above example will produce the following (example) output:
Files and directories in C:/MicroMacro/scripts: ==> 1: script1.lua ==> 2: script2.lua ==> 3: script3.lua ==> 4: subdirectory