Skip to content
Back to top
View this page
Edit this page

# Roles

You can use Roles to get short information of needs inside single sentences.

## need

The role `:need:` will add title, id and a link to the need.

We use it to reference an existing need, without the need to keep title and link location manually in sync.

With `[[` and `]]` you can refer to defined and set extra options.

Example 1

    .. req:: Sliced Bread
       :id: roles_req_1
       :status: open
       :value: 20
       :unit: slices

    | The requirement :need:`roles_req_1` is the most important one.
    | But we can also set :need:`a custom link name <roles_req_1>`.
    | And we can change the text even more e.g. :need:`[[value]] [[unit]] of [[title]] ([[id]] [[status]]) <roles_req_1>`.

Requirement: Sliced Bread roles_req_1
status: open value: 20 unit: slices links incoming: roles_req_2

The requirement Sliced Bread (roles_req_1) is the most important one.
But we can also set a custom link name (roles_req_1).
And we can change the text even more e.g. 20 slices of Sliced Bread (roles_req_1 open).

Note

You can customize the string representation by using the configuration parameters needs_role_need_template and needs_role_need_max_title_length. If we find a `[[` in the customized string, we handle it according to Python’s `{` .format() function. Please see https://pyformat.info/ for more information. RST-attributes like `**bold**` are not supported.

Warning

If you refer to an external need, the algorithm is different and you will only get the need id as link text.

## need_outgoing

Added in version 0.1.25.

`:need_outgoing:` adds a list of all outgoing links of the given need. The list contains the need IDs only, no title or any other information is printed.

Example 2

    .. req:: Butter on Bread
       :id: roles_req_2
       :links: roles_req_1

    To get butter on our bread, we need to fulfill :need_outgoing:`roles_req_2`

Requirement: Butter on Bread roles_req_2
links outgoing: roles_req_1

To get butter on our bread, we need to fulfill roles_req_1

## need_incoming

Added in version 0.1.25.

`:need_incoming:` prints a list of IDs of needs which have set outgoing links to the given need.

Example 3

    The realisation of **Sliced Bread** is really important because the needs :need_incoming:`roles_req_1` are based on
    it.

The realisation of Sliced Bread is really important because the needs roles_req_2 are based on it.

## need_part / np

Added in version 0.3.0.

You can use `:need_part:` or as shortcut `:np:` inside needs to set a sub-id for a specific sentence/part. This sub-ids can be linked and referenced in other need functions like links and co.

The used need_part id can be freely chosen, but should not contain any whitespaces or dots.

Example 4

    .. req:: Car must be awesome
       :id: my_car_1
       :tags: car
       :status: open

       My new car must be the fastest on the world. Therefor it shall have:

       * :need_part:`(1)A top speed of 300 km/h`
       * :np:`(2) An acceleration of 200 m/s² or much much more`

       And we also need --> :np:`(awesome_3) a turbo button`!

    .. spec:: Build awesome car
       :id: impl_my_car_1
       :links: my_car_1.1, my_car_1.2

       Requirements :need:`my_car_1.1` and :need:`my_car_1.2` are no problem and can
       be realised by doing rocket science.

       But no way to get :need:`my_car_1.awesome_3` realised.

    Reference to a part of a need from outside need scope: :need:`my_car_1.2`.

Requirement: Car must be awesome my_car_1
status: open tags: car links incoming: impl_my_car_1

My new car must be the fastest on the world. Therefor it shall have:

- A top speed of 300 km/h 1

- An acceleration of 200 m/s² or much much more 2

And we also need –> a turbo button awesome_3!

Specification: Build awesome car impl_my_car_1
links outgoing: my_car_1.1, my_car_1.2
Requirements A top speed of 300 km/h (my_car_1.1) and An acceleration of 200 m/s... (my_car_1.2) are no problem and can be realised by doing rocket science. But no way to get a turbo button (my_car_1.awesome_3) realised.

Reference to a part of a need from outside need scope: An acceleration of 200 m/s... (my_car_1.2).

Presentation in needflow

Links to need_parts are shown as dotted line to the upper need inside needflow diagrams. They are also getting the part_id as link description.

Example 5

    .. needflow::
       :filter: id in ["my_car_1","impl_my_car_1"]

Presentation in needtable

Please see show_parts of needtable configuration documentation.

Example 6

    .. needtable::
       :style: table
       :filter: 'car' in tags and is_need
       :show_parts:
       :columns: id, title, incoming, outgoing

ID | Title | Incoming | Outgoing
--- | --- | --- | ---
my_car_1 | Car must be awesome | impl_my_car_1 |
→ my_car_1.1 | → A top speed of 300 km/h | impl_my_car_1 |
→ my_car_1.2 | → An acceleration of 200 m/s² or much much more | impl_my_car_1 |
→ my_car_1.awesome_3 | → a turbo button |  |

## need_count

Added in version 0.3.1.

Counts found needs for a given filter and shows the final amount.

The content of the role must be a valid filter-string as used e.g. by needlist in the `:filter:` option. See Filter string for more information.

Example 7

    | All needs: :need_count:`True`
    | Specification needs: :need_count:`type=='spec'`
    | Open specification needs: :need_count:`type=='spec' and status=='open'`
    | Needs with tag *test*: :need_count:`'test' in tags`
    | Needs with title longer 10 chars: :need_count:`search("[\\w\\s]{10,}", title)`
    | All need_parts: :need_count:`is_part`
    | All needs containing need_parts: :need_count:`is_need and len(parts)>0`

All needs: 225
Specification needs: 39
Open specification needs: 8
Needs with tag test: 3
Needs with title longer 10 chars: 190
All need_parts: 10
All needs containing need_parts: 4

Note

If backslashes `\` are used inside the regex function `search`, please make sure to double them as in python one `\` needs to be represented by `\\`.

Note

`need_count` executes the given filter on needs and need_parts! So if you use need_part / np , the result may contain the amount of found needs and found need_parts. To avoid this, add `is_need` or `is_part` to your filter.

### Ratio

Added in version 0.5.3.

To calculate the ratio of one filter to another filter, you can define two filters separated by `_?_` (question mark surrounded by one space on each side).

Example 8

    :need_count:`status == open and type == "spec" ? type == "spec"` % of our specifications are open.

0.0 % of our specifications are open.

## need_func

Deprecated since version 3.1.0: Use ndf instead.

## ndf

Added in version 3.1.0.

Executes a need dynamic function and uses the return values as content.

Example 9

    A nice :ndf:`echo("first test")` for dynamic functions.

A nice first test for dynamic functions.