From cfdca639db51fcf48449b467ef95d300aa412526 Mon Sep 17 00:00:00 2001 From: Robert Jelic <36573031+NoryiE@users.noreply.github.com> Date: Mon, 31 Oct 2022 17:30:11 +0100 Subject: [PATCH] Docs update some docs update for the new installer --- docs/Home.md | 4 +- docs/_navbar.md | 4 +- docs/_sidebar.md | 6 +-- docs/home/How-To.md | 59 +++++++++++++++++++++++++ docs/home/Quick-Start.md | 95 ---------------------------------------- docs/home/download.md | 36 +++++++++++++++ docs/home/installer.md | 71 ------------------------------ docs/install.lua | 87 ++++++++++++++++-------------------- 8 files changed, 139 insertions(+), 223 deletions(-) create mode 100644 docs/home/How-To.md delete mode 100644 docs/home/Quick-Start.md create mode 100644 docs/home/download.md delete mode 100644 docs/home/installer.md diff --git a/docs/Home.md b/docs/Home.md index 9d660da..08db0ec 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -1,4 +1,4 @@ -# Welcome to The Basalt Wiki! +# Welcome to The Basalt Wiki *Note: The Basalt Wiki is a work in progress. Please treat wiki errors the same as bugs and report them accordingly.* @@ -6,7 +6,7 @@ Here you can find information about how to use Basalt as well as examples of fun ## About Basalt -Basalt is intended to be an easy-to-understand UI Framework designed for CC:Tweaked (Also know as "ComputerCraft: Tweaked") - a popular minecraft mod. For more information about CC:Tweaked, checkout the project's [wiki](https://tweaked.cc/) or [download](https://modrinth.com/mod/cc-tweaked). +Basalt is intended to be an easy-to-understand UI Framework designed for CC:Tweaked (Also known as "ComputerCraft: Tweaked") - a popular minecraft mod. For more information about CC:Tweaked, checkout the project's [wiki](https://tweaked.cc/) or [download](https://modrinth.com/mod/cc-tweaked). ## Quick Demo diff --git a/docs/_navbar.md b/docs/_navbar.md index af382db..52ab04e 100644 --- a/docs/_navbar.md +++ b/docs/_navbar.md @@ -1,4 +1,4 @@ - Getting Started - [Home](Home) - - [Quick Start](home/Quick-Start) - - [Installer](home/installer) + - [How To](home/How-To) + - [Download](home/download) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index ca57c17..93467e1 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,7 +1,7 @@ - About - - [Home](Home.md) - - [Quick Start](home/Quick-Start.md) - - [Installer](home/installer) + - [Home](home) + - [How To](home/How-To) + - [Download](home/download) - Objects - [Basalt](objects/Basalt.md) - [Object](objects/Object.md) diff --git a/docs/home/How-To.md b/docs/home/How-To.md new file mode 100644 index 0000000..f28754b --- /dev/null +++ b/docs/home/How-To.md @@ -0,0 +1,59 @@ +After downloading the project you can finally start creating your own program and use basalt. The first thing you want to use in your program is always: + +```lua +local basalt = require("basalt") +``` + +It doesn't matter if you're using the source folder or the minified/packed version of basalt. Both can be found by using require("basalt") without .lua. + +Also to really run basalt you should use + +```lua +basalt.autoUpdate() +``` + +somewhere on the bottom of your program. basalt.autoUpdate() starts the event listener and the draw handler. + +## Example + +Here is a fully working example of how a program could look like: + +```lua +local basalt = require("basalt") --> Load the basalt framework into the variable called "basalt" + +--> Now we want to create a base frame, we call the variable "main" - by default everything you create is visible. (you don't need to use :show()) +local main = basalt.createFrame() + +local button = mainFrame:addButton() --> Here we add our first button +button:setPosition(4, 4) -- of course we want to change the default position of our button +button:setSize(16, 3) -- and the default size. +button:setText("Click me!") --> This method displays what the text of our button should look like + +local function buttonClick() --> Let us create a function we want to call when the button gets clicked + basalt.debug("I got clicked!") +end + +-- Now we just need to register the function to the buttons onClick event handlers, this is how we can achieve that: +button:onClick(buttonClick) + + +basalt.autoUpdate() -- As soon as we call basalt.autoUpdate, the event and draw handlers will listen to any incomming events (and draw if necessary) +``` + +If you're like us and strive for succinct and beautiful code, here is a cleaner implementation of the code above: + +```lua +local basalt = require("basalt") + +local main = basalt.createFrame() +local button = main --> Basalt returns an instance of the object on most methods, to make use of "call-chaining" + :addButton() --> This is an example of call chaining + :setPosition(4,4) + :setText("Click me!") + :onClick( + function() + basalt.debug("I got clicked!") + end) + +basalt.autoUpdate() +``` diff --git a/docs/home/Quick-Start.md b/docs/home/Quick-Start.md deleted file mode 100644 index a46cad6..0000000 --- a/docs/home/Quick-Start.md +++ /dev/null @@ -1,95 +0,0 @@ -# Quick Start - -## How to use - -To load Basalt into your project, make use of the following code on top of your code. -```lua -local basalt = require("basalt") -``` - -It does not matter if you have installed the single file version or the full folder project. -Both versions can be loaded by using `require("Basalt")`, you dont need to add `.lua`. - -## Download - -### Download the folder version -This version is for people who'd like to work with Basalt, change something in Basalt, or checkout the project. -But you are also able to just use it to create your own UI. - - -To install the full project to your CC:Tweaked Computer, use the following command on your CC:Tweaked shell: - -`pastebin run ESs1mg7P` - -This will download the project as a folder called "Basalt". You are immediatly after the download is done able to use it in your projects. - -### Download the single file version -This is the version you should use if you're done with programming. It is a little bit faster and it is also minified, which makes the project smaller. -To install the single filed project to your CC:Tweaked Computer, use the following command on your CC:Tweaked shell: - -`pastebin run ESs1mg7P packed` - -This will download the project as a single file called "basalt.lua". You are immediatly after the download is done able to use it in your projects. - -### Basalt Package Manager - -**The Basalt Package Manager is still in alpha!** -The Basalt Package Manager is a visual installer, you are able to change some settings, also to choose which objects are necessary for your projects and which are not. - -To install the BPM (Basalt Package Manager) use the following command on your CC:Tweaked shell: - -`pastebin run ESs1mg7P bpm true` - -The true keyword in the end is optional and would simply start BPM immediately. - -## Example -Here is a fully functioning example of Basalt code - -```lua -local basalt = require("basalt") --> Load the Basalt framework - ---> Create the first frame. Please note that Basalt needs at least one active "non-parent" frame to properly supply events ---> When Basalt#createFrame makes use of unique identifiers (commonly referred to as UIDs), meaning that the supplied value must be UNIQUE -local mainFrame = basalt.createFrame("mainFrame") - ---> Show the frame to the user -mainFrame:show() - -local button = mainFrame:addButton("clickableButton") --> Add a button to the mainFrame (With a unique identifier) - ---> Set the position of the button, Button#setPosition follows an x, y pattern. ---> The x value is how far right the object should be from its anchor (negative values from an anchor will travel left) ---> The y value is how far down the object should be from its anchor (negative values from an anchor will travel up) -button:setPosition(4, 4) - -button:setText("Click me!") --> Set the text of our button - -local function buttonClick() --> This function serves as our click logic - basalt.debug("I got clicked!") -end - ---> Remember! You cannot supply buttonClick(), that will only supply the result of the function ---> Make sure the button knows which function to call when it's clicked -button:onClick(buttonClick) - -button:show() --> Make the button visible, so the user can click it - -basalt.autoUpdate() --> Basalt#autoUpdate starts the event listener to detect user input -``` -If you're like us and strive for succinct and beautiful code, here is a cleaner implementation of the code above: -```lua -local basalt = require("basalt") - -local mainFrame = basalt.createFrame("mainFrame"):show() -local button = mainFrame --> Basalt returns an instance of the object on most methods, to make use of "call-chaining" - :addButton("clickableButton") --> This is an example of call chaining - :setPosition(4,4) - :setText("Click me!") - :onClick( - function() - basalt.debug("I got clicked!") - end) - :show() - -basalt.autoUpdate() -``` diff --git a/docs/home/download.md b/docs/home/download.md new file mode 100644 index 0000000..2e06061 --- /dev/null +++ b/docs/home/download.md @@ -0,0 +1,36 @@ +Basalt provides multiple unique versions. A source version, a minified version and a web version. + +## Source + +This version is, like the name already says, the source code of basalt. If you want to dig into the code, add additional content or just prefer to use the source, then you should aim for the source-version. + +The following command allows you to download the source-version on your computer: + +`wget run https://basalt.madefor.cc/install.lua source [foldername] [branch]` + +The first optional argument is the folder name you wish that basalt should be installed into, by default the folder is called basalt. +The second optional argument is the branch you want to use. If you don't know what this means please ignore it (the 2 options are master and dev) + +## Minified / Packed + +This version is the minified version, i also call it the packed version. There are 2 changes, the first one is that the code will be shown minified which makes the size much smaller, the second change is that you will recieve a file instead of a folder. + +The following command allows you to download the packed-version on your computer: + +`wget run https://basalt.madefor.cc/install.lua packed [filename] [branch]` + +The first optional argument is the file name you wish that the installer should use, by default the file is called basalt.lua. +The second optional argument is the branch you want to use. If you don't know what this means please ignore it (the 2 options are master and dev) + +## Web + +The web version is a special version, used if your goal is to keep your project's size as small as possible. I suggest you to use the web version only if you don't restart your program over and over again. For example if you designed your program to reboot after the user made a bad choice (leads into a error or something like that) it is better to use the minified/source version. + +The following command allows you to download the web-version on your computer: + +`wget run https://basalt.madefor.cc/install.lua web [version] [filename]` + +By default the first argument is the latest version of basalt's releases. [Here](https://github.com/Pyroxenium/Basalt/tree/master/docs/versions) you can see which versions are available to use. +For example: wget run https://basalt.madefor.cc/install.lua web basalt-1.6.3.lua - the second argument is just the file name, default is basaltWeb.lua. + +Remember to rename `local basalt = require("basalt")` into `local basalt = require("basaltWeb")` if you want to use the web-version \ No newline at end of file diff --git a/docs/home/installer.md b/docs/home/installer.md deleted file mode 100644 index 170e25c..0000000 --- a/docs/home/installer.md +++ /dev/null @@ -1,71 +0,0 @@ -# Installer - -This is just a script which helps you to setup your program to automatically install the Basalt UI Framework if it doesn't exist. Which means you create your program (which requires basalt), and add this on the top of your program. Now everytime you execute your program it checks if basalt.lua (or your custom filepath) exists or not. If it dosent exist it installs it, or if you are using the advanced installer it asks the user if the program is allowed to install basalt for you. - -## Basic Installer -Here is a very basic installer which just installs basalt.lua if it dosen't exist: -```lua ---Basalt configurated installer -local filePath = "basalt.lua" --here you can change the file path that it installs to. default: /basalt.lua -if not(fs.exists(filePath))then - shell.run("pastebin run ESs1mg7P packed true "..filePath:gsub(".lua", "")) -- this is an alternative to the wget command -end -local basalt = require(filePath:gsub(".lua", "")) -- here you can change the variablename in any variablename you want default: basalt -``` - -## Advanced Installer -This is a visual version, it asks the user if he wants to install basalt.lua (if not found)
-![](https://raw.githubusercontent.com/Pyroxenium/Basalt/master/docs/_media/installer.png) -```lua ---Basalt configurated installer -local filePath = "basalt.lua" --here you can change the file path it installs to. Default: /basalt.lua -if not fs.exists(filePath) then - local w,h = term.getSize() - term.clear() - local _installerWindow = window.create(term.current(),w/2-8,h/2-3,18,6) - _installerWindow.setBackgroundColor(colors.gray) - _installerWindow.setTextColor(colors.black) - _installerWindow.write(" Basalt Installer ") - _installerWindow.setBackgroundColor(colors.lightGray) - for line=2,6,1 do - _installerWindow.setCursorPos(1,line) - if(line==3)then - _installerWindow.write(" No Basalt found! ") - elseif(line==4)then - _installerWindow.write(" Install it? ") - elseif(line==6)then - _installerWindow.setTextColor(colors.black) - _installerWindow.setBackgroundColor(colors.gray) - _installerWindow.write("Install") - _installerWindow.setBackgroundColor(colors.lightGray) - _installerWindow.write(string.rep(" ",5)) - _installerWindow.setBackgroundColor(colors.red) - _installerWindow.write("Cancel") - else - _installerWindow.write(string.rep(" ",18)) - end - end - _installerWindow.setVisible(true) - _installerWindow.redraw() - while(not(fs.exists(filePath))) do - local event, p1,p2,p3,p4 = os.pullEvent() - if(event=="mouse_click")then - if(p3==math.floor(h/2+2))and(p2>=w/2-8)and(p2<=w/2-2)then - shell.run("pastebin run ESs1mg7P packed true "..filePath:gsub(".lua", "")) - _installerWindow.setVisible(false) - term.clear() - break - end - if(p3==math.floor(h/2+2))and(p2<=w/2+9)and(p2>=w/2+4)then - _installerWindow.clear() - _installerWindow.setVisible(false) - term.setCursorPos(1,1) - term.clear() - return - end - end - end - term.setCursorPos(1,1) - term.clear() -end -``` diff --git a/docs/install.lua b/docs/install.lua index 0638c3f..580f43d 100644 --- a/docs/install.lua +++ b/docs/install.lua @@ -45,11 +45,11 @@ end -- Creates a filetree based on my github project, ofc you can use this in your projects if you'd like to function installer.createTree(page, branch, dirName) dirName = dirName or "" - printStatus("Receiving file tree for "..dirName~="" and dirName or "Basalt") + printStatus("Receiving file tree for "..(dirName~="" and "Basalt/"..dirName or "Basalt")) local tree = {} local request = http.get(page, _G._GIT_API_KEY and {Authorization = "token ".._G._GIT_API_KEY}) if not(page)then return end - if(request==nil)then error("API rate limit exceeded. It will be available again in a couple of hours.") end + if(request==nil)then error("API rate limit exceeded. It will be available again in one hour.") end for _,v in pairs(textutils.unserialiseJSON(request.readAll()).tree)do if(v.type=="blob")then table.insert(tree, {name = v.path, path=fs.combine(dirName, v.path), url=installer.githubPath..branch.."/Basalt/"..fs.combine(dirName, v.path), size=v.size}) @@ -60,27 +60,9 @@ function installer.createTree(page, branch, dirName) return tree end --- Creates a filetree based on my github project, ofc you can use this in your projects if you'd like to -function installer.createTableTree(page, branch, dirName) - dirName = dirName or "" - printStatus("Receiving file tree for "..dirName~="" and dirName or "Basalt") - local tree = {} - local request = http.get(page, _G._GIT_API_KEY and {Authorization = "token ".._G._GIT_API_KEY}) - if not(page)then return end - if(request==nil)then error("API rate limit exceeded. It will be available again in a couple of hours.") end - for _,v in pairs(textutils.unserialiseJSON(request.readAll()).tree)do - if(v.type=="blob")then - table.insert(tree, {name = v.path, path=fs.combine(dirName, v.path), url=installer.githubPath..branch.."/Basalt/"..fs.combine(dirName, v.path), size=v.size}) - elseif(v.type=="tree")then - tree[v.path] = installer.createTableTree(v.url, branch, fs.combine(dirName, v.path)) - end - end - return tree -end - function installer.createTreeByBasaltData(page, branch, dirName) dirName = dirName or "" - printStatus("Receiving file tree for "..dirName~="" and dirName or "Basalt") + printStatus("Receiving file tree for "..(dirName~="" and "Basalt/"..dirName or "Basalt")) local bData = installer.getBasaltData() if(bData~=nil)then local tree = {} @@ -159,7 +141,7 @@ function installer.getPackedProject(branch, ignoreList) else table.insert(ignoreList, "init.lua") end - local projTree = installer.createTableTree("https://api.github.com/repos/Pyroxenium/Basalt/git/trees/"..branch..":Basalt", branch, "") + local projTree = installer.createTree("https://api.github.com/repos/Pyroxenium/Basalt/git/trees/"..branch..":Basalt", branch, "") local filteredList = {} local project = {} @@ -255,6 +237,7 @@ end end function installer.generateWebVersion(file, version) + if(fs.exists(file))then error("A file called "..file.." already exists!") end version = version or "latest.lua" local request = http.get("https://basalt.madefor.cc/versions/"..version, _G._GIT_API_KEY and {Authorization = "token ".._G._GIT_API_KEY}) if(request~=nil)then @@ -273,6 +256,7 @@ end ]] f.write(content) f.close() + printStatus("Web version successfully downloaded!") end else error("Version doesn't exist!") @@ -296,8 +280,18 @@ function installer.getProjectFiles(branch, ignoreList) end for k,v in pairs(projTree)do - if not(isInIgnoreList(v))then - table.insert(filteredList, v) + if not(isInIgnoreList(v.name))then + if(type(k)=="string")then + local sub = {} + for a,b in pairs(v)do + if not(isInIgnoreList(b.name))then + table.insert(sub, b) + end + end + filteredList[k] = sub + else + table.insert(filteredList, v) + end end end @@ -308,7 +302,15 @@ function installer.getProjectFiles(branch, ignoreList) local fList = {} local delay = 0 for k,v in pairs(filteredList)do - table.insert(fList, function() sleep(delay) downloadFile(v.url, v.path) delay = delay + 0.05 end) + if(type(k)=="string")then + for a,b in pairs(v)do + table.insert(fList, function() sleep(delay) downloadFile(b.url, b.path) end) + delay = delay + 0.05 + end + else + table.insert(fList, function() sleep(delay) downloadFile(v.url, v.path) end) + delay = delay + 0.05 + end end parallel.waitForAll(table.unpack(fList)) @@ -316,6 +318,7 @@ function installer.getProjectFiles(branch, ignoreList) end function installer.downloadPacked(filename, branch, ignoreList, minify) + if(fs.exists(filename))then error("A file called "..filename.." already exists!") end local projectContent = installer.getPackedProject(branch, ignoreList) if(minify)then local min @@ -335,38 +338,22 @@ function installer.downloadPacked(filename, branch, ignoreList, minify) end local f = fs.open(filename, "w") f.write(projectContent) - f.close() + f.close() + printStatus("Packed version successfully downloaded!") end function installer.downloadProject(projectDir, branch, ignoreList) - local projectFiles = installer.getProjectFiles(branch, ignoreList) + if(fs.exists(projectDir))then error("A folder called "..projectDir.." already exists!") end projectDir = projectDir or "basalt" branch = branch or "master" - - local function downloadFile(url, path) - print("Downloading "..path) - local files = splitString(path) - if(#files>1)then - local folderPath = "" - for a,b in pairs(files)do - if(a<#files)then - folderPath = fs.combine(folderPath, b) - else - if not (fs.exists(folderPath))then fs.makeDir(folderPath) end - installer.download(url, fs.combine(projectDir, path)) - end - end - else - installer.download(url, fs.combine(projectDir, path)) - end - end - - local fList = {} - local delay = 0 + local projectFiles = installer.getProjectFiles(branch, ignoreList) + fs.makeDir(projectDir) for k,v in pairs(projectFiles)do - table.insert(fList, function() sleep(delay) downloadFile(v.url, v.path) delay = delay + 0.05 end) + local f = fs.open(fs.combine(projectDir, k), "w") + f.write(v) + f.close() end - parallel.waitForAll(table.unpack(fList)) + printStatus("Source version successfully downloaded!") end if(#args>0)then