diff --git a/.gitignore b/.gitignore index 8df202e..d8cff95 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ *.mermaid.* - +docs/ldoc # Created by https://www.gitignore.io/api/linux,lua diff --git a/.gitmodules b/.gitmodules index cd9ad4e..267dfbc 100644 --- a/.gitmodules +++ b/.gitmodules @@ -3,7 +3,7 @@ url = https://github.com/rubenwardy/ChatCmdBuilder [submodule "mods/areas"] path = mods/areas - url = https://github.com/rubenwardy/areas + url = https://github.com/CapitalismGame/areas [submodule "mods/content/oil"] path = mods/content/oil url = https://github.com/rubenwardy/oil diff --git a/docs/config.ld b/docs/config.ld new file mode 100644 index 0000000..55c610b --- /dev/null +++ b/docs/config.ld @@ -0,0 +1,15 @@ +project = "Capitalism Game" +title = "Capitalism Game Reference" +format = "discount" +backtick_references = true +readme = "docs/dev_intro.md" +--boilerplate = true +file = {'mods', exclude = {'mods/mtg'}} +template = "docs/template/" + +tparam_alias("pos", "table") +tparam_alias("owner", "string") +tparam_alias("player", "string") +tparam_alias("company", "company.Company") +tparam_alias("account", "banking.Account") +tparam_alias("shop", "shop.Shop") diff --git a/docs/gen.sh b/docs/gen.sh new file mode 100755 index 0000000..5f67cf4 --- /dev/null +++ b/docs/gen.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +ldoc mods/ -c docs/config.ld -d docs/ldoc -Mi diff --git a/docs/template/ldoc.ltp b/docs/template/ldoc.ltp new file mode 100644 index 0000000..f27f209 --- /dev/null +++ b/docs/template/ldoc.ltp @@ -0,0 +1,316 @@ + + + + + $(ldoc.title) + +# if ldoc.custom_css then -- add custom CSS file if configured. + +# end + + + +
+ +
+ +
+
+
+ + +
+ +# local no_spaces = ldoc.no_spaces +# local use_li = ldoc.use_li +# local display_name = ldoc.display_name +# local iter = ldoc.modules.iter +# local function M(txt,item) return ldoc.markup(txt,item,ldoc.plain) end +# local nowrap = ldoc.wrap and '' or 'nowrap' + + + + + +
+ +# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries + $(ldoc.body) +# elseif module then -- module documentation +

$(ldoc.module_typename(module)) $(module.name)

+

$(M(module.summary,module))

+

$(M(module.description,module))

+# if module.tags.include then + $(M(ldoc.include_file(module.tags.include))) +# end +# if module.see then +# local li,il = use_li(module.see) +

See also:

+
    +# for see in iter(module.see) do + $(li)$(see.label)$(il) +# end -- for +
+# end -- if see +# if module.usage then +# local li,il = use_li(module.usage) +

Usage:

+
    +# for usage in iter(module.usage) do + $(li)
    $(ldoc.escape(usage))
    $(il) +# end -- for +
+# end -- if usage +# if module.info then +

Info:

+
    +# for tag, value in module.info:iter() do +
  • $(tag): $(M(value,module))
    • +# end +
+# end -- if module.info + + +# if not ldoc.no_summary then +# -- bang out the tables of item types for this module (e.g Functions, Tables, etc) +# for kind,items in module.kinds() do +

$(kind)

+ +# for item in items() do + + + + +# end -- for items +
$(display_name(item))$(M(item.summary,item))
+#end -- for kinds + +
+
+ +#end -- if not no_summary + +# --- currently works for both Functions and Tables. The params field either contains +# --- function parameters or table fields. +# local show_return = not ldoc.no_return_or_parms +# local show_parms = show_return +# for kind, items in module.kinds() do +# local kitem = module.kinds:get_item(kind) +# local has_description = kitem and ldoc.descript(kitem) ~= "" +

$(kind)

+ $(M(module.kinds:get_section_description(kind),nil)) +# if kitem then +# if has_description then +
+ $(M(ldoc.descript(kitem),kitem)) +
+# end +# if kitem.usage then +

Usage:

+ 
$(ldoc.prettify(kitem.usage[1]))
+# end +# end +
+# for item in items() do +
+ + $(display_name(item)) +# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then + line $(item.lineno) +# end +
+
+ $(M(ldoc.descript(item),item)) + +# if ldoc.custom_tags then +# for custom in iter(ldoc.custom_tags) do +# local tag = item.tags[custom[1]] +# if tag and not custom.hidden then +# local li,il = use_li(tag) +

$(custom.title or custom[1]):

+
    +# for value in iter(tag) do + $(li)$(custom.format and custom.format(value) or M(value))$(il) +# end -- for +# end -- if tag +
+# end -- iter tags +# end + +# if show_parms and item.params and #item.params > 0 then +# local subnames = module.kinds:type_of(item).subnames +# if subnames then +

$(subnames):

+# end +
    +# for parm in iter(item.params) do +# local param,sublist = item:subparam(parm) +# if sublist then +
  • $(sublist)$(M(item.params.map[sublist],item)) +
      +# end +# for p in iter(param) do +# local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p) +
    • $(name) +# if tp ~= '' then + $(tp) +# end + $(M(item.params.map[p],item)) +# if def == true then + (optional) +# elseif def then + (default $(def)) +# end +# if item:readonly(p) then + readonly +# end +
      • +# end +# if sublist then +
    +# end +# end -- for +
+# end -- if params + +# if show_return and item.retgroups then local groups = item.retgroups +

Returns:

+# for i,group in ldoc.ipairs(groups) do local li,il = use_li(group) +
    +# for r in group:iter() do local type, ctypes = item:return_type(r); local rt = ldoc.typename(type) + $(li) +# if rt ~= '' then + $(rt) +# end + $(M(r.text,item))$(il) +# if ctypes then +
      +# for c in ctypes:iter() do +
    • $(c.name) + $(ldoc.typename(c.type)) + $(M(c.comment,item))
      • +# end +
    +# end -- if ctypes +# end -- for r +
+# if i < #groups then +

Or

+# end +# end -- for group +# end -- if returns + +# if show_return and item.raise then +

Raises:

+ $(M(item.raise,item)) +# end + +# if item.see then +# local li,il = use_li(item.see) +

See also:

+
    +# for see in iter(item.see) do + $(li)$(see.label)$(il) +# end -- for +
+# end -- if see + +# if item.usage then +# local li,il = use_li(item.usage) +

Usage:

+
    +# for usage in iter(item.usage) do + $(li)
    $(ldoc.prettify(usage))
    $(il) +# end -- for +
+# end -- if usage + +
+# end -- for items +
+# end -- for kinds + +# else -- if module; project-level contents + +# if ldoc.description then +

$(M(ldoc.description,nil))

+# end +# if ldoc.full_description then +

$(M(ldoc.full_description,nil))

+# end + +# for kind, mods in ldoc.kinds() do +

$(kind)

+# kind = kind:lower() + +# for m in mods() do + + + + +# end -- for modules +
$(m.name)$(M(ldoc.strip_header(m.summary),m))
+# end -- for kinds +# end -- if module + +
+
+
+generated by LDoc $(ldoc.version) +Last updated $(ldoc.updatetime) +
+
+ + diff --git a/mods/capitalism/audit/init.lua b/mods/capitalism/audit/init.lua index 9d6a289..1475895 100644 --- a/mods/capitalism/audit/init.lua +++ b/mods/capitalism/audit/init.lua @@ -1,8 +1,26 @@ +--- Allows actions to be audited by companies +-- +-- @module audit + +--- audit table audit = {} +--- Creates an `Auditor` object. +-- +-- @function __call +-- @string area Area name +-- @usage local adt = audit("company") +--adt:pos(username, comp, message) function audit.make(_, area) local ret = {} + --- @type Auditor + + --- Log a message + -- @function Auditor:post + -- @string username + -- @tparam company.Company|string comp + -- @string message function ret:post(username, comp, message) local cname = comp if type(cname) ~= "string" then diff --git a/mods/capitalism/banking/account.lua b/mods/capitalism/banking/account.lua index faf0a49..f3f8fcd 100644 --- a/mods/capitalism/banking/account.lua +++ b/mods/capitalism/banking/account.lua @@ -1,6 +1,18 @@ +--- Introduces bank accounts and transactions. +-- @module banking + +--- Account +-- +-- Class which represents a bank account +-- @type Account local Account = {} banking.Account = Account + +--- Constructor +-- +-- @param obj A table to construct an object on top of +-- @treturn banking.Account function Account:new(obj) obj = obj or {} setmetatable(obj, self) @@ -11,6 +23,10 @@ function Account:new(obj) return obj end + +--- Export to Lua table +-- +-- @treturn table function Account:to_table() return { owner = self.owner, @@ -19,6 +35,11 @@ function Account:to_table() } end + +--- Import from Lua table +-- +-- @tparam table t +-- @treturn bool true for success function Account:from_table(t) self.owner = t.owner self.balance = t.balance @@ -29,6 +50,13 @@ function Account:from_table(t) type(self.ledger) == "table" end + +--- Withdraw from account +-- +-- @int amount +-- @string to target account +-- @string reason Transaction message +-- @treturn bool Returns false on failure function Account:withdraw(amount, to, reason) assert(amount > 0) @@ -40,7 +68,13 @@ function Account:withdraw(amount, to, reason) return true end -function Account:deposit(amount, to, reason) + +--- Deposit into account +-- +-- @int amount +-- @string from from account +-- @string reason Transaction message +function Account:deposit(amount, from, reason) assert(amount > 0) self.balance = self.balance + amount diff --git a/mods/capitalism/banking/api.lua b/mods/capitalism/banking/api.lua index 89f3855..adcd611 100644 --- a/mods/capitalism/banking/api.lua +++ b/mods/capitalism/banking/api.lua @@ -1,8 +1,16 @@ +--- +-- @module banking + banking._accounts = {} banking._account_by_owner = {} local adt = audit("banking") + +--- Gets the balance for a particular account +-- +-- @string owner Account owner +-- @treturn int function banking.get_balance(owner) if type(owner) == "table" then owner = owner.name @@ -14,6 +22,9 @@ function banking.get_balance(owner) return acc.balance end + +--- Adds an account to the local cache +-- @account acc function banking.add_account(acc) assert(not banking._account_by_owner[acc.owner]) @@ -24,12 +35,27 @@ function banking.add_account(acc) return acc end + +--- Gets account by owner name +-- +-- @owner owner +-- @treturn banking.Account function banking.get_by_owner(owner) assert(type(owner) == "string") return banking._account_by_owner[owner] end + +--- Transfers money between accounts, with permission checking +-- +-- @string actor User requesting this transfer +-- @string from From account +-- @string to Target account +-- @int amount +-- @string reason Transaction reason +-- @treturn true +-- @error Error message function banking.transfer(actor, from, to, amount, reason) assert(type(actor) == "string") assert(type(from) == "string") diff --git a/mods/capitalism/banking/init.lua b/mods/capitalism/banking/init.lua index 4273429..62f52aa 100644 --- a/mods/capitalism/banking/init.lua +++ b/mods/capitalism/banking/init.lua @@ -1,3 +1,7 @@ +--- +-- @module banking + +--- banking table banking = {} print("[banking] loading...") diff --git a/mods/capitalism/company/api.lua b/mods/capitalism/company/api.lua index 9453fec..b83ed70 100644 --- a/mods/capitalism/company/api.lua +++ b/mods/capitalism/company/api.lua @@ -1,3 +1,8 @@ +--- Introduces the concept of companies and the relationship between +-- companies and players. It adds permissions, but does not add stocks or shares. +-- +-- @module company + _.extend(company, { _companies = {}, _companies_by_name = {}, @@ -8,16 +13,28 @@ local adt = audit("company") local player_exists = minetest and minetest.player_exists or function() return true end + +--- Get a company by its name. +-- Company names are always in the form "c:[a-z-_]+" +-- @treturn company.Company function company.get_by_name(name) assert(type(name) == "string") return company._companies_by_name[name:lower()] end + +--- Verifies where a given string is a valid company name +-- @treturn bool function company.check_name(name) return ("^(c:[a-z]+)$"):match(name) end + +--- Creates a new company from a company reference +-- +-- @tparam company.Company obj +-- @treturn bool function company.create(obj) assert(type(obj) == "table") assert(obj.get_ownership) @@ -35,6 +52,13 @@ function company.create(obj) return true end + +--- Adds a company to in-memory store. +-- +-- Called by load and create. +-- +-- @tparam company.Company obj +-- @treturn bool function company.add(obj) assert(type(obj) == "table") assert(obj.get_ownership) @@ -56,6 +80,14 @@ function company.add(obj) return true end + +--- Set the active company for a player +-- +-- Performs permission checks. +-- +-- @string pname +-- @tparam company.Company|string comp +-- @treturn bool function company.set_active(pname, comp) assert(type(pname) == "string") assert(player_exists(pname)) @@ -76,6 +108,10 @@ function company.set_active(pname, comp) end end +--- Get active company for player name +-- +-- @string pname +-- @treturn ?company.Company function company.get_active(pname) assert(type(pname) == "string") assert(player_exists(pname)) @@ -84,6 +120,18 @@ function company.get_active(pname) return name and company.get_by_name(name) or nil end + +--- Check whether a player has a certain permission for a company +-- +-- Calling with a nil or nonexistent company will always result in +-- a return value of false +-- +-- @see company.permissions +-- @string pname the username +-- @tparam ?string cname +-- @string permission permission name, string +-- @tparam ?table meta Metadata about this request +-- @treturn bool function company.check_perm(pname, cname, permission, meta) assert(type(pname) == "string") assert(player_exists(pname)) @@ -104,6 +152,12 @@ function company.check_perm(pname, cname, permission, meta) return comp:check_perm(pname, permission, meta) end + +--- Get active company for player name, +-- or send chat message if no active companies. +-- +-- @string pname +-- @treturn ?company.Company function company.get_active_or_msg(pname) assert(type(pname) == "string") assert(player_exists(pname)) @@ -118,6 +172,10 @@ function company.get_active_or_msg(pname) end end + +--- List companies player is a member or CEO of +-- @string pname +-- @treturn [company.Company] function company.get_companies_for_player(pname) assert(type(pname) == "string") assert(player_exists(pname)) @@ -131,6 +189,16 @@ function company.get_companies_for_player(pname) return comps end + +--- Set the permissions for a particular member on a company +-- +-- @tparam company.Company comp +-- @string actor The player which is performing this action +-- @string target The member which is having their perms set +-- @string permission Permission name +-- @bool is_grant Whether the permission should be added or taken away +-- @treturn true +-- @error string Error message function company.set_perms(comp, actor, target, permission, is_grant) if not comp:check_perm(actor, "MANAGE_MEMBERS", { action = "add", name = "username" }) then @@ -182,14 +250,27 @@ function company.register_on_create(func) table.insert(company.registered_on_creates, func) end + +--- @see company.register_panel company.registered_panels = {} + + +--- Register a panel, shown as colored boxes on the Company GUI +-- @tparam table def function company.register_panel(def) assert(type(def) == "table") table.insert(company.registered_panels, def) end + +---@see company.register_snippet company.registered_snippets = {} + + +--- Register a snippet to go on company switchers +-- @string name +-- @tparam function func function company.register_snippet(name, func) assert(type(name) == "string") assert(type(func) == "function") @@ -198,6 +279,7 @@ function company.register_snippet(name, func) company.registered_snippets[name] = func end + -- Minetest won't be available in tests if minetest then local storage = minetest.get_mod_storage() diff --git a/mods/capitalism/company/company.lua b/mods/capitalism/company/company.lua index 0087104..6122f02 100644 --- a/mods/capitalism/company/company.lua +++ b/mods/capitalism/company/company.lua @@ -1,6 +1,19 @@ +--- +-- @module company + +--- Company +-- +-- Class which represents a company or government entity. +-- @type Company local Company = {} + company.Company = Company + +--- Constructor +-- +-- @param obj A table to construct an object on top of +-- @treturn company.Company function Company:new(obj) obj = obj or {} setmetatable(obj, self) @@ -10,6 +23,10 @@ function Company:new(obj) return obj end + +--- Export to Lua table +-- +-- @treturn table function Company:to_table() assert(self.name:sub(1, 2) == "c:") return { @@ -20,6 +37,11 @@ function Company:to_table() } end + +--- Import from Lua table +-- +-- @tparam table t +-- @treturn bool true on success, false on failure function Company:from_table(t) self.title = t.title self.name = t.name @@ -31,6 +53,10 @@ function Company:from_table(t) return self.name ~= nil and self.ceo ~= nil and type(self.members) == "table" end + +--- Calculate an appropriate name from a given title +-- +-- @string title function Company:set_title_calc_name(title) assert(type(title) == "string") @@ -38,10 +64,19 @@ function Company:set_title_calc_name(title) self.name = "c:" .. title:lower():gsub("%W", "_") end + +--- Get the name of the current CEO or president +-- +-- @treturn string function Company:get_ceo_name() return self.ceo end + +--- How must does a particular username own of this company? +-- +-- @string username +-- @treturn number Proportion of ownership, as a number out of 1. function Company:get_ownership(username) -- TODO: ownership if self.ceo == username then @@ -51,10 +86,23 @@ function Company:get_ownership(username) end end + +--- Whether a particular player can act as this company +-- +-- @string username +-- @treturn bool function Company:can_become_active(username) return self:check_perm(username, "SWITCH_TO") end + +--- Check whether a player has a certain permission +-- +-- @see company.permissions +-- @string username the username +-- @string permission permission name, string +-- @tparam ?table meta Metadata about this request +-- @treturn bool function Company:check_perm(username, permission, meta) assert(type(username) == "string") assert(type(permission) == "string") @@ -69,6 +117,14 @@ function Company:check_perm(username, permission, meta) return member and member.perms[permission] and true or false end + +--- Adds a member to the company +-- +-- Members are players other than the CEO that can have permissions +-- granted to them by the company +-- +-- @string username +-- @treturn Member table function Company:add_member(username) assert(not self.members[username]) @@ -83,6 +139,15 @@ function Company:add_member(username) return mem end + +--- Check whether this company is a governmental entity. +-- +-- Note: does NOT check whether the company is public or government-owned. +-- This condition imposes certain requirements on the government entity, +-- such as elections and voting, which do not make sense with government-owned +-- companies. +-- +-- @treturn bool function Company:is_government() return self.name == "c:government" end diff --git a/mods/capitalism/company/gui.lua b/mods/capitalism/company/gui.lua index bae27cb..c9c8c44 100644 --- a/mods/capitalism/company/gui.lua +++ b/mods/capitalism/company/gui.lua @@ -1,3 +1,9 @@ +--- +-- @module company + +--- Shows dialog to select company +-- @string name Player name to show to +-- @function company.show_company_select_dialog company.show_company_select_dialog = lib_quickfs.register("company:set_company", { get = function(context, player) local pname = player:get_player_name() diff --git a/mods/capitalism/company/init.lua b/mods/capitalism/company/init.lua index c6225b0..b7e6673 100644 --- a/mods/capitalism/company/init.lua +++ b/mods/capitalism/company/init.lua @@ -1,3 +1,7 @@ +--- +-- @module company + +--- company table company = {} print("[company] loading...") diff --git a/mods/capitalism/company/permissions.lua b/mods/capitalism/company/permissions.lua index 7d6d637..f51300c 100644 --- a/mods/capitalism/company/permissions.lua +++ b/mods/capitalism/company/permissions.lua @@ -1,3 +1,7 @@ +--- +-- @module company + +--- Permissions table company.permissions = { SWITCH_TO = "Can act on behalf of the company - needed to do anything else", EDIT_DETAILS = "Can edit the company's details, including name and branding", diff --git a/mods/capitalism/land/api.lua b/mods/capitalism/land/api.lua index 34b896f..fe67bde 100644 --- a/mods/capitalism/land/api.lua +++ b/mods/capitalism/land/api.lua @@ -1,7 +1,24 @@ +--- Introduces land plots, and modifies areas to allow companies to own land. +-- +-- This mod current uses areas as a backend, which means that a plot = an area. +-- +-- @module land + + +--- Dictionary of valid types land.valid_types = { commercial = true, residential = true, industrial = true } local adt = audit("land") + +--- Generates a tree representing land ownership hierarchy for a particular owner. +-- +-- Each element returned will have a children property, which will be a table +-- of child elements. +-- +-- @tparam [table] list A list of owned areas +-- @owner owner Player name or company name +-- @treturn (table,table) root, area by id function land.get_area_tree(list, owner) assert(list == nil or type(list) == "table") assert(owner == nil or type(owner) == "string") @@ -56,6 +73,11 @@ function land.get_area_tree(list, owner) return root, item_by_id end + +--- Gets all plots owned by a particular owner +-- +-- @owner owner Player name or company name +-- @treturn [table] List of plots function land.get_all(owner) local lands = {} for id, area in pairs(areas.areas) do @@ -68,6 +90,17 @@ function land.get_all(owner) return lands end + +--- Gets the owning plot of a particular area +-- +-- There is at most one owning area of a particular position; because +-- plots must not overlap, and any child of a plot most be fully contained. +-- +-- This function essential returns the lowest plot in the tree at a particular +-- point +-- +-- @pos pos +-- @treturn [table] function land.get_by_pos(pos) local areas = areas:getAreasAtPos(pos) @@ -90,6 +123,11 @@ function land.get_by_pos(pos) return first end + +--- Gets a plot by its area ID (as in the mod area) +-- +-- @int id +-- @treturn table plot function land.get_by_area_id(id) assert(type(id) == "number") @@ -97,6 +135,14 @@ function land.get_by_area_id(id) return area and area.land_type and area end + +--- Transfers a plot between two owners, after checking relevant permissions. +-- +-- @int id +-- @owner newowner +-- @player pname +-- @treturn true +-- @error Error message function land.transfer(id, newowner, pname) assert(type(id) == "number") assert(type(newowner) == "string") @@ -145,6 +191,14 @@ function land.transfer(id, newowner, pname) return true, "Transfered area id=" .. id .. " to " .. newowner end + +--- Whether a user can put a plot up for sale, or change the price when already +-- for sale +-- +-- @tparam table area +-- @player pname +-- @treturn true +-- @error Error message function land.can_set_price(area, pname) if not area or not area.land_type then return false, "Unable to sell unowned or unclassified (ie: c/i/r) area" @@ -172,6 +226,14 @@ function land.can_set_price(area, pname) return true end + +--- Puts a plot up for sale, or changes the price when already for sale +-- +-- @tparam table area +-- @player pname +-- @number price +-- @treturn true +-- @error Error message function land.set_price(area, pname, price) assert(type(area) == "table") assert(pname == nil or type(pname) == "string") @@ -196,6 +258,14 @@ function land.set_price(area, pname, price) return true end + +--- Whether a user can buy a plot +-- +-- @tparam table area +-- @player pname +-- @company comp +-- @treturn true +-- @error Error message function land.can_buy(area, pname, comp) assert(type(area) == "table") assert(type(pname) == "string") @@ -224,6 +294,13 @@ function land.can_buy(area, pname, comp) return true end + +--- Buy a plot +-- +-- @tparam table area +-- @player pname +-- @treturn true +-- @error Error message function land.buy(area, pname) assert(type(area) == "table") assert(type(pname) == "string") @@ -261,6 +338,13 @@ function land.buy(area, pname) return true end + +--- Whether a user can teleport to a plot +-- +-- @tparam table area +-- @player pname +-- @treturn true +-- @error Error message function land.can_teleport_to(area, pname) if type(pname) == "userdata" then pname = pname:get_player_name() @@ -283,6 +367,13 @@ function land.can_teleport_to(area, pname) return true end + +--- Teleport a user to a plot +-- +-- @tparam table area +-- @param player Player userdata +-- @treturn true +-- @error Error message function land.teleport_to(area, player) assert(type(area) == "table") assert(type(player) == "userdata") @@ -297,6 +388,13 @@ function land.teleport_to(area, player) return suc, msg end + +--- Whether a user can set the spawn of a plot +-- +-- @tparam table area +-- @player pname +-- @treturn true +-- @error Error message function land.can_set_spawn(area, pname) if type(pname) == "userdata" then pname = pname:get_player_name() diff --git a/mods/capitalism/land/init.lua b/mods/capitalism/land/init.lua index 1382632..6ddc64d 100644 --- a/mods/capitalism/land/init.lua +++ b/mods/capitalism/land/init.lua @@ -1,3 +1,7 @@ +--- +-- @module land + +--- land table land = {} print("[land] loading...") diff --git a/mods/capitalism/shop/api.lua b/mods/capitalism/shop/api.lua index f8cc537..8bc99f8 100644 --- a/mods/capitalism/shop/api.lua +++ b/mods/capitalism/shop/api.lua @@ -1,20 +1,32 @@ +--- Adds shops +-- +-- @module shop + _.extend(shop, { _shops = {}, _shops_by_area = {}, _context = {} }) + +--- Get a shop by its `land` area ID +-- +-- @int aid function shop.get_by_area(aid) assert(type(aid) == "number") return shop._shops_by_area[aid] end + +--- @pos pos function shop.get_by_pos(pos) assert(type(pos) == "table") local area = land.get_by_pos(pos) return area and shop.get_by_area(area.id) end + +--- @tparam table s function shop.add_shop(s) assert(not shop._shops_by_area[s.a_id]) @@ -23,25 +35,10 @@ function shop.add_shop(s) return true end -function shop.init_inventory(name) - return minetest.create_detached_inventory("shop_inv_" .. name, { - allow_put = function(inv, listname, index, stack, player) - return 0 - end, - - allow_take = function(inv, listname, index, stack, player) - return 0 - end - }) -end - -function shop.get_inventory_or_create(name) - return minetest.get_inventory({ - type = "detached", - name = "shop_inv_" .. name - }) or shop.init_inventory(name) -end - +--- Checks whether a user can use the admin interface for the shop +-- +-- @player pname +-- @pos pos function shop.can_admin(pname, pos) local area = land.get_by_pos(pos) local comp = company.get_by_name(area.owner) @@ -50,6 +47,13 @@ function shop.can_admin(pname, pos) company.check_perm(pname, comp.name, "SHOP_ADMIN", { pos = pos }) end + +--- Creates shops, checks permissions +-- +-- @player pname +-- @pos pos +-- @treturn true +-- @error Error message function shop.create_shop(pname, pos) local area = land.get_by_pos(pos) local comp = company.get_by_name(area.owner) @@ -71,6 +75,12 @@ function shop.create_shop(pname, pos) return true end + +--- Unassigns item allocation of chest. Will return any items. +-- +-- @shop s +-- @pos pos +-- @param inv Inventory userdata function shop.unassign_chest(s, pos, inv) local chest = s:get_chest(pos) if chest.itemname then @@ -92,6 +102,16 @@ function shop.unassign_chest(s, pos, inv) chest.count = 0 end + +--- Can user buy from shop, checks permissions +-- +-- @pos pos +-- @player pname +-- @string itemname +-- @int count +-- @int price +-- @treturn true +-- @error Error message function shop.can_buy(pos, pname, itemname, count, price) assert(type(pos) == "table") assert(type(pname) == "string") @@ -117,6 +137,16 @@ function shop.can_buy(pos, pname, itemname, count, price) return true end + +--- Buy from shop, checks permissions +-- +-- @pos pos +-- @player pname +-- @tparam table item +-- @int count +-- +-- @treturn true +-- @error Error message function shop.buy(pos, pname, item, count) assert(type(pos) == "table") assert(type(pname) == "string") @@ -193,6 +223,7 @@ function shop.buy(pos, pname, item, count) return true end + -- Minetest won't be available in tests if minetest then local storage = minetest.get_mod_storage() diff --git a/mods/libs/lib_underscore/init.lua b/mods/libs/lib_underscore/init.lua index 74e24b9..c54bea3 100644 --- a/mods/libs/lib_underscore/init.lua +++ b/mods/libs/lib_underscore/init.lua @@ -21,9 +21,6 @@ -- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -- OTHER DEALINGS IN THE SOFTWARE. ---- Underscore is a set of utility functions for dealing with --- iterators, arrays, tables, and functions. - local Underscore = { funcs = {} } Underscore.__index = Underscore @@ -59,7 +56,7 @@ function Underscore.range(start_i, end_i, step) return Underscore:new(range_iter) end ---- Identity function. This function looks useless, but is used throughout Underscore as a default. +-- Identity function. This function looks useless, but is used throughout Underscore as a default. -- @name _.identity -- @param value any object -- @return value