*Updated project and readme.

Author: paladin-t

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2020 - 2021 Tony Wang
+
+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

@@ -1,2 +1,134 @@
-# bitty.compiler_plugin
-A compiler plugin example for Bitty Engine.
+# Compiler plugin for Bitty Engine
+
+This repository demonstrates how to implement a custom compiler/transpiler plugin for [Bitty Engine](https://github.com/paladin-t/bitty) with a BF example.
+
+## Installing
+
+1. Clone or download this repository.
+
+2. Click "Project", "Browse Data Directory..." from the menu bar.
+
+![](imgs/browse.png)
+
+3. Ensure there is a "plugins" directory under that directory.
+
+4. Put the "plugin.bit" into the new created "plugins" directory. And name it properly.
+
+![](imgs/install.png)
+
+5. Reopen Bitty Engine.
+
+## Injecting
+
+1. Create a new asset, select the registered asset type.
+
+![](imgs/new_asset.png)
+
+2. Click "Install" to inject necessary assets to the target project.
+
+![](imgs/inject.png)
+
+![](imgs/injected.png)
+
+3. Write and run BF code.
+
+![](imgs/run.png)
+
+## Principles
+
+![](imgs/principles.png)
+
+Bitty Engine loads plugin to extend its features once it's installed. It loads a BF compiler in this example which can inject the compiler to a target project. And the injected compiler/transpiler runs as regular Bitty code that translates BF code to runnable Lua chunk.
+
+```lua
+require 'bf/compiler'               -- Require the compiler.
+
+local f = compile('hello world.bf') -- Compile something.
+f()                                 -- Run the compiled chunk.
+```
+
+## Write your own compiler plugin
+
+A compiler plugin contains three parts.
+
+### 1. Meta info
+
+Similar to regular Bitty projects, it has an "info.json", define it as you want.
+
+### 2. Main entry
+
+Bitty Engine doesn't run a plugin project directly, it must be installed before running. The execution entry is also named as "main.lua".
+
+But the entry functions are different from regular project. Eg.
+
+```lua
+-- Which assets are supposed to be injected from this plugin to target project.
+local assets = {
+  'bf/compiler.lua',
+  'bf/README.txt'
+}
+
+-- Tips and example code.
+local tips = 'Usage:\n  require \'bf/compiler\'\n  f = compile(\'source.bf\')\n  f()'
+local code = 'require \'bf/compiler\'\nf = compile(\'source.bf\')\nf()\n'
+
+-- Plugin entry, called to determine the usage of this plugin.
+function usage()
+  return { 'compiler' } -- This plugin is a compiler.
+end
+
+-- Plugin entry, called to determine the schema of this plugin.
+function schema()
+  return {
+    -- Common.
+    name = 'BF',      -- Asset name registered for this plugin.
+    extension = 'bf', -- Asset extension registered for this plugin.
+
+    -- List of string.
+    keywords = { },
+    identifiers = { },
+    quotes = { '\'', '"' },
+    -- String.
+    multiline_comment_start = nil,
+    multiline_comment_end = nil,
+    -- C++ regex.
+    comment_patterns = { '\\#.*' },
+    number_patterns = { },
+    identifier_patterns = { },
+    punctuation_patterns = { '[\\<\\>\\+\\-\\.\\,\\[\\]]' },
+    -- Boolean.
+    case_sensitive = true,
+    -- List of string.
+    assets = assets
+  }
+end
+
+-- Plugin entry, called to install necessary assets to your target project.
+function compiler()
+  print('Install BF compiler to the current project.')
+
+  waitbox('Installing')
+    :thus(function (rsp)
+      local install = function (name)
+        local data = Project.main:read(name)
+        data:poke(1)
+        Project.editing:write(name, data) -- Write into the target project.
+      end
+
+      for _, asset in ipairs(assets) do -- Install all necessary assets.
+        install(asset)
+      end
+
+      print('Done.')
+
+      msgbox(tips)
+        :thus(function ()
+          Platform.setClipboardText(code) -- Put example code to clipboard.
+        end)
+    end)
+end
+```
+
+### 3. Assets to be injected
+
+The plugin project also contains assets to be injected. See the plugin in this repository for details.

project.bit renamed to example.bit

@@ -1,11 +1,5 @@
 package:application/vnd.bitty-archive;
-data:text/lua;count=57;path=main.lua;
-require 'bf/compiler'
-
-f = compile('hello world.bf')
-f()
-
-data:text/lua;count=1486;path=bf/compiler.lua;
+data:text/lua;count=1632;path=bf/compiler.lua;
 --[[
 BF compiler for the Bitty Engine
 
@@ -48,14 +42,14 @@ function compile(asset)
 		if #ln > 0 then
 			local comment = ln:find('#')
 			if comment then
-				ln = ln:sub(1, comment - 1)
+				ln = ln:sub(1, comment - 1) -- Remove comment.
 			end
-			dst = dst .. ln
+			dst = dst .. ln                 -- Concat lines.
 		end
 	end
-	local full = interpreter .. 'interpret(\'' .. dst .. '\')'
+	local full = interpreter .. 'interpret(\'' .. dst .. '\')' -- Link the source code with the interpreter together.
 
-	return load(full)
+	return load(full) -- Return loaded and parsed Lua chunk.
 end
 
 data:text/txt;count=96;path=bf/README.txt;
@@ -66,18 +60,24 @@ Usage:
   f = compile('source.bf')
   f()
 
-data:binary/octet;count=124;path=hello world.bf;
-++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.>++.<<+++++++++++++++.>.++ #fasdf
-+.------.--------.>+.>.#adsg
-data:text/json;count=127;path=info.json;
+data:binary/octet;count=231;path=hello world.bf;
+++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.>++.<<+++++++++++++++.>.++ # The BF compiler supports new lines,
++.------.--------.>+.>.                                                                  # and comments.
+data:text/json;count=206;path=info.json;
 {
   "id": 0,
-  "title": "BF",
-  "description": "",
+  "title": "BF Example",
+  "description": "A BF example project.",
   "author": "Tony",
   "version": "1.0",
   "genre": "TUTORIAL",
-  "url": ""
+  "url": "https://github.com/paladin-t/bitty.compiler_plugin"
 }
 data:binary/octet;count=6;path=input.bf;
 ,.,.,.
+data:text/lua;count=183;path=main.lua;
+require 'bf/compiler'               -- Require the compiler.
+
+local f = compile('hello world.bf') -- Compile something.
+f()                                 -- Run the compiled chunk.
+

imgs/browse.png

@@ -1,5 +1,5 @@
 package:application/vnd.bitty-archive;
-data:text/lua;count=1331;path=main.lua;
+data:text/lua;count=1865;path=main.lua;
 --[[
 Plugin for the Bitty Engine
 
@@ -8,23 +8,27 @@ Copyright (C) 2020 - 2021 Tony Wang, all rights reserved
 Homepage: https://paladin-t.github.io/bitty/
 ]]
 
+-- Which assets are supposed to be injected from this plugin to target project.
 local assets = {
 	'bf/compiler.lua',
 	'bf/README.txt'
 }
 
+-- Tips and example code.
 local tips = 'Usage:\n  require \'bf/compiler\'\n  f = compile(\'source.bf\')\n  f()'
 local code = 'require \'bf/compiler\'\nf = compile(\'source.bf\')\nf()\n'
 
+-- Plugin entry, called to determine the usage of this plugin.
 function usage()
-	return { 'compiler' }
+	return { 'compiler' } -- This plugin is a compiler.
 end
 
+-- Plugin entry, called to determine the schema of this plugin.
 function schema()
 	return {
 		-- Common.
-		name = 'BF',
-		extension = 'bf',
+		name = 'BF',      -- Asset name registered for this plugin.
+		extension = 'bf', -- Asset extension registered for this plugin.
 
 		-- List of string.
 		keywords = { },
@@ -45,6 +49,7 @@ function schema()
 	}
 end
 
+-- Plugin entry, called to install necessary assets to your target project.
 function compiler()
 	print('Install BF compiler to the current project.')
 
@@ -53,23 +58,23 @@ function compiler()
 			local install = function (name)
 				local data = Project.main:read(name)
 				data:poke(1)
-				Project.editing:write(name, data)
+				Project.editing:write(name, data) -- Write into the target project.
 			end
 
-			for _, asset in ipairs(assets) do
+			for _, asset in ipairs(assets) do -- Install all necessary assets.
 				install(asset)
 			end
 
 			print('Done.')
 
 			msgbox(tips)
 				:thus(function ()
-					Platform.setClipboardText(code)
+					Platform.setClipboardText(code) -- Put example code to clipboard.
 				end)
 		end)
 end
 
-data:text/lua;count=1568;path=bf/compiler.lua;
+data:text/lua;count=1632;path=bf/compiler.lua;
 --[[
 BF compiler for the Bitty Engine
 
@@ -114,12 +119,12 @@ function compile(asset)
 			if comment then
 				ln = ln:sub(1, comment - 1) -- Remove comment.
 			end
-			dst = dst .. ln -- Concat lines.
+			dst = dst .. ln                 -- Concat lines.
 		end
 	end
-	local full = interpreter .. 'interpret(\'' .. dst .. '\')' -- Link the source code into the interpreter.
+	local full = interpreter .. 'interpret(\'' .. dst .. '\')' -- Link the source code with the interpreter together.
 
-	return load(full)
+	return load(full) -- Return loaded and parsed Lua chunk.
 end
 
 data:text/txt;count=96;path=bf/README.txt;
@@ -130,13 +135,13 @@ Usage:
   f = compile('source.bf')
   f()
 
-data:text/json;count=161;path=info.json;
+data:text/json;count=211;path=info.json;
 {
   "id": 0,
   "title": "BF Compiler",
   "description": "Compile BF source to Lua.",
   "author": "Tony",
   "version": "1.0",
   "genre": "COMPILER",
-  "url": ""
+  "url": "https://github.com/paladin-t/bitty.compiler_plugin"
 }

imgs/inject.png

@@ -40,12 +40,12 @@ function compile(asset)
 		if #ln > 0 then
 			local comment = ln:find('#')
 			if comment then
-				ln = ln:sub(1, comment - 1)
+				ln = ln:sub(1, comment - 1) -- Remove comment.
 			end
-			dst = dst .. ln
+			dst = dst .. ln                 -- Concat lines.
 		end
 	end
-	local full = interpreter .. 'interpret(\'' .. dst .. '\')'
+	local full = interpreter .. 'interpret(\'' .. dst .. '\')' -- Link the source code with the interpreter together.
 
-	return load(full)
+	return load(full) -- Return loaded and parsed Lua chunk.
 end

imgs/injected.png

@@ -0,0 +1,2 @@
+++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.>++.<<+++++++++++++++.>.++ # The BF compiler supports new lines,
++.------.--------.>+.>.                                                                  # and comments.

imgs/install.png

@@ -0,0 +1,9 @@
+{
+  "id": 0,
+  "title": "BF Example",
+  "description": "A BF example project.",
+  "author": "Tony",
+  "version": "1.0",
+  "genre": "TUTORIAL",
+  "url": "https://github.com/paladin-t/bitty.compiler_plugin"
+}

imgs/new_asset.png

@@ -0,0 +1,4 @@
+require 'bf/compiler'               -- Require the compiler.
+
+local f = compile('hello world.bf') -- Compile something.
+f()                                 -- Run the compiled chunk.

imgs/principles.png

@@ -42,10 +42,10 @@ function compile(asset)
 			if comment then
 				ln = ln:sub(1, comment - 1) -- Remove comment.
 			end
-			dst = dst .. ln -- Concat lines.
+			dst = dst .. ln                 -- Concat lines.
 		end
 	end
-	local full = interpreter .. 'interpret(\'' .. dst .. '\')' -- Link the source code into the interpreter.
+	local full = interpreter .. 'interpret(\'' .. dst .. '\')' -- Link the source code with the interpreter together.
 
-	return load(full)
+	return load(full) -- Return loaded and parsed Lua chunk.
 end

imgs/run.png

@@ -5,5 +5,5 @@
   "author": "Tony",
   "version": "1.0",
   "genre": "COMPILER",
-  "url": ""
+  "url": "https://github.com/paladin-t/bitty.compiler_plugin"
 }