org.el (org-read-date-minibuffer-local-map): Check if we are at the beginning of...
[org-mode.git] / contrib / lisp / ox-taskjuggler.el
blob4724ec3ee008f4a98d7f5d20318149e4942fe4f1
1 ;;; ox-taskjuggler.el --- TaskJuggler Back-End for Org Export Engine
2 ;;
3 ;; Copyright (C) 2007-2013 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
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/>.
28 ;;; Commentary:
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.
45 ;; * Installation
47 ;; Put this file into your load-path and the following line into your
48 ;; ~/.emacs:
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'
59 ;; * Tasks
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
65 ;; in:
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.
75 ;; * Resources
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,
105 ;; etc for tasks.
107 ;; * Dependencies
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
121 ;; :PROPERTIES:
122 ;; :task_id: training_material
123 ;; :ORDERED: t
124 ;; :END:
125 ;; ** Markup Guidelines
126 ;; :PROPERTIES:
127 ;; :Effort: 2d
128 ;; :END:
129 ;; ** Workflow Guidelines
130 ;; :PROPERTIES:
131 ;; :Effort: 2d
132 ;; :END:
133 ;; * Presentation
134 ;; :PROPERTIES:
135 ;; :Effort: 2d
136 ;; :BLOCKER: training_material { gapduration 1d } some_other_task
137 ;; :END:
139 ;;;; * TODO
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
145 ;;; Code:
147 (eval-when-compile (require 'cl))
149 (require 'ox)
153 ;;; User Variables
155 (defgroup org-export-taskjuggler nil
156 "Options specific for TaskJuggler export back-end."
157 :tag "Org Export TaskJuggler"
158 :group 'org-export)
160 (defcustom org-taskjuggler-extension ".tjp"
161 "Extension of TaskJuggler files."
162 :group 'org-export-taskjuggler
163 :type 'string)
165 (defcustom org-taskjuggler-project-tag "taskjuggler_project"
166 "Tag marking project's tasks.
167 This tag is used to find the tree containing all the tasks for
168 the project."
169 :group 'org-export-taskjuggler
170 :type 'string)
172 (defcustom org-taskjuggler-resource-tag "taskjuggler_resource"
173 "Tag marking project's resources.
174 This tag is used to find the tree containing all the resources
175 for the project."
176 :group 'org-export-taskjuggler
177 :type 'string)
179 (defcustom org-taskjuggler-report-tag "taskjuggler_report"
180 "Tag marking project's reports.
181 This tag is used to find the tree containing all the reports for
182 the project."
183 :group 'org-export-taskjuggler
184 :type 'string)
186 (defcustom org-taskjuggler-target-version 3.0
187 "Which version of TaskJuggler the exporter is targeting.
188 By default a project plan is exported which conforms to version
189 3.x of TaskJuggler. For a project plan that is compatible with
190 versions of TaskJuggler older than 3.0 set this to 2.4.
192 If you change this variable be sure to also change
193 `org-taskjuggler-default-reports' as the format of reports has
194 changed considerably between version 2.x and 3.x of TaskJuggler"
195 :group 'org-export-taskjuggler
196 :type 'number)
198 (defcustom org-taskjuggler-default-project-version "1.0"
199 "Default version string for the project.
200 This value can also be set with the \":VERSION:\" property
201 associated to the headline defining the project."
202 :group 'org-export-taskjuggler
203 :type 'string)
205 (defcustom org-taskjuggler-default-project-duration 280
206 "Default project duration.
207 The value will be used if no start and end date have been defined
208 in the root node of the task tree, i.e. the tree that has been
209 marked with `org-taskjuggler-project-tag'"
210 :group 'org-export-taskjuggler
211 :type 'integer)
213 (defcustom org-taskjuggler-default-reports
214 '("textreport report \"Plan\" {
215 formats html
216 header '== <-query attribute=\"name\"-> =='
218 center -8<-
219 [#Plan Plan] | [#Resource_Allocation Resource Allocation]
220 ----
221 === Plan ===
222 <[report id=\"plan\"]>
223 ----
224 === Resource Allocation ===
225 <[report id=\"resourceGraph\"]>
226 ->8-
229 # A traditional Gantt chart with a project overview.
230 taskreport plan \"\" {
231 headline \"Project Plan\"
232 columns bsi, name, start, end, effort, chart
233 loadunit shortauto
234 hideresource 1
237 # A graph showing resource allocation. It identifies whether each
238 # resource is under- or over-allocated for.
239 resourcereport resourceGraph \"\" {
240 headline \"Resource Allocation Graph\"
241 columns no, name, effort, weekly
242 loadunit shortauto
243 hidetask ~(isleaf() & isleaf_())
244 sorttasks plan.start.up
246 "Default reports for the project.
247 These are sensible default reports to give a good out-of-the-box
248 result when exporting without defining any reports. If you want
249 to define your own reports you can change them here or simply
250 define the default reports so that they include an external
251 report definition as follows:
253 include reports.tji
255 These default are made to work with tj3. If you are targeting
256 TaskJuggler 2.4 (see `org-taskjuggler-target-version') please
257 change these defaults to something like the following:
259 taskreport \"Gantt Chart\" {
260 headline \"Project Gantt Chart\"
261 columns hierarchindex, name, start, end, effort, duration, completed, chart
262 timeformat \"%Y-%m-%d\"
263 hideresource 1
264 loadunit shortauto
267 resourcereport \"Resource Graph\" {
268 headline \"Resource Allocation Graph\"
269 columns no, name, utilization, freeload, chart
270 loadunit shortauto
271 sorttasks startup
272 hidetask ~isleaf()
274 :group 'org-export-taskjuggler
275 :type '(repeat (string :tag "Report")))
277 (defcustom org-taskjuggler-default-global-header ""
278 "Default global header for the project.
279 This goes before project declaration, and might be useful for
280 early macros."
281 :group 'org-export-taskjuggler
282 :type '(string :tag "Preamble"))
284 (defcustom org-taskjuggler-default-global-properties
285 "shift s40 \"Part time shift\" {
286 workinghours wed, thu, fri off
289 "Default global properties for the project.
291 Here you typically define global properties such as shifts,
292 accounts, rates, vacation, macros and flags. Any property that
293 is allowed within the TaskJuggler file can be inserted. You
294 could for example include another TaskJuggler file.
296 The global properties are inserted after the project declaration
297 but before any resource and task declarations."
298 :group 'org-export-taskjuggler
299 :type '(string :tag "Preamble"))
301 (defcustom org-taskjuggler-valid-task-attributes
302 '(account start note duration endbuffer endcredit end
303 flags journalentry length limits maxend maxstart minend
304 minstart period reference responsible scheduling
305 startbuffer startcredit statusnote chargeset charge)
306 "Valid attributes for Taskjuggler tasks.
307 If one of these appears as a property for a headline, it will be
308 exported with the corresponding task."
309 :group 'org-export-taskjuggler)
311 (defcustom org-taskjuggler-valid-resource-attributes
312 '(limits vacation shift booking efficiency journalentry rate
313 workinghours flags)
314 "Valid attributes for Taskjuggler resources.
315 If one of these appears as a property for a headline, it will be
316 exported with the corresponding resource."
317 :group 'org-export-taskjuggler)
319 (defcustom org-taskjuggler-valid-report-attributes
320 '(headline columns definitions timeformat hideresource hidetask
321 loadunit sorttasks formats period)
322 "Valid attributes for Taskjuggler reports.
323 If one of these appears as a property for a headline, it will be
324 exported with the corresponding report."
325 :group 'org-export-taskjuggler)
327 (defcustom org-taskjuggler-keep-project-as-task t
328 "Non-nil keeps the project headline as an umbrella task for all tasks.
329 Setting this to nil will allow maintaining completely separated
330 task buckets, while still sharing the same resources pool."
331 :group 'org-export-taskjuggler
332 :type 'boolean)
336 ;;; Hooks
338 (defvar org-taskjuggler-final-hook nil
339 "Hook run after a TaskJuggler files has been saved.
340 This hook is run with the name of the file as argument.")
344 ;;; Back-End Definition
346 (org-export-define-backend 'taskjuggler
347 '((template . org-taskjuggler-project-plan))
348 :menu-entry
349 '(?J "Export to TaskJuggler"
350 ((?j "As TJP file" (lambda (a s v b) (org-taskjuggler-export a s v)))
351 (?o "As TJP file and open"
352 (lambda (a s v b)
353 (if a (org-taskjuggler-export a s v)
354 (org-taskjuggler-export-and-open s v))))))
355 ;; This property will be used to store unique ids in communication
356 ;; channel. Ids will be retrieved with `org-taskjuggler-get-id'.
357 :options-alist '((:taskjuggler-unique-ids nil nil nil)))
361 ;;; Unique IDs
363 (defun org-taskjuggler-assign-task-ids (tasks info)
364 "Assign a unique ID to each task in TASKS.
365 TASKS is a list of headlines. INFO is a plist used as a
366 communication channel. Return value is an alist between
367 headlines and their associated ID. IDs are hierarchical, which
368 means they only need to be unique among the task siblings."
369 (let* (alist
370 (build-id
371 (lambda (tasks local-ids)
372 (org-element-map tasks 'headline
373 (lambda (task)
374 (let ((id (org-taskjuggler--build-unique-id task local-ids)))
375 (push id local-ids)
376 (push (cons task id) alist)
377 (funcall build-id (org-element-contents task) nil)))
378 info nil 'headline))))
379 (funcall build-id tasks nil)
380 alist))
382 (defun org-taskjuggler-assign-resource-ids (resources info)
383 "Assign a unique ID to each resource within RESOURCES.
384 RESOURCES is a list of headlines. INFO is a plist used as a
385 communication channel. Return value is an alist between
386 headlines and their associated ID."
387 (let (ids)
388 (org-element-map resources 'headline
389 (lambda (resource)
390 (let ((id (org-taskjuggler--build-unique-id resource ids)))
391 (push id ids)
392 (cons resource id)))
393 info)))
397 ;;; Accessors
399 (defun org-taskjuggler-get-project (info)
400 "Return project in parse tree.
401 INFO is a plist used as a communication channel. First headline
402 in buffer with `org-taskjuggler-project-tag' defines the project.
403 If no such task is defined, pick the first headline in buffer.
404 If there is no headline at all, return nil."
405 (or (org-element-map (plist-get info :parse-tree) 'headline
406 (lambda (hl)
407 (and (member org-taskjuggler-project-tag
408 (org-export-get-tags hl info))
409 hl))
410 info t)
411 (org-element-map tree 'headline 'identity info t)))
413 (defun org-taskjuggler-get-id (item info)
414 "Return id for task or resource ITEM.
415 ITEM is a headline. INFO is a plist used as a communication
416 channel. Return value is a string."
417 (cdr (assq item (plist-get info :taskjuggler-unique-ids))))
419 (defun org-taskjuggler-get-name (item)
420 "Return name for task or resource ITEM.
421 ITEM is a headline. Return value is a string."
422 ;; Quote double quotes in name.
423 (replace-regexp-in-string
424 "\"" "\\\"" (org-element-property :raw-value item) t t))
426 (defun org-taskjuggler-get-start (item)
427 "Return start date for task or resource ITEM.
428 ITEM is a headline. Return value is a string or nil if ITEM
429 doesn't have any start date defined.."
430 (let ((scheduled (org-element-property :scheduled item)))
431 (and scheduled (org-timestamp-format scheduled "%Y-%02m-%02d"))))
433 (defun org-taskjuggler-get-end (item)
434 "Return end date for task or resource ITEM.
435 ITEM is a headline. Return value is a string or nil if ITEM
436 doesn't have any end date defined.."
437 (let ((deadline (org-element-property :deadline item)))
438 (and deadline (org-timestamp-format deadline "%Y-%02m-%02d"))))
442 ;;; Internal Functions
444 (defun org-taskjuggler--indent-string (s)
445 "Indent string S by 2 spaces.
446 Return new string. If S is the empty string, return it."
447 (if (equal "" s) s (replace-regexp-in-string "^ *\\S-" " \\&" s)))
449 (defun org-taskjuggler--build-attributes (item attributes)
450 "Return attributes string for task, resource or report ITEM.
451 ITEM is a headline. ATTRIBUTES is a list of symbols
452 representing valid attributes for ITEM."
453 (mapconcat
454 (lambda (attribute)
455 (let ((value (org-element-property
456 (intern (upcase (format ":%s" attribute)))
457 item)))
458 (and value (format "%s %s\n" attribute value))))
459 (remq nil attributes) ""))
461 (defun org-taskjuggler--build-unique-id (item unique-ids)
462 "Return a unique id for a given task or a resource.
463 ITEM is an `headline' type element representing the task or
464 resource. Its id is derived from its name and made unique
465 against UNIQUE-IDS. If the (downcased) first token of the
466 headline is not unique try to add more (downcased) tokens of the
467 headline or finally add more underscore characters (\"_\")."
468 (let ((id (org-string-nw-p (org-element-property :TASK_ID item))))
469 ;; If an id is specified, use it, as long as it's unique.
470 (if (and id (not (member id unique-ids))) id
471 (let* ((parts (org-split-string (org-element-property :raw-value item)))
472 (id (org-taskjuggler--clean-id (downcase (pop parts)))))
473 ;; Try to add more parts of the headline to make it unique.
474 (while (and (car parts) (member id unique-ids))
475 (setq id (concat id "_"
476 (org-taskjuggler--clean-id (downcase (pop parts))))))
477 ;; If it's still not unique, add "_".
478 (while (member id unique-ids)
479 (setq id (concat id "_")))
480 id))))
482 (defun org-taskjuggler--clean-id (id)
483 "Clean and return ID to make it acceptable for TaskJuggler.
484 ID is a string."
485 ;; Replace non-ascii by "_".
486 (replace-regexp-in-string
487 "[^a-zA-Z0-9_]" "_"
488 ;; Make sure id doesn't start with a number.
489 (replace-regexp-in-string "^\\([0-9]\\)" "_\\1" id)))
493 ;;; Dependencies
495 (defun org-taskjuggler-resolve-dependencies (task info)
496 "Return a list of all tasks TASK depends on.
497 TASK is a headline. INFO is a plist used as a communication
498 channel."
499 (let ((deps-ids
500 ;; Get all dependencies specified in BLOCKER and DEPENDS task
501 ;; properties. Clean options from them.
502 (let ((deps (concat (org-element-property :BLOCKER task)
503 (org-element-property :DEPENDS task))))
504 (and deps
505 (org-split-string (replace-regexp-in-string "{.*?}" "" deps)
506 "[ ,]* +"))))
507 depends)
508 (when deps-ids
509 ;; Find tasks with :task_id: property matching id in DEPS-IDS.
510 ;; Add them to DEPENDS.
511 (let* ((project (org-taskjuggler-get-project info))
512 (tasks (if org-taskjuggler-keep-project-as-task project
513 (org-element-contents project))))
514 (setq depends
515 (org-element-map tasks 'headline
516 (lambda (task)
517 (let ((task-id (org-element-property :TASK_ID task)))
518 (and task-id (member task-id deps-ids) task)))
519 info)))
520 ;; Check BLOCKER and DEPENDS properties. If "previous-sibling"
521 ;; belongs to DEPS-ID, add it to DEPENDS.
522 (when (and (member-ignore-case "previous-sibling" deps-ids)
523 (not (org-export-first-sibling-p task info)))
524 (let ((prev (org-export-get-previous-element task info)))
525 (and (not (memq prev depends)) (push prev depends)))))
526 ;; Check ORDERED status of parent.
527 (let ((parent (org-export-get-parent task)))
528 (when (and parent
529 (org-element-property :ORDERED parent)
530 (not (org-export-first-sibling-p task info)))
531 (push (org-export-get-previous-element task info) depends)))
532 ;; Return dependencies.
533 depends))
535 (defun org-taskjuggler-format-dependencies (dependencies task info)
536 "Format DEPENDENCIES to match TaskJuggler syntax.
537 DEPENDENCIES is list of dependencies for TASK, as returned by
538 `org-taskjuggler-resolve-depedencies'. TASK is a headline.
539 INFO is a plist used as a communication channel. Return value
540 doesn't include leading \"depends\"."
541 (let ((dep-str (concat (org-element-property :BLOCKER task)
543 (org-element-property :DEPENDS task)))
544 (get-path
545 (lambda (dep)
546 ;; Return path to DEP relatively to TASK.
547 (let ((parent (org-export-get-parent task))
548 (exclamations 1)
549 (option
550 (let ((id (org-element-property :TASK_ID dep)))
551 (and id
552 (string-match (concat id " +\\({.*?}\\)") dep-str)
553 (org-match-string-no-properties 1))))
554 path)
555 ;; Compute number of exclamation marks by looking for the
556 ;; common ancestor between TASK and DEP.
557 (while (not (org-element-map parent 'headline
558 (lambda (hl) (eq hl dep))))
559 (incf exclamations)
560 (setq parent (org-export-get-parent parent)))
561 ;; Build path from DEP to PARENT.
562 (while (not (eq parent dep))
563 (push (org-taskjuggler-get-id dep info) path)
564 (setq dep (org-export-get-parent dep)))
565 ;; Return full path. Add dependency options, if any.
566 (concat (make-string exclamations ?!)
567 (mapconcat 'identity path ".")
568 (and option (concat " " option)))))))
569 ;; Return dependencies string, without the leading "depends".
570 (mapconcat (lambda (dep) (funcall get-path dep)) dependencies ", ")))
574 ;;; Translator Functions
576 (defun org-taskjuggler-project-plan (contents info)
577 "Build TaskJuggler project plan.
578 CONTENTS is ignored. INFO is a plist holding export options.
579 Return complete project plan as a string in TaskJuggler syntax."
580 (let* ((tree (plist-get info :parse-tree))
581 (project (or (org-taskjuggler-get-project info)
582 (error "No project specified"))))
583 (concat
584 ;; 1. Insert header.
585 (org-element-normalize-string org-taskjuggler-default-global-header)
586 ;; 2. Insert project.
587 (org-taskjuggler--build-project project info)
588 ;; 3. Insert global properties.
589 (org-element-normalize-string org-taskjuggler-default-global-properties)
590 ;; 4. Insert resources. Provide a default one if none is
591 ;; specified.
592 (let ((main-resources
593 ;; Collect contents from various trees marked with
594 ;; `org-taskjuggler-resource-tag'. Only gather top level
595 ;; resources.
596 (apply 'append
597 (org-element-map tree 'headline
598 (lambda (hl)
599 (and (member org-taskjuggler-resource-tag
600 (org-export-get-tags hl info))
601 (org-element-map (org-element-contents hl) 'headline
602 'identity info nil 'headline)))
603 info nil 'headline))))
604 ;; Assign a unique ID to each resource. Store it under
605 ;; `:taskjuggler-unique-ids' property in INFO.
606 (setq info
607 (plist-put info :taskjuggler-unique-ids
608 (org-taskjuggler-assign-resource-ids
609 main-resources info)))
610 (concat
611 (if main-resources
612 (mapconcat
613 (lambda (resource) (org-taskjuggler--build-resource resource info))
614 main-resources "")
615 (format "resource %s \"%s\" {\n}\n" (user-login-name) user-full-name))
616 ;; 5. Insert tasks.
617 (let ((main-tasks
618 ;; If `org-taskjuggler-keep-project-as-task' is
619 ;; non-nil, there is only one task. Otherwise, every
620 ;; direct children of PROJECT is a top level task.
621 (if org-taskjuggler-keep-project-as-task (list project)
622 (or (org-element-map (org-element-contents project) 'headline
623 'identity info nil 'headline)
624 (error "No task specified")))))
625 ;; Assign a unique ID to each task. Add it to
626 ;; `:taskjuggler-unique-ids' property in INFO.
627 (setq info
628 (plist-put info :taskjuggler-unique-ids
629 (append
630 (org-taskjuggler-assign-task-ids main-tasks info)
631 (plist-get info :taskjuggler-unique-ids))))
632 ;; If no resource is allocated among tasks, allocate one to
633 ;; the first task.
634 (unless (org-element-map main-tasks 'headline
635 (lambda (task) (org-element-property :ALLOCATE task))
636 info t)
637 (org-element-put-property
638 (car main-tasks) :ALLOCATE
639 (or (org-taskjuggler-get-id (car main-resources) info)
640 (user-login-name))))
641 (mapconcat
642 (lambda (task) (org-taskjuggler--build-task task info))
643 main-tasks ""))
644 ;; 6. Insert reports. If no report is defined, insert default
645 ;; reports.
646 (let ((main-reports
647 ;; Collect contents from various trees marked with
648 ;; `org-taskjuggler-report-tag'. Only gather top level
649 ;; reports.
650 (apply 'append
651 (org-element-map tree 'headline
652 (lambda (hl)
653 (and (member org-taskjuggler-report-tag
654 (org-export-get-tags hl info))
655 (org-element-map (org-element-contents hl)
656 'headline 'identity info nil 'headline)))
657 info nil 'headline))))
658 (if main-reports
659 (mapconcat
660 (lambda (report) (org-taskjuggler--build-report report info))
661 main-reports "")
662 (mapconcat 'org-element-normalize-string
663 org-taskjuggler-default-reports ""))))))))
665 (defun org-taskjuggler--build-project (project info)
666 "Return a project declaration.
667 PROJECT is a headline. INFO is a plist used as a communication
668 channel. If no start date is specified, start today. If no end
669 date is specified, end `org-taskjuggler-default-project-duration'
670 days from now."
671 (format "project %s \"%s\" \"%s\" %s %s {\n}\n"
672 (org-taskjuggler-get-id project info)
673 (org-taskjuggler-get-name project)
674 ;; Version is obtained through :TASKJUGGLER_VERSION:
675 ;; property or `org-taskjuggler-default-project-version'.
676 (or (org-element-property :VERSION project)
677 org-taskjuggler-default-project-version)
678 (or (org-taskjuggler-get-start project)
679 (format-time-string "%Y-%m-%d"))
680 (let ((end (org-taskjuggler-get-end project)))
681 (or (and end (format "- %s" end))
682 (format "+%sd" org-taskjuggler-default-project-duration)))))
684 (defun org-taskjuggler--build-resource (resource info)
685 "Return a resource declaration.
687 RESOURCE is a headline. INFO is a plist used as a communication
688 channel.
690 All valid attributes from RESOURCE are inserted. If RESOURCE
691 defines a property \"resource_id\" it will be used as the id for
692 this resource. Otherwise it will use the ID property. If
693 neither is defined a unique id will be associated to it."
694 (concat
695 ;; Opening resource.
696 (format "resource %s \"%s\" {\n"
697 (org-taskjuggler--clean-id
698 (or (org-element-property :RESOURCE_ID resource)
699 (org-element-property :ID resource)
700 (org-taskjuggler-get-id resource info)))
701 (org-taskjuggler-get-name resource))
702 ;; Add attributes.
703 (org-taskjuggler--indent-string
704 (org-taskjuggler--build-attributes
705 resource org-taskjuggler-valid-resource-attributes))
706 ;; Add inner resources.
707 (org-taskjuggler--indent-string
708 (mapconcat
709 'identity
710 (org-element-map (org-element-contents resource) 'headline
711 (lambda (hl) (org-taskjuggler--build-resource hl info))
712 info nil 'headline)
713 ""))
714 ;; Closing resource.
715 "}\n"))
717 (defun org-taskjuggler--build-report (report info)
718 "Return a report declaration.
719 REPORT is a headline. INFO is a plist used as a communication
720 channel."
721 (concat
722 ;; Opening report.
723 (format "%s \"%s\" {\n"
724 (or (org-element-property :REPORT_KIND report) "taskreport")
725 (org-taskjuggler-get-name report))
726 ;; Add attributes.
727 (org-taskjuggler--indent-string
728 (org-taskjuggler--build-attributes
729 report org-taskjuggler-valid-report-attributes))
730 ;; Add inner reports.
731 (org-taskjuggler--indent-string
732 (mapconcat
733 'identity
734 (org-element-map (org-element-contents report) 'headline
735 (lambda (hl) (org-taskjuggler--build-report hl info))
736 info nil 'headline)
737 ""))
738 ;; Closing report.
739 "}\n"))
741 (defun org-taskjuggler--build-task (task info)
742 "Return a task declaration.
744 TASK is a headline. INFO is a plist used as a communication
745 channel.
747 All valid attributes from TASK are inserted. If TASK defines
748 a property \"task_id\" it will be used as the id for this task.
749 Otherwise it will use the ID property. If neither is defined
750 a unique id will be associated to it."
751 (let* ((allocate (org-element-property :ALLOCATE task))
752 (complete
753 (if (eq (org-element-property :todo-type task) 'done) "100"
754 (org-element-property :COMPLETE task)))
755 (depends (org-taskjuggler-resolve-dependencies task info))
756 (effort (org-element-property :EFFORT task))
757 (milestone
758 (or (org-element-property :MILESTONE task)
759 (not (or (org-element-map (org-element-contents task) 'headline
760 'identity info t) ; Has task any child?
761 effort
762 (org-element-property :LENGTH task)
763 (org-element-property :DURATION task)
764 (and (org-taskjuggler-get-start task)
765 (org-taskjuggler-get-end task))
766 (org-element-property :PERIOD task)))))
767 (priority
768 (let ((pri (org-element-property :priority task)))
769 (and pri
770 (max 1 (/ (* 1000 (- org-lowest-priority pri))
771 (- org-lowest-priority org-highest-priority)))))))
772 (concat
773 ;; Opening task.
774 (format "task %s \"%s\" {\n"
775 (org-taskjuggler-get-id task info)
776 (org-taskjuggler-get-name task))
777 ;; Add default attributes.
778 (and depends
779 (format " depends %s\n"
780 (org-taskjuggler-format-dependencies depends task info)))
781 (and allocate
782 (format " purge %s\n allocate %s\n"
783 ;; Compatibility for previous TaskJuggler versions.
784 (if (>= org-taskjuggler-target-version 3.0) "allocate"
785 "allocations")
786 allocate))
787 (and complete (format " complete %s\n" complete))
788 (and effort
789 (format " effort %s\n"
790 (let* ((minutes (org-duration-string-to-minutes effort))
791 (hours (/ minutes 60.0)))
792 (format "%.1fh" hours))))
793 (and priority (format " priority %s\n" priority))
794 (and milestone " milestone\n")
795 ;; Add other valid attributes.
796 (org-taskjuggler--indent-string
797 (org-taskjuggler--build-attributes
798 task org-taskjuggler-valid-task-attributes))
799 ;; Add inner tasks.
800 (org-taskjuggler--indent-string
801 (mapconcat 'identity
802 (org-element-map (org-element-contents task) 'headline
803 (lambda (hl) (org-taskjuggler--build-task hl info))
804 info nil 'headline)
805 ""))
806 ;; Closing task.
807 "}\n")))
811 ;;; Interactive Functions
813 ;;;###autoload
814 (defun org-taskjuggler-export (&optional async subtreep visible-only)
815 "Export current buffer to a TaskJuggler file.
817 The exporter looks for a tree with tag that matches
818 `org-taskjuggler-project-tag' and takes this as the tasks for
819 this project. The first node of this tree defines the project
820 properties such as project name and project period.
822 If there is a tree with tag that matches
823 `org-taskjuggler-resource-tag' this tree is taken as resources
824 for the project. If no resources are specified, a default
825 resource is created and allocated to the project.
827 Also the TaskJuggler project will be created with default reports
828 as defined in `org-taskjuggler-default-reports'.
830 If narrowing is active in the current buffer, only export its
831 narrowed part.
833 If a region is active, export that region.
835 A non-nil optional argument ASYNC means the process should happen
836 asynchronously. The resulting file should be accessible through
837 the `org-export-stack' interface.
839 When optional argument SUBTREEP is non-nil, export the sub-tree
840 at point, extracting information from the headline properties
841 first.
843 When optional argument VISIBLE-ONLY is non-nil, don't export
844 contents of hidden elements.
846 Return output file's name."
847 (interactive)
848 (let ((outfile
849 (org-export-output-file-name org-taskjuggler-extension subtreep)))
850 (if async
851 (org-export-async-start
852 (lambda (f)
853 (org-export-add-to-stack f 'taskjuggler)
854 (run-hook-with-args 'org-taskjuggler-final-hook f))
855 `(expand-file-name
856 (org-export-to-file 'taskjuggler ,outfile ,subtreep ,visible-only)))
857 (org-export-to-file 'taskjuggler outfile subtreep visible-only)
858 (run-hook-with-args 'org-taskjuggler-final-hook outfile)
859 outfile)))
861 ;;;###autoload
862 (defun org-taskjuggler-export-and-open (&optional subtreep visible-only)
863 "Export current buffer to a TaskJuggler file and open it.
865 The exporter looks for a tree with tag that matches
866 `org-taskjuggler-project-tag' and takes this as the tasks for
867 this project. The first node of this tree defines the project
868 properties such as project name and project period.
870 If there is a tree with tag that matches
871 `org-taskjuggler-resource-tag' this tree is taken as resources
872 for the project. If no resources are specified, a default
873 resource is created and allocated to the project.
875 Also the TaskJuggler project will be created with default reports
876 as defined in `org-taskjuggler-default-reports'.
878 If narrowing is active in the current buffer, only export its
879 narrowed part.
881 If a region is active, export that region.
883 When optional argument SUBTREEP is non-nil, export the sub-tree
884 at point, extracting information from the headline properties
885 first.
887 When optional argument VISIBLE-ONLY is non-nil, don't export
888 contents of hidden elements.
890 Open file with the TaskJuggler GUI."
891 (interactive)
892 (let* ((file (org-taskjuggler-export nil subtreep visible-only))
893 (process-name "TaskJugglerUI")
894 (command (concat process-name " " file)))
895 (start-process-shell-command process-name nil command)))
898 (provide 'ox-taskjuggler)
900 ;; Local variables:
901 ;; sentence-end-double-space: t
902 ;; End:
904 ;;; ox-taskjuggler.el ends here