imports Base

begin

(*<*)

setup{*

open_file_with_prelude 

*}

(*>*)

chapter {* First Steps\label{chp:firststeps} *}

text {*

   \begin{flushright}

  {\em

  ``We will most likely never realize the full importance of painting the Tower,\\ 

  that it is the essential element in the conservation of metal works and the\\ 

  more meticulous the paint job, the longer the tower shall endure.''} \\[1ex]

  Gustave Eiffel, In his book {\em The 300-Meter Tower}.\footnote{The Eiffel Tower has been 

  re-painted 18 times since its initial construction, an average of once every 

  seven years. It takes more than one year for a team of 25 painters to paint the tower 

  from top to bottom.}

  \end{flushright}

  \medskip

  Isabelle programming is done in ML. Just like lemmas and proofs, ML-code for

  Isabelle must be part of a theory. If you want to follow the code given in

  this chapter, we assume you are working inside the theory starting with

  \begin{quote}

  \begin{tabular}{@ {}l}

  \isacommand{imports} Main\\

  \isacommand{begin}\\

  \ldots

  \end{tabular}

  \end{quote}

  We also generally assume you are working with the logic HOL. The examples

  that will be given might need to be adapted if you work in a different logic.

*}

section {* Including ML-Code\label{sec:include} *}

text {*

  The easiest and quickest way to include code in a theory is by using the

  \isacommand{ML}-command. For example:

  \begin{isabelle}

  \begin{graybox}

  \isacommand{ML}~@{text "\<verbopen>"}\isanewline

  \hspace{5mm}@{ML "3 + 4"}\isanewline

  @{text "\<verbclose>"}\isanewline

  @{text "> 7"}\smallskip

  \end{graybox}

  \end{isabelle}

  Like normal Isabelle scripts, \isacommand{ML}-commands can be evaluated by

  using the advance and undo buttons of your Isabelle environment. The code

  inside the \isacommand{ML}-command can also contain value and function

  bindings, for example

*}

ML %gray {* 

  val r = Unsynchronized.ref 0

  fun f n = n + 1 

*}

text {*

  and even those can be undone when the proof script is retracted.  As

  mentioned in the Introduction, we will drop the \isacommand{ML}~@{text

  "\<verbopen> \<dots> \<verbclose>"} scaffolding whenever we show code. The lines

  prefixed with @{text [quotes] ">"} are not part of the code, rather they

  indicate what the response is when the code is evaluated.  There are also

  the commands \isacommand{ML\_val} and \isacommand{ML\_prf} for including

  ML-code. The first evaluates the given code, but any effect on the theory,

  in which the code is embedded, is suppressed. The second needs to be used if

  ML-code is defined inside a proof. For example

  \begin{quote}

  \begin{isabelle}

  \isacommand{lemma}~@{text "test:"}\isanewline

  \isacommand{shows}~@{text [quotes] "True"}\isanewline

  \isacommand{ML\_prf}~@{text "\<verbopen>"}~@{ML "writeln \"Trivial!\""}~@{text "\<verbclose>"}\isanewline

  \isacommand{oops}

  \end{isabelle}

  \end{quote}

  However, both commands will only play minor roles in this tutorial (we will

  always arrange that the ML-code is defined outside proofs).

  Once a portion of code is relatively stable, you usually want to export it

  to a separate ML-file. Such files can then be included somewhere inside a 

  theory by using the command \isacommand{use}. For example

  \begin{quote}

  \begin{tabular}{@ {}l}

  \isacommand{imports} Main\\

  \isacommand{uses}~@{text "(\"file_to_be_included.ML\")"} @{text "\<dots>"}\\

  \isacommand{begin}\\

  \ldots\\

  \isacommand{use}~@{text "\"file_to_be_included.ML\""}\\

  \ldots

  \end{tabular}

  \end{quote}

  The \isacommand{uses}-command in the header of the theory is needed in order 

  to indicate the dependency of the theory on the ML-file. Alternatively, the 

  file can be included by just writing in the header

  \begin{quote}

  \begin{tabular}{@ {}l}

  \isacommand{imports} Main\\

  \isacommand{uses} @{text "\"file_to_be_included.ML\""} @{text "\<dots>"}\\

  \isacommand{begin}\\

  \ldots

  \end{tabular}

  \end{quote}

  Note that no parentheses are given in this case. Note also that the included

  ML-file should not contain any \isacommand{use} itself. Otherwise Isabelle

  is unable to record all file dependencies, which is a nuisance if you have

  to track down errors.

*}

section {* Printing and Debugging\label{sec:printing} *}

text {*

  During development you might find it necessary to inspect data in your

  code. This can be done in a ``quick-and-dirty'' fashion using the function

  @{ML_ind writeln in Output}. For example

  will print out @{text [quotes] "any string"} inside the response buffer of

  Isabelle.  This function expects a string as argument. If you develop under

  PolyML, then there is a convenient, though again ``quick-and-dirty'', method

  for converting values into strings, namely the antiquotation 

  @{text "@{make_string}"}:

  @{ML_response_fake [display,gray] "writeln (@{make_string} 1)" "\"1\""} 

  However, @{text "@{makes_tring}"} only works if the type of what

  is converted is monomorphic and not a function.

  The function @{ML "writeln"} should only be used for testing purposes,

  because any output this function generates will be overwritten as soon as an

  error is raised. For printing anything more serious and elaborate, the

  function @{ML_ind tracing in Output} is more appropriate. This function writes all

  output into a separate tracing buffer. For example:

  It is also possible to redirect the ``channel'' where the string @{text

  "foo"} is printed to a separate file, e.g., in order to prevent ProofGeneral from

  choking on massive amounts of trace output. This redirection can be achieved

  with the code:

*}

ML{*val strip_specials =

let

  fun strip ("\^A" :: _ :: cs) = strip cs

    | strip (c :: cs) = c :: strip cs

    | strip [] = [];

in 

  implode o strip o explode 

end

fun redirect_tracing stream =

 Output.tracing_fn := (fn s =>

    (TextIO.output (stream, (strip_specials s));

     TextIO.output (stream, "\n");

     TextIO.flushOut stream)) *}

text {*

  Calling now

  @{ML [display,gray] "redirect_tracing (TextIO.openOut \"foo.bar\")"}

  will cause that all tracing information is printed into the file @{text "foo.bar"}.

  You can print out error messages with the function @{ML_ind error in Library}; for 

  example:

  @{ML_response_fake [display,gray] 

  "if 0=1 then true else (error \"foo\")" 

"Exception- ERROR \"foo\" raised

At command \"ML\"."}

  This function raises the exception @{text ERROR}, which will then 

  be displayed by the infrastructure. Note that this exception is meant 

  for ``user-level'' error messages seen by the ``end-user''.

  For messages where you want to indicate a genuine program error, then

  use the exception @{text Fail}. Here the infrastructure indicates that this 

  is a low-level exception, and also prints the source position of the ML 

  raise statement. 

  \footnote{\bf FIXME Mention how to work with @{ML_ind debug in Toplevel} and 

  @{ML_ind profiling in Toplevel}.}

*}

(* FIXME*)

(*

ML {* reset Toplevel.debug *}

ML {* fun dodgy_fun () = (raise TYPE ("",[],[]); 1) *}

ML {* fun innocent () = dodgy_fun () *}

ML {* exception_trace (fn () => cterm_of @{theory} (Bound 0)) *}

ML {* exception_trace (fn () => innocent ()) *}

ML {* Toplevel.program (fn () => cterm_of @{theory} (Bound 0)) *}

ML {* Toplevel.program (fn () => innocent ()) *}

*)

text {*

  %Kernel exceptions TYPE, TERM, THM also have their place in situations 

  %where kernel-like operations are involved.  The printing is similar as for 

  %Fail, although there is some special treatment when Toplevel.debug is 

  %enabled.

  Most often you want to inspect data of Isabelle's basic data structures,

  namely @{ML_type term}, @{ML_type typ}, @{ML_type cterm}, @{ML_type ctyp}

  and @{ML_type thm}. Isabelle contains elaborate pretty-printing functions,

  which we will explain in more detail in Section \ref{sec:pretty}. For now

  we just use the functions @{ML_ind writeln in Pretty}  from the structure

  @{ML_struct Pretty} and @{ML_ind pretty_term in Syntax} from the structure

  @{ML_struct Syntax}. For more convenience, we bind them to the toplevel.

*}

text {*

  They can now be used as follows

  @{ML_response_fake [display,gray]

  "pwriteln (pretty_term @{context} @{term \"1::nat\"})"

  "\"1\""}

  If there is more than one term to be printed, you can use the 

*} 

ML{*fun pretty_terms ctxt ts =  

  Pretty.enum "," "" "" (map (pretty_term ctxt) ts)*}

text {*

  You can also print out terms together with their typing information.

  For this you need to set the reference @{ML_ind show_types in Syntax} 

  to @{ML true}.

*}

ML{*show_types := true*}

text {*

  Now @{ML pretty_term} prints out

  @{ML_response_fake [display, gray]

  "pwriteln (pretty_term @{context} @{term \"(1::nat, x)\"})"

  "(1::nat, x::'a)"}

  where @{text 1} and @{text x} are displayed with their inferred type.

  Even more type information can be printed by setting 

  the reference @{ML_ind show_all_types in Syntax} to @{ML true}. 

  In this case we obtain

*}

(*<*)ML %linenos {*show_all_types := true*}

(*>*)

text {*

  @{ML_response_fake [display, gray]

  "pwriteln (pretty_term @{context} @{term \"(1::nat, x)\"})"

  "(Pair::nat \<Rightarrow> 'a \<Rightarrow> nat \<times> 'a) (1::nat) (x::'a)"}

  where @{term Pair} is the term-constructor for products. 

  Other references that influence printing of terms are 

  @{ML_ind show_brackets in Syntax} and @{ML_ind show_sorts in Syntax}. 

*}

(*<*)ML %linenos {*show_types := false; show_all_types := false*}

(*>*)

text {*

  A @{ML_type cterm} can be printed with the following function.

*}

ML{*fun pretty_cterm ctxt ct =  

  pretty_term ctxt (term_of ct)*}

text {*

  Here the function @{ML_ind term_of in Thm} extracts the @{ML_type

  term} from a @{ML_type cterm}.  More than one @{ML_type cterm}s can be

  printed again with @{ML enum in Pretty}.

*} 

ML{*fun pretty_cterms ctxt cts =  

  Pretty.enum "," "" "" (map (pretty_cterm ctxt) cts)*}

text {*

  The easiest way to get the string of a theorem is to transform it

  into a @{ML_type term} using the function @{ML_ind prop_of in Thm}. 

*}

ML{*fun pretty_thm ctxt thm =

  pretty_term ctxt (prop_of thm)*}

text {*

  Theorems include schematic variables, such as @{text "?P"}, 

  @{text "?Q"} and so on. They are needed in Isabelle in order to able to

  instantiate theorems when they are applied. For example the theorem 

  @{thm [source] conjI} shown below can be used for any (typable) 

  instantiation of @{text "?P"} and @{text "?Q"}. 

  @{ML_response_fake [display, gray]

  "pwriteln (pretty_thm @{context} @{thm conjI})"

  "\<lbrakk>?P; ?Q\<rbrakk> \<Longrightarrow> ?P \<and> ?Q"}

  However, in order to improve the readability when printing theorems, we

  convert these schematic variables into free variables using the function

  @{ML_ind  import in Variable}. This is similar to statements like @{text

  "conjI[no_vars]"} on Isabelle's user-level.

*}

ML{*fun no_vars ctxt thm =

let 

  val ((_, [thm']), _) = Variable.import true [thm] ctxt

in

  thm'

end

fun pretty_thm_no_vars ctxt thm =

  pretty_term ctxt (prop_of (no_vars ctxt thm))*}

text {* 

  With this function, theorem @{thm [source] conjI} is now printed as follows:

  @{ML_response_fake [display, gray]

  "pwriteln (pretty_thm_no_vars @{context} @{thm conjI})"

  "\<lbrakk>P; Q\<rbrakk> \<Longrightarrow> P \<and> Q"}

  Again the function @{ML commas} helps with printing more than one theorem. 

*}

ML{*fun pretty_thms ctxt thms =  

  Pretty.enum "," "" "" (map (pretty_thm ctxt) thms)

fun pretty_thms_no_vars ctxt thms =  

  Pretty.enum "," "" "" (map (pretty_thm_no_vars ctxt) thms)*}

text {*

  The printing functions for types are

*}

ML{*fun pretty_typ ctxt ty = Syntax.pretty_typ ctxt ty

fun pretty_typs ctxt tys = Pretty.commas (map (pretty_typ ctxt) tys)*}

text {*

  respectively ctypes

*}

ML{*fun pretty_ctyp ctxt cty = pretty_typ ctxt (typ_of cty)

fun pretty_ctyps ctxt ctys = Pretty.commas (map (pretty_ctyp ctxt) ctys)*}

text {*

  \begin{readmore}

  The simple conversion functions from Isabelle's main datatypes to 

  @{ML_type string}s are implemented in @{ML_file "Pure/Syntax/syntax.ML"}. 

  The references that change the printing information are declared in 

  @{ML_file "Pure/Syntax/printer.ML"}.

  \end{readmore}

  Note that for printing out several ``parcels'' of information that belong

  together, like a warning message consisting of a term and its type, you

  should try to print these parcels together in a single string. Therefore do

  \emph{not} print out information as

@{ML_response_fake [display,gray]

"writeln \"First half,\"; 

writeln \"and second half.\""

"First half,

and second half."}

  but as a single string with appropriate formatting. For example

@{ML_response_fake [display,gray]

"writeln (\"First half,\" ^ \"\\n\" ^ \"and second half.\")"

"First half,

and second half."}

  To ease this kind of string manipulations, there are a number

  of library functions in Isabelle. For example,  the function 

  @{ML_ind cat_lines in Library} concatenates a list of strings 

  and inserts newlines in between each element. 

  @{ML_response_fake [display, gray]

  "writeln (cat_lines [\"foo\", \"bar\"])"

  "foo

bar"}

  Section \ref{sec:pretty} will explain the infrastructure that Isabelle 

  provides for more elaborate pretty printing. 

  \begin{readmore}

  Most of the basic string functions of Isabelle are defined in 

  @{ML_file "Pure/library.ML"}.

  \end{readmore}

*}

section {* Combinators\label{sec:combinators} *}

text {*

  For beginners perhaps the most puzzling parts in the existing code of

  Isabelle are the combinators. At first they seem to greatly obstruct the

  comprehension of code, but after getting familiar with them and handled with

  care, they actually ease the understanding and also the programming.

  The simplest combinator is @{ML_ind I in Library}, which is just the 

  identity function defined as

*}

ML{*fun I x = x*}

text {* 

  Another simple combinator is @{ML_ind K in Library}, defined as 

*}

ML{*fun K x = fn _ => x*}

text {*

  @{ML K} ``wraps'' a function around @{text "x"} that ignores its argument. As a 

  result, @{ML K} defines a constant function always returning @{text x}.

  The next combinator is reverse application, @{ML_ind  "|>" in Basics}, defined as: 

*}

ML{*fun x |> f = f x*}

text {* While just syntactic sugar for the usual function application,

  the purpose of this combinator is to implement functions in a  

  ``waterfall fashion''. Consider for example the function *}

ML %linenosgray{*fun inc_by_five x =

  x |> (fn x => x + 1)

    |> (fn x => (x, x))

    |> fst

    |> (fn x => x + 4)*}

text {*

  which increments its argument @{text x} by 5. It does this by first

  incrementing the argument by 1 (Line 2); then storing the result in a pair

  (Line 3); taking the first component of the pair (Line 4) and finally

  incrementing the first component by 4 (Line 5). This kind of cascading

  manipulations of values is quite common when dealing with theories. The

  reverse application allows you to read what happens in a top-down

  manner. This kind of coding should be familiar, if you have been exposed to

  Haskell's {\it do}-notation. Writing the function @{ML inc_by_five} using

  the reverse application is much clearer than writing

*}

ML{*fun inc_by_five x = fst ((fn x => (x, x)) (x + 1)) + 4*}

text {* or *}

ML{*fun inc_by_five x = 

  ((fn x => x + 4) o fst o (fn x => (x, x)) o (fn x => x + 1)) x*}

text {* and typographically more economical than *}

ML{*fun inc_by_five x =

let val y1 = x + 1