theory Parsing

imports Base "Package/Simple_Inductive_Package"

keywords "foobar" "foobar_trace" :: thy_decl and

         "foobar_goal" "foobar_prove" :: thy_goal

begin

chapter \<open>Parsing\label{chp:parsing}\<close>

text \<open>

  \begin{flushright}

  {\em An important principle underlying the success and popularity of Unix\\ is

  the philosophy of building on the work of others.} \\[1ex]

  Tony Travis in an email about the\\ ``LINUX is obsolete'' debate 

  \end{flushright}

  \begin{flushright}

  {\em

  Document your code as if someone else might have to take it over at any 

  moment and know what to do with it. That person might actually be you -- 

  how often have you had to revisit your own code and thought to yourself, 

  what was I trying to do here?} \\[1ex]

  Phil Chu in ``Seven Habits of Highly Effective Programmers'' 

  \end{flushright}

  Isabelle distinguishes between \emph{outer} and \emph{inner}

  syntax. Commands, such as \isacommand{definition}, \isacommand{inductive}

  and so on, belong to the outer syntax, whereas terms, types and so on belong

  to the inner syntax. For parsing inner syntax, Isabelle uses a rather

  general and sophisticated algorithm, which is driven by priority

  grammars. Parsers for outer syntax are built up by functional parsing

  combinators. These combinators are a well-established technique for parsing,

  which has, for example, been described in Paulson's classic ML-book

  \cite{paulson-ml2}.  Isabelle developers are usually concerned with writing

  these outer syntax parsers, either for new definitional packages or for

  calling methods with specific arguments.

  \begin{readmore}

  The library for writing parser combinators is split up, roughly, into two

  parts: The first part consists of a collection of generic parser combinators

  defined in the structure @{ML_structure Scan} in the file @{ML_file

  "Pure/General/scan.ML"}. The second part of the library consists of

  combinators for dealing with specific token types, which are defined in the

  structure @{ML_structure Parse} in the file @{ML_file

  "Pure/Isar/parse.ML"}. In addition specific parsers for packages are 

  defined in @{ML_file "Pure/Isar/parse_spec.ML"}. Parsers for method arguments 

  are defined in @{ML_file "Pure/Isar/args.ML"}.

  \end{readmore}

\<close>

section \<open>Building Generic Parsers\<close>

text \<open>

  Let us first have a look at parsing strings using generic parsing

  combinators. The function @{ML_ind "$$" in Scan} takes a string as argument and will

  ``consume'' this string from a given input list of strings. ``Consume'' in

  this context means that it will return a pair consisting of this string and

  the rest of the input list. For example:

  @{ML_matchresult [display,gray] 

  \<open>($$ "h") (Symbol.explode "hello")\<close> \<open>("h", ["e", "l", "l", "o"])\<close>}

  @{ML_matchresult [display,gray] 

  \<open>($$ "w") (Symbol.explode "world")\<close> \<open>("w", ["o", "r", "l", "d"])\<close>}

  The function @{ML \<open>$$\<close>} will either succeed (as in the two examples above)

  or raise the exception \<open>FAIL\<close> if no string can be consumed. For

  example trying to parse

  @{ML_response [display,gray] 

  \<open>($$ "x") (Symbol.explode "world")\<close> 

  \<open>exception FAIL NONE raised\<close>}

  will raise the exception \<open>FAIL\<close>. The function @{ML_ind "$$" in Scan} will also

  fail if you try to consume more than a single character.

  There are three exceptions that are raised by the parsing combinators:

  \begin{itemize}

  \item \<open>FAIL\<close> indicates that alternative routes of parsing 

  might be explored. 

  \item \<open>MORE\<close> indicates that there is not enough input for the parser. For example 

  in \<open>($$ "h") []\<close>.

  \item \<open>ABORT\<close> indicates that a dead end is reached. 

  It is used for example in the function @{ML \<open>!!\<close>} (see below).

  \end{itemize}

  However, note that these exceptions are private to the parser and cannot be accessed

  by the programmer (for example to handle them).

  In the examples above we use the function @{ML_ind explode in Symbol} from the

  structure @{ML_structure Symbol}, instead of the more standard library function

  @{ML_ind explode in String}, for obtaining an input list for the parser. The reason is

  that @{ML explode in Symbol} is aware of character

  sequences, for example \<open>\<foo>\<close>, that have a special meaning in

  Isabelle. To see the difference consider

@{ML_matchresult [display,gray]

\<open>String.explode "\<foo> bar"\<close>

\<open>[#"\\", #"<", #"f", #"o", #"o", #">", #" ", #"b", #"a", #"r"]\<close>}

@{ML_matchresult [display,gray]

\<open>Symbol.explode "\<foo> bar"\<close>

\<open>["\<foo>", " ", "b", "a", "r"]\<close>}

  Slightly more general than the parser @{ML \<open>$$\<close>} is the function 

  @{ML_ind one in Scan}, in that it takes a predicate as argument and 

  then parses exactly

  one item from the input list satisfying this predicate. For example the

  following parser either consumes an @{text [quotes] "h"} or a @{text

  [quotes] "w"}:

@{ML_matchresult [display,gray] 

\<open>let 

  val hw = Scan.one (fn x => x = "h" orelse x = "w")

  val input1 = Symbol.explode "hello"

  val input2 = Symbol.explode "world"

in

  (hw input1, hw input2)

end\<close>

    \<open>(("h", ["e", "l", "l", "o"]),("w", ["o", "r", "l", "d"]))\<close>}

  Two parsers can be connected in sequence by using the function @{ML_ind "--" in Scan}. 

  For example parsing \<open>h\<close>, \<open>e\<close> and \<open>l\<close> (in this 

  order) you can achieve by:

  @{ML_matchresult [display,gray] 

  \<open>($$ "h" -- $$ "e" -- $$ "l") (Symbol.explode "hello")\<close>

  \<open>((("h", "e"), "l"), ["l", "o"])\<close>}

  Note how the result of consumed strings builds up on the left as nested pairs.  

  If, as in the previous example, you want to parse a particular string, 

  then you can use the function @{ML_ind this_string in Scan}.

  @{ML_matchresult [display,gray] 

  \<open>Scan.this_string "hell" (Symbol.explode "hello")\<close>

  \<open>("hell", ["o"])\<close>}

  Parsers that explore alternatives can be constructed using the function 

  @{ML_ind  "||" in Scan}. The parser @{ML \<open>(p || q)\<close> for p q} returns the

  result of \<open>p\<close>, in case it succeeds; otherwise it returns the

  result of \<open>q\<close>. For example:

@{ML_matchresult [display,gray] 

\<open>let 

  val hw = $$ "h" || $$ "w"

  val input1 = Symbol.explode "hello"

  val input2 = Symbol.explode "world"

in

  (hw input1, hw input2)

end\<close>

  \<open>(("h", ["e", "l", "l", "o"]), ("w", ["o", "r", "l", "d"]))\<close>}

  The functions @{ML_ind "|--" in Scan} and @{ML_ind "--|" in Scan} work like the sequencing

  function for parsers, except that they discard the item being parsed by the

  first (respectively second) parser. That means the item being dropped is the 

  one that @{ML_ind "|--" in Scan} and @{ML_ind "--|" in Scan} ``point'' away.

  For example:

@{ML_matchresult [display,gray]

\<open>let 

  val just_e = $$ "h" |-- $$ "e" 

  val just_h = $$ "h" --| $$ "e" 

  val input = Symbol.explode "hello"  

in 

  (just_e input, just_h input)

end\<close>

  \<open>(("e", ["l", "l", "o"]), ("h", ["l", "l", "o"]))\<close>}

  The parser @{ML \<open>Scan.optional p x\<close> for p x} returns the result of the parser 

  \<open>p\<close>, in case it succeeds; otherwise it returns 

  the default value \<open>x\<close>. For example:

@{ML_matchresult [display,gray]

\<open>let 

  val p = Scan.optional ($$ "h") "x"

  val input1 = Symbol.explode "hello"

  val input2 = Symbol.explode "world"  

in 

  (p input1, p input2)

end\<close> 

 \<open>(("h", ["e", "l", "l", "o"]), ("x", ["w", "o", "r", "l", "d"]))\<close>}

  The function @{ML_ind option in Scan} works similarly, except no default value can

  be given. Instead, the result is wrapped as an \<open>option\<close>-type. For example:

@{ML_matchresult [display,gray]

\<open>let 

  val p = Scan.option ($$ "h")

  val input1 = Symbol.explode "hello"

  val input2 = Symbol.explode "world"  

in 

  (p input1, p input2)

end\<close> \<open>((SOME "h", ["e", "l", "l", "o"]), (NONE, ["w", "o", "r", "l", "d"]))\<close>}

  The function @{ML_ind ahead in Scan} parses some input, but leaves the original

  input unchanged. For example:

  @{ML_matchresult [display,gray]

  \<open>Scan.ahead (Scan.this_string "foo") (Symbol.explode "foo")\<close> 

  \<open>("foo", ["f", "o", "o"])\<close>} 

  The function @{ML_ind "!!" in Scan} helps with producing appropriate error messages

  during parsing. For example if you want to parse \<open>p\<close> immediately 

  followed by \<open>q\<close>, or start a completely different parser \<open>r\<close>,

  you might write:

  @{ML [display,gray] \<open>(p -- q) || r\<close> for p q r}

  However, this parser is problematic for producing a useful error

  message, if the parsing of @{ML \<open>(p -- q)\<close> for p q} fails. Because with the

  parser above you lose the information that \<open>p\<close> should be followed by \<open>q\<close>.

  To see this assume that \<open>p\<close> is present in the input, but it is not

  followed by \<open>q\<close>. That means @{ML \<open>(p -- q)\<close> for p q} will fail and

  hence the alternative parser \<open>r\<close> will be tried. However, in many

  circumstances this will be the wrong parser for the input ``\<open>p\<close>-followed-by-something''

  and therefore will also fail. The error message is then caused by the failure

  of \<open>r\<close>, not by the absence of \<open>q\<close> in the input. Such

  situation can be avoided when using the function @{ML \<open>!!\<close>}.  This function

  aborts the whole process of parsing in case of a failure and prints an error

  message. For example if you invoke the parser

  @{ML [display,gray] \<open>!! (fn _ => fn _ =>"foo") ($$ "h")\<close>}

  on @{text [quotes] "hello"}, the parsing succeeds

  @{ML_matchresult [display,gray] 

  \<open>(!! (fn _ => fn _ => "foo") ($$ "h")) (Symbol.explode "hello")\<close> 

  \<open>("h", ["e", "l", "l", "o"])\<close>}

  but if you invoke it on @{text [quotes] "world"}

  @{ML_response [display,gray] \<open>(!! (fn _ => fn _ => "foo") ($$ "h")) (Symbol.explode "world")\<close>

                               \<open>exception ABORT fn raised\<close>}

  then the parsing aborts and the error message \<open>foo\<close> is printed. In order to

  see the error message properly, you need to prefix the parser with the function 

  @{ML_ind error in Scan}. For example:

  @{ML_response [display,gray] 

  \<open>Scan.error (!! (fn _ => fn _ => "foo") ($$ "h")) (Symbol.explode "world")\<close>

  \<open>foo\<close>}

  This kind of ``prefixing'' to see the correct error message is usually done by wrappers 

  such as @{ML_ind local_theory in Outer_Syntax} 

  (see Section~\ref{sec:newcommand} which explains this function in more detail). 

  Let us now return to our example of parsing @{ML \<open>(p -- q) || r\<close> for p q

  r}. If you want to generate the correct error message for failure

  of parsing \<open>p\<close>-followed-by-\<open>q\<close>, then you have to write:

\<close>

ML %grayML\<open>fun p_followed_by_q p q r =

let 

  val err_msg = fn _ => p ^ " is not followed by " ^ q

in

  ($$ p -- (!! (fn _ => err_msg) ($$ q))) || ($$ r -- $$ r)

end\<close>

text \<open>

  Running this parser with the arguments

  @{text [quotes] "h"}, @{text [quotes] "e"} and @{text [quotes] "w"}, and 

  the input @{text [quotes] "holle"} 

  @{ML_response [display,gray] \<open>Scan.error (p_followed_by_q "h" "e" "w") (Symbol.explode "holle")\<close>

                               \<open>h is not followed by e\<close>} 

  produces the correct error message. Running it with

  @{ML_matchresult [display,gray] \<open>Scan.error (p_followed_by_q "h" "e" "w") (Symbol.explode "wworld")\<close>

                          \<open>(("w", "w"), ["o", "r", "l", "d"])\<close>}

  yields the expected parsing. 

  The function @{ML \<open>Scan.repeat p\<close> for p} will apply a parser \<open>p\<close> as 

  long as it succeeds. For example:

  @{ML_matchresult [display,gray] \<open>Scan.repeat ($$ "h") (Symbol.explode "hhhhello")\<close> 

                \<open>(["h", "h", "h", "h"], ["e", "l", "l", "o"])\<close>}

  Note that @{ML_ind repeat in Scan} stores the parsed items in a list. The function

  @{ML_ind repeat1 in Scan} is similar, but requires that the parser \<open>p\<close> 

  succeeds at least once.

  Also note that the parser would have aborted with the exception \<open>MORE\<close>, if

  you had it run with the string @{text [quotes] "hhhh"}. This can be avoided by using

  the wrapper @{ML_ind finite in Scan} and the ``stopper-token'' 

  @{ML_ind stopper in Symbol}. With them you can write:

  @{ML_matchresult [display,gray] \<open>Scan.finite Symbol.stopper (Scan.repeat ($$ "h")) (Symbol.explode "hhhh")\<close> 

                \<open>(["h", "h", "h", "h"], [])\<close>}

  The function @{ML stopper in Symbol} is the ``end-of-input'' indicator for parsing strings;

  other stoppers need to be used when parsing, for example, tokens. However, this kind of 

  manually wrapping is often already done by the surrounding infrastructure. 

  The function @{ML_ind repeat in Scan} can be used with @{ML_ind one in Scan} to read any 

  string as in

  @{ML_matchresult [display,gray] 

\<open>let 

   val p = Scan.repeat (Scan.one Symbol.not_eof)

   val input = Symbol.explode "foo bar foo"

in

   Scan.finite Symbol.stopper p input

end\<close> 

\<open>(["f", "o", "o", " ", "b", "a", "r", " ", "f", "o", "o"], [])\<close>}

  where the function @{ML_ind not_eof in Symbol} ensures that we do not read beyond the 

  end of the input string (i.e.~stopper symbol).

  The function @{ML_ind unless in Scan} takes two parsers: if the first one can 

  parse the input, then the whole parser fails; if not, then the second is tried. Therefore

  @{ML_response [display,gray] \<open>Scan.unless ($$ "h") ($$ "w") (Symbol.explode "hello")\<close>

                               "exception FAIL NONE raised"}

  fails, while

  @{ML_matchresult [display,gray] \<open>Scan.unless ($$ "h") ($$ "w") (Symbol.explode "world")\<close>

                          \<open>("w",["o", "r", "l", "d"])\<close>}

  succeeds. 

  The functions @{ML_ind repeat in Scan} and @{ML_ind unless in Scan} can 

  be combined to read any input until a certain marker symbol is reached. In the 

  example below the marker symbol is a @{text [quotes] "*"}.

  @{ML_matchresult [display,gray]

\<open>let 

  val p = Scan.repeat (Scan.unless ($$ "*") (Scan.one Symbol.not_eof))

  val input1 = Symbol.explode "fooooo"

  val input2 = Symbol.explode "foo*ooo"

in

  (Scan.finite Symbol.stopper p input1, 

   Scan.finite Symbol.stopper p input2)

end\<close>

\<open>((["f", "o", "o", "o", "o", "o"], []),

 (["f", "o", "o"], ["*", "o", "o", "o"]))\<close>}

  After parsing is done, you almost always want to apply a function to the parsed 

  items. One way to do this is the function @{ML_ind ">>" in Scan} where 

  @{ML \<open>(p >> f)\<close> for p f} runs 

  first the parser \<open>p\<close> and upon successful completion applies the 

  function \<open>f\<close> to the result. For example

@{ML_matchresult [display,gray]

\<open>let 

  fun double (x, y) = (x ^ x, y ^ y) 

  val parser = $$ "h" -- $$ "e"

in

  (parser >> double) (Symbol.explode "hello")

end\<close>

\<open>(("hh", "ee"), ["l", "l", "o"])\<close>}

  doubles the two parsed input strings; or

  @{ML_matchresult [display,gray] 

\<open>let 

   val p = Scan.repeat (Scan.one Symbol.not_eof)

   val input = Symbol.explode "foo bar foo" 

in

   Scan.finite Symbol.stopper (p >> implode) input

end\<close> 

\<open>("foo bar foo",[])\<close>}

  where the single-character strings in the parsed output are transformed

  back into one string.

  The function @{ML_ind lift in Scan} takes a parser and a pair as arguments. This function applies

  the given parser to the second component of the pair and leaves the  first component 

  untouched. For example

@{ML_matchresult [display,gray]

\<open>Scan.lift ($$ "h" -- $$ "e") (1, Symbol.explode "hello")\<close>

\<open>(("h", "e"), (1, ["l", "l", "o"]))\<close>}

  \footnote{\bf FIXME: In which situations is \<open>lift\<close> useful? Give examples.} 

  Be aware of recursive parsers. Suppose you want to read strings separated by

  commas and by parentheses into a tree datastructure; for example, generating

  the tree corresponding to the string @{text [quotes] "(A, A), (A, A)"} where

  the \<open>A\<close>s will be the leaves.  We assume the trees are represented by the

  datatype:

\<close>

ML %grayML\<open>datatype tree = 

    Lf of string 

  | Br of tree * tree\<close>

text \<open>

  Since nested parentheses should be treated in a meaningful way---for example

  the string @{text [quotes] "((A))"} should be read into a single 

  leaf---you might implement the following parser.

\<close>

ML %grayML\<open>fun parse_basic s = 

  $$ s >> Lf || $$ "(" |-- parse_tree s --| $$ ")"  

and parse_tree s = 

  parse_basic s --| $$ "," -- parse_tree s >> Br || parse_basic s\<close>

text \<open>

  This parser corresponds to the grammar:

  \begin{center}

  \begin{tabular}{lcl}

  \<open><Basic>\<close>  & \<open>::=\<close> & \<open><String> | (<Tree>)\<close>\\

  \<open><Tree>\<close>   & \<open>::=\<close> & \<open><Basic>, <Tree> | <Basic>\<close>\\

  \end{tabular}

  \end{center}

  The parameter \<open>s\<close> is the string over which the tree is parsed. The

  parser @{ML parse_basic} reads either a leaf or a tree enclosed in

  parentheses. The parser @{ML parse_tree} reads either a pair of trees

  separated by a comma, or acts like @{ML parse_basic}. Unfortunately,

  because of the mutual recursion, this parser will immediately run into a

  loop, even if it is called without any input. For example

  @{ML_matchresult_fake_both [display, gray]

  \<open>parse_tree "A"\<close>

  \<open>*** Exception- TOPLEVEL_ERROR raised\<close>}

  raises an exception indicating that the stack limit is reached. Such

  looping parser are not useful, because of ML's strict evaluation of

  arguments. Therefore we need to delay the execution of the

  parser until an input is given. This can be done by adding the parsed

  string as an explicit argument. So the parser above should be implemented

  as follows.

\<close>

ML %grayML\<open>fun parse_basic s xs = 

  ($$ s >> Lf || $$ "(" |-- parse_tree s --| $$ ")") xs 

and parse_tree s xs = 

  (parse_basic s --| $$ "," -- parse_tree s >> Br || parse_basic s) xs\<close>

text \<open>

  While the type of the parser is unchanged by the addition, its behaviour 

  changed: with this version of the parser the execution is delayed until 

  some string is  applied for the argument \<open>xs\<close>. This gives us 

  exactly the parser what we wanted. An example is as follows:

  @{ML_matchresult [display, gray]

  \<open>let

  val input = Symbol.explode "(A,((A))),A"

in

  Scan.finite Symbol.stopper (parse_tree "A") input

end\<close>

  \<open>(Br (Br (Lf "A", Lf "A"), Lf "A"), [])\<close>}

  \begin{exercise}\label{ex:scancmts}

  Write a parser that parses an input string so that any comment enclosed

  within \<open>(*\<dots>*)\<close> is replaced by the same comment but enclosed within

  \<open>(**\<dots>**)\<close> in the output string. To enclose a string, you can use the

  function @{ML \<open>enclose s1 s2 s\<close> for s1 s2 s} which produces the string @{ML \<open>s1 ^ s ^ s2\<close> for s1 s2 s}. Hint: To simplify the task ignore the proper 

  nesting of comments.

  \end{exercise}

\<close>

section \<open>Parsing Theory Syntax\<close>

text \<open>

  Most of the time, however, Isabelle developers have to deal with parsing

  tokens, not strings.  These token parsers have the type:

\<close>