Three-valued Logic Overview

The term three-value logic refers to the fact that in the HotDocs scripting language there are three acceptable answer values for an IF instruction, or any other expression that evaluates a true/false question: TRUE, FALSE, and UNANSWERED. For example, if a template user doesn't answer a question resulting from an IF instruction during an interview, HotDocs does not process the IF as either true or false, and saves a value of UNANSWERED for that expression in the answer set.

Overview

In most computer languages, a true/false statement must evaluate to either "true" or "false". The HotDocs scripting language is a little more flexible in allowing a third value that is "unanswered". This means that the value is unknown, or indeterminate. Because you can present a variable in an interview using a prompt, every variable in HotDocs can return a value of "unanswered". Unless you require an answer for a particular question, HotDocs can save the value UNANSWERED as an answer in the answer set." Likewise, in a script, any IF instruction (since HotDocs evaluates these as true/false expressions), can return a value of "true", "false", or "unanswered".

Rationale for Three-valued Logic

A template user may or may not answer all variables in an interview, so variables need to accommodate an answer value of UNANSWERED. Three-valued logic works as it does to make your job simpler. With three-valued logic, you don't have to worry about knowing how to handle unanswered values – the HotDocs system handles them for you.

Once your scripting skills advance to the point where you begin to want to handle unanswered questions yourself, you can use an IF instruction with the ANSWERED function to do this.

Common Tasks

Among others, three-valued logic enables you to perform the following common tasks:

Workflow

By accommodating an UNANSWERED question, HotDocs provides a degree of tolerance for situations where a template user does not yet know an answer, i.e., UNANSWERED enables a user to answer some questions in an interview, but skip the ones they don't know. This can be important if a template user is part of a workflow that involves more than one person answering questions within a single interview. The tolerance provided by UNANSWERED as an acceptable value enables a user to answer what they know, inspect their answers, and then pass the interview along to the next person in the workflow.

You can also think of the UNANSWERED feature as a type of debugging feature. For instance, if an answer needs to return true or false, an UNANSWERED value can helps you inspect your template flow, and see in document preview mode what you still need to do for the template to work as you want it to. This feature also enables you to produce a preview without requiring all the data to be present first.

Three-valued Logic Enables Short-circuit Evaluation

Short-circuit evaluation or just "short-circuiting" refers to logic systems that speed up the evaluation of true/false expressions by gathering the minimum relevant information to return a value of true/false.

Three-valued logic is most useful for short-circuiting when HotDocs scans a template to build an interview or assemble a document. When doing this, HotDocs is not just determining whether a logical proposition evaluates to true or false, but also deciding the relevance of questions to ensure that the interview only presents the minimum relevant set of questions to the template user. HotDocs keys off of both UNANSWERED and relevance to present questions in the interview, and to short-circuit so as not to show irrelevant questions.

For example, if your template contains «IF ConditionA AND ConditionB», by default, the interview only ASKs ConditionA. It’s not until a template user answers ConditionA (and ConditionA evaluates to TRUE) that HotDocs can determine whether or not to present ConditionB. The existence of UNANSWERED means that HotDocs can avoid unnecessarily asking and evaluating ConditionB.

To see how this is so, suppose HotDocs didn't short circuit based on UNANSWERED and relevance, but provided more conventional logical short-circuiting. Then if your template contains «IF ConditionA AND ConditionB», your default interview would ask for both ConditionA and ConditionB by default. However, once your template user answers ConditionA – if ConditionA evaluates to FALSE, then ConditionB becomes logically irrelevant. Would you then suddenly remove ConditionB from the interview? That would not make for a smoothly flowing interview.

UNANSWERED in Expression Evaluation versus Record and List Evaluation

Expression evaluation can include UNANSWERED as a value. If any element of an expression equates to UNANSWERED then the whole expression equals UNANSWERED. This is not the same with a record or a list value, since though these both comprise individual values, a list or record has its own value. In other words, a list or a record is a single value. If an individual value within a list or record is UNANSWERED, the record or list is still answered.

UNANSWERED in Selection Variables and Option Sources

Selection variables present another twist on UNANSWERED. While a template user may leave a selection variable unanswered, and HotDocs may store a value of UNANSWERED for that variable, every answer to a Selection variable or Selection List refers to an option in an option list. If an option ceases to exist, the selection variable's reference to that option gets thrown away and does not become an UNANSWERED value.

In the case of Selection List variables, if a template user chooses None of the Above, the list is evaluated as an empty list, which is not the same as UNANSWERED.

Ramifications of UNANSWERED when Evaluating List Literal Comparisons

Before evaluating list literals in a script by using the = operator, you should be aware that when comparing two lists, HotDocs checks for each of the following, in the following order:

the type of each value in the list
the number of values in the list
the order of the values in the list

In addition to the above, when comparing two list literals,

There is no such thing as a list of UNANSWERED values, the value of the list is just UNANSWERED (the corollary is also true – i.e., If any individual item in a list is answered, then the entire list is answered – the same applies to dialogs and records)
If any item in either list is UNANSWERED, the comparison evaluates to UNANSWERED, because you cannot know whether an unknown value is the same as a known value

Unless you keep all these rules in mind, comparisons can seem tricky. For example, [1,2,UNANSWERED] = [1,3,2] is FALSE because HotDocs never gets to notice the UNANSWERED value, because the order of the values is not the same. Similarly, [1,UNANSWERED, 2] = [1,2,3] is FALSE because HotDocs doesn't stop evaluating at the UNANSWERED value, and 2 does not equal 3. On the other hand, List A [1,2,3] = List B [1,unanswered, 3] evaluates to UNANSWERED because you cannot know whether a known value (2) is the same as an unknown value (UNANSWERED) .

Ramifications of UNANSWERED when Evaluating Record Literal Comparisons

Before evaluating record literals in a script by using the = operator, you should be aware that when comparing two records:

HotDocs checks for the existence of all fields in both records, then checks for the values in the fields
The order the fields appear in the records does not matter
Field name comparisons are case sensitive, but the values stored in the fields are case insensitive
If any field's value is UNANSWERED, then the comparison is UNANSWERED

In addition to the above, when comparing two record literals,

There is no such thing as a record of UNANSWERED values, the value of the record is just UNANSWERED (the corollary is also true – i.e., If any individual item in a record is answered, then the entire record is answered – the same applies to dialogs and lists)
If any item in either record is UNANSWERED, the comparison evaluates to UNANSWERED, because you cannot know whether an unknown value is the same as a known value