Document Lua plugin functions, bump version to 3.8.0

README.md

@@ -22,7 +22,7 @@ See [`docker/README.md`](docker/README.md)
 See [config.md](config.md)
 
 ## Plugins
-Gochan has a built-in [Lua](https://lua.org) interpreter and an event system to allow for extending your Gochan instance's functionality. See [events_triggered.md](./events_triggered.md) for a list of events and information about when they are used.
+Gochan has a built-in [Lua](https://lua.org) interpreter and an event system to allow for extending your Gochan instance's functionality. See [plugin_api.md](./plugin_api.md) for a list of functions and events, and information about when they are used.
 
 ## Migration
 If you run gochan v3.0 or newer and get a message telling you that your database is out of date, please run gochan-migration -updatedb. If this does not work, please contact the developers.
@@ -33,10 +33,9 @@ If you run gochan v3.0 or newer and get a message telling you that your database
 	- **Note on MySQL:** While MariaDB and mainline MySQL are very similar, there are a few features that MariaDB has that MySQL lacks that may cause issues. To specifically use the mainline MySQL server, run `GC_MYSQL_MAINLINE=1 vagrant up`
 3. After it finishes installing the Ubuntu VM, follow the printed instructions.
 
-
-## For developers (using vscode)
-1. Install go, the vs-go extention and gcc (I think, let me know if you need something else)
-2. Install either postgreSQL or mariaDB. Setup a database with an account and enter the ip:post and login information into the gochan.json config. See "Configuration". (Tools like PG admin highly recommended for easy debugging of the database)
+## For developers (using VS Code)
+1. Install Go, the VS Code Go extention, and gcc
+2. Install MariaDB, PostgreSQL, or MySQL. Setup a database with an account and enter the ip:post and login information into the gochan.json config. See "Configuration". (Tools like PG admin highly recommended for easy debugging of the database)
 3. Set "DebugMode" to true. This will log all logs to the console and disable some checks.
 4. Open the folder containing everything in vscode (named gochan most likely), go to "Run"
 	1. Select "gochan" if you wish to run/debug the website itself

build.py

@@ -38,7 +38,7 @@
 	"README.md",
 )
 
-GOCHAN_VERSION = "3.7.0"
+GOCHAN_VERSION = "3.8.0"
 DATABASE_VERSION = "2" # stored in DBNAME.DBPREFIXdatabase_version
 
 PATH_NOTHING = -1

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gochan.js",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "",
   "main": "./ts/main.ts",
   "private": true,

html/error/404.html

@@ -7,6 +7,6 @@
 <h1>404: File not found</h1>
 <img src="/error/lol 404.gif" border="0" alt="">
 <p>The requested file could not be found on this server.</p>
-<hr/>Site powered by <a href="https://github.com/gochan-org/gochan" target="_blank">Gochan</a> v3.7.0
+<hr/>Site powered by <a href="https://github.com/gochan-org/gochan" target="_blank">Gochan</a> v3.8.0
 </body>
 </html>

html/error/500.html

@@ -7,6 +7,6 @@
 <h1>Error 500: Internal Server error</h1>
 <img src="/error/server500.gif" border="0" alt="">
 <p>The server encountered an error while trying to serve the page, and we apologize for the inconvenience. The <a href="https://en.wikipedia.org/wiki/Idiot">system administrator</a> will try to fix things as soon they get around to it, whenever that is. Hopefully soon.</p>
-<hr/>Site powered by <a href="https://github.com/gochan-org/gochan" target="_blank">Gochan</a> v3.7.0
+<hr/>Site powered by <a href="https://github.com/gochan-org/gochan" target="_blank">Gochan</a> v3.8.0
 </body>
 </html>

html/error/502.html

@@ -7,6 +7,6 @@
 <h1>Error 502: Bad gateway</h1>
 <img src="/error/server500.gif" border="0" alt="">
 <p>The server encountered an error while trying to serve the page, and we apologize for the inconvenience. The <a href="https://en.wikipedia.org/wiki/Idiot">system administrator</a> will try to fix things as soon they get around to it, whenever that is. Hopefully soon.</p>
-<hr/>Site powered by <a href="https://github.com/gochan-org/gochan" target="_blank">Gochan</a> v3.7.0
+<hr/>Site powered by <a href="https://github.com/gochan-org/gochan" target="_blank">Gochan</a> v3.8.0
 </body>
 </html>

pkg/gcplugin/lua_test.go

@@ -30,7 +30,7 @@ event_trigger("newPost", "blah", 16, 3.14, true, nil)`
 )
 
 func initPluginTests() {
-	config.SetVersion("3.7.0")
+	config.SetVersion("3.8.0")
 	initLua()
 }
 
@@ -39,7 +39,7 @@ func TestVersionFunction(t *testing.T) {
 	err := lState.DoString(versionStr)
 	assert.Nil(t, err)
 	testingVersionStr := lState.Get(-1).(lua.LString)
-	assert.EqualValues(t, "3.7.0", testingVersionStr)
+	assert.EqualValues(t, config.GetVersion().String(), testingVersionStr)
 }
 
 func TestStructPassing(t *testing.T) {

plugin_api.md

@@ -0,0 +1,80 @@
+# Constants
+- **_GOCHAN_VERSION**
+	- The version string of the running Gochan server
+
+# Functions
+- **error_log([error_message string])**
+	- Creates and returns a zerolog [Event](https://pkg.go.dev/github.com/rs/zerolog) object for the error log. If a string is used as the argument, it is used as the error message.
+
+- **info_log()**
+	- Creates and returns a zerolog [Event](https://pkg.go.dev/github.com/rs/zerolog) object with an info level.
+
+- **warn_log()**
+	- Creates and returns a zerolog [Event](https://pkg.go.dev/github.com/rs/zerolog) object with a warning level.
+
+- **register_upload_handler(ext string, function(upload, post, board, filePath, thumbPath, catalogThumbPath, infoEv, accessEv, errEv))**
+	- Registers a function to be called for handling uploaded files with the given extension. See [pdf_thumbnail.lua](./sample-plugins/pdf_thumbnail.lua) for a usage example.
+
+- **get_thumbnail_ext(upload_ext string)**
+	- Returns the configured (or built-in) thumbnail file extension to be used for the given upload extension
+
+- **set_thumbnail_ext(upload_ext string, thumbnail_ext string)**
+	- Sets the thumbnail extension to be used for the given upload extension
+
+- **system_critical_config()**
+	- Returns the [SystemCriticalConfig](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/config#SystemCriticalConfig)
+
+- **site_config()**
+	- Returns the [SiteConfig](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/config#SiteConfig)
+
+- **board_config(board string)**
+	- Returns the [BoardConfig](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/config#BoardConfig) for the given board, or the default BoardConfig if `board` is an empty string
+
+- **db_query(query string)**
+	- Returns a [Rows](https://pkg.go.dev/database/sql#Rows) object for the given SQL query and an error if any occured, or nil if there were no errors.
+
+- **db_scan_rows(rows, scan_table)**
+	- scans the value of the current row into `scan_table` and returns an error if any occured, or nil if there were no errors.
+
+- **event_register(events_table, handler_func)**
+	- Registers `handler_func` for the events in `events_table`. If any arguments are passed to the event when it is triggered, it will be sent to `handler_func`.
+
+- **event_trigger(event_name string, data...)**
+	- Triggers the event registered to `event_name` and passes `data` (if set) to the event handler.
+
+- **register_manage_page(action string, title string, perms int, wants_json int, handler func(writer, request, staff, wants_json, info_ev, err_ev))**
+	- Registers the manage page accessible at /manage/`action` to be handled by `handler`. See [manage.RegisterManagePage](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/manage#RegisterManagePage) for info on how `handler` should be used, or [registermgmtpage.lua](./sample-plugins/registermgmtpage.lua) for an example
+
+- **load_template(files...)**
+	- Calls [gctemplates.LoadTemplate](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/gctemplates#LoadTemplate) using the given `files` and returns a [Template](https://pkg.go.dev/html/template#Template) and an error object (or nil if there were no errors).
+
+- **parse_template(template_name string, template_data string)**
+	- Calls [gctemplates.ParseTemplate](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/gctemplates#ParseTemplate) with the given template name and Go template data, and returns a [Template](https://pkg.go.dev/html/template#Template) and an error object (or nil if there were no errors).
+
+- **minify_template(template, data_table, writer, media_type)**
+	- Calls [serverutil.MinifyTemplate](https://pkg.go.dev/github.com/gochan-org/gochan/pkg/server/serverutil#MinifyTemplate) with the given `template` object, `data_table` (as variables passed to the template), `writer`, and `media_type`. See [registermgmtpage.lua](./sample-plugins/registermgmtpage.lua) for an example
+
+
+# Events
+This is a list of events that gochan may trigger at some point and can be used in the plugin system.
+
+- **db-connected**
+	- Triggered after gochan successfully connects to the database but before it is checked and initialized (db version checking, provisisioning, etc)
+
+- **db-initialized**
+	- Triggered after the database is successfully initialized (db version checking, provisioning, etc)
+
+- **incoming-upload**
+	- Triggered by the `gcsql` package when an upload is attached to a post. It is triggered before the upload is entered in the database
+
+- **message-pre-format**
+	- Triggered when an incoming post or post edit is about to be formatted
+
+- **shutdown**
+	- Triggered when gochan is about to shut down, in `main()` as a deferred call
+
+- **startup**
+	- Triggered when gochan first starts after its plugin system is initialized. This is (or at least should be) only triggered once.
+
+- **upload-saved**
+	- Triggered by the `posting` package when an upload is saved to the disk but before thumbnails are generated.