This document describes the keyword naming strategy and syntax as used by PSYC.
All keywords used as method name of a Packet have a special syntax. This syntax allows generic treatment of specialized methods.
Keywords consist of ASCII characters and have the following syntax:
keyword = 1*short-subkeyword *long-subkeyword =/ 1*long-subkeyword short-subkeyword = printchar long-subkeyword = "_" 1*alphanumeric alphanumeric = %x30-39 / %x41-5A / %x61-7A ; The ASCII characters 0-9, a-z and A-Z printchar = <see Spec:Packet for definition of printchar>
This is a long form of a keyword: _reply_error_invalidTarget_noSuchObject. And the short form for it is: reto
Keywords can also be mixed: ret_invalidNamingSyntaxForThisSite.
Short vs. Long Forms
All keywords defined within this specification have a short form and a long form. However, some special or experimental keywords don't have short forms until they are standardized.
All implementations MUST accept both forms for the keywords defined in this specification.
It is recommended to only pass long forms to applications in programmer APIs, so that short forms stay a simple protocol level optimization. Thus, mapping from short forms to long forms should happen right after parsing.
A keyword consists of a hierarchical set of subkeywords. The meaning of the keyword becomes more precise with the number of additional subkeywords appended to its tail.
That means that the receiver of an unknown keyword can strip off subkeywords from the end of the keyword until it recognizes it. With this the receiver can process the packet by only using the known part of the keyword. This implements a form of semantic inheritance that we call keyword inheritance.
How to come up with a method name
Most important thing to remember when creating a new method: Don't use your language grammar logic, but always ask yourself, is this a special and compatible case of something we already have. For instance if you have _request_file and you want to be able to request a list of files, then _request_file_list would initiate a file transfer whereas _request_list_files actually sends you a list. So the latter is better.
The PSYC Draft tentatively tries to name the methods that are being or will be used in PSYC 1.0, but in fact we are still thinking on how to get those names just perfect for 1.0. So there may be a revision coming on. First the original design from 1998, then the revisionary thoughts.
The current use of methods is best seen in the psyced text database which comes with the distribution or can be inspected at http://www.psyced.org/dist/world/default/de/plain.textdb - Codes with leading uppercase (like _TEXT_something) are internal to psyced, so just skip them. Unfortunately you can only look at the german version because the english one is the default and is contained within the source code of psyced. Yes we are slowly changing that.
The big rename
<lynX> Ever since I first sketched PSYC i had the plan to do a major overhaul of the entire keyword naming scheme just before releasing PSYC 1.0 in order to learn from "beta" practice. This is why PSYC as currently in use with psyced has some non-optimal names for methods and variables, sometimes it was better to postpone a rename to avoid unnecessarily breaking things and simply mention it in the source, on the Talk:Method or on the Talk:Keyword naming page. Unfortunately the latter is held in German. Instead, the great rename should happen with the introduction of the new syntax according to the specification, when everything is changed anyhow. Of course it is close to impossible to support both syntaxes and naming schemes in psyced at the same time, so once the big rename happens, psyced will no longer be able to talk to old applications, even if it formally still supports the old dot syntax. If you have suggestions on which keywords to rename in order to have a more efficient inheritance structure etc, please add to Talk:Method.