Ruby Interface

It is possible to access the data via Ruby. All default fields are already evaluated.

Loading

Instantiate a loader and call the load() method. load() offers three arguments:

• file: Either a requirements or a config filename. Mandatory argument.

• attributes_file: Project specific custom attributes filename, Optional, defaults to empty filepath.

• allow_missing Ignore unresolved references if set to true. Optional, defaults to false.

• silent Suppress logging output while loading files if set to true. Optional, defaults to true.

• no_check_enclosed Skips the enclosed file check. Optional, defaults to false.

Example:

require 'dim/loader'

l = Dim::Loader.new
l.load(file: "module.dim", attributes_file: "attributes.dim", allow_missing: true, silent: false)

Data Access

After loading, all data is accessible via the member variable requirements of the loader. This variable is a hash, the keys are the IDs of the requirements, the values the requirement objects.

A requirements object has the following getters:

• All attribute names from Requirements Files to access the data, like text, review_status, etc.

• document: the document name used in the Requirements Files

• id: for convenience, same as the key in the requirements hash

• origin, category: from config file

• filename, line_number: to print error messages, etc.

• existingRefs: array of ref-IDs which really exists (useful if allow_missing was set to true)

• backwardRefs: array of ref-IDs which reference this requirement

• upstreamRefs: array of IDs from refs to higher category level plus backward-refs from higher or same category level

• downstreamRefs: array of IDs from refs to lower or same category level plus backward refs from lower category

The following table shows the return types of the getter methods:

Strings	Array of Strings
asil	backwardRefs
cal	developer
change_request	downstreamRefs
comment	existingRefs
feature	refs
filename	sources
id	tags
miscellaneous	verification_methods
document	tester
origin
review_status
status
text
type
verification_criteria

Some examples:

require 'dim/loader'

l = Dim::Loader.new
l.load(...)

requirements_text = l.requirements["myId"].text
modules = l.requirements.values.map {|r| r.document}.uniq
valid_notRejected_Reqs = l.requirements.values.select do |r|
  r.type == "requirement" && r.status == "valid" && r.review_status != "rejected"
end
devMyCompany = reqs.select {|r| r.developer.include?("MyCompany")}
reqsWithRefs = reqs.select {|r| !r.refs.empty? }

The metadata is available via the member variable metadata of the loader. This variable is a hash with document name as key and the metadata as string value.

Example:

require 'dim/loader'

l = Dim::Loader.new
l.load(...)

puts l.metadata["document"]

Convenience Methods

String Lists

Dim extends the Ruby String class with the following methods which can be also used by custom scripts:

• cleanSplit returns an array of the elements without leading and trailing whitespaces

  Example: "a,a,b    ,,  c".cleanSplit() == ["a", "a", "b", "", "c"]
• cleanArray same as cleanSplit, but without empty elements

  Example: "a,a,b    ,,  c".cleanArray() == ["a", "a", "b", "c"]
• cleanUniqArray same as cleanArray, but also removes duplicates

  Example: "a,a,b    ,,  c".cleanArray() == ["a", "b", "c"]
• cleanString removes empty elements, leading and trailing whitespaces

  Example: "a,a,b    ,,  c".cleanString() == "a, a, b, c"
• cleanUniqString same as cleanString but also removes duplicates

  Example: "a,a,b    ,,  c".cleanUniqString() == "a, b, c"
• addEnum adds another element to the list and makes all elements in the list unique

  Example: "a, b, c, a".addEnum("d") == "a, b, c, d"
• removeEnum removes all enums with a specific value from the list

  Example: "a, b, c, a".removeEnum("a") == "b, c"

Calculations

• safety_relevant? returns

  • true if the asil in the requirement is neither QM nor not_set,

  • otherwise false.

• security_relevant? returns

  • true if the cal in the requirement is neither QM nor not_set,

  • otherwise false.

Original Data (Expert Usage)

For special expert usages, the loader also provides a member variable original_data. This is a hash of filenames to the data read from the files via YAML library.

Note, that a few things are nevertheless changed and not completely “original”:

• converting short forms to regular forms

• converting non-breaking spaces to regular spaces

• removing duplicate entries from verification_methods and tags

• stripping strings

• adding non-existing attributes of a requirement as empty strings

Example:

# filename.dim
document: myModule

myId:
  text: abc

# script
require 'dim/loader'

l = Dim::Loader.new
l.load(...)

l.original_data["filename.dim"]["module"] == "myModule"
l.original_data["filename.dim"]["myId"]["text"] == "abc"

Use the formatter to write changed data back to the requirements files:

require 'dim/commands/format'

l = Dim::Loader.new
l.load(...)

l.original_data ...

formatter = Dim::Format.new(l)
formatter.execute