source: project/release/4/javahack/doc.scm @ 14825

Last change on this file since 14825 was 14825, checked in by felix winkelmann, 11 years ago

java-ref accepts string or symbol

File size: 7.7 KB
Line 
1(use eggdoc)
2
3(define license
4"The javahack extension is distributed under the modified
5BSD license and Copyright (c) 2006 Felix L. Winkelmann
6
7JScheme is
8Copyright (c) 2002 Ken R. Anderson, Timothy J. Hickey, Peter Norvig
9
10This software is provided 'as-is', without any express or
11implied warranty.
12
13In no event will the authors be held liable for any damages
14arising from the use of this software.
15
16Permission is granted to anyone to use this software for any
17purpose, including commercial applications, and to alter it
18and redistribute it freely, subject to the following
19restrictions:
20
211. The origin of this software must not be misrepresented; you
22   must not claim that you wrote the original software. If you
23   use this software in a product, an acknowledgment in the
24   product documentation would be appreciated but is not
25   required.
26
272. Altered source versions must be plainly marked as such, and
28   must not be misrepresented as being the original software.
29
303. This notice may not be removed or altered from any source
31   distribution.")
32
33(define email "mailto:felix@call-with-current-continuation.org")
34
35(define doc
36  `((eggdoc:begin
37     (name "javahack")
38     (description (p "A simple interface to Java(tm)"))
39     
40     (author (url ,email "felix"))
41
42     (history
43      (version "0.3" "Initial release"))
44
45     (usage)
46     (download "javahack.egg")
47
48     (documentation
49      (p "This library provides a simple and convenient interface to Java. By running java "
50         "as a sub-process and reading/writing s-expressions, no JNI and OS-specific hacks are needed "
51         "which makes this approach more portable and robust.")
52      (p "On the Java side " (a (@ (href "http://jscheme.sourceforge.net")) "jscheme") " is used to "
53         "parse expressions passed from CHICKEN and to convert results back into a Scheme-friendly format.")
54      (p "(" (tt "jscheme.jar") " version 6.1 is included in this egg)")
55
56      (group
57       (macro "(java SYMBOL)"
58         (p "Returns the value represented by " (tt "SYMBOL") " which should designate a Java class, field, "
59            "or method, using `Java Dot' notation:")
60         (table
61          (tr (td "Syntax") (td "Type of Member") (td "Example"))
62          (tr (td "\".\" at the end") (td "constructor") (td (code "((java Font.) NAME STYLE SIZE)")))
63          (tr (td "\".\" at the beginning") (td "instance member") (td (code "((java .setFont) COMP FONT)")))
64          (tr (td "\".\" at beginning and \"$\" at the end") (td "instance field") 
65              (td (code "(define (mycar x) ((java .first$) x))") (br) (code "(define (myset-car! x y) ((java .first$) x y))")) )
66          (tr (td "\".\" only in the middle") (td "static member") (td (code "((java Math.round) 123.456)")))
67          (tr (td "\".class\" suffix") (td "Java class") (td (code "(java Font.class)")))
68          (tr (td "\"$\" at the end") (td "static field") (td (code "(java Font.BOLD$)") (br) (code "(set! (java \"U.useJavaSyntax$\") #t)")))
69          (tr (td "\"$\" in the middle") (td "inner class") (td (code "(java java.awt.geom.Point2D$Double.class)")))
70          (tr (td "\"$\" at the beginning") (td "packageless class") (td (code "(java $ParseDemo.class)")))
71          (tr (td "\"#\" at the end")(td "allow private access")(td (code "((java .name$#) ((java Symbol.#) \"abc\"))"))) )
72         (p "Notes:")
73         (ul (li (p "Each evaluation of the " (tt "java") " macro sends an expression to the java process and receives a result expression."
74                 " Since most of the results will stay constant throughout the lifetime of the session (as they refer to classes, fields"
75                 " and methods), they are cached and"
76                 " subsequent evaluation of the same " (tt "(java ...)") " expression will refer to the cached value instead."
77                 " You can disable this caching (in case you are doing rather funky things) with the help of the "
78                 (tt "java-enable-cache") " form (see below).") )
79             (li (p "Java objects which are returned from the Java-side can be safely used and are only garbage collected when"
80                    " no more references exist.") ) ) )
81       (macro "(java-enable-cache FLAG)"
82         (p "Enables or disables caching of results returned by the " (tt "java") " macro. " (tt "FLAG") " should be either"
83            " the symbol " (tt "on") " or " (tt "off") ". Caching is enabled by default.") ) )
84
85      (group
86       (procedure "(java-run #!key java jar debug options classpath)"
87                  (p "Starts the java-VM as a subprocess, with any additional arguments customizing the JVM invocation."
88                     " " (tt "java") " specifies the jvm executable and defaults to " (tt "java") ". " (tt "jar") 
89                     " gives the location of the jscheme jar file, " (tt "options") " and " (tt "classpath") " can"
90                     " be used to customize where the JVM should search for support classes and libraries, together"
91                     " with JVM specific options.")
92                  (p "Passing " (tt "#t") " for the " (tt "debug") " parameter will print information about the"
93                     " message flow between CHICKEN and jscheme.") )
94       (procedure "(java-stop)"
95                  (p "Terminates the java process.") )
96       (procedure "(java-send EXPR)"
97                  (p "Send an expression to Java and returns whatever result is passed back.") )
98       (procedure "(java-import STRING ...)"
99                  (p "Imports Java packages. " (tt "STRING") " should be a qualified package identifier, like "
100                     (tt "\"java.lang.*\"") ".") )
101       (procedure "(java-ref NAME)"
102                  (p "References or sets a static field. Setting static fields is supported through a " (a (@ (href "http://srfi.schemers.org/srfi-17/srfi-17.html")) "SRFI-17")
103                     " setter, as in the example above. Since the field-name is evaluated before being sent to the java-process,"
104                     " pass the field as a string.") )
105       (procedure "(java-object? X)"
106                  (p "Returns " (tt "#t") " if " (tt "X") " is a raw Java object (that can not be meaningfully converted"
107                     " into a Scheme value).") ) ))
108     
109      (examples
110       (pre #<<EOF
111(use javahack)
112
113(java-run debug: #t)
114
115(define s (java String.class))
116(pp s)
117(define s1 ((java String.) "hello!"))
118(pp s1)
119(do ((n 2 (sub1 n))) ((zero? n))
120  (pp ((java .hashCode) s1)) )
121(set! s #f)
122(set! s1 #f)
123EOF
124)     
125       "Another example, a minimal SWT application. It assumes " (tt "swt.jar") " and all"
126       " necessary native libraries are in the path, or in the current directory:"
127       (pre #<<EOF
128(use javahack)
129
130(java-run debug: #t options: '("-Djava.library.path=.") classpath: "swt.jar")
131
132(java-import "org.eclipse.swt.*")
133(java-import "org.eclipse.swt.widgets.*")
134(java-import "org.eclipse.swt.graphics.*")
135(java-import "org.eclipse.swt.layout.*")
136
137((java Display.setAppName) "Hello")
138
139(define disp ((java Display.)))
140(define shell ((java Shell.) disp))
141
142((java .setLayout) shell ((java FillLayout.) (java SWT.VERTICAL$)))
143((java .setText) shell "Hello, world!")
144
145(define label ((java Label.) shell (java SWT.CENTER$)))
146
147((java .setText) label "Hello, world")
148((java .setSize) shell 300 300)
149((java .open) shell)
150
151(do () (((java .isDisposed) shell))
152  (unless ((java .readAndDispatch) disp) ((java .sleep) disp)) )
153
154((java .dispose) disp)
155EOF
156     )
157     "Yet another example that performs a callback. The Java code performing the callback could"
158     " look like this:"
159     (pre #<<EOF
160public class Callback
161{
162    public static Object invoke(jsint.Procedure proc, Object x) {
163        return proc.apply(new jsint.Pair(x, jsint.Pair.EMPTY));
164    }
165}
166EOF
167     )
168     "If you compile it with " (tt "javac -classpath `chicken-setup -repository`/jscheme.jar Callback.java")
169     " you will have a classfile in the current directory that in combination with the following example"
170     " code will call back to the CHICKEN side:"
171     (pre #<<EOF
172(use javahack)
173
174(java-run debug: #t classpath: ".")
175
176(write
177  ((java Callback.invoke)
178    (lambda (x) 
179      (print "ok: " x) 
180      42) 
181    "something") )
182EOF
183     ) ) )
184     (section "License" (pre ,license)) ) )
185
186(eggdoc->html doc)
187
Note: See TracBrowser for help on using the repository browser.