:orphan:

.. index:: pair: group; Helper functions for handling options
.. _doxid-group__tapi__job__opt:

Helper functions for handling options
=====================================

.. toctree::
	:hidden:

	group_tapi_job_opt_bind_constructors.rst
	group_tapi_job_opt_formatting.rst
	struct_tapi_job_opt_array.rst
	struct_tapi_job_opt_bind.rst
	struct_tapi_job_opt_struct.rst

Overview
~~~~~~~~

TAPI to handle tool options. :ref:`More...<details-group__tapi__job__opt>`

|	:ref:`convenience macros for option<doxid-group__tapi__job__opt__bind__constructors>`
|	:ref:`functions for argument formatting<doxid-group__tapi__job__opt__formatting>`



.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// typedefs

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`tapi_job_opt_arg_format<doxid-group__tapi__job__opt_1gafcd00d33b4005fd70324f417882c6032>`)(
		const void *opt,
		const void *priv,
		te_vec *arg
		);

	typedef struct :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>` :ref:`tapi_job_opt_bind<doxid-group__tapi__job__opt_1ga6e11aa3aa0f525b0e264c5e94d09224d>`;
	typedef struct :ref:`tapi_job_opt_array<doxid-structtapi__job__opt__array>` :ref:`tapi_job_opt_array<doxid-group__tapi__job__opt_1ga90bac59e8399c7c8f52d590a0a938c2e>`;
	typedef struct :ref:`tapi_job_opt_struct<doxid-structtapi__job__opt__struct>` :ref:`tapi_job_opt_struct<doxid-group__tapi__job__opt_1gafd2f31ba670fc0cffedbc3f3d01af4a7>`;
	typedef :ref:`te_optional_uint_t<doxid-structte__optional__uint__t>` :ref:`tapi_job_opt_uint_t<doxid-group__tapi__job__opt_1ga6029f81fe926f3cb1d5a63c02b06d8b9>`;
	typedef :ref:`te_optional_uintmax_t<doxid-structte__optional__uintmax__t>` :ref:`tapi_job_opt_uintmax_t<doxid-group__tapi__job__opt_1ga2d12253362860180cd87ec371f8672df>`;
	typedef :ref:`te_optional_double_t<doxid-structte__optional__double__t>` :ref:`tapi_job_opt_double_t<doxid-group__tapi__job__opt_1gaee9f6ff157633a98216ac591fec50609>`;

	// structs

	struct :ref:`tapi_job_opt_array<doxid-structtapi__job__opt__array>`;
	struct :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>`;
	struct :ref:`tapi_job_opt_struct<doxid-structtapi__job__opt__struct>`;

	// global functions

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_job_opt_build_args<doxid-group__tapi__job__opt_1gaf259befcd14284ab0eff49dbbc6ceeab>`(const char* path, const :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>`* binds, const void* opt, :ref:`te_vec<doxid-structte__vec>`* tool_args);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_job_opt_append_strings<doxid-group__tapi__job__opt_1gac6ff1c2ff4c9136a0d24c256d2f53db9>`(const char** items, :ref:`te_vec<doxid-structte__vec>`* tool_args);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_job_opt_append_args<doxid-group__tapi__job__opt_1gacebd137e5541e058c383d1dd9f9b6ada>`(const :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>`* binds, const void* opt, :ref:`te_vec<doxid-structte__vec>`* tool_args);

	// macros

	#define :ref:`TAPI_JOB_OPT_DOUBLE_UNDEF<doxid-group__tapi__job__opt_1gadf9604d915b2dae43b16566949fca00d>`
	#define :ref:`TAPI_JOB_OPT_DOUBLE_VAL<doxid-group__tapi__job__opt_1ga3ccd3bf0856e5792df343b6119445bc7>`(_x)
	#define :ref:`TAPI_JOB_OPT_SET<doxid-group__tapi__job__opt_1gace52e46c20a8d479a7529ab3eb56e2c0>`(...)
	#define :ref:`TAPI_JOB_OPT_UINTMAX_UNDEF<doxid-group__tapi__job__opt_1gaf8e17db0f58485e9888dcdb560e3a1ce>`
	#define :ref:`TAPI_JOB_OPT_UINTMAX_VAL<doxid-group__tapi__job__opt_1ga027eb9d425717bdf18205d1be1f9e319>`(_x)
	#define :ref:`TAPI_JOB_OPT_UINT_UNDEF<doxid-group__tapi__job__opt_1ga8db07499d9d1da3556820e463320bdf2>`
	#define :ref:`TAPI_JOB_OPT_UINT_VAL<doxid-group__tapi__job__opt_1ga7be73d34770d24b6151333bedc73fdbc>`(_x)

.. _details-group__tapi__job__opt:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

TAPI to handle tool options.

Typedefs
--------

.. index:: pair: typedef; tapi_job_opt_arg_format
.. _doxid-group__tapi__job__opt_1gafcd00d33b4005fd70324f417882c6032:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*tapi_job_opt_arg_format)(
		const void *opt,
		const void *priv,
		te_vec *arg
		)

Formatting function pointer: put formatted command-line argument in a vector.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- opt

		- Pointer to an argument, with specific type for every formatting function.

	*
		- priv

		- Pointer to private data that may be needed for a formatting function.

	*
		- arg

		- Vector to put formatted argument to. Functions are allowed to put multiple string in the vector. In that case multiple arguments will be created.

	*
		- TE_ENOENT

		- The argument must be skipped (along with prefix/suffix);



.. rubric:: Returns:

Status code

.. index:: pair: typedef; tapi_job_opt_bind
.. _doxid-group__tapi__job__opt_1ga6e11aa3aa0f525b0e264c5e94d09224d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>` tapi_job_opt_bind

Bind between a tool's option struct field and command line arguments.

Field here is a member of a struct. The struct is the tool's custom struct with command line options.

.. index:: pair: typedef; tapi_job_opt_array
.. _doxid-group__tapi__job__opt_1ga90bac59e8399c7c8f52d590a0a938c2e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_job_opt_array<doxid-structtapi__job__opt__array>` tapi_job_opt_array

The descriptor for an array-typed field. This structure shall *never* be used directly, see :ref:`TAPI_JOB_OPT_ARRAY() <doxid-group__tapi__job__opt__bind__constructors_1gab55685aede972d6dac2f3f2e68d96115>`

.. index:: pair: typedef; tapi_job_opt_struct
.. _doxid-group__tapi__job__opt_1gafd2f31ba670fc0cffedbc3f3d01af4a7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_job_opt_struct<doxid-structtapi__job__opt__struct>` tapi_job_opt_struct

The descriptor for an struct-typed field. This structure shall *never* be used directly, see :ref:`TAPI_JOB_OPT_STRUCT() <doxid-group__tapi__job__opt__bind__constructors_1ga3156c98fd06de285235796441731f814>`

.. index:: pair: typedef; tapi_job_opt_uint_t
.. _doxid-group__tapi__job__opt_1ga6029f81fe926f3cb1d5a63c02b06d8b9:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_optional_uint_t<doxid-structte__optional__uint__t>` tapi_job_opt_uint_t

Unsigned integer which can be left undefined.

This is guaranteed to be assignment-compatible with :ref:`te_optional_uint_t <doxid-structte__optional__uint__t>`.

.. index:: pair: typedef; tapi_job_opt_uintmax_t
.. _doxid-group__tapi__job__opt_1ga2d12253362860180cd87ec371f8672df:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_optional_uintmax_t<doxid-structte__optional__uintmax__t>` tapi_job_opt_uintmax_t

Unsigned long integer which can be left undefined.

This is guaranteed to be assignment-compatible with :ref:`te_optional_uintmax_t <doxid-structte__optional__uintmax__t>`.

.. index:: pair: typedef; tapi_job_opt_double_t
.. _doxid-group__tapi__job__opt_1gaee9f6ff157633a98216ac591fec50609:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_optional_double_t<doxid-structte__optional__double__t>` tapi_job_opt_double_t

Double which can be left undefined.

This is guaranteed to be assignment-compatible with :ref:`te_optional_double_t <doxid-structte__optional__double__t>`.

Global Functions
----------------

.. index:: pair: function; tapi_job_opt_build_args
.. _doxid-group__tapi__job__opt_1gaf259befcd14284ab0eff49dbbc6ceeab:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_job_opt_build_args(const char* path, const :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>`* binds, const void* opt, :ref:`te_vec<doxid-structte__vec>`* tool_args)

Create a vector with command line arguments by processing option binds.

``tool_args`` contents is overwritten by this function, so it should have no elements prior to the call, or a memory leak would ensue.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- path

		- Tool path (program location).

	*
		- binds

		- Binds between ``opt`` and produced arguments, or ``NULL``.

	*
		- opt

		- Tool's custom option struct which is forwarded to argument formatting callback, or ``NULL`` if the previous argument is ``NULL``.

	*
		- tool_args

		- Vector with command line arguments.



.. rubric:: Returns:

Status code.



.. rubric:: See also:

:ref:`tapi_job_opt_append_strings() <doxid-group__tapi__job__opt_1gac6ff1c2ff4c9136a0d24c256d2f53db9>`

:ref:`tapi_job_opt_append_args() <doxid-group__tapi__job__opt_1gacebd137e5541e058c383d1dd9f9b6ada>`

.. index:: pair: function; tapi_job_opt_append_strings
.. _doxid-group__tapi__job__opt_1gac6ff1c2ff4c9136a0d24c256d2f53db9:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_job_opt_append_strings(const char** items, :ref:`te_vec<doxid-structte__vec>`* tool_args)

Append a list of strings to an already built argument vector.

The terminating ``NULL`` is moved accordingly.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- items

		- ``NULL-terminated`` array of strings (they are strdup'ed in the vector).

	*
		- tool_args

		- Argument vector (must be initialized).



.. rubric:: Returns:

Status code



.. rubric:: See also:

:ref:`tapi_job_opt_build_args() <doxid-group__tapi__job__opt_1gaf259befcd14284ab0eff49dbbc6ceeab>`

.. index:: pair: function; tapi_job_opt_append_args
.. _doxid-group__tapi__job__opt_1gacebd137e5541e058c383d1dd9f9b6ada:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_job_opt_append_args(const :ref:`tapi_job_opt_bind<doxid-structtapi__job__opt__bind>`* binds, const void* opt, :ref:`te_vec<doxid-structte__vec>`* tool_args)

Append options to an already built argument vector.

The terminating ``NULL`` is moved accordingly.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- binds

		- Binds between ``opt`` and produced arguments, or ``NULL``.

	*
		- opt

		- Tool's custom option struct which is forwarded to argument formatting callback, or ``NULL`` if the previous argument is ``NULL``.

	*
		- tool_args

		- Argument vector (must be initialized).



.. rubric:: Returns:

Status code.



.. rubric:: See also:

:ref:`tapi_job_opt_build_args() <doxid-group__tapi__job__opt_1gaf259befcd14284ab0eff49dbbc6ceeab>`

Macros
------

.. index:: pair: define; TAPI_JOB_OPT_DOUBLE_UNDEF
.. _doxid-group__tapi__job__opt_1gadf9604d915b2dae43b16566949fca00d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_DOUBLE_UNDEF

Undefined value for tapi_job_opt_double_t.

.. index:: pair: define; TAPI_JOB_OPT_DOUBLE_VAL
.. _doxid-group__tapi__job__opt_1ga3ccd3bf0856e5792df343b6119445bc7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_DOUBLE_VAL(_x)

Defined value for tapi_job_opt_double_t.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _x

		- Value to set.

.. index:: pair: define; TAPI_JOB_OPT_SET
.. _doxid-group__tapi__job__opt_1gace52e46c20a8d479a7529ab3eb56e2c0:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_SET(...)

A convenience vector constructor to define option binds

.. index:: pair: define; TAPI_JOB_OPT_UINTMAX_UNDEF
.. _doxid-group__tapi__job__opt_1gaf8e17db0f58485e9888dcdb560e3a1ce:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_UINTMAX_UNDEF

Undefined value for tapi_job_opt_uintmax_t.

.. index:: pair: define; TAPI_JOB_OPT_UINTMAX_VAL
.. _doxid-group__tapi__job__opt_1ga027eb9d425717bdf18205d1be1f9e319:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_UINTMAX_VAL(_x)

Defined value for tapi_job_opt_uintmax_t.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _x

		- Value to set.

.. index:: pair: define; TAPI_JOB_OPT_UINT_UNDEF
.. _doxid-group__tapi__job__opt_1ga8db07499d9d1da3556820e463320bdf2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_UINT_UNDEF

Undefined value for tapi_job_opt_uint_t.

.. index:: pair: define; TAPI_JOB_OPT_UINT_VAL
.. _doxid-group__tapi__job__opt_1ga7be73d34770d24b6151333bedc73fdbc:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JOB_OPT_UINT_VAL(_x)

Defined value for tapi_job_opt_uint_t.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _x

		- Value to set.