theory First_Steps

imports Base

begin

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

text {*

  \begin{flushright}

  {\em ``The most effective debugging tool is still careful thought,\\ 

  coupled with judiciously placed print statements.''} \\[1ex]

  Brian Kernighan, in {\em Unix for Beginners}, 1979

  \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{theory} First\_Steps\\

  \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}

  If you work with ProofGeneral then like normal Isabelle scripts

  \isacommand{ML}-commands can be evaluated by using the advance and

  undo buttons of your Isabelle environment.  If you work with the

  Jedit GUI, then you just have to hover the cursor over the code 

  and you see the evaluated result in the ``Output'' window.

  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 most of

  the time make sure 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{ML\_file}. For example

  \begin{quote}

  \begin{tabular}{@ {}l}

  \isacommand{theory} First\_Steps\\

  \isacommand{imports} Main\\

  \isacommand{begin}\\

  \ldots\\

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

  \ldots

  \end{tabular}

  \end{quote}

*}

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

  @{ML_response_fake [display,gray] "writeln \"any string\"" "\"any string\""}

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

  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. 

  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}. 

  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.

*}

ML %grayML{*val pretty_term = Syntax.pretty_term

val pwriteln = Pretty.writeln*}

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 

  function @{ML_ind commas in Pretty} and @{ML_ind block in Pretty} 

  to separate them.

*} 

ML %grayML{*fun pretty_terms ctxt trms =  

  Pretty.block (Pretty.commas (map (pretty_term ctxt) trms))*}

text {*

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

  For this you need to set the configuration value 

  @{ML_ind show_types in Syntax} to @{ML true}.

*}

ML %grayML{*val show_types_ctxt = Config.put show_types true @{context}*}

text {*

  Now by using this context @{ML pretty_term} prints out

  @{ML_response_fake [display, gray]

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

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

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

  printing of terms include 

  \begin{itemize}

  \item @{ML_ind show_brackets in Syntax} 

  \item @{ML_ind show_sorts in Syntax}

  \item @{ML_ind eta_contract in Syntax}

  \end{itemize}

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

*}

ML %grayML %grayML{*fun pretty_cterm ctxt ctrm =  

  pretty_term ctxt (term_of ctrm)*}

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 commas in Pretty}.

*} 

ML %grayML{*fun pretty_cterms ctxt ctrms =  

  Pretty.block (Pretty.commas (map (pretty_cterm ctxt) ctrms))*}

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 %grayML{*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

  can switch off the question marks as follows:

*}

ML %grayML{*fun pretty_thm_no_vars ctxt thm =

let

  val ctxt' = Config.put show_question_marks false ctxt

in

  pretty_term ctxt' (prop_of thm)

end*}

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 functions @{ML commas} and @{ML block in Pretty} help 

  with printing more than one theorem. 

*}

ML %grayML{*fun pretty_thms ctxt thms =  

  Pretty.block (Pretty.commas (map (pretty_thm ctxt) thms))

fun pretty_thms_no_vars ctxt thms =  

  Pretty.block (Pretty.commas (map (pretty_thm_no_vars ctxt) thms))*}

text {*

  Printing functions for @{ML_type typ} are

*}

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

fun pretty_typs ctxt tys = 

  Pretty.block (Pretty.commas (map (pretty_typ ctxt) tys))*}

text {*

  respectively @{ML_type ctyp}

*}

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

fun pretty_ctyps ctxt ctys = 

  Pretty.block (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 configuration values 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]

"pwriteln (Pretty.str \"First half,\"); 

pwriteln (Pretty.str \"and second half.\")"

"First half,

and second half."}

  but as a single string with appropriate formatting. For example

@{ML_response_fake [display,gray]

"pwriteln (Pretty.str (\"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]

  "pwriteln (Pretty.str (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 %grayML{*fun I x = x*}

text {* 

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

*}

ML %grayML{*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 %grayML{*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 %grayML{*fun inc_by_five x = fst ((fn x => (x, x)) (x + 1)) + 4*}

text {* or *}

ML %grayML{*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 %grayML{*fun inc_by_five x =

let val y1 = x + 1

    val y2 = (y1, y1)

    val y3 = fst y2

    val y4 = y3 + 4

in y4 end*}

text {* 

  Another reason why the let-bindings in the code above are better to be

  avoided: it is more than easy to get the intermediate values wrong, not to 

  mention the nightmares the maintenance of this code causes!

  In Isabelle a ``real world'' example for a function written in 

  the waterfall fashion might be the following code:

*}

ML %linenosgray{*fun apply_fresh_args f ctxt =

    f |> fastype_of

      |> binder_types 

      |> map (pair "z")

      |> Variable.variant_frees ctxt [f]

      |> map Free  

      |> curry list_comb f *}

text {*

  This function takes a term and a context as argument. If the term is of function

  type, then @{ML "apply_fresh_args"} returns the term with distinct variables 

  applied to it. For example below three variables are applied to the term 

  @{term [show_types] "P::nat \<Rightarrow> int \<Rightarrow> unit \<Rightarrow> bool"}:

  @{ML_response_fake [display,gray]

"let

  val trm = @{term \"P::nat \<Rightarrow> int \<Rightarrow> unit \<Rightarrow> bool\"}

  val ctxt = @{context}

in 

  apply_fresh_args trm ctxt

   |> pretty_term ctxt

   |> pwriteln

end" 

  "P z za zb"}

  You can read off this behaviour from how @{ML apply_fresh_args} is coded: in

  Line 2, the function @{ML_ind fastype_of in Term} calculates the type of the

  term; @{ML_ind binder_types in Term} in the next line produces the list of

  argument types (in the case above the list @{text "[nat, int, unit]"}); Line

  4 pairs up each type with the string @{text "z"}; the function @{ML_ind

  variant_frees in Variable} generates for each @{text "z"} a unique name

  avoiding the given @{text f}; the list of name-type pairs is turned into a

  list of variable terms in Line 6, which in the last line is applied by the

  function @{ML_ind list_comb in Term} to the original term. In this last step we have

  to use the function @{ML_ind curry in Library}, because @{ML list_comb}

  expects the function and the variables list as a pair. 

  Functions like @{ML apply_fresh_args} are often needed when constructing

  terms involving fresh variables. For this the infrastructure helps

  tremendously to avoid any name clashes. Consider for example:

   @{ML_response_fake [display,gray]

"let

  val trm = @{term \"za::'a \<Rightarrow> 'b \<Rightarrow> 'c\"}

  val ctxt = @{context}

in

  apply_fresh_args trm ctxt 

   |> pretty_term ctxt

   |> pwriteln

end"

  "za z zb"}

  where the @{text "za"} is correctly avoided.

  The combinator @{ML_ind "#>" in Basics} is the reverse function composition. 

  It can be used to define the following function

*}

ML %grayML{*val inc_by_six = 

  (fn x => x + 1) #> 

  (fn x => x + 2) #> 

  (fn x => x + 3)*}

text {* 

  which is the function composed of first the increment-by-one function and

  then increment-by-two, followed by increment-by-three. Again, the reverse

  function composition allows you to read the code top-down. This combinator

  is often used for setup functions inside the

  \isacommand{setup}- or \isacommand{local\_setup}-command. These functions 

  have to be of type @{ML_type "theory -> theory"}, respectively 

  @{ML_type "local_theory -> local_theory"}. More than one such setup function 

  can be composed with @{ML "#>"}. Consider for example the following code, 

  where we store the theorems @{thm [source] conjI}, @{thm [source] conjunct1} 

  and @{thm [source] conjunct2} under alternative names.

*}  

local_setup %graylinenos {* 

let  

  fun my_note name thm = Local_Theory.note ((name, []), [thm]) #> snd

in

  my_note @{binding "foo_conjI"} @{thm conjI} #>

  my_note @{binding "bar_conjunct1"} @{thm conjunct1} #>

  my_note @{binding "bar_conjunct2"} @{thm conjunct2}

end *}

text {*

  The function @{ML_text "my_note"} in line 3 is just a wrapper for the function 

  @{ML_ind note in Local_Theory} in the structure @{ML_struct Local_Theory}; 

  its purpose is to store a theorem under a name. 

  In lines 5 to 6 we call this function to give alternative names for the three

  theorems. The point of @{ML "#>"} is that you can sequence such function calls. 

  The remaining combinators we describe in this section add convenience for

  the ``waterfall method'' of writing functions. The combinator @{ML_ind tap

  in Basics} allows you to get hold of an intermediate result (to do some

  side-calculations or print out an intermediate result, for instance). The

  function

 *}

ML %linenosgray{*fun inc_by_three x =

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

       |> tap (fn x => pwriteln (Pretty.str (@{make_string} x)))

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