From 44905cbc89629f4bd88823ab8e6141006c087f5e Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Mon, 4 Nov 2024 16:02:25 +0300 Subject: [PATCH 1/4] Added reference for argument clinic directives --- .../clinic-directive-reference.rst | 303 ++++++++++++++++++ development-tools/index.rst | 1 + 2 files changed, 304 insertions(+) create mode 100644 development-tools/clinic-directive-reference.rst diff --git a/development-tools/clinic-directive-reference.rst b/development-tools/clinic-directive-reference.rst new file mode 100644 index 0000000000..e716d891cc --- /dev/null +++ b/development-tools/clinic-directive-reference.rst @@ -0,0 +1,303 @@ +Argument Clinic References +--------------------------- + +@getter Directive +----------------- + +**Description**: +The ``@getter`` directive generates a C function that provides read-only access to an attribute, mimicking Python’s property. It is used to create an "impl" function that retrieves the value of an attribute. + +**Parameters**: +- None + +**Usage Example**: +The use of ``@getter`` in combination with the :ref:`@critical_section ` directive:: + + /*[clinic input] + @critical_section + @getter + _io.TextIOWrapper._CHUNK_SIZE + [clinic start generated code]*/ + + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context)) + { + PyObject *return_value = NULL; + Py_BEGIN_CRITICAL_SECTION(self); + return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl(self); + Py_END_CRITICAL_SECTION(); + return return_value + } + +**Explanation**: + - The generated C function, ``get()``, retrieves the ``_CHUNK_SIZE value`` from the ``TextIOWrapper`` class. + - A critical section ensures thread safety when accessing the attribute. + +Refer to the ``getter`` function section in :ref:`clinic-howto-getset ` for more details. + +@setter Directive +----------------- + +**Description**: +The ``@setter`` directive generates a C function that sets a value for an attribute, providing property-like write access. It works alongside the ``@getter`` directive to create read-write properties for Python objects in C extensions. + +**Parameters**: +- value (automatically passed): The new value to be set for the attribute. + +**Usage Example**: +The use of ``@setter`` in combination with the :ref:`@critical_section ` directive:: + + /*[clinic input] + @critical_section + @setter + _io.TextIOWrapper._CHUNK_SIZE + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static int + _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED(context)) + { + int return_value; + Py_BEGIN_CRITICAL_SECTION(self); + return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl(self, value); + Py_END_CRITICAL_SECTION(); + return return_value; + } + +**Explanation**: + - The setter function assigns a new value to ``_CHUNK_SIZE``. + - A ``critical section`` ensures thread safety during the update. + - The ``value`` parameter is added implicitly by Argument Clinic and represents the new data passed by the user. + +Refer to the ``setter`` function section in :ref:`clinic-howto-getset ` for more details. + +@critical_section Directive +---------------------------- + +**Description**: + - The ``@critical_section`` directive in Argument Clinic ensures thread safety by wrapping a function call within a critical section. This section locks the first argument's associated object, preventing concurrent access during execution. It is particularly useful in GIL-free builds of CPython to avoid deadlocks across threads. + +**Usage**: + - Without additional arguments: Locks only the first argument’s object. + - With additional arguments: Allows locking more objects by passing their C variable names as parameters. + +Example Usage:: + + /*[clinic input] + @critical_section + _io._Buffered.close + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _io__Buffered_close(buffered *self, PyObject *Py_UNUSED(ignored)) + { + PyObject *return_value = NULL; + + Py_BEGIN_CRITICAL_SECTION(self); + return_value = _io__Buffered_close_impl(self); + Py_END_CRITICAL_SECTION(); + + return return_value; + } + +Example with additional arguments:: + + /*[clinic input] + @critical_section object + _weakref.getweakrefcount -> Py_ssize_t + + object: object + / + Return the number of weak references to 'object'. + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _weakref_getweakrefs(PyObject *module, PyObject *object) + { + PyObject *return_value = NULL; + + Py_BEGIN_CRITICAL_SECTION(object); + return_value = _weakref_getweakrefs_impl(module, object); + Py_END_CRITICAL_SECTION(); + + return return_value; + } + +**Explanation**: + - ``Critical Section Behavior``: The critical section acquires a lock on entry and releases it on exit. + - ``GIL Impact``: In CPython builds with the GIL, these sections are no-ops, as the GIL already ensures thread safety. + +Refer to the ``@critical_section`` directive in the section :ref:`@critical_section ` for details. + +@text_signature Directive +------------------------- + +**Description**: +The ``@text_signiture`` directive is used to override the default generated signature in the docstring. + +**Parameters**: + - The ``@text_signiture`` directive takes on argument: ``( @text_signiture [arg1] )`` + +Example from :cpy-file:`Objects/codeobject.c`:: + + + /*[clinic input] + @text_signature "($self, /, **changes)" + code.replace + * + co_argcount: int(c_default="self->co_argcount") = unchanged + co_posonlyargcount: int(c_default="self->co_posonlyargcount") = unchanged + # etc ... + + Return a copy of the code object with new values for the specified fields. + [clinic start generated output]*/ + +The generated docstring ends up looking like this: + +.. code-block:: none + + replace($self, /, **changes) + -- + + Return a copy of the code object with new values for the specified fields. + +dump Directive +--------------- + +**Description**: +Dumps the contents of the specified destination buffer into the output of the current block and empties it. This is useful in configuring how and where Argument Clinic outputs generated code, particularly in multi-pass processing. + +**Parameters**: + - The ``dump`` directive takes in one argument ``(dump [arg1])`` + - Where ``arg1`` corresponds to the name of the ``destination`` of the buffer to dump, valid options being ``buffer`` or ``two-pass`` destinations. + +.. code-block:: none + + dump + + +output Directive +---------------- + +**Description**: +The ``output`` directive specifies where Argument Clinic should output specific fields, supporting custom and preset configurations. + +**Parameters**: + - The ``output`` directive takes in two arguments ``(output [arg1] [arg2])`` + - Where ``arg1`` is the ``field`` to output and ``arg2`` is the ``destination`` for the output. + +.. code-block:: none + + output + +Outputs the specified ```` to ````. + +.. note:: + + For all fields, use ``everything`` as the ````. + +**Configuration Commands**: + - ``output push``: Pushes the current configuration to the stack for temporary changes. + - ``output pop``: Restores the last configuration from the stack. + - ``preset ``: Sets output configuration to a preset. + +**Preset Options**: + - ``block``: Outputs most fields immediately after input block. + - ``file``: Outputs fields to a separate file for inclusion. + - ``buffer``: Saves output to dump later, reducing file edits. + - ``two-pass``: Uses two buffers to handle forward declarations and definitions separately. + - ``partial-buffer``: Outputs smaller code chunks to ``block``, larger ones to ``buffer``. + +destination Directive +--------------------- + +**Description**: +The ``destination`` directive allows for operations on output destinations. + +**Parameters**: + - The ``destination`` directive takes in two arguments ``(destination [arg1] [arg2])``. + - Where ``arg1`` is the ``name`` of the output destination and ``arg2`` is the ``command`` on the output destination. + +.. code-block:: none + + destination [...] + +There two defined subcommands: ``new`` and ``clear`` + +The ``new`` subcommand works like this: + +.. code-block:: none + + destination new + +This creates a new destination with name ```` and type ````. + +There are five destination types: + + - ``suppress``: Discards the output. + - ``block``: Writes to the current block. + - ``buffer``: A simple text buffer. + - ``file``: A text file (requires a filename template). + - ``two-pass``: A two-pass buffer. + + +The ``clear`` subcommand works like this: + +.. code-block:: none + + destination clear + +This removes all the accumulated text in the specified destination. + +set Directive +------------- +The ``set`` directive allows you to configure internal variables in Argument Clinic. + +**Syntax**: + +.. code-block:: none + + set line_prefix "string" + set line_suffix "string" + +**Description**: + - ``line_prefix``: Specifies a string to prepend to each line of Clinic's output. + - ``line_suffix``: Specifies a string to append to each line of Clinic's output. + +**Format Strings**: + +Both ``line_prefix`` and ``line_suffix`` support the following format strings: + +``{block comment start}`` + Turns into the string ``/*``, the start-comment text sequence for C files. + +``{block comment end}`` + Turns into the string ``*/``, the end-comment text sequence for C files. + +preserve Directive +------------------ + +The ``preserver`` directive tells Clinic that the current contents of the output should be kept, unmodified. +This is used internally by Clinic when dumping output into ``file`` files; wrapping +it in a Clinic block lets Clinic use its existing checksum functionality to ensure +the file was not modified by hand before it gets overwritten. + +.. code-block:: none + + preserve diff --git a/development-tools/index.rst b/development-tools/index.rst index 5031227a18..8aa45eab63 100644 --- a/development-tools/index.rst +++ b/development-tools/index.rst @@ -11,3 +11,4 @@ Development tools gdb clang warnings + clinic-directive-reference From b48115fb6dd20c5e4b915f04e341f187f3346c23 Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Mon, 4 Nov 2024 17:54:31 +0300 Subject: [PATCH 2/4] Added clinic directive references to the argument clinic documentation --- .../clinic-directive-reference.rst | 303 ----------------- development-tools/clinic.rst | 307 ++++++++++++++++++ development-tools/index.rst | 1 - 3 files changed, 307 insertions(+), 304 deletions(-) delete mode 100644 development-tools/clinic-directive-reference.rst diff --git a/development-tools/clinic-directive-reference.rst b/development-tools/clinic-directive-reference.rst deleted file mode 100644 index e716d891cc..0000000000 --- a/development-tools/clinic-directive-reference.rst +++ /dev/null @@ -1,303 +0,0 @@ -Argument Clinic References ---------------------------- - -@getter Directive ------------------ - -**Description**: -The ``@getter`` directive generates a C function that provides read-only access to an attribute, mimicking Python’s property. It is used to create an "impl" function that retrieves the value of an attribute. - -**Parameters**: -- None - -**Usage Example**: -The use of ``@getter`` in combination with the :ref:`@critical_section ` directive:: - - /*[clinic input] - @critical_section - @getter - _io.TextIOWrapper._CHUNK_SIZE - [clinic start generated code]*/ - - -The generated glue code looks like this: - -.. code-block:: c - - static PyObject * - _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context)) - { - PyObject *return_value = NULL; - Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl(self); - Py_END_CRITICAL_SECTION(); - return return_value - } - -**Explanation**: - - The generated C function, ``get()``, retrieves the ``_CHUNK_SIZE value`` from the ``TextIOWrapper`` class. - - A critical section ensures thread safety when accessing the attribute. - -Refer to the ``getter`` function section in :ref:`clinic-howto-getset ` for more details. - -@setter Directive ------------------ - -**Description**: -The ``@setter`` directive generates a C function that sets a value for an attribute, providing property-like write access. It works alongside the ``@getter`` directive to create read-write properties for Python objects in C extensions. - -**Parameters**: -- value (automatically passed): The new value to be set for the attribute. - -**Usage Example**: -The use of ``@setter`` in combination with the :ref:`@critical_section ` directive:: - - /*[clinic input] - @critical_section - @setter - _io.TextIOWrapper._CHUNK_SIZE - [clinic start generated code]*/ - -The generated glue code looks like this: - -.. code-block:: c - - static int - _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED(context)) - { - int return_value; - Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl(self, value); - Py_END_CRITICAL_SECTION(); - return return_value; - } - -**Explanation**: - - The setter function assigns a new value to ``_CHUNK_SIZE``. - - A ``critical section`` ensures thread safety during the update. - - The ``value`` parameter is added implicitly by Argument Clinic and represents the new data passed by the user. - -Refer to the ``setter`` function section in :ref:`clinic-howto-getset ` for more details. - -@critical_section Directive ----------------------------- - -**Description**: - - The ``@critical_section`` directive in Argument Clinic ensures thread safety by wrapping a function call within a critical section. This section locks the first argument's associated object, preventing concurrent access during execution. It is particularly useful in GIL-free builds of CPython to avoid deadlocks across threads. - -**Usage**: - - Without additional arguments: Locks only the first argument’s object. - - With additional arguments: Allows locking more objects by passing their C variable names as parameters. - -Example Usage:: - - /*[clinic input] - @critical_section - _io._Buffered.close - [clinic start generated code]*/ - -The generated glue code looks like this: - -.. code-block:: c - - static PyObject * - _io__Buffered_close(buffered *self, PyObject *Py_UNUSED(ignored)) - { - PyObject *return_value = NULL; - - Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io__Buffered_close_impl(self); - Py_END_CRITICAL_SECTION(); - - return return_value; - } - -Example with additional arguments:: - - /*[clinic input] - @critical_section object - _weakref.getweakrefcount -> Py_ssize_t - - object: object - / - Return the number of weak references to 'object'. - [clinic start generated code]*/ - -The generated glue code looks like this: - -.. code-block:: c - - static PyObject * - _weakref_getweakrefs(PyObject *module, PyObject *object) - { - PyObject *return_value = NULL; - - Py_BEGIN_CRITICAL_SECTION(object); - return_value = _weakref_getweakrefs_impl(module, object); - Py_END_CRITICAL_SECTION(); - - return return_value; - } - -**Explanation**: - - ``Critical Section Behavior``: The critical section acquires a lock on entry and releases it on exit. - - ``GIL Impact``: In CPython builds with the GIL, these sections are no-ops, as the GIL already ensures thread safety. - -Refer to the ``@critical_section`` directive in the section :ref:`@critical_section ` for details. - -@text_signature Directive -------------------------- - -**Description**: -The ``@text_signiture`` directive is used to override the default generated signature in the docstring. - -**Parameters**: - - The ``@text_signiture`` directive takes on argument: ``( @text_signiture [arg1] )`` - -Example from :cpy-file:`Objects/codeobject.c`:: - - - /*[clinic input] - @text_signature "($self, /, **changes)" - code.replace - * - co_argcount: int(c_default="self->co_argcount") = unchanged - co_posonlyargcount: int(c_default="self->co_posonlyargcount") = unchanged - # etc ... - - Return a copy of the code object with new values for the specified fields. - [clinic start generated output]*/ - -The generated docstring ends up looking like this: - -.. code-block:: none - - replace($self, /, **changes) - -- - - Return a copy of the code object with new values for the specified fields. - -dump Directive ---------------- - -**Description**: -Dumps the contents of the specified destination buffer into the output of the current block and empties it. This is useful in configuring how and where Argument Clinic outputs generated code, particularly in multi-pass processing. - -**Parameters**: - - The ``dump`` directive takes in one argument ``(dump [arg1])`` - - Where ``arg1`` corresponds to the name of the ``destination`` of the buffer to dump, valid options being ``buffer`` or ``two-pass`` destinations. - -.. code-block:: none - - dump - - -output Directive ----------------- - -**Description**: -The ``output`` directive specifies where Argument Clinic should output specific fields, supporting custom and preset configurations. - -**Parameters**: - - The ``output`` directive takes in two arguments ``(output [arg1] [arg2])`` - - Where ``arg1`` is the ``field`` to output and ``arg2`` is the ``destination`` for the output. - -.. code-block:: none - - output - -Outputs the specified ```` to ````. - -.. note:: - - For all fields, use ``everything`` as the ````. - -**Configuration Commands**: - - ``output push``: Pushes the current configuration to the stack for temporary changes. - - ``output pop``: Restores the last configuration from the stack. - - ``preset ``: Sets output configuration to a preset. - -**Preset Options**: - - ``block``: Outputs most fields immediately after input block. - - ``file``: Outputs fields to a separate file for inclusion. - - ``buffer``: Saves output to dump later, reducing file edits. - - ``two-pass``: Uses two buffers to handle forward declarations and definitions separately. - - ``partial-buffer``: Outputs smaller code chunks to ``block``, larger ones to ``buffer``. - -destination Directive ---------------------- - -**Description**: -The ``destination`` directive allows for operations on output destinations. - -**Parameters**: - - The ``destination`` directive takes in two arguments ``(destination [arg1] [arg2])``. - - Where ``arg1`` is the ``name`` of the output destination and ``arg2`` is the ``command`` on the output destination. - -.. code-block:: none - - destination [...] - -There two defined subcommands: ``new`` and ``clear`` - -The ``new`` subcommand works like this: - -.. code-block:: none - - destination new - -This creates a new destination with name ```` and type ````. - -There are five destination types: - - - ``suppress``: Discards the output. - - ``block``: Writes to the current block. - - ``buffer``: A simple text buffer. - - ``file``: A text file (requires a filename template). - - ``two-pass``: A two-pass buffer. - - -The ``clear`` subcommand works like this: - -.. code-block:: none - - destination clear - -This removes all the accumulated text in the specified destination. - -set Directive -------------- -The ``set`` directive allows you to configure internal variables in Argument Clinic. - -**Syntax**: - -.. code-block:: none - - set line_prefix "string" - set line_suffix "string" - -**Description**: - - ``line_prefix``: Specifies a string to prepend to each line of Clinic's output. - - ``line_suffix``: Specifies a string to append to each line of Clinic's output. - -**Format Strings**: - -Both ``line_prefix`` and ``line_suffix`` support the following format strings: - -``{block comment start}`` - Turns into the string ``/*``, the start-comment text sequence for C files. - -``{block comment end}`` - Turns into the string ``*/``, the end-comment text sequence for C files. - -preserve Directive ------------------- - -The ``preserver`` directive tells Clinic that the current contents of the output should be kept, unmodified. -This is used internally by Clinic when dumping output into ``file`` files; wrapping -it in a Clinic block lets Clinic use its existing checksum functionality to ensure -the file was not modified by hand before it gets overwritten. - -.. code-block:: none - - preserve diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 642f40dce9..0a2fe8f36d 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2213,3 +2213,310 @@ and update your unit tests to reflect the new behaviour. If you forget to update your input block during the alpha and beta phases, the compiler warning will turn into a compiler error when the release candidate phase begins. + +.. _clinic-directives: + +Argument Clinic Directives +--------------------------- + +@getter Directive +----------------- + +**Description**: +The ``@getter`` directive generates a C function that provides read-only access to an attribute, mimicking Python’s property. It is used to create an "impl" function that retrieves the value of an attribute. + +**Parameters**: +- None + +**Usage Example**: +The use of ``@getter`` in combination with the :ref:`@critical_section ` directive:: + + /*[clinic input] + @critical_section + @getter + _io.TextIOWrapper._CHUNK_SIZE + [clinic start generated code]*/ + + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context)) + { + PyObject *return_value = NULL; + Py_BEGIN_CRITICAL_SECTION(self); + return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl(self); + Py_END_CRITICAL_SECTION(); + return return_value + } + +**Explanation**: + - The generated C function, ``get()``, retrieves the ``_CHUNK_SIZE value`` from the ``TextIOWrapper`` class. + - A critical section ensures thread safety when accessing the attribute. + +Refer to the ``getter`` function section in :ref:`clinic-howto-getset ` for more details. + + +@setter Directive +----------------- + +**Description**: +The ``@setter`` directive generates a C function that sets a value for an attribute, providing property-like write access. It works alongside the ``@getter`` directive to create read-write properties for Python objects in C extensions. + +**Parameters**: +- value (automatically passed): The new value to be set for the attribute. + +**Usage Example**: +The use of ``@setter`` in combination with the :ref:`@critical_section ` directive:: + + /*[clinic input] + @critical_section + @setter + _io.TextIOWrapper._CHUNK_SIZE + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static int + _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED(context)) + { + int return_value; + Py_BEGIN_CRITICAL_SECTION(self); + return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl(self, value); + Py_END_CRITICAL_SECTION(); + return return_value; + } + +**Explanation**: + - The setter function assigns a new value to ``_CHUNK_SIZE``. + - A ``critical section`` ensures thread safety during the update. + - The ``value`` parameter is added implicitly by Argument Clinic and represents the new data passed by the user. + +Refer to the ``setter`` function section in :ref:`clinic-howto-getset ` for more details. + +@critical_section Directive +---------------------------- + +**Description**: + - The ``@critical_section`` directive in Argument Clinic ensures thread safety by wrapping a function call within a critical section. This section locks the first argument's associated object, preventing concurrent access during execution. It is particularly useful in GIL-free builds of CPython to avoid deadlocks across threads. + +**Usage**: + - Without additional arguments: Locks only the first argument’s object. + - With additional arguments: Allows locking more objects by passing their C variable names as parameters. + +Example Usage:: + + /*[clinic input] + @critical_section + _io._Buffered.close + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _io__Buffered_close(buffered *self, PyObject *Py_UNUSED(ignored)) + { + PyObject *return_value = NULL; + + Py_BEGIN_CRITICAL_SECTION(self); + return_value = _io__Buffered_close_impl(self); + Py_END_CRITICAL_SECTION(); + + return return_value; + } + +Example with additional arguments:: + + /*[clinic input] + @critical_section object + _weakref.getweakrefcount -> Py_ssize_t + + object: object + / + Return the number of weak references to 'object'. + [clinic start generated code]*/ + +The generated glue code looks like this: + +.. code-block:: c + + static PyObject * + _weakref_getweakrefs(PyObject *module, PyObject *object) + { + PyObject *return_value = NULL; + + Py_BEGIN_CRITICAL_SECTION(object); + return_value = _weakref_getweakrefs_impl(module, object); + Py_END_CRITICAL_SECTION(); + + return return_value; + } + +**Explanation**: + - ``Critical Section Behavior``: The critical section acquires a lock on entry and releases it on exit. + - ``GIL Impact``: In CPython builds with the GIL, these sections are no-ops, as the GIL already ensures thread safety. + +Refer to the ``@critical_section`` directive in the section :ref:`@critical_section ` for details. + +@text_signature Directive +--------------------------- + +**Description**: +The ``@text_signiture`` directive is used to override the default generated signature in the docstring. + +**Parameters**: + - The ``@text_signiture`` directive takes on argument: ``( @text_signiture [arg1] )`` + +Example from :cpy-file:`Objects/codeobject.c`:: + + + /*[clinic input] + @text_signature "($self, /, **changes)" + code.replace + * + co_argcount: int(c_default="self->co_argcount") = unchanged + co_posonlyargcount: int(c_default="self->co_posonlyargcount") = unchanged + # etc ... + + Return a copy of the code object with new values for the specified fields. + [clinic start generated output]*/ + +The generated docstring ends up looking like this: + +.. code-block:: none + + replace($self, /, **changes) + -- + + Return a copy of the code object with new values for the specified fields. + +dump Directive +--------------- + +**Description**: +Dumps the contents of the specified destination buffer into the output of the current block and empties it. This is useful in configuring how and where Argument Clinic outputs generated code, particularly in multi-pass processing. + +**Parameters**: + - The ``dump`` directive takes in one argument ``(dump [arg1])`` + - Where ``arg1`` corresponds to the name of the ``destination`` of the buffer to dump, valid options being ``buffer`` or ``two-pass`` destinations. + +.. code-block:: none + + dump + + +output Directive +---------------- + +**Description**: +The ``output`` directive specifies where Argument Clinic should output specific fields, supporting custom and preset configurations. + +**Parameters**: + - The ``output`` directive takes in two arguments ``(output [arg1] [arg2])`` + - Where ``arg1`` is the ``field`` to output and ``arg2`` is the ``destination`` for the output. + +.. code-block:: none + + output + +Outputs the specified ```` to ````. + +.. note:: + + For all fields, use ``everything`` as the ````. + +**Configuration Commands**: + - ``output push``: Pushes the current configuration to the stack for temporary changes. + - ``output pop``: Restores the last configuration from the stack. + - ``preset ``: Sets output configuration to a preset. + +**Preset Options**: + - ``block``: Outputs most fields immediately after input block. + - ``file``: Outputs fields to a separate file for inclusion. + - ``buffer``: Saves output to dump later, reducing file edits. + - ``two-pass``: Uses two buffers to handle forward declarations and definitions separately. + - ``partial-buffer``: Outputs smaller code chunks to ``block``, larger ones to ``buffer``. + +destination Directive +--------------------- + +**Description**: +The ``destination`` directive allows for operations on output destinations. + +**Parameters**: + - The ``destination`` directive takes in two arguments ``(destination [arg1] [arg2])``. + - Where ``arg1`` is the ``name`` of the output destination and ``arg2`` is the ``command`` on the output destination. + +.. code-block:: none + + destination [...] + +There two defined subcommands: ``new`` and ``clear`` + +The ``new`` subcommand works like this: + +.. code-block:: none + + destination new + +This creates a new destination with name ```` and type ````. + +There are five destination types: + + - ``suppress``: Discards the output. + - ``block``: Writes to the current block. + - ``buffer``: A simple text buffer. + - ``file``: A text file (requires a filename template). + - ``two-pass``: A two-pass buffer. + + +The ``clear`` subcommand works like this: + +.. code-block:: none + + destination clear + +This removes all the accumulated text in the specified destination. + +set Directive +------------- +The ``set`` directive allows you to configure internal variables in Argument Clinic. + +**Syntax**: + +.. code-block:: none + + set line_prefix "string" + set line_suffix "string" + +**Description**: + - ``line_prefix``: Specifies a string to prepend to each line of Clinic's output. + - ``line_suffix``: Specifies a string to append to each line of Clinic's output. + +**Format Strings**: + +Both ``line_prefix`` and ``line_suffix`` support the following format strings: + +``{block comment start}`` + Turns into the string ``/*``, the start-comment text sequence for C files. + +``{block comment end}`` + Turns into the string ``*/``, the end-comment text sequence for C files. + +preserve Directive +------------------ + +The ``preserver`` directive tells Clinic that the current contents of the output should be kept, unmodified. +This is used internally by Clinic when dumping output into ``file`` files; wrapping +it in a Clinic block lets Clinic use its existing checksum functionality to ensure +the file was not modified by hand before it gets overwritten. + +.. code-block:: none + + preserve diff --git a/development-tools/index.rst b/development-tools/index.rst index 8aa45eab63..5031227a18 100644 --- a/development-tools/index.rst +++ b/development-tools/index.rst @@ -11,4 +11,3 @@ Development tools gdb clang warnings - clinic-directive-reference From bd2b1de4c396720fe393c119ba0e0569a116113b Mon Sep 17 00:00:00 2001 From: Lincoln <71312724+Lincoln-developer@users.noreply.github.com> Date: Tue, 5 Nov 2024 08:38:14 +0300 Subject: [PATCH 3/4] Update development-tools/clinic.rst Adjusted output destination list formatting as per feedback. Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- development-tools/clinic.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index 0a2fe8f36d..feb486736f 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2469,11 +2469,11 @@ This creates a new destination with name ```` and type ````. There are five destination types: - - ``suppress``: Discards the output. - - ``block``: Writes to the current block. - - ``buffer``: A simple text buffer. - - ``file``: A text file (requires a filename template). - - ``two-pass``: A two-pass buffer. +- ``suppress``: Discards the output. +- ``block``: Writes to the current block. +- ``buffer``: A simple text buffer. +- ``file``: A text file (requires a filename template). +- ``two-pass``: A two-pass buffer. The ``clear`` subcommand works like this: From 81127893ed3919102fffe3f1ba257dd06a6b6317 Mon Sep 17 00:00:00 2001 From: Lincoln-developer Date: Tue, 5 Nov 2024 08:46:53 +0300 Subject: [PATCH 4/4] Adjusted list formatting as per feedback --- development-tools/clinic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/development-tools/clinic.rst b/development-tools/clinic.rst index feb486736f..506f0499b0 100644 --- a/development-tools/clinic.rst +++ b/development-tools/clinic.rst @@ -2450,8 +2450,8 @@ destination Directive The ``destination`` directive allows for operations on output destinations. **Parameters**: - - The ``destination`` directive takes in two arguments ``(destination [arg1] [arg2])``. - - Where ``arg1`` is the ``name`` of the output destination and ``arg2`` is the ``command`` on the output destination. +- The ``destination`` directive takes in two arguments ``(destination [arg1] [arg2])``. +- Where ``arg1`` is the ``name`` of the output destination and ``arg2`` is the ``command`` on the output destination. .. code-block:: none