… | |
… | |
172 | |
172 | |
173 | =item json => JSON or JSON::XS object |
173 | =item json => JSON or JSON::XS object |
174 | |
174 | |
175 | This is the json coder object used by the C<json> read and write types. |
175 | This is the json coder object used by the C<json> read and write types. |
176 | |
176 | |
177 | If you don't supply it, then AnyEvent::Handle will use C<encode_json> and |
177 | If you don't supply it, then AnyEvent::Handle will create and use a |
178 | C<decode_json>. |
178 | suitable one, which will write and expect UTF-8 encoded JSON texts. |
179 | |
179 | |
180 | Note that you are responsible to depend on the JSON module if you want to |
180 | Note that you are responsible to depend on the JSON module if you want to |
181 | use this functionality, as AnyEvent does not have a dependency itself. |
181 | use this functionality, as AnyEvent does not have a dependency itself. |
182 | |
182 | |
183 | =item filter_r => $cb |
183 | =item filter_r => $cb |
… | |
… | |
395 | in UTF-8. |
395 | in UTF-8. |
396 | |
396 | |
397 | JSON objects (and arrays) are self-delimiting, so you can write JSON at |
397 | JSON objects (and arrays) are self-delimiting, so you can write JSON at |
398 | one end of a handle and read them at the other end without using any |
398 | one end of a handle and read them at the other end without using any |
399 | additional framing. |
399 | additional framing. |
|
|
400 | |
|
|
401 | The generated JSON text is guaranteed not to contain any newlines: While |
|
|
402 | this module doesn't need delimiters after or between JSON texts to be |
|
|
403 | able to read them, many other languages depend on that. |
|
|
404 | |
|
|
405 | A simple RPC protocol that interoperates easily with others is to send |
|
|
406 | JSON arrays (or objects, although arrays are usually the better choice as |
|
|
407 | they mimic how function argument passing works) and a newline after each |
|
|
408 | JSON text: |
|
|
409 | |
|
|
410 | $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever |
|
|
411 | $handle->push_write ("\012"); |
|
|
412 | |
|
|
413 | An AnyEvent::Handle receiver would simply use the C<json> read type and |
|
|
414 | rely on the fact that the newline will be skipped as leading whitespace: |
|
|
415 | |
|
|
416 | $handle->push_read (json => sub { my $array = $_[1]; ... }); |
|
|
417 | |
|
|
418 | Other languages could read single lines terminated by a newline and pass |
|
|
419 | this line into their JSON decoder of choice. |
400 | |
420 | |
401 | =cut |
421 | =cut |
402 | |
422 | |
403 | register_write_type json => sub { |
423 | register_write_type json => sub { |
404 | my ($self, $ref) = @_; |
424 | my ($self, $ref) = @_; |
… | |
… | |
859 | 2.09 (and JSON::XS version 2.2) and above. You have to provide a |
879 | 2.09 (and JSON::XS version 2.2) and above. You have to provide a |
860 | dependency on your own: this module will load the JSON module, but |
880 | dependency on your own: this module will load the JSON module, but |
861 | AnyEvent does not depend on it itself. |
881 | AnyEvent does not depend on it itself. |
862 | |
882 | |
863 | Since JSON texts are fully self-delimiting, the C<json> read and write |
883 | Since JSON texts are fully self-delimiting, the C<json> read and write |
864 | types are an ideal simple RPC protocol: just exchange JSON datagrams. |
884 | types are an ideal simple RPC protocol: just exchange JSON datagrams. See |
|
|
885 | the C<json> write type description, above, for an actual example. |
865 | |
886 | |
866 | =cut |
887 | =cut |
867 | |
888 | |
868 | register_read_type json => sub { |
889 | register_read_type json => sub { |
869 | my ($self, $cb, $accept, $reject, $skip) = @_; |
890 | my ($self, $cb, $accept, $reject, $skip) = @_; |
… | |
… | |
871 | require JSON; |
892 | require JSON; |
872 | |
893 | |
873 | my $data; |
894 | my $data; |
874 | my $rbuf = \$self->{rbuf}; |
895 | my $rbuf = \$self->{rbuf}; |
875 | |
896 | |
876 | my $json = $self->{json} ||= JSON::XS->new->utf8; |
897 | my $json = $self->{json} ||= JSON->new->utf8; |
877 | |
898 | |
878 | sub { |
899 | sub { |
879 | my $ref = $json->incr_parse ($self->{rbuf}); |
900 | my $ref = $json->incr_parse ($self->{rbuf}); |
880 | |
901 | |
881 | if ($ref) { |
902 | if ($ref) { |