Mercurial > libervia-backend

annotate doc/libervia-cli/pubsub.rst @ 4309:b56b1eae7994

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
component email gateway: add multicasting: XEP-0033 multicasting is now supported both for incoming and outgoing messages. XEP-0033 metadata are converted to suitable Email headers and vice versa. Email address and JID are both supported, and delivery is done by the gateway when suitable on incoming messages. rel 450
author Goffi <goffi@goffi.org>
date Thu, 26 Sep 2024 16:12:01 +0200
parents c4418949aa37
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
3951
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
27 |e2e_arg|
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
28
3975
c4418949aa37 doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents: 3966
diff changeset
29 |pte_arg|
c4418949aa37 doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents: 3966
diff changeset
30
3966
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
31 |sign_arg|
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
32
3100
cea52c9ddfd9 plugin XEP-0060, jp (pubsub/set): publish-options implementation:
Goffi <goffi@goffi.org>
parents: 3041
diff changeset
33 .. _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
34
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
36 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
37
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
38 Create an item with a custom note XML::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
40 $ 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
41
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
42 .. _li_pubsub_get:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
43
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 get
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 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
48
3951
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
49 If the node is end-to-end encrypted, items will be automatically and transparently
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
50 decrypted if the shared secrets are known. If you want to avoid this behaviour and get the
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
51 items undecrypted, you can use the ``--no-decrypt`` flag.
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
52
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
54 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
55
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 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
57
3610
7c4fcef5b561 doc (cli/pubsub/get): fix option in example:
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
58 $ li pubsub get -n notes -M 5
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
59
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
60 .. _li_pubsub_delete:
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
61
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
62 delete
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
3611
ce864968fb23 doc (cli/pubsub/delete): update doc following notification option change
Goffi <goffi@goffi.org>
parents: 3610
diff changeset
65 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
66 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
67 sync, take caution when using this flag).
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 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
70 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
71
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
72 example
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
75 Delete item with id ``123456`` from a node::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
76
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
77 $ 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
78
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 edit
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
82 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
83
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 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
85
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 :ref:`draft_common` commands can be used.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
3951
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
88 |e2e_arg|
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
89
3975
c4418949aa37 doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents: 3966
diff changeset
90 |pte_arg|
c4418949aa37 doc (encryption, cli): document Pubsub Targeted Encryption:
Goffi <goffi@goffi.org>
parents: 3966
diff changeset
91
3966
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
92 |sign_arg|
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
93
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
94 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
95 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
96
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 Edit the last note in our custom node::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
98
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
99 $ li pubsub edit -n notes -L
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
100
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
101 .. _li-pubsub_rename:
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
102
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
103 rename
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
104 ======
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
105
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
106 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
107 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
108 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
109
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
110 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
111 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
112
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
113 example
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
114 -------
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
115
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
116 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
117
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3505
diff changeset
118 $ 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
119
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 subscribe
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 Subscribe to a node.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
124
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
125 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
126 deletion.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
127
3771
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
128 If ``--public`` is used, the subscription will be made visible to anybody. For this to
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
129 work, the target pubsub/PEP service must implement `XEP-0465 Public Pubsub
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
130 Subscriptions`_. If your own server also implements XEP-0495 (and thus `XEP-0376 Pubsub
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
131 Account Management`_ wich is a dependency), your subscription will also be visible to
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
132 people requesting pubsub public subscriptions from your account.
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
133
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
134 .. note::
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
135
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
136 Making a subscription public is interesting to show your center of interests and to let
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
137 other people discover people that you are subscribed to or who are subscribed to you
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
138 (this correspond the the "following" and "followers" feature that is seen on some
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
139 software).
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
140
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
141 However, it also makes your subscription visible to evil entities such as
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
142 spammer, bot collectings informations for e.g. marketing or surveillance. In some
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
143 locations, it may even be life threating as unwisely making public subscription may
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
144 show your political views, sexual orientation, religion, etc.
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
145
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
146 Furthermore, if you make public subscriptions, your JID may be retrieved easily (public
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
147 subscriptions can be checked to see if a JID exists and is used, or your JID can be
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
148 simply found from subscribed node, or from your subscribers). This is often desirable
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
149 in the case of social interactions, but this is to be known if you're willing to keep
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
150 your identifier secret (in this case, don't use public subscriptions).
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
151
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
152
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
153 example
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 Subscribe to an information blog::
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 subscribe -n informations -s pubsub.example.net
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
159
3771
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
160 Pierre wants to subscribe to Louise blog, and to make it public, so other people can
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
161 discover it::
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
162
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
163 $ li pubsub subscribe -n urn:xmpp:microblog:0 -s louise@example.org --public
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
164
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
165 unsubscribe
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
168 Unsubscribe from a node.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
169
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
170 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
171 -------
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 Unsubscribe from an information blog::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
174
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
175 $ 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
176
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
177 subscriptions
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
3771
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
180 Retrieve subscriptions from a user, or subscriptions for all nodes on a service.
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
181
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
182 If no service and no node are specified, and if your server supports `XEP-0376 Pubsub
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
183 Account Management`_, all subscriptions to any server or node of the profile are returned.
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
184
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
185 ``-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
186 it has subscription with multiple subIDs).
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
187
3771
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
188 If ``--public`` is used, only public subscriptions are retrieved. This can be used to find
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
189 public subscriptions from an external user. The PEP/Pubsub service of the target entity
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
190 must implement `XEP-0465 Public Pubsub Subscriptions`_.
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
191
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
192 .. _XEP-0376 Pubsub Account Management: https://xmpp.org/extensions/xep-0376.html
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
193 .. _XEP-0465 Public Pubsub Subscriptions: https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
194
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
195
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
196 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
197 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
198
3771
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
199 Pierre server supports XEP-0465. To check all the node where he has a subscription, Pierre
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
200 can use this command::
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
201
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
202 $ li pubsub subscriptions
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
203
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
204 Retrieve all subscriptions on a specific pubsub service::
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
205
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
206 $ li pubsub subscriptions -s pubsub@example.net
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
207
3771
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
208 Louise wants to checks to which node Pierre is publicly subscribed. She do it with
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
209 following command::
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
210
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
211 $ li pubsub subscriptions --public -s pierre@example.net
e597dbfbc4c6 doc (cli/pubsub): document new `--public` flags:
Goffi <goffi@goffi.org>
parents: 3635
diff changeset
212
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
213 affiliations
3836
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
214 ============
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
215
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
216 Retrieve affiliations for all nodes at a service.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
217
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
218 ``-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
219
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
220 examples
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
223 Retrieve all affiliations at a pubsub service::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
224
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
225 $ li pubsub affiliations -s pubsub@example.net
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
226
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
227 Retrieve affiliation for the ``notes`` node::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
228
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
229 $ 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
230
3836
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
231 reference
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
232 =========
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
233
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
234 Send a reference (e.g. a mention) of a pubsub item to an entity.
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
235
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
236 example
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
237 -------
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
238
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
239 Pierre send a reference to Louise to indicate that she has been mentioned in his blog post
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
240 with ID ``from-paris-to-noumea-abcd``::
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
241
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
242 $ li pubsub reference -s pierre@example.net -n urn:xmpp:microblog:0 -i from-paris-to-noumea-abcd louise@example.org
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
243
e183f1fbfa8d doc (cli/pubsub): add doc for ``reference`` subcommand:
Goffi <goffi@goffi.org>
parents: 3771
diff changeset
244
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
245 search
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
246 ======
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 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
249
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
250 ``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
251 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
252 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
253
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
254 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
255 use MAM to do searching when suitable.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
256
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
257 filters
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
260 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
261 specified. You can use 4 kinds of filters:
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
262
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
263 ``-t TEXT, --text TEXT``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
264 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
265 tags or arguments), the item is selected
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 ``-r EXPRESSION, --regex EXPRESSION``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
268 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
269 can use its syntax.
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 ``-x XPATH, --xpath XPATH``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
272 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
273 `Wikipedia XPath page`_ for a user friendly introduction.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
274
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
275 ``-P PYTHON_CODE, --python PYTHON_CODE``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
276 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
277 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
278 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
279 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
280
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
281 .. _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
282 .. _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
283 .. _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
284
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
285 filter modifiers
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
286 ----------------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
287
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
288 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
289 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
290 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
291
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
292 The available filters are:
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
293
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
294 ``-C [BOOLEAN], --ignore-case [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
295 (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
296 behaviour.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
297
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
298 ``-I [BOOLEAN], --invert [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
299 (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
300 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
301 items which are **not** matching the filter.
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 ``-A [BOOLEAN], --dot-all [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
304 (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
305 ``--regex`` expression.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
306
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
307 ``-k [BOOLEAN], --only-matching [BOOLEAN]``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
308 (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
309 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
310
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
311 .. _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
312
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
313 actions
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
314 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
315
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
316 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
317 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
318
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
319 The following actions are available:
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 ``print`` (default)
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
322 pretty print the found items.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
323
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
324 ``exec``
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
325 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
326 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
327 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
328
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
329 ``external``
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
330 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
331 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
332
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
333 recursive search
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
336 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
337 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
338 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
339
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
340 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
341 you can do that::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
342
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
343 $ 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
344
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
345 examples
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
346 --------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
347
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
348 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
349
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
350 $ 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
351
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
352 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
353 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
354 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
355
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
356 $ 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
357
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
358 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
359 ``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
360 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
361 title -k id`` on found items::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
362
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
363 $ 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
364
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
365 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
366 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
367 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
368 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
369 [BOOLEAN]`` to filter out elements which match.::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
370
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
371 $ 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
372
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
373 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
374 --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
375 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
376 items there too)::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
377
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
378 $ 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
379
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
380 .. _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
381
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
382 transform
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
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
385 Modify items using an external command.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
386
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
387 ``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
388 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
389 3 things:
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
390
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
391 - 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
392 - 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
393 - 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
394
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
395 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
396 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
397
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
398 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
399 ``--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
400 (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
401
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
402 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
403 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
404 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
405 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
406 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
407
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
408 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
409 --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
410 returned.
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
411
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
412 .. _RSM: https://xmpp.org/extensions/xep-0059.html
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
413
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
414 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
415 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
416
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
417 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
418
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
419 .. sourcecode:: python
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
420
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
421 #!/usr/bin/env python3
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
422
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
423 import sys
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
424 item_raw = sys.stdin.read()
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
425 if not "SàT" in item_raw:
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
426 print("SKIP")
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
427 else:
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
428 print(item_raw.replace("SàT", "Libervia"))
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
429
3632
7acf19bdca2f doc: minor typo
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
430 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
431 with ``chmod +x ~/expand_sat.py``).
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
432
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
433 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
434
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
435 $ 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
436
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
437 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
438 transformations::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
439
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
440 $ 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
441
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
442 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
443 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
444 ``xml.etree.ElementTree`` module or with ``lxml.etree``).
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
445
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
446 uri
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
447 ===
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
448
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
449 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
450
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
451 example
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
452 -------
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
453
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
454 Build a link to personal blog::
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
455
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
456 $ 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
457
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
458 node
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
459 ====
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
460
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
461 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
462
3873
8b76caa89aa0 doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:
Goffi <goffi@goffi.org>
parents: 3836
diff changeset
463 attachments
8b76caa89aa0 doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:
Goffi <goffi@goffi.org>
parents: 3836
diff changeset
464 ===========
8b76caa89aa0 doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:
Goffi <goffi@goffi.org>
parents: 3836
diff changeset
465
8b76caa89aa0 doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:
Goffi <goffi@goffi.org>
parents: 3836
diff changeset
466 Subcommands to add or remove data attached to pubsub items. Please check
8b76caa89aa0 doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:
Goffi <goffi@goffi.org>
parents: 3836
diff changeset
467 :ref:`libervia-cli_pubsub_attachments`.
8b76caa89aa0 doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:
Goffi <goffi@goffi.org>
parents: 3836
diff changeset
468
3966
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
469 signature
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
470 =========
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
471
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
472 Subcommands to handle items signature. Please check :ref:`libervia-cli_pubsub_signature`.
9f85369294f3 doc (encryption, cli): pubsub signing documentation:
Goffi <goffi@goffi.org>
parents: 3951
diff changeset
473
3951
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
474 secret
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
475 ======
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
476
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
477 Subcommands for pubsub node shared secrets management. Please check :ref:`libervia-cli_pubsub_secret`.
4b8776eb6826 doc (blog, pubsub): documentation on new e2ee arguments for pubsub, and shared secrets handling:
Goffi <goffi@goffi.org>
parents: 3873
diff changeset
478
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
479 hook
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
480 ====
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff changeset
481
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3100
diff changeset
482 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
483
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
484 cache
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
485 =====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
486
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents: 3611
diff changeset
487 Subcommands for cache management. Please check :ref:`libervia-cli_pubsub_cache`.