Requirements

What are requirements ?

Requirements allow you to create dependences between your options. To keep it simple, an option’s value will impact other options or OptionDescription properties.

For example :

1
2
3
4
5
6
7
8
9
def requirement_freeze():
    opt1 = ChoiceOption('opt1', '', ('on', 'off'), default = 'on')
    opt2 = StrOption('opt2', '', requires = [{'option': opt1, 'expected': 'off', 'action':'frozen'}])
    rootod = OptionDescription('root', '', [opt1, opt2])
    cfg = Config(rootod)
    cfg.property.read_write()

    cfg.option('opt1').value.set('off')
    cfg.option('opt2').value.set('value')

This little piece of code allows you to freeze opt2 depending on the value of opt1. It also works with various other properties, as “disabled” for example.

Requirement in OptionDescription

You can also use requirements on OptionDescriptions :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
def requirement_OD() :
    opt1 = ChoiceOption('opt1', '', ('on', 'off'), default = 'on')
    opt2 = StrOption('opt2', '', default = 'value')
    opt3 = BoolOption('opt3', '', default = True)
    optdes1 = OptionDescription('optdes1', '', [opt1])
    optdes2 = OptionDescription('optdes2', '', [opt2, opt3], requires = [{'option': opt1, 'expected': 'off', 'action':'disabled'}])
    rootod = OptionDescription('root', '', [optdes1, optdes2])
    cfg = Config(rootod)
    cfg.property.read_write()

    cfg.option('optdes1.opt1').value.set('off')
    cfg.option('optdes2.opt3').value.set(True)
    #>>> tiramisu.error.PropertiesOptionError: cannot access to optiondescription "optdes2" because has property "disabled" (the value of "opt1" is "off")

However, you can’t make an OptionDescription depend on an option included in it. For example :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
def requirement_OD_2():
    opt1 = ChoiceOption('opt1', '', ('on', 'off'), default = 'on')
    opt2 = StrOption('opt2', '', default = 'value')
    opt3 = BoolOption('opt3', '', default = True)
    rootod = OptionDescription('root', '', [opt1, opt2, opt3], requires = [{'option': opt1, 'expected': 'off', 'action':'disabled'}])
    cfg = Config(rootod)
    cfg.property.read_write()

    cfg.option('opt1').value.set('off')
    cfg.option('opt3').value.set(True)
    #No error raised, the OptionDescription hasn't been disabled

Reverse requirement

You can also reverse the requirement : instead of having the effect “if this option has this value, execute this action”, it will have the effect “as soon as this option has not this value anymore, execute this action”. For example :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
def inverse_requirement():
    opt1 = ChoiceOption('opt1', '', ('on', 'off'), default = 'on')
    opt2 = BoolOption('opt2', '', default = True, requires = [{'option': opt1, 'expected': 'on', 'action':'disabled', 'inverse': True}])
    #while opt1's value is 'on', opt2 will not be disabled
    #as soon as opt1's value becomes something else than 'on', opt2 will be disabled
    rootod = OptionDescription('root', '', [opt1, opt2])
    cfg = Config(rootod)
    cfg.property.read_write()

    print(cfg.option('opt2').value.get())
    #opt2 isn't disabled
    cfg.option('opt1').value.set('off')
    print(cfg.option('opt2').value.get())
    #>>> tiramisu.error.PropertiesOptionError: cannot access to option "opt2" because has property "disabled" (the value of "opt1" is not "on")
    #opt2 is now disabled

Transitivity

Requirement is transitive. This means that if you disable an option that is needed in a requirement with an other requirement , the option that required the first one will be disabled too. Seems difficult ?. It isn’t, really. Let’s see with an example :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
def transitive_requirement():
    opt1 = ChoiceOption('opt1', '', ('on', 'off'), default = 'on')
    opt2 = ChoiceOption('opt2', '', ('on', 'off'), default = 'on', requires = [{'option': opt1, 'expected': 'off', 'action':'disabled'}])
    opt3 = BoolOption('opt3', '', default = True, requires = [{'option': opt2, 'expected': 'off', 'action':'disabled'}])
    rootod = OptionDescription('root', '', [opt1, opt2, opt3])
    cfg = Config(rootod)
    cfg.property.read_write()

    cfg.option('opt1').value.set('off')
    print(cfg.option('opt3').value.get())
    #>>> tiramisu.error.PropertiesOptionError: cannot access to option "opt2" because has property "disabled" (the value of "opt1" is not "on")
    #opt3 is disabled, because it depends on opt2 which as been disabled

If you want all your “disabled” or “frozen properties” to work, it’s important to set the config’s properties to “read_write”, because those properties are specific to some acces rights.