source: project/release/4/pyffi/trunk/pyffi-eggdoc.scm @ 14475

Last change on this file since 14475 was 14475, checked in by Ivan Raikov, 11 years ago

pyffi ported to Chicken 4

File size: 7.1 KB
Line 
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
172EOF
173))
174     (license
175      "Copyright 2007-2009 Ivan Raikov. Based on pyffi.lisp by Dmitri Hrapof.
176
177This program is free software: you can redistribute it and/or modify
178it under the terms of the GNU General Public License as published by
179the Free Software Foundation, either version 3 of the License, or (at
180your option) any later version.
181
182This program is distributed in the hope that it will be useful, but
183WITHOUT ANY WARRANTY; without even the implied warranty of
184MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
185General Public License for more details.
186
187A full copy of the GPL license can be found at
188<http://www.gnu.org/licenses/>."))))
189
190(if (eggdoc->html doc) (void))
Note: See TracBrowser for help on using the repository browser.