From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 236A84401C; Mon, 13 May 2024 18:01:56 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C209740A6F; Mon, 13 May 2024 18:01:39 +0200 (CEST) Received: from mail-pf1-f177.google.com (mail-pf1-f177.google.com [209.85.210.177]) by mails.dpdk.org (Postfix) with ESMTP id 2E9FC4068A for ; Mon, 13 May 2024 17:59:34 +0200 (CEST) Received: by mail-pf1-f177.google.com with SMTP id d2e1a72fcca58-6f44b390d5fso3875009b3a.3 for ; Mon, 13 May 2024 08:59:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1715615973; x=1716220773; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=52vRRnKzaU4qoo4ra4R6E1KzbeNonGh6OU//roUYvcQ=; b=KmNyVDVGtrp9gCWsjQ1UcV04LN79p2ac5x23g43nDvchsXa0AplNRlPcgg3Wz+YiHl 5BlUSvkswH0p5/LhgJ/oNvqhw1AYuJbj81pfRA5kDU0BrK8jrs+2MR46tQjGhd9g58j0 IG/6qoGE+17DUjrmRqP8fP/4TQKuKIwvWQAWaJlL+IVQB6WGpiV7482WX9y+ojIfuh79 6ozdcKONLwFxKBxpPCJIMGxl+tn5fzPJ1nZ6uFIuAq/n2z/CUfZKKVref5Qenb0Z5vqA 7uH8oSaBfPPgqi/3mbXgwslGWyQ+vC6/99exv+R8s3o0vTd7PMiOWaBKF+UWUWlHfR+Z 8e6Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1715615973; x=1716220773; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=52vRRnKzaU4qoo4ra4R6E1KzbeNonGh6OU//roUYvcQ=; b=b7/4CW6Ihno4WBiVuLennvwmISUm9j1PZvQg8OYMgHNy7TnNO5XlGZi79eBkZDwuJq L95A4BG5pXoNIkFi75saY9tzXD2kNPaXXv/TOqGwizaVBHRHfiNkl6rPlTRDgsYcWv3D z/B5YoXWB+WziLAGbNnjJQWuVFeFihIZZQgtYqBVqEYKl3Ipvy0wb5vvVBc+D3BP50uc gEmPBIKwHEdR5WAnG8OnLdfF7vBGpYhnxAb5hvInN1u+suSrG8qxbrO8YabcJhBYUBo6 /DPTkttype8qB4HD8ER5s1dvRLd3T078CJzfEdR/FzjSCSXZZTV3eJUgnvrFNnJGVv9D mW0w== X-Gm-Message-State: AOJu0Ywg45xP5zThDIa9PDpgsskLetm4XTx2skgXHcDhScY3EVSYcHTf PL4agLWU0xnAOcdv+CQxoyJXBdiEisp12Z5DW7jG1nBJmqj1DzLQUdiXOw== X-Google-Smtp-Source: AGHT+IEHGQeBqFLdyHY5IlB3UJdiT+LPABFyMtP9dMvAjfQIW8WFTt9xIJRvELanwQcF2ue6CJ3cUQ== X-Received: by 2002:a05:6a00:10c9:b0:6f3:f447:5861 with SMTP id d2e1a72fcca58-6f4e026b8f2mr11793875b3a.5.1715615972876; Mon, 13 May 2024 08:59:32 -0700 (PDT) Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com. [76.32.89.124]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-6f4d2aa16dfsm7715078b3a.93.2024.05.13.08.59.32 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 May 2024 08:59:32 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH 3/9] doc: reword argparse section in prog guide Date: Mon, 13 May 2024 08:59:05 -0700 Message-Id: <20240513155911.31872-4-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240513155911.31872-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Mailman-Approved-At: Mon, 13 May 2024 18:01:34 +0200 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org made small edits to sections 6.1 and 6.2 intro Signed-off-by: Nandini Persad --- doc/guides/prog_guide/argparse_lib.rst | 72 +++++++++++++------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/doc/guides/prog_guide/argparse_lib.rst b/doc/guides/prog_guide/argparse_lib.rst index a6ac11b1c0..a2af7d49e9 100644 --- a/doc/guides/prog_guide/argparse_lib.rst +++ b/doc/guides/prog_guide/argparse_lib.rst @@ -4,22 +4,21 @@ Argparse Library ================ -The argparse library provides argument parsing functionality, -this library makes it easy to write user-friendly command-line program. +The argparse library provides argument parsing functionality and makes it easy to write user-friendly command-line programming. Features and Capabilities ------------------------- -- Support parsing optional argument (which could take with no-value, - required-value and optional-value). +- Supports parsing of optional arguments (which can contain no-value, + required-value and optional-values). -- Support parsing positional argument (which must take with required-value). +- Supports parsing of positional arguments (which must contain required-values). -- Support automatic generate usage information. +- Supports automatic generation of usage information. -- Support issue errors when provide with invalid arguments. +- Provides issue errors when an argument is invalid -- Support parsing argument by two ways: +- Supports parsing arguments in two ways: #. autosave: used for parsing known value types; #. callback: will invoke user callback to parse. @@ -27,7 +26,7 @@ Features and Capabilities Usage Guide ----------- -The following code demonstrates how to use: +The following code demonstrates how to use the following: .. code-block:: C @@ -89,12 +88,12 @@ The following code demonstrates how to use: ... } -In this example, the arguments which start with a hyphen (-) are optional -arguments (they're "--aaa"/"--bbb"/"--ccc"/"--ddd"/"--eee"/"--fff"); and the -arguments which don't start with a hyphen (-) are positional arguments -(they're "ooo"/"ppp"). +In this example, the arguments thhat start with a hyphen (-) are optional +arguments ("--aaa"/"--bbb"/"--ccc"/"--ddd"/"--eee"/"--fff"). +The arguments that do not start with a hyphen (-) are positional arguments +("ooo"/"ppp"). -Every argument must be set whether to carry a value (one of +Every argument must set whether it carries a value (one of ``RTE_ARGPARSE_ARG_NO_VALUE``, ``RTE_ARGPARSE_ARG_REQUIRED_VALUE`` and ``RTE_ARGPARSE_ARG_OPTIONAL_VALUE``). @@ -105,26 +104,26 @@ Every argument must be set whether to carry a value (one of User Input Requirements ~~~~~~~~~~~~~~~~~~~~~~~ -For optional arguments which take no-value, +For optional arguments which have no-value, the following mode is supported (take above "--aaa" as an example): - The single mode: "--aaa" or "-a". -For optional arguments which take required-value, +For optional arguments which have required-value, the following two modes are supported (take above "--bbb" as an example): - The kv mode: "--bbb=1234" or "-b=1234". - The split mode: "--bbb 1234" or "-b 1234". -For optional arguments which take optional-value, +For optional arguments which have optional-value, the following two modes are supported (take above "--ccc" as an example): - The single mode: "--ccc" or "-c". - The kv mode: "--ccc=123" or "-c=123". -For positional arguments which must take required-value, +For positional arguments which must have required-value, their values are parsing in the order defined. .. note:: @@ -132,15 +131,15 @@ their values are parsing in the order defined. The compact mode is not supported. Take above "-a" and "-d" as an example, don't support "-ad" input. -Parsing by autosave way +Parsing the Autosave Method ~~~~~~~~~~~~~~~~~~~~~~~ -Argument of known value type (e.g. ``RTE_ARGPARSE_ARG_VALUE_INT``) -could be parsed using this autosave way, -and its result will save in the ``val_saver`` field. +Arguments of a known value type (e.g. ``RTE_ARGPARSE_ARG_VALUE_INT``) +can be parsed using the autosave method, +The result will save in the ``val_saver`` field. In the above example, the arguments "--aaa"/"--bbb"/"--ccc" and "ooo" -both use this way, the parsing is as follows: +both use this method. The parsing is as follows: - For argument "--aaa", it is configured as no-value, so the ``aaa_val`` will be set to ``val_set`` field @@ -150,28 +149,27 @@ both use this way, the parsing is as follows: so the ``bbb_val`` will be set to user input's value (e.g. will be set to 1234 with input "--bbb 1234"). -- For argument "--ccc", it is configured as optional-value, - if user only input "--ccc" then the ``ccc_val`` will be set to ``val_set`` field +- For argument "--ccc", it is configured as optional-value. + If user only input "--ccc", then the ``ccc_val`` will be set to ``val_set`` field which is 200 in the above example; - if user input "--ccc=123", then the ``ccc_val`` will be set to 123. + If user input "--ccc=123", then the ``ccc_val`` will be set to 123. - For argument "ooo", it is positional argument, the ``ooo_val`` will be set to user input's value. -Parsing by callback way -~~~~~~~~~~~~~~~~~~~~~~~ - -It could also choose to use callback to parse, -just define a unique index for the argument -and make the ``val_save`` field to be NULL also zero value-type. +Parsing by Callback Method +~~~~~~~~~ +You may choose to use the callback method to parse. +To do so, define a unique index for the argument +and make the ``val_save`` field to be NULL as a zero value-type. -In the above example, the arguments "--ddd"/"--eee"/"--fff" and "ppp" both use this way. +In the above example, the arguments "--ddd"/"--eee"/"--fff" and "ppp" both use this method. -Multiple times argument +Multiple Times Argument ~~~~~~~~~~~~~~~~~~~~~~~ -If want to support the ability to enter the same argument multiple times, -then should mark ``RTE_ARGPARSE_ARG_SUPPORT_MULTI`` in the ``flags`` field. +If you want to support the ability to enter the same argument multiple times, +then you should mark ``RTE_ARGPARSE_ARG_SUPPORT_MULTI`` in the ``flags`` field. For example: .. code-block:: C @@ -182,5 +180,5 @@ Then the user input could contain multiple "--xyz" arguments. .. note:: - The multiple times argument only support with optional argument + The multiple times argument is only supported with optional argument and must be parsed by callback way. -- 2.34.1