From 9cbe5cba9047b449308e1365690b0a5acfdef181 Mon Sep 17 00:00:00 2001 From: Hisham Muhammad Date: Fri, 24 Jun 2022 12:12:13 -0300 Subject: Move doc/us/ to docs/, replacing the gh-pages branch. --- docs/doc.css | 209 ++++++++++++++++++++++++++++++++++++ docs/examples.html | 101 +++++++++++++++++ docs/index.html | 230 +++++++++++++++++++++++++++++++++++++++ docs/license.html | 108 +++++++++++++++++++ docs/luafilesystem.png | Bin 0 -> 8535 bytes docs/manual.html | 286 +++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 934 insertions(+) create mode 100644 docs/doc.css create mode 100644 docs/examples.html create mode 100644 docs/index.html create mode 100644 docs/license.html create mode 100644 docs/luafilesystem.png create mode 100644 docs/manual.html (limited to 'docs') diff --git a/docs/doc.css b/docs/doc.css new file mode 100644 index 0000000..f233ce4 --- /dev/null +++ b/docs/doc.css @@ -0,0 +1,209 @@ +body { + color: #47555c; + font-size: 16px; + font-family: "Open Sans", sans-serif; + margin: 0; + padding: 0; + background: #eff4ff; +} + +a:link { color: #008fee; } +a:visited { color: #008fee; } +a:hover { color: #22a7ff; } + +h1 { font-size:26px; } +h2 { font-size:24px; } +h3 { font-size:18px; } +h4 { font-size:16px; } + +hr { + height: 1px; + background: #c1cce4; + border: 0px; + margin: 20px 0; +} + +code { + font-family: "Open Sans Mono", "Andale Mono", monospace; +} + +tt { + font-family: "Open Sans Mono", "Andale Mono", monospace; +} + +body, td, th { +} + +textarea, pre, tt { + font-family: "Open Sans Mono", "Andale Mono", monospace; +} + +img { + border-width: 0px; +} + +.example { + background-color: #323744; + color: white; + font-size: 16px; + padding: 16px 24px; + border-radius: 2px; +} + +div.header, div.footer { +} + +#container { +} + +#product { + background-color: white; + padding: 10px; + height: 130px; + border-bottom: solid #d3dbec 1px; +} + +#product big { + font-size: 42px; +} +#product strong { + font-weight: normal; +} + +#product_logo { + float: right; +} + +#product_name { + padding-top: 15px; + padding-left: 30px; + font-size: 42px; + font-weight: normal; +} + +#product_description { + padding-left: 30px; + color: #757779; +} + +#main { + background: #eff4ff; + margin: 0; +} + +#navigation { + width: 100%; + background-color: rgb(44,62,103); + padding: 10px; + margin: 0; +} + +#navigation h1 { + display: none; +} + +#navigation a:hover { + text-decoration: underline; +} + +#navigation ul li a { + color: rgb(136, 208, 255); + font-weight: bold; + text-decoration: none; +} + +#navigation ul li li a { + color: rgb(136, 208, 255); + font-weight: normal; + text-decoration: none; +} + +#navigation ul { + display: inline; + color: white; + padding: 0px; + padding-top: 10px; + padding-bottom: 10px; +} + +#navigation li { + display: inline; + list-style-type: none; + padding-left: 5px; + padding-right: 5px; +} + +#navigation li { + padding: 10px; + padding: 10px; +} + +#navigation li li { +} + +#navigation li:hover a { + color: rgb(166, 238, 255); +} + +#content { + padding: 20px; + width: 800px; + margin-left: auto; + margin-right: auto; +} + +#about { + display: none; +} + +dl.reference { + background-color: white; + padding: 20px; + border: solid #d3dbec 1px; +} + +dl.reference dt { + padding: 5px; + padding-top: 25px; + color: #637bbc; +} + +dl.reference dl dt { + padding-top: 5px; + color: #637383; +} + +dl.reference dd { +} + +@media print { + body { + font: 10pt "Times New Roman", "TimeNR", Times, serif; + } + a { + font-weight:bold; color: #004080; text-decoration: underline; + } + #main { + background-color: #ffffff; border-left: 0px; + } + #container { + margin-left: 2%; margin-right: 2%; background-color: #ffffff; + } + #content { + margin-left: 0px; padding: 1em; border-left: 0px; border-right: 0px; background-color: #ffffff; + } + #navigation { + display: none; + } + #product_logo { + display: none; + } + #about img { + display: none; + } + .example { + font-family: "Andale Mono", monospace; + font-size: 8pt; + page-break-inside: avoid; + } +} diff --git a/docs/examples.html b/docs/examples.html new file mode 100644 index 0000000..68756c8 --- /dev/null +++ b/docs/examples.html @@ -0,0 +1,101 @@ + + + + LuaFileSystem + + + + + + +
+ +
+ +
LuaFileSystem
+
File System Library for the Lua Programming Language
+
+ +
+ + + +
+ +

Examples

+ +

Directory iterator

+ +

The following example iterates over a directory and recursively lists the +attributes for each file inside it.

+ +
+local lfs = require"lfs"
+
+function attrdir (path)
+    for file in lfs.dir(path) do
+        if file ~= "." and file ~= ".." then
+            local f = path..'/'..file
+            print ("\t "..f)
+            local attr = lfs.attributes (f)
+            assert (type(attr) == "table")
+            if attr.mode == "directory" then
+                attrdir (f)
+            else
+                for name, value in pairs(attr) do
+                    print (name, value)
+                end
+            end
+        end
+    end
+end
+
+attrdir (".")
+
+ +
+ +
+ + + +
+ + + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..b4f056e --- /dev/null +++ b/docs/index.html @@ -0,0 +1,230 @@ + + + + LuaFileSystem + + + + + + +
+ +
+ +
LuaFileSystem
+
File System Library for the Lua Programming Language
+
+ +
+ + + +
+ +

Overview

+ +

LuaFileSystem is a Lua library +developed to complement the set of functions related to file +systems offered by the standard Lua distribution.

+ +

LuaFileSystem offers a portable way to access +the underlying directory structure and file attributes.

+ +

LuaFileSystem is free software and uses the same +license as Lua 5.x (MIT).

+ +

Status

+ +

Current version is 1.8.0. It works with Lua 5.1, 5.2, 5.3 and 5.4, and it runs on various +flavors of Unix (including Linux, BSDs, macOS) and Windows.

+ +

Download

+ +

LuaFileSystem can be installed using LuaRocks: + +

+$ luarocks install luafilesystem
+
+ +

Its source can be found at its GitHub page.

+ +

History

+ +
+
Version 1.8.0 [22/Apr/2020]
+
    +
  • Lua 5.4 support
    • +
  • lfs.link and lfs.symlinkattributes now work on Windows
    • +
  • MACOSX_DEPLOYMENT_TARGET is configurable in the Makefile
    • +
  • Fallback to _POSIX_PATH_MAX when MAXPATHLEN is not avaliable
    • +
  • Fixed memory leak in case of realloc failure
    • +
+ +
Version 1.7.0 [15/Sep/2017]
+
    +
  • symlinkattributes function now provides 'target' field, containing name of the file that the symlink points to.
    • +
  • attributes, symlinkattributes, touch, mkdir, and rmdir functions now return system-dependent error code as the third value on error.
    • +
  • Fixed detection of closed files for Lua 5.2+ in setmode, lock, and unlock functions.
    • +
  • Fixed various compiler warnings.
    • +
+ +
Version 1.6.3 [15/Jan/2015]
+
    +
  • Lua 5.3 support.
    • +
  • Assorted bugfixes.
    • +
+ +
Version 1.6.2 [??/Oct/2012]
+
    +
  • Full Lua 5.2 compatibility (with Lua 5.1 fallbacks)
    • +
+ +
Version 1.6.1 [01/Oct/2012]
+
    +
  • fix build for Lua 5.2
    • +
+ +
Version 1.6.0 [26/Sep/2012]
+
    +
  • getcwd fix for Android
    • +
  • support for Lua 5.2
    • +
  • add lfs.link
    • +
  • other bug fixes
    • +
+ +
Version 1.5.0 [20/Oct/2009]
+
    +
  • Added explicit next and close methods to second return value of lfs.dir +(the directory object), for explicit iteration or explicit closing.
    • +
  • Added directory locking via lfs.lock_dir function (see the manual).
    • +
+
Version 1.4.2 [03/Feb/2009]
+
+
    +
  • fixed bug + lfs.attributes(filename, 'size') overflow on files > 2 Gb again (bug report and patch by KUBO Takehiro).
    • +
  • fixed bug + Compile error on Solaris 10 (bug report and patch by Aaron B).
    • +
  • fixed compilation problems with Borland C.
    • +
+
+ +
Version 1.4.1 [07/May/2008]
+
+
    +
  • documentation review
    • +
  • fixed Windows compilation issues
    • +
  • fixed bug in the Windows tests (patch by Shmuel Zeigerman)
    • +
  • fixed bug + lfs.attributes(filename, 'size') overflow on files > 2 Gb +
    • +
+
+ +
Version 1.4.0 [13/Feb/2008]
+
+
    +
  • added function + lfs.setmode + (works only in Windows systems).
    • +
  • lfs.attributes + raises an error if attribute does not exist
    • +
+
+ +
Version 1.3.0 [26/Oct/2007]
+
+ +
+ +
Version 1.2.1 [08/May/2007]
+
+
    +
  • compatible only with Lua 5.1 (Lua 5.0 support was dropped)
    • +
+
+ +
Version 1.2 [15/Mar/2006]
+
+ +
+ +
Version 1.1 [30/May/2005]
+
+ +
+ +
Version 1.0 [21/Jan/2005]
+
+ +
Version 1.0 Beta [10/Nov/2004]
+
+
+ +

Credits

+ +

The LuaFileSystem library was originally designed and +implemented by Roberto Ierusalimschy, André Carregal and +Tomás Guisasola. It was then maintained by Fábio +Mascarenhas for several years and has since been maintained +by many contributors -- see the Git history for detailed credits.

+ +
+ +
+ + + +
+ + + diff --git a/docs/license.html b/docs/license.html new file mode 100644 index 0000000..bb66e48 --- /dev/null +++ b/docs/license.html @@ -0,0 +1,108 @@ + + + + LuaFileSystem + + + + + + +
+ +
+ +
LuaFileSystem
+
File System Library for the Lua Programming Language
+
+ +
+ + + +
+ +

License

+ +

The spirit of the license is that you are free to use +LuaFileSystem for any purpose at no cost without having to ask us. +The only requirement is that if you do use LuaFileSystem, then you +should give us credit by including the appropriate copyright notice +somewhere in your product or its documentation.

+ +

The LuaFileSystem library was originally designed and +implemented by Roberto Ierusalimschy, André Carregal and +Tomás Guisasola, and has since been maintained over the years +by many people -- see the Git history for detailed credits. +The implementation is not derived from any other licensed software.

+ +
+

Copyright © 2003 - 2014 Kepler Project.

+

Copyright © 2014 - 2022 The LuaFileSystem authors.

+ +

Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, copy, +modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions:

+ +

The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software.

+ +

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS +BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN +ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.

+ +
+ +
+ + + +
+ + + diff --git a/docs/luafilesystem.png b/docs/luafilesystem.png new file mode 100644 index 0000000..e1dd8c6 Binary files /dev/null and b/docs/luafilesystem.png differ diff --git a/docs/manual.html b/docs/manual.html new file mode 100644 index 0000000..1feb86a --- /dev/null +++ b/docs/manual.html @@ -0,0 +1,286 @@ + + + + LuaFileSystem + + + + + + +
+ +
+ +
LuaFileSystem
+
File System Library for the Lua Programming Language
+
+ +
+ + + +
+ +

Introduction

+ +

LuaFileSystem is a Lua library +developed to complement the set of functions related to file +systems offered by the standard Lua distribution.

+ +

LuaFileSystem offers a portable way to access +the underlying directory structure and file attributes.

+ +

Building

+ +

+LuaFileSystem should be built with Lua 5.1 so the language library +and header files for the target version must be installed properly. +

+ +

+LuaFileSystem offers a Makefile and a separate configuration file, +config, +which should be edited to suit your installation before running +make. +The file has some definitions like paths to the external libraries, +compiler options and the like. +

+ +

On Windows, the C runtime used to compile LuaFileSystem must be the same +runtime that Lua uses, or some LuaFileSystem functions will not work.

+ +

Installation

+ +

The easiest way to install LuaFileSystem is to use LuaRocks:

+ +
+luarocks install luafilesystem
+
+ +

If you prefer to install LuaFileSystem manually, the compiled binary should be copied to a directory in your +C path.

+ +

Reference

+ +

+LuaFileSystem offers the following functions: +

+ +
+
lfs.attributes (filepath [, request_name | result_table])
+
Returns a table with the file attributes corresponding to + filepath (or nil followed by an error message and a system-dependent error code + in case of error). + If the second optional argument is given and is a string, then only the value of the + named attribute is returned (this use is equivalent to + lfs.attributes(filepath)[request_name], but the table is not created + and only one attribute is retrieved from the O.S.). + if a table is passed as the second argument, it (result_table) is filled with attributes and returned instead of a new table. + The attributes are described as follows; + attribute mode is a string, all the others are numbers, + and the time related attributes use the same time reference of + os.time: +
+
dev
+
on Unix systems, this represents the device that the inode resides on. On Windows systems, + represents the drive number of the disk containing the file
+ +
ino
+
on Unix systems, this represents the inode number. On Windows systems this has no meaning
+ +
mode
+
string representing the associated protection mode (the values could be + file, directory, link, socket, + named pipe, char device, block device or + other)
+ +
nlink
+
number of hard links to the file
+ +
uid
+
user-id of owner (Unix only, always 0 on Windows)
+ +
gid
+
group-id of owner (Unix only, always 0 on Windows)
+ +
rdev
+
on Unix systems, represents the device type, for special file inodes. + On Windows systems represents the same as dev
+ +
access
+
time of last access
+ +
modification
+
time of last data modification
+ +
change
+
time of last file status change
+ +
size
+
file size, in bytes
+ +
permissions
+
file permissions string
+ +
blocks
+
block allocated for file; (Unix only)
+ +
blksize
+
optimal file system I/O blocksize; (Unix only)
+
+ This function uses stat internally thus if the given + filepath is a symbolic link, it is followed (if it points to + another link the chain is followed recursively) and the information + is about the file it refers to. + To obtain information about the link itself, see function + lfs.symlinkattributes. +
+ +
lfs.chdir (path)
+
Changes the current working directory to the given + path.
+ Returns true in case of success or nil plus an + error string.
+ +
lfs.lock_dir(path, [seconds_stale])
+
Creates a lockfile (called lockfile.lfs) in path if it does not + exist and returns the lock. If the lock already exists checks if + it's stale, using the second parameter (default for the second + parameter is INT_MAX, which in practice means the lock will never + be stale. To free the the lock call lock:free().
+ In case of any errors it returns nil and the error message. In + particular, if the lock exists and is not stale it returns the + "File exists" message.
+ +
lfs.currentdir ()
+
Returns a string with the current working directory or nil + plus an error string.
+ +
iter, dir_obj = lfs.dir (path)
+
+ Lua iterator over the entries of a given directory. + Each time the iterator is called with dir_obj it returns a directory entry's name as a string, or + nil if there are no more entries. You can also iterate by calling dir_obj:next(), and + explicitly close the directory before the iteration finished with dir_obj:close(). + Raises an error if path is not a directory. +
+ +
lfs.lock (filehandle, mode[, start[, length]])
+
Locks a file or a part of it. This function works on open files; the + file handle should be specified as the first argument. + The string mode could be either + r (for a read/shared lock) or w (for a + write/exclusive lock). The optional arguments start + and length can be used to specify a starting point and + its length; both should be numbers.
+ Returns true if the operation was successful; in + case of error, it returns nil plus an error string. +
+ +
lfs.link (old, new[, symlink])
+
Creates a link. The first argument is the object to link to + and the second is the name of the link. If the optional third + argument is true, the link will by a symbolic link (by default, a + hard link is created). +
+ +
lfs.mkdir (dirname)
+
Creates a new directory. The argument is the name of the new + directory.
+ Returns true in case of success or nil, an error message and + a system-dependent error code in case of error. +
+ +
lfs.rmdir (dirname)
+
Removes an existing directory. The argument is the name of the directory.
+ Returns true in case of success or nil, an error message and + a system-dependent error code in case of error. + +
lfs.setmode (file, mode)
+
Sets the writing mode for a file. The mode string can be either "binary" or "text". + Returns true followed the previous mode string for the file, or + nil followed by an error string in case of errors. + On non-Windows platforms, where the two modes are identical, + setting the mode has no effect, and the mode is always returned as binary. +
+ +
lfs.symlinkattributes (filepath [, request_name])
+
Identical to lfs.attributes except that + it obtains information about the link itself (not the file it refers to). + It also adds a target field, containing + the file name that the symlink points to. + On Windows this function does not yet support links, and is identical to + lfs.attributes. +
+ +
lfs.touch (filepath [, atime [, mtime]])
+
Set access and modification times of a file. This function is + a bind to utime function. The first argument is the + filename, the second argument (atime) is the access time, + and the third argument (mtime) is the modification time. + Both times are provided in seconds (which should be generated with + Lua standard function os.time). + If the modification time is omitted, the access time provided is used; + if both times are omitted, the current time is used.
+ Returns true in case of success or nil, an error message and + a system-dependent error code in case of error. +
+ +
lfs.unlock (filehandle[, start[, length]])
+
Unlocks a file or a part of it. This function works on + open files; the file handle should be specified as the first + argument. The optional arguments start and + length can be used to specify a starting point and its + length; both should be numbers.
+ Returns true if the operation was successful; + in case of error, it returns nil plus an error string. +
+
+ +
+ +
+ + + +
+ + + -- cgit v1.2.3-55-g6feb