Creating Extensions

Shosetsu currently uses Lua extensions and an API on which the whole app is built off of.

Lua is a simple interperated language. We recommend skimming through Programming in Lua and/or the reference manual before trying to start writing extensions.

Requirements

• An internet connection.
• Basic programming knowledge.
• Any text editor except Microsoft Notepad, preferably an IDE.

::: guide IDE Recommendation For this guide we recommend IntelliJ IDEA, as that is the one we've based our guide on. ::: aside Download here :::

Setup

1. Fork the extensions repository
2. Clone the repository to your local machine

   git clone https://gitlab.com/USERNAME_HERE/extensions.git
   # For the SSH fans
   git clone git@gitlab.com:USERNAME_HERE/extensions.git
   

3. In the directory, run the dev-setup.sh script to download development files to your repository.

IntelliJ IDEA

1. Install the EmmyLua and Kotlin plugins (Settings > Plugins > Marketplace) and restart IDEA.
2. Open the directory of the extensions repo with File > Open.
3. Now you can start development!

Extension testing

Android emulation

Best method.

Run Android Studio to run Shosetsu, and be able to see logcat to see output and or errors.

Extension tester

Easiest method.

Download the jar from here and plop it into the repository directory.

When you need to test something, perform the following command and the tester will test.

java -jar ./extension-tester.jar src/LANG/EXTENSION.lua

Understanding Lua Extensions and Libraries

Each Lua extension has the responsibility for an individual site, but sites often use available software, which means they share the same code base. This is why extensions sometimes do not have any code but a call to Require. A good example is the plethora of extensions based on the Madara library, which defer all logic to the Madara library.

Kotlin Lib

Shosetsu uses something called the "kotlin-lib" for all its fundamental functionality.

Documentation can be found here. I suggest looking at the documentation of the custom Lua functions you can use.

Extension information

Template

You can acquire a template extension from here. This template has documentation on the various fields expected in an extension.

Header

A Commented JSON Header is included at the start of every Lua Extension. This is used for file based identification.

-- {"id":-1,"ver":"1.0.0","libVer":"1.0.0","author":"","repo":"","dep":["foo","bar"]}

Life cycle

An extension has a life cycle internally in Shosetsu.

| Stage | Description | ----------------- | ------------------------------------------------------------- | | Initialization | Extension is required for some process, and is initialized. | | Invocation | Extension is invoked for whatever process needs it. | | Storage in memory | Extension is stored in memory till it is needed again. | | Discarded | Extension is discarded from memory during app shutdown. |

This means that values you declare in the top level scope of an extension are retained throughout the entire extension lifecycle.

Explanation of values

Constants provided

Variable Naming

There are a few DO NOT's with creating extensions.

1. DO NOT name a local or global variable the same as any of the above

Writing your extension

Now that you understand the basics, you can get to writing your extension:

1. Copy the template you downloaded to src/LANG/NAME.lua. LANG being the language of the website and NAME being the file name you want to give it.
2. Fill in required fields.
3. Remove optionals that you do not need.
4. Create functions according to specification
5. Test the extension
6. Repeat 5 until there are no bugs.
7. Make a PR to upstream.