doc-src/IsarAdvanced/Codegen/Thy/Adaption.thy

-theory Adaption
-imports Setup
-begin
-
-setup %invisible {* Code_Target.extend_target ("\<SML>", ("SML", K I)) *}
-
-section {* Adaption to target languages \label{sec:adaption} *}
-
-subsection {* Adapting code generation *}
-
-text {*
-  The aspects of code generation introduced so far have two aspects
-  in common:
-
-  \begin{itemize}
-    \item They act uniformly, without reference to a specific
-       target language.
-    \item They are \emph{safe} in the sense that as long as you trust
-       the code generator meta theory and implementation, you cannot
-       produce programs that yield results which are not derivable
-       in the logic.
-  \end{itemize}
-
-  \noindent In this section we will introduce means to \emph{adapt} the serialiser
-  to a specific target language, i.e.~to print program fragments
-  in a way which accommodates \qt{already existing} ingredients of
-  a target language environment, for three reasons:
-
-  \begin{itemize}
-    \item improving readability and aesthetics of generated code
-    \item gaining efficiency
-    \item interface with language parts which have no direct counterpart
-      in @{text "HOL"} (say, imperative data structures)
-  \end{itemize}
-
-  \noindent Generally, you should avoid using those features yourself
-  \emph{at any cost}:
-
-  \begin{itemize}
-    \item The safe configuration methods act uniformly on every target language,
-      whereas for adaption you have to treat each target language separate.
-    \item Application is extremely tedious since there is no abstraction
-      which would allow for a static check, making it easy to produce garbage.
-    \item More or less subtle errors can be introduced unconsciously.
-  \end{itemize}
-
-  \noindent However, even if you ought refrain from setting up adaption
-  yourself, already the @{text "HOL"} comes with some reasonable default
-  adaptions (say, using target language list syntax).  There also some
-  common adaption cases which you can setup by importing particular
-  library theories.  In order to understand these, we provide some clues here;
-  these however are not supposed to replace a careful study of the sources.
-*}
-
-subsection {* The adaption principle *}
-
-text {*
-  The following figure illustrates what \qt{adaption} is conceptually
-  supposed to be:
-
-  \begin{figure}[here]
-    \begin{tikzpicture}[scale = 0.5]
-      \tikzstyle water=[color = blue, thick]
-      \tikzstyle ice=[color = black, very thick, cap = round, join = round, fill = white]
-      \tikzstyle process=[color = green, semithick, ->]
-      \tikzstyle adaption=[color = red, semithick, ->]
-      \tikzstyle target=[color = black]
-      \foreach \x in {0, ..., 24}
-        \draw[style=water] (\x, 0.25) sin + (0.25, 0.25) cos + (0.25, -0.25) sin
-          + (0.25, -0.25) cos + (0.25, 0.25);
-      \draw[style=ice] (1, 0) --
-        (3, 6) node[above, fill=white] {logic} -- (5, 0) -- cycle;
-      \draw[style=ice] (9, 0) --
-        (11, 6) node[above, fill=white] {intermediate language} -- (13, 0) -- cycle;
-      \draw[style=ice] (15, -6) --
-        (19, 6) node[above, fill=white] {target language} -- (23, -6) -- cycle;
-      \draw[style=process]
-        (3.5, 3) .. controls (7, 5) .. node[fill=white] {translation} (10.5, 3);
-      \draw[style=process]
-        (11.5, 3) .. controls (15, 5) .. node[fill=white] (serialisation) {serialisation} (18.5, 3);
-      \node (adaption) at (11, -2) [style=adaption] {adaption};
-      \node at (19, 3) [rotate=90] {generated};
-      \node at (19.5, -5) {language};
-      \node at (19.5, -3) {library};
-      \node (includes) at (19.5, -1) {includes};
-      \node (reserved) at (16.5, -3) [rotate=72] {reserved}; % proper 71.57
-      \draw[style=process]
-        (includes) -- (serialisation);
-      \draw[style=process]
-        (reserved) -- (serialisation);
-      \draw[style=adaption]
-        (adaption) -- (serialisation);
-      \draw[style=adaption]
-        (adaption) -- (includes);
-      \draw[style=adaption]
-        (adaption) -- (reserved);
-    \end{tikzpicture}
-    \caption{The adaption principle}
-    \label{fig:adaption}
-  \end{figure}
-
-  \noindent In the tame view, code generation acts as broker between
-  @{text logic}, @{text "intermediate language"} and
-  @{text "target language"} by means of @{text translation} and
-  @{text serialisation};  for the latter, the serialiser has to observe
-  the structure of the @{text language} itself plus some @{text reserved}
-  keywords which have to be avoided for generated code.
-  However, if you consider @{text adaption} mechanisms, the code generated
-  by the serializer is just the tip of the iceberg:
-
-  \begin{itemize}
-    \item @{text serialisation} can be \emph{parametrised} such that
-      logical entities are mapped to target-specific ones
-      (e.g. target-specific list syntax,
-        see also \secref{sec:adaption_mechanisms})
-    \item Such parametrisations can involve references to a
-      target-specific standard @{text library} (e.g. using
-      the @{text Haskell} @{verbatim Maybe} type instead
-      of the @{text HOL} @{type "option"} type);
-      if such are used, the corresponding identifiers
-      (in our example, @{verbatim Maybe}, @{verbatim Nothing}
-      and @{verbatim Just}) also have to be considered @{text reserved}.
-    \item Even more, the user can enrich the library of the
-      target-language by providing code snippets
-      (\qt{@{text "includes"}}) which are prepended to
-      any generated code (see \secref{sec:include});  this typically
-      also involves further @{text reserved} identifiers.
-  \end{itemize}
-
-  \noindent As figure \ref{fig:adaption} illustrates, all these adaption mechanisms
-  have to act consistently;  it is at the discretion of the user
-  to take care for this.
-*}
-
-subsection {* Common adaption patterns *}
-
-text {*
-  The @{theory HOL} @{theory Main} theory already provides a code
-  generator setup
-  which should be suitable for most applications.  Common extensions
-  and modifications are available by certain theories of the @{text HOL}
-  library; beside being useful in applications, they may serve
-  as a tutorial for customising the code generator setup (see below
-  \secref{sec:adaption_mechanisms}).
-
-  \begin{description}
-
-    \item[@{theory "Code_Integer"}] represents @{text HOL} integers by big
-       integer literals in target languages.
-    \item[@{theory "Code_Char"}] represents @{text HOL} characters by 
-       character literals in target languages.
-    \item[@{theory "Code_Char_chr"}] like @{text "Code_Char"},
-       but also offers treatment of character codes; includes
-       @{theory "Code_Char"}.
-    \item[@{theory "Efficient_Nat"}] \label{eff_nat} implements natural numbers by integers,
-       which in general will result in higher efficiency; pattern
-       matching with @{term "0\<Colon>nat"} / @{const "Suc"}
-       is eliminated;  includes @{theory "Code_Integer"}
-       and @{theory "Code_Index"}.
-    \item[@{theory "Code_Index"}] provides an additional datatype
-       @{typ index} which is mapped to target-language built-in integers.
-       Useful for code setups which involve e.g. indexing of
-       target-language arrays.
-    \item[@{theory "Code_Message"}] provides an additional datatype
-       @{typ message_string} which is isomorphic to strings;
-       @{typ message_string}s are mapped to target-language strings.
-       Useful for code setups which involve e.g. printing (error) messages.
-
-  \end{description}
-
-  \begin{warn}
-    When importing any of these theories, they should form the last
-    items in an import list.  Since these theories adapt the
-    code generator setup in a non-conservative fashion,
-    strange effects may occur otherwise.
-  \end{warn}
-*}
-
-
-subsection {* Parametrising serialisation \label{sec:adaption_mechanisms} *}
-
-text {*
-  Consider the following function and its corresponding
-  SML code:
-*}
-
-primrec %quote in_interval :: "nat \<times> nat \<Rightarrow> nat \<Rightarrow> bool" where
-  "in_interval (k, l) n \<longleftrightarrow> k \<le> n \<and> n \<le> l"
-(*<*)
-code_type %invisible bool
-  (SML)
-code_const %invisible True and False and "op \<and>" and Not
-  (SML and and and)
-(*>*)
-text %quote {*@{code_stmts in_interval (SML)}*}
-
-text {*
-  \noindent Though this is correct code, it is a little bit unsatisfactory:
-  boolean values and operators are materialised as distinguished
-  entities with have nothing to do with the SML-built-in notion
-  of \qt{bool}.  This results in less readable code;
-  additionally, eager evaluation may cause programs to
-  loop or break which would perfectly terminate when
-  the existing SML @{verbatim "bool"} would be used.  To map
-  the HOL @{typ bool} on SML @{verbatim "bool"}, we may use
-  \qn{custom serialisations}:
-*}
-
-code_type %quotett bool
-  (SML "bool")
-code_const %quotett True and False and "op \<and>"
-  (SML "true" and "false" and "_ andalso _")
-
-text {*
-  \noindent The @{command code_type} command takes a type constructor
-  as arguments together with a list of custom serialisations.
-  Each custom serialisation starts with a target language
-  identifier followed by an expression, which during
-  code serialisation is inserted whenever the type constructor
-  would occur.  For constants, @{command code_const} implements
-  the corresponding mechanism.  Each ``@{verbatim "_"}'' in
-  a serialisation expression is treated as a placeholder
-  for the type constructor's (the constant's) arguments.
-*}
-
-text %quote {*@{code_stmts in_interval (SML)}*}
-
-text {*
-  \noindent This still is not perfect: the parentheses
-  around the \qt{andalso} expression are superfluous.
-  Though the serialiser
-  by no means attempts to imitate the rich Isabelle syntax
-  framework, it provides some common idioms, notably
-  associative infixes with precedences which may be used here:
-*}
-
-code_const %quotett "op \<and>"
-  (SML infixl 1 "andalso")
-
-text %quote {*@{code_stmts in_interval (SML)}*}
-
-text {*
-  \noindent The attentive reader may ask how we assert that no generated
-  code will accidentally overwrite.  For this reason the serialiser has
-  an internal table of identifiers which have to be avoided to be used
-  for new declarations.  Initially, this table typically contains the
-  keywords of the target language.  It can be extended manually, thus avoiding
-  accidental overwrites, using the @{command "code_reserved"} command:
-*}
-
-code_reserved %quote "\<SML>" bool true false andalso
-
-text {*
-  \noindent Next, we try to map HOL pairs to SML pairs, using the
-  infix ``@{verbatim "*"}'' type constructor and parentheses:
-*}
-(*<*)
-code_type %invisible *
-  (SML)
-code_const %invisible Pair
-  (SML)
-(*>*)
-code_type %quotett *
-  (SML infix 2 "*")
-code_const %quotett Pair
-  (SML "!((_),/ (_))")
-
-text {*
-  \noindent The initial bang ``@{verbatim "!"}'' tells the serialiser
-  never to put
-  parentheses around the whole expression (they are already present),
-  while the parentheses around argument place holders
-  tell not to put parentheses around the arguments.
-  The slash ``@{verbatim "/"}'' (followed by arbitrary white space)
-  inserts a space which may be used as a break if necessary
-  during pretty printing.
-
-  These examples give a glimpse what mechanisms
-  custom serialisations provide; however their usage
-  requires careful thinking in order not to introduce
-  inconsistencies -- or, in other words:
-  custom serialisations are completely axiomatic.
-
-  A further noteworthy details is that any special
-  character in a custom serialisation may be quoted
-  using ``@{verbatim "'"}''; thus, in
-  ``@{verbatim "fn '_ => _"}'' the first
-  ``@{verbatim "_"}'' is a proper underscore while the
-  second ``@{verbatim "_"}'' is a placeholder.
-*}
-
-
-subsection {* @{text Haskell} serialisation *}
-
-text {*
-  For convenience, the default
-  @{text HOL} setup for @{text Haskell} maps the @{class eq} class to
-  its counterpart in @{text Haskell}, giving custom serialisations
-  for the class @{class eq} (by command @{command code_class}) and its operation
-  @{const HOL.eq}
-*}
-
-code_class %quotett eq
-  (Haskell "Eq")
-
-code_const %quotett "op ="
-  (Haskell infixl 4 "==")
-
-text {*
-  \noindent A problem now occurs whenever a type which
-  is an instance of @{class eq} in @{text HOL} is mapped
-  on a @{text Haskell}-built-in type which is also an instance
-  of @{text Haskell} @{text Eq}:
-*}
-
-typedecl %quote bar
-
-instantiation %quote bar :: eq
-begin
-
-definition %quote "eq_class.eq (x\<Colon>bar) y \<longleftrightarrow> x = y"
-
-instance %quote by default (simp add: eq_bar_def)
-
-end %quote
-
-code_type %quotett bar
-  (Haskell "Integer")
-
-text {*
-  \noindent The code generator would produce
-  an additional instance, which of course is rejected by the @{text Haskell}
-  compiler.
-  To suppress this additional instance, use
-  @{text "code_instance"}:
-*}
-
-code_instance %quotett bar :: eq
-  (Haskell -)
-
-
-subsection {* Enhancing the target language context \label{sec:include} *}
-
-text {*
-  In rare cases it is necessary to \emph{enrich} the context of a
-  target language;  this is accomplished using the @{command "code_include"}
-  command:
-*}
-
-code_include %quotett Haskell "Errno"
-{*errno i = error ("Error number: " ++ show i)*}
-
-code_reserved %quotett Haskell Errno
-
-text {*
-  \noindent Such named @{text include}s are then prepended to every generated code.
-  Inspect such code in order to find out how @{command "code_include"} behaves
-  with respect to a particular target language.
-*}
-
-end