CONTEXT RAP IN ENGLISH LATEX
{- This file contains the documentation of RAP in LaTeX format.
   Each concept of the RAP metamodel has its own section, where sections are separated by comments -}

-- Context
PURPOSE PATTERN Context
{+The rules that govern contexts are brought together in one pattern,
in order to formalize contexts and determine their meaning.
-}
CONCEPT Context "A context is a set of statements in a formal language that are true within that context."
PURPOSE CONCEPT Context
{+
Contexts exist in Ampersand for the purpose of dealing with truth.
Within one context there can be no contradictions.
Ampersand's way of dealing with a contradiction is either to resolve it or to separate them in different contexts.
\subsubsection*{Explanation}
The world is full of contradictions. Examples:
\begin{itemize}
\item   Bob's personal income over March 2013 according to Bob's employer differs from Bob's personal income over March 2013 according to the National Tax Authority.
\item   The police can be convinced that Peter X commited the crime, yet his attorney is convinced he is innocent.
\item   One computer system can tell that the person with social security number 721-07-4426 was born on April 27th, 1943, while at the same time another computer system tells me this person was born on May 3rd, 1952.
\end{itemize}

\begin{itemize}
In language philosopy, the idea of a context was invented to give truth a place.
\item   In the context of the National Tax Authority, Bob's personal income over March 2013 can be computed to precisely one amount. In the context of his employment, Bob's personal income over March 2013 can be different, because that is another context.
\item   The job of a court of law is to create a new truth, whose consequences (e.g. imprisonement) can be enforced by law. The court creates a new context, in which conflicts between the (different) truths of both parties are resolved by a decision of the court.
\item   If two computers operate in the same context, yet disagree on matters of fact, we say there is an error. It is likely that in this example someone must step in to determine which date of birth is correct (if any). The error could be detected because we know (i.e. we have a rule that says) that a person must have a unique date of birth.
\end{itemize}

Ampersand uses contexts to organize truth.
Within one context, there is a single truth and there are no contradictions.
For this reason, a context defines a language by means of concepts and relations, in which utterances can be made.
We say that these utterances {\emph make sense} in that context.
-}

PURPOSE PATTERN Rules
{+The rules that govern rules are brought together in one pattern,
in order to formalize rules and determine their meaning.
-}
CONCEPT Rule "A rule is a statement that must be true in each context in which it is valid."
PURPOSE CONCEPT Rule
{+
Rules are used as a concrete reason for people to act, feel or believe.
In philosophy, this is called a 'norm'.
\subsubsection*{Explanation}
A rule differs from a statement in that it must always be true.
Example:
\begin{itemize}
\item   The statement "St. Paul street is a one way street." might be either true or false.
        We just have to check the road signs on St. Paul street to know.
        If, however, the city council decides that St. Paul street is a one way street, we have a rule.
        It is a rule because St. Paul street must be a one way street.
        As long as the appropriate road signs are absent, the situation on the street contradicts the decision of the city council.
\end{itemize}
The word 'must' implies that there is someone who says so.
In this example, the city council, by the authority invested upon it by the law, says that St. Paul street must be a one way street.
The people who are affected by this are called stakeholders.
All contexts in which this rule is valid are called the scope of this rule.
Outside its scope, a rule has no meaning.
For example a rule may be valid in downtown St. Catharines, Ontario, but totally meaningless in Smalltown, NY that does not even have a St. Paul street.
-}

PURPOSE PATTERN Patterns
{+The rules that govern patterns are brought together in one pattern,
in order to formalize patterns and determine their meaning.
-}
CONCEPT Pattern "A pattern is a set of rules that describes a theme or a general reusable solution to a commonly occurring problem."
PURPOSE CONCEPT Pattern
{+
Patterns are used to isolate discussions about a specific theme to a particular group of stakeholders,
who are competent to identify (define, select, invent, etc.) rules that define the theme.

\subsubsection*{Explanation}
A pattern formalizes the agreement among stakeholders on this particular theme.
Design patterns are meant to make solutions reusable.
On top of that, Ampersand advocates "one theme in one pattern".
Stakeholders confine their discussion to one theme, and deliver the result in one pattern.
A pattern is created when a group of stakeholders is trying to agree on a solution for a particular problem.
The agreements they reach are written as rules, which are collected in a pattern.
Therefore, they are independent from a particular context.
\subsubsection*{Example}
The problem of identifying which persons have been using an information system can be solved by making rules
about log-in, users and sessions.
-}

-- Expression
PATTERN Expressions
PURPOSE PATTERN Expressions
{+The rules that govern expressions are brought together in one pattern,
in order to formalize expressions and determine their meaning.
-}
CONCEPT ExpressionID "An expressionID identifies an expression with a context-dependent meaning e.g. a rule assertion, a signal relation, or a relation." TYPE "Text"
CONCEPT Expression "An expression is a relation algebraic term, denoted in Ampersand syntax"  TYPE "Text"
PURPOSE CONCEPT Expression
{+
Ampersand uses relation algebra to formalize phrases.
The formalized phrases are called expressions.
An Ampersand professional uses expressions to calculate with language and to specify information systems and business processes.
\subsubsection*{Explanation}
An expression combines relations with operators.
That results in new relations, the population of which can be calculated from the constituent parts.
This is similar to arithmetic, where for instance the result of expression $(3+5)\times 2$ can be calculated from the constituent numbers.
In ampersand, you calculate with relations rather than numbers.
\subsubsection*{Example}
The problem of identifying which persons have been using an information system can be solved by making rules
about log-in, users and sessions.
-}
ENDPATTERN

PURPOSE PATTERN Specialization
{+Let us briefly recall, by example, what specialization is all about.
Citrus fruit comes in many colors: oranges are orange, lemons are yellow, limes are green, and grapefruits are red, yellow or a mixture of both.
Based on such an observation, we might have a concept $\id{Citrus}$, with a property $\id{color}$.
Since all limes are citrus fruits, we might have a concept $\id{Lime}$.
Every instance of $\id{Lime}$ is a small green and very sour fruit. It is not just a $\id{Lime}$, but it is a $\id{Citrus}$ as well.
This is called {\em specialization}.
The reason we call \id{Lime} a specialization of \id{Citrus} is that every lime (i.e.\ each instance of \id{Lime}) has all the properties of a citrus
and on top of that it has properties specific to limes.

Specialization should be used on intrinsic properties only.
Ask yourself: once a lime, always a lime? If the answer is yes (which sounds right to me), you can use specialization.
Now ask yourself: once an employee, always an employee? The answer to this question is more likely to be no.
Therefore, don't use specialization to say that an employee is a person.
-}

-- Concept
PATTERN Concepts
PURPOSE PATTERN Concepts
{+The rules that govern concepts are brought together in one pattern,
in order to formalize concepts and determine their meaning.
-}
--HJO, 20150420: In het documentatie bestand moet je eigenlijk geen definities opnemen. Die moeten elders --CONCEPT A_Concept "A concept is a name for a category of similar objects."
--HJO, 20150420: In het documentatie bestand moet je eigenlijk geen definities opnemen. Die moeten elders ----CONCEPT ConceptOne "ConceptOne, also known as ONE, is a predefined concept that has the role of universal singleton"
PURPOSE CONCEPT PlainConcept
{+
In order to reason about meaning,
Ampersand has borrowed the idea of a "concept" from the field of semantics
(a part of the philosophy of language).
\subsubsection*{Example}
For example, the city of Amsterdam is an instance of the concept ``City''.
\subsubsection*{Explanation}
Concepts, such as City, Person, Document, Installment, and so on,
allow a designer to talk about things without having them.
We can discuss cities and persons that live in them
without referring to the actual instances of those concepts.
The distinction between an object (Amsterdam) and the corresponding concept (City)
has been studied for a long time [e.g.\ Frege, 1892] and is highly relevant for Ampersand.
-}
ENDPATTERN

PATTERN Populations
PURPOSE PATTERN Populations
{+The rules that govern atoms, pairs, and populations are brought together in one pattern,
in order to formalize them and determine their meaning.
-}

CONCEPT Population "The contents of a Concept or Relation"
PURPOSE CONCEPT Population
{+
Populations are a means to specify a number of true statements that are stored in a relation.
If an information system is generated, the population specified in an Ampersand script
is used as the initial data stored in the database.
This data can subsequently be changed by performing transactions on that database.
\subsubsection*{Example}
\begin{verbatim}
  POPULATION address[Person,Address] CONTAINS
  { ("Peter", "148 Browning Street")
  ; ("Susan", "Dorpsstraat 78")
  ; ("Bart",  "2013 McGinnigall Drive")
  }
\end{verbatim}
\subsubsection*{Explanation}
Populations provide the initial content of a database. 

The word {\emph population} is used sloppily for contexts as well.
It refers the the total of all populations in relations and concepts inside that context.
-}

CONCEPT RelPopu "The content of a relation"
CONCEPT CptPopu "The content of a concept"
CONCEPT PairID "A pairID is an identifier for a pair of atomic terms as an instance of an element with a sign e.g. the population of a relation or the violations of a rule"
CONCEPT Blob "A blob is a pString expected to need more than 256 characters of reserved space." TYPE "Blob"
CONCEPT String "A string is a pString expected to be less than 256 characters."
--HJO20150420: Uitgezet: CONCEPT Conid "A conid is an identifier starting with an uppercase"
--HJO20150420: Uitgezet: CONCEPT Varid "A varid is an identifier starting with a lowercase"
--HJO20150420: Uitgezet: CONCEPT ADLid "An ADLid is an identifier of type pVarid <|> pConid <|> pString"
CONCEPT Gen "A gen, or generalization rule, is the is-a-relation between a more specific and a more generic concept."
CONCEPT Sign "A sign is a relation type signature consisting of a source concept and a target concept."
CONCEPT PropertyRule "A property rule is a rule, that is a property of a user-declared relation"
CONCEPT Property "UNI<|>TOT<|>INJ<|>SUR<|>RFX<|>IRF<|>SYM<|>ASY<|>TRN<|>PROP"
CONCEPT Declaration "A declaration is a statement saying there exists a relation."
CONCEPT Relation "A relation is a set of pairs."
CONCEPT Pair "A pair is an element of a relation, which has a left atom and a right atom."
ENDPATTERN

PURPOSE PATTERN Plugs
{+Atoms are stored in pairs, pairs are stored in relations, relations are stored in plugs, and plugs are stored in databases.
To understand how (binary) relations are stored,
you may perceive a plug as a database table, in which a number of rules are being maintained.

Plugs are defined merely for reasons of efficient storage.
Theoretically, each relation can be stored in a binary plug.
In that situation, the system will work. Such a system is likely to contain more joins to be executed, so a performance problem lures.
Ampersand tries to store multiple relations and concepts in one plug, in order to create tables with multiple columns, but with little data duplication.
The way it works is easily visualized by perceiving each plug as a single worksheet in a spreadsheet.
The first few colums are used as concept tables, in which concepts are stored that are related through generalization and specializations.
The other columns are used to store relations.
-}

PURPOSE RULE "rule allocation"
{+In order to maintain a rule, a plug must have access to the data necessary for detecting violations.
Consequently, the information contents of a plug limits the number of rules it can maintain on its own.
-}

PURPOSE RULE "All isas in one plug"
{+If every atom that is Lime is also Citrus, then creating a new limes must ensure that the newly made atom is a citrus too.
Similarly, deleting the lime must ensure that the atom does not remain existent as a citrus.
For this purpose, all concepts that are related through specialization or generalization are stored in the same plug.
-}

ENDCONTEXT