Both person and place entities provide user commands.
These used to be command line commands as described in the psyced manual (see also Help:Contents), but now it is also possible to define commands in a proper PSYC protocol syntax, which makes it easier and cleaner to put functions into client menus and wizards.
We currently have a somewhat redundant choice of _request_something and _request_do_something. The general rule is, _request_do_something is for clients talking to their identity whereas _request_something are interserver or other inter-entity communications.
It is rather easy to add more methods to the new request() mechanism, so you can either force us to do that, or continue using either _request_input for raw user input including potential command characters, or use _request_execute for everything which is known to be a command, without the leading command character.
The practice of using _request_execute with the command line in the psyc body is also described below and it will continue to work even as the proper technique becomes more and more available.
Any command request method sent to your UNI, be it _request_input or anything that starts with _request_execute, accept a _focus variable to indicate to which "current" room or person the command applies. This even has an effect on the "/people" output - it shows your last active public room. ;-)
Contents |
Command requests
All variations of _request_do allow you to specify a _focus, additionally many commands have argument vars. Here's the current list of defined PSYC command requests:
Standard Person Commands
These are the commands PSYC person entities may want to implement:
| _request_do... | related variables | equivalent command |
|---|---|---|
| _action_whatever | _focus | /action |
| This command lets the person entity do a chat action, like _request_do_action_hug would virtually hug someone. | ||
| _add_friend | _nick_person or _person, _trustee | /friend |
| _cast | _method, _amount_friendivity | /cast (= /friendcast) |
| _clear_friend | _nick_person or _person | /cancel |
| _clear_log | /logclear | |
| _enter | _group | /enter |
| _enter_home | (too psyced specific) | /home |
| _examine | _person _trustee _tag _format | /examine /surf |
| _follow | /follow | |
| _help | /help | |
| _invite | _person _focus | /invite |
| _leave | _group | /leave |
| _list_peers | /show * | |
| _list_peers_JSON | /show data | |
| _list_places | /list | |
| _list_places_public | /places | |
| _list_users_public | /people | |
| _message | _person, _group | /tell and / |
| This sends a message to either a _person or a _group. | ||
| _presence | _degree_mood _degree_availability _degree_automation _description_presence | /availability /mood and many more |
| _quit | /quit | |
| _register | _password | /register |
| _remove_friend | _nick_person or _person | /unfriend |
| _retrieve | ||
| Generates a _status_storage with _application variables. | ||
| _save | /save | |
| _set | _key _value | /set |
| _show_log | _amount _match _parameter | /lastlog |
| _status | /status | |
| _store | _application* | |
| Stores all variables of the _application family in the entity storage. SHOULD also handle profile settings. | ||
| _subscribe | _group | /subscribe |
| _subscribe_permanent | _group | /subscribe |
| _time_boot | /uptime | |
| _unsubscribe | _group | /unsubscribe |
| _wake | _person | /wake |
Presence with PSYC clients
In PSYC, clients are in charge of setting and resetting presence states on behalf of their users. That means, that a client will probably want to transmit a _request_do_presence soon after logging in and before logging out using _request_do_quit. Quitting does not automatically send offline presence. This only happens when the client loses contact to the server abnormally.
So these are the functions that are only waiting for a nifty client programmer to implement them thru flashy buttons, wizards and menues.
Example: /invite
=_target psyc://psyc.example.net/~nick =_source_identification psyc://psyc.example.net/~nick :_person psyc://any.example.net/~newFriend :_focus psyc://oth.example.net/@place _request_do_invite .
Example: /set
:_key_set room :_value 101 _request_do_set .
Place command requests
| _request... | variables | equivalent command |
|---|---|---|
| _kick | _person | /kick |
| _nick | _nick_local (masquerade) | /nick |
| _set_masquerade | _flag_masquerade | /masq(uerade) |
| _set_owners | _list_owners | /owners |
| _set_public | _flag_public | /public |
| _set_style | _uniform_style | /style |
| _show_log | _match _amount _parameter | /history |
The _target MUST be aimed at a place (consider however, places potentially provide differing choices of methods). If your request is to be performed on behalf of an identity not identical to the source (typically the case for a client or external tool) you need to provide a _source_identification.
Note how the _requests in this case have no _do (since the place isn't your identity, but that's just an excuse).
Arbitrary commands
Arbitrary commands are the ones with a command character (like a slash, see below) followed by a series of arguments that in some cases only the user typing them and the application intended to receive them know about. Intermediate actors just need to forward them to the intended recipient. This is also sometimes referred to as ad hoc commands.
| A "_request_execute" is PSYC's functionality superhighway, since a user interface is supposed to deliver any user command that it doesn't have a use for, to the current communication counterpart. For instance if the user enters "/topic", you are not supposed to handle that command yourself. You should rather send it as a _request_execute (with the command in the body) to the counterpart which in that case probably is a chatroom, which happens to implement such a command. When you do not have a current counterpart, for instance in your "console/status" window, your command should be delivered to your identification (UNI). This is how a client software can appear to have an immense amount of functions, simply because your home server hosting the UNI does. |
Such arbitrary commands may be described in precision using signatures. The signature tells an automaton how to interpret the arguments in the command line, which PSYC variables to assign them to and which regular PSYC method to call.
- You may choose to provide multiple command characters for built-in, UNI and chat counterpart commands, not just "/", but then again - users do not really think about what they are doing to whom, so it may prove very unintuitive. See also "Don't Mode Me". That is: Users may not grasp the difference and get confused. Then again, maybe it is good users learn to grasp the difference..?
Additionally to _request_execute the person implementations also support _request_input which is just like _request_execute, but also includes any potential command characters. In fact it should be used for chat window inputs when you have a single-window UI which uses server-side input routing (query/talk and place choice management) to decide where user chat input should finally be sent. Using this makes your client side focus logic extremely simple: instead of keeping track which target the window currently has, you simple send _request_do's to the person to modify the default input route - or let the power user use slash commands. This is how telnet-like and old-school-IRC-like interfaces should be implemented.
Example
Here is an example of how to issue a command using _request_input
The UNI (psyc://host.tld/~nick) should be that of your self, /command is a command that the server understands.
_focus, if given, contains the current default target of your window, either a place or a person.
=_source_identification psyc://host.tld/~nick =_target psyc://host.tld/~nick :_focus psyc://oth.host/@place _request_input something the user typed .
Here's how to say goodbye from your PSYC UNI.
:_target psyc://host.tld/~nick _request_execute bye .
About the command character
The traditional command character of chat systems is the '/'. It appeared in Bitnet Relay, then IRC and it probably was used that way even before. We can't use it for IRC and Jabber access as client functions might interfere with it.
Also quite popular was the '.' character, especially in BBS systems. But there are chat situations where you quite likely want to start a line with a period sign, like a one-eyed smiley.
'#' is out because it is the comment character in many languages, thus impeding a mouse-paste of such source codes. '$' is used in everyday talk when it comes to mentioning prices.
We have been using '+' for a long while. lynX never thought it was a beautiful choice, but it was quite safe - the only problem appears when you feel like pasting a diff output.
Right now lynX is pondering whether we should switch again. What's wrong with '%'. Is there any reason not to have '%' as the default replacement for '/' ? It even has a resemblance!
Special cases
Request Description (/examine)
When you /x a person, _list messages are generated by the UNI. If you want to receive the original _status_description message, you have to send a _request_description directly to the entity and dress it with an _identification so that it can do PSYC AUTH. Auth works automatically behind your back, the UNIs (thus the psyceds) worry about that between each other.
Viewing Profile (/surf)
There is even a further alternative now. You can send
/examine <person> <trustee> <tag>
The trustee has to do with surfing the Social Network, you can put your own UNI in there if you don't have profiles. The tag can be interesting, as it not only lets you know which request matches which reply, but it also makes psyced deliver the description to you in HTML format much like the /surf command, so you can display it in a web browser. you may want to check out PsycZilla to see this in action.
Putting a tag in the command line is syntactically ugly, but one day there will be a change in the syntax of such a request, not in the functionality itself - so no big deal. Let's just be a little like IRC until we can do it the PSYC way. ;)
Questions & Answers
<kuchn> Why should a client implement it's own commands?
<lynX> It should *only* implement commands that need to be handled on client side, like initiating a File Transfer. All things a UNI can do for you, let her do it until PSYC has better client protocol (after 0.99).
Setting Topic
<lynX> since so far i never considered /topic a fundamental psyc feature, it is just one out of any possible commands implemented in a place. so it is quite correct to send the _execute to the place in this case.
- <kuchn> /topic shouldn't be handled by the client? Why does my client work properly with it's own _request_set_topic (with vars _target (the room-uni), _topic (the topic- if not set topic is cleared) and _nick as your own nick) ?
- <lynX> because for some hysterical raisin we have such a method, but don't trust it. Use the _focus var in _request_execute or _input instead.
- <elmex> If i have a 'topic'-bar, should i use a special _<message> for it or should i send /topic via _request_execute and parse the result?
- <lynX> yes, always use the result because your room may not like your _request or it may decide to first translate your topic into finnish.
See also
Commands are not actions.