Description

An app of SPPAS does not do one thing: it does what it was told to do. What tells it is a handful of values — a language, a threshold, a file of correspondences, a box ticked — and those values have to come from somebody. That somebody is a person, and she has to be shown what there is to set before she can set it.

This is what shows it, and it is nothing else. It is given what an app lets one set, it shows it in a form which can be acted upon, it takes what was set, it refuses what cannot be used, and it hands back what was decided. It runs nothing, and it does not know what a single one of those values means.

That ignorance is the whole point. A threshold is a number to this domain and nothing more; which threshold, of what, and what happens above it, belongs to the app which declared it. It is what lets one interface serve every app of swapp, and whatever is added next, without being read again.

What an option is made of is established and is not redesigned here: sppasOption carries a key, a type, an un-typed value, a name, a short text and a long description, and its type is one of six — bool, int, float, str, filename, filepath. This document reads that, and adds nothing to it.

Defining the needs

Scope

This document covers what an app lets one set: how it is obtained, how it is shown, how it is changed, what is refused, and how what was set is handed back.

What is not covered, and belongs to whoever declares an option: what it means, what it is for, what a value does to an app, and which values make sense together. What is not covered, and belongs elsewhere: where a file stands and how it gets there, which is the provision of files; and the running itself, which is the app's.

sppasOption and sppasBaseOption are read and not modelled. Their functioning is established, and this document names them as it names a neighbour.

Data dictionary

Two data, and that is all this domain holds of its own.

• D1. A set of options — what an app hands over at one time, and what is handed back to it at one time.
• D2. A refusal — what is said of a value which does not suit the option it was given for. It exists while that value is being given, and no longer.

sppasOption is not one of them. Its functioning is established, it is read and its value is changed, and this document adds nothing to it: it is named here as a neighbour, as the dossier of Convert names the API which reads and writes annotations.

Conceptual model of communication

Three actors border this domain. One is a person, one is what calls it, and one is a neighbouring domain it calls in turn.

Actors

• A1. The person — reads what an option is for, sees the value it holds, changes that value, puts it back to the value it arrived with, and chooses a file where an option takes one.
• A2. An app — hands over a set of options, and gets that set back with the values.
• A3. The provision of files — the neighbouring domain which lets the person designate a file of hers, wherever SPPAS runs.

Flows

• F1. A2 → domain — a set of options [012].
• F2. domain → A1 — the short label of every option [021].
• F3. domain → A1 — the long description of one option, on demand [022].
• F4. domain → A1 — the value of every option, and what it takes to change that value [031], [032].
• F5. domain → A1 — the bounds of an option which has bounds [103].
• F6. A1 → domain — the values she gave, for the whole set, when she validates them [101].
• F7. domain → A1 — one refusal per refused option, naming the option and the value which is expected [202].
• F8. A1 → domain — put one option back to the value it arrived with [301].
• F9. A1 → domain — put every option back to the value it arrived with [302].
• F10. A1 → domain — the request to choose a file, for one option [401].
• F11. domain → A3 — the request for a file of the person.
• F12. A3 → domain — the file she chose.
• F13. domain → A2 — the set of options, with their values [601].

Nothing goes to A2 between F1 and F13. An app hands over its options and hears nothing more until they are handed back: it is not told which value was changed, nor when, nor that one was refused. What it gets is the state at the end, once.

Nothing goes to A3 but a request. This domain asks for a file and receives one; it opens none, reads none, and holds what came back as the value of an option and nothing more.

Two needs of the person are carried by this model and answered elsewhere. The file of [401] is answered by A3, which serves it on the machine of the person as well as from a server. And [501] — finding again the values given the time before — is answered by A2: whether the values of a former setting are restored is that app's decision, it hands over the options carrying the values it wants shown, and F1 carries them. This domain does not know whether a value it is given comes from a setting made yesterday or from a declaration written today, and has no need to.

Conceptual model of data

Three classes. The option is one of them without being modelled: it is an object of SPPAS, its functioning is established, and what is held here is its identity inside a set and the value it had on arrival.

The classes of entities

The relations

R1 is an aggregation: an option is named by its key inside its set, and two apps name an option language without naming the same option. It is also what identifies an option here — its key inside its set.

R2 reads (0,1) on the side of the option: an option carries one refusal or none, the one of the last validation. A value which is taken in leaves no refusal behind, and a validation which refuses nothing leaves none at all.

The value on arrival is the one thing this domain adds to an option of SPPAS. It is what going back goes back to, and without it nothing could. It is written when the set arrives and never afterwards.

Computed, and never held

• The value an option holds now, which is on the option itself and belongs to SPPAS.
• That a value was changed, which is the value now against the value on arrival.
• What is handed back to an app, which is the set itself.

What is not modelled, and why

• The option itself — its kind, its label, its description, its value. All four are established, read where they are written, and nothing here adds to them.
• What an option means, and what two values are together: the app's, and refused nowhere here.
• The file an option designates, which is the provision of files', and of which this domain holds what came back and nothing else.

Conceptual model of treatments

Eight treatments, and they are all this domain does. Every one of them is triggered by one event, and none of them waits for a second: a set arrives, a person acts on it, an app asks for it back.

The events

Organisational model of treatments

One procedure per treatment, numbered as it is. One table and not two: what differs between SPPAS running on the machine of the person and SPPAS running on a server is not what is done here, and not where it is done.

One column holds one value, and that is the result. Everything happens on the server. What the browser holds is the gesture — the box ticked, the number typed, the button pressed — and the values already given, which it carries from one request to the next. It decides nothing, because it knows nothing of what an option accepts. RO1, RO2

Five procedures out of eight are conversational, and they are a request each. Validating what was given is one request and carries the whole set; asking for a description is another, and so is putting an option back. That is what makes [202] hold: the refusals come back on the request which carried the values, beside the options they are about.

PF6 is the one procedure this domain does not perform. It appears in the table so that the request it makes to a neighbour is written down, and so that the one moment something happens outside the server is visible.

Rules of organisation

• RO1 — The values already given are carried from one request to the next by the page, and nothing of a set is held on the server between two requests.
• RO2 — A value is verified where it is taken in, on the server. The browser holds no knowledge of what an option accepts, and refuses nothing of its own.
• RO3 — Every request carries the whole set: the option which is being acted upon, and the values of all the others.
• RO4 — The two contexts of execution are one organisation. Nothing here is done in one and not in the other.
• RO5 — This domain has no page of its own. What it produces is a piece of page an app places in its own, and where that piece stands belongs to that app.
• RO6 — A set of options exists for the time an app is being set up, and this domain keeps none of it afterwards.

RO1 is what the neighbouring dossiers already hold to, and it is what lets one implementation serve a context which knows the person and one which does not. It is also what T08 rests on: an app asking for its options back is answered from what the page transmitted, and from nothing else.

The tables

Each class of entities becomes a table, and its identifier becomes its key. Three tables, and one of them holds a key and nothing else.

R1 is an aggregation: the aggregated table takes the key of the aggregating one, so an option carries the name of its set, and the two together tell one option from another. Two sets carry an option called language without carrying the same option.

The key of a refusal is the key of the option it is about. R2 reads (0,1) on the side of the option, and a key says it better than a rule would: an option carries one refusal or none, and a second value given for it takes the place of the first.

OPTION SET is a key and nothing else. The table exists so that the others may name it; what a set is made of is the options which carry its key.

Not in the tables, and belonging to SPPAS: the kind of an option, its label, its description, and the value it holds. All four are read where they are written, and this document adds nothing to them.

Not in the tables, and computed: whether the value an option holds differs from the value it arrived with.

Where each table stands

Here the machines are named, and not before. There is no database, no file and no disk: the three tables stand in what the page transmits, and nowhere else.

This is the one domain of the four which holds nothing anywhere. It has no place of its own, no lifetime to manage and nothing to sweep: a set exists while an app is being set up, and the last request is the end of it. RO6

What comes back from the page is what the page was given, and nothing here can tell otherwise. The value on arrival travels to the browser and comes back with every request; a page which sent back another one would be putting an option back to a value it never arrived with. What that costs is bounded: a person can only do it to the options she is setting herself, and what an app receives it would have accepted from a keyboard. It is written down rather than guarded against.

Operational model of treatments

The organisational level said by what and when; this says in what tasks. One request is one unit: the set is rebuilt from what the page transmitted, the one thing which was asked is done, and what is to be shown is sent back.

The last column holds one word, and it is the consequence of holding nothing. There is no transaction here, no rollback and no recovery, because there is nothing which could be half written: a request which dies leaves the page as it was, and the next request starts from what the page still holds.

Two requests never meet. Two persons setting up two apps carry two sets, each in its own page, and neither is anywhere the other could reach. No lock is needed, and none is taken.

PF6 and PF7 are two requests with nothing held between them. What ties them is carried by the page and by what the provision of files gives back: which option the file was asked for. A file which comes back for an option nobody asked about is a file which is not taken in.

Where the code goes

In sppas/ui/swapp/services/options/: in the family folder of the services, beside the provision of files, because it is a service and not an app. One module per kind of knowledge.

What each one promises, which is the reason for the cutting:

• Acceptance is given a kind, bounds and a value, and answers. It knows no option, no set and no page, which is what lets every rule of what is accepted be tested with nothing installed.
• The set module is the only one which knows what the page transmits and how a set is rebuilt from it. The day that changes, it is the only one to be read again.
• Presentation decides nothing: what it shows was decided before it was called, and the texts it shows are the ones the options carry.

No module here knows what an option means, what a value does, or what an app will run. There is nowhere for that knowledge to be held, which is the ignorance of the first chapter written as a cut.

The request for a file is made to the provision of files and to nothing else. It is the only tie of this domain to a neighbour, and the set module carries it: what comes back is a value like any other.

Implementation model: MVC

The model holds the set, the value every option arrived with and the rules of what a value may be, and it exposes neither the objects of SPPAS nor the provision of files to the rest of the domain. The controller is called once per request, reads the task the app dispatched, and holds nothing afterwards. The view renders and collects, and takes no decision. Three components, three class diagrams.

What answers is not a response of this domain. An app is reached by a URL and answers with a page; this domain is reached by the app which placed its container in that page. There is therefore no recipe to bake a tree here, and one class stands where an app would have one: the manager, which an app holds.

The classes of the model

/ marks what is derived and held by nobody. What the operations promise is the chapter on the contracts.

OPTION SET and OPTION are one class and not two: an option of a set has no existence outside that set. OptionSet is the only class which touches an sppasOption, and FileForOption the only tie of this domain to a neighbour.

An option is an sppasOption, and nothing here is written for one. Its key, its kind, its value, its name and the text it carries are held by that object, which this domain holds, reads and sets. A class of this domain carrying the same thing under another name would be a second truth.

OptionSet.set_value() sets and does not judge: whether a value may be set is ValueAcceptance's answer, and the controller asks it first. A class which decided what it may hold would hold the rules as well as the data, and the rules would then be in two places.

OptionSet.for_app() gives back the options, every one of them holding the value it holds. It gives back no refusal and no value on arrival: a value which was refused was never set, and what an option arrived with is this domain's own business.

What is tied to what

In yUML

To be read at yuml.me, class diagram.

[OptionSet|options;values on arrival;/changed|rebuild();value_on_arrival_of();set_value();put_back();put_all_back();refusals();for_app()]++1-0..*>[OptionRefusal|option;expected]

[OptionSet]-.->[sppasOption]
[ValueAcceptance|accepts();what_is_expected()]
[FileForOption|ask_for();take_in()]

The classes of the view

A view builds a tree and does nothing else: it decides nothing, refuses nothing, and reaches neither a disk nor a neighbour. What it shows was decided before it was called, and the texts it shows are the ones the options carry. There is one part and not several: what this domain shows is one container, and the page it stands in belongs to the app which placed it.

What is tied to what

In yUML

[OptionsView|populate_tree_content()]-.->[OptionsRecord]

The classes of the controller

OptionsManager is what an app holds, and the only object of this domain it holds. Where an application of swapp is reached by a URL and answers with a page, this domain is reached by the app which placed its container: what answers is not a response of its own but the app's, and this class is where that difference stands.

What is tied to what

In yUML

[OptionsManager|container();consumes();options_for_app()]++1-1>[OptionsController|record|handle();populate_view()]
[OptionsManager]++1-1>[OptionsView]
[OptionsController]++1-1>[OptionsRecord|task;set;to_be_shown|serialize();parse()]
[OptionsRecord]++1-1>[OptionSet]

[OptionsController]-.->[ValueAcceptance]
[OptionsController]-.->[FileForOption]
[OptionsController]-.->[OptionsView]

The states

One thing has states here, and it is what the person reads on a line.

An option is in one of the three and never in two. Refused is not a state of the value which was refused — that value is nowhere — it is a state of the option, and it goes when a value is taken in for it or when the option is put back.

The sequence, from the set to the set

1. An app hands its options over and asks for a container to place in its page.
2. The value every option arrived with is written down, and the container is built: one line per option.
3. The person asks what one of them is for, and the description is shown.
4. She gives values, and validates. Every value is verified against the kind and the bounds of its option; those which suit are taken in, and the others come back as refusals beside their options.
5. She corrects what was refused and validates again, as often as she wants.
6. She asks for a file for an option which takes one. The provision of files answers, and what comes back becomes the value of that option.
7. She puts one option back, or all of them, and what they arrived with stands again.
8. The app asks for its options back, and receives them with the values they hold.

Steps 3 to 7 happen in any order, any number of times, and none of them has to happen at all. What is not in the list is an order imposed by this domain: there is none.

The error policy

What is raised is caught by whatever answers a request, and by nothing below it. A person is never shown what a machine says to itself.

How to read them

pre is what has to be true on the way in, and what the operation does not check; post is what the caller can count on without looking.

What holds everywhere

• Nothing is held between two requests. Every operation is given what it works on, and keeps none of it. RO1
• What is absent gives back an empty thing — no refusal, an empty set, an empty description — and never nothing at all.
• Only OptionSet touches an sppasOption. No other class of this domain knows that such an object exists.
• Only FileForOption speaks to the provision of files.
• Nothing here reads what a value means, and nothing opens a file.
• What is raised is caught by whatever answers a request, and no class below it writes a catch.

Class by class

It sets and it does not judge: what may be set was answered before. It is also the only class which knows that an option is an sppasOption, so it is the only one to be read again the day that object changes.

It reads no disk, holds no set and knows no page. Every rule of what is accepted is therefore verified with nothing installed, which makes it the first class to be tested and the last to surprise.

Where each requirement is held

[501] is the only requirement of this dossier held nowhere in it, and it is written down so that nobody looks for it here. [401] is held by one class which asks a neighbour, which is another thing.

Without anything installed

No disk, no server, no browser, no neighbour. Sixteen tests out of twenty-one run here, which is what the cutting into three modules was for.

TE14 and TE15 are the two which say what a validation is. A set is not accepted or refused as a whole, and a refusal erases nothing: written the other way round, this domain would lose nineteen good values to punish one bad one.

TE5 is written to fail if somebody helps. Two values which make no sense together are both accepted here, because what they mean belongs to the app. The day this test has to be changed, this domain has started to judge.

With a view, and with a neighbour

TE21 is the only test which needs the provision of files. What it checks on this side is the tie: which option a file was asked for, and which option gets it. What the neighbour does with the request is tested in the dossier of that neighbour.

What no test covers, and where they stand

• [501] — finding the values of a former setting. It is held nowhere in this domain, so there is nothing here to test.
• What an option means, and whether two values make sense together: the app's, and judged nowhere here.
• What a page transmits when it has been tampered with. The value on arrival which comes back is taken for what it is, and the physical level says why.
• The WCAG rules, which are verified on the page an app builds, and not on a piece of it.

The tests stand where the project puts its own: in tests/swapp/, which follows the shape of the sources. Sixteen of the twenty-one need nothing at all.