ox-taskjuggler.el 39 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039
  1. ;;; ox-taskjuggler.el --- TaskJuggler Back-End for Org Export Engine
  2. ;;
  3. ;; Copyright (C) 2007-2018 Free Software Foundation, Inc.
  4. ;;
  5. ;; Emacs Lisp Archive Entry
  6. ;; Filename: ox-taskjuggler.el
  7. ;; Author: Christian Egli
  8. ;; Nicolas Goaziou <n dot goaziou at gmail dot com>
  9. ;; Maintainer: Christian Egli
  10. ;; Keywords: org, taskjuggler, project planning
  11. ;; Description: Converts an Org mode buffer into a TaskJuggler project plan
  12. ;; This file is not part of GNU Emacs.
  13. ;; This program is free software: you can redistribute it and/or modify
  14. ;; it under the terms of the GNU General Public License as published by
  15. ;; the Free Software Foundation, either version 3 of the License, or
  16. ;; (at your option) any later version.
  17. ;; This program is distributed in the hope that it will be useful,
  18. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20. ;; GNU General Public License for more details.
  21. ;; You should have received a copy of the GNU General Public License
  22. ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
  23. ;;; Commentary:
  24. ;;
  25. ;; This library implements a TaskJuggler exporter for Org mode.
  26. ;; TaskJuggler is a project planing tool that uses a text format to
  27. ;; define projects, tasks and resources, so it is a natural fit for
  28. ;; Org mode. It can produce all sorts of reports for tasks or
  29. ;; resources in either HTML, CSV or PDF. TaskJuggler is implemented
  30. ;; in Ruby and should therefore run on any platform.
  31. ;;
  32. ;; The exporter does not export all the nodes of a document or
  33. ;; strictly follow the order of the nodes in the document.
  34. ;;
  35. ;; Instead the TaskJuggler exporter looks for a tree that defines the
  36. ;; tasks and a optionally tree that defines the resources for this
  37. ;; project. It then creates a TaskJuggler file based on these trees
  38. ;; and the attributes defined in all the nodes.
  39. ;;
  40. ;; * Installation
  41. ;;
  42. ;; Put this file into your load-path and the following line into your
  43. ;; ~/.emacs:
  44. ;;
  45. ;; (add-to-list 'org-export-backends 'taskjuggler)
  46. ;;
  47. ;; or customize `org-export-backends' variable.
  48. ;;
  49. ;; The interactive functions are the following:
  50. ;;
  51. ;; M-x `org-taskjuggler-export'
  52. ;; M-x `org-taskjuggler-export-and-open'
  53. ;;
  54. ;; * Tasks
  55. ;;
  56. ;; Let's illustrate the usage with a small example. Create your tasks
  57. ;; as you usually do with org-mode. Assign efforts to each task using
  58. ;; properties (it's easiest to do this in the column view). You
  59. ;; should end up with something similar to the example by Peter Jones
  60. ;; in:
  61. ;;
  62. ;; http://www.devalot.com/assets/articles/2008/07/project-planning/project-planning.org.
  63. ;;
  64. ;; Now mark the top node of your tasks with a tag named
  65. ;; "taskjuggler_project" (or whatever you customized
  66. ;; `org-taskjuggler-project-tag' to). You are now ready to export the
  67. ;; project plan with `org-taskjuggler-export-and-open' which will
  68. ;; export the project plan and open a Gantt chart in TaskJugglerUI.
  69. ;;
  70. ;; * Resources
  71. ;;
  72. ;; Next you can define resources and assign those to work on specific
  73. ;; tasks. You can group your resources hierarchically. Tag the top
  74. ;; node of the resources with "taskjuggler_resource" (or whatever you
  75. ;; customized `org-taskjuggler-resource-tag' to). You can optionally
  76. ;; assign an identifier (named "resource_id") to the resources (using
  77. ;; the standard org properties commands) or you can let the exporter
  78. ;; generate identifiers automatically (the exporter picks the first
  79. ;; word of the headline as the identifier as long as it is unique, see
  80. ;; the documentation of `org-taskjuggler--build-unique-id'). Using that
  81. ;; identifier you can then allocate resources to tasks. This is again
  82. ;; done with the "allocate" property on the tasks. Do this in column
  83. ;; view or when on the task type
  84. ;;
  85. ;; C-c C-x p allocate RET <resource_id> RET
  86. ;;
  87. ;; Once the allocations are done you can again export to TaskJuggler
  88. ;; and check in the Resource Allocation Graph which person is working
  89. ;; on what task at what time.
  90. ;;
  91. ;; * Export of properties
  92. ;;
  93. ;; The exporter also takes TODO state information into consideration,
  94. ;; i.e. if a task is marked as done it will have the corresponding
  95. ;; attribute in TaskJuggler ("complete 100"). Also it will export any
  96. ;; property on a task resource or resource node which is known to
  97. ;; TaskJuggler, such as limits, vacation, shift, booking, efficiency,
  98. ;; journalentry, rate for resources or account, start, note, duration,
  99. ;; end, journalentry, milestone, reference, responsible, scheduling,
  100. ;; etc for tasks.
  101. ;;
  102. ;; * Dependencies
  103. ;;
  104. ;; The exporter will handle dependencies that are defined in the tasks
  105. ;; either with the ORDERED attribute (see TODO dependencies in the Org
  106. ;; mode manual) or with the BLOCKER attribute (see org-depend.el) or
  107. ;; alternatively with a depends attribute. Both the BLOCKER and the
  108. ;; depends attribute can be either "previous-sibling" or a reference
  109. ;; to an identifier (named "task_id") which is defined for another
  110. ;; task in the project. BLOCKER and the depends attribute can define
  111. ;; multiple dependencies separated by either space or comma. You can
  112. ;; also specify optional attributes on the dependency by simply
  113. ;; appending it. The following examples should illustrate this:
  114. ;;
  115. ;; * Training material
  116. ;; :PROPERTIES:
  117. ;; :task_id: training_material
  118. ;; :ORDERED: t
  119. ;; :END:
  120. ;; ** Markup Guidelines
  121. ;; :PROPERTIES:
  122. ;; :Effort: 2d
  123. ;; :END:
  124. ;; ** Workflow Guidelines
  125. ;; :PROPERTIES:
  126. ;; :Effort: 2d
  127. ;; :END:
  128. ;; * Presentation
  129. ;; :PROPERTIES:
  130. ;; :Effort: 2d
  131. ;; :BLOCKER: training_material { gapduration 1d } some_other_task
  132. ;; :END:
  133. ;;
  134. ;;;; * TODO
  135. ;; - Look at org-file-properties, org-global-properties and
  136. ;; org-global-properties-fixed
  137. ;; - What about property inheritance and org-property-inherit-p?
  138. ;; - Use TYPE_TODO as an way to assign resources
  139. ;; - Add support for org-export-with-planning
  140. ;;
  141. ;;; Code:
  142. (eval-when-compile (require 'cl))
  143. (require 'ox)
  144. ;;; User Variables
  145. (defgroup org-export-taskjuggler nil
  146. "Options specific for TaskJuggler export back-end."
  147. :tag "Org Export TaskJuggler"
  148. :group 'org-export)
  149. (defcustom org-taskjuggler-extension ".tjp"
  150. "Extension of TaskJuggler files."
  151. :group 'org-export-taskjuggler
  152. :type 'string)
  153. (defcustom org-taskjuggler-project-tag "taskjuggler_project"
  154. "Tag marking project's tasks.
  155. This tag is used to find the tree containing all the tasks for
  156. the project."
  157. :group 'org-export-taskjuggler
  158. :type 'string)
  159. (defcustom org-taskjuggler-resource-tag "taskjuggler_resource"
  160. "Tag marking project's resources.
  161. This tag is used to find the tree containing all the resources
  162. for the project."
  163. :group 'org-export-taskjuggler
  164. :type 'string)
  165. (defcustom org-taskjuggler-report-tag "taskjuggler_report"
  166. "Tag marking project's reports.
  167. This tag is used to find the tree containing all the reports for
  168. the project."
  169. :group 'org-export-taskjuggler
  170. :type 'string)
  171. (defcustom org-taskjuggler-target-version 3.0
  172. "Which version of TaskJuggler the exporter is targeting.
  173. By default a project plan is exported which conforms to version
  174. 3.x of TaskJuggler. For a project plan that is compatible with
  175. versions of TaskJuggler older than 3.0 set this to 2.4.
  176. If you change this variable be sure to also change
  177. `org-taskjuggler-default-reports' as the format of reports has
  178. changed considerably between version 2.x and 3.x of TaskJuggler"
  179. :group 'org-export-taskjuggler
  180. :type 'number)
  181. (defcustom org-taskjuggler-default-project-version "1.0"
  182. "Default version string for the project.
  183. This value can also be set with the \":VERSION:\" property
  184. associated to the headline defining the project."
  185. :group 'org-export-taskjuggler
  186. :type 'string)
  187. (defcustom org-taskjuggler-default-project-duration 280
  188. "Default project duration.
  189. The value will be used if no start and end date have been defined
  190. in the root node of the task tree, i.e. the tree that has been
  191. marked with `org-taskjuggler-project-tag'"
  192. :group 'org-export-taskjuggler
  193. :type 'integer)
  194. (defcustom org-taskjuggler-default-reports
  195. '("textreport report \"Plan\" {
  196. formats html
  197. header '== %title =='
  198. center -8<-
  199. [#Plan Plan] | [#Resource_Allocation Resource Allocation]
  200. ----
  201. === Plan ===
  202. <[report id=\"plan\"]>
  203. ----
  204. === Resource Allocation ===
  205. <[report id=\"resourceGraph\"]>
  206. ->8-
  207. }
  208. # A traditional Gantt chart with a project overview.
  209. taskreport plan \"\" {
  210. headline \"Project Plan\"
  211. columns bsi, name, start, end, effort, chart
  212. loadunit shortauto
  213. hideresource 1
  214. }
  215. # A graph showing resource allocation. It identifies whether each
  216. # resource is under- or over-allocated for.
  217. resourcereport resourceGraph \"\" {
  218. headline \"Resource Allocation Graph\"
  219. columns no, name, effort, weekly
  220. loadunit shortauto
  221. hidetask ~(isleaf() & isleaf_())
  222. sorttasks plan.start.up
  223. }")
  224. "Default reports for the project.
  225. These are sensible default reports to give a good out-of-the-box
  226. result when exporting without defining any reports. \"%title\"
  227. anywhere in the reports will be replaced with the document title.
  228. If you want to define your own reports you can change them here
  229. or simply define the default reports so that they include an
  230. external report definition as follows:
  231. include reports.tji
  232. These default are made to work with tj3. If you are targeting
  233. TaskJuggler 2.4 (see `org-taskjuggler-target-version') please
  234. change these defaults to something like the following:
  235. taskreport \"Gantt Chart\" {
  236. headline \"Project Gantt Chart\"
  237. columns hierarchindex, name, start, end, effort, duration, completed, chart
  238. timeformat \"%Y-%m-%d\"
  239. hideresource 1
  240. loadunit shortauto
  241. }
  242. resourcereport \"Resource Graph\" {
  243. headline \"Resource Allocation Graph\"
  244. columns no, name, utilization, freeload, chart
  245. loadunit shortauto
  246. sorttasks startup
  247. hidetask ~isleaf()
  248. }"
  249. :group 'org-export-taskjuggler
  250. :type '(repeat (string :tag "Report")))
  251. (defcustom org-taskjuggler-default-global-header ""
  252. "Default global header for the project.
  253. This goes before project declaration, and might be useful for
  254. early macros."
  255. :group 'org-export-taskjuggler
  256. :type '(string :tag "Preamble"))
  257. (defcustom org-taskjuggler-default-global-properties
  258. "shift s40 \"Part time shift\" {
  259. workinghours wed, thu, fri off
  260. }
  261. "
  262. "Default global properties for the project.
  263. Here you typically define global properties such as shifts,
  264. accounts, rates, vacation, macros and flags. Any property that
  265. is allowed within the TaskJuggler file can be inserted. You
  266. could for example include another TaskJuggler file.
  267. The global properties are inserted after the project declaration
  268. but before any resource and task declarations."
  269. :group 'org-export-taskjuggler
  270. :type '(string :tag "Preamble"))
  271. (defcustom org-taskjuggler-valid-task-attributes
  272. '(account start note duration endbuffer endcredit end
  273. flags journalentry length limits maxend maxstart minend
  274. minstart period reference responsible scheduling
  275. startbuffer startcredit statusnote chargeset charge)
  276. "Valid attributes for Taskjuggler tasks.
  277. If one of these appears as a property for a headline, it will be
  278. exported with the corresponding task.
  279. Note that multiline properties are not supported, so attributes
  280. like note or journalentry have to be on a single line."
  281. :group 'org-export-taskjuggler)
  282. (defcustom org-taskjuggler-valid-project-attributes
  283. '(timingresolution timezone alertlevels currency currencyformat
  284. dailyworkinghours extend includejournalentry now numberformat
  285. outputdir scenario shorttimeformat timeformat trackingscenario
  286. weekstartsmonday weekstartssunday workinghours
  287. yearlyworkingdays)
  288. "Valid attributes for Taskjuggler project.
  289. If one of these appears as a property for a headline that is a
  290. project definition, it will be exported with the corresponding
  291. task. Attribute 'timingresolution' should be the first in the
  292. list."
  293. :group 'org-export-taskjuggler)
  294. (defcustom org-taskjuggler-valid-resource-attributes
  295. '(limits vacation shift booking efficiency journalentry rate
  296. workinghours flags)
  297. "Valid attributes for Taskjuggler resources.
  298. If one of these appears as a property for a headline, it will be
  299. exported with the corresponding resource."
  300. :group 'org-export-taskjuggler)
  301. (defcustom org-taskjuggler-valid-report-attributes
  302. '(headline columns definitions timeformat hideresource hidetask
  303. loadunit sorttasks formats period)
  304. "Valid attributes for Taskjuggler reports.
  305. If one of these appears as a property for a headline, it will be
  306. exported with the corresponding report."
  307. :group 'org-export-taskjuggler)
  308. (defcustom org-taskjuggler-process-command
  309. "tj3 --silent --no-color --output-dir %o %f"
  310. "Command to process a Taskjuggler file.
  311. The command will be given to the shell as a command to process a
  312. Taskjuggler file. \"%f\" in the command will be replaced by the
  313. full file name, \"%o\" by the reports directory (see
  314. `org-taskjuggler-reports-directory').
  315. If you are targeting Taskjuggler 2.4 (see
  316. `org-taskjuggler-target-version') this setting is ignored."
  317. :group 'org-export-taskjuggler)
  318. (defcustom org-taskjuggler-reports-directory "reports"
  319. "Default directory to generate the Taskjuggler reports in.
  320. The command `org-taskjuggler-process-command' generates the
  321. reports and associated files such as CSS inside this directory.
  322. If the directory is not an absolute path it is relative to the
  323. directory of the exported file. The directory is created if it
  324. doesn't exist.
  325. If you are targeting Taskjuggler 2.4 (see
  326. `org-taskjuggler-target-version') this setting is ignored."
  327. :group 'org-export-taskjuggler)
  328. (defcustom org-taskjuggler-keep-project-as-task t
  329. "Non-nil keeps the project headline as an umbrella task for all tasks.
  330. Setting this to nil will allow maintaining completely separated
  331. task buckets, while still sharing the same resources pool."
  332. :group 'org-export-taskjuggler
  333. :type 'boolean)
  334. ;;; Hooks
  335. (defvar org-taskjuggler-final-hook nil
  336. "Hook run after a TaskJuggler files has been saved.
  337. This hook is run with the name of the file as argument.")
  338. ;;; Back-End Definition
  339. (org-export-define-backend 'taskjuggler
  340. '((template . org-taskjuggler-project-plan))
  341. :menu-entry
  342. '(?J "Export to TaskJuggler"
  343. ((?j "As TJP file" (lambda (a s v b) (org-taskjuggler-export a s v)))
  344. (?p "As TJP file and process"
  345. (lambda (a s v b)
  346. (if a (org-taskjuggler-export a s v)
  347. (org-taskjuggler-export-and-process s v))))
  348. (?o "As TJP file, process and open"
  349. (lambda (a s v b)
  350. (if a (org-taskjuggler-export a s v)
  351. (org-taskjuggler-export-process-and-open s v))))))
  352. ;; This property will be used to store unique ids in communication
  353. ;; channel. Ids will be retrieved with `org-taskjuggler-get-id'.
  354. :options-alist '((:taskjuggler-unique-ids nil nil nil)))
  355. ;;; Unique IDs
  356. (defun org-taskjuggler-assign-task-ids (tasks info)
  357. "Assign a unique ID to each task in TASKS.
  358. TASKS is a list of headlines. INFO is a plist used as a
  359. communication channel. Return value is an alist between
  360. headlines and their associated ID. IDs are hierarchical, which
  361. means they only need to be unique among the task siblings."
  362. (let* (alist
  363. build-id ; For byte-compiler.
  364. (build-id
  365. (lambda (tasks local-ids)
  366. (org-element-map tasks 'headline
  367. (lambda (task)
  368. (let ((id (org-taskjuggler--build-unique-id task local-ids)))
  369. (push id local-ids)
  370. (push (cons task id) alist)
  371. (funcall build-id (org-element-contents task) nil)))
  372. info nil 'headline))))
  373. (funcall build-id tasks nil)
  374. alist))
  375. (defun org-taskjuggler-assign-resource-ids (resources info)
  376. "Assign a unique ID to each resource within RESOURCES.
  377. RESOURCES is a list of headlines. INFO is a plist used as a
  378. communication channel. Return value is an alist between
  379. headlines and their associated ID."
  380. (let (ids)
  381. (org-element-map resources 'headline
  382. (lambda (resource)
  383. (let ((id (org-taskjuggler--build-unique-id resource ids)))
  384. (push id ids)
  385. (cons resource id)))
  386. info)))
  387. ;;; Accessors
  388. (defun org-taskjuggler-get-project (info)
  389. "Return project in parse tree.
  390. INFO is a plist used as a communication channel. First headline
  391. in buffer with `org-taskjuggler-project-tag' defines the project.
  392. If no such task is defined, pick the first headline in buffer.
  393. If there is no headline at all, return nil."
  394. (let ((tree (plist-get info :parse-tree)))
  395. (or (org-element-map tree 'headline
  396. (lambda (hl)
  397. (and (member org-taskjuggler-project-tag
  398. (org-export-get-tags hl info))
  399. hl))
  400. info t)
  401. (org-element-map tree 'headline 'identity info t))))
  402. (defun org-taskjuggler-get-id (item info)
  403. "Return id for task or resource ITEM.
  404. ITEM is a headline. INFO is a plist used as a communication
  405. channel. Return value is a string."
  406. (cdr (assq item (plist-get info :taskjuggler-unique-ids))))
  407. (defun org-taskjuggler-get-name (item)
  408. "Return name for task or resource ITEM.
  409. ITEM is a headline. Return value is a string."
  410. ;; Quote double quotes in name.
  411. (replace-regexp-in-string
  412. "\"" "\\\"" (org-element-property :raw-value item) t t))
  413. (defun org-taskjuggler-get-start (item)
  414. "Return start date for task or resource ITEM.
  415. ITEM is a headline. Return value is a string or nil if ITEM
  416. doesn't have any start date defined."
  417. (let ((scheduled (org-element-property :scheduled item)))
  418. (or
  419. (and scheduled (org-timestamp-format scheduled "%Y-%02m-%02d"))
  420. (and (memq 'start org-taskjuggler-valid-task-attributes)
  421. (org-element-property :START item)))))
  422. (defun org-taskjuggler-get-end (item)
  423. "Return end date for task or resource ITEM.
  424. ITEM is a headline. Return value is a string or nil if ITEM
  425. doesn't have any end date defined."
  426. (let ((deadline (org-element-property :deadline item)))
  427. (and deadline (org-timestamp-format deadline "%Y-%02m-%02d"))))
  428. ;;; Internal Functions
  429. (defun org-taskjuggler--indent-string (s)
  430. "Indent string S by 2 spaces.
  431. Return new string. If S is the empty string, return it."
  432. (if (equal "" s) s (replace-regexp-in-string "^ *\\S-" " \\&" s)))
  433. (defun org-taskjuggler--build-attributes (item attributes)
  434. "Return attributes string for ITEM.
  435. ITEM is a project, task, resource or report headline. ATTRIBUTES
  436. is a list of symbols representing valid attributes for ITEM."
  437. (mapconcat
  438. (lambda (attribute)
  439. (let ((value (org-element-property
  440. (intern (upcase (format ":%s" attribute)))
  441. item)))
  442. (and value (format "%s %s\n" attribute value))))
  443. (remq nil attributes) ""))
  444. (defun org-taskjuggler--build-unique-id (item unique-ids)
  445. "Return a unique id for a given task or a resource.
  446. ITEM is an `headline' type element representing the task or
  447. resource. Its id is derived from its name and made unique
  448. against UNIQUE-IDS. If the (downcased) first token of the
  449. headline is not unique try to add more (downcased) tokens of the
  450. headline or finally add more underscore characters (\"_\")."
  451. (let ((id (org-string-nw-p (org-element-property :TASK_ID item))))
  452. ;; If an id is specified, use it, as long as it's unique.
  453. (if (and id (not (member id unique-ids))) id
  454. (let* ((parts (split-string (org-element-property :raw-value item)))
  455. (id (org-taskjuggler--clean-id (downcase (pop parts)))))
  456. ;; Try to add more parts of the headline to make it unique.
  457. (while (and (car parts) (member id unique-ids))
  458. (setq id (concat id "_"
  459. (org-taskjuggler--clean-id (downcase (pop parts))))))
  460. ;; If it's still not unique, add "_".
  461. (while (member id unique-ids)
  462. (setq id (concat id "_")))
  463. id))))
  464. (defun org-taskjuggler--clean-id (id)
  465. "Clean and return ID to make it acceptable for TaskJuggler.
  466. ID is a string."
  467. ;; Replace non-ascii by "_".
  468. (replace-regexp-in-string
  469. "[^a-zA-Z0-9_]" "_"
  470. ;; Make sure id doesn't start with a number.
  471. (replace-regexp-in-string "^\\([0-9]\\)" "_\\1" id)))
  472. ;;; Dependencies
  473. (defun org-taskjuggler-resolve-dependencies (task info)
  474. "Return a list of all tasks TASK depends on.
  475. TASK is a headline. INFO is a plist used as a communication
  476. channel."
  477. (let ((deps-ids
  478. ;; Get all dependencies specified in BLOCKER and DEPENDS task
  479. ;; properties. Clean options from them.
  480. (let ((deps (concat (org-element-property :BLOCKER task)
  481. (org-element-property :DEPENDS task))))
  482. (and deps
  483. (split-string (replace-regexp-in-string "{.*?}" "" deps)
  484. "[ ,]* +"))))
  485. depends)
  486. (when deps-ids
  487. ;; Find tasks with :task_id: property matching id in DEPS-IDS.
  488. ;; Add them to DEPENDS.
  489. (let* ((project (org-taskjuggler-get-project info))
  490. (tasks (if org-taskjuggler-keep-project-as-task project
  491. (org-element-contents project))))
  492. (setq depends
  493. (org-element-map tasks 'headline
  494. (lambda (task)
  495. (let ((task-id (or (org-element-property :TASK_ID task)
  496. (org-element-property :ID task))))
  497. (and task-id (member task-id deps-ids) task)))
  498. info)))
  499. ;; Check BLOCKER and DEPENDS properties. If "previous-sibling"
  500. ;; belongs to DEPS-ID, add it to DEPENDS.
  501. (when (and (member-ignore-case "previous-sibling" deps-ids)
  502. (not (org-export-first-sibling-p task info)))
  503. (let ((prev (org-export-get-previous-element task info)))
  504. (and (not (memq prev depends)) (push prev depends)))))
  505. ;; Check ORDERED status of parent.
  506. (let ((parent (org-export-get-parent task)))
  507. (when (and parent
  508. (org-element-property :ORDERED parent)
  509. (not (org-export-first-sibling-p task info)))
  510. (push (org-export-get-previous-element task info) depends)))
  511. ;; Return dependencies.
  512. depends))
  513. (defun org-taskjuggler-format-dependencies (dependencies task info)
  514. "Format DEPENDENCIES to match TaskJuggler syntax.
  515. DEPENDENCIES is list of dependencies for TASK, as returned by
  516. `org-taskjuggler-resolve-depedencies'. TASK is a headline.
  517. INFO is a plist used as a communication channel. Return value
  518. doesn't include leading \"depends\"."
  519. (let* ((dep-str (concat (org-element-property :BLOCKER task)
  520. " "
  521. (org-element-property :DEPENDS task)))
  522. (get-path
  523. (lambda (dep)
  524. ;; Return path to DEP relatively to TASK.
  525. (let ((parent (org-export-get-parent task))
  526. (exclamations 1)
  527. (option
  528. (let ((id (org-element-property :TASK_ID dep)))
  529. (and id
  530. (string-match (concat id " +\\({.*?}\\)") dep-str)
  531. (match-string-no-properties 1 dep-str))))
  532. path)
  533. ;; Compute number of exclamation marks by looking for the
  534. ;; common ancestor between TASK and DEP.
  535. (while (not (org-element-map parent 'headline
  536. (lambda (hl) (eq hl dep))))
  537. (incf exclamations)
  538. (setq parent (org-export-get-parent parent)))
  539. ;; Build path from DEP to PARENT.
  540. (while (not (eq parent dep))
  541. (push (org-taskjuggler-get-id dep info) path)
  542. (setq dep (org-export-get-parent dep)))
  543. ;; Return full path. Add dependency options, if any.
  544. (concat (make-string exclamations ?!)
  545. (mapconcat 'identity path ".")
  546. (and option (concat " " option)))))))
  547. ;; Return dependencies string, without the leading "depends".
  548. (mapconcat (lambda (dep) (funcall get-path dep)) dependencies ", ")))
  549. ;;; Translator Functions
  550. (defun org-taskjuggler-project-plan (contents info)
  551. "Build TaskJuggler project plan.
  552. CONTENTS is ignored. INFO is a plist holding export options.
  553. Return complete project plan as a string in TaskJuggler syntax."
  554. (let* ((tree (plist-get info :parse-tree))
  555. (project (or (org-taskjuggler-get-project info)
  556. (error "No project specified"))))
  557. (concat
  558. ;; 1. Insert header.
  559. (org-element-normalize-string org-taskjuggler-default-global-header)
  560. ;; 2. Insert project.
  561. (org-taskjuggler--build-project project info)
  562. ;; 3. Insert global properties.
  563. (org-element-normalize-string org-taskjuggler-default-global-properties)
  564. ;; 4. Insert resources. Provide a default one if none is
  565. ;; specified.
  566. (let ((main-resources
  567. ;; Collect contents from various trees marked with
  568. ;; `org-taskjuggler-resource-tag'. Only gather top level
  569. ;; resources.
  570. (apply 'append
  571. (org-element-map tree 'headline
  572. (lambda (hl)
  573. (and (member org-taskjuggler-resource-tag
  574. (org-export-get-tags hl info))
  575. (org-element-map (org-element-contents hl) 'headline
  576. 'identity info nil 'headline)))
  577. info nil 'headline))))
  578. ;; Assign a unique ID to each resource. Store it under
  579. ;; `:taskjuggler-unique-ids' property in INFO.
  580. (setq info
  581. (plist-put info :taskjuggler-unique-ids
  582. (org-taskjuggler-assign-resource-ids
  583. main-resources info)))
  584. (concat
  585. (if main-resources
  586. (mapconcat
  587. (lambda (resource) (org-taskjuggler--build-resource resource info))
  588. main-resources "")
  589. (format "resource %s \"%s\" {\n}\n" (user-login-name) user-full-name))
  590. ;; 5. Insert tasks.
  591. (let ((main-tasks
  592. ;; If `org-taskjuggler-keep-project-as-task' is
  593. ;; non-nil, there is only one task. Otherwise, every
  594. ;; direct children of PROJECT is a top level task.
  595. (if org-taskjuggler-keep-project-as-task (list project)
  596. (or (org-element-map (org-element-contents project) 'headline
  597. 'identity info nil 'headline)
  598. (error "No task specified")))))
  599. ;; Assign a unique ID to each task. Add it to
  600. ;; `:taskjuggler-unique-ids' property in INFO.
  601. (setq info
  602. (plist-put info :taskjuggler-unique-ids
  603. (append
  604. (org-taskjuggler-assign-task-ids main-tasks info)
  605. (plist-get info :taskjuggler-unique-ids))))
  606. ;; If no resource is allocated among tasks, allocate one to
  607. ;; the first task.
  608. (unless (org-element-map main-tasks 'headline
  609. (lambda (task) (org-element-property :ALLOCATE task))
  610. info t)
  611. (org-element-put-property
  612. (car main-tasks) :ALLOCATE
  613. (or (org-taskjuggler-get-id (car main-resources) info)
  614. (user-login-name))))
  615. (mapconcat
  616. (lambda (task) (org-taskjuggler--build-task task info))
  617. main-tasks ""))
  618. ;; 6. Insert reports. If no report is defined, insert default
  619. ;; reports.
  620. (let ((main-reports
  621. ;; Collect contents from various trees marked with
  622. ;; `org-taskjuggler-report-tag'. Only gather top level
  623. ;; reports.
  624. (apply 'append
  625. (org-element-map tree 'headline
  626. (lambda (hl)
  627. (and (member org-taskjuggler-report-tag
  628. (org-export-get-tags hl info))
  629. (org-element-map (org-element-contents hl)
  630. 'headline 'identity info nil 'headline)))
  631. info nil 'headline))))
  632. (if main-reports
  633. (mapconcat
  634. (lambda (report) (org-taskjuggler--build-report report info))
  635. main-reports "")
  636. ;; insert title in default reports
  637. (let* ((title (org-export-data (plist-get info :title) info))
  638. (report-title (if (string= title "")
  639. (org-taskjuggler-get-name project)
  640. title)))
  641. (mapconcat
  642. 'org-element-normalize-string
  643. (mapcar
  644. (function
  645. (lambda (report)
  646. (replace-regexp-in-string "%title" report-title report t t)))
  647. org-taskjuggler-default-reports) "")))))))))
  648. (defun org-taskjuggler--build-project (project info)
  649. "Return a project declaration.
  650. PROJECT is a headline. INFO is a plist used as a communication
  651. channel. If no start date is specified, start today. If no end
  652. date is specified, end `org-taskjuggler-default-project-duration'
  653. days from now."
  654. (concat
  655. ;; Opening project.
  656. (format "project %s \"%s\" \"%s\" %s %s {\n"
  657. (org-taskjuggler-get-id project info)
  658. (org-taskjuggler-get-name project)
  659. ;; Version is obtained through :TASKJUGGLER_VERSION:
  660. ;; property or `org-taskjuggler-default-project-version'.
  661. (or (org-element-property :VERSION project)
  662. org-taskjuggler-default-project-version)
  663. (or (org-taskjuggler-get-start project)
  664. (format-time-string "%Y-%m-%d"))
  665. (let ((end (org-taskjuggler-get-end project)))
  666. (or (and end (format "- %s" end))
  667. (format "+%sd"
  668. org-taskjuggler-default-project-duration))))
  669. ;; Add attributes.
  670. (org-taskjuggler--indent-string
  671. (org-taskjuggler--build-attributes
  672. project org-taskjuggler-valid-project-attributes))
  673. ;; Closing project.
  674. "}\n"))
  675. (defun org-taskjuggler--build-resource (resource info)
  676. "Return a resource declaration.
  677. RESOURCE is a headline. INFO is a plist used as a communication
  678. channel.
  679. All valid attributes from RESOURCE are inserted. If RESOURCE
  680. defines a property \"resource_id\" it will be used as the id for
  681. this resource. Otherwise it will use the ID property. If
  682. neither is defined a unique id will be associated to it."
  683. (concat
  684. ;; Opening resource.
  685. (format "resource %s \"%s\" {\n"
  686. (org-taskjuggler--clean-id
  687. (or (org-element-property :RESOURCE_ID resource)
  688. (org-element-property :ID resource)
  689. (org-taskjuggler-get-id resource info)))
  690. (org-taskjuggler-get-name resource))
  691. ;; Add attributes.
  692. (org-taskjuggler--indent-string
  693. (org-taskjuggler--build-attributes
  694. resource org-taskjuggler-valid-resource-attributes))
  695. ;; Add inner resources.
  696. (org-taskjuggler--indent-string
  697. (mapconcat
  698. 'identity
  699. (org-element-map (org-element-contents resource) 'headline
  700. (lambda (hl) (org-taskjuggler--build-resource hl info))
  701. info nil 'headline)
  702. ""))
  703. ;; Closing resource.
  704. "}\n"))
  705. (defun org-taskjuggler--build-report (report info)
  706. "Return a report declaration.
  707. REPORT is a headline. INFO is a plist used as a communication
  708. channel."
  709. (concat
  710. ;; Opening report.
  711. (format "%s \"%s\" {\n"
  712. (or (org-element-property :REPORT_KIND report) "taskreport")
  713. (org-taskjuggler-get-name report))
  714. ;; Add attributes.
  715. (org-taskjuggler--indent-string
  716. (org-taskjuggler--build-attributes
  717. report org-taskjuggler-valid-report-attributes))
  718. ;; Add inner reports.
  719. (org-taskjuggler--indent-string
  720. (mapconcat
  721. 'identity
  722. (org-element-map (org-element-contents report) 'headline
  723. (lambda (hl) (org-taskjuggler--build-report hl info))
  724. info nil 'headline)
  725. ""))
  726. ;; Closing report.
  727. "}\n"))
  728. (defun org-taskjuggler--build-task (task info)
  729. "Return a task declaration.
  730. TASK is a headline. INFO is a plist used as a communication
  731. channel.
  732. All valid attributes from TASK are inserted. If TASK defines
  733. a property \"task_id\" it will be used as the id for this task.
  734. Otherwise it will use the ID property. If neither is defined
  735. a unique id will be associated to it."
  736. (let* ((allocate (org-element-property :ALLOCATE task))
  737. (complete
  738. (if (eq (org-element-property :todo-type task) 'done) "100"
  739. (org-element-property :COMPLETE task)))
  740. (depends (org-taskjuggler-resolve-dependencies task info))
  741. (effort (let ((property
  742. (intern (concat ":" (upcase org-effort-property)))))
  743. (org-element-property property task)))
  744. (milestone
  745. (or (org-element-property :MILESTONE task)
  746. (not (or (org-element-map (org-element-contents task) 'headline
  747. 'identity info t) ; Has task any child?
  748. effort
  749. (org-element-property :LENGTH task)
  750. (org-element-property :DURATION task)
  751. (and (org-taskjuggler-get-start task)
  752. (org-taskjuggler-get-end task))
  753. (org-element-property :PERIOD task)))))
  754. (priority
  755. (let ((pri (org-element-property :priority task)))
  756. (and pri
  757. (max 1 (/ (* 1000 (- org-lowest-priority pri))
  758. (- org-lowest-priority org-highest-priority)))))))
  759. (concat
  760. ;; Opening task.
  761. (format "task %s \"%s\" {\n"
  762. (org-taskjuggler-get-id task info)
  763. (org-taskjuggler-get-name task))
  764. ;; Add default attributes.
  765. (and depends
  766. (format " depends %s\n"
  767. (org-taskjuggler-format-dependencies depends task info)))
  768. (and allocate
  769. (format " purge %s\n allocate %s\n"
  770. ;; Compatibility for previous TaskJuggler versions.
  771. (if (>= org-taskjuggler-target-version 3.0) "allocate"
  772. "allocations")
  773. allocate))
  774. (and complete (format " complete %s\n" complete))
  775. (and effort
  776. (format " effort %s\n"
  777. (let* ((minutes (org-duration-to-minutes effort))
  778. (hours (/ minutes 60.0)))
  779. (format "%.1fh" hours))))
  780. (and priority (format " priority %s\n" priority))
  781. (and milestone " milestone\n")
  782. ;; Add other valid attributes.
  783. (org-taskjuggler--indent-string
  784. (org-taskjuggler--build-attributes
  785. task org-taskjuggler-valid-task-attributes))
  786. ;; Add inner tasks.
  787. (org-taskjuggler--indent-string
  788. (mapconcat 'identity
  789. (org-element-map (org-element-contents task) 'headline
  790. (lambda (hl) (org-taskjuggler--build-task hl info))
  791. info nil 'headline)
  792. ""))
  793. ;; Closing task.
  794. "}\n")))
  795. ;;; Interactive Functions
  796. ;;;###autoload
  797. (defun org-taskjuggler-export (&optional async subtreep visible-only)
  798. "Export current buffer to a TaskJuggler file.
  799. The exporter looks for a tree with tag that matches
  800. `org-taskjuggler-project-tag' and takes this as the tasks for
  801. this project. The first node of this tree defines the project
  802. properties such as project name and project period.
  803. If there is a tree with tag that matches
  804. `org-taskjuggler-resource-tag' this tree is taken as resources
  805. for the project. If no resources are specified, a default
  806. resource is created and allocated to the project.
  807. Also the TaskJuggler project will be created with default reports
  808. as defined in `org-taskjuggler-default-reports'.
  809. If narrowing is active in the current buffer, only export its
  810. narrowed part.
  811. If a region is active, export that region.
  812. A non-nil optional argument ASYNC means the process should happen
  813. asynchronously. The resulting file should be accessible through
  814. the `org-export-stack' interface.
  815. When optional argument SUBTREEP is non-nil, export the sub-tree
  816. at point, extracting information from the headline properties
  817. first.
  818. When optional argument VISIBLE-ONLY is non-nil, don't export
  819. contents of hidden elements.
  820. Return output file's name."
  821. (interactive)
  822. (let ((outfile
  823. (org-export-output-file-name org-taskjuggler-extension subtreep)))
  824. (org-export-to-file 'taskjuggler outfile
  825. async subtreep visible-only nil nil
  826. (lambda (file)
  827. (run-hook-with-args 'org-taskjuggler-final-hook file) nil))))
  828. ;;;###autoload
  829. (defun org-taskjuggler-export-and-process (&optional subtreep visible-only)
  830. "Export current buffer to a TaskJuggler file and process it.
  831. The exporter looks for a tree with tag that matches
  832. `org-taskjuggler-project-tag' and takes this as the tasks for
  833. this project. The first node of this tree defines the project
  834. properties such as project name and project period.
  835. If there is a tree with tag that matches
  836. `org-taskjuggler-resource-tag' this tree is taken as resources
  837. for the project. If no resources are specified, a default
  838. resource is created and allocated to the project.
  839. Also the TaskJuggler project will be created with default reports
  840. as defined in `org-taskjuggler-default-reports'.
  841. If narrowing is active in the current buffer, only export its
  842. narrowed part.
  843. If a region is active, export that region.
  844. When optional argument SUBTREEP is non-nil, export the sub-tree
  845. at point, extracting information from the headline properties
  846. first.
  847. When optional argument VISIBLE-ONLY is non-nil, don't export
  848. contents of hidden elements.
  849. Return a list of reports."
  850. (interactive)
  851. (let ((file (org-taskjuggler-export nil subtreep visible-only)))
  852. (org-taskjuggler-compile file)))
  853. ;;;###autoload
  854. (defun org-taskjuggler-export-process-and-open (&optional subtreep visible-only)
  855. "Export current buffer to a TaskJuggler file, process and open it.
  856. Export and process the file using
  857. `org-taskjuggler-export-and-process' and open the generated
  858. reports with a browser.
  859. If you are targeting TaskJuggler 2.4 (see
  860. `org-taskjuggler-target-version') the processing and display of
  861. the reports is done using the TaskJuggler GUI."
  862. (interactive)
  863. (if (< org-taskjuggler-target-version 3.0)
  864. (let* ((process-name "TaskJugglerUI")
  865. (command
  866. (concat process-name " "
  867. (org-taskjuggler-export nil subtreep visible-only))))
  868. (start-process-shell-command process-name nil command))
  869. (dolist (report (org-taskjuggler-export-and-process subtreep visible-only))
  870. (org-open-file report))))
  871. (defun org-taskjuggler-compile (file)
  872. "Compile a TaskJuggler file.
  873. FILE is the name of the file being compiled. Processing is done
  874. through the command given in `org-taskjuggler-process-command'.
  875. Return a list of reports."
  876. (let* ((full-name (file-truename file))
  877. (out-dir
  878. (expand-file-name
  879. org-taskjuggler-reports-directory (file-name-directory file)))
  880. errors)
  881. (message (format "Processing TaskJuggler file %s..." file))
  882. (save-window-excursion
  883. (let ((outbuf (get-buffer-create "*Org Taskjuggler Output*")))
  884. (unless (file-directory-p out-dir)
  885. (make-directory out-dir t))
  886. (with-current-buffer outbuf (erase-buffer))
  887. (shell-command
  888. (replace-regexp-in-string
  889. "%f" (shell-quote-argument full-name)
  890. (replace-regexp-in-string
  891. "%o" (shell-quote-argument out-dir)
  892. org-taskjuggler-process-command t t) t t) outbuf)
  893. ;; Collect standard errors from output buffer.
  894. (setq errors (org-taskjuggler--collect-errors outbuf)))
  895. (if (not errors)
  896. (message "Process completed.")
  897. (error (format "TaskJuggler failed with errors: %s" errors))))
  898. (file-expand-wildcards (format "%s/*.html" out-dir))))
  899. (defun org-taskjuggler--collect-errors (buffer)
  900. "Collect some kind of errors from \"tj3\" command output.
  901. BUFFER is the buffer containing output.
  902. Return collected error types as a string, or nil if there was
  903. none."
  904. (with-current-buffer buffer
  905. (save-excursion
  906. (goto-char (point-min))
  907. (let ((case-fold-search t)
  908. (errors ""))
  909. (while (re-search-forward "^.+:[0-9]+: \\(.*\\)$" nil t)
  910. (setq errors (concat errors " " (match-string 1))))
  911. (and (org-string-nw-p errors) (org-trim errors))))))
  912. (provide 'ox-taskjuggler)
  913. ;; Local variables:
  914. ;; sentence-end-double-space: t
  915. ;; End:
  916. ;;; ox-taskjuggler.el ends here