emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [ANN] puml.el --- Emacs Lisp DSL for PlantUML
@ 2014-07-13 23:42 Thorsten Jolitz
  0 siblings, 0 replies; only message in thread
From: Thorsten Jolitz @ 2014-07-13 23:42 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2014-07-13 23:45 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-07-13 23:42 [ANN] puml.el --- Emacs Lisp DSL for PlantUML Thorsten Jolitz

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