emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Thorsten Jolitz <tjolitz@gmail.com>
To: emacs-orgmode@gnu.org
Subject: [ANN] puml.el --- Emacs Lisp DSL for PlantUML
Date: Mon, 14 Jul 2014 01:42:14 +0200	[thread overview]
Message-ID: <878unwygfd.fsf@gmail.com> (raw)

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



			    Thorsten Jolitz

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 <tjolitz AT gmail DOT com>
  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

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

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

                 reply	other threads:[~2014-07-13 23:45 UTC|newest]

Thread overview: [no followups] expand[flat|nested]  mbox.gz  Atom feed

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=878unwygfd.fsf@gmail.com \
    --to=tjolitz@gmail.com \
    --cc=emacs-orgmode@gnu.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).