# VerbTech/QCL Wikibook/An Outline of the Language

< User:VerbTech/QCL Wikibook

# Questions Unrelated

In this section, we assume that the QApairs in your quiz are unrelated.
There are no common patterns to them.
There are no associated probabilities or difficulties with them.
You will effectively be learning how to make a single QApair.

## Question and Answer Unrelated

In this section, we assume that in your QApair the Qpart is unrelated to the Apart.
This will make more sense once you have read the section where they are related.

### Single Question

The Qpart of a QApair is made up of questions.
In this section, we assume your Qpart has just one question in it.

#### Simple Question

Here is the simplest possible sort of QApair you could make:
Try it out by writing a quiz with 5 QApairs, as we have done below:
Place this code in the QCL text box of the Quiz Content Tab.
Then click Begin Quiz in the Quiz Tab and try the test.
If you have not changed any of the default settings, then you will have to type the answer exactly and press return (or click the Submit button, if you are using a different Quiz app).
The line beginning with // is called a single-line comment.
Everything on that line is ignored by the interpreter.
A multi-line comment looks like this:
The syntax is to begin it with /* and end it with */.
It is useful for commenting out blocks of QApairs. That is, turning off a group of QApairs.
The last thing to say about this is that if you want to use a semicolon ; in your question or answer, then you have to type \;
\ Is called an escape character.
These are needed because QCL uses some characters that you may want to put in your content.
In the following table, the characters on the left are ones that you can only use as part of your content, if you use the character sequence on the right instead:
       Character Character Escape Sequence ; \; { \{ } \} \ \\ [ \[ ] \]
So, to make it clear, if we wanted the question:
We would have to use:

#### Single Varytag

A varytag is a part of a question that can change its contents at run time.
Run time is when the code is being processed and the quiz is being done.
Here is a simple example of a varytag in the Qpart of a QApair:
When this QApair is used in the quiz, it has a 1 in 3 chance of being asked as any of the following:
capital, capital city, and seat of government are possibilities of the varytag.
Notice that the following two questions are the same to the interpreter:
* If you repeat a possibility like this:
    What is the {capital|capital|capital|capital city|seat of government} of Australia?;;Canberra
    then the chances of that possibility being chosen are increased correspondingly.
    In this case, capital has a 3/5 chance of being chosen for that place.
* If you substitute a varytag for a possibility like this:
    What is the {{capital|capital city}|seat of government} of Australia?;;Canberra
    then that also changes the chances that the more nested possibilities will be chosen.
    In this case, {capital|capital city} is just as likely to be chosen as government.
Rather than nesting or repeating possibilities, it is better to assign probabilities, as we will see in the next section.

#### Single Varytag with Probabilities

The possibilities of a varytag can be assigned probabilities.
Here is an example of a varytag in a QApair with probabilities assigned:
2 is the raw probability of the possibility capital. Similarly, 3 is the raw probability of the possibility capital city.
If you add the raw probabilities of this varytag, you get 10.
2/10 (or 0.2 or 20%) is the probability of the possibility capital.
That is, there is a 2/10 likelihood of being asked this:
If raw probabilities are missing, like this:
then the interpreter assumes the remaining ones have raw probabilities of 1, like this:
The raw probabilities must be non-zero positive integers (from the set: {1,2,3,...}).
[%2]capital is the first possibility of the varytag {[%2]capital|[%3]capital city|[%1]seat of government}.
capital is its content.
[%2] is its raw probability, and must come before its content.
[%2] is called a probability tag.
Probability tags are a type of structure tag. You will meet more of these along the way.
The first symbol inside the structure tag, which is % in this case, is important. It indicates the purpose of the structure tag.
Just remember that % is the Percentage sign and stands for Probability.

#### Multiple Varytags related by Anchors

Sometimes, you will want possibilities in different varytags to be tied together.
For instance, you might want an to come before words beginning with vowels, and a to come before words beginning with consonants.
For this, you will need anchors.
Here is a simple example of anchors in use below:
Anchors are another kind of structure tag, and so are placed in square brackets [ ], too.
They always begin with an at sign @, and can be any combination of letters or numbers or the underscore character _.
It is usual, though, to use numbers.
Just remember that @ is the At sign and stands for Anchor.
The interpreter reads it from left to right and works like this:
In the first varytag, it chooses a or an.
This is called evaluation of the varytag.
Supposing it chose a, the current construction of the question would be:
a has the anchor 1.
It tracks this in something called the ongoing anchor set.
The ongoing anchor set currently has only the element 1 in it.
When it meets the next varytag, it excludes some of the possibilities based on the ongoing anchor set.
To not be excluded and remain a possibility, the possibility must have:
* No anchors
    OR
* At least one anchor which is in the ongoing anchor set.
In this case, the varytag would turn into {cat|dog|horse|squirrel}.
Which it might evaluate, with a 1 in 4 chance, to dog resulting in:

#### Multiple Varytags with Forced Evaluation Order

In the previous section, we saw that the question wasn’t quite fair, because the 7 animals didn't each have a 1 in 7 chance of being chosen.
To solve this, we can force the order of evaluation of the varytags.
Here is how we do it:
This means that the second tag would be evaluated first.
This still doesn’t solve the problem. To do that we need to assign probabilities to the possibilities like this:
This type of structure tag, [#1], is called an index tag.
It must be of the form [#n], where n is a non-zero positive integer ({1,2,3,...}).
If there are some varytags with varytag indexes, and some without, then the varytags with them are evaluated first, in the correct order, followed by those without them, from left to right.
You can use repeated anchor tags to repeat a varytag like this:
If the varytag was evaluated as Mark, then the question would appear as this:
You may have a lot of "what if...?" questions about this feature.
To answer them, you should try them out and understand how the interpreter works with the feature.
Here's what happens:
The interpreter goes from left to right looking for the first index tag that has a varytag immediately after it.
It is [#1]{A|E|O}.
It then evaluates this. Suppose it evaluated it to be O.
Then it goes from left to right again and replaces all parts of the line that are [#1], like this:
Which it may carry on further to evaluate as:
Notice how it does not care about varytags with the index tag of [#1] that come after the first one.
It just looks for [#1] wherever it is and replaces it with O.
Finally, if for some odd reason you would like to have the actual piece of text [#1] in your question, then you have to use the escape characters mentioned earlier. Like this: \[#1\]

### Multiple Questions

You can have multiple questions in the Qpart of the QApair. Here is an example:
There is a 1 in 3 chance that any of the questions in particular will be chosen.
To alter that probability, you can do the following trick:
A QApair may be spanned over several lines, if it is felt to be easier on the eyes.
Here is an example:
Blank lines will be ignored.
The braces { } must be on their own lines.

### Single Answer

So far we have only shown a QApair where the Apart has one answer in it:

#### Multiple Lines in the Question or Answer

It is possible that your answer may have multiple lines in it.
Unfortunately, the enter button is used to make both a newline and to submit the answer.
To solve this problem, go in the Session Settings Tab and type the following code:
This tells the interpreter that in your next session, you will type ++ to submit your answer.
That is, as soon as the interpreter notices ++ in the Answer Box it takes all the text before ++ and evaluates the correctness of it.
Of course, there is no reason to choose ++. It can be what you like.
If it is blank, the interpreter only moves on to the next question, if the contents of the Answer Box are correct.
(You can find out more about how to change your quiz session, in the session settings section)
Back to the problem; a newline can be included in your character using the escape sequence \n
So in this QApair:
The question is asked as:
And the answer is expected to be:
(And of course, you would type ++ to submit that.)

#### Varytags

As with questions, you can include varytags in the answer:
This means that The capital of Australia., The capital city of Australia., and The seat of government of Australia are all acceptable answers to the question What is Canberra?

#### Anchors

As with questions, you can use anchor tags to control the evaluation of the varytags and the range of acceptable answers:

#### Forced Evaluation Order

Currently, QCL does not support the index tags in answers.

#### Uppercase and Lowercase Insensitivity

For the QApair:
We accept the answers Apple. and Apple
But, we may want to accept the answer apple
It is tedious to type:
We may be smart about this by typing something like:
However, this makes the code hard to read, and it is a common enough problem for a shortcut to exist:
The structure tag [;Aa] is a type of leniency tag. They feature in the Apart.
It applies to the varytag immediately following it.
It means that Apple., apple., and aPpLe. are all viewed as the same by QCL.

#### Substrings

It is very hard to predict what a user may answer in response to a question. For the question:
they may respond with Apple., An apple, Apple?.
A string in computing is just a sequence of characters, like abcde, and a substring is just a block contained within that sequence, like bc, cde, or even abcde itself.
We might care only if the answer is a substring of the user's attempted answer.
We can do that using the leniency tag [;sub] like this:
All of these would pass as answers:

### Multiple Answers
## Question and Answer Related

In this section, we assume that the Qpart and the Apart in your QApairs are related.

### Substitutions

One common application for QCL is to be posed a sentence such as:

### List Answers
# Common Applications
## General

In this section, we cover the several general types of questions that are frequently used in quizzes.

### Multiple Choice

Multiple choice questions look like this: