Added Elisp code, updated README
This commit is contained in:
Phuntsok Drak-pa
parent
9eccaba263
commit
a1a7799523
115
README.org
115
README.org
@ -1,11 +1,27 @@
|
||||
[[file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
|
||||
|
||||
* Features Tree
|
||||
* Table of content :TOC_5_gh:noexport:
|
||||
- [[#tree-to-dot][Tree to dot]]
|
||||
- [[#presentation][Presentation]]
|
||||
- [[#usage][Usage]]
|
||||
- [[#tldr][TL;DR]]
|
||||
- [[#elisp][Elisp]]
|
||||
- [[#scheme][Scheme]]
|
||||
- [[#more-details][More details]]
|
||||
- [[#elisp-1][Elisp]]
|
||||
- [[#scheme-1][Scheme]]
|
||||
- [[#my-elements-are-not-alignedcentered-what-do][My elements are not aligned/centered, what do?]]
|
||||
- [[#how-can-i-do-that-on-windows][How can I do that on Windows?]]
|
||||
- [[#scheme-2][Scheme]]
|
||||
- [[#elisp-2][Elisp]]
|
||||
- [[#license][License]]
|
||||
|
||||
* Tree to dot
|
||||
|
||||
** Presentation
|
||||
|
||||
*Features Tree* is a small utility for linguists and especially conlangers
|
||||
that allows them to declare trees with any number of children per node. I
|
||||
*Tree to dot* is a small utility for linguists and especially conlangers that
|
||||
allows them to declare trees with any number of children per node. I
|
||||
especially made it with the option in mind to make feature contrastive trees
|
||||
as presentented by Joseph Windsor in his talk during the /Language Creation
|
||||
Conference 8/, with examples below.
|
||||
@ -18,8 +34,16 @@
|
||||
|
||||
*** TL;DR
|
||||
|
||||
In your *NIX terminal, clone the project, edit the example trees or create a
|
||||
new one, and execute this:
|
||||
**** Elisp
|
||||
|
||||
Load this source code within Emacs, either in a ~emacs-lisp-mode~ buffer or
|
||||
in a source block in your ~org-mode~ buffer. Create trees, pass them as
|
||||
arguments to ~tree-to-dot~, execute, and voilà.
|
||||
|
||||
**** Scheme
|
||||
|
||||
In your *NIX terminal, clone the project, edit the example trees or create
|
||||
a new one, and execute this:
|
||||
#+BEGIN_SRC sh
|
||||
cd features-tree
|
||||
chicken-csc features-tree.scm # Compile the .scm file
|
||||
@ -29,6 +53,49 @@
|
||||
|
||||
*** More details
|
||||
|
||||
**** Elisp
|
||||
|
||||
The Elisp code was written with the intent of being used from org-mode in
|
||||
order to create inline images out of code. Put that source code in a code
|
||||
block in org-mode, and declare it as a noweb block.
|
||||
#+BEGIN_SRC org
|
||||
,#+NAME: process-tree
|
||||
,#+BEGIN_SRC emacs-lisp :exports none :noweb yes
|
||||
Code here!
|
||||
,#+END_SRC
|
||||
#+END_SRC
|
||||
Don’t forget to name your source blocks, it will be important for the noweb
|
||||
part later.
|
||||
|
||||
Then, you can declare later a beautiful tree in another code block, like
|
||||
so, and call your ~tree-to-dot~ function on it:
|
||||
#+BEGIN_SRC org
|
||||
,#+NAME: my-tree
|
||||
,#+BEGIN_SRC emacs-lisp :noweb yes :exports none
|
||||
(defvar mytree
|
||||
'("Tree"
|
||||
("First child"
|
||||
("First child’s child"))
|
||||
("Second child"
|
||||
("Second child’s first child")
|
||||
("Second child’s second child"))))
|
||||
,#+END_SRC
|
||||
#+END_SRC
|
||||
|
||||
You can now finally create one last code block in order to get your image:
|
||||
#+BEGIN_SRC org
|
||||
,#+BEGIN_SRC dot :file whatever.png :var input=my-tree :exports results
|
||||
$input
|
||||
,#+END_SRC
|
||||
#+END_SRC
|
||||
You can now export this last code block only to get your image. It will be
|
||||
automatically evaluated when you export your org buffer, but you can also
|
||||
manually trigger the evaluation by typing ~C-c C-c~ with your cursor on
|
||||
this last code block. Be sure to have enabled the dot language in babel and
|
||||
to have configured it properly ([[https://www.orgmode.org/worg/org-contrib/babel/languages/ob-doc-dot.html][this]] might help).
|
||||
|
||||
**** Scheme
|
||||
|
||||
For now, the workflow is not the best, as you have to edit yourself the
|
||||
source code and re-compile it each time you edit your own tree.
|
||||
|
||||
@ -37,10 +104,10 @@
|
||||
#+BEGIN_SRC scheme
|
||||
("text" (child1) (child2) ...)
|
||||
#+END_SRC
|
||||
Each child is itself a tree that should follow the same type of declaration,
|
||||
with as many child as you like per node –I discourage you to have more than
|
||||
nine children though, otherwise it might break the output. If a node does
|
||||
not have any child, it should be declared like so:
|
||||
Each child is itself a tree that should follow the same type of
|
||||
declaration, with as many child as you like per node –I discourage you to
|
||||
have more than nine children though, otherwise it might break the output.
|
||||
If a node does not have any child, it should be declared like so:
|
||||
#+BEGIN_SRC scheme
|
||||
("text")
|
||||
#+END_SRC
|
||||
@ -90,19 +157,18 @@
|
||||
|
||||
Once you’ve declared the tree you want to get, modify the last line of the
|
||||
source code =(tree-to-dot ...)= by replacing the default argument with the
|
||||
name of your tree. For the first example, we would call
|
||||
=(tree-to-dot vowels)=, while for the second we would call
|
||||
=(tree-to-dot syntax-tree)=.
|
||||
name of your tree. For the first example, we would call =(tree-to-dot
|
||||
vowels)=, while for the second we would call =(tree-to-dot syntax-tree)=.
|
||||
|
||||
*Only one =(tree-to-dot)= call can be done at once, else what follows might
|
||||
break!*
|
||||
|
||||
Once you’ve done that, compile your file! I personally use [[https://call-cc.org/][Chicken]] as my
|
||||
Scheme compiler, but if you already have another, you can use your own. Just
|
||||
replace my calls to =chicken-csc= by your own compiler’s command. Also, be
|
||||
aware that I use =chicken-csc= as the command for che Chicken compiler, but
|
||||
if you also use Chicken, you might have to call =csc= instead (this might
|
||||
mean you have an older version than the one I use).
|
||||
Scheme compiler, but if you already have another, you can use your own.
|
||||
Just replace my calls to =chicken-csc= by your own compiler’s command.
|
||||
Also, be aware that I use =chicken-csc= as the command for che Chicken
|
||||
compiler, but if you also use Chicken, you might have to call =csc= instead
|
||||
(this might mean you have an older version than the one I use).
|
||||
|
||||
Now that you’ve compiled your file, you will have to execute it. If your
|
||||
edits were alright, you should have some text output that looks like this,
|
||||
@ -160,10 +226,10 @@
|
||||
#+END_SRC
|
||||
If you get some errors, then you fucked up somewhere in your tree, probably
|
||||
missing some parenthesis or you forgot to add the ='= before the first
|
||||
parenthesis after the name of your tree. Go back to your source file and fix
|
||||
that. Also, it might be easier to edit the file if you have a decent text
|
||||
editor, I’d recommend using something along the lines of VS Code, Atom or
|
||||
Brackets, or even Emacs if you are not afraid by steep –but extremely
|
||||
parenthesis after the name of your tree. Go back to your source file and
|
||||
fix that. Also, it might be easier to edit the file if you have a decent
|
||||
text editor, I’d recommend using something along the lines of VS Code, Atom
|
||||
or Brackets, or even Emacs if you are not afraid by steep –but extremely
|
||||
rewarding– learning curves.
|
||||
|
||||
Now, you need to have [[https://graphviz.org/][Graphviz]]’s dot tool installed to generate images. In
|
||||
@ -184,11 +250,18 @@
|
||||
|
||||
*** How can I do that on Windows?
|
||||
|
||||
**** Scheme
|
||||
|
||||
IDK. Get a UNIX terminal (like the Linux subsystem, Putty(?) or Cygwin) and
|
||||
apply what has been said before, maybe. If you have a better explanation,
|
||||
you are more than welcome to either send it with a new issue or a pull
|
||||
request.
|
||||
|
||||
**** Elisp
|
||||
|
||||
This should work properly with Emacs on Windows, provided you’ve configured
|
||||
properly org-babel. I haven’t tested it though.
|
||||
|
||||
* License
|
||||
|
||||
Check out the [[file:LICENSE.org]]. TL;DR: a GPLv3 licence gives you the right to
|
||||
|
||||
50
tree-to-dot.el
Normal file
50
tree-to-dot.el
Normal file
@ -0,0 +1,50 @@
|
||||
(defun declare-node (node-text node-generation)
|
||||
"Declares a node in the graphviz source code. The node’s identifier will be
|
||||
~node-generation~, and it will bear the label ~node-text~."
|
||||
(concat (number-to-string node-generation)
|
||||
"[label=\""
|
||||
node-text
|
||||
"\"];"))
|
||||
|
||||
(defun make-link (previous-node current-node)
|
||||
"This creates a link in the graphviz source code between the two nodes
|
||||
bearing ~previous-node~ and ~current-node~ respectively as their node
|
||||
identifier."
|
||||
(concat (number-to-string previous-node) " -- "
|
||||
(number-to-string current-node) ";"))
|
||||
|
||||
(defun tree-to-dot-helper (tree current-generation previous-generation)
|
||||
"Helper to ~tree-to-dot~ that translates an Elisp tree with any number of
|
||||
children per node to a corresponding graphviz file that can be executed from
|
||||
dot.
|
||||
Arguments:
|
||||
- tree :: tree-to-convert
|
||||
- current-generation :: Generation number, incremented when changing from a node
|
||||
to another node from the same generation, multiplied by 10 when going from
|
||||
a node to one of its children.
|
||||
- previous-generation :: generation number from previous named node"
|
||||
(cond
|
||||
((null tree) "")
|
||||
((atom (car tree)) ;; '("text" () () ())
|
||||
(concat (declare-node (car tree) current-generation)
|
||||
(make-link previous-generation current-generation)
|
||||
(tree-to-dot-helper (cdr tree)
|
||||
(+ 1 (* 10 current-generation))
|
||||
current-generation)))
|
||||
((listp (car tree)) ;; '(() () ())
|
||||
(concat (tree-to-dot-helper (car tree) ;; child of current node
|
||||
current-generation
|
||||
previous-generation)
|
||||
(tree-to-dot-helper (cdr tree)
|
||||
(+ 1 current-generation)
|
||||
previous-generation)))))
|
||||
|
||||
(defun tree-to-dot (tree)
|
||||
"Returns a graphviz’s dot compatible string representing an Elisp tree"
|
||||
(interactive)
|
||||
(if (null tree) ""
|
||||
(concat
|
||||
"graph{node[shape=plaintext];graph[bgcolor=\"transparent\"];"
|
||||
(declare-node (car tree) 0)
|
||||
(tree-to-dot-helper (cdr tree) 1 0)
|
||||
"}")))
|
||||
Reference in New Issue
Block a user