diff options
author | Soumith Chintala <soumith@gmail.com> | 2015-08-29 01:34:30 +0300 |
---|---|---|
committer | Soumith Chintala <soumith@gmail.com> | 2015-08-29 01:34:30 +0300 |
commit | 5700640456e4fbc94b214d841b3dbe5df6114521 (patch) | |
tree | 679dd09dc8fa067a893a7cac280d5eff993e2250 | |
parent | be5c68886b3e969515f9999a7893b1d061c656d2 (diff) | |
parent | 00bf7ebab296cc69757a247331ac099996e417b2 (diff) |
Merge pull request #13 from nicholas-leonard/rtd
readthedocs
-rw-r--r-- | README.md | 324 | ||||
-rw-r--r-- | doc/dirfunctions.md | 86 | ||||
-rw-r--r-- | doc/dirpaths.md | 78 | ||||
-rw-r--r-- | doc/filenames.md | 81 | ||||
-rw-r--r-- | doc/index.md | 14 | ||||
-rw-r--r-- | doc/misc.md | 59 | ||||
-rw-r--r-- | mkdocs.yml | 12 |
7 files changed, 337 insertions, 317 deletions
@@ -1,323 +1,13 @@ -<a name="paths.dok"/> +<a name="paths.dok"></a> # Filename Manipulation Package # -This package provides portable functions to manipulate filenames. +This package provides portable functions and variables to manipulate the file system : + + * [Manipulating filenames](doc/filenames.md) : functions for manipulating filenames ; + * [Directory functions](doc/dirfunctions.md) : functions for listing and manipulating directories ; + * [Directory paths](doc/dirpaths.md) : paths to well known directories ; + * [Miscellaneous](doc/misc.md) : uncategorized functions ; 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.extname"/> -### paths.extname(path) ### - -Return the extension of the `path` or nil if none is found. - -<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 and directories in directory `dname`. -This function return `nil` if the specified directory does not exists. -For linux, this includes the `.` and `..` directories. - -<a name="paths.files"/> -### paths.files(dname [, include]) ### - -Returns an iterator over the files and directories located in directory `dname`. -For linux, this includes the `.` and `..` directories. -This can be used in *__for__* expression as shown below: - -```lua -for f in paths.files(".") do - print(f) -end -``` - -Optional argument `include` is either a function or a string used to -determine which files are to be included. The function takes the filename -as argument and should return true if the file is to be included. -When a string is provided, the following function is used : - -```lua -function(file) - return file:find(f) -end -``` - -Files and directories of sub-folders aren't included. - -<a name="paths.iterdirs"/> -### paths.iterdirs(dname) ### - -Returns an iterator over the directories located in directory `dname`. -This can be used in *__for__* expression as shown below: - -```lua -for dir in paths.iterdirs(".") do - print(dir) -end -``` - -Directories of sub-folders, and the `.` and `..` folders aren't included. - -<a name="paths.iterdirs"/> -### paths.iterfiles(dname) ### - -Returns an iterator over the files (non-directories) located in directory `dname`. -This can be used in *__for__* expression as shown below: - -```lua -for file in paths.iterfiles(".") do - print(file) -end -``` - -Files of sub-folders, and the `.` and `..` folders aren't included. - -<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. - diff --git a/doc/dirfunctions.md b/doc/dirfunctions.md new file mode 100644 index 0000000..51584bb --- /dev/null +++ b/doc/dirfunctions.md @@ -0,0 +1,86 @@ +<a name="paths.dirs.dok"></a> +## Directory Functions ## + +The following functions can be used +to examine directory contents or manipulate directories. + +<a name="paths.dir"></a> +### paths.dir(dname) ### + +Return a table containing the files and directories in directory `dname`. +This function return `nil` if the specified directory does not exists. +For linux, this includes the `.` and `..` directories. + +<a name="paths.files"></a> +### paths.files(dname [, include]) ### + +Returns an iterator over the files and directories located in directory `dname`. +For linux, this includes the `.` and `..` directories. +This can be used in *__for__* expression as shown below: + +```lua +for f in paths.files(".") do + print(f) +end +``` + +Optional argument `include` is either a function or a string used to +determine which files are to be included. The function takes the filename +as argument and should return true if the file is to be included. +When a string is provided, the following function is used : + +```lua +function(file) + return file:find(f) +end +``` + +Files and directories of sub-folders aren't included. + +<a name="paths.iterdirs"></a> +### paths.iterdirs(dname) ### + +Returns an iterator over the directories located in directory `dname`. +This can be used in *__for__* expression as shown below: + +```lua +for dir in paths.iterdirs(".") do + print(dir) +end +``` + +Directories of sub-folders, and the `.` and `..` folders aren't included. + +<a name="paths.iterdirs"></a> +### paths.iterfiles(dname) ### + +Returns an iterator over the files (non-directories) located in directory `dname`. +This can be used in *__for__* expression as shown below: + +```lua +for file in paths.iterfiles(".") do + print(file) +end +``` + +Files of sub-folders, and the `.` and `..` folders aren't included. + +<a name="paths.mkdir"></a> +### paths.mkdir(s) ### + +Create a directory. +Returns `true` on success. + +<a name="paths.rmdir"></a> +### paths.rmdir(s) ### + +Delete an empty directory. +Returns `true` on success. + +<a name="paths.rmall"></a> +### paths.rmall(s, y) ### + +Recursively delete file or directory `s` and its contents. +Argument `y` must be string `"yes"` +Returns `true` on success. + diff --git a/doc/dirpaths.md b/doc/dirpaths.md new file mode 100644 index 0000000..b9216fc --- /dev/null +++ b/doc/dirpaths.md @@ -0,0 +1,78 @@ +<a name="paths.wellknowndirs.dok"></a> +## Directory Paths ## + +These variables indicate the paths where the various Torch components are installed, +as well as other common environment variables like `$HOME`. +It is not advisable to change their values! + +<a name="paths.install_prefix"></a> +### paths.install_prefix ### + +The base directory of the Torch installation. + +<a name="paths.install_bin"></a> +### 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"></a> +### paths.install_man ### + +The name of the directory containing the unix style manual pages. + +<a name="paths.install_lib"></a> +### 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"></a> +### 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"></a> +### paths.install_include ### + +The name of the directory containing the include files +for the various Torch libraries. + +<a name="paths.install_hlp"></a> +### paths.install_hlp ### + +The name of the directory containing the Torch help files. + +<a name="paths.install_html"></a> +### 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"></a> +### paths.install_cmake ### + +The name of the directory containing the CMake files +used by external Torch modules. + +<a name="paths.install_lua_path"></a> +### 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"></a> +### 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"></a> +### paths.home ### + +The home directory of the current user. + diff --git a/doc/filenames.md b/doc/filenames.md new file mode 100644 index 0000000..401e728 --- /dev/null +++ b/doc/filenames.md @@ -0,0 +1,81 @@ +<a name="paths.filenames.dok"></a> +## Manipulating Filenames ## + +The following functions can be used +to manipulate filenames in a portable way +over multiple platforms. + +<a name="paths.filep"></a> +### paths.filep(path) ### + +Return a boolean indicating whether `path` +refers to an existing file. + +<a name="paths.dirp"></a> +### paths.dirp(path) ### + +Return a boolean indicating whether `path` +refers to an existing directory. + +<a name="paths.basename"></a> +### 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"></a> +### paths.dirname(path) ### + +Return the name of directory containing file `path`. +This is similar to the well known shell command `"dirname"`. + +<a name="paths.extname"></a> +### paths.extname(path) ### + +Return the extension of the `path` or nil if none is found. + +<a name="paths.concat"></a> +### 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"></a> +### paths.cwd() ### + +Return the full path of the current working directory. + +<a name="paths.execdir"></a> +### 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"></a> +### 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. + diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..6dd23cc --- /dev/null +++ b/doc/index.md @@ -0,0 +1,14 @@ +<a name="paths.dok"></a> +# Filename Manipulation Package # + +This package provides portable functions and variables to manipulate the file system : + + * [Manipulating filenames](filenames.md) : functions for manipulating filenames ; + * [Directory functions](dirfunctions.md) : functions for listing and manipulating directories ; + * [Directory paths](dirpaths.md) : paths to well known directories ; + * [Miscellaneous](misc.md) : uncategorized functions ; + +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. + diff --git a/doc/misc.md b/doc/misc.md new file mode 100644 index 0000000..83283c7 --- /dev/null +++ b/doc/misc.md @@ -0,0 +1,59 @@ +<a name="paths.misc.dok"></a> +## Miscellaneous ## + +<a name="paths.uname"></a> +### 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"></a> +### paths.is_win() ### + +Returns true if the operating system is Microsoft Windows. + +<a name="paths.is_mac"></a> +### 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. + +<a name="paths.findingfiles.dok"></a> +<a name="paths.thisfile"></a> +### 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"></a> +### 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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..1fe86d1 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,12 @@ +site_name: paths +theme : simplex +repo_url : https://github.com/torch/paths +use_directory_urls : false +markdown_extensions: [extra] +docs_dir : doc +pages: +- [index.md, Paths] +- [filenames.md, Manipulating Filenames] +- [dirfunctions.md, Directory Functions] +- [dirpaths.md, Directory Paths] +- [misc.md, Miscellaneous] |