From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thorsten Jolitz Subject: [ANN] puml.el --- Emacs Lisp DSL for PlantUML Date: Mon, 14 Jul 2014 01:42:14 +0200 Message-ID: <878unwygfd.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:58489) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X6TSE-0000xu-H1 for emacs-orgmode@gnu.org; Sun, 13 Jul 2014 19:45:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X6TS9-0000ZJ-BL for emacs-orgmode@gnu.org; Sun, 13 Jul 2014 19:45:14 -0400 Received: from plane.gmane.org ([80.91.229.3]:53362) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X6TS9-0000Z2-1S for emacs-orgmode@gnu.org; Sun, 13 Jul 2014 19:45:09 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1X6TS4-0004Cj-1w for emacs-orgmode@gnu.org; Mon, 14 Jul 2014 01:45:04 +0200 Received: from g231105079.adsl.alicedsl.de ([92.231.105.79]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 14 Jul 2014 01:45:04 +0200 Received: from tjolitz by g231105079.adsl.alicedsl.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 14 Jul 2014 01:45:04 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org [This was posted on the Emacs Help mailing list too] Hi List, here is the comment section from new library puml.el which lets you create PlantUML scripts from Emacs Lisp by calling functions with arguments (instead of inserting hard-coded strings). The core functionality is all there, but I could not implement all PlantUML syntax elements yet, its easy but rather tedious due to their number. ACTIVITY DIAGRAMS are fully implemented, most likely USE CASE DIAGRAMS and CLASS DIAGRAMS will follow in the near future. I thought I announce it anyway, because when creating UML reports from Emacs Lisp programs it might be better to first expand puml.el with a few API functions and then use the library instead of working on the string level. So patches are welcome. ___________________ PUML Thorsten Jolitz tjolitz@gmail.com ___________________ Table of Contents _________________ 1 puml.el --- Emacs Lisp DSL for PlantUML .. 1.1 MetaData .. 1.2 Commentary .. 1.3 Usage .. 1.4 Known bugs and limitations 1 puml.el --- Emacs Lisp DSL for PlantUML ========================================= Author: Thorsten Jolitz Version: 0.9 URL: [https://github.com/tj64/puml] 1.1 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 1.2 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). 1.3 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=== | | --> (*) `---- 1.4 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..* `---- Emacs 24.3.1 (Org mode beta_8.3) -- cheers, Thorsten