1 | |
---|
2 | (use eggdoc) |
---|
3 | |
---|
4 | (define doc |
---|
5 | `((eggdoc:begin |
---|
6 | (name "pyffi") |
---|
7 | |
---|
8 | (description "An interface to the Python programming language.") |
---|
9 | |
---|
10 | (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov")) |
---|
11 | |
---|
12 | (history |
---|
13 | (version "2.11" "Ported to Chicken 4") |
---|
14 | (version "2.10" "Fixes in utf8 support") |
---|
15 | (version "2.9" "Added support for automatic conversion of Python class instances to Scheme alists") |
---|
16 | (version "2.8" "Bug fixes in Python FFI function declarations") |
---|
17 | (version "2.7" "Bug fixes in the Python unicode string conversion routine") |
---|
18 | (version "2.6" "define-pyslot updated to support modifying attributes") |
---|
19 | (version "2.5" "Added definitions for Py_IncRef and Py_DecRef when using Python 2.3") |
---|
20 | (version "2.4" "Fixed a bug in the wrapper of PyRun_String") |
---|
21 | (version "2.3" "Added support for the boolean type") |
---|
22 | (version "2.2" "Some fixes to ensure compatibility with Python 2.3 and 2.5") |
---|
23 | (version "2.1" "Build script updated for better cross-platform compatibility") |
---|
24 | (version "2.0" "Change to use utf8 extension") |
---|
25 | (version "1.1" "Metafile fix") |
---|
26 | (version "1.0" "Initial release")) |
---|
27 | |
---|
28 | (requires (url "utf8.html" "utf8") |
---|
29 | (url "easyffi.html" "easyffi")) |
---|
30 | |
---|
31 | (usage "(require-extension pyffi)") |
---|
32 | |
---|
33 | (download "pyffi.egg") |
---|
34 | |
---|
35 | (documentation |
---|
36 | |
---|
37 | (p "The " (tt "pyffi") " extension uses the " |
---|
38 | (url "http://www.python.org" "Python") " C interface " |
---|
39 | " to invoke Python procedures and methods from within Scheme " |
---|
40 | " and to convert data objects between their Python and Scheme " |
---|
41 | "representation. ") |
---|
42 | |
---|
43 | (p "Currently, " (tt "pyffi") " supports the Python data " |
---|
44 | "types listed in the table below. All other Python data types " |
---|
45 | "are represented as pointers. ") |
---|
46 | |
---|
47 | (symbol-table |
---|
48 | (describe "int, float" |
---|
49 | ("numeric types, converted to and from the corresponding Scheme numeric values.")) |
---|
50 | |
---|
51 | (describe "list" |
---|
52 | ("list type, converted to and from Scheme list value")) |
---|
53 | |
---|
54 | (describe "str" |
---|
55 | ("string type, converted to and from Scheme string value")) |
---|
56 | |
---|
57 | (describe "unicode" |
---|
58 | ("Unicode string type, converted to and from Scheme " (url "utf8.html" "utf8") " string")) |
---|
59 | |
---|
60 | (describe "dict" |
---|
61 | ("dictionary type, converted to and from Scheme alist value")) |
---|
62 | |
---|
63 | (describe "instance" |
---|
64 | ("class instance type, converted to Scheme alist value")) |
---|
65 | |
---|
66 | (describe "tuple" |
---|
67 | ("tuple type, converted to and from Scheme vector value"))) |
---|
68 | |
---|
69 | (subsection "Procedures" |
---|
70 | |
---|
71 | (procedure "(py-start)" |
---|
72 | (p "Initializes the Python interpreter, and creates an evaluation environment. " |
---|
73 | "This procedure must be called before all other procedures in the extension. ")) |
---|
74 | |
---|
75 | (procedure "(py-stop)" |
---|
76 | (p "Deallocates the memory reserved by the Python interpreter, and frees all " |
---|
77 | "internal structures of the extension. ")) |
---|
78 | |
---|
79 | (procedure "(py-import name)" |
---|
80 | (p "Imports Python module " (tt "NAME") ". If the import was unsuccessful, " |
---|
81 | "raises an exception of type " (tt "'pyerror") ". ")) |
---|
82 | |
---|
83 | |
---|
84 | (procedure "(py-eval expr)" |
---|
85 | (p "Evaluates the Python expression contained in the string " (tt "EXPR") |
---|
86 | " and returns the resulting value, either converted to Scheme " |
---|
87 | "representation, or as a pointer to a Python value. ")) |
---|
88 | |
---|
89 | (procedure "(py-apply func arg1 ...)" |
---|
90 | (p "Applies the given arguments to the Python object " (tt "FUNC") |
---|
91 | " and returns the resulting value, either converted to Scheme " |
---|
92 | "representation, or as a pointer to a Python value. " |
---|
93 | "The arguments must be either Scheme values of types listed " |
---|
94 | "in the type conversion table above, or pointers to Python values."))) |
---|
95 | |
---|
96 | (subsection "Macros" |
---|
97 | |
---|
98 | (macro "(define-pyfun expr arg1 ...)" |
---|
99 | (p "Defines a Scheme procedure named when called, " |
---|
100 | "invokes the Python procedure of the same name. " |
---|
101 | (tt "EXPR") " is either a string that contains the procedure name, " |
---|
102 | "or a pair of the form " (tt "(FORM . NAME)") " where " (tt "FORM") |
---|
103 | " is a Python expression that when evaluated returns a Python procedure, " |
---|
104 | "and " (tt "NAME") " is a string that contains the name of the Scheme procedure. " |
---|
105 | "The arguments must be all symbols. ")) |
---|
106 | |
---|
107 | (macro "(define-pyslot NAME [SCHEME-NAME])" |
---|
108 | (p "Defines an accessor/modifier for the Python object attribute " (tt "NAME") ". " |
---|
109 | "The optional argument " (tt "SCHEME-NAME") " is an alternate name for the " |
---|
110 | "Scheme procedure. The returned procedure takes in a Python object " |
---|
111 | "and returns the value of attribute " (tt "NAME") " contained in that object. " |
---|
112 | "If the object has no such attribute, #f is returned. " |
---|
113 | "If a value is supplied after the name of the object, the procedure acts as a modifier for that slot. " |
---|
114 | )) |
---|
115 | |
---|
116 | (macro "(define-pymethod NAME [SCHEME-NAME])" |
---|
117 | (p "Defines an accessor for the Python method " (tt "NAME") ". " |
---|
118 | "The optional argument " (tt "SCHEME-NAME") " is an alternate name for the " |
---|
119 | "Scheme procedure. The accessor is a procedure of the form " |
---|
120 | (tt "LAMBDA OBJ ARG1 ...") " that takes in a Python object " (tt "OBJ") |
---|
121 | " and invokes the method " (tt "NAME") " contained in that object, " |
---|
122 | "with the supplied arguments, which must be either Scheme values of types " |
---|
123 | "listed in the type conversion table above, or pointers to Python values. " |
---|
124 | "If the object has no such method, #f is returned. ")))) |
---|
125 | |
---|
126 | |
---|
127 | |
---|
128 | (examples (pre #<<EOF |
---|
129 | ;; |
---|
130 | ;; Python-UNO example from pyffi.lisp by Dmitri Hrapof. |
---|
131 | ;; |
---|
132 | ;; Before running the following code, you must make sure OpenOffice is |
---|
133 | ;; running as a server: |
---|
134 | ;; |
---|
135 | ;; soffice "-accept=socket,host=localhost,port=2002;urp;" |
---|
136 | ;; |
---|
137 | (require-extension pyffi) |
---|
138 | |
---|
139 | (py-start) |
---|
140 | |
---|
141 | (py-import "uno") |
---|
142 | |
---|
143 | (define-pyfun "uno.getComponentContext") |
---|
144 | |
---|
145 | (define-pyslot "ServiceManager") |
---|
146 | (define-pyslot "Text") |
---|
147 | |
---|
148 | ;; Can't yet find out appropriate class, the following is lame |
---|
149 | (define-pymethod "createInstanceWithContext") |
---|
150 | (define-pymethod "resolve") |
---|
151 | (define-pymethod "getCurrentComponent") |
---|
152 | (define-pymethod "createTextCursor") |
---|
153 | (define-pymethod "insertString") |
---|
154 | |
---|
155 | (define (message-uno str) |
---|
156 | (let* ((lc (uno.getcomponentcontext)) |
---|
157 | (resolver (createInstanceWithContext |
---|
158 | (ServiceManager lc) |
---|
159 | "com.sun.star.bridge.UnoUrlResolver" lc)) |
---|
160 | (ctx (resolve resolver "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext")) |
---|
161 | (desktop (CreateInstanceWithContext |
---|
162 | (ServiceManager ctx) |
---|
163 | "com.sun.star.frame.Desktop" ctx)) |
---|
164 | (model (getCurrentComponent desktop)) |
---|
165 | (text (text model)) |
---|
166 | (cursor (createTextCursor text))) |
---|
167 | (insertString text cursor str 0))) |
---|
168 | |
---|
169 | |
---|
170 | (message-uno "Hello, world!") |
---|
171 | |
---|
172 | EOF |
---|
173 | )) |
---|
174 | (license |
---|
175 | "Copyright 2007-2009 Ivan Raikov. Based on pyffi.lisp by Dmitri Hrapof. |
---|
176 | |
---|
177 | This program is free software: you can redistribute it and/or modify |
---|
178 | it under the terms of the GNU General Public License as published by |
---|
179 | the Free Software Foundation, either version 3 of the License, or (at |
---|
180 | your option) any later version. |
---|
181 | |
---|
182 | This program is distributed in the hope that it will be useful, but |
---|
183 | WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
184 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
185 | General Public License for more details. |
---|
186 | |
---|
187 | A full copy of the GPL license can be found at |
---|
188 | <http://www.gnu.org/licenses/>.")))) |
---|
189 | |
---|
190 | (if (eggdoc->html doc) (void)) |
---|