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

There are two setup ways, "standalone" or "to upstream".

Standalone for when you want to have your own repository, and work on your extension alone.

"To Upstream" is when you intend to create a merge request to the main Shosetsu Extensions repository.

Standalone

You want your extension on your own repository, or just to use by yourself.

Via GitLab

If you want to use GitLab.

  1. Fork the template repository. Choose a new name if you want.
  2. Clone the repository to your local machine. Using the new name if you changed it. 
    git clone https://gitlab.com/USERNAME_HERE/template-repository.git
# For the SSH fans
git clone git@gitlab.com:USERNAME_HERE/template-repository.git
  3. Proceed through to the next step of the guide.

Of your own choice

  1. Clone the repository to your local machine. 
    git clone https://gitlab.com/shosetsuorg/template-repository.git
# For the SSH fans
git clone git@gitlab.com:shosetsuorg/template-repository.git
  2. Proceed through to the next step of the guide.

To Upstream

You want to upstream your extension.

  1. Fork the extensions repository. So that you can create a merge request later.
  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.

  1. Run Android Studio to run Shosetsu.
  2. Ensure the test-server.sh script is running in your repository.
  3. Get your current IP address of your computer, typically something like 192.168.1.123.
  4. Using the IP address, add a repository to Shosetsu with a URL like so http://192.168.1.123:8080/, changing the IP address of course.
    • Note: the end "/" is very important, do not remove it.

and be able to see logcat to see output and or errors.

Extension tester

Easiest method. Already downloaded via the dev-setup.sh script.

When you need to test something, perform the following command and the tester will test your extension:

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 logical code, instead just have a call to Require with a large definition block.

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.

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
NameDescription
idUnique ID of the extension, should match in all locations.
verVersion of this extension, should match index. This can be set to a version behind to always appear as an update is needed.
libVerVersion of kotlin-lib that this extension is designed to work with.
authorYour name or user name.
repoIf your extension is not based on the shosetsu extension repository, place your repo url here. Currently does nothing.
depA list of dependencies that this extension requires. Currently does nothing.

Constants provided

NameUseValue
QUERYTo retrieve the query data from data.0
PAGE_INDEXIndex of the page number to start with1

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.