Mercurial > scansion / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/character-classes/client.md	Fri Feb 01 11:22:20 2019 +0000
@@ -0,0 +1,92 @@
+# Client: XMPP client
+
+The `[Client]` class represents an XMPP client connection to a server.
+
+Example:
+
+```
+[Client] Romeo
+	jid: romeo@example.com
+	password: s3cr3t!
+```
+
+
+## Properties
+
+| Property     | Description                         |
+|:-------------|:------------------------------------|
+| jid          | The JID to connect to the server as |
+| password     | The password to connect with        |
+| connect_host | The server host, if not the default |
+| connect_port | The server port, if not the default |
+
+## Actions
+
+### sends
+
+Sends a stanza to the XMPP server.
+
+Example:
+
+```
+Romeo sends:
+	<iq type="get" id="123">
+		<query xmlns="jabber:iq:roster"/>
+	</iq>
+```
+
+### receives
+
+Expects to receive a stanza from the server.
+
+Example:
+
+```
+Romeo receives:
+	<iq type="result" id="123">
+		<query xmlns="jabber:iq:roster">
+			<item jid="juliet@example.com" subscription="both" />
+		</query>
+	</iq>
+```
+
+If no stanza is expected, the simple string 'nothing' may be used:
+
+```
+Romeo receives: nothing
+```
+
+#### Matching rules
+
+When a stanza is received from the server, it is matched against the one in the script.
+If it does not match, the script will fail and abort.
+
+The matching has two modes, strict and non-strict. They require:
+
+Non-strict mode:
+
+- All attributes in the expected stanza must be present in the received stanza. Additional
+attributes in the received stanza are ignored.
+- All tags in the expected stanza must be present in the received stanza. Additional tags are ignored. Order is ignored.
+
+Strict mode:
+
+- All attributes in the expected stanza must be in the received stanza, and vice-versa. Additional attributes in the received stanza are not allowed.
+- All tags in the expected stanza must be in the received stanza, additional tags are not allowed. Order must be the same.
+
+Both modes:
+
+- If an attribute value is `{scansion:any}` in the expected stanza, that attribute must be present in the received stanza, but
+the value itself is ignored. This is useful for e.g. id attributes or other attributes that may vary unpredictably.
+
+By default tags in the default namespace are matched using the non-strict rules, but tags with their own namespace are matched using the
+strict rules. You can override the matching behaviour for any tag by adding a `scansion:strict` attribute with a value of `true` or `false`:
+
+```
+# By default this would match any message, by ignoring
+# extra payloads. However we enable strict mode to ensure
+# that it only matches a completely empty message stanza:
+
+Romeo receives:
+	<message scansion:strict="true"/>
+```