Merge pull request #36 from technomancy/readme

Add documentation.

Author: MikuAuahDark

license.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2019-2022 LOVE Development Team
+Copyright (c) 2019-2025 LOVE Development Team
 
 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages

readme.md

@@ -0,0 +1,99 @@
+# lua-https
+
+lua-https is a simple Lua HTTPS module using native platform backends
+specifically written for [LÖVE](https://love2d.org) 12.0 and supports
+Windows, Linux, macOS, iOS, and Android.
+
+## Reference
+
+To use lua-https, load it with require like `local https = require("https")`.
+lua-https does not create global variables!
+
+The https module exposes a single function: `https.request`.
+
+## Synopsis
+
+Simplified form:
+
+```lua
+code, body = https.request( url )
+```
+
+If you need to specify headers in the request or get them in the
+response, you can use the full form:
+
+```lua
+code, body, headers = https.request( url, options )
+```
+
+### Arguments
+
+* string `url`: HTTP or HTTPS URL to access.
+* table `options`: Optional options for advanced mode.
+  * string `data`: Additional data to send as application/x-www-form-urlencoded (unless specified otherwise in Content-Type header).
+  * string `method`: HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.
+  * table `headers`: Additional headers to add to the request as key-value pairs.
+
+### Return values
+
+* number `code`: HTTP status code, or 0 on failure.
+* string `body`: HTTP response body or nil on failure.
+* table `headers`: HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.
+
+## Compile From Source
+
+While lua-https is bundled in LÖVE 12.0 by default, it's possible to
+compile the module from source and use it on earlier version of LÖVE
+or Lua. All compilation requires Lua 5.1 (or LuaJIT) headers and libraries.
+
+### Linux
+
+Ensure you have CMake as well as the OpenSSL and cURL development
+libraries installed.
+
+```
+cmake -Bbuild -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install
+cmake --build build --target install
+```
+
+`https.so` can be found in the `install` folder.
+
+### Windows
+
+Compilation is done using CMake. This assume MSVC toolchain is
+used. Change "x64" to "Win32" to compile for x86 32-bit platform or
+"ARM64" for ARM64 platform.
+
+```
+cmake -Bbuild -S. -A x64 -DCMAKE_INSTALL_PREFIX=%CD%\install
+cmake --build build --config Release --target install
+```
+
+https.dll can be found in the install folder.
+
+### Android
+
+Available since LÖVE 11.4
+Proper 3rd-party C module support requires this LÖVE version.
+
+Compilation is done by placing lua-https source code in
+`<love-android>/love/src/jni/lua-modules`. The structure will look like this:
+
+`<love-android>/love/src/jni/lua-modules/lua-https`
++ example
++ src
++ Android.mk
++ CMakeLists.txt
++ java.txt
++ license.txt
+
+Afterwards compile love-android as usual. The modules will be
+automatically embedded to the APK. This can be verified by checking
+the APK with Zip viewer application and inspecting files in
+lib/arm64-v8a and lib/armeabi-v7a. 
+
+## Copyright
+
+Copyright © 2019-2025 LOVE Development Team
+
+lua-https is licensed under [zLib license](license.txt), same as LÖVE.