diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..7c9d606 --- /dev/null +++ b/README.md @@ -0,0 +1,279 @@ +<a name="paths.dok"/> +# Filename Manipulation Package # + +This package provides portable functions to manipulate filenames. + +When this package is loaded, it also computes a number of useful +variables indicating where the various Torch components are installed. +Do not change their values. + + +<a name="paths.filenames.dok"/> +## Manipulating file names ## + +The following functions can be used +to manipulate filenames in a portable way +over multiple platforms. + + +<a name="paths.filep"/> +### paths.filep(path) ### + +Return a boolean indicating whether `path` +refers to an existing file. + +<a name="paths.dirp"/> +### paths.dirp(path) ### + +Return a boolean indicating whether `path` +refers to an existing directory. + +<a name="paths.basename"/> +### paths.basename(path,[suffix]) ### + +Return the last path component of `path` +and optionally strip the suffix `suffix`. +This is similar to the well know shell command `"basename"`. + +<a name="paths.dirname"/> +### paths.dirname(path) ### + +Return the name of directory containing file `path`. +This is similar to the well known shell command `"dirname"`. + +<a name="paths.concat"/> +### paths.concat([path1,....,pathn]) ### + +Concatenates relative filenames. + +First this function computes the full filename +of `path1` relative to the current directory. +Then it successively computes the full filenames +of arguments `path2` to `pathn` relative to +the filename returned for the previous argument. +Finally the last result is returned. + +Calling this function without argument returns the +full name of the current directory. + + +<a name="paths.cwd"/> +### paths.cwd() ### + +Return the full path of the current directory. + + +<a name="paths.execdir"/> +### paths.execdir() ### + +Return the name of the directory containing the +current Lua executable. +When the module `paths` is first loaded, +this information is used to relocate +the variables indicating +the location of the various Torch components. + + +<a name="paths.tmpname"/> +### paths.tmpname() ### + +Return the name of a temporary file. +All the temporaty files whose name was obtained in this way +are removed when Lua exits. + +This function should be preferred over `os.tmpname()` +because it makes sure that the files are removed on exit. +In addition, `os.tmpname()` under windows often returns filenames +for which the user has no permission to write. + + + + +<a name="paths.dirs.dok"/> +## Directory functions ## + +The following functions can be used +to examine directory contents or manipulate directories. + + +<a name="paths.dir"/> +### paths.dir(dname) ### + +Return a table containing the files in directory `dname`. +This function return `nil` if the specified directory +does not exists. + +<a name="paths.files"/> +### paths.files(dname) ### + +Returns an iterator over the files located in directory `dname`. +This can be used in *__for__* expression as shown below: +``` + for f in paths.files(".") do + print(f) + end +``` + +<a name="paths.mkdir"/> +### paths.mkdir(s) ### + +Create a directory. +Returns `true` on success. + +<a name="paths.rmdir"/> +### paths.rmdir(s) ### + +Delete an empty directory. +Returns `true` on success. + +<a name="paths.rmall"/> +### paths.rmall(s, y) ### + +Recursively delete file or directory `s` and its contents. +Argument `y` must be string `"yes"` +Returns `true` on success. + + +<a name="paths.findingfiles.dok"/> +## Finding files relative to a Lua script ## + +<a name="paths.thisfile"/> +### paths.thisfile([arg]) ### + +Calling `paths.thisfile()` without argument +inside a lua file returns returns the full +pathname of the file from which it is called. +This function always returns `nil` when called +interactively. + +Calling `paths.thisfile(arg)` with a string argument `arg` +returns the full pathname of the file `arg` relative +to the directory containing the file from which +function `paths.thisfile` is invoked. This is useful, +for instance, to locate files located in the same +directory as a lua script. + + +<a name="paths.dofile"/> +### paths.dofile(filename) ### + +This function is similar to the standard Lua function `dofile` +but interprets `filename` relative to the directory containing +the file that contains the call to `paths.dofile`, +or to the current directory when `paths.dofile` is +called interactively. + +<a name="paths.wellknowndirs.dok"/> +## Well known directories ## + +These variables indicate where the various Torch components are installed. +It is not advisable to change their values! + + +<a name="paths.install_prefix"/> +### paths.install_prefix ### + +The base directory of the Torch installation. + +<a name="paths.install_bin"/> +### paths.install_bin ### + +The name of the directory containing the executable programs. +Under Windows, this directory also contains +the dynamically loadable libraries (`.dll`). + +<a name="paths.install_man"/> +### paths.install_man ### + +The name of the directory containing the unix style manual pages. + +<a name="paths.install_lib"/> +### paths.install_lib ### + +The name of the directory containing the object code libraries. +Under Unix, this directory also contains the dynamically +loadable libraries (`.so` or `.dylib`). + +<a name="paths.install_share"/> +### paths.install_share ### + +The name of the directory containing processor independent data files, +such as lua code and other text files. + +<a name="paths.install_include"/> +### paths.install_include ### + +The name of the directory containing the include files +for the various Torch libraries. + +<a name="paths.install_hlp"/> +### paths.install_hlp ### + +The name of the directory containing the Torch help files. + +<a name="paths.install_html"/> +### paths.install_html ### + +The name of the directory containing the HTML version +of the Torch help files. These files are generated +when you enable the CMake option `HTML_DOC`. + +<a name="paths.install_cmake"/> +### paths.install_cmake ### + +The name of the directory containing the CMake files +used by external Torch modules. + +<a name="paths.install_lua_path"/> +### paths.install_lua_path ### + +The name of the directory containing the Lua packages. +This directory is used to build variable `package.path`. + +<a name="paths.install_lua_cpath"/> +### paths.install_lua_cpath ### + +The name of the directory containing the Lua loadable binary modules. +This directory is used to build variable `package.cpath`. + +<a name="paths.home"/> +### paths.home ### + +The home directory of the current user. + + +<a name="paths.misc.dok"/> +## Miscellaneous ## + + +<a name="paths.uname"/> +### paths.uname() ### + +Returns up to three strings describing the operating system. +The first string is a system name, e.g., "Windows", "Linux", "Darwin", "FreeBSD", etc. +The second string is the network name of this computer. +The third string indicates the processor type. + +<a name="paths.is_win"/> +### paths.is_win() ### + +Returns true if the operating system is Microsoft Windows. + +<a name="paths.is_mac"/> +### paths.is_mac() ### + +Returns true if the operating system is Mac OS X. + +### paths.getregistryvalue(key,subkey,value) ### + +Query a value in the Windows registry value. +Causes an error on other systems. + +### paths.findprogram(progname,...) ### + +Finds an executable program named "progname" and returns its full path. +If none is found, continue searching programs named after the following arguments +and return the full path of the first match. +All the directories specified by the PATH variable are searched. +Under windows, this also searches the "App Path" registry entries. + |