Mercurial > libervia-backend
annotate doc/jp/common_arguments.rst @ 3350:cc6164a4973b
plugin list of interests: normalize item ID + added `get` method
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Sat, 05 Sep 2020 20:22:23 +0200 |
| parents | d2a26ec74b31 |
| children |
| rev | line source |
|---|---|
| 2946 | 1 ================ |
| 2 common arguments | |
| 3 ================ | |
| 4 | |
| 5 Some arguments are used in many commands. This page describe them. | |
| 6 | |
|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
7 .. _jp-common_profile: |
|
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
8 |
| 2946 | 9 profile |
| 10 ======= | |
| 11 | |
| 12 profile arguments are really common, they allow you to select your profile. | |
| 13 If you don't select any, the default profile is used, which is the first | |
| 14 profile created or the one you have explicitly set. You can check which profile | |
| 15 is used by default with ``jp profile default``. | |
| 16 | |
| 17 The common arguments for profile are: | |
| 18 | |
| 19 ``-p PROFILE, --profile PROFILE`` | |
| 20 to select the name of your profile. It can be a profile key like ``@DEFAULT@`` | |
| 21 | |
| 22 ``-c, --connect`` | |
| 23 connect the profile to the XMPP server before doing anything else. If your | |
| 24 profile is already connected, nothing happen. This is specially useful in scripts. | |
| 25 | |
| 26 ``--start-session`` | |
| 27 starts a session without connecting, this can be needed if you can't connect but | |
| 28 you need to access your session e.g. to change parameters. | |
| 29 This is advanced used and is not need in most common cases. | |
| 30 | |
| 31 ``--pwd PASSWORD`` | |
| 32 the password of your profile, needed if the session is not started yet. | |
| 33 | |
| 34 .. note:: | |
| 35 | |
|
3050
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
36 using the ``--pwd`` option is not secure if you are not the only user of your machine: |
|
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
37 the password will appear **IN CLEAR** in the list of launched processes, or in the |
|
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
38 history of your shell. If the profile password is needed and not specified, it will be |
|
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
39 prompted (with echo disabled). If you are on a shared machine or if anybody can access |
|
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
40 your shell history at some point, you should either connect first your profile with an |
|
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
41 other frontend (Primitivus for instance), or avoid the ``--pwd`` option and use the |
|
d2a26ec74b31
doc (jp/common_arguments): updated note about `--pwd`
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
42 prompt instead. |
| 2946 | 43 |
| 44 .. _pubsub_common: | |
| 45 | |
| 46 pubsub | |
| 47 ====== | |
| 48 | |
| 49 pubsub arguments are used in many commands, they allow you to select a service, node and | |
| 50 items. Depending on the command, you may only not be able to select an item, or you may | |
| 51 select one or multiple items. | |
| 52 | |
| 53 The common arguments for pubsub are: | |
| 54 | |
| 55 ``-u PUBSUB_URL, --pubsub-url PUBSUB_URL`` | |
| 56 retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an | |
| 57 ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to | |
| 58 retrieve the location of the XMPP node/item, if available. | |
| 59 Note that you can override parts of the location in the URL if you specify service, node | |
| 60 or item. | |
| 61 | |
| 62 e.g.:: | |
| 63 | |
| 64 $ jp blog get -u https://www.goffi.org | |
| 65 | |
| 66 ``-s SERVICE, --service`` | |
| 67 used to specifiy the JID of the pubsub service | |
| 68 | |
| 69 ``-n NODE, --node NODE`` | |
| 70 used to specifiy the pubsub node | |
| 71 | |
| 72 ``-i ITEM, --item ITEM`` | |
| 73 for commands where an item can be specified, you do it with this option. In some | |
| 74 commands, multiple items can be specified, in this case just use this arguments several | |
| 75 times. | |
| 76 | |
| 77 ``-L, --last-item`` | |
| 78 when an item id is needed, you can use this option to retrieve the last published item. | |
| 79 e.g.:: | |
| 80 | |
| 81 $ jp blog edit --last-item | |
| 82 | |
| 83 ``-M, --max-items`` | |
| 84 use to specify a maxium number of items to retrieve, when it makes sense. | |
| 85 Note that this is using the pubsub max (i.e. defined in | |
| 86 `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should | |
| 87 implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in | |
| 88 this case the ``-m, --max`` argument should be prefered. See below for RSM common | |
| 89 arguments. | |
| 90 | |
| 91 result set management | |
| 92 ===================== | |
| 93 | |
| 94 Result Set Management (RSM) common arguments are used to navigate into pages of results | |
| 95 when lot of elements may be expected. Given a result with a large number of arguments, a | |
| 96 *page* is set of elements which correspond to an *index* (a page number). For instance if | |
| 97 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to | |
| 98 20 included. | |
| 99 | |
| 100 | |
| 101 ``-a ITEM_ID, --after ITEM_ID`` | |
| 102 find page after this item. You usually use the last item id of the latest page you got. | |
| 103 | |
| 104 ``-b ITEM_ID, --before ITEM_ID`` | |
| 105 find page before this item. This this usually used when you check items backwards | |
| 106 | |
| 107 ``--index RSM_INDEX`` | |
| 108 index of the page to retrieve. Note that first page has index **0**. | |
| 109 | |
| 110 ``-m RSM_MAX, --max RSM_MAX`` | |
| 111 used to specify a maxium number of items to retrieve per page. Note that the actual | |
| 112 maximum number of items per page used may be lower if the service used consider that | |
| 113 your request is too big. | |
| 114 | |
| 115 message archive management | |
| 116 ========================== | |
| 117 | |
| 118 Message Archive Management (MAM) argument is used by some commands (related to instant message or | |
| 119 pubsub) to filter results. | |
| 120 | |
| 121 There is currently only one argument in this group: | |
| 122 | |
| 123 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE`` | |
| 124 specify a MAM filter to use. Depending on the service supporting MAM, some filters can | |
| 125 be used to do things like full text search. The available filters depend on the service | |
| 126 you use, please check documentation of your service. | |
| 127 | |
| 128 order-by | |
| 129 ======== | |
| 130 | |
| 2957 | 131 Order-By argument specify how the returned elements are sorted. |
| 2946 | 132 |
| 133 There is currently only one argument in this group: | |
| 134 | |
| 135 ``-o {creation,modification}, --order-by {creation,modification}`` | |
| 136 specify how result is sorted. with ``creation``, first created element is returned | |
| 137 first. There is no notion of *creation* of *modification* in original | |
| 138 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an | |
| 139 existing id will overwrite the older one, creating a new item. With this option, we use | |
| 140 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and | |
| 141 *creation* time is the time when the first item has been published, before being | |
| 142 overwritten. | |
| 143 | |
| 144 In the case of ``modification``, if an item is overwritten, it reappears on top, this is | |
| 145 the default pubsub sorting order. | |
| 146 | |
| 147 progress | |
| 148 ======== | |
| 149 | |
| 150 This single option may be used when a long operation is happening, like a file transfer. | |
| 151 | |
| 152 ``-P, --progress`` | |
| 153 Show progress bar. | |
| 154 | |
| 155 verbose | |
| 156 ======= | |
| 157 | |
| 158 ``--verbose, -v`` | |
| 159 Add a verbosity level (can be used multiple times). Use to have more concise output by | |
| 160 default when it makes sense. | |
| 161 | |
|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
162 .. _draft_common: |
|
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
163 |
| 2946 | 164 draft |
| 165 ===== | |
| 166 | |
| 167 Common arguments used when an edition is potentially long to do, and a file may be kept | |
| 168 until publication. | |
| 169 | |
| 170 | |
| 171 ``-D, --current`` | |
| 172 Used when you have started to edit something (e.g. a blog post), which is not yet | |
| 173 published, and you want to continue your work. | |
| 174 | |
| 175 e.g.:: | |
| 176 | |
| 177 $ jp blog edit -D | |
| 178 | |
| 179 ``-F DRAFT_PATH, --draft-path DRAFT_PATH`` | |
| 180 Used when you have started to edit something and want to continue your work from this | |
| 181 file. In other words, it's similar to ``-D, --current`` except that you specify the file | |
| 182 to use instead of using the last available draft. | |
| 183 | |
|
3021
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2957
diff
changeset
|
184 .. _jp-output: |
|
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2957
diff
changeset
|
185 |
| 2946 | 186 output |
| 187 ====== | |
| 188 | |
| 189 Output is used when you want to get the result of the command in a specific way. It may be | |
| 190 used, for instance, to retrieve the result formatted in JSON so the data can be easily | |
| 191 manipulated by a script, or if you want only a specific element of the result. | |
| 192 | |
| 193 ``-O {…}, --output {…}`` | |
| 194 specifiy the output to use. Available options depends of the command you are using, | |
| 195 check ``jp [your command] --help`` to know them. | |
| 196 | |
| 197 e.g.:: | |
| 198 | |
| 199 $ jp blog get -O json | |
| 200 | |
| 201 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS`` | |
| 202 depending of the output selected, you may have options to customise the output. | |
| 203 For instance, if you use the ``template`` output, you may use an option to display the | |
| 204 result in a browser. | |
| 205 | |
| 206 e.g.:: | |
| 207 | |
| 208 $ jp blog | |
| 209 | |
| 210 Some options expect parameters, in this case they can be specified using ``=``. | |
| 211 | |
| 212 e.g. specifiying a template to use:: | |
| 213 | |
| 214 $ jp blog get -O template --oo browser --oo template=/tmp/my_template.html |