Author: dylan Date: 2005-03-20 02:04:28 -0500 (Sun, 20 Mar 2005) New Revision: 648
Added: trunk/docs/spec/Haver/ trunk/docs/spec/Haver/Spec.pod Modified: trunk/ trunk/docs/manual/chap/introduction.texi trunk/docs/manual/haver.texi Log: [EMAIL PROTECTED]: dylan | 2005-03-20 01:52:08 -0500 writing Haver::Spec. Property changes on: trunk ___________________________________________________________________ Name: svk:merge - 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178 27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212 e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:833 edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238 + 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178 27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212 e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:850 edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238 Modified: trunk/docs/manual/chap/introduction.texi =================================================================== --- trunk/docs/manual/chap/introduction.texi 2005-03-15 04:58:25 UTC (rev 647) +++ trunk/docs/manual/chap/introduction.texi 2005-03-20 07:04:28 UTC (rev 648) @@ -1,17 +1,6 @@ @node Introduction @chapter Introduction -Haver is a simple line based, tab delimited protocol. It is -not meant as a replacement to IRC, Jabber, -or SILC. Nevertheless, it should be rather -less difficult to write clients for haver than the above mentioned protocols. - -This protocol is being designed because current protocols are either -too limited (e.g. IRC) or too complicated (e.g. jabber, SILC) to extend -in playful and useless ways. Something simple and powerful needs to exist, -and this could very well be haver. - - @menu * Servers:: * Clients:: Modified: trunk/docs/manual/haver.texi =================================================================== --- trunk/docs/manual/haver.texi 2005-03-15 04:58:25 UTC (rev 647) +++ trunk/docs/manual/haver.texi 2005-03-20 07:04:28 UTC (rev 648) @@ -40,14 +40,12 @@ @node Top @top Divine Secrets of Haver - @heading Abstract Haver is a network protocol for real time textual confrencing, and is being developed by an international coalition of four people. It does not utilize advanced technologies such as XML. - @end ifnottex @menu Added: trunk/docs/spec/Haver/Spec.pod =================================================================== --- trunk/docs/spec/Haver/Spec.pod 2005-03-15 04:58:25 UTC (rev 647) +++ trunk/docs/spec/Haver/Spec.pod 2005-03-20 07:04:28 UTC (rev 648) @@ -0,0 +1,137 @@ +=head1 NAME + +Haver::Spec - The Divine Secrets of Haver + +=head1 ABSTRACT + +Haver is a network protocol for real time textual confrencing, +and is being developed by an international coalition of four people. +It does B<not> utilize advanced technologies such as XML. + + +=head1 INTRODUCTION + +Haver is a simple line based, tab delimited protocol. It is +not meant as a replacement to IRC, Jabber, +or SILC. Nevertheless, it should be rather +less difficult to write clients for haver than the above mentioned protocols. + +This protocol is being designed because current protocols are either +too limited (e.g. IRC) or too complicated (e.g. jabber, SILC) to extend +in playful and useless ways. Something simple and powerful needs to exist, +and this could very well be haver. + +It is also a programming exercise for the authors, who have been having a lot of fun +writing haver clients in various languages. + +=head2 Servers + +A Haver server is almost, but not quite, entirely unlike chocolate. +While chocolate's main purpose is to delight with its delicious +taste, haver servers do not have any taste. + +Instead, haver servers route messages (events) to their clients, +and maintain data about their clients and channels. +Monolithic servers will do more than just this, and will handle many events +internally. Micro-servers will offload this burden unto special service clients. + +=head2 Clients + +A client is a simple TCP/IP program that conforms to the Haver protocol. +There are at least two types of clients: Users and Services. +The vast majority of clients will be users, which are representations +of either real people, bots, or GreenReaper. + +Services may add new protocol events to the server, +produce virtual user-like entities called Agents to interact with +the real users, and extend virtual channels into the server allows different +forms of server linking. + +=head2 Channels + +Channels are pretty much like they are on IRC, except their identifiers (channel ids, cids) +follow the same rules as identifiers for the other types of objects (users, services, etc). + +They may either automagically created upon use, or channel creation can be +restricted to privileged users. + +=head2 Lobby + +There is a global entity which is very similiar to a channel, but not quite. +It is called the lobby, and it contains all users, channels, and services that exist on the server. +It is in essence a virtual channel. + +=head2 Namespace + +Users, Services, and Channels all exist in seperate namespaces. +Thus you can have a channel named bob, a user named bob, and a service named bob. + +The lobby exists outside of this namespace scheme. + +=head1 PROTOCOL + +The haver protocol is in the UTF-8 encoding, as defined in +RFC 2279. However, only the first 127 character codes (the ASCII range) +are used for events, identifiers, and delimiters. + +The protocol is delimited into lines separated by CR LF (0x0D 0x0A). +Each line is further delimited by the Tab character (0x09) +into a series of tokens. +The first of the tokens is called the command, +the remaining tokens (if any) are refered to as the arguments. + +If a literal tab, carriage return, or line feed needs to be sent, +it must be written in escaped form with the Esc character (0x1b). +In addition, Esc itself must be escaped. + +A literal carriage return is represented by ``<Esc>r'' +a literal line feed by ``<Esc>n'', a tab by ``<Esc>t'', +and an Esc by ``<Esc>e''. +Naturally, replace ``<Esc>'' with the Esc character (0x1b). + +See L<Haver::Spec::Escapes> for more information and a perl example. + +=head1 FORMATS + +This section describes formats used in the haver protocol, +such as how dates, times, and time zones are formatted. +It also describes the format for identifiers (the ids of channels, users, etc), +and events. + +=head2 Dates and Times + +Dates are expressed in YYYY-MM-DD format, e.g. 1985-09-14. + +The format for times is HH:MM:SS.nnn. +HH is from 0 to 23, MM is from 0 to 59, +SS is from 0 to 59 [What about leap seconds?]. +The ``.nn'' part is fractional parts of a second, +it is optional and may be ommited. + +Time zones are in the form of [+-]HHMM. +For example, EDT is -0400. + +A full datetime is thus ``YYYY-MM-DD HH:MM:SS [-+]HHMM'', +for example: ``2004-08-15 19:01:05 -0400''. + +=head2 Identifiers + +The format for identifiers is best expressed +by the regular expression C</&?[A-Za-z][A-Za-z0-9_.'@-]+/> + +In English, identifiers may be prefixed with an ampersand (C<&>), +must begin with a letter, and must be followed by one or more of: letters; +numbers; periods; hyphens; underscores; single quotes; or the at symbol (C<@>). +All other characters constitute an illegal ID. + +Further, the length of the ID must be greater than two +and less than or equal to 20 (C<length(id) E<gt> 2 && length(id) <= 20>). + +=head2 Events + +Events must only contain upper-case letters, hyphers, underscores, +and colons. (C</[A-Z:_-]/>). + +=head1 EVENTS + +
