Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

path.lua documentation #487

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+64 −57
Open

path.lua documentation #487

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 64 additions & 57 deletions lua/pl/path.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ end
-- @function dir
path.dir = lfs.dir

--- Creates a directory.
--- Create a directory.
-- Implicit link to [`luafilesystem.mkdir`](https://lunarmodules.github.io/luafilesystem/manual.html#mkdir)
-- @function mkdir
path.mkdir = function(d)
Expand All @@ -60,7 +60,7 @@ path.mkdir = function(d)
return ok, err, code
end

--- Removes a directory.
--- Remove a directory.
-- Implicit link to [`luafilesystem.rmdir`](https://lunarmodules.github.io/luafilesystem/manual.html#rmdir)
-- @function rmdir
path.rmdir = function(d)
Expand All @@ -71,7 +71,7 @@ path.rmdir = function(d)
return ok, err, code
end

--- Gets attributes.
--- Get file system attributes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
--- Get file system attributes.
--- Get file attributes.

This isn't querying the underlying file system attributes, just the file attributes.

-- Implicit link to [`luafilesystem.attributes`](https://lunarmodules.github.io/luafilesystem/manual.html#attributes)
-- @function attrib
path.attrib = function(d, r)
Expand All @@ -93,7 +93,7 @@ path.currentdir = function()
return ok, err, code
end

--- Gets symlink attributes.
--- Get symlink attributes.
-- Implicit link to [`luafilesystem.symlinkattributes`](https://lunarmodules.github.io/luafilesystem/manual.html#symlinkattributes)
-- @function link_attrib
path.link_attrib = function(d, r)
Expand All @@ -104,7 +104,7 @@ path.link_attrib = function(d, r)
return ok, err, code
end

--- Changes the working directory.
--- Change the working directory.
-- On Windows, if a drive is specified, it also changes the current drive. If
-- only specifying the drive, it will only switch drive, but not modify the path.
-- Implicit link to [`luafilesystem.chdir`](https://lunarmodules.github.io/luafilesystem/manual.html#chdir)
Expand All @@ -117,21 +117,21 @@ path.chdir = function(d)
return ok, err, code
end

--- is this a directory?
--- Is this a directory?
-- @string P A file path
function path.isdir(P)
assert_string(1,P)
return attrib(P,'mode') == 'directory'
end

--- is this a file?
--- Is this a file?
-- @string P A file path
function path.isfile(P)
assert_string(1,P)
return attrib(P,'mode') == 'file'
end

-- is this a symbolic link?
--- Is this a symbolic link?
-- @string P A file path
function path.islink(P)
assert_string(1,P)
Expand All @@ -142,36 +142,36 @@ function path.islink(P)
end
end

--- return size of a file.
--- Get the size of a file.
-- @string P A file path
function path.getsize(P)
assert_string(1,P)
return attrib(P,'size')
end

--- does a path exist?
--- Does a path exist?
-- @string P A file path
-- @return the file path if it exists (either as file, directory, socket, etc), false otherwise
function path.exists(P)
assert_string(1,P)
return attrib(P,'mode') ~= nil and P
end

--- Return the time of last access as the number of seconds since the epoch.
--- Get the time of last access as the number of seconds since the epoch.
-- @string P A file path
function path.getatime(P)
assert_string(1,P)
return attrib(P,'access')
end

--- Return the time of last modification as the number of seconds since the epoch.
--- Get the time of last modification as the number of seconds since the epoch.
-- @string P A file path
function path.getmtime(P)
assert_string(1,P)
return attrib(P,'modification')
end

---Return the system's ctime as the number of seconds since the epoch.
---Get the system's ctime as the number of seconds since the epoch.
-- @string P A file path
function path.getctime(P)
assert_string(1,P)
Expand Down Expand Up @@ -199,35 +199,39 @@ else
end
sep = path.sep

--- are we running Windows?
--- Are we running Windows?
-- @class field
-- @name path.is_windows

--- path separator for this platform.
--- Path separator for this platform.
-- @class field
-- @name path.sep

--- separator for PATH for this platform
--- Separator for PATH for this platform
-- @class field
-- @name path.dirsep

--- given a path, return the directory part and a file part.
-- if there's no directory part, the first value will be empty
-- @string P A file path
--- Get the directory and base parts of a path.
-- If some part is missing, the corresponding value will be empty.
-- @string P A path
-- @return directory part
-- @return file part
-- @return base part
-- @usage
-- local dir, file = path.splitpath("some/dir/myfile.txt")
-- local dir, base = path.splitpath("some/dir/myfile.txt")
-- assert(dir == "some/dir")
-- assert(file == "myfile.txt")
-- assert(base == "myfile.txt")
--
-- local dir, file = path.splitpath("some/dir/")
-- local dir, base = path.splitpath("some/dir/")
-- assert(dir == "some/dir")
-- assert(file == "")
-- assert(base == "")
--
-- local dir, base = path.splitpath("some_dir")
-- assert(dir == "")
-- assert(base == "some_dir")
--
-- local dir, file = path.splitpath("some_dir")
-- local dir, base = path.splitpath("/some_dir")
-- assert(dir == "")
-- assert(file == "some_dir")
-- assert(base == "some_dir")
function path.splitpath(P)
assert_string(1,P)
local i = #P
Expand All @@ -243,8 +247,8 @@ function path.splitpath(P)
end
end

--- return an absolute path.
-- @string P A file path
--- Get an absolute path from a path.
-- @string P A path
-- @string[opt] pwd optional start path to use (default is current dir)
function path.abspath(P,pwd)
assert_string(1,P)
Expand All @@ -261,9 +265,9 @@ function path.abspath(P,pwd)
return path.normpath(P)
end

--- given a path, return the root part and the extension part.
-- if there's no extension part, the second value will be empty
-- @string P A file path
--- Get the root and extension parts of a path.
-- If some part is missing, the corresponding value will be empty.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both ways make sense, but this edit looses the tip off that if only one part is found it is assumed to be the base, not an extension. This is perhaps intuitive, but less explicit docs doesn't seem good to me. Maybe we can come up with wording that makes this more explicit.

-- @string P A path
-- @treturn string root part (everything upto the "."", maybe empty)
-- @treturn string extension part (including the ".", maybe empty)
-- @usage
Expand Down Expand Up @@ -292,21 +296,22 @@ function path.splitext(P)
end
end

--- return the directory part of a path
-- @string P A file path
--- Get the directory part of a path.
-- @string P A path
-- @treturn string everything before the last dir-separator
-- @see splitpath
-- @usage
-- path.dirname("/some/path/file.txt") -- "/some/path"
-- path.dirname("file.txt") -- "" (empty string)
-- path.dirname("/file.txt") -- "" (empty string)
function path.dirname(P)
assert_string(1,P)
local p1 = path.splitpath(P)
return p1
end

--- return the file part of a path
-- @string P A file path
--- Get the base part of a path.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might actually be more confusing to some people. I suggest a wording that includes both labeling for clarify, perhaps:

Suggested change
--- Get the base part of a path.
--- Get the base part (filename segment) of a path.

-- @string P A path
-- @treturn string
-- @see splitpath
-- @usage
Expand All @@ -318,8 +323,8 @@ function path.basename(P)
return p2
end

--- get the extension part of a path.
-- @string P A file path
--- Get the extension part of a path.
-- @string P A path
-- @treturn string
-- @see splitext
-- @usage
Expand All @@ -331,8 +336,8 @@ function path.extension(P)
return p2
end

--- is this an absolute path?
-- @string P A file path
--- Is this an absolute path?
-- @string P A path
-- @usage
-- path.isabs("hello/path") -- false
-- path.isabs("/hello/path") -- true
Expand All @@ -349,9 +354,9 @@ function path.isabs(P)
return seps[at(P,1)] ~= nil
end

--- return the path resulting from combining the individual paths.
-- if the second (or later) path is absolute, we return the last absolute path (joined with any non-absolute paths following).
-- empty elements (except the last) will be ignored.
--- Get the path resulting from combining individual paths.
-- If the second or any later path is absolute, this returns the last absolute path joined with all (non-absolute) following paths.
-- Empty elements but the last will be ignored.
-- @string p1 A file path
-- @string p2 A file path
-- @string ... more file paths
Expand Down Expand Up @@ -380,12 +385,12 @@ function path.join(p1,p2,...)
return p1..p2
end

--- normalize the case of a pathname. On Unix, this returns the path unchanged,
--- Get a path by normalizing the case of a path. On Unix, this returns the path unchanged,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
--- Get a path by normalizing the case of a path. On Unix, this returns the path unchanged,
--- Normalize the case of a path. On Unix, this returns the path unchanged,

-- for Windows it converts;
--
-- * the path to lowercase
-- * forward slashes to backward slashes
-- @string P A file path
-- @string P A path
-- @usage path.normcase("/Some/Path/File.txt")
-- -- Windows: "\some\path\file.txt"
-- -- Others : "/Some/Path/File.txt"
Expand All @@ -398,7 +403,7 @@ function path.normcase(P)
end
end

--- normalize a path name.
--- Get a path by normalizing a path.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just fix the case on the original, this is less clear than the original. It's just stuffing words into a word salad, not clarifying what is happening.

-- `A//B`, `A/./B`, and `A/foo/../B` all become `A/B`.
--
-- An empty path results in '.'.
Expand Down Expand Up @@ -451,9 +456,9 @@ function path.normpath(P)
return P
end

--- relative path from current directory or optional start point
--- Get the relative path of a path from the current directory or an optional start point.
-- @string P a path
-- @string[opt] start optional start point (default current directory)
-- @string[opt] start optional start point (defaults to the current directory)
function path.relpath (P,start)
assert_string(1,P)
if start then assert_string(2,start) end
Expand Down Expand Up @@ -489,11 +494,11 @@ function path.relpath (P,start)
end


--- Replace a starting '~' with the user's home directory.
-- In windows, if HOME isn't set, then USERPROFILE is used in preference to
-- HOMEDRIVE HOMEPATH. This is guaranteed to be writeable on all versions of Windows.
-- @string P A file path
-- @treturn[1] string The file path with the `~` prefix substituted, or the input path if it had no prefix.
--- Get a path by replacing in a path a starting '~' with the user's home directory.
-- In windows, if `HOME` environment variable isn't set, then `USERPROFILE` is used in preference to
-- `HOMEDRIVE HOMEPATH`. This is guaranteed to be writeable on all versions of Windows.
-- @string P A path
-- @treturn[1] string The path with the `~` prefix substituted, or the input path if it had no prefix.
-- @treturn[2] nil
-- @treturn[2] string Error message if the environment variables were unavailable.
function path.expanduser(P)
Expand Down Expand Up @@ -525,7 +530,7 @@ function path.expanduser(P)
end


---Return a suitable full path to a new temporary file name.
---Get a new temporary full path.
-- unlike os.tmpname(), it always gives you a writeable path (uses TEMP environment variable on Windows)
function path.tmpname ()
local res = tmpnam()
Expand All @@ -538,10 +543,13 @@ function path.tmpname ()
return res
end

--- return the largest common prefix path of two paths.
--- Get the largest common prefix path of two paths.
-- @string path1 a file path
-- @string path2 a file path
-- @return the common prefix (Windows: separators will be normalized, casing will be original)
-- @return the common prefix path (Windows: separators will be normalized, casing will be original)
-- @usage
-- local common = path.common_prefix("a/b/...","a/bb/...")
-- assert(common == "a")
function path.common_prefix (path1,path2)
assert_string(1,path1)
assert_string(2,path2)
Expand Down Expand Up @@ -569,7 +577,7 @@ function path.common_prefix (path1,path2)
--return ''
end

--- return the full path where a particular Lua module would be found.
--- Get the full path where a particular Lua module would be found.
-- Both package.path and package.cpath is searched, so the result may
-- either be a Lua file or a shared library.
-- @string mod name of the module
Expand All @@ -586,5 +594,4 @@ function path.package_path(mod)
end


---- finis -----
return path
Loading