Initial

.gitignore

@@ -0,0 +1,6 @@
+/luarocks
+/lua
+/lua_modules
+/.luarocks
+**.o
+**.so

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# CONTRIBUTING
+
+As you can see this project has documentation inside Lua and C files.
+To be more useful to everyone some rules should be observed:
+
+* **Lua files should not have output**, i.e, people should know what Lua is
+doing without see output. You can accomplish that adding tests with `assert`
+functions, in a way that the reader/visitor/developer/magician that came to
+the code know exactly to what the code was evaluated to. Also doing this, when
+running code you will be certain that example has proven correct.
+
+* **Always test under multiple Lua versions**. Check the main project documentation
+to know which Lua versions should be supported.
+
+
+## Configure your text editor
+
+For C and Lua files our coding style uses:
+
+* `2` spaces for indentation
+
+* `80` column wide
+
+* C curly braces opening `{` should be kept in the line where the expression is
+opened, be in function declaratinos or in conditional/loops.
+
+The main reason to adopt this approach is:
+
+* The majority of IDEs support side-by-side edition. Some support even
+multiple vertical splits. 80 columns and 2 spaces as indentation give the
+reader/developer possibility to improve its work editing a source and its
+testings or even reading documentation.
+
+* It widens the device use possibilities, giving accessibility to develop and
+and read the code even in mobile (ex: Termux) or older devices.
+
+* It enforces the code simplicity. It is paradoxal, but it keep your code
+vertical, at the same time that reinforce the functions to be smaller,
+easy to read and simple to understand.
+
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Thadeu A. C. de Paula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,40 @@
+# ALK - A Lua Knowledge
+
+The main purpose of this project is gather Lua examples in a comprehensible
+way generating manuals, output in most diversified formats from the simple
+Lua and C code.
+
+## How to use
+
+As ALK is in its very beginning, you can just clone this repository and
+head to the src folder. Each folder is a Lua module containing a single lesson
+or specific concern.
+
+Each lesson on C Api, should have a Lua file containing its tests, named
+"ex.lua" and a C file named "ex.c".
+
+Each lesson directly on Lua should have a Lua file. The file should not
+generate any user output. All the examples should be written as tests
+using the builtin Lua function `assert`. This works to show exactly what
+is expected from the example at the same time that someone can run it
+and check for its validity, still changing and playing with the values.
+
+## How to play with
+
+1. Clone repo and enter the directory
+
+    git clone https://github.com/waxlab/alk.git alk
+    cd alk
+
+2. Choose the target Lua version you want to play with
+
+    luarocks init --lua-version 5.4
+
+3. Then you just need to pick the folder name under the `./src`
+and run it:
+
+    ./lua ./run.lua stack
+
+It is expected the code be compiled and returns no error. As you change
+the code, as every test should be in an `assert()` call any error
+will be shown on console.

alk-dev-1.rockspec

@@ -0,0 +1,23 @@
+package = "alk"
+version = "dev-1"
+source = {
+  url = "git+https://github.com/waxlab/alk",
+  tag = "latest"
+}
+description = {
+  homepage   = "https://codeberg.org/waxlab/alk",
+  license    = "MIT",
+  summary    = "Recipes on the Lua Alchemy",
+  maintainer = "Thadeu de Paula",
+  detailed   = "Lua documentation with examples",
+}
+
+dependencies = { "lua >= 5.1, < 5.5" }
+
+build = {
+  type = 'builtin',
+  modules = {
+    ["alk.stack"]   = "src/stack/ex.lua",
+    ["alk.stack.c"] = "src/stack/ex.c"
+  }
+}

run.lua

@@ -0,0 +1,13 @@
+#!/usr/bin/env lua
+if arg[1] and arg[1]:match("5%.") then
+  os.execute("luarocks --lua-version %q init"):format(arg[1])
+else
+  os.execute("./luarocks build")
+  os.execute(
+    ([[./lua -l %q]])
+    :format(
+      ([[alk.%s]])
+        :format(arg[1])
+    )
+  )
+end

src/stack/ex.c

@@ -0,0 +1,54 @@
+#include <lua.h>
+#include <lauxlib.h>
+
+/*
+--| lua_gettop(L) returns the top of stack index, i.e, stack size
+*/
+
+int table(lua_State *L) {
+  return 0;
+}
+
+
+int args(lua_State *L) {
+  lua_pushinteger(L, lua_gettop(L));
+  return 1;
+}
+
+/* In order to represent the real state of the stack on function
+** calling, we need to push the last first, as once pushed the
+** stack can be changed */
+int edges(lua_State *L) {
+  lua_pushvalue(L,-1);
+  lua_pushvalue(L,1);
+  return 2;
+}
+
+int returns(lua_State *L) {
+  int before, after;
+  before = lua_gettop(L);
+  lua_pushstring(L, "hi");
+  after = lua_gettop(L);
+  lua_pushinteger(L, before);
+  lua_pushinteger(L, after);
+  return 3;
+}
+
+
+int luaopen_alk_stack_c(lua_State *L) {
+
+  luaL_Reg module[] = {
+    { "args",    args    },
+    { "edges",   edges   },
+    { "returns", returns },
+    { "table",   table   },
+    { NULL,      NULL    }
+  };
+
+  #if ( LUA_VERSION_NUM < 502 )
+    luaL_register(L, "", module);
+  #else
+    luaL_newlib(L,module);
+  #endif
+  return 1;
+}

src/stack/ex.lua

@@ -0,0 +1,38 @@
+local stack = require "alk.stack.c"
+
+assert( stack.args("o") == 1 )
+assert( stack.args("o",10) == 2)
+assert( stack.args("o",nil,{"a",10,false}) == 3)
+
+
+-- The edges of stack.
+-- In a stack of one item, the first (1) and the last(-1) are the same.
+-- In a stack of two items the first (1) is the (-2) and the second is the (-1)
+do
+  -- stack:
+  -- | {} |  1  -1
+  local last, first = stack.edges({})
+  assert(first == last)
+
+  -- stack:
+  -- | a |  1  -2
+  -- | b |  2  -1
+  local a, b = {}, {}
+  local last, first = stack.edges(a, b)
+  assert( first == a and last == b )
+end
+
+-- To return the values of Lua the stack is changed
+do
+  local res, before, after = stack.returns();
+  assert(res == "hi", 0, 1)
+
+  res, before, after = stack.returns("a");
+  assert(res == "hi" and before == 1 and after == 2)
+
+  -- An interesting test... are so many arguments allowed?
+  res, before, after = stack.returns(1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6,7,8,9,0,"a","b","c","d","e","f")
+  assert(res == "hi" and before == 26 and after == 27)
+end
+
+