Changes between Version 9 and Version 10 of JavaFfi

Timestamp:

11/25/10 22:46:42 (13 years ago)

Author:

astalla

Comment:

--

JavaFfi

@@ -78 +78 @@
 (jstatic "getRuntime" (jclass "java.lang.Runtime")) => #<java.lang.Runtime java.lang.Runtime@1ef3212 {C8E4DE}>
 (jstatic (jmethod "java.lang.Runtime" "getRuntime") nil) => #<java.lang.Runtime java.lang.Runtime@1ef3212 {129DF8A}>
+}}}
+
+=== Function JFIELD, JFIELD-RAW, (SETF JFIELD) ===
+
+'''Syntax:'''
+
+'''jfield''' ''class-ref-or-field field-or-instance &optional instance value => object''
+
+'''jfield-raw''' ''class-ref-or-field field-or-instance &optional instance value => JAVA-OBJECT''
+
+(setf ('''jfield''' ''class-ref-or-field field-or-instance &optional (instance nil instance-supplied-p) unused-value'') ''newvalue'')
+
+'''Arguments and Values:'''
+
+`class-ref-or-field` -- depending on the usage pattern, a Java class designator or a string naming a field in a Java object.
+
+`field-or-instance` -- depending on the usage pattern, a Java object or a string naming a field in a Java object.
+
+`instance` -- a Java object.
+
+`value` -- an object; the new value of the field.
+
+`unused-value` -- ignored, present only to make `(setf jfield)` accept the same parameter patterns as `jfield`.
+
+'''Description:'''
+
+`jfield` is a complex operator supporting several usage patterns for reading the value of a Java field. For historical reasons, `jfield` can also be used to set the value of a field, but the more idiomatic form `(setf jfield)` should be preferred. These are the possible usages of `jfield`:
+
+For reading values:
+ 1. `(jfield `''class-ref field''`)`: Retrieves the value of the static field `field` from class `class-ref`.
+ 2. `(jfield `''field instance''`)`: Retrieves the value of the field `field` from the Java object `instance`. The class to which the field belongs is taken to be the class of `instance`.
+ 3. `(jfield `''class-ref field instance''`)`: Retrieves the value of the field `field` of the class `class-ref` from the Java object `instance`.
+
+For storing values:
+ 4. `(jfield `''class-ref field primitive-value''`)`: Stores `primitive-value` as the value of the static field `field` of class `class-ref`.
+ 5. `(jfield `''field instance value''`)`: Stores `value` as the value of the field `field` in the Java object `instance`. The class to which the field belongs is taken to be the class of `instance`.
+ 6. `(jfield `''class-ref field instance value''`)`: Stores `value` as the value of the field `field` of the class `class-ref` in the Java object `instance`.
+ 7. `(jfield `''class-ref field''` NIL `''value''`)`: Stores `value` as the value of the static field `field` of class `class-ref`, when `value` could be confused with an instance (case 3).
+
+`(setf jfield)` can be used with patterns 1, 2 and 3 to store a value where `jfield` would have read it from.
+
+`jfield` translates the value of the field to a Lisp object when possible. `jfield-raw` performs no such translation.
+
+'''Examples:'''
+
+{{{
+(jfield "java.lang.System" "out") => #<java.io.PrintStream java.io.PrintStream@198a1f4 {1B0D990}>
+(jfield "width" (jnew "java.awt.Dimension")) => 0
+
+(let ((d (jnew "java.awt.Dimension")))
+  (setf (jfield "width" d) 42)
+  (jcall "toString" d))
+
+=> "java.awt.Dimension[width=42,height=0]"
 }}}