Skip to content

Latest commit

 

History

History
287 lines (207 loc) · 5.65 KB

README.md

File metadata and controls

287 lines (207 loc) · 5.65 KB
Raw

puml.el — Emacs Lisp DSL for PlantUML

Author: Thorsten Jolitz Version: 0.9 URL: https://github.com/tj64/puml

MetaData

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

Commentary

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).

Usage

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===

--> (*)

Known bugs and limitations

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..*