Merge pull request #2960 from myk002/myk_attach_item

pipe dfhack.job.attachJobItem through to Lua

docs/changelog.txt

@@ -47,6 +47,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - Gui focus strings will no longer get the "dfhack/" prefix if the string "dfhack/" already exists in the focus string
 
 ## Lua
+- ``dfhack.job.attachJobItem()``: allows you to attach specific items to a job
 - ``dfhack.screen.paintTile()``: you can now explicitly clear the interface cursor from a map tile by passing ``0`` as the tile value
 - ``widgets.Label``: token ``tile`` properties can now be functions that return a value
 -@ ``gui.INTERIOR_FRAME``: a panel frame style for use in highlighting off interior areas of a UI

docs/dev/Lua API.rst

@@ -1219,6 +1219,15 @@ Job module
   if there are any jobs with ``first_id <= id < job_next_id``,
   a lua list containing them.
 
+* ``dfhack.job.attachJobItem(job, item, role, filter_idx, insert_idx)``
+
+  Attach a real item to this job. If the item is intended to satisfy a job_item
+  filter, the index of that filter should be passed in ``filter_idx``; otherwise,
+  pass ``-1``. Similarly, if you don't care where the item is inserted, pass
+  ``-1`` for ``insert_idx``. The ``role`` param is a ``df.job_item_ref.T_role``.
+  If the item needs to be brought to the job site, then the value should be
+  ``df.job_item_ref.T_role.Hauled``.
+
 * ``dfhack.job.isSuitableItem(job_item, item_type, item_subtype)``
 
   Does basic sanity checks to verify if the suggested item type matches

library/LuaApi.cpp

@@ -1659,6 +1659,7 @@ static bool jobItemEqual(const df::job_item *job1, const df::job_item *job2)
 }
 
 static const LuaWrapper::FunctionReg dfhack_job_module[] = {
+    WRAPM(Job,attachJobItem),
     WRAPM(Job,cloneJobStruct),
     WRAPM(Job,printItemDetails),
     WRAPM(Job,printJobDetails),