Compare commits

..

No commits in common. "f40ce3c8f71f54cbd722d562c83ed2f1c1d66f4a" and "bb8d072b8c1dd44ba5e0c4891df0120c88c2b249" have entirely different histories.

17 changed files with 333 additions and 456 deletions

View File

@ -555,7 +555,7 @@ func main() {
`, htmlSig, dps.FuncName)) `, htmlSig, dps.FuncName))
for _, doc := range dps.Doc { for _, doc := range dps.Doc {
if !strings.HasPrefix(doc, "---") { if !strings.HasPrefix(doc, "---") {
f.WriteString(doc + " \n") f.WriteString(doc + "\n")
} }
} }
f.WriteString("#### Parameters\n") f.WriteString("#### Parameters\n")

View File

@ -8,28 +8,22 @@ menu:
--- ---
## Introduction ## Introduction
The fs module provides easy and simple access to filesystem functions
The fs module provides filesystem functions to Hilbish. While Lua's standard and other things, and acts an addition to the Lua standard library's
library has some I/O functions, they're missing a lot of the basics. The `fs` I/O and filesystem functions.
library offers more functions and will work on any operating system Hilbish does.
## Functions ## Functions
||| |||
|----|----| |----|----|
|<a href="#abs">abs(path) -> string</a>|Returns an absolute version of the `path`.| |<a href="#abs">abs(path) -> string</a>|Gives an absolute version of `path`.|
|<a href="#basename">basename(path) -> string</a>|Returns the "basename," or the last part of the provided `path`. If path is empty,| |<a href="#basename">basename(path) -> string</a>|Gives the basename of `path`. For the rules,|
|<a href="#cd">cd(dir)</a>|Changes Hilbish's directory to `dir`.| |<a href="#cd">cd(dir)</a>|Changes directory to `dir`|
|<a href="#dir">dir(path) -> string</a>|Returns the directory part of `path`. If a file path like| |<a href="#dir">dir(path) -> string</a>|Returns the directory part of `path`. For the rules, see Go's|
|<a href="#glob">glob(pattern) -> matches (table)</a>|Match all files based on the provided `pattern`.| |<a href="#glob">glob(pattern) -> matches (table)</a>|Glob all files and directories that match the pattern.|
|<a href="#join">join(...path) -> string</a>|Takes any list of paths and joins them based on the operating system's path separator.| |<a href="#join">join(...) -> string</a>|Takes paths and joins them together with the OS's|
|<a href="#mkdir">mkdir(name, recursive)</a>|Creates a new directory with the provided `name`.| |<a href="#mkdir">mkdir(name, recursive)</a>|Makes a directory called `name`. If `recursive` is true, it will create its parent directories.|
|<a href="#readdir">readdir(path) -> table[string]</a>|Returns a list of all files and directories in the provided path.| |<a href="#readdir">readdir(dir) -> {}</a>|Returns a table of files in `dir`.|
|<a href="#stat">stat(path) -> {}</a>|Returns the information about a given `path`.| |<a href="#stat">stat(path) -> {}</a>|Returns a table of info about the `path`.|
## Static module fields
|||
|----|----|
|pathSep|The operating system's path separator.|
<hr><div id='abs'> <hr><div id='abs'>
<h4 class='heading'> <h4 class='heading'>
@ -39,12 +33,9 @@ fs.abs(path) -> string
</a> </a>
</h4> </h4>
Returns an absolute version of the `path`. Gives an absolute version of `path`.
This can be used to resolve short paths like `..` to `/home/user`.
#### Parameters #### Parameters
`string` **`path`** This function has no parameters.
</div> </div>
<hr><div id='basename'> <hr><div id='basename'>
@ -55,12 +46,10 @@ fs.basename(path) -> string
</a> </a>
</h4> </h4>
Returns the "basename," or the last part of the provided `path`. If path is empty, Gives the basename of `path`. For the rules,
`.` will be returned. see Go's filepath.Base
#### Parameters #### Parameters
`string` **`path`** This function has no parameters.
Path to get the base name of.
</div> </div>
<hr><div id='cd'> <hr><div id='cd'>
@ -71,11 +60,9 @@ fs.cd(dir)
</a> </a>
</h4> </h4>
Changes Hilbish's directory to `dir`. Changes directory to `dir`
#### Parameters #### Parameters
`string` **`dir`** This function has no parameters.
Path to change directory to.
</div> </div>
<hr><div id='dir'> <hr><div id='dir'>
@ -86,12 +73,10 @@ fs.dir(path) -> string
</a> </a>
</h4> </h4>
Returns the directory part of `path`. If a file path like Returns the directory part of `path`. For the rules, see Go's
`~/Documents/doc.txt` then this function will return `~/Documents`. filepath.Dir
#### Parameters #### Parameters
`string` **`path`** This function has no parameters.
Path to get the directory for.
</div> </div>
<hr><div id='glob'> <hr><div id='glob'>
@ -102,50 +87,24 @@ fs.glob(pattern) -> matches (table)
</a> </a>
</h4> </h4>
Match all files based on the provided `pattern`. Glob all files and directories that match the pattern.
For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match For the rules, see Go's filepath.Glob
#### Parameters #### Parameters
`string` **`pattern`** This function has no parameters.
Pattern to compare files with.
#### Example
```lua
--[[
Within a folder that contains the following files:
a.txt
init.lua
code.lua
doc.pdf
]]--
local matches = fs.glob './*.lua'
print(matches)
-- -> {'init.lua', 'code.lua'}
````
</div> </div>
<hr><div id='join'> <hr><div id='join'>
<h4 class='heading'> <h4 class='heading'>
fs.join(...path) -> string fs.join(...) -> string
<a href="#join" class='heading-link'> <a href="#join" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
</h4> </h4>
Takes any list of paths and joins them based on the operating system's path separator. Takes paths and joins them together with the OS's
directory separator (forward or backward slash).
#### Parameters #### Parameters
`string` **`path`** (This type is variadic. You can pass an infinite amount of parameters with this type.) This function has no parameters.
Paths to join together
#### Example
```lua
-- This prints the directory for Hilbish's config!
print(fs.join(hilbish.userDir.config, 'hilbish'))
-- -> '/home/user/.config/hilbish' on Linux
````
</div> </div>
<hr><div id='mkdir'> <hr><div id='mkdir'>
@ -156,38 +115,22 @@ fs.mkdir(name, recursive)
</a> </a>
</h4> </h4>
Creates a new directory with the provided `name`. Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
With `recursive`, mkdir will create parent directories.
-- This will create the directory foo, then create the directory bar in the
-- foo directory. If recursive is false in this case, it will fail.
fs.mkdir('./foo/bar', true)
#### Parameters #### Parameters
`string` **`name`** This function has no parameters.
Name of the directory
`boolean` **`recursive`**
Whether to create parent directories for the provided name
#### Example
```lua
````
</div> </div>
<hr><div id='readdir'> <hr><div id='readdir'>
<h4 class='heading'> <h4 class='heading'>
fs.readdir(path) -> table[string] fs.readdir(dir) -> {}
<a href="#readdir" class='heading-link'> <a href="#readdir" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
</h4> </h4>
Returns a list of all files and directories in the provided path. Returns a table of files in `dir`.
#### Parameters #### Parameters
`string` **`dir`** This function has no parameters.
</div> </div>
<hr><div id='stat'> <hr><div id='stat'>
@ -198,33 +141,13 @@ fs.stat(path) -> {}
</a> </a>
</h4> </h4>
Returns the information about a given `path`. Returns a table of info about the `path`.
The returned table contains the following values: It contains the following keys:
name (string) - Name of the path name (string) - Name of the path
size (number) - Size of the path in bytes size (number) - Size of the path
mode (string) - Unix permission mode in an octal format string (with leading 0) mode (string) - Permission mode in an octal format string (with leading 0)
isDir (boolean) - If the path is a directory isDir (boolean) - If the path is a directory
#### Parameters #### Parameters
`string` **`path`** This function has no parameters.
#### Example
```lua
local inspect = require 'inspect'
local stat = fs.stat '~'
print(inspect(stat))
--[[
Would print the following:
{
isDir = true,
mode = "0755",
name = "username",
size = 12288
}
]]--
````
</div> </div>

View File

@ -2,51 +2,56 @@
local fs = {} local fs = {}
--- Returns an absolute version of the `path`. --- Gives an absolute version of `path`.
--- This can be used to resolve short paths like `..` to `/home/user`. --- @param path string
--- @returns string
function fs.abs(path) end function fs.abs(path) end
--- Returns the "basename," or the last part of the provided `path`. If path is empty, --- Gives the basename of `path`. For the rules,
--- `.` will be returned. --- see Go's filepath.Base
--- @returns string
function fs.basename(path) end function fs.basename(path) end
--- Changes Hilbish's directory to `dir`. --- Changes directory to `dir`
--- @param dir string
function fs.cd(dir) end function fs.cd(dir) end
--- Returns the directory part of `path`. If a file path like --- Returns the directory part of `path`. For the rules, see Go's
--- `~/Documents/doc.txt` then this function will return `~/Documents`. --- filepath.Dir
--- @param path string
--- @returns string
function fs.dir(path) end function fs.dir(path) end
--- Match all files based on the provided `pattern`. --- Glob all files and directories that match the pattern.
--- For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match --- For the rules, see Go's filepath.Glob
--- --- @param pattern string
--- --- @returns table
function fs.glob(pattern) end function fs.glob(pattern) end
--- Takes any list of paths and joins them based on the operating system's path separator. --- Takes paths and joins them together with the OS's
--- --- directory separator (forward or backward slash).
--- --- @vararg string
function fs.join(...path) end --- @returns string
function fs.join(...) end
--- Creates a new directory with the provided `name`. --- Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
--- With `recursive`, mkdir will create parent directories. --- @param name string
--- --- @param recursive boolean
--- -- This will create the directory foo, then create the directory bar in the
--- -- foo directory. If recursive is false in this case, it will fail.
--- fs.mkdir('./foo/bar', true)
function fs.mkdir(name, recursive) end function fs.mkdir(name, recursive) end
--- Returns a list of all files and directories in the provided path. --- Returns a table of files in `dir`.
function fs.readdir(path) end --- @param dir string
--- @return table
function fs.readdir(dir) end
--- Returns the information about a given `path`. --- Returns a table of info about the `path`.
--- The returned table contains the following values: --- It contains the following keys:
--- name (string) - Name of the path --- name (string) - Name of the path
--- size (number) - Size of the path in bytes --- size (number) - Size of the path
--- mode (string) - Unix permission mode in an octal format string (with leading 0) --- mode (string) - Permission mode in an octal format string (with leading 0)
--- isDir (boolean) - If the path is a directory --- isDir (boolean) - If the path is a directory
--- --- @param path string
--- --- @returns table
function fs.stat(path) end function fs.stat(path) end
return fs return fs

View File

@ -1,10 +1,7 @@
// filesystem interaction and functionality library // filesystem interaction and functionality library
/* // The fs module provides easy and simple access to filesystem functions
The fs module provides filesystem functions to Hilbish. While Lua's standard // and other things, and acts an addition to the Lua standard library's
library has some I/O functions, they're missing a lot of the basics. The `fs` // I/O and filesystem functions.
library offers more functions and will work on any operating system Hilbish does.
#field pathSep The operating system's path separator.
*/
package fs package fs
import ( import (
@ -45,46 +42,9 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
return rt.TableValue(mod), nil return rt.TableValue(mod), nil
} }
// abs(path) -> string
// Returns an absolute version of the `path`.
// This can be used to resolve short paths like `..` to `/home/user`.
// #param path string
// #returns string
func fabs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
path, err := c.StringArg(0)
if err != nil {
return nil, err
}
path = util.ExpandHome(path)
abspath, err := filepath.Abs(path)
if err != nil {
return nil, err
}
return c.PushingNext1(t.Runtime, rt.StringValue(abspath)), nil
}
// basename(path) -> string
// Returns the "basename," or the last part of the provided `path`. If path is empty,
// `.` will be returned.
// #param path string Path to get the base name of.
// #returns string
func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
path, err := c.StringArg(0)
if err != nil {
return nil, err
}
return c.PushingNext(t.Runtime, rt.StringValue(filepath.Base(path))), nil
}
// cd(dir) // cd(dir)
// Changes Hilbish's directory to `dir`. // Changes directory to `dir`
// #param dir string Path to change directory to. // --- @param dir string
func fcd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func fcd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -103,102 +63,10 @@ func fcd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), err return c.Next(), err
} }
// dir(path) -> string
// Returns the directory part of `path`. If a file path like
// `~/Documents/doc.txt` then this function will return `~/Documents`.
// #param path string Path to get the directory for.
// #returns string
func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
path, err := c.StringArg(0)
if err != nil {
return nil, err
}
return c.PushingNext(t.Runtime, rt.StringValue(filepath.Dir(path))), nil
}
// glob(pattern) -> matches (table)
// Match all files based on the provided `pattern`.
// For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match
// #param pattern string Pattern to compare files with.
// #returns table A list of file names/paths that match.
/*
#example
--[[
Within a folder that contains the following files:
a.txt
init.lua
code.lua
doc.pdf
]]--
local matches = fs.glob './*.lua'
print(matches)
-- -> {'init.lua', 'code.lua'}
#example
*/
func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
pattern, err := c.StringArg(0)
if err != nil {
return nil, err
}
matches, err := filepath.Glob(pattern)
if err != nil {
return nil, err
}
luaMatches := rt.NewTable()
for i, match := range matches {
luaMatches.Set(rt.IntValue(int64(i + 1)), rt.StringValue(match))
}
return c.PushingNext(t.Runtime, rt.TableValue(luaMatches)), nil
}
// join(...path) -> string
// Takes any list of paths and joins them based on the operating system's path separator.
// #param path ...string Paths to join together
// #returns string The joined path.
/*
#example
-- This prints the directory for Hilbish's config!
print(fs.join(hilbish.userDir.config, 'hilbish'))
-- -> '/home/user/.config/hilbish' on Linux
#example
*/
func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
strs := make([]string, len(c.Etc()))
for i, v := range c.Etc() {
if v.Type() != rt.StringType {
// +2; go indexes of 0 and first arg from above
return nil, fmt.Errorf("bad argument #%d to run (expected string, got %s)", i + 1, v.TypeName())
}
strs[i] = v.AsString()
}
res := filepath.Join(strs...)
return c.PushingNext(t.Runtime, rt.StringValue(res)), nil
}
// mkdir(name, recursive) // mkdir(name, recursive)
// Creates a new directory with the provided `name`. // Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
// With `recursive`, mkdir will create parent directories. // --- @param name string
// #param name string Name of the directory // --- @param recursive boolean
// #param recursive boolean Whether to create parent directories for the provided name
/*
#example
-- This will create the directory foo, then create the directory bar in the
-- foo directory. If recursive is false in this case, it will fail.
fs.mkdir('./foo/bar', true)
*/
func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -225,58 +93,15 @@ func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), err return c.Next(), err
} }
// readdir(path) -> table[string]
// Returns a list of all files and directories in the provided path.
// #param dir string
// #returns table
func freaddir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
dir, err := c.StringArg(0)
if err != nil {
return nil, err
}
dir = util.ExpandHome(dir)
names := rt.NewTable()
dirEntries, err := os.ReadDir(dir)
if err != nil {
return nil, err
}
for i, entry := range dirEntries {
names.Set(rt.IntValue(int64(i + 1)), rt.StringValue(entry.Name()))
}
return c.PushingNext1(t.Runtime, rt.TableValue(names)), nil
}
// stat(path) -> {} // stat(path) -> {}
// Returns the information about a given `path`. // Returns a table of info about the `path`.
// The returned table contains the following values: // It contains the following keys:
// name (string) - Name of the path // name (string) - Name of the path
// size (number) - Size of the path in bytes // size (number) - Size of the path
// mode (string) - Unix permission mode in an octal format string (with leading 0) // mode (string) - Permission mode in an octal format string (with leading 0)
// isDir (boolean) - If the path is a directory // isDir (boolean) - If the path is a directory
// #param path string // --- @param path string
// #returns table // --- @returns table
/*
#example
local inspect = require 'inspect'
local stat = fs.stat '~'
print(inspect(stat))
--[[
Would print the following:
{
isDir = true,
mode = "0755",
name = "username",
size = 12288
}
]]--
#example
*/
func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -300,3 +125,128 @@ func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext1(t.Runtime, rt.TableValue(statTbl)), nil return c.PushingNext1(t.Runtime, rt.TableValue(statTbl)), nil
} }
// readdir(dir) -> {}
// Returns a table of files in `dir`.
// --- @param dir string
// --- @return table
func freaddir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
dir, err := c.StringArg(0)
if err != nil {
return nil, err
}
dir = util.ExpandHome(dir)
names := rt.NewTable()
dirEntries, err := os.ReadDir(dir)
if err != nil {
return nil, err
}
for i, entry := range dirEntries {
names.Set(rt.IntValue(int64(i + 1)), rt.StringValue(entry.Name()))
}
return c.PushingNext1(t.Runtime, rt.TableValue(names)), nil
}
// abs(path) -> string
// Gives an absolute version of `path`.
// --- @param path string
// --- @returns string
func fabs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
path, err := c.StringArg(0)
if err != nil {
return nil, err
}
path = util.ExpandHome(path)
abspath, err := filepath.Abs(path)
if err != nil {
return nil, err
}
return c.PushingNext1(t.Runtime, rt.StringValue(abspath)), nil
}
// basename(path) -> string
// Gives the basename of `path`. For the rules,
// see Go's filepath.Base
// --- @returns string
func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
path, err := c.StringArg(0)
if err != nil {
return nil, err
}
return c.PushingNext(t.Runtime, rt.StringValue(filepath.Base(path))), nil
}
// dir(path) -> string
// Returns the directory part of `path`. For the rules, see Go's
// filepath.Dir
// --- @param path string
// --- @returns string
func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
path, err := c.StringArg(0)
if err != nil {
return nil, err
}
return c.PushingNext(t.Runtime, rt.StringValue(filepath.Dir(path))), nil
}
// glob(pattern) -> matches (table)
// Glob all files and directories that match the pattern.
// For the rules, see Go's filepath.Glob
// --- @param pattern string
// --- @returns table
func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
}
pattern, err := c.StringArg(0)
if err != nil {
return nil, err
}
matches, err := filepath.Glob(pattern)
if err != nil {
return nil, err
}
luaMatches := rt.NewTable()
for i, match := range matches {
luaMatches.Set(rt.IntValue(int64(i + 1)), rt.StringValue(match))
}
return c.PushingNext(t.Runtime, rt.TableValue(luaMatches)), nil
}
// join(...) -> string
// Takes paths and joins them together with the OS's
// directory separator (forward or backward slash).
// --- @vararg string
// --- @returns string
func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
strs := make([]string, len(c.Etc()))
for i, v := range c.Etc() {
if v.Type() != rt.StringType {
// +2; go indexes of 0 and first arg from above
return nil, fmt.Errorf("bad argument #%d to run (expected string, got %s)", i + 1, v.TypeName())
}
strs[i] = v.AsString()
}
res := filepath.Join(strs...)
return c.PushingNext(t.Runtime, rt.StringValue(res)), nil
}

View File

@ -1,5 +1,5 @@
languageCode = 'en-us'
baseURL = 'https://rosettea.github.io/Hilbish/' baseURL = 'https://rosettea.github.io/Hilbish/'
languageCode = 'en-us'
title = 'Hilbish' title = 'Hilbish'
theme = 'hsh' theme = 'hsh'
enableGitInfo = true enableGitInfo = true
@ -34,7 +34,6 @@ lineNos = true
lineNumbersInTable = false lineNumbersInTable = false
noClasses = false noClasses = false
codeFences = true codeFences = true
guessSyntax = true
[author] [author]
[author.sammyette] [author.sammyette]