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 88974454B2; Fri, 21 Jun 2024 04:33:22 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7D57942E7A; Fri, 21 Jun 2024 04:33:22 +0200 (CEST) Received: from mail-pf1-f182.google.com (mail-pf1-f182.google.com [209.85.210.182]) by mails.dpdk.org (Postfix) with ESMTP id 4A98F42E7A for ; Fri, 21 Jun 2024 04:33:20 +0200 (CEST) Received: by mail-pf1-f182.google.com with SMTP id d2e1a72fcca58-705bf368037so1394202b3a.0 for ; Thu, 20 Jun 2024 19:33:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718937199; x=1719541999; 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=hG5jPfxCs2cqf2u0yQ4c5/Wr1lNC/AZ4J8oIgNAwgow=; b=AAQMwy1T+tgKb063i2mwJ3qJhDyRATBM1kA0iKMT1cn/i7Ico3jPRYeuUw2pd0IAPe yooMMWQeMFNkDYnurs7lDwO3WUxYVbxHOrNDxQA/FZagGy5zk+36a+KPR/lqR2epeZ3a HEvY506tUO41BeFcjbWAjx0CyqyB9fYA079u02SRH7AOB+jxfvy4uQlYUPUDekGym/5O yHiKfaKQcm5/q0I+OdB1qTdY0UgGdz+YWxcnddx7VVaSmwUuM+ocOrNBZPKHrndUDv3d 16j8sJMNOgRqck4oAjCh1x/oR2adNchfb8U2c8ghXTbkZsHsdDwc2q6LInyHiCCf9wt1 wzgA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718937199; x=1719541999; 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=hG5jPfxCs2cqf2u0yQ4c5/Wr1lNC/AZ4J8oIgNAwgow=; b=seca2uyI6KxPJvGnGj4wekC6uhdPY99vAayN5u9G141lElI+91f57pMUilXUELp6vd gcBA4tlwiL0Xs6oIbzmpYEby6wiOEFZCS3fUzgNUmqKkAbheJLvLgTvfC6fBgZ+zobOA z5awfY+tuYygLpCsuZrwOQvUPNOE7kjyO087AUxrNnezmfCyc8EPFFk+6rRyNnonZ3vB Jga5or8OIrcaIKAD5ZOp1fZaowyaJB84X8vEN+fmiWY+gWhFK5aOR1h6Rh1b2UBiAKRB 4YuKFam5col9WF4dCtS6NsqUIvJRF5ZgfAore7ytPhl6R/IOTdiDDr+ZgJCHQZBR7T+I 9g4Q== X-Gm-Message-State: AOJu0YyzYMwYvjTGTXKecrlUjjcFfN4/J5I1vBXzsa39yr/Idic6Pshl bF7R4A7p9k0JCRk4e+1AETDiPd0z03xHI6rf9gx5y81y2vcPZ1GqyrEpK96d X-Google-Smtp-Source: AGHT+IHDQjv2lqMGwSwNgl4UW0Oy2YtpE2GLxnyqSg4ux4+ZgKvznx6ukeXylQFx9PRZkfvdXTNmVA== X-Received: by 2002:a05:6a00:a93:b0:705:c273:d19 with SMTP id d2e1a72fcca58-70629c43067mr9174173b3a.12.1718937198980; Thu, 20 Jun 2024 19:33:18 -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-7065124df73sm334482b3a.110.2024.06.20.19.33.18 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 20 Jun 2024 19:33:18 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Subject: [PATCH v2 2/9] doc: reword argparse section in prog guide Date: Thu, 20 Jun 2024 19:32:47 -0700 Message-Id: <20240621023254.4258-2-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com> References: <20240513155911.31872-1-nandinipersad361@gmail.com> <20240621023254.4258-1-nandinipersad361@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 I have made small edits for syntax in this section. Signed-off-by: Nandini Persad --- doc/guides/prog_guide/argparse_lib.rst | 75 +++++++++++++------------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/doc/guides/prog_guide/argparse_lib.rst b/doc/guides/prog_guide/argparse_lib.rst index a6ac11b1c0..1acde60861 100644 --- a/doc/guides/prog_guide/argparse_lib.rst +++ b/doc/guides/prog_guide/argparse_lib.rst @@ -4,30 +4,31 @@ 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 + +- Supports parsing arguments in two ways: -- Support parsing argument by two ways: #. autosave: used for parsing known value types; #. callback: will invoke user callback to parse. + Usage Guide ----------- -The following code demonstrates how to use: +The following code demonstrates how to use the following: .. code-block:: C @@ -89,12 +90,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 +106,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 +133,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 +151,28 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~ +Parsing by Callback Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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. +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 +183,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