Mercurial > libervia-backend
annotate doc/libervia-cli/pubsub.rst @ 3743:54c249ec35ce
core (memory/migration): ignore FTS table when autogenerating script for migration:
SQLite Full-Text Search stable are not associated to Python object and can't be detected
by Alembic. To avoid the generation of unwanted drop commands, they are now ignored when
autogenerating migration scripts.
rel 364
author | Goffi <goffi@goffi.org> |
---|---|
date | Tue, 22 Mar 2022 17:00:42 +0100 |
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 | 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`. |