Refactor (#102)

* Refactor Code

* Doc: Look & feel changes, and doc comment updates by trappi_stone.

* Doc: Sidebar navigation alphabetize

* Doc: Show module name in the title tab

* Moved queue to stdlib/queue/queue

* Moved: stdlib/string, moved to stdlib/utils/string

* Moved: stdlib/table, moved to stdlib/utils/table

* Moved: stdlib/trains, moved to stdlib/event/trains

* Deprecated: stdlib/core, functions are available in stdlib/game

* Deprecated: *.to_collosion_area, update scripts to use entity.bounding_box

* Deprecated: stdlib/area/area and stdlib/area/position *.to_table, see *.new

* Add: stdlib/event/opened

* Add: stdlib/game get_player and get_force

* Add: stdlib/Color.from_rgb

* Add: stdlib/event/player

* Add: stdlib/event/force

* Add: stdlib/utils/console

* Add table_size to table.size

* Changed: stdlib/area/area uses metamethods and can be used as a class

* Changed: stdlib/position/position uses metamethods and can be used as a class

* Note: stdlib/area and stdlib/position now modify the tables in place, use *.copy() to create a new copy

* Fix: *.dispatch() correctly adds the tick to the event if missing

* Fix: event errors are logged to factorio_current.log 

* Fix: Removed unneeded _G references

* Fix: Many modules now have write protections

* Fix: defines.color can now be iterated.

* Tests: Added and updated many tests - trappi_stone

* Tests: Now pass linter checks

* Repo: Move deprecated files into a seperate folder and merge in during a release

* Repo: Prep for inclusion as mod

* Many updates

Add: Area.compare

Add: Area.__len operator to return the area size

Chang: Area.__eq to compare size

Add: Area.__lt to compare size

Fix: Area.normalize to return itself

Fix: Area metatable comparison

Doc: Some doc changes

Add: Game._concat for use in __concat metamethods

Add: Game._rawstring to get the rawstring value on tables with
__tostring

Fix: Queue.__len

Deprecate: Entity.to_collosion_area

Issue: game.print(area) doesn't work correctly

Change: Event.register will move duplicated registartions to the bottom
and print to log and added test for it.

* Tests: Add World and world_spec example Creating test worlds and players has never been this easy!

.gitignore

@@ -1,3 +1,10 @@
+# Exclude the build directories
 build
 build/*
-factorio_mods
+.build
+
+# Temporarily Exclude mod file changes
+mod/*
+!mod/info.json
+
+.luacompleterc

Makefile

@@ -1,39 +1,66 @@
-OUTPUT_DIR := build
+PACKAGE_NAME := $(shell cat 'mod/info.json'|jq -r .name)
+VERSION_STRING := $(shell cat 'mod/info.json'|jq -r .version)
+OUTPUT_DIR := $(PACKAGE_NAME)
+OUTPUT_NAME := $(PACKAGE_NAME)_$(VERSION_STRING)
+BUILD_DIR := build
 
-PKG_COPY := stdlib/
+FILES := $(shell find . -iname '*.json' -type f -path "./stdlib/*") $(shell find . -iname '*.lua' -type f -path "./stdlib/*")
+DEP_FILES := $(shell find . -iname '*.lua' -type f -path "./deprecated/*")
+MOD_FILES := $(shell find . -iname '*' -type f -path "./mod/*")
 
-FILES := $(shell find . -iname '*.lua' -type f -not -path "./$(OUTPUT_DIR)/*")
+all: clean check test package mod-files deprecated ldoc luacheck release
 
-all: clean check test package ldoc luacheck
+nodeps: clean check test package mod-files ldoc luacheck release
 
-doc: clean package ldoc
+mod: clean test package mod-files
 
-package-copy: $(FILES)
- @echo 'Copying Files'
- @mkdir -p $(OUTPUT_DIR)
- @cp -r $(PKG_COPY) $(OUTPUT_DIR)/$(PKG_COPY)
+nochecks: clean package deprecated release
 
-package: package-copy $(FILES)
+doc: clean package deprecated ldoc
+
+clean:
+ @rm -rf $(BUILD_DIR)
 
 check:
  @echo 'Checking lua files for errors'
- @set -e; for file in $$(find . -iname '*.lua' -type f -not -path "./$(OUTPUT_DIR)/*"); do echo "Checking syntax: $$file" ; luac -p $$file; done;
+ @set -e; for file in $$(find . -iname '*.lua' -type f -not -path "./$(BUILD_DIR)/*"); do echo "Checking syntax: $$file" ; luac -p $$file; done;
 
-ldoc:
- @echo 'Auto Generating with ldoc'
- @mkdir -p $(OUTPUT_DIR)/doc
- @cp README.md $(OUTPUT_DIR)/doc/readme.md
- @cp -r examples/ $(OUTPUT_DIR)/doc/examples/
- @cd $(OUTPUT_DIR) && ldoc -p "Factorio Stdlib" -t "Factorio Stdlib" -c ../doc/config.ld -X -s ../doc $(PKG_COPY)/
+test:
+ @echo 'Running tests'
+ @busted
 
+package: $(FILES)
+ @echo 'Copying files'
+ @mkdir -p $(BUILD_DIR)/$(OUTPUT_NAME)
+ @cp -r $(PACKAGE_NAME) $(BUILD_DIR)/$(OUTPUT_NAME)/$(PACKAGE_NAME)
+ @cp README.md $(BUILD_DIR)/$(OUTPUT_NAME)/README.md
+ @cp LICENSE $(BUILD_DIR)/$(OUTPUT_NAME)/LICENSE.md
+ @cp CHANGELOG.md $(BUILD_DIR)/$(OUTPUT_NAME)/CHANGELOG.md
 
-test:
- busted
+deprecated: $(DEP_FILES)
+ @echo 'Copying deprecated files'
+ @cp -rPn ./deprecated/* $(BUILD_DIR)/$(OUTPUT_NAME)/$(PACKAGE_NAME)
+
+mod-files: $(MOD_FILES)
+ @echo 'Copying test mod files'
+ @cp -PRn ./mod/* $(BUILD_DIR)/$(OUTPUT_NAME)/
+
+ldoc:
+ @echo 'Auto Generating with ldoc'
+ @mkdir -p $(BUILD_DIR)/doc
+ @cp README.md $(BUILD_DIR)/doc/readme.md
+ @cp doc/spectre.min.css $(BUILD_DIR)/doc/spectre.min.css
+ @cp doc/spectre-icons.min.css $(BUILD_DIR)/doc/spectre-icons.min.css
+ @cp -r examples/ $(BUILD_DIR)/doc/examples/
+ @cd $(BUILD_DIR) && ldoc -c ../doc/config.ld -l ../doc -s ../doc $(OUTPUT_NAME)/$(PACKAGE_NAME)
 
 luacheck:
  @echo 'Running luacheck on build directory'
- @wget -q --no-check-certificate -O $(OUTPUT_DIR)/.luacheckrc https://raw.githubusercontent.com/Nexela/Factorio-luacheckrc/master/.luacheckrc
- @cd $(OUTPUT_DIR)/$(PKG_COPY) && luacheck .
+ @luacheck --version
+ @wget -q --no-check-certificate -O $(BUILD_DIR)/.luacheckrc https://raw.githubusercontent.com/Nexela/Factorio-luacheckrc/master/.luacheckrc
+ @cd $(BUILD_DIR)/$(OUTPUT_NAME) && luacheck .
 
-clean:
- @rm -rf $(OUTPUT_DIR)/
+release:
+ @echo 'Making Release'
+ @cd $(BUILD_DIR) && zip -rq $(OUTPUT_NAME).zip $(OUTPUT_NAME)
+ @echo $(OUTPUT_NAME).zip ready

circle.yml

@@ -1,7 +1,7 @@
 dependencies:
  pre:
  - sudo apt-get update
- - sudo apt-get install build-essential curl wget unzip git openssl lua5.2 lua5.2-dev libev-dev -y
+ - sudo apt-get install build-essential curl wget unzip git openssl lua5.2 lua5.2-dev libev-dev libjs-jquery -y
  - wget -O /tmp/luarocks.zip https://github.com/keplerproject/luarocks/archive/v2.3.0.zip
  - unzip /tmp/luarocks.zip -d /tmp
  - (cd /tmp/luarocks-2.3.0 && ./configure --prefix=/usr --lua-version=5.2)

stdlib/core.lua → deprecated/core.lua

@@ -1,4 +1,4 @@
---- Core module
+--- Deprecated see @{Game}
 -- @module Core
 
 Core = {} --luacheck: allow defined top

deprecated/string.lua

@@ -0,0 +1,2 @@
+--deprecated: update require to stdlib/utils/string
+require 'stdlib/util/string'

deprecated/table.lua

@@ -0,0 +1,2 @@
+--deprecated: update require to stdlib/utils/table
+require 'stdlib/utils/table'

deprecated/trains/trains.lua

@@ -0,0 +1,5 @@
+-- Deprecated, This file will be removed in a future release
+-- File has been moved to stdlib/event/trains
+-- Update all stdlib.gui requires to stdlib.event.trains
+
+return require 'stdlib.event.trains'

doc/config.ld

@@ -1,88 +1,93 @@
 --luacheck: ignore
-project = 'Factorio Stdlib'
-description = 'Factorio Standard Library'
+project = "Factorio Stdlib"
+title = "Factorio Stdlib"
+description = "Factorio Standard Library"
 full_description = [[
-The Factorio Standard Library aims to extend the Factorio Lua api with well-tested, documented, and easy-to-use functions to make modding easier.
+ The Factorio Standard Library aims to extend the Factorio Lua API with well-tested, documented, and easy-to-use functions to make modding easier.
 ]]
-
---will pay for
-format = 'markdown'
-readme = '../build/doc/readme.md'
-
+no_lua_ref = true
 convert_opt = true
+sort = true
+no_return_or_parms = false
+not_luadoc = true
 merge = false
+backtick_references = false
+format = "discount"
+template_escape = ">"
+dir = "../build/doc"
+examples = {"../build/doc/examples"}
+topics = {"../build/doc/readme.md"}
 
-alias('p','tparam')
-alias('r','treturn')
+new_type("event", "Events", false, "Event Parameters")
 
-examples = {'../build/doc/examples'}
+local api_url = "http:https://lua-api.factorio.com/latest/%s.html%s"
 
---Shortcut for referring to concept targets in tparam and treturn
-local Concepts = {
- ['Position'] = true,
- ['BoundingBox'] = true,
- ['Color'] = true,
- ['Vector'] = true,
- ['SimpleItemStack'] = true
-}
-local api_url = 'http:https://lua-api.factorio.com/latest/%s.html%s'
-custom_see_handler('^Lua([%w_]+)(%.?[%w_]*)$',
+custom_see_handler("^Lua([%w_]*)%.?([%.?[%w_]*]*)$",
  function(name, section)
- local url
- if Concepts[name] then
- local header = 'Concepts'
- section = '#'..name
- url = api_url:format(header, section)
- else
- local header = 'Lua'..name
- name = #section > 0 and name..section or name
- section = (#section > 0 and ('#'..header..section)) or ''
- url = api_url:format(header, section)
- end
- return name, url
+ local link_txt = "Lua" .. name .. (#section > 0 and "." .. section or "")
+ local link_url = api_url:format("Lua" .. name, #section > 0 and "#" .. link_txt or "")
+ return link_txt, link_url
  end
 )
--- Factorio name: Concepts.Position expands to Concept Position
--- useful for @see refrences
-custom_see_handler('^Concepts%.?([%w_%.]*)$',
+
+custom_see_handler("^Concepts%.([%.?[%w_]*]*)$",
  function(section)
- local header, name, url
- header = 'Concepts'
- name = header ..' '..section
- url = api_url:format(header, '#'..section)
- return name, url
+ local link_txt = "Concepts." .. section
+ local link_url = api_url:format("Concepts", #section > 0 and "#" .. section or "")
+ return link_txt, link_url
+ end
+)
+
+custom_see_handler("^defines%.?([%.?[%w_]*]*)$",
+ function(section)
+ local link_txt = "defines." .. section
+ local link_url
+ if section == "color" or section == "time" then
+ link_url = "../modules/"..link_txt..".html"
+ else
+ link_url = api_url:format("defines", #section > 0 and "#" .. link_txt or "")
+ end
+ return link_txt, link_url
  end
 )
-custom_see_handler('^defines(%.?[%w_%.]*)$',
+
+custom_see_handler("^Common%.([%.?[%w_]*]*)$",
  function(section)
- local name, url
- name = 'defines'..section
- url = api_url:format('defines', '#'..name)
- return name, url
+ local link_txt = "Common." .. section
+ local link_url = api_url:format("Common", #section > 0 and "#" .. link_txt or "")
+ return link_txt, link_url
  end
 )
 
-local wikipat = 'https://en.wikipedia.org/wiki/%s'
-custom_see_handler('^wiki (.+)',
+local wikipat = "https://en.wikipedia.org/wiki/%s"
+custom_see_handler("^wiki (.+)",
  function(name)
  local url = wikipat:format(name)
  return name, url
  end
 )
 
---https://forums.factorio.com/viewtopic.php?t=32039#p202158
-custom_see_handler('^(http[s]?%:%/%/.-) (.+)$',
+-- https://forums.factorio.com/viewtopic.php?t=32039#p202158
+custom_see_handler("^(http[s]?%:%/%/.-) (.+)$",
  function(url, name)
  return name, url
  end
 )
 
--- -- define a @callback tag:
--- custom_tags = { { 'callback', hidden = true } }
--- -- show a label beside functions tagged with @callback.
--- custom_display_name_handler = function(item, default_handler)
--- if item.tags.callback then
--- return item.name .. ' [callback]'
--- end
--- return default_handler(item)
--- end
+local lua_url = "https://www.lua.org/pil/%s.html%s"
+
+custom_see_handler("^boolean$", function() return "boolean", api_url:format("Builtin-Types", "#boolean") end)
+custom_see_handler("^int$", function() return "int", api_url:format("Builtin-Types", "#int") end)
+custom_see_handler("^uint$", function() return "uint", api_url:format("Builtin-Types", "#uint") end)
+custom_see_handler("^uint8$", function() return "uint8", api_url:format("Builtin-Types", "#uint8") end)
+custom_see_handler("^uint64$", function() return "uint64", api_url:format("Builtin-Types", "#uint64") end)
+custom_see_handler("^string$", function() return "string", api_url:format("Builtin-Types", "#string") end)
+custom_see_handler("^float$", function() return "float", api_url:format("Builtin-Types", "#float") end)
+custom_see_handler("^double$", function() return "double", api_url:format("Builtin-Types", "#double") end)
+custom_see_handler("^nil$", function() return "nil", lua_url:format("2.1", "") end)
+custom_see_handler("^number$", function() return "number", lua_url:format("2.3", "") end)
+custom_see_handler("^table$", function() return "table", lua_url:format("2.5", "") end)
+custom_see_handler("^function$", function() return "function", lua_url:format("2.6", "") end)
+custom_see_handler("^userdata$", function() return "userdata", lua_url:format("2.7", "") end)
+custom_see_handler("^thread$", function() return "thread", lua_url:format("9", "#CoroutineSec") end)
+custom_see_handler("^array$", function() return "array", lua_url:format("11.1", "") end)