mirror of https://github.com/texmacs/doc.git
pyminimal example of a plug-in with Python code
This commit is contained in:
Darcy Shen
parent
71538d873a
commit
22e2d4e5f5
|
|
@ -8,6 +8,8 @@
|
|||
<section|Changes from version 1.99.1 to 2.1>
|
||||
|
||||
<\itemize>
|
||||
<item>Documentation on how to write plugins using Python (2.1).
|
||||
|
||||
<item><scm|(run-all-tests)> aggregates and runs all the tests in <scheme>
|
||||
(2.1).
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,190 @@
|
|||
<TeXmacs|1.99.11>
|
||||
|
||||
<style|<tuple|tmdoc|english|old-spacing>>
|
||||
|
||||
<\body>
|
||||
<tmdoc-title|Example of a plug-in with Python code>
|
||||
|
||||
<paragraph*|The <verbatim|pyminimal> plug-in>
|
||||
|
||||
Consider the example of the <verbatim|pyminimal> plug-in in the directory
|
||||
|
||||
<\verbatim>
|
||||
\ \ \ \ $TEXMACS_PATH/examples/plugins
|
||||
</verbatim>
|
||||
|
||||
It consists of the following files:
|
||||
|
||||
<\verbatim>
|
||||
\ \ \ \ <example-plugin-link|pyminimal/progs/init-pyminimal.scm>
|
||||
|
||||
\ \ \ \ <example-plugin-link|pyminimal/src/minimal.py>
|
||||
</verbatim>
|
||||
|
||||
In order to try the plug-in, you first have to recursively copy the
|
||||
directory
|
||||
|
||||
<\verbatim>
|
||||
\ \ \ \ $TEXMACS_PATH/examples/plugins/pyminimal
|
||||
</verbatim>
|
||||
|
||||
to <verbatim|$TEXMACS_PATH/progs> or <verbatim|$TEXMACS_HOME_PATH/progs>.
|
||||
|
||||
When relaunching <TeXmacs>, the plug-in should now be automatically
|
||||
recognized.
|
||||
|
||||
<paragraph*|How it works: The Scheme Part>
|
||||
|
||||
The <verbatim|pyminimal> plug-in demonstrates a minimal interface between
|
||||
<TeXmacs> and an extern program in python. The initialization file
|
||||
<verbatim|init-pyminimal.scm> essentially contains the following code:
|
||||
|
||||
<\scm-code>
|
||||
(define (python-launcher)
|
||||
|
||||
\ \ (if (url-exists? "$TEXMACS_HOME_PATH/plugins/pyminimal")
|
||||
|
||||
\ \ \ \ \ \ (string-append "python \\""
|
||||
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (getenv "TEXMACS_HOME_PATH")
|
||||
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "/plugins/pyminimal/src/minimal.py\\"")
|
||||
|
||||
\ \ \ \ \ \ (string-append "python \\""
|
||||
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (getenv "TEXMACS_PATH")
|
||||
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "/plugins/pyminimal/src/minimal.py\\"")))
|
||||
|
||||
\;
|
||||
|
||||
(plugin-configure pyminimal
|
||||
|
||||
\ \ (:require (url-exists-in-path? "python"))
|
||||
|
||||
\ \ (:launch ,(python-launcher))
|
||||
|
||||
\ \ (:session "PyMinimal"))
|
||||
</scm-code>
|
||||
|
||||
The <scm|:require> option checks whether <shell|python> indeed exists in
|
||||
the path (so this will fail if you did not have python installed). The
|
||||
<scm|:launch> option specifies how to launch the extern program. The
|
||||
<verbatim|:session> option indicates that it will be possible to create
|
||||
sessions for the <verbatim|pyminimal> plug-in using
|
||||
<menu|Insert|Session|PyMinimal>.
|
||||
|
||||
The <scm|python-launcher> function will be evaluated and return the proper
|
||||
command to launcher the extern program. If
|
||||
<shell|$TEXMACS_HOME_PATH/plugins/pyminimal> exists, it would be
|
||||
|
||||
<\shell-code>
|
||||
python "$TEXMACS_HOME_PATH/plugins/pyminimal/src/minimal.py"
|
||||
</shell-code>
|
||||
|
||||
otherwise,
|
||||
|
||||
<\shell-code>
|
||||
python "$TEXMACS_PATH/plugins/pyminimal/src/minimal.py"
|
||||
</shell-code>
|
||||
|
||||
The environment variables will be replaced in runtime. Sometimes,
|
||||
<shell|$TEXMACS_HOME_PATH> and <shell|$TEXMACS_PATH> may contain spaces, as
|
||||
a result, we quote the path using the double quotes.
|
||||
|
||||
<paragraph|How it works: The Python Part>
|
||||
|
||||
Using the Python interpreter, we do not need to compile the code. And most
|
||||
of the time, python code can be interpreted without any modification under
|
||||
multiple platforms. The built-in python libraries are really helpful and
|
||||
handy.
|
||||
|
||||
Many <TeXmacs> built-in plugins are written in Python, and we have
|
||||
carefully organized the code and reused the common part named <name|tmpy>.
|
||||
|
||||
<\python-code>
|
||||
import os
|
||||
|
||||
import sys
|
||||
|
||||
from os.path import exists
|
||||
|
||||
tmpy_home_path = os.environ.get("TEXMACS_HOME_PATH") + "/plugins/tmpy"
|
||||
|
||||
if (exists (tmpy_home_path)):
|
||||
|
||||
\ \ \ \ sys.path.append(os.environ.get("TEXMACS_HOME_PATH") +
|
||||
"/plugins/")
|
||||
|
||||
else:
|
||||
|
||||
\ \ \ \ sys.path.append(os.environ.get("TEXMACS_PATH") + "/plugins/")
|
||||
</python-code>
|
||||
|
||||
The first part of the code just add <shell|$TEXMACS_HOME_PATH/plugins> or
|
||||
<shell|$TEXMACS_PATH/plugins> to the python path for importing the
|
||||
<name|tmpy> package.
|
||||
|
||||
<\python-code>
|
||||
from tmpy.protocol \ \ \ \ \ \ \ import *
|
||||
|
||||
from tmpy.compat \ \ \ \ \ \ \ \ \ import *
|
||||
|
||||
\;
|
||||
|
||||
flush_verbatim ("Hi there!")
|
||||
|
||||
\;
|
||||
|
||||
while True:
|
||||
|
||||
\ \ \ \ line = tm_input()
|
||||
|
||||
\ \ \ \ if not line:
|
||||
|
||||
\ \ \ \ \ \ \ \ pass
|
||||
|
||||
\ \ \ \ else:
|
||||
|
||||
\ \ \ \ \ \ \ \ flush_verbatim ("You typed " + line)
|
||||
</python-code>
|
||||
|
||||
<python|flush_verbatim> is provided by <python|tmpy.protocol> which is a
|
||||
subpackage for interaction with <TeXmacs> server in Python.
|
||||
|
||||
<python|tm_input> is provided by <python|tmpy.compat> which is a subpackage
|
||||
for compatibility within Python 2 and 3. For built-in plugins written in
|
||||
Python, it would be better to support more Python version. For example, in
|
||||
some desktop environments, the <shell|python> command may redirect to
|
||||
<shell|python2.6>.
|
||||
|
||||
<paragraph|Comparison with <c++>>
|
||||
|
||||
This demo plugin is a Python implementation of the well-documented
|
||||
<hlink|minimal plugin|plugin-binary.en.tm> written in <c++>. Here is the
|
||||
summary of the differences:
|
||||
|
||||
<\itemize>
|
||||
<item><verbatim|pyminimal> requires the <name|Python> interpreter,
|
||||
<verbatim|minimal> needs to be compiled and linked
|
||||
|
||||
<item><verbatim|pyminimal> is easier to install than <verbatim|minimal>
|
||||
|
||||
<item><verbatim|pyminimal> reuses the common part related to <TeXmacs>
|
||||
|
||||
<item><verbatim|pyminimal> has better compatibility for <name|Linux>,
|
||||
<name|Windows> and <name|macOS>
|
||||
</itemize>
|
||||
|
||||
<tmdoc-copyright|2019|Darcy Shen>
|
||||
|
||||
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
|
||||
document under the terms of the GNU Free Documentation License, Version 1.1
|
||||
or any later version published by the Free Software Foundation; with no
|
||||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
||||
Texts. A copy of the license is included in the section entitled "GNU Free
|
||||
Documentation License".>
|
||||
</body>
|
||||
|
||||
<initial|<\collection>
|
||||
</collection>>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
<TeXmacs|1.0.7.14>
|
||||
<TeXmacs|1.99.11>
|
||||
|
||||
<style|tmdoc>
|
||||
<style|<tuple|tmdoc|english|old-spacing>>
|
||||
|
||||
<\body>
|
||||
<tmdoc-title|The <TeXmacs> plug-in system>
|
||||
|
|
@ -21,6 +21,8 @@
|
|||
|
||||
<branch|Example of a plug-in with <name|C++> code|plugin-binary.en.tm>
|
||||
|
||||
<branch|Example of a plug-in with Python code|plugin-python.en.tm>
|
||||
|
||||
<branch|Summary of the configuration options for
|
||||
plug-ins|plugin-config.en.tm>
|
||||
</traverse>
|
||||
|
|
@ -35,8 +37,5 @@
|
|||
Documentation License".>
|
||||
</body>
|
||||
|
||||
<\initial>
|
||||
<\collection>
|
||||
<associate|language|english>
|
||||
</collection>
|
||||
</initial>
|
||||
<initial|<\collection>
|
||||
</collection>>
|
||||
Loading…
Reference in New Issue