Standard Library

Constants

format: table

Contains all of the formats for the into and from functions

format = {
    json = "json",
    toml = "toml",
    yaml = "yaml",
    ini = "ini",
}

format.hash: table

Contains the formats for the hash function.

format.hash = {
    sha256 = "sha256",
    sha512 = "sha512",
    sha224 = "sha224",
    sha512_224 = "sha512-224",
    sha512_256 = "sha512-256",
    sha384 = "sha384",
    sha3_224 = "sha3-224",
    sha3_256 = "sha3-256",
    sha3_384 = "sha3-384",
    sha3_512 = "sha3-512",
    md5 = "md5"
}

format.checksum: table

Contains the formats for the checksum function

format.checksum = {
    crc32 = "crc32",
    xxh3 = "xxh3",
    adler32 = "adler32"
}

format.archive: table

Contains the formats for the extract function.

format.archive = {
    tar = "tar",
    zip = "zip",
    gz = "gz",
    tar_gz = "tar_gz"
}

lang: table

A table of builtin language identifiers.

lang = {
    C = "c",
    Cpp = "cpp",
    Rust = "rust",
    Python = "py3",
    Python2 = "py2",
}

tasks: table

Contains all of the functions that can be ran from the command line.

function tasks.build(args)
    print("hello from build")
end

$ pksc build
hello from build

Any arguments passed after the task are passed into the function as a table

lock: table

The lock table is a way to persists data, it is loaded from disk at startup and saved at program exit (uses `build.lock`).

IWD: string

Represents the initial working directory, or the directory that PackScript was initially ran in.

Network Operations

fetch(url: string, [, options: table]) -> string

Executes a basic https operation, you can customize the headers and add queries using the optionstable.

local options = {
    header = {
        -- Any headers here
    },
    query = {
        -- Queries here
        query = true
        -- This would be equivalent to https:://example.com/?query=true
    }
}
fetch("https://example.com", options)

File Operations

path(path: string) -> path

Creates a path table from the given string. The path must exist and be a valid path

The returned table has the following format

Name	Description
path	The given relative path (equivalent to path)
extension	The extension of the file (if it has one)
name	The name of the file (including extension)
stem	The name of the file (without extension)
parent	The parent path of the file/directory
is_dir	Whether or not the current path represents a directory
abspath	The absolute canonicalized version of this path
absparent	The absolute canonicalized version of the parent path

stat(path: path) -> table

Returns various statistics about the given path. Returns a table with the format:

name	description
file_type	Is one of "file", "dir", "symlink" or "unknown"
len	The length in bytes of this file
readonly	Whether or not the file is readonly
modified	The last-modified time in seconds from the unix epoch
accessed	The last-accessed time in seconds from the unix epoch
created	The time created in seconds from the unix epoch

exists(path: string) -> boolean

Returns if the given path (a string) exists.

write(path: string, data: string)

A convenience function for writing to a file.

append(path: string, data: string)

A convenience function for appending to a file.

cat(path: string) -> string

Returns a string containing all of the file contents.

glob(pattern: string) -> [path]

Returns an array of every matched path. Uses the GNU Glob syntax.

Pattern	Function
?	Matches a single character
*	Matches everything except path separators
**	Matches everything including path separators, must form a single path component, so "/**/*" is valid but "/b**" is not
[...]	Matches any character inside the brackets, including ranges
[!...]	A negated character class

local c_srcs = glob "src/**/*.c"
local c_headers = glob "include/**/*.h"

Encoding/Decoding

into(table: table, format: string) -> string

Serializes a table into the given format, valid formats are included in the format table.

local project = {
    name = "Into Example",
    id = "example",
    is_example = true
}
local serialized = into(project, format.json)
print(serialized)
-- Prints {"name": "Into Example", "id": "example", "is_example": true}

The __serializemetamethod can be used on a table to define how it should be serialized. An example is `Version`.

local project = {
    name = "Example",
    id = "example",
    version = Version(1, 4, 10)
}
print(project.version.minor) -- Prints: 4
print(project.version) -- Prints: "1.4.10", since the __tostring metamethod is set
local serialized = into(project, format.toml)
print(serialized)
-- Prints:
-- 
-- [project]
-- name = "Example"
-- id = "example"
-- version = "1.4.10"
-- 
-- since into will recursively call __serialize on every child

from(string: string, format: string) -> table

The opposite of into, takes a string and a format, returns the de-serialized table.

extract(path_in: path, path_out: path, format: string) -> path

Extracts the given archive into the output path using the specified format (from format.archive).

If the top-most entry in the archive is a directory then it returns the path to that directory, otherwise it returns path_out.

Cryptographic Functions

hash(file: path, format: string) -> string

Hashes the given file using the given format (one of format.hash).

hashs(data: string, format: string) -> string

Same as hash but takes in string data instead of a file.

checksum(file: path, format: string) -> number

Calculates a checksum using the given format (one of format.checksum)

checksums(data: string, format: string) -> number

Same as checksum but takes in string data instead of a file.

Iterator Functions

map(table: table, fn -> function) -> table

Maps every pair in `table` using `fn`.

local nums = {1, 2, 3, 4}
nums = map(nums, function(index, value) return value + 1 end)
print(nums) -- prints: 2, 3, 4, 5
-- map only maps the values not the indexes 

filter(table: table, fn: function) -> table

Filters a table based on `fn`, if fnreturns truethen it keeps the value, otherwise it removes it

filter_map(table: table, fn: function) -> table

Combines both filter and map. Maps the values as long as fnis not `nil`

foreach(table: table, fn: function)

Runs fnfor every pair in `table`

iforeach(table: table, fn: function)

Runs fnfor every pair in tableusing `ipairs`

reduce(table: table, fn: function) -> value

Reduces the table using `fn`

local nums = {1, 2, 3, 4}
nums = reduce(nums, function(accum, value) return accum + value end)
print(nums) -- prints: 10

idiscard(fn: function) -> function

Returns a function that takes in two parameters but only passes the second. It is mostly intended to be used as a convenience function with iteration functions.

Misc

curry(fn: function) -> function

Transforms the provided function into a "curriable" function. A curried function can accept fewer arguments than what are required, it will only run when it receives all of its arguments.

function add(a,b)
    return a + b
end

local cadd = curry(add)
local add5 = cadd(5) -- cadd(5) returns a function that takes in `b` 
local result = add5(7) -- recivied all of the needed arguments so is called
print(result) -- prints: 12 

Regex

This API is not yet finished

re.matches(text: string, pattern: string) -> table

returns an array of matches from the text using the pattern. Technically it returns an array of arrays where the sub-arrays are the captures.

local example = "The quick brown fox jumps over the lazy dog"
local ms = re.matches(example, [[\S+]]) -- matches all words

re.replace(text: string, pattern: string, replace: string) -> string

Replaces all patternwith replacefor every line in text.

Supports backreferences in `replace`

re.freplace(path: string, pattern: string, replace: string)

Same as re.replace but uses the file at pathas text (modifies the file!).