1 ;;; ox-taskjuggler.el --- TaskJuggler Back-End for Org Export Engine
3 ;; Copyright (C) 2007-2014 Free Software Foundation, Inc.
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
13 ;; This file is not part of GNU Emacs.
15 ;; This program is free software: you can redistribute it and/or modify
16 ;; it under the terms of the GNU General Public License as published by
17 ;; the Free Software Foundation, either version 3 of the License, or
18 ;; (at your option) any later version.
20 ;; This program is distributed in the hope that it will be useful,
21 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
22 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 ;; GNU General Public License for more details.
25 ;; You should have received a copy of the GNU General Public License
26 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
30 ;; This library implements a TaskJuggler exporter for Org mode.
31 ;; TaskJuggler is a project planing tool that uses a text format to
32 ;; define projects, tasks and resources, so it is a natural fit for
33 ;; Org mode. It can produce all sorts of reports for tasks or
34 ;; resources in either HTML, CSV or PDF. TaskJuggler is implemented
35 ;; in Ruby and should therefore run on any platform.
37 ;; The exporter does not export all the nodes of a document or
38 ;; strictly follow the order of the nodes in the document.
40 ;; Instead the TaskJuggler exporter looks for a tree that defines the
41 ;; tasks and a optionally tree that defines the resources for this
42 ;; project. It then creates a TaskJuggler file based on these trees
43 ;; and the attributes defined in all the nodes.
47 ;; Put this file into your load-path and the following line into your
50 ;; (add-to-list 'org-export-backends 'taskjuggler)
52 ;; or customize `org-export-backends' variable.
54 ;; The interactive functions are the following:
56 ;; M-x `org-taskjuggler-export'
57 ;; M-x `org-taskjuggler-export-and-open'
61 ;; Let's illustrate the usage with a small example. Create your tasks
62 ;; as you usually do with org-mode. Assign efforts to each task using
63 ;; properties (it's easiest to do this in the column view). You
64 ;; should end up with something similar to the example by Peter Jones
67 ;; http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org.
69 ;; Now mark the top node of your tasks with a tag named
70 ;; "taskjuggler_project" (or whatever you customized
71 ;; `org-taskjuggler-project-tag' to). You are now ready to export the
72 ;; project plan with `org-taskjuggler-export-and-open' which will
73 ;; export the project plan and open a Gantt chart in TaskJugglerUI.
77 ;; Next you can define resources and assign those to work on specific
78 ;; tasks. You can group your resources hierarchically. Tag the top
79 ;; node of the resources with "taskjuggler_resource" (or whatever you
80 ;; customized `org-taskjuggler-resource-tag' to). You can optionally
81 ;; assign an identifier (named "resource_id") to the resources (using
82 ;; the standard org properties commands) or you can let the exporter
83 ;; generate identifiers automatically (the exporter picks the first
84 ;; word of the headline as the identifier as long as it is unique, see
85 ;; the documentation of `org-taskjuggler--build-unique-id'). Using that
86 ;; identifier you can then allocate resources to tasks. This is again
87 ;; done with the "allocate" property on the tasks. Do this in column
88 ;; view or when on the task type
90 ;; C-c C-x p allocate RET <resource_id> RET
92 ;; Once the allocations are done you can again export to TaskJuggler
93 ;; and check in the Resource Allocation Graph which person is working
94 ;; on what task at what time.
96 ;; * Export of properties
98 ;; The exporter also takes TODO state information into consideration,
99 ;; i.e. if a task is marked as done it will have the corresponding
100 ;; attribute in TaskJuggler ("complete 100"). Also it will export any
101 ;; property on a task resource or resource node which is known to
102 ;; TaskJuggler, such as limits, vacation, shift, booking, efficiency,
103 ;; journalentry, rate for resources or account, start, note, duration,
104 ;; end, journalentry, milestone, reference, responsible, scheduling,
109 ;; The exporter will handle dependencies that are defined in the tasks
110 ;; either with the ORDERED attribute (see TODO dependencies in the Org
111 ;; mode manual) or with the BLOCKER attribute (see org-depend.el) or
112 ;; alternatively with a depends attribute. Both the BLOCKER and the
113 ;; depends attribute can be either "previous-sibling" or a reference
114 ;; to an identifier (named "task_id") which is defined for another
115 ;; task in the project. BLOCKER and the depends attribute can define
116 ;; multiple dependencies separated by either space or comma. You can
117 ;; also specify optional attributes on the dependency by simply
118 ;; appending it. The following examples should illustrate this:
120 ;; * Training material
122 ;; :task_id: training_material
125 ;; ** Markup Guidelines
129 ;; ** Workflow Guidelines
136 ;; :BLOCKER: training_material { gapduration 1d } some_other_task
140 ;; - Look at org-file-properties, org-global-properties and
141 ;; org-global-properties-fixed
142 ;; - What about property inheritance and org-property-inherit-p?
143 ;; - Use TYPE_TODO as an way to assign resources
144 ;; - Add support for org-export-with-planning
148 (eval-when-compile (require 'cl
))
156 (defgroup org-export-taskjuggler nil
157 "Options specific for TaskJuggler export back-end."
158 :tag
"Org Export TaskJuggler"
161 (defcustom org-taskjuggler-extension
".tjp"
162 "Extension of TaskJuggler files."
163 :group
'org-export-taskjuggler
166 (defcustom org-taskjuggler-project-tag
"taskjuggler_project"
167 "Tag marking project's tasks.
168 This tag is used to find the tree containing all the tasks for
170 :group
'org-export-taskjuggler
173 (defcustom org-taskjuggler-resource-tag
"taskjuggler_resource"
174 "Tag marking project's resources.
175 This tag is used to find the tree containing all the resources
177 :group
'org-export-taskjuggler
180 (defcustom org-taskjuggler-report-tag
"taskjuggler_report"
181 "Tag marking project's reports.
182 This tag is used to find the tree containing all the reports for
184 :group
'org-export-taskjuggler
187 (defcustom org-taskjuggler-target-version
3.0
188 "Which version of TaskJuggler the exporter is targeting.
189 By default a project plan is exported which conforms to version
190 3.x of TaskJuggler. For a project plan that is compatible with
191 versions of TaskJuggler older than 3.0 set this to 2.4.
193 If you change this variable be sure to also change
194 `org-taskjuggler-default-reports' as the format of reports has
195 changed considerably between version 2.x and 3.x of TaskJuggler"
196 :group
'org-export-taskjuggler
199 (defcustom org-taskjuggler-default-project-version
"1.0"
200 "Default version string for the project.
201 This value can also be set with the \":VERSION:\" property
202 associated to the headline defining the project."
203 :group
'org-export-taskjuggler
206 (defcustom org-taskjuggler-default-project-duration
280
207 "Default project duration.
208 The value will be used if no start and end date have been defined
209 in the root node of the task tree, i.e. the tree that has been
210 marked with `org-taskjuggler-project-tag'"
211 :group
'org-export-taskjuggler
214 (defcustom org-taskjuggler-default-reports
215 '("textreport report \"Plan\" {
217 header '== %title =='
220 [#Plan Plan] | [#Resource_Allocation Resource Allocation]
223 <[report id=\"plan\"]>
225 === Resource Allocation ===
226 <[report id=\"resourceGraph\"]>
230 # A traditional Gantt chart with a project overview.
231 taskreport plan \"\" {
232 headline \"Project Plan\"
233 columns bsi, name, start, end, effort, chart
238 # A graph showing resource allocation. It identifies whether each
239 # resource is under- or over-allocated for.
240 resourcereport resourceGraph \"\" {
241 headline \"Resource Allocation Graph\"
242 columns no, name, effort, weekly
244 hidetask ~(isleaf() & isleaf_())
245 sorttasks plan.start.up
247 "Default reports for the project.
248 These are sensible default reports to give a good out-of-the-box
249 result when exporting without defining any reports. \"%title\"
250 anywhere in the reports will be replaced with the document title.
251 If you want to define your own reports you can change them here
252 or simply define the default reports so that they include an
253 external report definition as follows:
257 These default are made to work with tj3. If you are targeting
258 TaskJuggler 2.4 (see `org-taskjuggler-target-version') please
259 change these defaults to something like the following:
261 taskreport \"Gantt Chart\" {
262 headline \"Project Gantt Chart\"
263 columns hierarchindex, name, start, end, effort, duration, completed, chart
264 timeformat \"%Y-%m-%d\"
269 resourcereport \"Resource Graph\" {
270 headline \"Resource Allocation Graph\"
271 columns no, name, utilization, freeload, chart
276 :group
'org-export-taskjuggler
277 :type
'(repeat (string :tag
"Report")))
279 (defcustom org-taskjuggler-default-global-header
""
280 "Default global header for the project.
281 This goes before project declaration, and might be useful for
283 :group
'org-export-taskjuggler
284 :type
'(string :tag
"Preamble"))
286 (defcustom org-taskjuggler-default-global-properties
287 "shift s40 \"Part time shift\" {
288 workinghours wed, thu, fri off
291 "Default global properties for the project.
293 Here you typically define global properties such as shifts,
294 accounts, rates, vacation, macros and flags. Any property that
295 is allowed within the TaskJuggler file can be inserted. You
296 could for example include another TaskJuggler file.
298 The global properties are inserted after the project declaration
299 but before any resource and task declarations."
300 :group
'org-export-taskjuggler
301 :type
'(string :tag
"Preamble"))
303 (defcustom org-taskjuggler-valid-task-attributes
304 '(account start note duration endbuffer endcredit end
305 flags journalentry length limits maxend maxstart minend
306 minstart period reference responsible scheduling
307 startbuffer startcredit statusnote chargeset charge
)
308 "Valid attributes for Taskjuggler tasks.
309 If one of these appears as a property for a headline, it will be
310 exported with the corresponding task."
311 :group
'org-export-taskjuggler
)
313 (defcustom org-taskjuggler-valid-project-attributes
314 '(timingresolution timezone alertlevels currency currencyformat
315 dailyworkinghours extend includejournalentry now numberformat
316 outputdir scenario shorttimeformat timeformat trackingscenario
317 weekstartsmonday weekstartssunday workinghours
319 "Valid attributes for Taskjuggler project.
320 If one of these appears as a property for a headline that is a
321 project definition, it will be exported with the corresponding
322 task. Attribute 'timingresolution' should be the first in the
324 :group
'org-export-taskjuggler
)
326 (defcustom org-taskjuggler-valid-resource-attributes
327 '(limits vacation shift booking efficiency journalentry rate
329 "Valid attributes for Taskjuggler resources.
330 If one of these appears as a property for a headline, it will be
331 exported with the corresponding resource."
332 :group
'org-export-taskjuggler
)
334 (defcustom org-taskjuggler-valid-report-attributes
335 '(headline columns definitions timeformat hideresource hidetask
336 loadunit sorttasks formats period
)
337 "Valid attributes for Taskjuggler reports.
338 If one of these appears as a property for a headline, it will be
339 exported with the corresponding report."
340 :group
'org-export-taskjuggler
)
342 (defcustom org-taskjuggler-process-command
343 "tj3 --silent --no-color --output-dir %o %f"
344 "Command to process a Taskjuggler file.
345 The command will be given to the shell as a command to process a
346 Taskjuggler file. \"%f\" in the command will be replaced by the
347 full file name, \"%o\" by the reports directory (see
348 `org-taskjuggler-reports-directory').
350 If you are targeting Taskjuggler 2.4 (see
351 `org-taskjuggler-target-version') this setting is ignored."
352 :group
'org-export-taskjuggler
)
354 (defcustom org-taskjuggler-reports-directory
"reports"
355 "Default directory to generate the Taskjuggler reports in.
356 The command `org-taskjuggler-process-command' generates the
357 reports and associated files such as CSS inside this directory.
359 If the directory is not an absolute path it is relative to the
360 directory of the exported file. The directory is created if it
363 If you are targeting Taskjuggler 2.4 (see
364 `org-taskjuggler-target-version') this setting is ignored."
365 :group
'org-export-taskjuggler
)
367 (defcustom org-taskjuggler-keep-project-as-task t
368 "Non-nil keeps the project headline as an umbrella task for all tasks.
369 Setting this to nil will allow maintaining completely separated
370 task buckets, while still sharing the same resources pool."
371 :group
'org-export-taskjuggler
378 (defvar org-taskjuggler-final-hook nil
379 "Hook run after a TaskJuggler files has been saved.
380 This hook is run with the name of the file as argument.")
384 ;;; Back-End Definition
386 (org-export-define-backend 'taskjuggler
387 '((template . org-taskjuggler-project-plan
))
389 '(?J
"Export to TaskJuggler"
390 ((?j
"As TJP file" (lambda (a s v b
) (org-taskjuggler-export a s v
)))
391 (?p
"As TJP file and process"
393 (if a
(org-taskjuggler-export a s v
)
394 (org-taskjuggler-export-and-process s v
))))
395 (?o
"As TJP file, process and open"
397 (if a
(org-taskjuggler-export a s v
)
398 (org-taskjuggler-export-process-and-open s v
))))))
399 ;; This property will be used to store unique ids in communication
400 ;; channel. Ids will be retrieved with `org-taskjuggler-get-id'.
401 :options-alist
'((:taskjuggler-unique-ids nil nil nil
)))
407 (defun org-taskjuggler-assign-task-ids (tasks info
)
408 "Assign a unique ID to each task in TASKS.
409 TASKS is a list of headlines. INFO is a plist used as a
410 communication channel. Return value is an alist between
411 headlines and their associated ID. IDs are hierarchical, which
412 means they only need to be unique among the task siblings."
414 build-id
; For byte-compiler.
416 (lambda (tasks local-ids
)
417 (org-element-map tasks
'headline
419 (let ((id (org-taskjuggler--build-unique-id task local-ids
)))
421 (push (cons task id
) alist
)
422 (funcall build-id
(org-element-contents task
) nil
)))
423 info nil
'headline
))))
424 (funcall build-id tasks nil
)
427 (defun org-taskjuggler-assign-resource-ids (resources info
)
428 "Assign a unique ID to each resource within RESOURCES.
429 RESOURCES is a list of headlines. INFO is a plist used as a
430 communication channel. Return value is an alist between
431 headlines and their associated ID."
433 (org-element-map resources
'headline
435 (let ((id (org-taskjuggler--build-unique-id resource ids
)))
444 (defun org-taskjuggler-get-project (info)
445 "Return project in parse tree.
446 INFO is a plist used as a communication channel. First headline
447 in buffer with `org-taskjuggler-project-tag' defines the project.
448 If no such task is defined, pick the first headline in buffer.
449 If there is no headline at all, return nil."
450 (let ((tree (plist-get info
:parse-tree
)))
451 (or (org-element-map tree
'headline
453 (and (member org-taskjuggler-project-tag
454 (org-export-get-tags hl info
))
457 (org-element-map tree
'headline
'identity info t
))))
459 (defun org-taskjuggler-get-id (item info
)
460 "Return id for task or resource ITEM.
461 ITEM is a headline. INFO is a plist used as a communication
462 channel. Return value is a string."
463 (cdr (assq item
(plist-get info
:taskjuggler-unique-ids
))))
465 (defun org-taskjuggler-get-name (item)
466 "Return name for task or resource ITEM.
467 ITEM is a headline. Return value is a string."
468 ;; Quote double quotes in name.
469 (replace-regexp-in-string
470 "\"" "\\\"" (org-element-property :raw-value item
) t t
))
472 (defun org-taskjuggler-get-start (item)
473 "Return start date for task or resource ITEM.
474 ITEM is a headline. Return value is a string or nil if ITEM
475 doesn't have any start date defined."
476 (let ((scheduled (org-element-property :scheduled item
)))
478 (and scheduled
(org-timestamp-format scheduled
"%Y-%02m-%02d"))
479 (and (memq 'start org-taskjuggler-valid-task-attributes
)
480 (org-element-property :START item
)))))
482 (defun org-taskjuggler-get-end (item)
483 "Return end date for task or resource ITEM.
484 ITEM is a headline. Return value is a string or nil if ITEM
485 doesn't have any end date defined."
486 (let ((deadline (org-element-property :deadline item
)))
487 (and deadline
(org-timestamp-format deadline
"%Y-%02m-%02d"))))
491 ;;; Internal Functions
493 (defun org-taskjuggler--indent-string (s)
494 "Indent string S by 2 spaces.
495 Return new string. If S is the empty string, return it."
496 (if (equal "" s
) s
(replace-regexp-in-string "^ *\\S-" " \\&" s
)))
498 (defun org-taskjuggler--build-attributes (item attributes
)
499 "Return attributes string for ITEM.
500 ITEM is a project, task, resource or report headline. ATTRIBUTES
501 is a list of symbols representing valid attributes for ITEM."
504 (let ((value (org-element-property
505 (intern (upcase (format ":%s" attribute
)))
507 (and value
(format "%s %s\n" attribute value
))))
508 (remq nil attributes
) ""))
510 (defun org-taskjuggler--build-unique-id (item unique-ids
)
511 "Return a unique id for a given task or a resource.
512 ITEM is an `headline' type element representing the task or
513 resource. Its id is derived from its name and made unique
514 against UNIQUE-IDS. If the (downcased) first token of the
515 headline is not unique try to add more (downcased) tokens of the
516 headline or finally add more underscore characters (\"_\")."
517 (let ((id (org-string-nw-p (org-element-property :TASK_ID item
))))
518 ;; If an id is specified, use it, as long as it's unique.
519 (if (and id
(not (member id unique-ids
))) id
520 (let* ((parts (org-split-string (org-element-property :raw-value item
)))
521 (id (org-taskjuggler--clean-id (downcase (pop parts
)))))
522 ;; Try to add more parts of the headline to make it unique.
523 (while (and (car parts
) (member id unique-ids
))
524 (setq id
(concat id
"_"
525 (org-taskjuggler--clean-id (downcase (pop parts
))))))
526 ;; If it's still not unique, add "_".
527 (while (member id unique-ids
)
528 (setq id
(concat id
"_")))
531 (defun org-taskjuggler--clean-id (id)
532 "Clean and return ID to make it acceptable for TaskJuggler.
534 ;; Replace non-ascii by "_".
535 (replace-regexp-in-string
537 ;; Make sure id doesn't start with a number.
538 (replace-regexp-in-string "^\\([0-9]\\)" "_\\1" id
)))
544 (defun org-taskjuggler-resolve-dependencies (task info
)
545 "Return a list of all tasks TASK depends on.
546 TASK is a headline. INFO is a plist used as a communication
549 ;; Get all dependencies specified in BLOCKER and DEPENDS task
550 ;; properties. Clean options from them.
551 (let ((deps (concat (org-element-property :BLOCKER task
)
552 (org-element-property :DEPENDS task
))))
554 (org-split-string (replace-regexp-in-string "{.*?}" "" deps
)
558 ;; Find tasks with :task_id: property matching id in DEPS-IDS.
559 ;; Add them to DEPENDS.
560 (let* ((project (org-taskjuggler-get-project info
))
561 (tasks (if org-taskjuggler-keep-project-as-task project
562 (org-element-contents project
))))
564 (org-element-map tasks
'headline
566 (let ((task-id (or (org-element-property :TASK_ID task
)
567 (org-element-property :ID task
))))
568 (and task-id
(member task-id deps-ids
) task
)))
570 ;; Check BLOCKER and DEPENDS properties. If "previous-sibling"
571 ;; belongs to DEPS-ID, add it to DEPENDS.
572 (when (and (member-ignore-case "previous-sibling" deps-ids
)
573 (not (org-export-first-sibling-p task info
)))
574 (let ((prev (org-export-get-previous-element task info
)))
575 (and (not (memq prev depends
)) (push prev depends
)))))
576 ;; Check ORDERED status of parent.
577 (let ((parent (org-export-get-parent task
)))
579 (org-element-property :ORDERED parent
)
580 (not (org-export-first-sibling-p task info
)))
581 (push (org-export-get-previous-element task info
) depends
)))
582 ;; Return dependencies.
585 (defun org-taskjuggler-format-dependencies (dependencies task info
)
586 "Format DEPENDENCIES to match TaskJuggler syntax.
587 DEPENDENCIES is list of dependencies for TASK, as returned by
588 `org-taskjuggler-resolve-depedencies'. TASK is a headline.
589 INFO is a plist used as a communication channel. Return value
590 doesn't include leading \"depends\"."
591 (let* ((dep-str (concat (org-element-property :BLOCKER task
)
593 (org-element-property :DEPENDS task
)))
596 ;; Return path to DEP relatively to TASK.
597 (let ((parent (org-export-get-parent task
))
600 (let ((id (org-element-property :TASK_ID dep
)))
602 (string-match (concat id
" +\\({.*?}\\)") dep-str
)
603 (org-match-string-no-properties 1))))
605 ;; Compute number of exclamation marks by looking for the
606 ;; common ancestor between TASK and DEP.
607 (while (not (org-element-map parent
'headline
608 (lambda (hl) (eq hl dep
))))
610 (setq parent
(org-export-get-parent parent
)))
611 ;; Build path from DEP to PARENT.
612 (while (not (eq parent dep
))
613 (push (org-taskjuggler-get-id dep info
) path
)
614 (setq dep
(org-export-get-parent dep
)))
615 ;; Return full path. Add dependency options, if any.
616 (concat (make-string exclamations ?
!)
617 (mapconcat 'identity path
".")
618 (and option
(concat " " option
)))))))
619 ;; Return dependencies string, without the leading "depends".
620 (mapconcat (lambda (dep) (funcall get-path dep
)) dependencies
", ")))
624 ;;; Translator Functions
626 (defun org-taskjuggler-project-plan (contents info
)
627 "Build TaskJuggler project plan.
628 CONTENTS is ignored. INFO is a plist holding export options.
629 Return complete project plan as a string in TaskJuggler syntax."
630 (let* ((tree (plist-get info
:parse-tree
))
631 (project (or (org-taskjuggler-get-project info
)
632 (error "No project specified"))))
635 (org-element-normalize-string org-taskjuggler-default-global-header
)
636 ;; 2. Insert project.
637 (org-taskjuggler--build-project project info
)
638 ;; 3. Insert global properties.
639 (org-element-normalize-string org-taskjuggler-default-global-properties
)
640 ;; 4. Insert resources. Provide a default one if none is
642 (let ((main-resources
643 ;; Collect contents from various trees marked with
644 ;; `org-taskjuggler-resource-tag'. Only gather top level
647 (org-element-map tree
'headline
649 (and (member org-taskjuggler-resource-tag
650 (org-export-get-tags hl info
))
651 (org-element-map (org-element-contents hl
) 'headline
652 'identity info nil
'headline
)))
653 info nil
'headline
))))
654 ;; Assign a unique ID to each resource. Store it under
655 ;; `:taskjuggler-unique-ids' property in INFO.
657 (plist-put info
:taskjuggler-unique-ids
658 (org-taskjuggler-assign-resource-ids
659 main-resources info
)))
663 (lambda (resource) (org-taskjuggler--build-resource resource info
))
665 (format "resource %s \"%s\" {\n}\n" (user-login-name) user-full-name
))
668 ;; If `org-taskjuggler-keep-project-as-task' is
669 ;; non-nil, there is only one task. Otherwise, every
670 ;; direct children of PROJECT is a top level task.
671 (if org-taskjuggler-keep-project-as-task
(list project
)
672 (or (org-element-map (org-element-contents project
) 'headline
673 'identity info nil
'headline
)
674 (error "No task specified")))))
675 ;; Assign a unique ID to each task. Add it to
676 ;; `:taskjuggler-unique-ids' property in INFO.
678 (plist-put info
:taskjuggler-unique-ids
680 (org-taskjuggler-assign-task-ids main-tasks info
)
681 (plist-get info
:taskjuggler-unique-ids
))))
682 ;; If no resource is allocated among tasks, allocate one to
684 (unless (org-element-map main-tasks
'headline
685 (lambda (task) (org-element-property :ALLOCATE task
))
687 (org-element-put-property
688 (car main-tasks
) :ALLOCATE
689 (or (org-taskjuggler-get-id (car main-resources
) info
)
692 (lambda (task) (org-taskjuggler--build-task task info
))
694 ;; 6. Insert reports. If no report is defined, insert default
697 ;; Collect contents from various trees marked with
698 ;; `org-taskjuggler-report-tag'. Only gather top level
701 (org-element-map tree
'headline
703 (and (member org-taskjuggler-report-tag
704 (org-export-get-tags hl info
))
705 (org-element-map (org-element-contents hl
)
706 'headline
'identity info nil
'headline
)))
707 info nil
'headline
))))
710 (lambda (report) (org-taskjuggler--build-report report info
))
712 ;; insert title in default reports
713 (let* ((title (org-export-data (plist-get info
:title
) info
))
714 (report-title (if (string= title
"")
715 (org-taskjuggler-get-name project
)
718 'org-element-normalize-string
722 (replace-regexp-in-string "%title" report-title report t t
)))
723 org-taskjuggler-default-reports
) "")))))))))
725 (defun org-taskjuggler--build-project (project info
)
726 "Return a project declaration.
727 PROJECT is a headline. INFO is a plist used as a communication
728 channel. If no start date is specified, start today. If no end
729 date is specified, end `org-taskjuggler-default-project-duration'
733 (format "project %s \"%s\" \"%s\" %s %s {\n"
734 (org-taskjuggler-get-id project info
)
735 (org-taskjuggler-get-name project
)
736 ;; Version is obtained through :TASKJUGGLER_VERSION:
737 ;; property or `org-taskjuggler-default-project-version'.
738 (or (org-element-property :VERSION project
)
739 org-taskjuggler-default-project-version
)
740 (or (org-taskjuggler-get-start project
)
741 (format-time-string "%Y-%m-%d"))
742 (let ((end (org-taskjuggler-get-end project
)))
743 (or (and end
(format "- %s" end
))
745 org-taskjuggler-default-project-duration
))))
747 (org-taskjuggler--indent-string
748 (org-taskjuggler--build-attributes
749 project org-taskjuggler-valid-project-attributes
))
753 (defun org-taskjuggler--build-resource (resource info
)
754 "Return a resource declaration.
756 RESOURCE is a headline. INFO is a plist used as a communication
759 All valid attributes from RESOURCE are inserted. If RESOURCE
760 defines a property \"resource_id\" it will be used as the id for
761 this resource. Otherwise it will use the ID property. If
762 neither is defined a unique id will be associated to it."
765 (format "resource %s \"%s\" {\n"
766 (org-taskjuggler--clean-id
767 (or (org-element-property :RESOURCE_ID resource
)
768 (org-element-property :ID resource
)
769 (org-taskjuggler-get-id resource info
)))
770 (org-taskjuggler-get-name resource
))
772 (org-taskjuggler--indent-string
773 (org-taskjuggler--build-attributes
774 resource org-taskjuggler-valid-resource-attributes
))
775 ;; Add inner resources.
776 (org-taskjuggler--indent-string
779 (org-element-map (org-element-contents resource
) 'headline
780 (lambda (hl) (org-taskjuggler--build-resource hl info
))
786 (defun org-taskjuggler--build-report (report info
)
787 "Return a report declaration.
788 REPORT is a headline. INFO is a plist used as a communication
792 (format "%s \"%s\" {\n"
793 (or (org-element-property :REPORT_KIND report
) "taskreport")
794 (org-taskjuggler-get-name report
))
796 (org-taskjuggler--indent-string
797 (org-taskjuggler--build-attributes
798 report org-taskjuggler-valid-report-attributes
))
799 ;; Add inner reports.
800 (org-taskjuggler--indent-string
803 (org-element-map (org-element-contents report
) 'headline
804 (lambda (hl) (org-taskjuggler--build-report hl info
))
810 (defun org-taskjuggler--build-task (task info
)
811 "Return a task declaration.
813 TASK is a headline. INFO is a plist used as a communication
816 All valid attributes from TASK are inserted. If TASK defines
817 a property \"task_id\" it will be used as the id for this task.
818 Otherwise it will use the ID property. If neither is defined
819 a unique id will be associated to it."
820 (let* ((allocate (org-element-property :ALLOCATE task
))
822 (if (eq (org-element-property :todo-type task
) 'done
) "100"
823 (org-element-property :COMPLETE task
)))
824 (depends (org-taskjuggler-resolve-dependencies task info
))
825 (effort (let ((property
826 (intern (concat ":" (upcase org-effort-property
)))))
827 (org-element-property property task
)))
829 (or (org-element-property :MILESTONE task
)
830 (not (or (org-element-map (org-element-contents task
) 'headline
831 'identity info t
) ; Has task any child?
833 (org-element-property :LENGTH task
)
834 (org-element-property :DURATION task
)
835 (and (org-taskjuggler-get-start task
)
836 (org-taskjuggler-get-end task
))
837 (org-element-property :PERIOD task
)))))
839 (let ((pri (org-element-property :priority task
)))
841 (max 1 (/ (* 1000 (- org-lowest-priority pri
))
842 (- org-lowest-priority org-highest-priority
)))))))
845 (format "task %s \"%s\" {\n"
846 (org-taskjuggler-get-id task info
)
847 (org-taskjuggler-get-name task
))
848 ;; Add default attributes.
850 (format " depends %s\n"
851 (org-taskjuggler-format-dependencies depends task info
)))
853 (format " purge %s\n allocate %s\n"
854 ;; Compatibility for previous TaskJuggler versions.
855 (if (>= org-taskjuggler-target-version
3.0) "allocate"
858 (and complete
(format " complete %s\n" complete
))
860 (format " effort %s\n"
861 (let* ((minutes (org-duration-string-to-minutes effort
))
862 (hours (/ minutes
60.0)))
863 (format "%.1fh" hours
))))
864 (and priority
(format " priority %s\n" priority
))
865 (and milestone
" milestone\n")
866 ;; Add other valid attributes.
867 (org-taskjuggler--indent-string
868 (org-taskjuggler--build-attributes
869 task org-taskjuggler-valid-task-attributes
))
871 (org-taskjuggler--indent-string
873 (org-element-map (org-element-contents task
) 'headline
874 (lambda (hl) (org-taskjuggler--build-task hl info
))
882 ;;; Interactive Functions
885 (defun org-taskjuggler-export (&optional async subtreep visible-only
)
886 "Export current buffer to a TaskJuggler file.
888 The exporter looks for a tree with tag that matches
889 `org-taskjuggler-project-tag' and takes this as the tasks for
890 this project. The first node of this tree defines the project
891 properties such as project name and project period.
893 If there is a tree with tag that matches
894 `org-taskjuggler-resource-tag' this tree is taken as resources
895 for the project. If no resources are specified, a default
896 resource is created and allocated to the project.
898 Also the TaskJuggler project will be created with default reports
899 as defined in `org-taskjuggler-default-reports'.
901 If narrowing is active in the current buffer, only export its
904 If a region is active, export that region.
906 A non-nil optional argument ASYNC means the process should happen
907 asynchronously. The resulting file should be accessible through
908 the `org-export-stack' interface.
910 When optional argument SUBTREEP is non-nil, export the sub-tree
911 at point, extracting information from the headline properties
914 When optional argument VISIBLE-ONLY is non-nil, don't export
915 contents of hidden elements.
917 Return output file's name."
920 (org-export-output-file-name org-taskjuggler-extension subtreep
)))
921 (org-export-to-file 'taskjuggler outfile
922 async subtreep visible-only nil nil
924 (run-hook-with-args 'org-taskjuggler-final-hook file
) nil
))))
927 (defun org-taskjuggler-export-and-process (&optional subtreep visible-only
)
928 "Export current buffer to a TaskJuggler file and process it.
930 The exporter looks for a tree with tag that matches
931 `org-taskjuggler-project-tag' and takes this as the tasks for
932 this project. The first node of this tree defines the project
933 properties such as project name and project period.
935 If there is a tree with tag that matches
936 `org-taskjuggler-resource-tag' this tree is taken as resources
937 for the project. If no resources are specified, a default
938 resource is created and allocated to the project.
940 Also the TaskJuggler project will be created with default reports
941 as defined in `org-taskjuggler-default-reports'.
943 If narrowing is active in the current buffer, only export its
946 If a region is active, export that region.
948 When optional argument SUBTREEP is non-nil, export the sub-tree
949 at point, extracting information from the headline properties
952 When optional argument VISIBLE-ONLY is non-nil, don't export
953 contents of hidden elements.
955 Return a list of reports."
957 (let ((file (org-taskjuggler-export nil subtreep visible-only
)))
958 (org-taskjuggler-compile file
)))
961 (defun org-taskjuggler-export-process-and-open (&optional subtreep visible-only
)
962 "Export current buffer to a TaskJuggler file, process and open it.
964 Export and process the file using
965 `org-taskjuggler-export-and-process' and open the generated
966 reports with a browser.
968 If you are targeting TaskJuggler 2.4 (see
969 `org-taskjuggler-target-version') the processing and display of
970 the reports is done using the TaskJuggler GUI."
972 (if (< org-taskjuggler-target-version
3.0)
973 (let* ((process-name "TaskJugglerUI")
975 (concat process-name
" "
976 (org-taskjuggler-export nil subtreep visible-only
))))
977 (start-process-shell-command process-name nil command
))
978 (dolist (report (org-taskjuggler-export-and-process subtreep visible-only
))
979 (org-open-file report
))))
981 (defun org-taskjuggler-compile (file)
982 "Compile a TaskJuggler file.
984 FILE is the name of the file being compiled. Processing is done
985 through the command given in `org-taskjuggler-process-command'.
987 Return a list of reports."
988 (let* ((full-name (file-truename file
))
991 org-taskjuggler-reports-directory
(file-name-directory file
)))
993 (message (format "Processing TaskJuggler file %s..." file
))
994 (save-window-excursion
995 (let ((outbuf (get-buffer-create "*Org Taskjuggler Output*")))
996 (unless (file-directory-p out-dir
)
997 (make-directory out-dir t
))
998 (with-current-buffer outbuf
(erase-buffer))
1000 (replace-regexp-in-string
1001 "%f" (shell-quote-argument full-name
)
1002 (replace-regexp-in-string
1003 "%o" (shell-quote-argument out-dir
)
1004 org-taskjuggler-process-command t t
) t t
) outbuf
)
1005 ;; Collect standard errors from output buffer.
1006 (setq errors
(org-taskjuggler--collect-errors outbuf
)))
1008 (message "Process completed.")
1009 (error (format "TaskJuggler failed with errors: %s" errors
))))
1010 (file-expand-wildcards (format "%s/*.html" out-dir
))))
1012 (defun org-taskjuggler--collect-errors (buffer)
1013 "Collect some kind of errors from \"tj3\" command output.
1015 BUFFER is the buffer containing output.
1017 Return collected error types as a string, or nil if there was
1019 (with-current-buffer buffer
1021 (goto-char (point-min))
1022 (let ((case-fold-search t
)
1024 (while (re-search-forward "^.+:[0-9]+: \\(.*\\)$" nil t
)
1025 (setq errors
(concat errors
" " (match-string 1))))
1026 (and (org-string-nw-p errors
) (org-trim errors
))))))
1029 (provide 'ox-taskjuggler
)
1032 ;; sentence-end-double-space: t
1035 ;;; ox-taskjuggler.el ends here