summaryrefslogtreecommitdiff
path: root/spec.pod
diff options
context:
space:
mode:
Diffstat (limited to 'spec.pod')
-rw-r--r--spec.pod119
1 files changed, 80 insertions, 39 deletions
diff --git a/spec.pod b/spec.pod
index 5d20adc..8f8df72 100644
--- a/spec.pod
+++ b/spec.pod
@@ -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.