Author: Thorsten Jolitz Version: 0.9 URL: https://github.com/tj64/puml
copyright: Thorsten Jolitz copyright-years: 2014+ version: 0.9 licence: GPL 3 or later (free software) licence-url: http://www.gnu.org/licenses/ part-of-emacs: no author: Thorsten Jolitz author_email: tjolitz AT gmail DOT com keywords: emacs org-mode org-bandbook plantuml git-repo: https://github.com/tj64/puml git-clone: git://github.com/tj64/puml.git
Emacs-lisp domain-specific-language (DSL) for PlantUML.
This library is meant for creating PlantUML Scripts programmatically by calling Emacs Lisp functions with arguments (instead of inserting hardcoded strings from a program or directly writing PlantUML syntax).
Almost all the real work is done by function `puml–generic'. It assumes that most PlantUML syntax constructs can be expressed like this:
This function is then called by almost all the API functions that normally implement one PlantUML syntax element each. Here is the simple function for implementing stereotypes like '<< human >>':
(defun* puml-stereotype (code &key (ldelim "<<") (rdelim ">>") (crlf "\n") ins) "Return or insert PlantUML stereotype." (puml--generic :typ 'generic-nospaces :1st (puml-sym-or-strg ldelim) :2nd (puml-sym-or-strg code) :3rd (puml-sym-or-strg rdelim) :crlf crlf :ins ins))
A call to this function looks like this:
(puml-stereotype " human ")
<< human >>
Here is a little PlantUML script from the PlantUML Language Reference translated to puml.el:
(puml-pack (puml-start-activity :crlf nil) (puml-space (puml-sync-bar "B1") :lead 1) (puml-activity :nm "Parallel Activity 1") (puml-activity :crlf nil) (puml-space (puml-sync-bar "B2") :lead 1) (puml-newline) (puml-sync-bar "B1" :crlf nil) (puml-space (puml-activity :nm "Parallel Activity 2") :lead 1) (puml-activity :crlf nil) (puml-space (puml-sync-bar "B2") :lead 1) (puml-newline) (puml-end-activity))
(*) --> ===B1=== --> "Parallel Activity 1" --> ===B2=== ===B1=== --> "Parallel Activity 2" --> ===B2=== --> (*)
Currently this library only implements ACTIVITY DIAGRAMS. Patches are welcome to expand this library to all PlantUML diagram types.
The complete template for an API function that calls `puml–generic' looks like this:
(defun* puml-foo (&key typ fmt pre 1st 2nd 3rd as suf (crlf "\n") ins) "Return or insert PlantUML foo." (puml--generic :typ 'generic-nospaces :fmt generic-nospaces :pre pre :1st 1st :2nd 2nd :3rd 3rd :as as :suf suf :crlf crlf :ins ins))
Type 'generic' is the default :typ and need not be given. Both types 'generic' and 'generic-nospaces' have their associated format-strings, thus argument :fmt need not be given for them.
Argument :as stands for assignment like 'as B1'. Argument :ins stands for 'insert', if non-nil result is inserted at point instead of returned. In practice it is mostly used for the outermost call to `puml-pack' that wraps a PlantUML script:
(puml-pack (puml-key-val "foo" "bar") :ins t)
Besides `puml-pack', another very important and versatile function is `puml-arrow'. In can be used to create all kinds of arrow syntax used by PlantUML.
Here are two example:
(puml-arrow :dir "up" :lhead "<" :rhead nil :lextra "|")
(puml-arrow :shaft "." :lhead "1" :rhead "*")