MudletPackageManager.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MudletPackage>
<MudletPackage version="1.001">
	<TriggerPackage />
	<TimerPackage />
	<AliasPackage>
		<AliasGroup isActive="yes" isFolder="yes">
			<name>mkpg</name>
			<script></script>
			<command></command>
			<packageName></packageName>
			<regex></regex>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg help</name>
				<script>mpkg.functions.printHelp()
</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg help$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg repo add</name>
				<script>mpkg.functions.addRepo(matches[2], matches[3], matches[4])</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg repo add (.+?) (.+?) (.*)$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg repo list</name>
				<script>mpkg.functions.listRepos()</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg repo list$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg repo info</name>
				<script>mpkg.functions.repoInfo(matches[2])</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg repo info (.+)$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg repo remove</name>
				<script>mpkg.functions.deleteRepo(matches[2])</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg repo remove (.+)$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg update</name>
				<script>mpkg.functions.update()</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg update$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg package list</name>
				<script>mpkg.functions.packageList()</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg package list$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg package info</name>
				<script>mpkg.functions.packageInfo(matches[2])</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg package info (.+)$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg install</name>
				<script>mpkg.functions.install(matches[2])</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg install ([^\s]+?)$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg uninstall</name>
				<script>mpkg.functions.uninstall(matches[2])</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg uninstall ([^\s]+)$</regex>
			</Alias>
			<Alias isActive="yes" isFolder="no">
				<name>mpkg upgrade</name>
				<script>mpkg.functions.upgrade()</script>
				<command></command>
				<packageName></packageName>
				<regex>^mpkg upgrade$</regex>
			</Alias>
		</AliasGroup>
	</AliasPackage>
	<ActionPackage />
	<ScriptPackage>
		<ScriptGroup isActive="yes" isFolder="yes">
			<name>mpkg</name>
			<packageName></packageName>
			<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
</script>
			<eventHandlerList />
			<Script isActive="yes" isFolder="no">
				<name>patch DB</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------

-- If we don't have qzery_by_example, we need to patch DB.lua as there were a lot of bugs.
if not db.query_by_example then

-- the timestamp is stored in UTC time, so work out the difference in seconds
-- from local to UTC time. Credit: https://github.com/stevedonovan/Penlight/blob/master/lua/pl/Date.lua#L85
function datetime:calculate_UTCdiff(ts)
   local date, time = os.date, os.time
   local utc = date('!*t',ts)
   local lcl = date('*t',ts)
   lcl.isdst = false
   return os.difftime(time(lcl), time(utc))
end

-- NOT LUADOC
-- The rex.match function does not return named patterns even if you use named capture
-- groups, but the r:tfind does -- but this only operates on compiled patterns. So,
-- we are caching the conversion of 'simple format' date patterns into a regex, and
-- then compiling them.
function datetime:_get_pattern(format)
   if not datetime._pattern_cache[format] then
      local fmt = rex.gsub(format, "(%[A-Za-z])",
         function(m)
               return datetime._directives[m] or m
         end
         )

      datetime._pattern_cache[format] = rex.new(fmt, rex.flags().CASELESS)
   end

   return datetime._pattern_cache[format]
end



--- Parses the specified source string, according to the format if given, to return a representation of
--- the date/time. The default format if not specified is: "^%Y-%m-%d %H:%M:%S$" &lt;br/&gt;&lt;br/&gt;
---
--- If as_epoch is provided and true, the return value will be a Unix epoch -- the number
--- of seconds since 1970. This is a useful format for exchanging date/times with other systems. If as_epoch
--- is false, then a Lua time table will be returned. Details of the time tables are provided
--- in the http://www.lua.org/pil/22.1.html. &lt;br/&gt;&lt;br/&gt;
---
--- Supported Format Codes
---   &lt;/pre&gt;
---   %b   Abbreviated Month Name
---   %B   Full Month Name
---   %d   Day of Month
---   %H   Hour (24-hour format)
---   %I   Hour (12-hour format, requires %p as well)
---   %p   AM or PM
---   %m   2-digit month (01-12)
---   %M   2-digit minutes (00-59)
---   %S   2-digit seconds (00-59)
---   %y   2-digit year (00-99), will automatically prepend 20 so 10 becomes 2010 and not 1910.
---   %Y   4-digit year.
---   &lt;/pre&gt;
function datetime:parse(source, format, as_epoch)
   if not format then
      format = "^%Y-%m-%d %H:%M:%S$"
   end

   local fmt = datetime:_get_pattern(format)
   local m = {fmt:tfind(source)}

   if m and m[3] then
      m = m[3]
      dt = {}

      if m.year_half then
         dt.year = tonumber("20"..m.year_half)
      elseif m.year_full then
         dt.year = tonumber(m.year_full)
      end

      if m.month then
         dt.month = tonumber(m.month)
      elseif m.month_name then
         dt.month = datetime._month_names[m.month_name:lower()]
      elseif m.abbrev_month_name then
         dt.month = datetime._abbrev_month_names[m.abbrev_month_name:lower()]
      end

      dt.day = m.day_of_month

      if m.hour_12 then
         assert(m.ampm, "You must use %p (AM|PM) with %I (12-hour time)")
         if m.ampm == "PM" then
            dt.hour = 12 + tonumber(m.hour_12)
         else
            dt.hour = tonumber(m.hour_12)
         end
      else
         dt.hour = tonumber(m.hour_24)
      end

      dt.min = tonumber(m.minute)
      dt.sec = tonumber(m.second)
      dt.isdst = false

      if as_epoch then
         return os.time(dt)
      else
         return dt
      end
   else
      return nil
   end
end



-----------------------------------------------------------------------------
-- The database wrapper library
-----------------------------------------------------------------------------
if package.loaded["luasql.sqlite3"] then luasql = require "luasql.sqlite3" end

db = {}
db.__autocommit = {}
db.__schema = {}
db.__conn = {}

db.debug_sql = false



-- NOT LUADOC
-- Converts the type of a lua object to the equivalent type in SQL
function db:_sql_type(value)
   local t = type(value)

   if t == "number" then
      return "REAL"
   elseif t == "nil" then
      return "NULL"
   elseif t == "table" and value._timestamp ~= nil then
      return "INTEGER"
   else
      return "TEXT"
   end
end



-- NOT LUADOC
-- Converts a data value in Lua to its SQL equivalent; notably it will also escape single-quotes to
-- prevent inadvertant SQL injection.
-- called when generating the schema
function db:_sql_convert(value)
   local t = db:_sql_type(value)

   if value == nil then
      return "NULL"
   elseif t == "TEXT" and type(value) == "string" then
      return '"'..value:gsub("'", "''")..'"'
   elseif t == "NULL" then
      return "NULL"
   elseif t == "INTEGER" then
      -- With db.Timestamp's, a value of false should be interpreted as nil.
      if value._timestamp == false then
         return "NULL"
      end
      return tostring(value._timestamp)
   else
      return tostring(value)
   end
end



-- NOT LUADOC
-- Given a sheet name and the details of an index, this function will return a unique index name to
-- add to the database. The purpose of this is to create unique index names as indexes are tested
-- for existance on each call of db:create and not only on creation. That way new indexes can be
-- added after initial creation.
function db:_index_name(tbl_name, params)
   local t = type(params)

   if t == "string" then
      return "idx_" .. tbl_name .. "_c_" .. params
   elseif assert(t == "table", "Indexes must be either a string or a table.") then
      local parts = {"idx", tbl_name, "c"}
      for _, v in pairs(params) do
         parts[#parts+1] = v
      end
      return table.concat(parts, "_")
   end
end



-- NOT LUADOC
-- This function returns true if all of the columns referenced in index_columns also exist within
-- the sheet_columns table array. The purpose of this is to raise an error if someone tries to index
-- a column which doesn't currently exist in the schema.
function db:_index_valid(sheet_columns, index_columns)
   if type(index_columns) == "string" then
      if sheet_columns[index_columns] ~= nil then
         return true
      else
         return false
      end
   else
      for _, v in ipairs(index_columns) do
         if sheet_columns[v] == nil then
            db:echo_sql("\n--&gt; Bad index "..v)
            return false
         end
      end
   end
   return true
end



-- NOT LUADOC
-- The column_spec is either a string or an indexed table. This function returns either "column" or
-- "column1", "column2" for use in the column specification of INSERT.
function db:_sql_columns(value)
   local colstr = ''
   local t = type(value)

   if t == "table" then
      col_chunks = {}
      for _, v in ipairs(value) do
         -- see https://www.sqlite.org/syntaxdiagrams.html#ordering-term
         if v:lower() == "desc" or v:lower() == "asc" then
            col_chunks[#col_chunks] = col_chunks[#col_chunks] .. " " .. v
         else
            col_chunks[#col_chunks+1] = '"'..v:lower()..'"'
         end
      end

      colstr = table.concat(col_chunks, ',')
   elseif assert(t == "string",
         "Must specify either a table array or string for index, not "..type(value)) then
      colstr = '"'..value:lower()..'"'
   end
   return colstr
end



-- NOT LUADOC
-- This serves as a very similar function to db:_sql_columns, quoting column names properly but for
-- uses outside of INSERTs.
function db:_sql_fields(values)
   local sql_fields = {}

   for k, v in pairs(values) do
      sql_fields[#sql_fields+1] = '"'..k..'"'
   end

   return   "("..table.concat(sql_fields, ",")..")"
end



-- NOT LUADOC
-- This quotes values to be passed into an INSERT or UPDATE operation in a SQL list. Meaning, it turns
-- {x="this", y="that", z=1} into ('this', 'that', 1).
-- It is intelligent with data-types; strings are automatically quoted (with internal single quotes
-- escaped), nil turned into NULL, timestamps converted to integers, and such.
function db:_sql_values(values)
   local sql_values = {}

   for k, v in pairs(values) do
      local t = type(v)
      local s = ""

      if t == "string" then
         s = "'"..v:gsub("'", "''").."'"
      elseif t == "nil" then
         s = "NULL"
      elseif t == "table" and t._timestamp ~= nil then
         if not t._timestamp then
            return "NULL"
         else
            s = "datetime('"..t._timestamp.."', 'unixepoch')"
         end
      else
         s = tostring(v)
      end

      sql_values[#sql_values+1] = s
   end

   return "("..table.concat(sql_values, ",")..")"
end



--- &lt;b&gt;&lt;u&gt;TODO&lt;/u&gt;&lt;/b&gt; db:safe_name(name)
--   On a filesystem level, names are restricted to being alphanumeric only. So, "my_database" becomes
--   "mydatabase", and "../../../../etc/passwd" becomes "etcpasswd". This prevents any possible
--   security issues with database names.
function db:safe_name(name)
   name = name:gsub("[^%ad]", "")
   name = name:lower()
   return name
end



--- Creates and/or modifies an existing database. This function is safe to define at a top-level of a Mudlet
--- script: in fact it is reccommended you run this function at a top-level without any kind of guards.
--- If the named database does not exist it will create it. If the database does exist then it will add
--- any columns or indexes which didn't exist before to that database. If the database already has all the
--- specified columns and indexes, it will do nothing. &lt;br/&gt;&lt;br/&gt;
---
--- The database will be called Database_&lt;sanitized database name&gt;.db and will be stored in the
--- Mudlet configuration directory. &lt;br/&gt;&lt;br/&gt;
---
--- Database 'tables' are called 'sheets' consistently throughout this documentation, to avoid confusion
--- with Lua tables. &lt;br/&gt;&lt;br/&gt;
---
--- The schema table must be a Lua table array containing table dictionaries that define the structure and
--- layout of each sheet. &lt;br/&gt;&lt;br/&gt;
---
--- For sheets with unique indexes, you may specify a _violations key to indicate how the db layer handle
--- cases where the unique index is violated. The options you may use are:
---   &lt;pre&gt;
---   FAIL - the default. A hard error is thrown, cancelling the script.
---   IGNORE - The command that would add a record that violates uniqueness just fails silently.
---   REPLACE - The old record which matched the unique index is dropped, and the new one is added to replace it.
---   &lt;/pre&gt;
---
--- @usage Example bellow will create a database with two sheets; the first is kills and is used to track every successful kill,
---   with both where and when the kill happened. It has one index, a compound index tracking the combination of name and area.
---   The second sheet has two indexes, but one is unique: it isn't possible to add two items to the enemies sheet with the same name.
---   &lt;pre&gt;
---   local mydb = db:create("combat_log",
---     {
---       kills = {
---         name = "",
---         area = "",
---         killed = db:Timestamp("CURRENT_TIMESTAMP"),
---         _index = {{"name", "area"}}
---       },
---       enemies = {
---         name = "",
---         city = "",
---         reason = "",
---         enemied = db:Timestamp("CURRENT_TIMESTAMP"),
---         _index = { "city" },
---         _unique = { "name" },
---         _violations = "IGNORE"
---       }
---     }
---   )
---   &lt;/pre&gt;
---   Note that you have to use double {{ }} if you have composite index/unique constrain.
function db:create(db_name, sheets)
   if not db.__env then
      db.__env = luasql.sqlite3()
   end

   db_name = db:safe_name(db_name)

   if not db.__conn[db_name] then
      db.__conn[db_name] = db.__env:connect(getMudletHomeDir() .. "/Database_" .. db_name .. ".db")
      db.__conn[db_name]:setautocommit(false)
      db.__autocommit[db_name] = true
   end

   db.__schema[db_name] = {}

   -- We need to separate the actual column configuration from the meta-configuration of the desired
   -- sheet. {sheet={"column"}} verses {sheet={"column"}, _index={"column"}}. In the former we are
   -- creating a database with a single field; in the latter we are also adding an index on that
   -- field. The db package reserves any key that begins with an underscore to be special and syntax
   -- for its own use.
   for s_name, sht in pairs(sheets) do
      options = {}

      if sht[1] ~= nil then         -- in case the sheet was provided in the sheet = {"column1", "column2"} format:
         local t = {}               --   assume field types are text, and should default to ""
         for k, v in pairs(sht) do
            t[v] = ""
         end
         sht = t
      else                          -- sheet provided in the sheet = {"column1" = default} format
         local opts = {}
         for k, v in pairs(sht) do
            if string.starts(k, "_") then
               options[k] = v
               opts[#opts + 1] = k
            end
         end
         for _, v in ipairs(opts) do
            sht[v] = nil
         end
      end

      if not options._violations then
         options._violations = "FAIL"
      end

      db.__schema[db_name][s_name] = {columns=sht, options=options}
      db:_migrate(db_name, s_name)
   end
   return db:get_database(db_name)
end



-- NOT LUADOC
-- The migrate function is meant to upgrade an existing database live, to maintain a consistant
-- and correct set of sheets and fields, along with their indexes. It should be safe to run
-- at any time, and must not cause any data loss. It simply adds to what is there: in perticular
-- it is not capable of removing indexes, columns, or sheets after they have been defined.
function db:_migrate(db_name, s_name)
   local conn = db.__conn[db_name]
   local schema = db.__schema[db_name][s_name]

   local current_columns = {}

   -- The PRAGMA table_info command is a query which returns all of the columns currently
   -- defined in the specified table. The purpose of this section is to see if any new columns
   -- have been added.
   local cur = conn:execute("PRAGMA table_info('"..s_name.."')") -- currently broken - LuaSQL bug, needs to be upgraded for new sqlite API

   if type(cur) ~= "number" then
      local row = cur:fetch({}, "a")
      if row then
         while row do
            current_columns[row.name] = row.type
            row = cur:fetch({}, "a")
         end
      else
         ---------------  GETS ALL COLUMNS FROM SHEET IF IT EXISTS
         db:echo_sql("SELECT * FROM "..s_name)
         local get_sheet_cur = conn:execute("SELECT * FROM "..s_name)  -- select the sheet

         if get_sheet_cur and get_sheet_cur ~= 0 then
            local row = get_sheet_cur:fetch({}, "a") -- grab the first row, if any
            if not row then -- if no first row then
               local tried_cols, contains, found_something, col = {}, table.contains, false

               while not found_something do -- guarded by the error below from infinite looping
                  col = false
                  for k,v in pairs(schema.columns) do -- look through sheet schema to find the first column that is text
                     if type(k) == "number" then
                        if string.sub(v,1,1) ~= "_" and not contains(tried_cols, v) then col = v break end
                     else
                        if string.sub(k,1,1) ~= "_" and type(v) == "string" and not contains(tried_cols, k) then col = k break end
                     end
                  end

                  if not col then error("db:_migrate: cannot find a suitable column for testing a new row with.") end

                  -- add row with found column set as "test"
                  db:add({_db_name = db_name, _sht_name = s_name},{[col] = "test"})

                  db:echo_sql("SELECT * FROM "..s_name)
                  local get_row_cur = conn:execute("SELECT * FROM "..s_name) -- select the sheet
                  row = get_row_cur:fetch({}, "a") -- grab the newly created row
                  get_row_cur:close()

                  -- delete the newly created row. If we picked a row that doesn't exist yet and we're
                  -- trying to add, the delete will fail - remember this, and try another row
                  local worked, msg = pcall(db.delete, db, {_db_name = db_name, _sht_name = s_name},db:eq({database = db_name, sheet = s_name, name = col, type = "string"},"test"))

                  if not worked then
                     tried_cols[#tried_cols+1] = col
                  else
                     found_something = true
                  end
               end
            end

            if row then -- add each column from row to current_columns table
               for k,v in pairs(row) do
                  current_columns[k] = ""
               end
            end
            get_sheet_cur:close()
         end
      end
   end

   if type(cur) == "userdata" then
      cur:close()
   end

   -- The SQL definition of a column is:
   --    "column_name" column_type NULL
   -- The db module does not presently support columns that are required. Everything is optional,
   -- everything may be NULL / nil.
   -- If you specify a column's type, you also specify its default value.
   if table.is_empty(current_columns) then
      -- At this point, we know that the specified table does not exist in the database and so we
      -- should create it.

      -- Every sheet has an implicit _row_id column. It is not presently (and likely never will be)
      -- supported to define the primary key of any sheet.
      local sql = db:_build_create_table_sql(schema, s_name)
      db:echo_sql(sql)
      conn:execute(sql)

   else
      -- At this point we know that the sheet already exists, but we are concerned if the current
      -- definition includes columns which may be added.
      local missing = {}

      for k, v in pairs(schema.columns) do

         -- Here we test it a given column exists in the sheet already, and if not, we add that
         -- column.
         if not current_columns[k] then
            missing[#missing + 1] = { name = k, default = v }
         end
      end

      if #missing &gt; 0 and 
         table.size(current_columns) + #missing == table.size(schema.columns)+1
         -- We have changes and when we did those changes, we have exactly
         -- the number of columns we need. The "+1" is for the _row_id
         -- which is not in the schema.
      then
         local sql_add = 'ALTER TABLE %s ADD COLUMN "%s" %s NULL DEFAULT %s'
         for _, v in ipairs(missing) do
            local t = db:_sql_type(v.default)
            local def = db:_sql_convert(v.default)
            local sql = sql_add:format(s_name, v.name, t, def)
            conn:execute(sql)
            db:echo_sql(sql)
         end
      elseif 
         #missing + table.size(current_columns) &gt; table.size(schema.columns) + 1
         -- if we add all missing columns and we have more columns than we want
         -- then there are currently some columns we don't want anymore.
      then
         local get_create = "SELECT sql FROM sqlite_master " ..
                            "WHERE type = 'table' AND " ..
                            "name = '" .. s_name .."'"
         local ret_str
         cur, ret_str = conn:execute(get_create)
         assert(cur, ret_str)
         if type(cur) ~= "number" then
            local row = cur:fetch({}, "a");
            cur:close()
            local create_tmp = row.sql:gsub(s_name, s_name .. "_bak")
            local sql_chunks = {}
            local fields = { "_row_id" }
            local sql

            create_tmp = create_tmp:gsub("TABLE", "TEMPORARY TABLE")

            for k, _ in pairs(schema.columns) do
              fields[#fields + 1] = string.format('"%s"', k)
            end
            local fields_sql = table.concat(fields, ", ")

            sql_chunks[#sql_chunks + 1] = create_tmp .. ";"
            sql_chunks[#sql_chunks + 1] = "INSERT INTO " .. s_name .. "_bak " ..
                                          "SELECT * FROM " .. s_name .. ";"
            sql_chunks[#sql_chunks + 1] = "DROP TABLE " .. s_name .. ";"
            sql_chunks[#sql_chunks + 1] = db:_build_create_table_sql(schema,
                                               s_name) .. ";"
            sql_chunks[#sql_chunks + 1] = string.format(
                 "INSERT INTO %s SELECT %s FROM %s_bak;", s_name, fields_sql,
                 s_name)
            sql_chunks[#sql_chunks + 1] = "DROP TABLE " .. s_name .. "_bak;"

            for _, sql in ipairs(sql_chunks) do
               db:echo_sql(sql)
               local ret, str = conn:execute(sql)
               assert(ret, str)
            end
         end
      end
   end

   -- On every invocation of db:create we run the code that creates indexes, as that code will
   -- do nothing if the specific indexes already exist. This is enforced by the db:_index_name
   -- function creating a unique index.
   --
   -- Note that in no situation will an existing index be deleted.

   -- make up current_columns, as pragma_info currently does not populate it, due to luasql bug
   for key, value in pairs(schema.columns) do
      current_columns[key] =  db:_sql_type(value)
   end

   db:_migrate_indexes(conn, s_name, schema, current_columns)
   db:echo_sql("COMMIT")
   conn:commit()
   conn:execute("VACUUM")
end

function db:_build_create_table_sql(schema, s_name)

   local sql_column = ', "%s" %s NULL'
   local sql_column_default = sql_column..' DEFAULT %s'


   local sql_chunks = {"CREATE TABLE ", s_name,  '("_row_id" INTEGER PRIMARY KEY AUTOINCREMENT'}

      -- We iterate over every defined column, and add a line which creates it.
   for key, value in pairs(schema.columns) do
      local sql = ""
      if value == nil then
         sql = sql_column:format(key, db:_sql_type(value))
      else
         sql = sql_column_default:format(key, db:_sql_type(value), db:_sql_convert(value))
      end
      if (type(schema.options._unique) == "table" and table.contains(schema.options._unique, key))
         or (type(schema.options._unique) == "string" and schema.options._unique == key) then
         sql = sql .. " UNIQUE"
      end
      sql_chunks[#sql_chunks+1] = sql
   end

   sql_chunks[#sql_chunks+1] = ")"

   return table.concat(sql_chunks, "")
end


-- NOT LUADOC
-- Creates any indexes which do not yet exist in the given database.
function db:_migrate_indexes(conn, s_name, schema, current_columns)
   local sql_create_index = "CREATE %s IF NOT EXISTS %s ON %s (%s);"
   local opt = {_unique = "UNIQUE INDEX", _index = "INDEX"} -- , _check = "CHECK"}

   for option_type, options in pairs(schema.options) do
      if option_type == "_unique" or option_type == "_index" then
         for _, value in pairs(options) do

            -- If an index references a column which does not presently exist within the schema
            -- this will fail.

            if db:_index_valid(current_columns, value) then
               --assert(db:_index_valid(current_columns, value),
               --      "In sheet "..s_name.." an index field is specified that does not exist.")

               local sql = sql_create_index:format(
                     opt[option_type], db:_index_name(s_name, value), s_name, db:_sql_columns(value)
               )
               db:echo_sql(sql)
               conn:execute(sql)
            end
         end
      end
   end
end



--- Adds one or more new rows to the specified sheet. If any of these rows would violate a UNIQUE index,
--- a lua error will be thrown and execution will cancel. As such it is advisable that if you use a UNIQUE
--- index, you test those values before you attempt to insert a new row. &lt;br/&gt;&lt;br/&gt;
---
--- Each table is a series of key-value pairs to set the values of the sheet, but if any keys do not exist
--- then they will be set to nil or the default value. As you can see, all fields are optional.
---
--- @usage Adding one record.
---   &lt;pre&gt;
---   db:add(mydb.enemies, {name="Bob Smith", city="San Francisco"})
---   &lt;/pre&gt;
--- @usage Adding multiple records.
---   &lt;pre&gt;
---   db:add(mydb.enemies,
---     {name="John Smith", city="San Francisco"},
---     {name="Jane Smith", city="San Francisco"},
---     {name="Richard Clark"}
---   )
---   &lt;/pre&gt;
function db:add(sheet, ...)
   local db_name = sheet._db_name
   local s_name = sheet._sht_name
   assert(s_name, "First argument to db:add must be a proper Sheet object.")

   local conn = db.__conn[db_name]
   local sql_insert = "INSERT OR %s INTO %s %s VALUES %s"

   for _, t in ipairs({...}) do
      if t._row_id then
         -- You are not permitted to change a _row_id
         t._row_id = nil
      end

      local sql = sql_insert:format(db.__schema[db_name][s_name].options._violations, s_name, db:_sql_fields(t), db:_sql_values(t))
      db:echo_sql(sql)

      local result, msg = conn:execute(sql)
      if not result then return nil, msg end
   end
   if db.__autocommit[db_name] then
      conn:commit()
   end
   return true
end



--- Execute SQL select query against database. This only useful for some very specific cases. &lt;br/&gt;
--- Use db:fetch if possible instead - this function should not be normally used!
---
--- @release post Mudlet 1.1.1 (&lt;b&gt;&lt;u&gt;TODO update before release&lt;/u&gt;&lt;/b&gt;)
---
--- @usage Following will select all distinct area from my kills DB.
---   &lt;pre&gt;
---   db:fetch_sql(mydb.kills, "SELECT distinct area FROM kills")
---   &lt;/pre&gt;
---
--- @see db:fetch
function db:fetch_sql(sheet, sql)
   local db_name = sheet._db_name
   local conn = db.__conn[db_name]

   db:echo_sql(sql)
   local cur = conn:execute(sql)

   -- if we had a syntax error in our SQL, cur will be nil
   if cur and cur ~= 0 then
      local results = {}
      local row = cur:fetch({}, "a")

      while row do
         results[#results+1] = db:_coerce_sheet(sheet, row)
         row = cur:fetch({}, "a")
      end
      cur:close()
      return results
   else
      return nil
   end
end



--- Returns a table array containing a table for each matching row in the specified sheet. All arguments
--- but sheet are optional. If query is nil, the entire contents of the sheet will be returned. &lt;br/&gt;&lt;br/&gt;
---
--- Query is a string which should be built by calling the various db: expression functions, such as db:eq,
--- db:AND, and such. You may pass a SQL WHERE clause here if you wish, but doing so is very dangerous.
--- If you don't know SQL well, its best to build the expression.&lt;br/&gt;&lt;br/&gt;
---
--- Query may also be a table array of such expressions, if so they will be AND'd together implicitly.&lt;br/&gt;&lt;br/&gt;
---
--- The results that are returned are not in any guaranteed order, though they are usually the same order
--- as the records were inserted. If you want to rely on the order in any way, you must pass a value to the
--- order_by field. This must be a table array listing the fields you want to sort by.
--- It can be { mydb.kills.area }, or { mydb.kills.area, mydb.kills.name } &lt;br/&gt;&lt;br/&gt;
---
--- The results are returned in ascending (smallest to largest) order; to reverse this pass true into the final field.
---
--- @usage The first will fetch all of your enemies, sorted first by the city they reside in and then by their name.
---   &lt;pre&gt;
---   db:fetch(mydb.enemies, nil, {mydb.enemies.city, mydb.enemies.name})
---   &lt;/pre&gt;
--- @usage The second will fetch only the enemies which are in San Francisco.
---   &lt;pre&gt;
---   db:fetch(mydb.enemies, db:eq(mydb.enemies.city, "San Francisco"))
---   &lt;/pre&gt;
--- @usage The third will fetch all the things you've killed in Undervault which have Drow in their name.
---   &lt;pre&gt;
---   db:fetch(mydb.kills,
---      {
---         db:eq(mydb.kills.area, "Undervault"),
---         db:like(mydb.kills.name, "%Drow%")
---      }
---   )
---   &lt;/pre&gt;
---
--- @see db:fetch_sql
function db:fetch(sheet, query, order_by, descending)
   local s_name = sheet._sht_name

   local sql = "SELECT * FROM "..s_name

   if query then
      if type(query) == "table" then
         sql = sql.." WHERE "..db:AND(unpack(query))
      else
         sql = sql.." WHERE "..query
      end
   end

   if order_by then
      local o = {}
      for _, v in ipairs(order_by) do
         assert(v.name, "You must pass field instances (as obtained from yourdb.yoursheet.yourfield) to sort.")
         o[#o+1] = v.name

         if descending then
            o[#o+1] = "DESC"
         end
      end

      sql = sql.." ORDER BY "..db:_sql_columns(o)
   end

   return db:fetch_sql(sheet, sql)
end



--- Returns the result of calling the specified aggregate function on the field and its sheet. &lt;br/&gt;&lt;br/&gt;
---
--- The supported aggregate functions are:
---   &lt;pre&gt;
---   COUNT - Returns the total number of records that are in the sheet or match the query.
---   AVG   - Returns the average of all the numbers in the specified field.
---   MAX   - Returns the highest number in the specified field.
---   MIN   - Returns the lowest number in the specified field.
---   TOTAL - Returns the value of adding all the contents of the specified field.
---   &lt;/pre&gt;
---
--- @param query optional
---
--- @usage Example:
---   &lt;pre&gt;
---   local mydb = db:get_database("my database")
---   echo(db:aggregate(mydb.enemies.name, "count"))
---   &lt;/pre&gt;
function db:aggregate(field, fn, query, distinct)
   local db_name = field.database
   local s_name = field.sheet
   local conn = db.__conn[db_name]

   assert(type(field) == "table", "Field must be a field reference.")
   assert(field.name, "Field must be a real field reference.")

   local sql_chunks = {"SELECT", fn, "(", distinct and "DISTINCT" or "", field.name, ")", "AS", fn, "FROM", s_name}

   if query then
      sql_chunks[#sql_chunks+1] = "WHERE"
      if type(query) == "table" then
         sql_chunks[#sql_chunks+1] = db:AND(unpack(query))
      else
         sql_chunks[#sql_chunks+1] = query
      end
   end

   local sql = table.concat(sql_chunks, " ")

   db:echo_sql(sql)
   local cur = conn:execute(sql)

   if cur ~= 0 then
      local row = cur:fetch({}, "a")
      local count = row[fn]
      cur:close()
      
      -- give back the correct data type. see http://www.sqlite.org/lang_aggfunc.html
      if (fn:upper() ~= "MIN" and fn:upper() ~= "MAX") or field.type == "number" then
         return tonumber(count)
      end
      if field.type == "string" then
        return count
      end
      -- Only datetime left
      -- the value, count, is currently in a UTC timestamp
      local localtime = datetime:parse(count, nil, true)
      -- convert it into a UTC timestamp as datetime:parse parses it in the local time context
      count = db:Timestamp(localtime + datetime:calculate_UTCdiff(localtime))
      return count
   else
      return 0
   end
end



--- Deletes rows from the specified sheet. The argument for query tries to be intelligent: &lt;br/&gt;
--- * if it is a simple number, it deletes a specific row by _row_id &lt;br/&gt;
--- * if it is a table that contains a _row_id (e.g., a table returned by db:get) it deletes just that record. &lt;br/&gt;
--- * Otherwise, it deletes every record which matches the query pattern which is specified as with db:get. &lt;br/&gt;
--- * If the query is simply true, then it will truncate the entire contents of the sheet. &lt;br/&gt;
---
--- @usage When passed an actual result table that was obtained from db:fetch, it will delete the record for that table.
---   &lt;pre&gt;
---   enemies = db:fetch(mydb.enemies)
---   db:delete(mydb.enemies, enemies[1])
---   &lt;/pre&gt;
--- @usage When passed a number, will delete the record for that _row_id. This example shows getting the row id from a table.
---   &lt;pre&gt;
---   enemies = db:fetch(mydb.enemies)
---   db:delete(mydb.enemies, enemies[1]._row_id)
---   &lt;/pre&gt;
--- @usage As above, but this example just passes in the row id directly.
---   &lt;pre&gt;
---   db:delete(mydb.enemies, 5)
---   &lt;/pre&gt;
--- @usage Here, we will delete anything which matches the same kind of query as db:fetch uses - namely,
---   anyone who is in the city of San Francisco.
---   &lt;pre&gt;
---   db:delete(mydb.enemies, db:eq(mydb.enemies.city, "San Francisco"))
---   &lt;/pre&gt;
--- @usage And finally, we will delete the entire contents of the enemies table.
---   &lt;pre&gt;
---   db:delete(mydb.enemies, true)
---   &lt;/pre&gt;
function db:delete(sheet, query)
   local db_name = sheet._db_name
   local s_name = sheet._sht_name

   local conn = db.__conn[db_name]

   assert(query, "must pass a query argument to db:delete()")
   if type(query) == "number" then
      query = "_row_id = "..tostring(query)
   elseif type(query) == "table" then
      assert(query._row_id, "Passed a non-result table to db:delete, need a _row_id field to continue.")
      query = "_row_id = "..tostring(query._row_id)
   end

   local sql = "DELETE FROM "..s_name

   if query ~= true then
      sql = sql.." WHERE "..query
   end

   db:echo_sql(sql)
   assert(conn:execute(sql))
   if db.__autocommit[db_name] then
      conn:commit()
   end
end



--- Merges the specified table array into the sheet, modifying any existing rows and adding any that don't exist.
---
--- This function is a convenience utility that allows you to quickly modify a sheet, changing
--- existing rows and add new ones as appropriate. It ONLY works on sheets which have a unique
--- index, and only when that unique index is only on a single field. For more complex situations
--- you'll have to do the logic yourself.
---
--- The table array may contain tables that were either returned previously by db:fetch, or new tables
--- that you've constructed with the correct fields, or any mix of both. Each table must have a value
--- for the unique key that has been set on this sheet.
---
--- @usage For example, consider this database:
---   &lt;pre&gt;
---   local mydb = db:create("peopledb",
---     {
---       friends = {
---         name = "",
---         race = "",
---         level = 0,
---         city = "",
---         _index = { "city" },
---         _unique = { "name" }
---       }
---     }
---   )
---   &lt;/pre&gt;
---
---   Here you have a database with one sheet, which contains your friends, their race, level,
---   and what city they live in. Let's say you want to fetch everyone who lives in San Francisco, you could do:
---   &lt;pre&gt;
---   local results = db:fetch(mydb.friends, db:eq(mydb.friends.city, "San Francisco"))
---   &lt;/pre&gt;
---
---   The tables in results are static, any changes to them are not saved back to the database.
---   But after a major radioactive cataclysm rendered everyone in San Francisco a mutant,
---   you could make changes to the tables as so:
---   &lt;pre&gt;
---   for _, friend in ipairs(results) do
---     friend.race = "Mutant"
---   end
---   &lt;/pre&gt;
---
---   If you are also now aware of a new arrival in San Francisco, you could add them to that existing table array:
---   &lt;pre&gt;
---   results[#results+1] = {name="Bobette", race="Mutant", city="San Francisco"}
---   &lt;/pre&gt;
---
---   And commit all of these changes back to the database at once with:
---   &lt;pre&gt;
---   db:merge_unique(mydb.friends, results)
---   &lt;/pre&gt;
---
---   The db:merge_unique function will change the 'city' values for all the people who we previously fetched, but then add a new record as well.
function db:merge_unique(sheet, tables)
   assert(type(tables) == "table", "db:merge_unique: missing the required table of data to merge")

   local db_name = sheet._db_name
   local s_name = sheet._sht_name

   local unique_options = db.__schema[db_name][s_name].options._unique
   assert(unique_options, "db:merge_unique only works on a sheet with a unique index.")
   assert(#unique_options == 1, "db:merge_unique only works on a sheet with a single unique index.")

   local unique_index = unique_options[1]
   local unique_key = ""
   if type(unique_index) == "table" then
      assert(#unique_index == 1, "db:merge_unique currently only supports sheets with a single unique index with a single column.")
      unique_key = unique_index[1]
   else
      unique_key = unique_index
   end

   db:echo_sql(":: Unique index = "..unique_key)

   local conn = db.__conn[db_name]
   local mydb = db:get_database(db_name)
   mydb:_begin()

   for _, tbl in ipairs(tables) do
      assert(tbl[unique_key], "attempting to db:merge_unique with a table that does not have the unique key.")

      local results = db:fetch(sheet, db:eq(sheet[unique_key], tbl[unique_key]))
      if results and results[1] then
         local t = results[1]
         for k, v in pairs(tbl) do
            t[k] = v
         end

         db:update(sheet, t)
      else
         db:add(sheet, tbl)
      end
   end

   mydb:_commit()
   mydb:_end()
end



--- This function updates a row in the specified sheet, but only accepts a row which has been previously
--- obtained by db:fetch. Its primary purpose is that if you do a db:fetch, then change the value of a field
--- or tow, you can save back that table.
---
--- @usage This obtains a database reference, and queries the friends sheet for someone named Bob. As this
---   returns a table array containing only one item, it assigns that one item to the local variable named bob.
---   We then change the notes on Bob, and pass it into db:update() to save the changes back.
---   &lt;pre&gt;
---   local mydb = db:get_database("my database")
---   local bob = db:fetch(mydb.friends, db:eq(mydb.friends.name, "Bob"))[1]
---   bob.notes = "He's a really awesome guy."
---   db:update(mydb.friends, bob)
---   &lt;/pre&gt;
function db:update(sheet, tbl)
   assert(tbl._row_id, "Can only update a table with a _row_id")
   assert(not table.is_empty(tbl), "An empty table was passed to db:update")

   local db_name = sheet._db_name
   local s_name = sheet._sht_name

   local conn = db.__conn[db_name]

   local sql_chunks = {"UPDATE OR", db.__schema[db_name][s_name].options._violations, s_name, "SET"}

   local set_chunks = {}
   local set_block = [["%s" = %s]]

   for k, v in pairs(db.__schema[db_name][s_name]['columns']) do
      if tbl[k] then
         local field = sheet[k]
         set_chunks[#set_chunks+1] = set_block:format(k, db:_coerce(field, tbl[k]))
      end
   end

   sql_chunks[#sql_chunks+1] = table.concat(set_chunks, ",")
   sql_chunks[#sql_chunks+1] = "WHERE _row_id = "..tbl._row_id

   local sql = table.concat(sql_chunks, " ")
   db:echo_sql(sql)
   assert(conn:execute(sql))
   if db.__autocommit[db_name] then
      conn:commit()
   end
end



--- The db:set function allows you to set a certain field to a certain value across an entire sheet.
--- Meaning, you can change all of the last_read fields in the sheet to a certain value, or possibly only
--- the last_read fields which are in a certain city. The query argument can be any value which is appropriate
--- for db:fetch, even nil which will change the value for the specified column for EVERY row in the sheet.
---
--- For example, consider a situation in which you are tracking how many times you find a certain
--- type of egg during Easter. You start by setting up your database and adding an Eggs sheet, and
--- then adding a record for each type of egg.
---   &lt;pre&gt;
---   local mydb = db:create("egg database", {eggs = {color = "", last_found = db.Timestamp(false), found = 0}})
---   db:add(mydb.eggs,
---     {color = "Red"},
---     {color = "Blue"},
---     {color = "Green"},
---     {color = "Yellow"},
---     {color = "Black"}
---   )
---   &lt;/pre&gt;
---
--- Now, you have three columns. One is a string, one a timestamp (that ends up as nil in the database),
--- and one is a number. &lt;br/&gt;&lt;br/&gt;
---
--- You can then set up a trigger to capture from the mud the string, "You pick up a (.*) egg!", and you
--- end up arranging to store the value of that expression in a variable called "myegg". &lt;br/&gt;&lt;br/&gt;
---
--- To increment how many we found, we will do this:
---   &lt;pre&gt;
---   myegg = "Red" -- We will pretend a trigger set this.
---   db:set(mydb.eggs.found, db:exp("found + 1"), db:eq(mydb.eggs.color, myegg))
---   db:set(mydb.eggs.last_found, db.Timestamp("CURRENT_TIMESTAMP"), db:eq(mydb.eggs.color, myegg))
---   &lt;/pre&gt;
---
--- This will go out and set two fields in the Red egg sheet; the first is the found field, which will
--- increment the value of that field (using the special db:exp function). The second will update the
--- last_found field with the current time. &lt;br/&gt;&lt;br/&gt;
---
--- Once this contest is over, you may wish to reset this data but keep the database around.
--- To do that, you may use a more broad use of db:set as such:
---   &lt;pre&gt;
---   db:set(mydb.eggs.found, 0)
---   db:set(mydb.eggs.last_found, nil)
---   &lt;/pre&gt;
function db:set(field, value, query)
   local db_name = field.database
   local s_name = field.sheet

   local conn = db.__conn[db_name]

   local sql_update = [[UPDATE OR %s %s SET "%s" = %s]]
   if query then
       sql_update = sql_update .. [[ WHERE %s]]
   end

   local sql = sql_update:format(db.__schema[db_name][s_name].options._violations, s_name, field.name, db:_coerce(field, value), query)

   db:echo_sql(sql)
   assert(conn:execute(sql))
   if db.__autocommit[db_name] then
      conn:commit()
   end
end



--- This is a debugging function, which echos any SQL commands if db.debug_sql is true.
--- You should not call this function directly from Mudlet.
---
--- @usage Set following lua variable to enable SQL echos.
---   &lt;pre&gt;
---   db.debug_sql=true
---   &lt;/pre&gt;
function db:echo_sql(sql)
   if db.debug_sql then
      print(sql)
   end
end



-- NOT LUADOC
-- After a table so retrieved from the database, this function coerces values to
-- their proper types. Specifically, numbers and datetimes become the proper
-- types.
function db:_coerce_sheet(sheet, tbl)
   if tbl then
      tbl._row_id = tonumber(tbl._row_id)

      for k, v in pairs(tbl) do
         if k ~= "_row_id" then
            local field = sheet[k]
            if field.type == "number" then
               tbl[k] = tonumber(tbl[k]) or tbl[k]
            elseif field.type == "datetime" then
               -- the value, tbl[k], is currently in a UTC timestamp
               local localtime = datetime:parse(tbl[k], nil, true)
               -- convert it into a UTC timestamp as datetime:parse parses it in the local time context
               tbl[k] = db:Timestamp(localtime + datetime:calculate_UTCdiff(localtime))
            end
         end
      end
      return tbl
   end
end



-- NOT LUADOC
-- The function converts a Lua value into its SQL representation, depending on the
-- type of the specified field. Strings will be single-quoted (and single-quotes
-- within will be properly escaped), numbers will be rendered properly, and such.
function db:_coerce(field, value)
   if field.type == "number" then
      return tonumber(value) or "'"..value.."'"
   elseif field.type == "datetime" then
      if value._timestamp == false then
         return "NULL"
      else
         return "datetime('"..value._timestamp.."', 'unixepoch')" or "'"..value.."'"
      end
   else
      return "'"..tostring(value):gsub("'", "''").."'"
   end
end



--- Returns a database expression to test if the field in the sheet is equal to the value.
---
--- @see db:fetch
function db:eq(field, value, case_insensitive)
   local fieldname = field.name
   -- escape column names as per https://www.sqlite.org/lang_expr.html
   fieldname = '"'..fieldname:gsub("'", "''")..'"'
   if case_insensitive then
      local v = db:_coerce(field, value):lower()
      return "lower("..fieldname..") == "..v
   else
      local v = db:_coerce(field, value)
      return fieldname.." == "..v
   end
end



--- Returns a database expression to test if the field in the sheet is NOT equal to the value.
---
--- @see db:fetch
function db:not_eq(field, value, case_insensitive)
   if case_insensitive then
      local v = db:_coerce(field, value):lower()
      return "lower("..field.name..") != "..v
   else
      local v = db:_coerce(field, value)
      return field.name.." != "..v
   end
end



--- Returns a database expression to test if the field in the sheet is less than the value.
---
--- @see db:fetch
function db:lt(field, value)
   local v = db:_coerce(field, value)
   return field.name.." &lt; "..v
end



--- Returns a database expression to test if the field in the sheet is less than or equal to the value.
---
--- @see db:fetch
function db:lte(field, value)
   local v = db:_coerce(field, value)
   return field.name.." &lt;= "..v
end



--- Returns a database expression to test if the field in the sheet is greater than to the value.
---
--- @see db:fetch
function db:gt(field, value)
   local v = db:_coerce(field, value)
   return field.name.." &gt; "..v
end



--- Returns a database expression to test if the field in the sheet is greater than or equal to the value.
---
--- @see db:fetch
function db:gte(field, value)
   local v = db:_coerce(field, value)
   return field.name.." &gt;= "..v
end



--- Returns a database expression to test if the field in the sheet is nil.
---
--- @see db:fetch
function db:is_nil(field)
   return field.name.." IS NULL"
end



--- Returns a database expression to test if the field in the sheet is not nil.
---
--- @see db:fetch
function db:is_not_nil(field)
   return field.name.." IS NOT NULL"
end



--- Returns a database expression to test if the field in the sheet matches the specified pattern. &lt;br/&gt;&lt;br/&gt;
---
--- LIKE patterns are not case-sensitive, and allow two wild cards. The first is an underscore which matches
--- any single one character. The second is a percent symbol which matches zero or more of any character.
---   &lt;pre&gt;
---   LIKE with "_" is therefore the same as the "." regular expression.
---   LIKE with "%" is therefore the same as ".*" regular expression.
---   &lt;/pre&gt;
---
--- @see db:not_like
--- @see db:fetch
function db:like(field, value)
   local v = db:_coerce(field, value)
   return field.name.." LIKE "..v
end



--- Returns a database expression to test if the field in the sheet does not match the specified pattern.
---
--- LIKE patterns are not case-sensitive, and allow two wild cards. The first is an underscore which matches
--- any single one character. The second is a percent symbol which matches zero or more of any character.
---   &lt;pre&gt;
---   LIKE with "_" is therefore the same as the "." regular expression.
---   LIKE with "%" is therefore the same as ".*" regular expression.
---   &lt;/pre&gt;
---
--- @see db:like
--- @see db:fetch
function db:not_like(field, value)
   local v = db:_coerce(field, value)
   return field.name.." NOT LIKE "..v
end



--- Returns a database expression to test if the field in the sheet is a value between lower_bound and upper_bound.
--- This only really makes sense for numbers and Timestamps.
---
--- @see db:not_between
--- @see db:fetch
function db:between(field, left_bound, right_bound)
   local x = db:_coerce(field, left_bound)
   local y = db:_coerce(field, right_bound)
   return field.name.." BETWEEN "..x.." AND "..y
end



--- Returns a database expression to test if the field in the sheet is NOT a value between lower_bound and upper_bound.
--- This only really makes sense for numbers and Timestamps.
---
--- @see db:between
--- @see db:fetch
function db:not_between(field, left_bound, right_bound)
   local x = db:_coerce(field, left_bound)
   local y = db:_coerce(field, right_bound)
   return field.name.." NOT BETWEEN "..x.." AND "..y
end



--- Returns a database expression to test if the field in the sheet is one of the values in the table array. &lt;br/&gt;&lt;br/&gt;
---
--- First, note the trailing underscore carefully! It is required.
---
--- @usage The following example illustrates the use of &lt;b&gt;in_&lt;/b&gt;:
---   This will obtain all of your kills which happened in the Undervault, Hell or Purgatory. Every db:in_ expression
---   can be written as a db:OR, but that quite often gets very complex.
---   &lt;pre&gt;
---   local mydb = db:get_database("my database")
---   local areas = {"Undervault", "Hell", "Purgatory"}
---   db:fetch(mydb.kills, db:in_(mydb.kills.area, areas))
---   &lt;/pre&gt;
---
--- @see db:fetch
function db:in_(field, tbl)
   local parts = {}
   for _, v in ipairs(tbl) do
      parts[#parts+1] = db:_coerce(field, v)
   end

   return field.name.." IN ("..table.concat(parts, ",")..")"
end



--- Returns a database expression to test if the field in the sheet is not one of the values in the table array.
---
--- @see db:in_
--- @see db:fetch
function db:not_in(field, tbl)
   local parts = {}
   for _, v in ipairs(tbl) do
      parts[#parts+1] = db:_coerce(field, v)
   end

   return field.name.." NOT IN ("..table.concat(parts, ",")..")"
end



--- Returns the string as-is to the database. &lt;br/&gt;&lt;br/&gt;
---
--- Use this function with caution, but it is very useful in some circumstances. One of the most
--- common of such is incrementing an existing field in a db:set() operation, as so:
---   &lt;pre&gt;
---   db:set(mydb.enemies, db:exp("kills + 1"), db:eq(mydb.enemies.name, "Ixokai"))
---   &lt;/pre&gt;
---
--- This will increment the value of the kills field for the row identified by the name Ixokai. &lt;br/&gt;&lt;br/&gt;
---
--- But there are other uses, as the underlining database layer provides many functions you can call
--- to do certain things. If you want to get a list of all your enemies who have a name longer then
--- 10 characters, you may do:
---   &lt;pre&gt;
---   db:fetch(mydb.enemies, db:exp("length(name) &gt; 10"))
---   &lt;/pre&gt;
---
--- Again, take special care with this, as you are doing SQL syntax directly and the library can't
--- help you get things right.
---
--- @see db:fetch
function db:exp(text)
   return text
end



--- Returns a compound database expression that combines all of the simple expressions passed into it.
--- These expressions should be generated with other db: functions such as db:eq, db:like, db:lt and the like. &lt;br/&gt;&lt;br/&gt;
---
--- This compound expression will only find items in the sheet if all sub-expressions match.
---
--- @see db:fetch
function db:AND(...)
   local parts = {}

   for _, expression in ipairs({...}) do
      parts[#parts+1] = "("..expression..")"
   end

   return "("..table.concat(parts, " AND ")..")"
end



--- Returns a compound database expression that combines both of the simple expressions passed into it.
--- These expressions should be generated with other db: functions such as db:eq, db:like, db:lt and the like. &lt;br/&gt;&lt;br/&gt;
---
--- This compound expression will find any item that matches either the first or the second sub-expression.
---
--- @see db:fetch
function db:OR(left, right)
   if not string.starts(left, "(") then
      left = "("..left..")"
   end

   if not string.starts(right, "(") then
      right = "("..right..")"
   end

   return left.." OR "..right
end



--- &lt;b&gt;&lt;u&gt;TODO&lt;/u&gt;&lt;/b&gt;
function db:close()
   for _, c in pairs(db.__conn) do
      c:close()
   end
   db.__conn = {}
   db.__env:close()
   db.__env = nil
end



-- Timestamp support
db.__Timestamp = {}



db.__TimestampMT = {
   __index = db.__Timestamp
}


function db.__Timestamp:as_string(format)
   if not format then
      format = "%m-%d-%Y %H:%M:%S"
   end

   -- given how we have an as_string function, having to wrap it in tostring() is a bit silly. So in this case, return nil as a string
   if type(self._timestamp) ~= "number" then return "nil", "db.Timestamp:as_string: timestamp seems to be invalid and isn't a number" end

   return os.date(format, self._timestamp)
end

function db.__Timestamp:as_table()
   if type(self._timestamp) ~= "number" then return nil, "db.Timestamp:as_table: timestamp seems to be invalid and isn't a number" end

   return os.date("*t", self._timestamp)
end

function db.__Timestamp:as_number()
   if type(self._timestamp) ~= "number" then return nil, "db.Timestamp:as_number: timestamp seems to be invalid and isn't a number" end

   return self._timestamp
end

function db.__Timestamp:set(timestamp)
   assert(type(timestamp) == "number", "db.Timestamp:set: timestamp needs to be a number")

   self._timestamp = timestamp
end


--- &lt;b&gt;&lt;u&gt;TODO&lt;/u&gt;&lt;/b&gt;
function db:Timestamp(ts, fmt)
   local dt = {}
   if type(ts) == "table" then
      dt._timestamp = os.time(ts)
   elseif type(ts) == "number" then
      dt._timestamp = ts
   elseif type(ts) == "string" and
           assert(ts == "CURRENT_TIMESTAMP", "The only strings supported by db.DateTime:new is CURRENT_TIMESTAMP") then
      dt._timestamp = "CURRENT_TIMESTAMP"
   elseif ts == nil then
      dt._timestamp = false
   else
      assert(nil, "Invalid value passed to db.Timestamp()")
   end
   return setmetatable(dt, db.__TimestampMT)
end



db.Field = {}
db.__FieldMT = {
   __index = db.Field
}



db.Sheet = {}
db.__SheetMT = {
   __index = function(t, k)
      local v = rawget(db.Sheet, k)
      if v then
         return v
      end

      local db_name = rawget(t, "_db_name")
      local sht_name = rawget(t, "_sht_name")
      local f_name = k

      local errormsg = "Attempt to access field %s in sheet %s in database %s that does not exist."

      local field = db.__schema[db_name][sht_name]['columns'][f_name]
      if assert(field, errormsg:format(k, sht_name, db_name)) then
         type_ = type(field)
         if type_ == "table" and field._timestamp then
            type_ = "datetime"
         end

         rt = setmetatable({database=db_name, sheet=sht_name, type=type_, name=f_name}, db.__FieldMT)
         rawset(t,k,rt)
         return rt
      end

   end
}



db.Database = {}
db.__DatabaseMT = {
   __index = function(t, k)
      local v = rawget(t, k)
      if v then
         return v
      end

      local v = rawget(db.Database, k)
      if v then
         return v
      end

      local db_name = rawget(t, "_db_name")
      if assert(db.__schema[db_name][k], "Attempt to access sheet '"..k.."'in db '"..db_name.."' that does not exist.") then
         rt = setmetatable({_db_name = db_name, _sht_name = k}, db.__SheetMT)
         rawset(t,k,rt)
         return rt
      end
   end
}



function db.Database:_begin()
   db.__autocommit[self._db_name] = false
end



function db.Database:_commit()
   local conn = db.__conn[self._db_name]
   conn:commit()
end



function db.Database:_rollback()
   local conn = db.__conn[self._db_name]
   conn:rollback()
end



function db.Database:_end()
   db.__autocommit[self._db_name] = true
end



function db.Database._drop(s_name)
   local conn = db.__conn[self._db_name]
   local schema = db.__schema[self._db_name]

   if schema.options._index then
      for _, value in schema.options._index do
         conn:execute("DROP INDEX IF EXISTS " .. db:_index_name(s_name, value))
      end
   end

   if schema.options._unique then
      for _, value in schema.options._unique do
         conn:execute("DROP INDEX IF EXISTS " .. db:_index_name(s_name, value))
      end
   end

   conn:execute("DROP TABLE IF EXISTS "..s_name)
   conn:commit()
end



--- Returns a reference of an already existing database. This instance can be used to get references
--- to the sheets (and from there, fields) that are defined within the database. You use these
--- references to construct queries. &lt;br/&gt;&lt;br/&gt;
---
--- These references do not contain any actual data, they only point to parts of the database structure.
---
--- @usage If a database has a sheet named enemies, you can obtain a reference to that sheet by simply doing:
---   &lt;pre&gt;
---   local mydb = db:get_database("my database")
---   local enemies_ref = mydb.enemies
---   local name_ref = mydb.enemies.name
---   &lt;/pre&gt;
function db:get_database(db_name)
   db_name = db:safe_name(db_name)
   assert(db.__schema[db_name], "Attempt to access database that does not exist.")

   db_inst = {_db_name = db_name}
   return setmetatable(db_inst, db.__DatabaseMT)
end

--- Queries for database content matching the given example. Different fields of
--- the example are AND connected.
--- &lt;/br&gt;
--- Field values should be strings and can contain the following values:
--- &lt;ul&gt;
---   &lt;li&gt;literal strings to search for
---   &lt;li&gt;comparison terms prepended with &amp;lt;, &amp;gt;, &amp;gt;=, &amp;lt;=, !=, &amp;lt;&amp;gt;
---       for number and date comparisons
---   &lt;li&gt;ranges with :: between lower and upper bound
---   &lt;li&gt;different single values combined by || as OR
---   &lt;li&gt;strings containing % for a single and _ for multiple wildcard
---       characters
--- &lt;/ul&gt;
--- &lt;br/&gt;
--- @param database Reference to the database that should be queried.
--- @param example  Query prototype that should be searched for.
--- @usage This example shows, how to use this function:
---   &lt;pre&gt;
---      mydb = db:create("mydb",
---        {
---          sheet = {
---            name = "", id = 0, city = "",
---            _index = { "name" },
---            _unique = { "id" },
---            _violations = "FAIL"
---          }
---        })
---      test_data = {
---        {name="Ixokai", city="Magnagora", id=1},
---        {name="Vadi", city="New Celest", id=2},
---        {name="Heiko", city="Hallifax", id=3},
---        {name="Keneanung", city="Hashan", id=4},
---        {name="Carmain", city="Mhaldor", id=5},
---        {name="Ixokai", city="Hallifax", id=6},
---      }
---      db:add(mydb.sheet, unpack(test_data))
---      res = db:query_by_example(mydb.sheet, { name = "Ixokai"})
---      display(res)
---      --[[
---      Prints
---      {
---        {
---          id = 1,
---          name = "Ixokai",
---          city = "Magnagora"
---        },
---        {
---          id = 6,
---          name = "Ixokai",
---          city = "Hallifax"
---        }
---      }
---      --]]
---   &lt;/pre&gt;
---
--- @usage This example shows, how to combine two fields:
---   &lt;pre&gt;
---      mydb = db:create("mydb",
---        {
---          sheet = {
---            name = "", id = 0, city = "",
---            _index = { "name" },
---            _unique = { "id" },
---            _violations = "FAIL"
---          }
---        })
---      test_data = {
---        {name="Ixokai", city="Magnagora", id=1},
---        {name="Vadi", city="New Celest", id=2},
---        {name="Heiko", city="Hallifax", id=3},
---        {name="Keneanung", city="Hashan", id=4},
---        {name="Carmain", city="Mhaldor", id=5},
---      }
---      db:add(mydb.sheet, unpack(test_data))
---      res = db:query_by_example(mydb.sheet, { name = "Ixokai", id = "1"})
---      display(res)
---      --[[
---      Prints
---      {
---        id = 1,
---        name = "Ixokai",
---        city = "Magnagora"
---      }
---      --]]
---   &lt;/pre&gt;
function db:query_by_example(database, example)

   if table.is_empty(example) then return nil end

   local topLevel = {}
   local find = string.find
   local match = string.match

   for key, value in pairs(example) do

      value = string.trim(value)

      local op, exp = match(value, "^%s*([&lt;&gt;=!]*)%s*(.*)$")

      if op == "&lt;" then
         topLevel[#topLevel + 1] = db:lt(database[key], exp)
      elseif op == "&gt;" then
         topLevel[#topLevel + 1] = db:gt(database[key], exp)
      elseif op == "&gt;=" then
         topLevel[#topLevel + 1] = db:gte(database[key], exp)
      elseif op == "&lt;=" then
         topLevel[#topLevel + 1] = db:lte(database[key], exp)
      elseif op == "!=" or op == "&lt;&gt;" then
         if find(exp, "__NULL__", 1, true) then
            topLevel[#topLevel + 1] = db:is_not_nil(database[key])
         else
            topLevel[#topLevel + 1] = db:not_eq(database[key], exp)
         end
      else
         if find(value, "%s*||%s*") then
            topLevel[#topLevel + 1] = db:in_(database[key], string.split(value,
"%s*||%s*"))
         elseif find(value, "__NULL__", 1, true) then
            topLevel[#topLevel + 1] = db:is_nil(database[key])
         elseif find(value, "_", 1, true) or find(value, "%", 1, true) then
            topLevel[#topLevel + 1] = db:like(database[key], value)
         elseif find(value, "::", 1, true) then
            topLevel[#topLevel + 1] = db:between(database[key], match(value, "^(.-)::(.+)$"))
         else
            topLevel[#topLevel + 1] = db:eq(database[key], value)
         end
      end

   end

   return db:AND(unpack(topLevel))
end

end</script>
				<eventHandlerList />
			</Script>
			<Script isActive="yes" isFolder="no">
				<name>init mpkg</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
mpkg = mpkg or { }
mpkg.database = db:create("MudletPackageManager", {
	repositories = {
		name = "",
		url = "",
		description = "",
		_unique = {"name"},
		_violations = "REPLACE"
	},
	packages = {
		name = "",
		version = "",
		installed = "",
		url = "",
		description = "",
		author = "",
    updated_on = "",
		repository = "",
		extension = "",
		_index = { "name" }
	},
	dependencies = {
		name = "",
		dependency = "",
		repository = "",
		_index = { "name" }
	}
})

mpkg.transaction = mpkg.transaction or { }
if db:aggregate(mpkg.database.packages.name, "COUNT") == 0 then
	db:add(mpkg.database.packages, {name = "MudletPackageManager", version = "0.0.4", installed = "0.0.4", url = "http://keneanung.gitlab.io/MudletPackageManager/MudletPackageManager.xml", author = "Keneanung",
			description = "The Mudlet Package Manager", repository = "MudletPackageManager", extension = "xml" } )
	db:add(mpkg.database.repositories, {name = "MudletPackageManager", url = "http://keneanung.gitlab.io/MudletPackageManager/repository.json",
			description = "The bootstrap repository for the mudlet package manager." } )
end</script>
				<eventHandlerList />
			</Script>
			<Script isActive="yes" isFolder="no">
				<name>config</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
mpkg.config = {
	locale = "en-US"
}
</script>
				<eventHandlerList />
			</Script>
			<Script isActive="yes" isFolder="no">
				<name>functions</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
mpkg.functions = {

	checkCache = function()
		local success, error = true, ""
		if not lfs.attributes(getMudletHomeDir() .. "/mpkg") then
			success, error = lfs.mkdir(getMudletHomeDir() .. "/mpkg")
		end
		if success and not lfs.attributes(getMudletHomeDir() .. "/mpkg/cache") then
			success, error = lfs.mkdir(getMudletHomeDir() .. "/mpkg/cache")
		end
		return success, error
	end,

	checkDependencies = function(name, repository, queue)

		local dependencyTable	= mpkg.database.dependencies
		local packageTable		= mpkg.database.packages

		local functions				= mpkg.functions
		local checkDependencies	= functions.checkDependencies
		local fetchByExample		= functions.fetchByExample
		local bestCandidate		= functions.bestCandidate

		local dependencies = fetchByExample(dependencyTable, { name = name, repository = repository })

		for _, dep in ipairs(dependencies) do
			local installedDependency = fetchByExample(packageTable, { name = dep.dependency, installed = "!=" })

			if table.is_empty(installedDependency) then
				local success, dependencyPackage = bestCandidate(fetchByExample(packageTable, { name = dep.dependency }))

				if success then
					local found
					local filename = string.format("%s.%s", dependencyPackage.name, dependencyPackage.extension)
					for _, queueItem in ipairs(queue) do
						if queueItem.name == filename then
							found = true
						end
					end
					if not found then
						table.insert(queue, 1, {name = filename, url= dependencyPackage.url})
						checkDependencies(dependencyPackage.name, dependencyPackage.repository, queue)
					end
				end
			end
		end
	end,

	bestCandidate = function(packageList)

		local localization	= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localization.general
		local locPackage	= localization.package

		if not packageList or type(packageList)~="table" then
			return false, locGeneral.invalidParameterType:format("packageList", type(packageList), "table")
		end

		if table.is_empty(packageList) then
			return false, locGeneral.emptyTable
		end

		local bestPackage = packageList[1]

		for _, package in ipairs(packageList) do
			if package.name ~= bestPackage.name then
				return false, locPackage.nameMismatch
			end
			if mpkg.functions.greaterVersion(bestPackage.version, package.version) then
				bestPackage = package
			end
		end
		return true, bestPackage
	end,

	greaterVersion = function(baseVersion, newVersion)
		local base = baseVersion:split("%.")
		local new = newVersion:split("%.")
		if tonumber(base[1] or 0) &lt; tonumber(new[1] or 0) or tonumber(base[2] or 0) &lt; tonumber(new[2] or 0) or tonumber(base[3] or 0) &lt; tonumber(new[3] or 0) then
			return true
		end
		return false
	end,

	printHelp = function()
		local help = mpkg.localization[mpkg.config.locale].help
		local templates = mpkg.templates
		local header = templates.headerTemplate
		local command = templates.commandHelpTemplate
		local description = templates.helpDescriptionTemplate

		for _, headerEntry in ipairs(help.headers) do
			cecho(header:format(headerEntry))
		end
		for _, helpEntry in ipairs(help.entries) do
			cechoLink(command:format(helpEntry.command), helpEntry.action, helpEntry.command, true)
      moveCursorEnd()
      moveCursor(1, getLineNumber()-1)
      selectString(helpEntry.command,1)
      setUnderline(true)
      resetFormat()
			for _, descriptionLine in ipairs(helpEntry.description) do
				cecho(description:format(descriptionLine))
			end
		end
	end,

	addRepo = function(name, url, description)

		local templates		= mpkg.templates
		local propTemplate	= templates.propertyLineTemplate

		local localized		= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localized.general
		local locRepo		= localized.repo

		local  newRepo = {
			name = name,
			url = url, 
			description = description
		}

		local res, error = db:add(mpkg.database.repositories, newRepo)

		if res then
			cecho(templates.headerTemplate:format(locRepo.successfullAddMessage))
			cecho(propTemplate:format(locGeneral.name, newRepo.name))
			cecho(propTemplate:format(locGeneral.url, newRepo.url))
			cecho(propTemplate:format(locGeneral.description, newRepo.description))
		else
			cecho(templates.errorTemplate:format(locRepo.addError))
			cecho(error)
		end
	end,

	fetchByExample = function(dbTable, example)
		return db:fetch(dbTable, db:query_by_example(dbTable, example))
	end,

	listRepos = function()
		local repoList = db:fetch(mpkg.database.repositories)
		cecho(mpkg.templates.headerTemplate:format(mpkg.localization[mpkg.config.locale].repo.listHeader))
		for _, repo in ipairs(repoList) do
			cecho(mpkg.templates.propertyLineTemplate:format(repo.name, repo.url))
		end
	end,

	repoInfo = function(pattern)

		local templates			= mpkg.templates
		local propTemplate		= templates.propertyLineTemplate
		local headerTemplate	= templates.headerTemplate

		local localized		= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localized.general

		local foundRepositories = mpkg.functions.fetchByExample(mpkg.database.repositories, { name = pattern } )
		if #foundRepositories &gt; 0 then
			for _, repo in ipairs(foundRepositories) do
				cecho(headerTemplate:format(repo.name))
				cecho(propTemplate:format(locGeneral.url, repo.url))
				cecho(propTemplate:format(locGeneral.description, repo.description))
			end
		else
			cecho(headerTemplate:format(localized.repo.notFound:format(pattern)))
		end
	end,

	deleteRepo = function(pattern)

		local headerTemplate	= mpkg.templates.headerTemplate

		local locRepo		= mpkg.localization[mpkg.config.locale].repo

		local foundRepositories = mpkg.functions.fetchByExample(mpkg.database.repositories, { name = pattern } )
		if #foundRepositories &gt; 0 then
			for _, repo in ipairs(foundRepositories) do
				db:delete(mpkg.database.repositories, db:query_by_example(mpkg.database.repositories, { name = repo.name } ))
				cecho(headerTemplate:format(locRepo.removeSuccessful:format(repo.name)))
			end
		else
			cecho(headerTemplate:format(locRepo.notFound:format(pattern)))
		end
	end,

	update = function()

		local templates			= mpkg.templates
		local errorTemplate	= templates.errorTemplate

		local localized		= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localized.general

		local success, error = mpkg.functions.checkCache()
		if not success then
			cecho(errorTemplate:format(locGeneral.cacheCreationFailed))
			cecho(error)
			return
		end
		local repositories = db:fetch(mpkg.database.repositories)
		if not mpkg.transaction.type then
			cecho(templates.headerTemplate:format(localized.repo.updateStart))
			mpkg.transaction.type = "update"
			mpkg.transaction.argument = #repositories
		else
			cecho(errorTemplate:format(locGeneral.alreadyProcessing:format(mpkg.transaction.type)))
			return
		end
		for _, repository in ipairs(repositories) do
			downloadFile(getMudletHomeDir() .. "/mpkg/cache/" .. repository.name, repository.url)
		end
	end,

	packageList = function()

		local templates					  = mpkg.templates
		local packageListTemplate	= templates.packageListTemplate
		local localized					  = mpkg.localization[mpkg.config.locale]
		local locInstalled				= localized.general.installed
		local locInstall          = localized.general.install
		local locUninstall        = localized.general.uninstall
    local locUpgradable       = localized.general.upgradable

		local packageList = db:fetch(mpkg.database.packages)
		cecho(templates.headerTemplate:format(localized.package.listHeader))
		for _, package in ipairs(packageList) do
			cechoLink(packageListTemplate:format(package.name, package.installed ~= "" and package.installed or package.version, 
			package.repository, package.installed ~= "" and locInstalled or ""), 
			package.installed ~= "" and "mpkg.functions.uninstall('"..package.name.."')" or "mpkg.functions.install('"..package.name.."')", 
			package.installed ~= "" and locUninstall or locInstall, true)
			cechoLink(package.installed ~= "" and mpkg.functions.greaterVersion(package.installed, package.version) and 
			templates.upgradableTemplate:format(locUpgradable:format(package.version)) or "\n", 
			"mpkg.functions.upgrade()", "mpkg upgrade", true)
      
      moveCursorEnd()
      moveCursor(1, getLineNumber()-1)
      selectString(package.name,1)
      setUnderline(true)
      resetFormat()
		end
    		echo("\n")
	end,

	packageInfo = function(name)

		local fetchByExample = mpkg.functions.fetchByExample

		local templates			= mpkg.templates
		local propertyLine		= templates.propertyLineTemplate
		local headerTemplate	= templates.headerTemplate

		local localized		= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localized.general

		local foundPackages = fetchByExample(mpkg.database.packages, { name = name } )
		if #foundPackages &gt; 0 then
			for _, pkg in ipairs(foundPackages) do
				local dependencies = fetchByExample(mpkg.database.dependencies, { name = pkg.name } )
				cecho(headerTemplate:format(pkg.name))
				cecho(propertyLine:format(locGeneral.repository, pkg.repository))
				cecho(propertyLine:format(locGeneral.version, pkg.version))
				cecho(propertyLine:format(locGeneral.installedVersion , pkg.installed ~= "" and pkg.installed or locGeneral.none))
				cecho(propertyLine:format(locGeneral.author, pkg.author))
				cecho(propertyLine:format(locGeneral.description, pkg.description))
				cecho(propertyLine:format(locGeneral.updated_on, pkg.updated_on))
				local dependencyString = ""
				for num, dep in ipairs(dependencies) do
					dependencyString = dependencyString .. (num &gt; 1 and ", " or "") .. dep.dependency
				end
				cecho(propertyLine:format(locGeneral.dependencies, dependencyString))
			end
		else
			cecho(headerTemplate:format(localized.package.notFound:format(name)))
		end
	end,

	install = function(packageName)
		local warningTemplate = mpkg.templates.warningTemplate
		local errorTemplate = mpkg.templates.errorTemplate

		local localization	= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localization.general
		local locPackage	= localization.package

		local packageList = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, { name = packageName, installed = "!=" } ))

		if not table.is_empty(packageList) then
			cecho(warningTemplate:format(locPackage.alreadyInstalled:format(packageName)))
			return
		end

		packageList = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, { name = packageName } ))

		if table.is_empty(packageList) then
			cecho(warningTemplate:format(locPackage.notFound:format(packageName)))
			return
		end

		local success, package = mpkg.functions.bestCandidate(packageList)

		if not success then
			cecho(warningTemplate:format(package))
			return
		end

		local error
		success, error = mpkg.functions.checkCache()

		if not success then
			cecho(errorTemplate:format(locGeneral.cacheCreationFailed))
			cecho(error)
		end

		if mpkg.transaction.type then
			cecho(errorTemplate:format(locGeneral.alreadyProcessing:format(mpkg.transaction.type)))
			return
		end
		cecho(mpkg.templates.infoTemplate:format(locPackage.installing:format(package.name)))
		mpkg.transaction.type = "install"
		mpkg.transaction.argument = { { name = package.name .. "." ..package.extension, url = package.url} }
		mpkg.functions.checkDependencies(package.name, package.repository, mpkg.transaction.argument)
		downloadFile(getMudletHomeDir() .. "/mpkg/cache/" .. mpkg.transaction.argument[1].name, mpkg.transaction.argument[1].url)
	end,

	uninstall = function(pattern)
		local locPackage = mpkg.localization[mpkg.config.locale].package

		local package = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, { name = pattern, installed = "!=" } ))

		if #package &gt; 1 then
			cecho(mpkg.templates.errorTemplate:format(locPackage.multipleFound:format(pattern)))
			return
		end

		if table.is_empty(package) then
			cecho(mpkg.templates.warningTemplate:format(locPackage.notInstalled:format(pattern)))
			return
		end

		uninstallPackage(package[1].name)

		package[1].installed = ""
		db:update(mpkg.database.packages, package[1])
		cecho(mpkg.templates.infoTemplate:format(locPackage.finishedUninstalling:format(package[1].name)))
	end,

	upgrade = function()
		local errorTemplate	= mpkg.templates.errorTemplate

		local localization	= mpkg.localization[mpkg.config.locale]
		local locGeneral	= localization.general

		local installedPackages = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, {installed = "!="}))

		local success, error = mpkg.functions.checkCache()
		if not success then
			cecho(errorTemplate:format(locGeneral.cacheCreationFailed))
			cecho(error)
			return
		end

		if mpkg.transaction.type then
			cecho(errorTemplate:format(locGeneral.alreadyProcessing:format(mpkg.transaction.type)))
			return
		end

		mpkg.transaction.argument = {}
		for _, installedPackage in ipairs(installedPackages) do
			local samePackages = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, { name = installedPackage.name } ))
			local candidate = { reference = installedPackage.installed }

			for _, package in ipairs(samePackages) do
				if mpkg.functions.greaterVersion(candidate.reference, package.version) then
					candidate.best = package
					candidate.reference = package.version
				end
			end

			if candidate.best then
					cecho(mpkg.templates.warningTemplate:format(localization.package.upgradeStaged:format(candidate.best.name, candidate.best.version)))
					mpkg.transaction.type = "upgrade"
					mpkg.transaction.argument[#mpkg.transaction.argument+1] = { name = candidate.best.name, url = candidate.best.url }
			end


		end

		if #mpkg.transaction.argument &gt; 0 then
			downloadFile(getMudletHomeDir() .. "/mpkg/cache/" .. mpkg.transaction.argument[1].name, mpkg.transaction.argument[1].url)
		end

	end,

	finishedDownload = function(event, file)

		local errorTemplate	= mpkg.templates.errorTemplate
		local infoTemplate		= mpkg.templates.infoTemplate

		local localized		= mpkg.localization[mpkg.config.locale]
		local locRepo		= localized.repo
		local locPackage	= localized.package

		local fileName = file:match(".+/([%w-.]+)%.%w+$") or file:match(".+/([%w-.]+)$")
		local fileNameExt = file:match(".+/(.-)$")
		if mpkg.transaction.type == "update" and
			not table.is_empty(db:fetch(mpkg.database.repositories, db:query_by_example(mpkg.database.repositories, {name = fileName})))
		then

			local filePointer = io.open(file, "r")
			local str = filePointer:read("*all")
			local packages = yajl.to_value(str)

			db:delete(mpkg.database.packages, db:AND(db:eq(mpkg.database.packages.repository, fileName), db:eq(mpkg.database.packages.installed, "")))

			for _, currentPackage in ipairs(packages) do

				local knownPackage = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, {name = currentPackage.name, repository = fileName}))[1]

				if knownPackage then
					knownPackage.version = currentPackage.version
					knownPackage.url = currentPackage.url
					knownPackage.author = currentPackage.author
					knownPackage.updated_on = currentPackage.updated_on
					knownPackage.description = currentPackage.description
					knownPackage.extension = currentPackage.extension
					db:update(mpkg.database.packages, knownPackage)
				else
					local ret, error = db:add(mpkg.database.packages, { name = currentPackage.name,
							url = currentPackage.url,
							version = currentPackage.version,
							author = currentPackage.author,
							updated_on = currentPackage.updated_on,
							repository = fileName,
							description = currentPackage.description,
							extension = currentPackage.extension })
					if not ret then
						cecho(errorTemplate:format(locRepo.addNewPackageFailed))
						cecho(error)
					end
				end

				db:delete(mpkg.database.dependencies, db:query_by_example(mpkg.database.dependencies, {name = currentPackage.name, repository = fileName}))
				currentPackage.dependencies = currentPackage.dependencies and string.split(string.gsub(currentPackage.dependencies,"%s",""),",") or {}
				for _, dependency in ipairs(currentPackage.dependencies) do
					db:add(mpkg.database.dependencies, { 
						name = currentPackage.name,
						dependency = dependency,
						repository = fileName })
				end

			end

			cecho(infoTemplate:format(locRepo.updateFinishedRepo:format(fileName)))
			mpkg.transaction.argument = mpkg.transaction.argument - 1
			if mpkg.transaction.argument == 0 then
				cecho(infoTemplate:format(locRepo.updateFinishedAll))
				mpkg.transaction.type = nil
			else
				cecho(infoTemplate:format(locRepo.updateProgress:format(mpkg.transaction.argument)))
			end

		elseif (mpkg.transaction.type == "install" or mpkg.transaction.type == "upgrade") and
			mpkg.transaction.argument[1].name == fileNameExt
		then
			uninstallPackage(fileName)
			installPackage(file)

			local package = db:fetch(mpkg.database.packages, db:query_by_example(mpkg.database.packages, {name = fileName, url = mpkg.transaction.argument[1].url}))[1]

			package.installed = package.version
			db:update(mpkg.database.packages, package)

			table.remove(mpkg.transaction.argument, 1)
				cecho(infoTemplate:format(locPackage.finishedInstalling:format(fileName)))
			if table.is_empty(mpkg.transaction.argument) then
				cecho(infoTemplate:format(locPackage.finishedInstallingAll))
				mpkg.transaction.type = nil
			else
				cecho(infoTemplate:format(locPackage.installProgress:format(#mpkg.transaction.argument)))
				downloadFile(getMudletHomeDir() .. "/mpkg/cache/" .. mpkg.transaction.argument[1].name, mpkg.transaction.argument[1].url)
			end
		end
		return true
	end,

	failedDownload = function(event, message, file)

		local templates			= mpkg.templates
		local errorTemplate	= templates.errorTemplate
		local infoTemplate		= templates.infoTemplate

		local localized		= mpkg.localization[mpkg.config.locale]
		local locRepo		= localized.repo
		local locPackage	= localized.package

		local fileName = file:match(".+/(.-)$")
		if mpkg.transaction.type == "update" and
			not table.is_empty(db:fetch(mpkg.database.repositories, db:query_by_example(mpkg.database.repositories, {name = fileName})))
		then

			cecho(errorTemplate:format(locRepo.couldNotUpdate:format(fileName)))
			cecho(message .. "\n")
			mpkg.transaction.argument = mpkg.transaction.argument - 1
			if mpkg.transaction.argument == 0 then
				cecho(infoTemplate:format(locRepo.updateFinishedAll))
				mpkg.transaction.type = nil
			else
				cecho(infoTemplate:format(locRepo.updateProgress:format(mpkg.transaction.argument)))
			end

		elseif (mpkg.transaction.type == "install" or mpkg.transaction.type == "upgrade") and
			mpkg.transaction.argument[1].name == fileName
		then
			cecho(errorTemplate:format(locPackage.couldNotInstall:format(fileName)))
			cecho(message .. "\n")
			table.remove(mpkg.transaction.argument, 1)
			if table.is_empty(mpkg.transaction.argument) then
				cecho(errorTemplate:format(locPackage.finishedInstallingAll:format()))
				mpkg.transaction.type = nil
			else
				cecho(infoTemplate:format(locPackage.installProgress:format(#mpkg.transaction.argument)))
				downloadFile(getMudletHomeDir() .. "/mpkg/cache/" .. mpkg.transaction.argument[1].name, mpkg.transaction.argument[1].url)
			end
		end
		return true
	end,
	
	tryCatch = function(fun)
		local errorTemplate = mpkg.templates.errorTemplate
		local locPackage = mpkg.localization[mpkg.config.locale].package
	  return function(...)
	    local ret, message = pcall(fun, ...)
			if not ret then
			  cecho(errorTemplate:format(locPackage.couldNotInstall:format(mpkg.transaction.argument[1].name)))
				cecho(errorTemplate:format(message))
				mpkg.transaction = {}
			end
		end
	end,
}</script>
				<eventHandlerList />
			</Script>
			<Script isActive="yes" isFolder="no">
				<name>templates</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
mpkg.templates = {
	headerTemplate					  = "&lt;green&gt;%s&lt;reset&gt;\n",												          --template for headers
	propertyLineTemplate			= "  &lt;orange&gt;%s:&lt;reset&gt; %s\n",										      --template for detailed information 
																													                          --on one line. First argument is the 
																													                          --property, second its value

	commandHelpTemplate			 = "  &lt;orange&gt;%s&lt;reset&gt;\n",											          --help template for commands
  upgradableTemplate			 = "  &lt;red&gt;(%s)&lt;reset&gt;\n",											          --help template for upgradable
	helpDescriptionTemplate	 = "    %s\n",															              --help template for the descriptions
																													                          --of a command

	errorTemplate					  = "&lt;red&gt;%s&lt;reset&gt;\n",													            --template for error messages
	warningTemplate					= "&lt;orange&gt;%s&lt;reset&gt;\n",												          --template for warnings
	infoTemplate						= "&lt;green&gt;%s&lt;reset&gt;\n",												            --template for informational output
	packageListTemplate			= "  &lt;orange&gt;%s (%s) &lt;reset&gt;from %s &lt;green&gt;%s&lt;reset&gt;",		--template for a line in the package
																													                          --list
}</script>
				<eventHandlerList />
			</Script>
			<Script isActive="yes" isFolder="no">
				<name>localization</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
mpkg.localization = {

	["en-US"] = {

		help = {
			headers = {
				"Help of the Mudlet Package Manager.",
				"The following commands are available:"
			},

			entries = {

				{ 
					command     = "mpkg help",
					description = {"Displays this help text."},
					action      =  "mpkg.functions.printHelp()"
				},
				{
					command     = "mpkg repo add \&lt;name\&gt; \&lt;URL\&gt; \&lt;Description\&gt;",
          description = {"Adds a new repository with name, URL and description to the database of known repositories."},
          action      =  "printCmdLine('mpkg repo add')"
				},
				{
					command     = "mpkg repo list",
          description = {"Lists all known repositories."},
          action      =  "mpkg.functions.listRepos()"
				},
				{
					command     = "mpkg repo info \&lt;pattern\&gt;",
					description = {
						"Shows the URL and description of the repositories matching the pattern.",
						"The pattern may contain '_' as single character wildcard and '%' for multiple characters."
                    },
          action      =  "printCmdLine('mpkg repo info')"
				},
				{
					command     = "mpkg repo remove \&lt;pattern\&gt;",
					description = {
						"Removes the matching repositories from the database.",
						"The pattern may contain '_' as single character wildcard and '%' for multiple characters."
                    },
					action      =  "printCmdLine('mpkg repo remove')"
				},
				{
					command     = "mpkg update",
					description = {"Updates the list of available packages on all repositories."},
					action      =  "mpkg.functions.update()"
				},
				{
					command     = "mpkg package list",
					description = {"Lists all known packages."},
					action      =  "mpkg.functions.packageList()"
				},
				{
					command     = "mpkg package info \&lt;pattern\&gt;",
					description = {
						"Shows the URL, version, repository name and description of the packages matching the pattern.",
						"The pattern may contain '_' as single character wildcard and '%' for multiple characters."
                    },
		  			action      =  "printCmdLine('mpkg package info')"
				},
				{
					command     = "mpkg install \&lt;name\&gt;",
					description = {"Installs the package. This will always install the latest version of the package with that name found."},
					action      =  "printCmdLine('mpkg install')"
				},
				{
					command     = "mpkg uninstall \&lt;name\&gt;",
					description = {"Uninstalls the package."},
					action      =  "printCmdLine('mpkg uninstall')"
				},
				{
					command     = "mpkg upgrade",
					description = {"Downloads and installs the latest version of all installed packages."},
					action      =  "mpkg.functions.upgrade()"
				},
			},

		},

		general	= {
			name						      = "Name",
			url							      = "URL",
			description				    = "Description",
			invalidParameterType	= "Invalid parameter %s. Got '%s', expected '%s'.",
			emptyTable				    = "Table is empty.",
			cacheCreationFailed	  = "Unable to create cache directory:",
			alreadyProcessing		  = "There is currently an %s in progress. Please wait for it to finish and try again.",
			installed					    = "installed",
			upgradable            = "upgradable to version %s",
			install               = "Install Package",
			uninstall             = "Uninstall Package",
			none						      = "none",
			despendencies			    = "Dependencies",
			repository				    = "Repository",
			version					      = "Version",
			installedVersion		  = "Installed Version",
			dependencies				  = "Dependencies",
			author                = "Author",
			updated_on            = "Updated on"
		},

		repo		= {
			successfullAddMessage	= "Added new repository to database:",
			addError					    = "Couldn't add repository to database. Reason:",
			listHeader				    = "List of all known repositories:",
			notFound					    = "No repositories matching the pattern '%s' found.",
			removeSuccessful		  = "Successfully removed repository '%s'.",
			updateStart				    = "Updating the list of available packages.",
			addnewPackageFailed	  = "Could not add new package information to database. Reason:",
			updateFinishedRepo		= "Package list of repository '%s' updated.",
			updateFinishedAll		  = "Finished updating package list.",
			updateProgress			  = "Waiting for %s more repository updates to finish.",
			couldNotUpdate			  = "Package list of repository '%s' could not be updated. Reason:",
		},

		package	= {
			nameMismatch				 = "Package names don't match.",
			listHeader				   =  "List of all known packages:",
			notFound					   = "No package matching the pattern '%s' found.",
			alreadyInstalled		 = "Package '%s' is already installed.",
			installing				   = "Installing package '%s'.",
			notInstalled				 = "A package matching '%s' is not installed.",
			multipleFound			   = "Multiple packages matching the pattern '%s' found. Please be more specific, which package you want to uninstall.",
			finishedUninstalling = "Finished uninstalling package '%s'.",
			upgradeStaged			   = "Staging package '%s' for upgrade to version '%s'."	,
			finishedInstalling		= "Finished installing package '%s'.",
			finishedInstallingAll	= "Finished installing all packages.",
			installProgress			  = "%s more packages to install.",
			couldNotInstall			  = "Could not install package '%s'. Reason:"
		},

	}
}</script>
				<eventHandlerList />
			</Script>
			<Script isActive="yes" isFolder="no">
				<name>done loading</name>
				<packageName></packageName>
				<script>-------------------------------------------------
--         Put your Lua functions here.        --
--                                             --
-- Note that you can also use external Scripts --
-------------------------------------------------
registerAnonymousEventHandler("sysDownloadDone", "mpkg.functions.tryCatch(mpkg.functions.finishedDownload)")
registerAnonymousEventHandler("sysDownloadError", "mpkg.functions.tryCatch(mpkg.functions.failedDownload)")
raiseEvent("mpkg done loading")</script>
				<eventHandlerList />
			</Script>
		</ScriptGroup>
	</ScriptPackage>
	<KeyPackage />
	<HelpPackage>
		<helpURL></helpURL>
	</HelpPackage>
</MudletPackage>