docs/character-classes/client.md

# 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"/>
```