libervia-backend: doc/libervia-cli/pubsub.rst annotate

annotate doc/libervia-cli/pubsub.rst @ 3682:7c990aaa49d3

comp AP Gateway: ActivityPub Component first draft: this implement the base component, it is for the moment usable only through a developer API. rel: 362

author	Goffi <goffi@goffi.org>
date	Sun, 26 Sep 2021 16:41:55 +0200
parents	7bc443253b7c
children	e597dbfbc4c6

rev	line source
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	1 .. _libervia-cli_pubsub:
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	2
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	3 =========================
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	4 pubsub: PubSub management
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	5 =========================
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	6
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	7 PubSub commands are low level command to handle a PubSub Service.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	8 They are using the generic pubsub arguments
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	9
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	10 For most of those commands, :ref:`pubsub_common` commands are used to specify the
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	11 destination item.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	12
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	13 set
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	14 ===
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	15
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	16 Publish a pubsub item.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	17
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	18 ``stdin`` is used to get the raw XML of the payload of the item to publish.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	19
3100 cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	20 ``-f KEY VALUE, --field KEY VALUE`` can be used to specify publish options, i.e. option
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	21 which must be set if the node already exists, or used if the node is to be created, see
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	22 `XEP-0060 §7.1.5`_ for details.
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	23
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	24 In the same way as for :ref:`libervia-cli_pubsub_node_create`, ``-F, --full-prefix`` can be used if
3100 cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	25 you need to specify the full option name.
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	26
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	27 .. _XEP-0060 §7.1.5: https://xmpp.org/extensions/xep-0060.html#publisher-publish-options
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation: Goffi <goffi@goffi.org> parents: 3041 diff changeset	28
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	29 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	30 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	31
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	32 Create an item with a custom note XML::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	33
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	34 $ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' \| li pubsub set -n "notes"
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	35
3612 21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	36 .. _li_pubsub_get:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	37
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	38 get
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	39 ===
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	40
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	41 Retrieve items from specified node. Default output is prettified and highlighted XML.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	42
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	43 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	44 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	45
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	46 Retrieve the last 5 notes from our custom notes node::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	47
3610 7c4fcef5b561 doc (cli/pubsub/get): fix option in example: Goffi <goffi@goffi.org> parents: 3563 diff changeset	48 $ li pubsub get -n notes -M 5
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	49
3563 267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	50 .. _li_pubsub_delete:
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	51
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	52 delete
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	53 ======
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	54
3611 ce864968fb23 doc (cli/pubsub/delete): update doc following notification option change Goffi <goffi@goffi.org> parents: 3610 diff changeset	55 Delete an item from a node. If ``--no-notification`` is specified, subscribers wont be notified
ce864968fb23 doc (cli/pubsub/delete): update doc following notification option change Goffi <goffi@goffi.org> parents: 3610 diff changeset	56 of the item retraction (this is NOT recommended, as it will cause trouble to keep items in
ce864968fb23 doc (cli/pubsub/delete): update doc following notification option change Goffi <goffi@goffi.org> parents: 3610 diff changeset	57 sync, take caution when using this flag).
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	58
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	59 By default a confirmation is requested before deletion is requested to the PubSub service,
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	60 but you can override this behaviour by using ``-f, --force`` option.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	61
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	62 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	63 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	64
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	65 Delete item with id ``123456`` from a node::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	66
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	67 $ li pubsub delete -n test_node -i 123456
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	68
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	69 edit
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	70 ====
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	71
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	72 Edit the raw XML of an item payload using your local editor (the one set in ``$EDITOR``).
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	73
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	74 If you don't change anything or publish an empty blog post, the edition will be cancelled.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	75
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	76 :ref:`draft_common` commands can be used.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	77
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	78 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	79 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	80
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	81 Edit the last note in our custom node::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	82
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	83 $ li pubsub edit -n notes -L
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	84
3563 267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	85 .. _li-pubsub_rename:
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	86
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	87 rename
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	88 ======
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	89
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	90 Move a item to a new ID. As there is currently no "rename" or "move" operation in XMPP
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	91 PubSub, this is done by republishing the item with the new ID, then deleting the old item
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	92 if the publication succeed.
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	93
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	94 This is notably useful when user friendly URL based on ID are used, and one need to fix a
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	95 typo or something else.
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	96
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	97 example
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	98 -------
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	99
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	100 Rename a PubSub item with ID ``123`` to ``456``::
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	101
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	102 $ li pubsub rename -n some_node -i 123 456
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	103
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	104 subscribe
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	105 =========
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	106
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	107 Subscribe to a node.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	108
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	109 Subscription is used to get notifications from the node in case of new/updated item or
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	110 deletion.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	111
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	112 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	113 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	114
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	115 Subscribe to an information blog::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	116
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	117 $ li pubsub subscribe -n informations -s pubsub.example.net
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	118
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	119 unsubscribe
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	120 ===========
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	121
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	122 Unsubscribe from a node.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	123
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	124 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	125 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	126
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	127 Unsubscribe from an information blog::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	128
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	129 $ li pubsub unsubscribe -n informations -s pubsub.example.net
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	130
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	131 subscriptions
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	132 =============
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	133
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	134 Retrieve subscriptions for all nodes on a service.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	135
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	136 ``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	137 it has subscription with multiple subIDs).
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	138
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	139 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	140 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	141
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	142 Retrieve all subscriptions on a pubsub service::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	143
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	144 $ li pubsub subscriptions -s pubsub@example.net
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	145
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	146 affiliations
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	147 =============
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	148
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	149 Retrieve affiliations for all nodes at a service.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	150
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	151 ``-n NODE, --node NODE`` can be used to request affiliation for a specific node.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	152
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	153 examples
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	154 --------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	155
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	156 Retrieve all affiliations at a pubsub service::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	157
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	158 $ li pubsub affiliations -s pubsub@example.net
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	159
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	160 Retrieve affiliation for the ``notes`` node::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	161
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	162 $ li pubsub affiliations -s pubsub@example.net -n notes
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	163
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	164 search
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	165 ======
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	166
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	167 Search items corresponding to one or more filter(s).
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	168
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	169 ``search`` will check all items (or some of them according to options used) from one or
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	170 several nodes (several nodes can be checked if recursion is used, see below). For each
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	171 item the given filters will be checked, and all corresponding items will be returned.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	172
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	173 This is a resource intensive method (both for server and client), use with caution, and
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	174 use MAM to do searching when suitable.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	175
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	176 filters
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	177 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	178
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	179 To do a search you one or more filters. Filters are checked in the order in which they are
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	180 specified. You can use 4 kinds of filters:
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	181
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	182 ``-t TEXT, --text TEXT``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	183 do a full-text search. If TEXT is appearing anywhere in the item (including in XML
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	184 tags or arguments), the item is selected
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	185
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	186 ``-r EXPRESSION, --regex EXPRESSION``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	187 do a regular expression search. `Python standard re module`_ is used internally, so you
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	188 can use its syntax.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	189
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	190 ``-x XPATH, --xpath XPATH``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	191 use an `XPath version 1.0`_ expression to filter the query. You can have a look at
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	192 `Wikipedia XPath page`_ for a user friendly introduction.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	193
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	194 ``-P PYTHON_CODE, --python PYTHON_CODE``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	195 use a Python expression to do a test. The expression must return a boolean (``True`` to
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	196 keep item, ``False`` otherwise). From within the Python expression 3 variables are
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	197 defined: ``item`` which contain the raw item as a string, and ``item_xml`` which is the
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	198 parsed XML as an lxml ``etree.Element`` and ``etree`` which is the ``lxml.etree`` module.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	199
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	200 .. _Python standard re module: https://docs.python.org/3.7/library/re.html
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	201 .. _XPath version 1.0: https://www.w3.org/TR/1999/REC-xpath-19991116/
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	202 .. _Wikipedia XPath page: https://en.wikipedia.org/wiki/XPath
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	203
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	204 filter modifiers
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	205 ----------------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	206
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	207 Before each filter you can specify one or more filter modifiers. A modifier will change
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	208 filter behaviour, it's a flag which can be used either without argument (then it will
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	209 activate the flag), or with an explicit boolean value (i.e. ``true`` or ``false``).
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	210
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	211 The available filters are:
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	212
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	213 ``-C [BOOLEAN], --ignore-case [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	214 (don't) ignore case. Filters are normally case sensitive, this modifier change this
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	215 behaviour.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	216
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	217 ``-I [BOOLEAN], --invert [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	218 (don't) invert effect of following filters. This is applying a logical ``NOT`` to the
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	219 filter. This means that instead of keeping item matching the filter, it will keep the
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	220 items which are not matching the filter.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	221
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	222 ``-A [BOOLEAN], --dot-all [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	223 (don't) use `DOTALL`_ option for regex. This filter only makes sense before a
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	224 ``--regex`` expression.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	225
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	226 ``-k [BOOLEAN], --only-matching [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	227 (don't) keep only the matching part of the item. Normally the whole item is returned,
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	228 with this flag, only the part matching the filters are kept.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	229
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	230 .. _DOTALL: https://docs.python.org/3.7/library/re.html#re.DOTALL
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	231
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	232 actions
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	233 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	234
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	235 Once filters are set, you may indicate what do to with the found items. By default they
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	236 are printed, but you can also use an other li command, or even an external tool.
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	237
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	238 The following actions are available:
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	239
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	240 ``print`` (default)
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	241 pretty print the found items.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	242
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	243 ``exec``
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	244 use the given li command on each found item. Everything after the ``exec`` is used to
c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	245 indicate the command and arguments to use (you must not specify ``li``, use the command
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	246 directly). The service, node and item will be set to match the found item.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	247
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	248 ``external``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	249 pipe the raw XML of each item to the given command. Everything after the ``external``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	250 action is used to indicate the command and arguments to use.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	251
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	252 recursive search
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	253 ----------------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	254
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	255 By default, only items in the given node will be filtered, but if you specify a recursion
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	256 depth > 0 (using ``-D MAX_DEPTH, --max-depth MAX_DEPTH``), every node linked in item will
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	257 be checked too, then node linked in linked item and so on until depth level is reached.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	258
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	259 For instance, if you want to find all comments of a blog node containing an http(s) link,
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	260 you can do that::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	261
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	262 $ li pubsub search -n urn:xmpp:microblog:0 -s user@example.net -D 1 -r 'https?://'
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	263
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	264 examples
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	265 --------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	266
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	267 Finding all items containing the text "something interesting" in personal blog::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	268
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	269 $ li pubsub search -n urn:xmpp:microblog:0 -M -1 -t "something interesting"
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	270
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	271 Find which blog items in the last 20 have a body with less than 200 characters (note that
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	272 body can be either ``<title>`` or ``<content>``, see `XEP-0277`_ for details). Here we use
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	273 a python expression on the text of the body to count the number of characters::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	274
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	275 $ li pubsub search -n urn:xmpp:microblog:0 -M 20 --python "len((item_xml.find('.//{http://www.w3.org/2005/Atom}content[@type=\"text\"]') or item_xml.find('.//{http://www.w3.org/2005/Atom}title[@type=\"text\"]')).text) < 200"
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	276
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	277 Find items published by ``toto@example.net`` among last 30 on a blog node, and use
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	278 ``pubsub blog`` command to retrieve id and title. We use ``-N`` to specify the ``pubsub``
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	279 namespace which is used in the XPath expression, then we use ``exec`` to run ``blog get -k
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	280 title -k id`` on found items::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	281
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	282 $ li pubsub search -n some_blog_node -s pubsub.example.net -M 30 -N pubsub http://jabber.org/protocol/pubsub -x '/pubsub:item[starts-with(@publisher, "toto@example.net")]' exec blog get -k title -k id
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	283
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	284 Find items which have NOT a title among last 30 items in our personal blog. As
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	285 explained in `XEP-0277`_ Atom's ``<title>`` is always used (even if there is only a body
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	286 and no title), so we actually look for items without ``<content>``. We do that with an
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	287 XPath looking for this ``atom:content`` element, then we use the ``-I [BOOLEAN], --invert
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	288 [BOOLEAN]`` to filter out elements which match.::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	289
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	290 $ li pubsub search -n urn:xmpp:microblog:0 -M 30 -I -x //atom:content -N atom http://www.w3.org/2005/Atom
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	291
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	292 Display authors names from last 10 items and their comments, using the ``-k [BOOLEAN],
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	293 --only-matching [BOOLEAN]`` modifier to only display the data we need. We use ``-D 1`` to
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	294 do a recursive search of level 1, which will also look into comments nodes (using last 10
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	295 items there too)::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	296
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	297 $ li pubsub search -n urn:xmpp:microblog:0 -M 10 --only-matching -x //atom:author/atom:name -N atom http://www.w3.org/2005/Atom -D 1
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	298
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	299 .. _XEP-0277: https://xmpp.org/extensions/xep-0277.html
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	300
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	301 transform
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	302 =========
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	303
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	304 Modify items using an external command.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	305
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	306 ``transform`` will retrieve requested items, and will send each of them to the standard
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	307 input (stdin) of the specified command. The output of the command will be used, it can be
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	308 3 things:
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	309
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	310 - a raw XML of the modified item, in which case the item will be republished
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	311 - the string ``SKIP``, in which case the item will be ignored
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	312 - the string ``DELETE``, in which case the item will be retracted
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	313
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	314 By default a dry run is done, which means that no item is modified or deleted. To actually
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	315 do the transformation, you have to use ``--apply`` argument.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	316
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	317 If you have to modify the ``publisher`` of an item, you need specific privileges. The
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	318 ``--admin`` allows you do to that, but it must be supported by your PubSub service
3563 267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands Goffi <goffi@goffi.org> parents: 3505 diff changeset	319 (currently only ``Libervia PubSub`` supports this non standard feature).
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	320
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	321 To modify all items of a node, use the ``-A, --all`` option. This will use `RSM`_
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	322 repetitively until all items are treated. Of course that means that your PubSub service
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	323 must support RSM. The items being republished, they will reappear on top of your node,
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	324 that's why it is recommended to use ``--order-by creation`` option when supported by the
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	325 service, to keep consistent order and avoid transforming the same items several times.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	326
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	327 If the command you're using exit with a non zero code, the process will stop. Use ``-I,
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	328 --ignore_errors`` if you want to continue transformation even if an non zero code is
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	329 returned.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	330
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	331 .. _RSM: https://xmpp.org/extensions/xep-0059.html
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	332
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	333 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	334 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	335
3612 21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	336 Imagine that you want to replace all occurrences of "SàT" by "Libervia" in your personal blog. You first create a Python script like this:
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	337
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	338 .. sourcecode:: python
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	339
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	340 #!/usr/bin/env python3
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	341
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	342 import sys
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	343 item_raw = sys.stdin.read()
3612 21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	344 if not "SàT" in item_raw:
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	345 print("SKIP")
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	346 else:
3612 21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	347 print(item_raw.replace("SàT", "Libervia"))
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	348
3632 7acf19bdca2f doc: minor typo Goffi <goffi@goffi.org> parents: 3563 diff changeset	349 And save it a some location, e.g. ``~/expand_sat.py`` (don't forget to make it executable
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	350 with ``chmod +x ~/expand_sat.py``).
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	351
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	352 To be sure it's safe, you can first do a dry-run and check the result::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	353
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	354 $ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/expand_sat.py
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	355
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	356 Once you have checked that you have the expected behaviour, you can apply the
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	357 transformations::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	358
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	359 $ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/expand_sat.py
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	360
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	361 And that's it. You can use the same technique for more complex transformations, including
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	362 modifying the XML (with Python, you can easily do that with standard
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	363 ``xml.etree.ElementTree`` module or with ``lxml.etree``).
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	364
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	365 uri
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	366 ===
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	367
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	368 Build an XMPP URI linking to a PubSub node or item.
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	369
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	370 example
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	371 -------
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	372
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	373 Build a link to personal blog::
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	374
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	375 $ li pubsub uri -n urn:xmpp:microblog:0
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	376
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	377 node
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	378 ====
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	379
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	380 Subcommands for node management. Please check :ref:`libervia-cli_pubsub_node`.
3041 72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	381
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	382 hook
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	383 ====
72583524cfd3 doc (jp): jp commands are now fully documented: Goffi <goffi@goffi.org> parents: diff changeset	384
3488 c80a0f864b5d doc: updated doc following global renaming Goffi <goffi@goffi.org> parents: 3100 diff changeset	385 Subcommands for hooks management. Please check :ref:`libervia-cli_pubsub_hook`.
3612 21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	386
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	387 cache
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	388 =====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	389
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands Goffi <goffi@goffi.org> parents: 3611 diff changeset	390 Subcommands for cache management. Please check :ref:`libervia-cli_pubsub_cache`.

Mercurial > libervia-backend

annotate doc/libervia-cli/pubsub.rst @ 3682:7c990aaa49d3