-
Notifications
You must be signed in to change notification settings - Fork 104
/
myclass.api
179 lines (149 loc) · 7.04 KB
/
myclass.api
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
<class name = "myclass">
<!--
This model defines a public API for binding.
It shows a language binding developer what to expect from the API XML
files.
-->
My Feature-Rich Class
<include filename = "license.xml" />
<constant name = "default port" value = "8080">registered with IANA</constant>
<constant name = "normal" value = "1" />
<constant name = "fast" value = "2" />
<constant name = "safe" value = "3" />
<!-- Constructor is optional; default one has no arguments -->
<constructor>
Create a new myclass with the given name.
<argument name = "name" type = "string" />
</constructor>
<!-- Destructor is optional; default one follows standard style -->
<destructor>
Destructors implicitly get a new argument prepended, which:
* is called `self_p`
* is of this class' type
* is passed by reference
* is marked as the self pointer for the destructor (`destructor_self = "1"`)
</destructor>
<!-- This models an CZMQ actor. By default the actor method equals the
class name.
-->
<actor>
To work with my_actor, use the CZMQ zactor API:
Create new my_actor instance.
zactor_t *actor = zactor_new (my_actor, NULL);
Destroy my_actor instance
zactor_destroy (&actor);
Enable verbose logging of commands and activity:
zstr_send (actor, "VERBOSE");
</actor>
<!-- This models a method with no return value -->
<method name = "sleep">
Put the myclass to sleep for the given number of milliseconds.
No messages will be processed by it during this time.
<argument name = "duration" type = "integer" />
</method>
<!-- This models an accessor method -->
<method name = "has feature">
Return true if the myclass has the given feature.
<argument name = "feature" type = "string" />
<return type = "boolean" />
</method>
<method name = "send strings">
This does something with a series of strings (until NULL). The strings
won't be touched.
Because the next method has the same name with a prepended "v", it's
recognized as this method's `va_list` sibling (in GSL:
`method.has_va_list_sibling = "1"`). This information might be used by
the various language bindings.
<argument name = "string" type = "string" variadic = "1" />
<return type = "boolean" />
</method>
<method name = "vsend strings">
This does something with a series of strings (until NULL). The strings
won't be touched (they're declared immutable by default).
<argument name = "string" type = "string" variadic = "1" />
<return type = "boolean" />
</method>
<!-- Callback typedefs can be declared like methods -->
<callback_type name = "handler_fn">
<argument name = "self" type = "myclass" />
<argument name = "action" type = "string" />
<return type = "boolean" />
</callback_type>
<!-- Callback types can be used as method arguments -->
<method name = "add handler">
Store the given callback function for later
<argument name = "handler" type = "my_class_handler_fn" callback = "1" />
</method>
<!-- If singleton = "1", no class struct pointer is required. -->
<method name = "test" singleton = "1">
Self test of this class
<argument name = "verbose" type = "boolean" />
</method>
<method name = "new thing" singleton = "1" >
Creates a new myclass. The caller is responsible for destroying it when
finished with it.
<return type = "myclass" fresh = "1" />
</method>
<method name = "free" singleton = "1">
Frees a provided string, and nullify the parent pointer. Setting
`mutable = "1"` is not needed here, because transfering ownership from
the caller to the function using `by_reference = "1"` implies that it's
mutable.
<argument name = "string pointer" type = "string" by_reference = "1" />
</method>
<method name = "rotate" singleton = "1">
Rotates the characters in `data` in-place. This means that all
characters are shifted to the left by one, removing the left-most
character and appending it to the end.
<argument name = "data" type = "string" mutable = "1" />
</method>
<!-- These are the types we support
Not all of these are supported in all language bindings;
see each language binding's file for supported types in that
language, and add more types as needed where appropriate.
Also, see zproject_class_api.gsl to see how they're handled exactly.
-->
<method name = "tutorial">
<argument name = "void pointer" type = "anything" />
<argument name = "standard int" type = "integer" />
<argument name = "default float" type = "real" />
<argument name = "standard float" type = "real" size = "4" />
<argument name = "standard double" type = "real" size = "8" />
<argument name = "standard bool" type = "boolean" />
<argument name = "fixed size unsigned integer" type = "number" size = "4">
Supported sizes are 1, 2, 4, and 8.
</argument>
<argument name = "a byte" type = "byte" />
<argument name = "conversion mode" type = "integer" />
<argument name = "char pointer to C string" type = "string" />
<argument name = "byte pointer to buffer" type = "buffer" />
<argument name = "buffer size" type = "size" />
<argument name = "file handle" type = "FILE" />
<argument name = "file size" type = "file_size" />
<argument name = "time" type = "time" />
<argument name = "format" type = "format">
This makes the function is variadic (will cause a new argument to be
added to represent the variadic arguments).
</argument>
<argument name = "variadic list argument" type = "va_list" />
<argument name = "custom pointer" type = "my custom class">
Any other type is valid, as long as there is a corresponding C
type, in this case `my_custom_class_t`.
</argument>
<return type = "nothing">void method</return>
</method>
<method name = "set foo" polymorphic = "1">
Set attribute foo to a new value. Note that this method takes a
polymorphic reference (`void *`) as its first argument, which could point
to structs of different types.
This also means that high-level bindings might give you the choice to
call this method directly on an instance, or with an explicit receiver.
<argument name = "new value" type="integer" />
</method>
<method name = "set bar">
This method takes an argument type of the (descriptive) type `foo`, but
resolving it to a corresponding C type will be skipped because it's
overridden to `foobarbaz_t` by the `c_type` attribute.
<argument name = "new foo" type="foo" c_type="foobarbaz_t" />
</method>
</class>