From 5865b147a6149b3576be096e98fe02db4b01ef15 Mon Sep 17 00:00:00 2001 From: Anaminus Date: Fri, 14 Aug 2020 15:36:10 -0500 Subject: [PATCH] Sync documentation. --- README.md | 8 +- rbxmk/doc/DOCUMENTATION.md | 65 ++++++-- rbxmk/doc/USAGE.md | 320 ------------------------------------- 3 files changed, 53 insertions(+), 340 deletions(-) delete mode 100644 rbxmk/doc/USAGE.md diff --git a/README.md b/README.md index 973af161..52413c4b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ # rbxmk - `rbxmk` is a command-line tool for manipulating Roblox files. rbxmk is useful for development workflows that involve many separate files. If @@ -8,7 +7,6 @@ scripting and model files for assets, rbxmk makes it simple to combine these files into a final product, be it a game, plugin, model, and so on. ## Installation - **This project is unstable! Use at your own risk!** 1. [Install Go](https://golang.org/doc/install) @@ -23,7 +21,5 @@ If you installed Go correctly, this will install rbxmk to `$GOPATH/bin`, which will allow you run it directly from a shell. ## Usage - -See [USAGE.md](rbxmk/doc/USAGE.md) for an overview on how to use rbxmk. See -[DOCUMENTATION.md](rbxmk/doc/DOCUMENTATION.md) for full details on how rbxmk -works. +The [documentation page](rbxmk/doc/DOCUMENTATION.md) provides a complete +reference on how rbxmk is used. diff --git a/rbxmk/doc/DOCUMENTATION.md b/rbxmk/doc/DOCUMENTATION.md index 1391a9e7..734dbc4d 100644 --- a/rbxmk/doc/DOCUMENTATION.md +++ b/rbxmk/doc/DOCUMENTATION.md @@ -1,29 +1,30 @@ # Documentation -This document provides details on how rbxmk works. For a basic overview, see -[USAGE.md](USAGE.md). +This document contains a complete reference of the rbxmk API, and provides +details on how rbxmk works.
Table of Contents
-1. [Environment][environment] +1. [Command line][command-line] +2. [Environment][environment] 1. [Base library][base-lib] 2. [`rbxmk` library][rbxmk-lib] 3. [Roblox library][roblox-lib] 4. [`os` library][os-lib] 5. [`sym` library][sym-lib] 6. [`types` library][types-lib] -1. [Instances][instances] +3. [Instances][instances] 1. [Instance][Instance] 1. [DataModel][DataModel] -1. [Descriptors][descriptors] +4. [Descriptors][descriptors] 1. [Descriptor types][descriptor-types] 2. [Diffing and Patching][diffing-and-patching] -1. [Explicit primitives][explicit-primitives] -1. [Sources][sources] +5. [Explicit primitives][explicit-primitives] +6. [Sources][sources] 1. [`file` source][file-source] 2. [`http` source][http-source] -1. [Formats][formats] +7. [Formats][formats] 1. [String formats][string-formats] 3. [Lua formats][lua-formats] 4. [Roblox formats][roblox-formats] @@ -44,23 +45,59 @@ type Array = {[number]: T} [luau]: https://roblox.github.io/luau/ +# Command line +[command-line]: #user-content-command-line + +```bash +rbxmk [ FILE ] [ ...VALUE ] +``` + +The rbxmk command receives a path to a file to be executed as a Lua script. + +```bash +rbxmk script.lua +``` + +If `-` is given, then the script will be read from stdin instead. + +```bash +echo 'print("hello world!")' | rbxmk - +``` + +The remaining arguments are Lua values to be passed to the file. Numbers, bools, +and nil are parsed into their respective types in Lua, and any other value is +interpreted as a string. + +```bash +rbxmk script.lua true 3.14159 hello! +``` + +Within the script, these arguments can be received from the `...` operator: + +```lua +local arg1, arg2, arg3 = ... +``` + # Environment [environment]: #user-content-environment -The Lua environment provided by rbxmk is packaged as a number of libraries. Some -libraries are loaded under a specific name, while others are loaded directly -into the global environment. +[Lua][lua] scripts are used to perform actions in rbxmk. The environment +provided by rbxmk is packaged as a set of libraries. Some libraries are loaded +under a specific name, while others are loaded directly into the global +environment: Library | Description -----------------------|------------ [(base)][base-lib] | The Lua 5.1 standard library, abridged. [rbxmk ][rbxmk-lib] | An interface to the rbxmk engine, and the rbxmk environment. [(roblox)][roblox-lib] | An environment emulating the Roblox Lua API. -[os ][os-lib] | Extensions to the standard os library. -[sym ][sym-lib] | Symbols for accessing instance metadata. -[types ][types-lib] | Fallbacks for constructing certain types. +[os][os-lib] | Extensions to the standard os library. +[sym][sym-lib] | Symbols for accessing instance metadata. +[types][types-lib] | Fallbacks for constructing certain types. [(sources)][sources] | An assortment of libraries for interfacing with various external sources. +[lua]: https://lua.org + ## Base library [base-lib]: #user-content-base-library diff --git a/rbxmk/doc/USAGE.md b/rbxmk/doc/USAGE.md deleted file mode 100644 index 608e6dee..00000000 --- a/rbxmk/doc/USAGE.md +++ /dev/null @@ -1,320 +0,0 @@ -[DRAFT] - -# Usage -This document provides an overview of how rbxmk is used. For a detailed -reference, see [DOCUMENTATION.md](DOCUMENTATION.md). - -## Command options - -```bash -rbxmk [ FILE ] [ ...VALUE ] -``` - -The rbxmk command receives a path to a file to be executed as a Lua script. - -```bash -rbxmk script.lua -``` - -If `-` is given, then the script will be read from stdin instead. - -```bash -echo 'print("hello world!")' | rbxmk - -``` - -Remaining arguments are Lua values to be passed to the file. Numbers, bools, and -nil are parsed into their respective types in Lua, and any other value is -interpreted as a string. - -```bash -rbxmk script.lua true 3.14159 hello! -``` - -Within the script, these arguments can be received from the `...` operator: - -```lua -local arg1, arg2, arg3 = ... -``` - -## Lua environment -[Lua](https://lua.org) scripts are used to perform actions. Scripts are run in a -modified environment, where most of the standard functions and libraries are -available. A complete list of included items can be found in -[DOCUMENTATION.md](DOCUMENTATION.md#user-content-standard-library). - -Also included is an environment similar to the [Roblox Lua API][apiref], -allowing the user to construct and manipulate objects with a familiar API. - -Several additional libraries are included to aid the user's workflow: - -- `rbxmk`: General auxiliary functions. -- `os`: Additional operating system functions. -- Various source libraries that provide interfaces to external sources. - - -[apiref]: https://developer.roblox.com/en-us/api-reference - -## Workflow -Operating on objects within rbxmk is very similar to operating on objects within -Roblox. Instances can be created and modified. Properties can be retrieved and -updated. Values can be read from and written to external sources. - -```lua -local folder = Instance.new("Folder") -folder.Name = "Modules" - -local module = Instance.new("ModuleScript") -module.Name = "Hello" -module.Source = [[return "Hello world!"]] -module.Parent = folder -``` - -### Instances -A major difference between Roblox and rbxmk is what an instance represents. In -Roblox, an instance is a live object that acts and reacts. In rbxmk, an instance -represents *data*, and only data. - -Consider the RBXL file format. Files of this format contain information used to -reconstruct the instances that make up a place or model. Such files are static: -they contain only data, but are difficult to manipulate in-place. Instances in -rbxmk are like this, except that they are also interactive: the user can freely -modify data and move it around. - -Because of this, there are several differences between the Roblox API and the -rbxmk API. For one, any kind of class can be created. Instances are just data, -including the class name. The ClassName property can even be assigned to. - -```lua -local foobar = Instance.new("Foobar") -foobar.ClassName = "FizzBuzz" -- allowed -``` - -Instances also have no defined properties. A value of any type can be assigned -to any property. Likewise, properties that are not explicitly assigned -effectively do not exist. - -```lua -local part = Instance.new("Part") -part.Foobar = 42 -- allowed -print(part.Position) --> nil -``` - -That said, even though it is possible for rbxmk to create arbitrary classes with -arbitrary properties, this does not mean such instances will be interpreted in -any meaningful way when sent over to Roblox. If the user wants to use such data -in Roblox, it is up to them to make sure the data is correct according to -Roblox's API. - -Instances in rbxmk implement a subset of Roblox's Instance members: - -- `.ClassName` -- `.Name` -- `.Parent` -- `:ClearAllChildren()` -- `:Clone()` -- `:Destroy()` -- `:FindFirstAncestor()` -- `:FindFirstAncestorOfClass()` -- `:FindFirstChild()` -- `:FindFirstChildOfClass()` -- `:GetChildren()` -- `:GetDescendants()` -- `:GetFullName()` -- `:IsAncestorOf()` -- `:IsDescendantOf()` - - - -### DataModel -rbxmk has no singular game tree that contains all objects. Instead, any number -of **DataModel** objects can be created with the `DataModel.new()` function. The -resulting value is an Instance like any other, except that the class name cannot -be assigned to. - -```lua -local game = DataModel.new() -foobar.Parent = game -game.ClassName = "Foobar" -- not allowed -``` - -Additionally, the properties on a DataModel object are interpreted as metadata, -which may be needed in certain cases. - -```lua -game.ExplicitAutoJoints = true -``` - -For convenience, DataModels also define the `GetService` method. This creates a -child instance of the given class, and marks the instance as a service. If such -an instance already exists in the DataModel, then that instance will be returned -instead. - -```lua -local workspace = game:GetService("Workspace") -print(workspace == game:GetService("Workspace")) --> true -``` - -### Data types -Also included in the rbxmk environment are constructors for the various Roblox -types, such as `Vector3`, `CFrame`, and `UDim2`. - -```lua -local part = Instance.new("Part") -part.Position = Vector3.new(10, 20, 30) -``` - -Certain types have an ambiguous representation in Roblox Lua. In rbxmk, this is -remedied by defining constructors for such types. These return userdata values -that are used exclusively for assigning to properties to ensure the correct type -is encoded or decoded. When getting such a value, the original value of the base -type is returned instead of a userdata. - -The following numeric type constructors are available: -- `float.new(number)` -- `int.new(number)` -- `int64.new(number)` -- `token.new(number)` (enums) - -Normal Lua numbers are interpreted as the `double` type. - -The following string type constructors are available: -- `BinaryString.new(string)` -- `ProtectedString.new(string)` -- `Content.new(string)` -- `SharedString.new(string)` - -Normal Lua strings are interpreted as the `string` type. - -```lua -local value = Instance.new("BinaryValue") -value.Name = "BinaryValue" -value.Value = BinaryValue.new("\0\1\2\3") -print(value.Value) --> "\0\1\2\3" (as a Lua string) -``` - - - -## Formats -A principle concept in rbxmk is **formats**. A format describes how a Lua value -can be encoded between a raw sequence of bytes. For example, in rbxmk, the -"rbxl" format can encode a tree of instances into a format compatible with -Roblox's RBXL file format. - -Formats can be accessed at a low level through the `rbxmk.encodeformat` and -`rbxmk.decodeformat` functions. - -```lua -local folder = Instance.new("Folder") -folder.Name = "Modules" - -local data = rbxmk.encodeformat("rbxmx", folder) --> string containing XML model data -local folderCopy = rbxmk.decodeformat("rbxmx", data) --> Folder instance -print(folderCopy.Name) --> Modules -``` - -## Sources -Another principle concept is **sources**. A source is an external location from -which a stream of bytes can be read or written to. For example, the "file" -source allows encoded data to be read from or written to the file system. - -Sources can be accessed at a low level through the `rbxmk.readsource` and -`rbxmk.writesource` functions. - -```lua -local folder = Instance.new("Folder") -folder.Name = "Modules" - -local data = rbxmk.encodeformat("rbxmx", folder) -rbxmk.writesource("file", data, "folder.rbxmx") -- data written to folder.rbxmx - -local dataCopy = rbxmk.readsource("file", "folder.rbxmx") -- dataCopy read from folder.rbxmx -local folderCopy = rbxmk.decodeformat("rbxmx", dataCopy) -print(folderCopy.Name) --> Modules -``` - -## Libraries -rbxmk defines several additional libraries. - -### rbxmk -The **rbxmk** library contains general auxiliary functions. - -The `rbxmk.load` function is used to run another script from within the current -script. - -```lua -local result = rbxmk.load("subscript.lua", true, 3.14159, "hello!") -``` - -### os -The **os** library merges into the standard os library by including several -additional functions. - -The `os.split` function can be used split a file path into its components. - -```lua -print(os.split("projects/project/model/script.lua", "dir", "stem", "ext")) ---> "projects/project/model", "script", ".lua" -``` - -The `os.join` function can be used to correctly join two file paths together. - -```lua -print(os.join("projects/project/model", "script.lua")) ---> "projects/project/model/script.lua" -``` - -The `os.expand` function expands particular variables within a path to their -full representation. - -```lua -print(os.expand("$script_name")) --> "build.lua" -print(os.expand("$script_directory")) --> "projects/project" -``` - -The `os.getenv` function gets an environment variable. - -```lua -print(os.getenv("HOME")) --> "/home/user" -``` - -The `os.dir` function returns the files within a directory. - -```lua -for _, file in ipairs(os.dir("projects/project")) do - print(file.name) - print(file.isdir) - print(file.size) - print(file.modtime) -end -``` - -### file -The **file** library provides a convenient interface to the file system. - -The `file.read` function reads from a file. - -```lua -local game = file.read("place.rbxl") -- "rbxl" format is inferred from extension -local game = file.read("place.rbxl", "rbxlx") -- force "rbxlx" format -``` - -The `file.write` function writes to a file. - -```lua -file.write("place.rbxl", game) -file.write("place.rbxl", "rbxlx", game) -```