Skip to content
This repository was archived by the owner on Aug 31, 2021. It is now read-only.

Commit a2b5f3f

Browse files
livecodealilivecodeali
committed
[[ Java FFI DSL ]] Add docs for java dsl parser
1 parent 87b6aaf commit a2b5f3f

File tree

3 files changed

+264
-0
lines changed

3 files changed

+264
-0
lines changed

‎docs/notes/feature-java_dsl_parser.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# LiveCode Builder Tools
2+
## java-dsl-parse
3+
4+
* **java-dsl-parse** is a tool to create LiveCode Builder code which
5+
provides an interface between LCB modules and the Java Native
6+
Interface (JNI). It does this by taking a specification of a java
7+
package written in a domain-specific language and creating an LCB
8+
module which wraps the necessary foreign handlers which call the
9+
appropriate JNI methods. See the [documentation for the tool](https://github.com/livecode/livecode/blob/develop/toolchain/java-dsl-parse.1.md)
10+
and the [description of the DSL](https://github.com/livecode/livecode/tree/develop/docs/specs/java-ffi-dsl.md)
11+
for more details
12+

‎docs/specs/java-ffi-dsl.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Java FFI DSL Syntax
2+
The Java FFI DSL is used to describe the classes and interfaces of a
3+
java package, and their constructors, methods, variables and constants.
4+
5+
All java class definitions should have a unique representation in the
6+
DSL (indeed in many cases it will be very similar)
7+
8+
## DSL syntax
9+
### Package definition
10+
A package consists of a declaration of the Name, a ModuleName which is
11+
used for the LiveCode Builder output module, and a collection of class
12+
and interface definitions, and use clauses.
13+
14+
Package
15+
: "foreign" "package" <Name: QualifiedName> "named" <ModuleName: STRING> SEPARATOR
16+
{ Definition SEPARATOR }
17+
"end" "package"
18+
19+
A definition is either a class or an interface definition, or a use clause.
20+
21+
Definition
22+
: Use
23+
| Interface
24+
| Class
25+
26+
### Use clauses
27+
A use clause specifies which other java classes and interfaces are used
28+
within this package.
29+
30+
Use
31+
: "use" <PackageName: QualifiedName> "." <ClassName: STRING>
32+
33+
### Class and interface definitions
34+
Class and interface definitions contain lists of the constants,
35+
variables, methods and constructors that are members of the class or
36+
interface. They also specify how the class or interface fits in to the
37+
java Object hierarchy.
38+
39+
Interface
40+
: "interface" <Interface: ClassType> ["inherits" <Parents: InterfaceList>] SEPARATOR
41+
{ InterfaceDef SEPARATOR }
42+
"end" "interface"
43+
44+
Class
45+
: [ <Modifiers: ClassModifiers> ] "class" <Class: ClassType> ["inherits" <Parent: ClassType>] ["implements" <List: InterfaceList>] SEPARATOR
46+
{ ClassDef SEPARATOR }
47+
"end" "class"
48+
49+
Interfaces can only define methods and constants.
50+
51+
InterfaceDef
52+
: [ <Modifiers: InterfaceMethodModifier> ] "method" <Name: STRING> <ParamList: Parameters> ["named" <Alias: STRING>] ["throws" <List: ClassList>] "returns" <ReturnType: Type>
53+
| "constant" <Name: STRING> "as" <VarType: Type> ["is" <Exp: Expression>]
54+
55+
Classes can also define constructors and variables.
56+
57+
ClassDef
58+
: [ <Modifiers: MethodModifiers> ] "method" <Name: STRING> <ParamList: Parameters> ["named" <Alias: STRING>] ["throws" <List: ClassList>] "returns" <ReturnType: Type>
59+
| [ <Modifiers: ConstructiorModifiers> ] "constructor" <Name: STRING> ["named" <Alias: STRING>]
60+
| [ <Modifiers: VariableModifiers> ] "variable" <Name: STRING> "as" <VarType: Type>
61+
| "constant" <Name: STRING> "as" <VarType: Type> ["is" <Exp: Expression>]
62+
63+
### Implements / inherits
64+
Classes and interfaces can only implement/inherit other classes or
65+
interfaces of the appropriate type.
66+
67+
The only difference between ClassList and InterfaceList is that it is a
68+
parse error if the items in InterfaceList are not defined as interfaces.
69+
70+
InterfaceList
71+
: <Head: ClassTypeInstance> [ "," <Tail: InterfaceList> ]
72+
73+
ClassList
74+
: <Head: ClassTypeInstance> [ "," <Tail: ClassList> ]
75+
76+
### Modifiers
77+
Modifiers give extra information about how or in what context classes or
78+
their members can be used. For example, if the "class" instance modifier
79+
is applied to a method of a class, an instance of the class is not
80+
required in order to call that method (i.e. `static`, in java parlance).
81+
82+
The majority of the modifier information is not currently used, but
83+
should be provided anyway so that better glue code can be generated in
84+
the future.
85+
86+
ClassModifiers
87+
: [ <Access: AccessModifier> ] [ <StrictFP: StrictFPModifier> ] [ <Inheritance: InheritanceModifier> ] [ <Modify: ModifyModifier> ] [ <Instance: InstanceModifier> ]
88+
89+
MethodModifiers
90+
: [ <Access: AccessModifier> ] [ <Sync: SyncModifier> ] [ <Native: NativeModifier> ] [ <StrictFP: StrictFPModifier> ] [ <Inheritance: InheritanceModifier> ] [ <Instance: InstanceModifier> ]
91+
92+
ConstructorModifiers
93+
: [ <Access: AccessModifier> ]
94+
95+
VariableModifiers
96+
: [ <Access: AccessModifier> ] [ <Transient: TransientModifier> ] [ <Modify: ModifyModifier> ] [ <Instance: InstanceModifier> ]
97+
98+
InterfaceMethodModifier
99+
: "default"
100+
| "class"
101+
102+
AccessModifier
103+
: "public"
104+
| "protected"
105+
106+
SyncModifier
107+
: "synchronized"
108+
109+
NativeModifier
110+
: "native"
111+
112+
StrictFPModifier
113+
: "strictfp"
114+
115+
InheritanceModifier
116+
: "abstract"
117+
: "final"
118+
119+
InstanceModifier
120+
: "class"
121+
122+
ModifyModifier
123+
: "final"
124+
| "volatile"
125+
126+
TransientModifier
127+
: "transient"
128+
129+
130+
### Parameters
131+
Note: all java method parameters are `in` parameters from the LCB point
132+
of view.
133+
134+
Parameters
135+
: "(" [ <Head: Parameter> [ "," <Tail: Parameters> ] ")"
136+
| "..."
137+
138+
Parameter
139+
: <Name: STRING> "as" <ParamType: Type>
140+
141+
### Types
142+
Types in Java are either primitive, derived from the Object class, or
143+
arrays of either of those.
144+
145+
Type
146+
: "byte"
147+
| "short"
148+
| "int"
149+
| "long"
150+
| "float"
151+
| "double"
152+
| "boolean"
153+
| "char"
154+
| "String"
155+
| Type "[" "]"
156+
| ClassType
157+
158+
ClassType
159+
: <Name: STRING> ["<" <Params: ClassTypeParamList> ">" ]
160+
161+
ClassTypeParamList
162+
: <Head: ClassTypeParam> [ "," <Tail: ClassTypeParamList> ]
163+
164+
ClassTypeParam
165+
: ClassType
166+
| <Placeholder: STRING>
167+
| "?" [ <WildcardBounds: Bounds> ]
168+
169+
Bounds
170+
: "extends" <Parent: ClassTypeInstance>
171+
| "super" <Child: ClassTypeInstance>
172+
173+
## Examples
174+
### The java.lang.Object class
175+
The [java.lang.Object](https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html)
176+
class can be described in the DSL as follows:
177+
178+
class Object
179+
constructor Object()
180+
181+
final method getClass() returns Class<?>
182+
method hashCode() returns int
183+
method equals(obj as Object) returns boolean
184+
protected method clone() returns Object
185+
method toString() returns String
186+
final method notify() returns nothing
187+
final method notifyAll() returns nothing
188+
final method wait(timeout as long) named waitTimeout returns nothing
189+
final method wait(timeout as long, nanos as int) named waitNanos returns nothing
190+
final method wait() returns nothing
191+
protected method finalize() returns nothing
192+
end class
193+
194+
### The java.lang.reflect.TypeVariable class
195+
The [java.lang.reflect.TypeVariable](https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/TypeVariable.html)
196+
class can be translated into the DSL as follows:
197+
198+
interface TypeVariable<D> inherits Type
199+
method getBounds() returns Type[]
200+
method getGenericDeclaration() returns D
201+
method getName() returns String
202+
end interface
203+
204+
### The android.os.BatteryManager class
205+
The charging/discharging functionality of the [android.os.BatteryManager](https://developer.android.com/reference/android/os/BatteryManager.html)
206+
class can be translated as follows:
207+
208+
class BatteryManager
209+
constant ACTION_CHARGING as String is "android.os.action.CHARGING"
210+
constant ACTION_DISCHARGING as String is "android.os.action.DISCHARGING"
211+
method isCharging() returns boolean
212+
end class

‎toolchain/java-dsl-parse.1.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
java-dsl-parse(1) -- convert java package spec files into lcb code
2+
===================================================
3+
4+
## SYNOPSIS
5+
6+
**java-dsl-parse** [_OPTION_ ...] [--] _DSLFILE_...
7+
8+
## DESCRIPTION
9+
10+
**java-dsl-parse** parses a specification of a java package into an
11+
abstract form, and outputs as specified.
12+
13+
## OPTIONS
14+
15+
* --output _LCBFILE_:
16+
Output an LiveCode Builder source file containing a usable interface
17+
between LiveCode Builder and the Java Native Interface. Compiling and
18+
loading _LCBFILE_ using **lc-compile** allows the functionality
19+
described by the _DSLFILE_ to be used by LCB modules.
20+
21+
* --check _CHECKFILE_:
22+
Output the parsed data to _CHECKFILE_. This is used for checking
23+
consistency of output - the result of running **java-dsl-parse** on
24+
_CHECKFILE_ should be identical to _CHECKFILE_.
25+
26+
* -h, --help: Print some basic usage information.
27+
28+
* --: Stop processing options. This is useful in case _DSLFILE_ begins with `-`
29+
or `--`.
30+
31+
## COPYRIGHT
32+
33+
Copyright 2016 LiveCode Ltd.
34+
35+
This is free software; see the source for copying conditions. There is NO
36+
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
37+
38+
## SEE ALSO
39+
40+
**lc-compile**(1).

0 commit comments

Comments
 (0)