needextend¶

needextend allows to modify existing needs. It doesn’t provide any output, as the modifications get presented at the original location of the changing need.

Example

.. needextend:: <filter_string>
   :option: new value
   :+option: additional value
   :-option:

The following modifications are supported:

• option: replaces the value of an option

• +option: add new value to an existing value of an option.

• -option: delete a complete option.

The argument of needextend must be a Filter string which defines the needs to modify.

needextend can modify all string-based and list-based options. Also, you can add links or delete tags.

Example

.. req:: needextend Example 1
   :id: extend_test_001
   :status: open
   :author: Foo
   :tags: tag_1, tag_2

   This requirement got modified.

   | Status was **open**, now it is **[[copy('status')]]**.
   | Also author got changed from **Foo** to **[[copy('author')]]**.
   | And a tag was added.
   | Finally all links got removed.

.. needextend:: id == "extend_test_001"
   :status: closed
   :+author: and me
   :+tags: new_tag

Result

Requirement: needextend Example 1 extend_test_001

status: closed tags: tag_1, tag_2, new_tag author: Foo and me links outgoing: FEATURE_1, FEATURE_2, FEATURE_3

This requirement got modified. Status was open, now it is closed. Also author got changed from Foo to Foo and me. And a tag was added. Finally all links got removed.

Options¶

strict¶

The purpose of the :strict: option is to handle whether an exception gets thrown or a log-info message gets written if there is no need object to match the needextend's required argument (e.g. an ID).

If you set the :strict: option value to true, needextend raises an exception because the given ID does not exist, and the build stops.

If you set the :strict: option value to false, needextend logs an info-level message in the console, and the build continues.

Allowed values:

• true or

• false

Default: true

Single need modification¶

If only one single need shall get modified, the argument of needextend can just be the need-id.

Example

.. req:: needextend Example 2
   :id: extend_test_002
   :status: open

.. needextend:: extend_test_002
   :status: New status

Result

Requirement: needextend Example 2 extend_test_002

status: New status

Setting default option values¶

You can use needextend’s filter string to set default option values for a group of needs.

Example

The following example would set the status of all needs in the document docs/directives/needextend.rst, which do not have the status set explicitly, to open.

.. needextend:: (docname == "docs/directives/needextend") and (status is None)
   :status: open

See also: needs_global_options for setting a default option value for all needs.

Changing links¶

Options containing links get handled in two steps:

1. Options for the need are set as above.

2. The referenced need get updated as well and incoming links may get deleted, added or replaced.

Example

.. req:: needextend Example 3
   :id: extend_test_003

   Had no outgoing links.
   Got an outgoing link ``extend_test_004``.

.. req:: needextend Example 4
   :id: extend_test_004

   Had no links.
   Got an incoming links ``extend_test_003`` and ``extend_test_006``.

.. req:: needextend Example 5
   :id: extend_test_005
   :links: extend_test_003, extend_test_004

   Had the two links: ``extend_test_003`` and ``extend_test_004``.
   Both got deleted.

.. req:: needextend Example 6
   :id: extend_test_006
   :links: extend_test_003

   Had the link ``extend_test_003``, got another one ``extend_test_004``.

.. -- MANIPULATIONS --

.. needextend:: extend_test_003
   :links: extend_test_004

.. needextend:: extend_test_005
   :-links:

.. needextend:: extend_test_006
   :+links: extend_test_004

.. needextend:: extend_test_006
   :+links: extend_test_004

   Same as above, so it should not do anything.
   But it raises the modified-counter by one.

Result

Requirement: needextend Example 3 extend_test_003

links outgoing: extend_test_004 links incoming: extend_test_006

Had no outgoing links. Got an outgoing link extend_test_004.

Requirement: needextend Example 4 extend_test_004

links incoming: extend_test_003, extend_test_006

Had no links. Got an incoming links extend_test_003 and extend_test_006.

Requirement: needextend Example 5 extend_test_005

Had the two links: extend_test_003 and extend_test_004. Both got deleted.

Requirement: needextend Example 6 extend_test_006

links outgoing: extend_test_003, extend_test_004

Had the link extend_test_003, got another one extend_test_004.

Monitoring modifications¶

All needs have this two internal parameters:

• is_modified: A boolean value. Defaults to False

• modifications: A number. Defaults to 0.

If a need gets changed by a needextend directive, is_modified is changed to True. Also, the modifications number is increased by one. +1 for each executed needextend on this need.

To see these values, use :layout: debug on the need or by Defining own layouts.

Also filtering for these values is supported:

Example

We have :need_count:`is_modified` modified needs.

.. needtable::
   :filter: "needextend" in title
   :columns: id, title, is_modified, modifications

Result

We have 6 modified needs.