diff options
Diffstat (limited to 'spec.pod')
-rw-r--r-- | spec.pod | 119 |
1 files changed, 80 insertions, 39 deletions
@@ -36,10 +36,6 @@ Each element may be of a different type. Allowed types are: =item * Strings -=item * Booleans - -I<TODO:> Get rid of booleans and stick with integers instead? - =item * Arrays with elements of allowed types The elements of the array do not have to be of the same type. A tuple itself is @@ -62,23 +58,59 @@ A I<pattern> is similar to a tuple, but has a smaller set of allowed types: =item * Strings -=item * Booleans - =item * Wildcards =back -That is: Floating point numbers, arrays and maps are not allowed in patterns. +That is: Arrays and maps are not allowed in patterns. Neither are floating +point types, but see below on how they are handled. + +A string should always be encoded in UTF-8. + +An integer must be representable in a signed (two's complement) 32-bit integer. +Thus anything in the range of C<-2^31> to C<2^31-1> constitutes a valid integer +value. It is recommended that implementations extend this definition to 64-bit +integers, but portable applications should not assume these to be available. + +The maximum precision and range of floating point numbers is dictated by the +implementation, but should at least be a double precision IEEE 754 floating +point. The special values C<NaN>, C<-Inf> and C<+Inf> are not allowed, and +C<+0> and C<-0> should be considered as equivalent (i.e. the sign of the zero +value may get lost in transmission). + +Even though the above string, integer and float types are specified separately, +tuples are dynamically typed and conversion between the types is done depending +on what the application expects to receive. + +Integer to float conversion should be obvious. Float to integer conversion may +be done either by rounding the floating point number to the nearest integer or +by throwing away the non-integer part (flooring), depending on the +implementation. What happens when the number is out of the range of the integer +type is also implementation-defined. + +String to integer conversion should at least be supported when the string +matches the following regular expression: C<^-?([1-9][0-9]*|0)$>, in which case the +string should be interpreted as a decimal number. Other formats may be allowed +as well, but this is implementation-defined and should not be relied upon by +applications that attempt to be portable. Behaviour when the number is out of +range for the chosen integer type is again implementation-defined. -All integers should be representable in a signed (two's complement) 64-bit -integer. Thus anything in the range of C<-2^63> to C<2^63-1> (both inclusive) -are valid integer values. +String to float conversion follows the same behaviour as string to integer +conversion. Strings matching the following regular expression must be supported +for conversion: C<-?([1-9][0-9]*|0)(\.[0-9]+)?([eE]?[+-]?[0-9]+)?>. -The maximum precision of floating point numbers is dictated by the -implementation. In practice, this can be expected to be either single precision -or double precision IEEE 754 floating points. +Float to string and integer to string conversions are implementation-defined, +as long they are reversible by the string to float and string to integer +conversions used in the same implementation. + +Conversions to and from array and map types should not be allowed. + +There is no special boolean type, but if a boolean value is required then the +following values should evaluate to I<false>: The integer or floating point +with a value equal to 0, the zero-length string and the one-length string +containing only the ASCII C<'0'> character. Any other value should be +considered I<true>. -Strings should be encoded in UTF-8. =head2 Matching @@ -96,39 +128,48 @@ either of the following holds: =item 1. Either element is a wildcard -=item 2. The elements are of the same type, and their value is equivalent. +If the element of either the pattern or the tuple is a wildcard, then other +element can be of any type and value (this includes arrays and maps). -=back +=item 2. Both elements have the same integer value -The first rule is trivial: if the element of either the pattern or the tuple is -a wildcard, then other element can be of any type and value. The second rule is -slightly less obvious, and requires the type definitions given in the previous -section to be interpreted properly. One implication of the second rule is that -it is impossible to do a non-wildcard match on anything other than integers, -strings and booleans, since values of other types are not allowed in patterns. -Another thing to keep in mind is that both values have to be of the same type, -so the integer C<0> is not equivalent to the boolean C<false>. Nor is the -string C<"15"> equivalent to the integer C<15>. However, integers are always -equal if their numeric value is equivalent (provided they are within the -specified range). This means that if, within an implementation, a tuple with an -element of type uint8 with value C<5> is matched against a pattern with an -element at the same location of type int64 and with the same value, then these -elements match. Two strings are equal if they are of the same length and all of -their characters have the same unicode values. Strings are thus matched in a -case-sensitive fashion. The above rules also imply that the tuple must hold at -least as many elements as the pattern. +This implies that both elements can be converted to an integer type, as +specified in the previous section. This also implies that, when matching on +floating point types, only the integer representation (either rounded or +floored) is considered. Since this is implementation-defined, matching against +a floating point number for which the floored number is not equivalent to the +rounded number is not portable. -I<TODO:> Allow integer-formatted strings to do match integers of the same value? +=item 3. Both elements have the same string value -I<TODO:> Allow the integer C<10> in a pattern to match a float C<10.0> in a tuple? +Two strings are equivalent if they have the same length and their byte +representations are equivalent. Strings are thus matched in a case-sensitive +fashion. +=back +Rule 2 and 3 never apply to array or map types, as those can be converted to +neither integers nor strings. Thus matching on these types is impossible except +in rule 1, using a wildcard. -=head1 Communication +The above rules also imply that the tuple must hold at least as many elements +as the pattern, but the number of elements does not have to be equal. -I<TODO:> Describe the terms "network" and "session" +Note that matching on the previously mentioned notion of a boolean type is not +possible. That is, you can't specify that you wish to match on all elements +that are considered I<true> or I<false>. If this is required, it is recommended +to standardise on the integers C<1> and C<0> to represent true or false, +respectively. -I<TODO:> Refactor with the return-path being an argument of I<send>. +Also keep in mind that the above matching rules have a lot of +implementation-defined behaviour. For example, the integer C<1234> will match +on the string C<"02322"> if the implementation accepts octal numbers as a valid +candidate for integer conversion. This may lead to unexpected behaviour, but I +do not expect this to be a problem in practice. + + + +=head1 Communication Send and register are the two simplest form of communication. A session uses the I<register> primitive to indicate that it is interested in receiving tuples @@ -154,4 +195,4 @@ session sent them. Besides that, there are no ordering restrictions: Messages sent by two different sessions may be received by an other session in any order. -I<TODO:> More ordering constraints on message receival? +I<TODO:> Specify the return-path. |