ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Handle.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.240 by root, Tue Dec 17 16:43:15 2013 UTC vs.
Revision 1.241 by root, Fri Sep 5 22:17:26 2014 UTC

… …
501=item json => L<JSON>, L<JSON::PP> or L<JSON::XS> object 501=item json => L<JSON>, L<JSON::PP> or L<JSON::XS> object
502 502
503This is the json coder object used by the C<json> read and write types. 503This is the json coder object used by the C<json> read and write types.
504 504
505If you don't supply it, then AnyEvent::Handle will create and use a 505If you don't supply it, then AnyEvent::Handle will create and use a
506suitable one (on demand), which will write and expect UTF-8 encoded JSON 506suitable one (on demand), which will write and expect UTF-8 encoded
507JSON texts (either using L<JSON::XS> or L<JSON>). The written texts are
508guaranteed not to contain any newline character.
509
510For security reasons, this encoder will likely I<not> handle numbers and
511strings, only arrays and objects/hashes. The reason is that originally
512JSON was self-delimited, but Dougles Crockford thought it was a splendid
513idea to redefine JSON incompatibly, so this is no longer true.
514
515For protocols that used back-to-back JSON texts, this might lead to
516run-ins, where two or more JSON texts will be interpreted as one JSON
507texts. 517text.
518
519For this reason, if the default encoder uses L<JSON::XS>, it will default
520to not allowing anything but arrays and objects/hashes, at least for the
521forseeable future (it will change at some point). This might or might not
522be true for the L<JSON> module, so this might cause a security issue.
523
524If you depend on either behaviour, you should create your own json object
525and pass it in explicitly.
508 526
509=item cbor => L<CBOR::XS> object 527=item cbor => L<CBOR::XS> object
510 528
511This is the cbor coder object used by the C<cbor> read and write types. 529This is the cbor coder object used by the C<cbor> read and write types.
512 530
513If you don't supply it, then AnyEvent::Handle will create and use a 531If you don't supply it, then AnyEvent::Handle will create and use a
514suitable one (on demand), which will write CBOR without using extensions, 532suitable one (on demand), which will write CBOR without using extensions,
515if possible. texts. 533if possible.
516 534
517Note that you are responsible to depend on the L<CBOR::XS> module if you 535Note that you are responsible to depend on the L<CBOR::XS> module if you
518want to use this functionality, as AnyEvent does not have a dependency on 536want to use this functionality, as AnyEvent does not have a dependency on
519it itself. 537it itself.
520 538
… …
1054 1072
1055Encodes the given hash or array reference into a JSON object. Unless you 1073Encodes the given hash or array reference into a JSON object. Unless you
1056provide your own JSON object, this means it will be encoded to JSON text 1074provide your own JSON object, this means it will be encoded to JSON text
1057in UTF-8. 1075in UTF-8.
1058 1076
1077The default encoder might or might not handle every type of JSON value -
1078it might be limited to arrays and objects for security reasons. See the
1079C<json> constructor attribute for more details.
1080
1059JSON objects (and arrays) are self-delimiting, so you can write JSON at 1081JSON objects (and arrays) are self-delimiting, so if you only use arrays
1060one end of a handle and read them at the other end without using any 1082and hashes, you can write JSON at one end of a handle and read them at the
1061additional framing. 1083other end without using any additional framing.
1062 1084
1063The generated JSON text is guaranteed not to contain any newlines: While 1085The JSON text generated by the default encoder is guaranteed not to
1064this module doesn't need delimiters after or between JSON texts to be 1086contain any newlines: While this module doesn't need delimiters after or
1065able to read them, many other languages depend on that. 1087between JSON texts to be able to read them, many other languages depend on
1088them.
1066 1089
1067A simple RPC protocol that interoperates easily with other languages is 1090A simple RPC protocol that interoperates easily with other languages is
1068to send JSON arrays (or objects, although arrays are usually the better 1091to send JSON arrays (or objects, although arrays are usually the better
1069choice as they mimic how function argument passing works) and a newline 1092choice as they mimic how function argument passing works) and a newline
1070after each JSON text: 1093after each JSON text:

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines