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:
:pre | prefix |
:1st | 1st-part |
:2nd | 2nd-part |
:3rd | 3rd-part |
:as | as X |
:suf | suffix |
:crlf | crlf |
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))
puml-stereotype
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))
puml-foo
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.
arg | meaning | default |
---|---|---|
:len | length | 2 |
:dir | direction | |
:shaft | arrow shaft | "-" |
:lhead | leaft head | "" |
:rhead | right head | ">" |
:lextra | left extra | |
:rextra | right extra |
Here are two example:
(puml-arrow :dir "up" :lhead "<" :rhead nil :lextra "|")
<|-up-
(puml-arrow :shaft "." :lhead "1" :rhead "*")
1..*