sfml3-rb 0.2.2 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +9 -0
  3. data/CHANGELOG.md +67 -16
  4. data/README.md +123 -32
  5. data/TODO.md +18 -11
  6. data/ext/audio/audio_enums.c +58 -20
  7. data/ext/audio/listener.c +89 -6
  8. data/ext/audio/music.c +212 -5
  9. data/ext/audio/sound.c +218 -9
  10. data/ext/audio/sound_buffer.c +197 -47
  11. data/ext/audio/sound_buffer_recorder.c +90 -18
  12. data/ext/audio/sound_recorder.c +188 -58
  13. data/ext/audio/sound_source_cone.c +127 -33
  14. data/ext/audio/sound_stream.c +204 -21
  15. data/ext/core/exceptions.c +10 -8
  16. data/ext/core/unicode.c +12 -2
  17. data/ext/ext.c +8 -0
  18. data/ext/graphics/blend_mode.c +218 -60
  19. data/ext/graphics/circle.c +300 -16
  20. data/ext/graphics/color.c +253 -94
  21. data/ext/graphics/drawable.c +16 -4
  22. data/ext/graphics/font.c +144 -25
  23. data/ext/graphics/glyph.c +38 -8
  24. data/ext/graphics/image.c +205 -41
  25. data/ext/graphics/polygon.c +317 -30
  26. data/ext/graphics/rect.c +225 -60
  27. data/ext/graphics/rectangle.c +307 -35
  28. data/ext/graphics/render_state.c +124 -12
  29. data/ext/graphics/render_texture.c +191 -14
  30. data/ext/graphics/render_window.c +55 -0
  31. data/ext/graphics/render_window.h +10 -0
  32. data/ext/graphics/shader.c +289 -17
  33. data/ext/graphics/shape.c +265 -32
  34. data/ext/graphics/sprite.c +245 -30
  35. data/ext/graphics/stencil_mode.c +163 -46
  36. data/ext/graphics/target.c +121 -43
  37. data/ext/graphics/target.h +31 -17
  38. data/ext/graphics/text.c +339 -19
  39. data/ext/graphics/texture.c +291 -6
  40. data/ext/graphics/transform.c +178 -5
  41. data/ext/graphics/transformable.c +127 -12
  42. data/ext/graphics/vertex.c +98 -6
  43. data/ext/graphics/vertex_array.c +142 -21
  44. data/ext/graphics/vertex_buffer.c +154 -12
  45. data/ext/graphics/view.c +140 -6
  46. data/ext/network/ftp.c +278 -12
  47. data/ext/network/http.c +179 -44
  48. data/ext/network/ip_address.c +127 -35
  49. data/ext/network/network_enums.c +248 -141
  50. data/ext/network/packet.c +280 -41
  51. data/ext/network/socket_selector.c +98 -21
  52. data/ext/network/tcp_listener.c +82 -18
  53. data/ext/network/tcp_socket.c +135 -27
  54. data/ext/network/udp_socket.c +129 -28
  55. data/ext/ports.rb +7 -0
  56. data/ext/system/buffer.c +47 -16
  57. data/ext/system/clock.c +77 -12
  58. data/ext/system/input_stream.c +113 -51
  59. data/ext/system/sleep.c +10 -2
  60. data/ext/system/time.c +182 -40
  61. data/ext/system/vec2.c +166 -39
  62. data/ext/system/vec3.c +177 -39
  63. data/ext/window/clipboard.c +47 -17
  64. data/ext/window/context.c +66 -13
  65. data/ext/window/context_settings.c +132 -42
  66. data/ext/window/cursor.c +45 -9
  67. data/ext/window/event.c +164 -53
  68. data/ext/window/joystick.c +69 -3
  69. data/ext/window/keyboard.c +168 -116
  70. data/ext/window/mouse.c +64 -13
  71. data/ext/window/sensor.c +28 -2
  72. data/ext/window/touch.c +32 -12
  73. data/ext/window/video_mode.c +93 -31
  74. data/ext/window/vulkan.c +34 -6
  75. data/ext/window/window.c +228 -229
  76. data/ext/window/window.h +4 -4
  77. data/ext/window/window_base.c +251 -0
  78. data/ext/window/window_base.h +43 -0
  79. data/ext/window/window_base.inc +236 -0
  80. data/lib/sfml/version.rb +1 -1
  81. data/sig/audio/audio_enums.rbs +30 -0
  82. data/sig/audio/listener.rbs +16 -0
  83. data/sig/audio/music.rbs +56 -0
  84. data/sig/audio/sound.rbs +51 -0
  85. data/sig/audio/sound_buffer.rbs +17 -0
  86. data/sig/audio/sound_buffer_recorder.rbs +14 -0
  87. data/sig/audio/sound_recorder.rbs +17 -0
  88. data/sig/audio/sound_source_cone.rbs +14 -0
  89. data/sig/audio/sound_stream.rbs +51 -0
  90. data/sig/graphics/blend_mode.rbs +29 -0
  91. data/sig/graphics/circle.rbs +44 -0
  92. data/sig/graphics/color.rbs +39 -0
  93. data/sig/graphics/drawable.rbs +5 -0
  94. data/sig/graphics/font.rbs +20 -0
  95. data/sig/graphics/glyph.rbs +7 -0
  96. data/sig/graphics/image.rbs +22 -0
  97. data/sig/graphics/polygon.rbs +42 -0
  98. data/sig/graphics/rect.rbs +33 -0
  99. data/sig/graphics/rectangle.rbs +42 -0
  100. data/sig/graphics/render_state.rbs +21 -0
  101. data/sig/graphics/render_target.rbs +18 -0
  102. data/sig/graphics/render_texture.rbs +39 -0
  103. data/sig/graphics/render_window.rbs +7 -0
  104. data/sig/graphics/shader.rbs +39 -0
  105. data/sig/graphics/shape.rbs +38 -0
  106. data/sig/graphics/sprite.rbs +34 -0
  107. data/sig/graphics/stencil_mode.rbs +18 -0
  108. data/sig/graphics/target.rbs +8 -0
  109. data/sig/graphics/text.rbs +48 -0
  110. data/sig/graphics/texture.rbs +34 -0
  111. data/sig/graphics/transform.rbs +37 -0
  112. data/sig/graphics/transformable.rbs +25 -0
  113. data/sig/graphics/vertex.rbs +17 -0
  114. data/sig/graphics/vertex_array.rbs +17 -0
  115. data/sig/graphics/vertex_buffer.rbs +22 -0
  116. data/sig/graphics/view.rbs +23 -0
  117. data/sig/network/ftp.rbs +46 -0
  118. data/sig/network/http.rbs +27 -0
  119. data/sig/network/ip_address.rbs +22 -0
  120. data/sig/network/network_enums.rbs +95 -0
  121. data/sig/network/packet.rbs +40 -0
  122. data/sig/network/socket_selector.rbs +14 -0
  123. data/sig/network/tcp_listener.rbs +13 -0
  124. data/sig/network/tcp_socket.rbs +18 -0
  125. data/sig/network/udp_socket.rbs +17 -0
  126. data/sig/sfml/version.rbs +3 -0
  127. data/sig/system/buffer.rbs +11 -0
  128. data/sig/system/clock.rbs +13 -0
  129. data/sig/system/input_stream.rbs +7 -0
  130. data/sig/system/sleep.rbs +3 -0
  131. data/sig/system/time.rbs +28 -0
  132. data/sig/system/vec2.rbs +26 -0
  133. data/sig/system/vec3.rbs +27 -0
  134. data/sig/window/clipboard.rbs +8 -0
  135. data/sig/window/context.rbs +11 -0
  136. data/sig/window/context_settings.rbs +20 -0
  137. data/sig/window/cursor.rbs +6 -0
  138. data/sig/window/event.rbs +20 -0
  139. data/sig/window/joystick.rbs +15 -0
  140. data/sig/window/keyboard.rbs +10 -0
  141. data/sig/window/mouse.rbs +9 -0
  142. data/sig/window/sensor.rbs +8 -0
  143. data/sig/window/touch.rbs +6 -0
  144. data/sig/window/video_mode.rbs +16 -0
  145. data/sig/window/vulkan.rbs +7 -0
  146. data/sig/window/window.rbs +34 -0
  147. data/sig/window/window_base.rbs +33 -0
  148. metadata +76 -3
data/ext/graphics/view.c CHANGED
@@ -42,36 +42,86 @@ static VALUE View_new_from(VALUE klass, sfView* c_view) {
42
42
  return self;
43
43
  }
44
44
 
45
- static VALUE View_new(VALUE klass) {
46
- return View_new_from(klass, NULL);
45
+ static VALUE View_alloc(VALUE klass) {
46
+ sfView* view = View_create();
47
+
48
+ if (view == NULL) {
49
+ rb_raise(rb_eRuntimeError, "failed to create view");
50
+ }
51
+
52
+ return TypedData_Wrap_Struct(klass, &View_data_type, view);
47
53
  }
48
54
 
49
55
  /* The rect is the visible area: position is the top-left corner, not the
50
56
  centre, which is what distinguishes this from new + center=/size=. */
57
+ /* call-seq:
58
+ * View.from_rect(rect) -> View
59
+ *
60
+ * Creates a view covering the given rectangle.
61
+ *
62
+ * @return [View] a view whose visible area is +rect+ (position is the
63
+ * top-left corner)
64
+ */
51
65
  static VALUE View_s_from_rect(VALUE klass, VALUE rb_rect) {
52
66
  return View_new_from(klass, sfView_createFromRect(rect_from_rb(rb_rect)));
53
67
  }
54
68
 
69
+ /* call-seq:
70
+ * View.new -> View
71
+ *
72
+ * Creates a default view covering the (0, 0) - (1000, 1000) region.
73
+ *
74
+ * @return [View]
75
+ */
55
76
  static VALUE View_init(VALUE self) {
56
77
  return self;
57
78
  }
58
79
 
80
+ /* call-seq:
81
+ * rotation=(value) -> self
82
+ *
83
+ * Sets the object's rotation, in degrees.
84
+ *
85
+ * @return [self]
86
+ */
59
87
  static VALUE View_set_rotation(VALUE self, VALUE rb_rotation) {
60
88
  sfView_setRotation(Get_View_Struct(self), NUM2DBL(rb_rotation));
61
89
  return self;
62
90
  }
63
91
 
92
+ /* call-seq:
93
+ * size=(value) -> self
94
+ *
95
+ * Sets the object's size.
96
+ *
97
+ * @return [self]
98
+ */
64
99
  static VALUE View_set_size(VALUE self, VALUE rb_scale) {
65
100
  sfView_setSize(Get_View_Struct(self), vec2f_from_rb(rb_scale));
66
101
  return self;
67
102
  }
68
103
 
104
+ /* call-seq:
105
+ * center=(value) -> self
106
+ *
107
+ * Sets the view's center.
108
+ *
109
+ * @return [self]
110
+ */
69
111
  static VALUE View_set_center(VALUE self, VALUE rb_origin) {
70
112
  sfVector2f origin = VEC2_RB2C(rb_origin);
71
113
  sfView_setCenter(Get_View_Struct(self), origin);
72
114
  return self;
73
115
  }
74
116
 
117
+ /* call-seq:
118
+ * viewport=(value) -> self
119
+ *
120
+ * Sets the viewport: the target-relative (0..1) rectangle this view is
121
+ * rendered into.
122
+ *
123
+ * @return [self]
124
+ */
75
125
  static VALUE View_set_viewport(VALUE self, VALUE rb_viewport) {
76
126
  sfFloatRect viewport = RECT_RB2C(rb_viewport);
77
127
  sfView_setViewport(Get_View_Struct(self), viewport);
@@ -79,57 +129,141 @@ static VALUE View_set_viewport(VALUE self, VALUE rb_viewport) {
79
129
  return self;
80
130
  }
81
131
 
132
+ /* call-seq: rotation -> Float
133
+ *
134
+ * Returns the object's rotation, in degrees.
135
+ *
136
+ * @return [Float] degrees
137
+ */
82
138
  static VALUE View_get_rotation(VALUE self) {
83
139
  return DBL2NUM(sfView_getRotation(Get_View_Struct(self)));
84
140
  }
85
141
 
142
+ /* call-seq: size -> Vector2
143
+ *
144
+ * Returns the object's size.
145
+ *
146
+ * @return [Vector2]
147
+ */
86
148
  static VALUE View_get_size(VALUE self) {
87
149
  return vec2f_to_rb(sfView_getSize(Get_View_Struct(self)));
88
150
  }
89
151
 
152
+ /* call-seq: center -> Vector2
153
+ *
154
+ * Returns the view's center.
155
+ *
156
+ * @return [Vector2]
157
+ */
90
158
  static VALUE View_get_center(VALUE self) {
91
159
  return vec2f_to_rb(sfView_getCenter(Get_View_Struct(self)));
92
160
  }
93
161
 
162
+ /* call-seq: viewport -> Rect
163
+ *
164
+ * Returns the target's viewport rectangle, or +nil+ if none is set.
165
+ *
166
+ * @return [Rect]
167
+ */
94
168
  static VALUE View_get_viewport(VALUE self) {
95
169
  return RECT_C2RB(sfView_getViewport(Get_View_Struct(self)));
96
170
  }
97
171
 
172
+ /* call-seq:
173
+ * scissor=(value) -> self
174
+ *
175
+ * Sets the target's scissor rectangle.
176
+ *
177
+ * @return [self]
178
+ */
98
179
  static VALUE View_set_scissor(VALUE self, VALUE rb_scissor) {
99
180
  sfView_setScissor(Get_View_Struct(self), RECT_RB2C(rb_scissor));
100
181
 
101
182
  return self;
102
183
  }
103
184
 
185
+ /* call-seq: scissor -> Rect
186
+ *
187
+ * Returns the target's scissor rectangle, or +nil+ if none is set.
188
+ *
189
+ * @return [Rect]
190
+ */
104
191
  static VALUE View_get_scissor(VALUE self) {
105
192
  return RECT_C2RB(sfView_getScissor(Get_View_Struct(self)));
106
193
  }
107
194
 
195
+ /* call-seq:
196
+ * move(offset) -> self
197
+ *
198
+ * Moves the object by +offset+.
199
+ *
200
+ * @return [self]
201
+ */
108
202
  static VALUE View_move(VALUE self, VALUE rb_move) {
109
203
  sfView_move(Get_View_Struct(self), vec2f_from_rb(rb_move));
110
204
  return self;
111
205
  }
112
206
 
207
+ /* call-seq:
208
+ * rotate(angle) -> self
209
+ *
210
+ * Rotates the object by +angle+ degrees.
211
+ *
212
+ * @return [self]
213
+ */
113
214
  static VALUE View_rotate(VALUE self, VALUE rb_angle) {
114
215
  sfView_rotate(Get_View_Struct(self), NUM2DBL(rb_angle));
115
216
 
116
217
  return self;
117
218
  }
118
219
 
220
+ /* call-seq:
221
+ * zoom(factor) -> self
222
+ *
223
+ * Multiplies the view's size by +factor+.
224
+ *
225
+ * @return [self]
226
+ */
119
227
  static VALUE View_zoom(VALUE self, VALUE rb_zoom) {
120
228
  sfView_zoom(Get_View_Struct(self), NUM2DBL(rb_zoom));
121
229
 
122
230
  return self;
123
231
  }
124
232
 
233
+ /* call-seq: copy -> View
234
+ *
235
+ * Returns a deep copy of the object.
236
+ *
237
+ * @return [View] an independent copy
238
+ */
125
239
  static VALUE View_copy(VALUE self) {
126
240
  return Get_Casting_View(sfView_copy(Get_View_Struct(self)));
127
241
  }
128
242
 
129
- void Init_View(VALUE rb_module) {
130
- rb_cView = rb_define_class_under(rb_module, "View", rb_cObject);
131
-
132
- rb_define_singleton_method(rb_cView, "new", View_new, 0);
243
+ /* Document-class: SFML::View
244
+ * A 2D camera: the region of the scene visible on a render target, and
245
+ * where on that target it is shown.
246
+ *
247
+ * @!attribute rotation
248
+ * The object's rotation, in degrees.
249
+ * @return [Float] degrees
250
+ * @!attribute size
251
+ * The object's size.
252
+ * @return [Vector2]
253
+ * @!attribute center
254
+ * The view's center.
255
+ * @return [Vector2]
256
+ * @!attribute viewport
257
+ * The view's viewport rectangle.
258
+ * @return [Rect] the target-relative (0..1) rectangle this view renders into
259
+ * @!attribute scissor
260
+ * The view's scissor rectangle.
261
+ * @return [Rect]
262
+ */
263
+ void Init_View(VALUE rb_mSFML) {
264
+ rb_cView = rb_define_class_under(rb_mSFML, "View", rb_cObject);
265
+
266
+ rb_define_alloc_func(rb_cView, View_alloc);
133
267
  rb_define_singleton_method(rb_cView, "from_rect", View_s_from_rect, 1);
134
268
 
135
269
  // methods
data/ext/network/ftp.c CHANGED
@@ -130,10 +130,48 @@ static VALUE FtpListingResponse_wrap(sfFtpListingResponse* handle) {
130
130
  return TypedData_Wrap_Struct(rb_cFtpListingResponse, &FtpListingResponse_data_type, ptr);
131
131
  }
132
132
 
133
- static VALUE Ftp_new(VALUE klass) {
133
+ static VALUE Ftp_alloc(VALUE klass) {
134
+ (void)klass;
134
135
  return Ftp_wrap(sfFtp_create());
135
136
  }
136
137
 
138
+ static VALUE FtpResponse_alloc(VALUE klass) {
139
+ (void)klass;
140
+ rb_raise(rb_eNotImpError, "FTP response objects are returned by Ftp methods and cannot be "
141
+ "constructed directly");
142
+ }
143
+
144
+ static VALUE FtpDirectoryResponse_alloc(VALUE klass) {
145
+ (void)klass;
146
+ rb_raise(rb_eNotImpError, "FTP response objects are returned by Ftp methods and cannot be "
147
+ "constructed directly");
148
+ }
149
+
150
+ static VALUE FtpListingResponse_alloc(VALUE klass) {
151
+ (void)klass;
152
+ rb_raise(rb_eNotImpError, "FTP response objects are returned by Ftp methods and cannot be "
153
+ "constructed directly");
154
+ }
155
+
156
+ /* call-seq:
157
+ * Ftp.new -> Ftp
158
+ *
159
+ * Creates a new FTP client.
160
+ *
161
+ * @return [Ftp]
162
+ */
163
+ static VALUE Ftp_initialize(VALUE self) {
164
+ return self;
165
+ }
166
+
167
+ /* call-seq:
168
+ * connect(address, port = 21, timeout = Time.zero) -> FtpResponse
169
+ *
170
+ * Connects to the specified FTP server. Blocks until connected or
171
+ * +timeout+ elapses.
172
+ *
173
+ * @return [FtpResponse]
174
+ */
137
175
  static VALUE Ftp_connect(int argc, VALUE* argv, VALUE self) {
138
176
  VALUE rb_address, rb_port, rb_timeout;
139
177
  sfTime timeout = sfTime_Zero;
@@ -153,27 +191,70 @@ static VALUE Ftp_connect(int argc, VALUE* argv, VALUE self) {
153
191
  Get_Ftp_Struct(self), ip_address_from_rb(rb_address, sfIpAddress_None), port, timeout));
154
192
  }
155
193
 
194
+ /* call-seq:
195
+ * login_anonymous -> FtpResponse
196
+ *
197
+ * Logs in using the standard "anonymous" account.
198
+ *
199
+ * @return [FtpResponse]
200
+ */
156
201
  static VALUE Ftp_login_anonymous(VALUE self) {
157
202
  return FtpResponse_wrap(sfFtp_loginAnonymous(Get_Ftp_Struct(self)));
158
203
  }
159
204
 
205
+ /* call-seq:
206
+ * login(name, password) -> FtpResponse
207
+ *
208
+ * Logs in with the given +name+ and +password+.
209
+ *
210
+ * @return [FtpResponse]
211
+ */
160
212
  static VALUE Ftp_login(VALUE self, VALUE rb_name, VALUE rb_password) {
161
213
  return FtpResponse_wrap(
162
214
  sfFtp_login(Get_Ftp_Struct(self), StringValueCStr(rb_name), StringValueCStr(rb_password)));
163
215
  }
164
216
 
217
+ /* call-seq:
218
+ * disconnect -> FtpResponse
219
+ *
220
+ * Closes the connection with the server.
221
+ *
222
+ * @return [FtpResponse]
223
+ */
165
224
  static VALUE Ftp_disconnect(VALUE self) {
166
225
  return FtpResponse_wrap(sfFtp_disconnect(Get_Ftp_Struct(self)));
167
226
  }
168
227
 
228
+ /* call-seq:
229
+ * keep_alive -> FtpResponse
230
+ *
231
+ * Sends a null command to keep the connection alive.
232
+ *
233
+ * @return [FtpResponse]
234
+ */
169
235
  static VALUE Ftp_keep_alive(VALUE self) {
170
236
  return FtpResponse_wrap(sfFtp_keepAlive(Get_Ftp_Struct(self)));
171
237
  }
172
238
 
239
+ /* call-seq:
240
+ * working_directory -> FtpDirectoryResponse
241
+ *
242
+ * Returns the current working directory on the server.
243
+ *
244
+ * @return [FtpDirectoryResponse] the current working directory on the server
245
+ */
173
246
  static VALUE Ftp_working_directory(VALUE self) {
174
247
  return FtpDirectoryResponse_wrap(sfFtp_getWorkingDirectory(Get_Ftp_Struct(self)));
175
248
  }
176
249
 
250
+ /* call-seq:
251
+ * directory_listing(directory = nil) -> FtpListingResponse
252
+ *
253
+ * Lists the contents of +directory+ (or the current working directory if
254
+ * omitted/nil).
255
+ *
256
+ * @return [FtpListingResponse]
257
+ */
177
258
  static VALUE Ftp_directory_listing(int argc, VALUE* argv, VALUE self) {
178
259
  VALUE rb_directory;
179
260
 
@@ -183,32 +264,82 @@ static VALUE Ftp_directory_listing(int argc, VALUE* argv, VALUE self) {
183
264
  Get_Ftp_Struct(self), NIL_P(rb_directory) ? NULL : StringValueCStr(rb_directory)));
184
265
  }
185
266
 
267
+ /* call-seq:
268
+ * change_directory(directory) -> FtpResponse
269
+ *
270
+ * Changes the current working directory on the server.
271
+ *
272
+ * @return [FtpResponse]
273
+ */
186
274
  static VALUE Ftp_change_directory(VALUE self, VALUE rb_directory) {
187
275
  return FtpResponse_wrap(
188
276
  sfFtp_changeDirectory(Get_Ftp_Struct(self), StringValueCStr(rb_directory)));
189
277
  }
190
278
 
279
+ /* call-seq:
280
+ * parent_directory -> FtpResponse
281
+ *
282
+ * Moves to the parent directory of the current working directory.
283
+ *
284
+ * @return [FtpResponse]
285
+ */
191
286
  static VALUE Ftp_parent_directory(VALUE self) {
192
287
  return FtpResponse_wrap(sfFtp_parentDirectory(Get_Ftp_Struct(self)));
193
288
  }
194
289
 
290
+ /* call-seq:
291
+ * create_directory(name) -> FtpResponse
292
+ *
293
+ * Creates a directory named +name+ on the server.
294
+ *
295
+ * @return [FtpResponse]
296
+ */
195
297
  static VALUE Ftp_create_directory(VALUE self, VALUE rb_name) {
196
298
  return FtpResponse_wrap(sfFtp_createDirectory(Get_Ftp_Struct(self), StringValueCStr(rb_name)));
197
299
  }
198
300
 
301
+ /* call-seq:
302
+ * delete_directory(name) -> FtpResponse
303
+ *
304
+ * Deletes the directory named +name+ on the server.
305
+ *
306
+ * @return [FtpResponse]
307
+ */
199
308
  static VALUE Ftp_delete_directory(VALUE self, VALUE rb_name) {
200
309
  return FtpResponse_wrap(sfFtp_deleteDirectory(Get_Ftp_Struct(self), StringValueCStr(rb_name)));
201
310
  }
202
311
 
312
+ /* call-seq:
313
+ * rename_file(file, new_name) -> FtpResponse
314
+ *
315
+ * Renames +file+ to +new_name+ on the server.
316
+ *
317
+ * @return [FtpResponse]
318
+ */
203
319
  static VALUE Ftp_rename_file(VALUE self, VALUE rb_file, VALUE rb_new_name) {
204
320
  return FtpResponse_wrap(sfFtp_renameFile(Get_Ftp_Struct(self), StringValueCStr(rb_file),
205
321
  StringValueCStr(rb_new_name)));
206
322
  }
207
323
 
324
+ /* call-seq:
325
+ * delete_file(name) -> FtpResponse
326
+ *
327
+ * Deletes the file named +name+ on the server.
328
+ *
329
+ * @return [FtpResponse]
330
+ */
208
331
  static VALUE Ftp_delete_file(VALUE self, VALUE rb_name) {
209
332
  return FtpResponse_wrap(sfFtp_deleteFile(Get_Ftp_Struct(self), StringValueCStr(rb_name)));
210
333
  }
211
334
 
335
+ /* call-seq:
336
+ * download(remote_file, local_path, mode = :binary) -> FtpResponse
337
+ *
338
+ * Downloads +remote_file+ from the server into +local_path+ (a local
339
+ * directory). +mode+ is an FtpTransferMode name or value.
340
+ *
341
+ * @return [FtpResponse]
342
+ */
212
343
  static VALUE Ftp_download(int argc, VALUE* argv, VALUE self) {
213
344
  VALUE rb_remote, rb_local, rb_mode;
214
345
  sfFtpTransferMode mode = sfFtpBinary;
@@ -223,6 +354,16 @@ static VALUE Ftp_download(int argc, VALUE* argv, VALUE self) {
223
354
  StringValueCStr(rb_local), mode));
224
355
  }
225
356
 
357
+ /* call-seq:
358
+ * upload(local_file, remote_path, mode = :binary, append = false) -> FtpResponse
359
+ *
360
+ * Uploads +local_file+ to +remote_path+ (a directory on the server).
361
+ * +mode+ is an FtpTransferMode name or value; if +append+ is true, the
362
+ * data is appended to an existing remote file of the same name instead of
363
+ * overwriting it.
364
+ *
365
+ * @return [FtpResponse]
366
+ */
226
367
  static VALUE Ftp_upload(int argc, VALUE* argv, VALUE self) {
227
368
  VALUE rb_local, rb_remote, rb_mode, rb_append;
228
369
  sfFtpTransferMode mode = sfFtpBinary;
@@ -242,6 +383,14 @@ static VALUE Ftp_upload(int argc, VALUE* argv, VALUE self) {
242
383
  StringValueCStr(rb_remote), mode, append));
243
384
  }
244
385
 
386
+ /* call-seq:
387
+ * send_command(command, parameter = nil) -> FtpResponse
388
+ *
389
+ * Sends a raw FTP command, for functionality not exposed by the other
390
+ * methods. +command+ should not include the trailing CRLF.
391
+ *
392
+ * @return [FtpResponse]
393
+ */
245
394
  static VALUE Ftp_send_command(int argc, VALUE* argv, VALUE self) {
246
395
  VALUE rb_command, rb_parameter;
247
396
 
@@ -252,81 +401,198 @@ static VALUE Ftp_send_command(int argc, VALUE* argv, VALUE self) {
252
401
  NIL_P(rb_parameter) ? NULL : StringValueCStr(rb_parameter)));
253
402
  }
254
403
 
404
+ /* call-seq: ok? -> true or false
405
+ *
406
+ * Returns +true+ if the server reported success.
407
+ *
408
+ * @return [Boolean] whether the status is a "success" code (< 400)
409
+ */
255
410
  static VALUE FtpResponse_ok(VALUE self) {
256
411
  return BOOL2RB(sfFtpResponse_isOk(Get_FtpResponse_Struct(self)));
257
412
  }
258
413
 
414
+ /* call-seq: status -> Integer
415
+ *
416
+ * Returns the raw status code reported by the server.
417
+ *
418
+ * @return [Integer] the raw FTP status code
419
+ */
259
420
  static VALUE FtpResponse_status(VALUE self) {
260
421
  return INT2NUM(sfFtpResponse_getStatus(Get_FtpResponse_Struct(self)));
261
422
  }
262
423
 
424
+ /* call-seq: status_name -> Symbol
425
+ *
426
+ * Returns the status as an FtpStatus name.
427
+ *
428
+ * @return [Symbol] an FtpStatus name for #status
429
+ */
263
430
  static VALUE FtpResponse_status_name(VALUE self) {
264
431
  return ID2SYM(
265
432
  rb_intern(ftp_status_name(sfFtpResponse_getStatus(Get_FtpResponse_Struct(self)))));
266
433
  }
267
434
 
435
+ /* call-seq: message -> String
436
+ *
437
+ * Returns the message sent by the server.
438
+ *
439
+ * @return [String] the full response message sent by the server
440
+ */
268
441
  static VALUE FtpResponse_message(VALUE self) {
269
442
  return rb_str_new_cstr(sfFtpResponse_getMessage(Get_FtpResponse_Struct(self)));
270
443
  }
271
444
 
445
+ /* call-seq: ok? -> true or false
446
+ *
447
+ * Returns +true+ if the server reported success.
448
+ *
449
+ * @return [Boolean] whether the status is a "success" code (< 400)
450
+ */
272
451
  static VALUE FtpDirectoryResponse_ok(VALUE self) {
273
452
  return BOOL2RB(sfFtpDirectoryResponse_isOk(Get_FtpDirectoryResponse_Struct(self)));
274
453
  }
275
454
 
455
+ /* call-seq: status -> Integer
456
+ *
457
+ * Returns the raw status code reported by the server.
458
+ *
459
+ * @return [Integer] the raw FTP status code
460
+ */
276
461
  static VALUE FtpDirectoryResponse_status(VALUE self) {
277
462
  return INT2NUM(sfFtpDirectoryResponse_getStatus(Get_FtpDirectoryResponse_Struct(self)));
278
463
  }
279
464
 
465
+ /* call-seq: status_name -> Symbol
466
+ *
467
+ * Returns the status as an FtpStatus name.
468
+ *
469
+ * @return [Symbol] an FtpStatus name for #status
470
+ */
280
471
  static VALUE FtpDirectoryResponse_status_name(VALUE self) {
281
472
  return ID2SYM(rb_intern(
282
473
  ftp_status_name(sfFtpDirectoryResponse_getStatus(Get_FtpDirectoryResponse_Struct(self)))));
283
474
  }
284
475
 
476
+ /* call-seq: message -> String
477
+ *
478
+ * Returns the message sent by the server.
479
+ *
480
+ * @return [String] the full response message sent by the server
481
+ */
285
482
  static VALUE FtpDirectoryResponse_message(VALUE self) {
286
483
  return rb_str_new_cstr(
287
484
  sfFtpDirectoryResponse_getMessage(Get_FtpDirectoryResponse_Struct(self)));
288
485
  }
289
486
 
290
- /* Through the UTF-32 entry point, so a path with non-ASCII characters survives
291
- the trip; the plain getter re-encodes it through the C locale. */
487
+ /* call-seq: directory -> String
488
+ *
489
+ * Through the UTF-32 entry point, so a path with non-ASCII characters survives
490
+ * the trip; the plain getter re-encodes it through the C locale.
491
+ *
492
+ * @return [String] the directory requested/reported by the server
493
+ */
292
494
  static VALUE FtpDirectoryResponse_directory(VALUE self) {
293
495
  return utf32_to_rb(
294
496
  sfFtpDirectoryResponse_getDirectoryUnicode(Get_FtpDirectoryResponse_Struct(self)));
295
497
  }
296
498
 
499
+ /* call-seq: ok? -> true or false
500
+ *
501
+ * Returns +true+ if the server reported success.
502
+ *
503
+ * @return [Boolean] whether the status is a "success" code (< 400)
504
+ */
297
505
  static VALUE FtpListingResponse_ok(VALUE self) {
298
506
  return BOOL2RB(sfFtpListingResponse_isOk(Get_FtpListingResponse_Struct(self)));
299
507
  }
300
508
 
509
+ /* call-seq: status -> Integer
510
+ *
511
+ * Returns the raw status code reported by the server.
512
+ *
513
+ * @return [Integer] the raw FTP status code
514
+ */
301
515
  static VALUE FtpListingResponse_status(VALUE self) {
302
516
  return INT2NUM(sfFtpListingResponse_getStatus(Get_FtpListingResponse_Struct(self)));
303
517
  }
304
518
 
519
+ /* call-seq: status_name -> Symbol
520
+ *
521
+ * Returns the status as an FtpStatus name.
522
+ *
523
+ * @return [Symbol] an FtpStatus name for #status
524
+ */
305
525
  static VALUE FtpListingResponse_status_name(VALUE self) {
306
526
  return ID2SYM(rb_intern(
307
527
  ftp_status_name(sfFtpListingResponse_getStatus(Get_FtpListingResponse_Struct(self)))));
308
528
  }
309
529
 
530
+ /* call-seq: message -> String
531
+ *
532
+ * Returns the message sent by the server.
533
+ *
534
+ * @return [String] the full response message sent by the server
535
+ */
310
536
  static VALUE FtpListingResponse_message(VALUE self) {
311
537
  return rb_str_new_cstr(sfFtpListingResponse_getMessage(Get_FtpListingResponse_Struct(self)));
312
538
  }
313
539
 
540
+ /* call-seq: count -> Integer
541
+ *
542
+ * Returns the number of filenames in the listing.
543
+ *
544
+ * @return [Integer] the number of filenames in the listing
545
+ */
314
546
  static VALUE FtpListingResponse_count(VALUE self) {
315
547
  return SIZET2NUM(sfFtpListingResponse_getCount(Get_FtpListingResponse_Struct(self)));
316
548
  }
317
549
 
550
+ /* call-seq:
551
+ * name(index) -> String
552
+ *
553
+ * Returns the filename stored at +index+ in the listing.
554
+ *
555
+ * @return [String] the filename at +index+ in the listing
556
+ * @raise [IndexError] if +index+ is out of range
557
+ */
318
558
  static VALUE FtpListingResponse_name(VALUE self, VALUE rb_index) {
319
- return rb_str_new_cstr(sfFtpListingResponse_getName(Get_FtpListingResponse_Struct(self),
320
- (size_t)NUM2SIZET(rb_index)));
321
- }
559
+ void* response = Get_FtpListingResponse_Struct(self);
560
+ size_t index = (size_t)NUM2SIZET(rb_index);
561
+ size_t count = sfFtpListingResponse_getCount(response);
322
562
 
323
- void Init_Ftp(VALUE rb_module) {
324
- rb_cFtp = rb_define_class_under(rb_module, "Ftp", rb_cObject);
325
- rb_cFtpResponse = rb_define_class_under(rb_module, "FtpResponse", rb_cObject);
326
- rb_cFtpDirectoryResponse = rb_define_class_under(rb_module, "FtpDirectoryResponse", rb_cObject);
327
- rb_cFtpListingResponse = rb_define_class_under(rb_module, "FtpListingResponse", rb_cObject);
563
+ if (index >= count) {
564
+ rb_raise(rb_eIndexError, "index %zu outside of listing size %zu", index, count);
565
+ }
328
566
 
329
- rb_define_singleton_method(rb_cFtp, "new", Ftp_new, 0);
567
+ return rb_str_new_cstr(sfFtpListingResponse_getName(response, index));
568
+ }
569
+
570
+ /* Document-class: SFML::Ftp
571
+ * A basic FTP client. Every command method blocks until the server replies
572
+ * and returns an FtpResponse (or a more specific subtype).
573
+ */
574
+ void Init_Ftp(VALUE rb_mSFML) {
575
+ rb_cFtp = rb_define_class_under(rb_mSFML, "Ftp", rb_cObject);
576
+ rb_define_alloc_func(rb_cFtp, Ftp_alloc);
577
+ /* Document-class: SFML::FtpResponse
578
+ * The status and message returned by most Ftp commands.
579
+ */
580
+ rb_cFtpResponse = rb_define_class_under(rb_mSFML, "FtpResponse", rb_cObject);
581
+ rb_define_alloc_func(rb_cFtpResponse, FtpResponse_alloc);
582
+ /* Document-class: SFML::FtpDirectoryResponse
583
+ * An FtpResponse specialization returned by Ftp#working_directory,
584
+ * additionally carrying the directory path.
585
+ */
586
+ rb_cFtpDirectoryResponse = rb_define_class_under(rb_mSFML, "FtpDirectoryResponse", rb_cObject);
587
+ rb_define_alloc_func(rb_cFtpDirectoryResponse, FtpDirectoryResponse_alloc);
588
+ /* Document-class: SFML::FtpListingResponse
589
+ * An FtpResponse specialization returned by Ftp#directory_listing,
590
+ * additionally carrying the list of filenames.
591
+ */
592
+ rb_cFtpListingResponse = rb_define_class_under(rb_mSFML, "FtpListingResponse", rb_cObject);
593
+ rb_define_alloc_func(rb_cFtpListingResponse, FtpListingResponse_alloc);
594
+
595
+ rb_define_method(rb_cFtp, "initialize", Ftp_initialize, 0);
330
596
 
331
597
  rb_define_method(rb_cFtp, "connect", Ftp_connect, -1);
332
598
  rb_define_method(rb_cFtp, "login_anonymous", Ftp_login_anonymous, 0);