src/Doc/Isar_Ref/Outer_Syntax.thy
author wenzelm
Tue Jan 16 15:42:21 2018 +0100 (2018-01-16 ago)
changeset 67448 dbb1f02e667d
parent 66916 aca50a1572c5
child 67477 44b018d4aa5f
permissions -rw-r--r--
more documentation;
     1 (*:maxLineLen=78:*)
     2 
     3 theory Outer_Syntax
     4   imports Main Base
     5 begin
     6 
     7 chapter \<open>Outer syntax --- the theory language \label{ch:outer-syntax}\<close>
     8 
     9 text \<open>
    10   The rather generic framework of Isabelle/Isar syntax emerges from three main
    11   syntactic categories: \<^emph>\<open>commands\<close> of the top-level Isar engine (covering
    12   theory and proof elements), \<^emph>\<open>methods\<close> for general goal refinements
    13   (analogous to traditional ``tactics''), and \<^emph>\<open>attributes\<close> for operations on
    14   facts (within a certain context). Subsequently we give a reference of basic
    15   syntactic entities underlying Isabelle/Isar syntax in a bottom-up manner.
    16   Concrete theory and proof language elements will be introduced later on.
    17 
    18   \<^medskip>
    19   In order to get started with writing well-formed Isabelle/Isar documents,
    20   the most important aspect to be noted is the difference of \<^emph>\<open>inner\<close> versus
    21   \<^emph>\<open>outer\<close> syntax. Inner syntax is that of Isabelle types and terms of the
    22   logic, while outer syntax is that of Isabelle/Isar theory sources
    23   (specifications and proofs). As a general rule, inner syntax entities may
    24   occur only as \<^emph>\<open>atomic entities\<close> within outer syntax. For example, the
    25   string \<^verbatim>\<open>"x + y"\<close> and identifier \<^verbatim>\<open>z\<close> are legal term specifications within a
    26   theory, while \<^verbatim>\<open>x + y\<close> without quotes is not.
    27 
    28   Printed theory documents usually omit quotes to gain readability (this is a
    29   matter of {\LaTeX} macro setup, say via \<^verbatim>\<open>\isabellestyle\<close>, see also @{cite
    30   "isabelle-system"}). Experienced users of Isabelle/Isar may easily
    31   reconstruct the lost technical information, while mere readers need not care
    32   about quotes at all.
    33 \<close>
    34 
    35 
    36 section \<open>Commands\<close>
    37 
    38 text \<open>
    39   \begin{matharray}{rcl}
    40     @{command_def "print_commands"}\<open>\<^sup>*\<close> & : & \<open>any \<rightarrow>\<close> \\
    41     @{command_def "help"}\<open>\<^sup>*\<close> & : & \<open>any \<rightarrow>\<close> \\
    42   \end{matharray}
    43 
    44   @{rail \<open>
    45     @@{command help} (@{syntax name} * )
    46   \<close>}
    47 
    48   \<^descr> @{command "print_commands"} prints all outer syntax keywords
    49   and commands.
    50 
    51   \<^descr> @{command "help"}~\<open>pats\<close> retrieves outer syntax
    52   commands according to the specified name patterns.
    53 \<close>
    54 
    55 
    56 subsubsection \<open>Examples\<close>
    57 
    58 text \<open>
    59   Some common diagnostic commands are retrieved like this (according to usual
    60   naming conventions):
    61 \<close>
    62 
    63 help "print"
    64 help "find"
    65 
    66 
    67 section \<open>Lexical matters \label{sec:outer-lex}\<close>
    68 
    69 text \<open>
    70   The outer lexical syntax consists of three main categories of syntax tokens:
    71 
    72     \<^enum> \<^emph>\<open>major keywords\<close> --- the command names that are available
    73     in the present logic session;
    74 
    75     \<^enum> \<^emph>\<open>minor keywords\<close> --- additional literal tokens required
    76     by the syntax of commands;
    77 
    78     \<^enum> \<^emph>\<open>named tokens\<close> --- various categories of identifiers etc.
    79 
    80   Major keywords and minor keywords are guaranteed to be disjoint. This helps
    81   user-interfaces to determine the overall structure of a theory text, without
    82   knowing the full details of command syntax. Internally, there is some
    83   additional information about the kind of major keywords, which approximates
    84   the command type (theory command, proof command etc.).
    85 
    86   Keywords override named tokens. For example, the presence of a command
    87   called \<^verbatim>\<open>term\<close> inhibits the identifier \<^verbatim>\<open>term\<close>, but the string \<^verbatim>\<open>"term"\<close> can
    88   be used instead. By convention, the outer syntax always allows quoted
    89   strings in addition to identifiers, wherever a named entity is expected.
    90 
    91   When tokenizing a given input sequence, the lexer repeatedly takes the
    92   longest prefix of the input that forms a valid token. Spaces, tabs, newlines
    93   and formfeeds between tokens serve as explicit separators.
    94 
    95   \<^medskip>
    96   The categories for named tokens are defined once and for all as follows.
    97 
    98   \begin{center}
    99   \begin{supertabular}{rcl}
   100     @{syntax_def short_ident} & = & \<open>letter (subscript\<^sup>? quasiletter)\<^sup>*\<close> \\
   101     @{syntax_def long_ident} & = & \<open>short_ident(\<close>\<^verbatim>\<open>.\<close>\<open>short_ident)\<^sup>+\<close> \\
   102     @{syntax_def sym_ident} & = & \<open>sym\<^sup>+  |\<close>~~\<^verbatim>\<open>\\<close>\<^verbatim>\<open><\<close>\<open>short_ident\<close>\<^verbatim>\<open>>\<close> \\
   103     @{syntax_def nat} & = & \<open>digit\<^sup>+\<close> \\
   104     @{syntax_def float} & = & @{syntax_ref nat}\<^verbatim>\<open>.\<close>@{syntax_ref nat}~~\<open>|\<close>~~\<^verbatim>\<open>-\<close>@{syntax_ref nat}\<^verbatim>\<open>.\<close>@{syntax_ref nat} \\
   105     @{syntax_def term_var} & = & \<^verbatim>\<open>?\<close>\<open>short_ident  |\<close>~~\<^verbatim>\<open>?\<close>\<open>short_ident\<close>\<^verbatim>\<open>.\<close>\<open>nat\<close> \\
   106     @{syntax_def type_ident} & = & \<^verbatim>\<open>'\<close>\<open>short_ident\<close> \\
   107     @{syntax_def type_var} & = & \<^verbatim>\<open>?\<close>\<open>type_ident  |\<close>~~\<^verbatim>\<open>?\<close>\<open>type_ident\<close>\<^verbatim>\<open>.\<close>\<open>nat\<close> \\
   108     @{syntax_def string} & = & \<^verbatim>\<open>"\<close> \<open>\<dots>\<close> \<^verbatim>\<open>"\<close> \\
   109     @{syntax_def altstring} & = & \<^verbatim>\<open>`\<close> \<open>\<dots>\<close> \<^verbatim>\<open>`\<close> \\
   110     @{syntax_def cartouche} & = & @{verbatim "\<open>"} \<open>\<dots>\<close> @{verbatim "\<close>"} \\
   111     @{syntax_def verbatim} & = & \<^verbatim>\<open>{*\<close> \<open>\<dots>\<close> \<^verbatim>\<open>*}\<close> \\[1ex]
   112 
   113     \<open>letter\<close> & = & \<open>latin  |\<close>~~\<^verbatim>\<open>\\<close>\<^verbatim>\<open><\<close>\<open>latin\<close>\<^verbatim>\<open>>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\\<close>\<^verbatim>\<open><\<close>\<open>latin latin\<close>\<^verbatim>\<open>>\<close>~~\<open>|  greek  |\<close> \\
   114     \<open>subscript\<close> & = & \<^verbatim>\<open>\<^sub>\<close> \\
   115     \<open>quasiletter\<close> & = & \<open>letter  |  digit  |\<close>~~\<^verbatim>\<open>_\<close>~~\<open>|\<close>~~\<^verbatim>\<open>'\<close> \\
   116     \<open>latin\<close> & = & \<^verbatim>\<open>a\<close>~~\<open>| \<dots> |\<close>~~\<^verbatim>\<open>z\<close>~~\<open>|\<close>~~\<^verbatim>\<open>A\<close>~~\<open>|  \<dots> |\<close>~~\<^verbatim>\<open>Z\<close> \\
   117     \<open>digit\<close> & = & \<^verbatim>\<open>0\<close>~~\<open>|  \<dots> |\<close>~~\<^verbatim>\<open>9\<close> \\
   118     \<open>sym\<close> & = & \<^verbatim>\<open>!\<close>~~\<open>|\<close>~~\<^verbatim>\<open>#\<close>~~\<open>|\<close>~~\<^verbatim>\<open>$\<close>~~\<open>|\<close>~~\<^verbatim>\<open>%\<close>~~\<open>|\<close>~~\<^verbatim>\<open>&\<close>~~\<open>|\<close>~~\<^verbatim>\<open>*\<close>~~\<open>|\<close>~~\<^verbatim>\<open>+\<close>~~\<open>|\<close>~~\<^verbatim>\<open>-\<close>~~\<open>|\<close>~~\<^verbatim>\<open>/\<close>~~\<open>|\<close> \\
   119     & & \<^verbatim>\<open><\<close>~~\<open>|\<close>~~\<^verbatim>\<open>=\<close>~~\<open>|\<close>~~\<^verbatim>\<open>>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>?\<close>~~\<open>|\<close>~~\<^verbatim>\<open>@\<close>~~\<open>|\<close>~~\<^verbatim>\<open>^\<close>~~\<open>|\<close>~~\<^verbatim>\<open>_\<close>~~\<open>|\<close>~~\<^verbatim>\<open>|\<close>~~\<open>|\<close>~~\<^verbatim>\<open>~\<close> \\
   120     \<open>greek\<close> & = & \<^verbatim>\<open>\<alpha>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<beta>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<gamma>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<delta>\<close>~~\<open>|\<close> \\
   121           &   & \<^verbatim>\<open>\<epsilon>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<zeta>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<eta>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<theta>\<close>~~\<open>|\<close> \\
   122           &   & \<^verbatim>\<open>\<iota>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<kappa>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<mu>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<nu>\<close>~~\<open>|\<close> \\
   123           &   & \<^verbatim>\<open>\<xi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<pi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<rho>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<sigma>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<tau>\<close>~~\<open>|\<close> \\
   124           &   & \<^verbatim>\<open>\<upsilon>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<phi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<chi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<psi>\<close>~~\<open>|\<close> \\
   125           &   & \<^verbatim>\<open>\<omega>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Gamma>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Delta>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Theta>\<close>~~\<open>|\<close> \\
   126           &   & \<^verbatim>\<open>\<Lambda>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Xi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Pi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Sigma>\<close>~~\<open>|\<close> \\
   127           &   & \<^verbatim>\<open>\<Upsilon>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Phi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Psi>\<close>~~\<open>|\<close>~~\<^verbatim>\<open>\<Omega>\<close> \\
   128   \end{supertabular}
   129   \end{center}
   130 
   131   A @{syntax_ref term_var} or @{syntax_ref type_var} describes an unknown,
   132   which is internally a pair of base name and index (ML type @{ML_type
   133   indexname}). These components are either separated by a dot as in \<open>?x.1\<close> or
   134   \<open>?x7.3\<close> or run together as in \<open>?x1\<close>. The latter form is possible if the base
   135   name does not end with digits. If the index is 0, it may be dropped
   136   altogether: \<open>?x\<close> and \<open>?x0\<close> and \<open>?x.0\<close> all refer to the same unknown, with
   137   basename \<open>x\<close> and index 0.
   138 
   139   The syntax of @{syntax_ref string} admits any characters, including
   140   newlines; ``\<^verbatim>\<open>"\<close>'' (double-quote) and ``\<^verbatim>\<open>\\<close>'' (backslash) need to be
   141   escaped by a backslash; arbitrary character codes may be specified as
   142   ``\<^verbatim>\<open>\\<close>\<open>ddd\<close>'', with three decimal digits. Alternative strings according to
   143   @{syntax_ref altstring} are analogous, using single back-quotes instead.
   144 
   145   The body of @{syntax_ref verbatim} may consist of any text not containing
   146   ``\<^verbatim>\<open>*}\<close>''; this allows to include quotes without further escapes, but there
   147   is no way to escape ``\<^verbatim>\<open>*}\<close>''. Cartouches do not have this limitation.
   148 
   149   A @{syntax_ref cartouche} consists of arbitrary text, with properly balanced
   150   blocks of ``@{verbatim "\<open>"}~\<open>\<dots>\<close>~@{verbatim "\<close>"}''. Note that the rendering
   151   of cartouche delimiters is usually like this: ``\<open>\<open> \<dots> \<close>\<close>''.
   152 
   153   Source comments take the form \<^verbatim>\<open>(*\<close>~\<open>\<dots>\<close>~\<^verbatim>\<open>*)\<close> and may be nested, although
   154   the user-interface might prevent this. Note that this form indicates source
   155   comments only, which are stripped after lexical analysis of the input. The
   156   Isar syntax also provides proper \<^emph>\<open>document comments\<close> that are considered as
   157   part of the text (see \secref{sec:comments}).
   158 
   159   Common mathematical symbols such as \<open>\<forall>\<close> are represented in Isabelle as \<^verbatim>\<open>\<forall>\<close>.
   160   There are infinitely many Isabelle symbols like this, although proper
   161   presentation is left to front-end tools such as {\LaTeX} or Isabelle/jEdit.
   162   A list of predefined Isabelle symbols that work well with these tools is
   163   given in \appref{app:symbols}. Note that \<^verbatim>\<open>\<lambda>\<close> does not belong to the
   164   \<open>letter\<close> category, since it is already used differently in the Pure term
   165   language.
   166 \<close>
   167 
   168 
   169 section \<open>Common syntax entities\<close>
   170 
   171 text \<open>
   172   We now introduce several basic syntactic entities, such as names, terms, and
   173   theorem specifications, which are factored out of the actual Isar language
   174   elements to be described later.
   175 \<close>
   176 
   177 
   178 subsection \<open>Names\<close>
   179 
   180 text \<open>
   181   Entity @{syntax name} usually refers to any name of types, constants,
   182   theorems etc.\ Quoted strings provide an escape for non-identifier names or
   183   those ruled out by outer syntax keywords (e.g.\ quoted \<^verbatim>\<open>"let"\<close>).
   184 
   185   @{rail \<open>
   186     @{syntax_def name}: @{syntax short_ident} | @{syntax long_ident} |
   187       @{syntax sym_ident} | @{syntax nat} | @{syntax string}
   188     ;
   189     @{syntax_def par_name}: '(' @{syntax name} ')'
   190   \<close>}
   191 
   192   A @{syntax_def system_name} is like @{syntax name}, but it excludes
   193   white-space characters and needs to conform to file-name notation.
   194 \<close>
   195 
   196 
   197 subsection \<open>Numbers\<close>
   198 
   199 text \<open>
   200   The outer lexical syntax (\secref{sec:outer-lex}) admits natural numbers and
   201   floating point numbers. These are combined as @{syntax int} and @{syntax
   202   real} as follows.
   203 
   204   @{rail \<open>
   205     @{syntax_def int}: @{syntax nat} | '-' @{syntax nat}
   206     ;
   207     @{syntax_def real}: @{syntax float} | @{syntax int}
   208   \<close>}
   209 
   210   Note that there is an overlap with the category @{syntax name}, which also
   211   includes @{syntax nat}.
   212 \<close>
   213 
   214 
   215 subsection \<open>Embedded content\<close>
   216 
   217 text \<open>
   218   Entity @{syntax embedded} refers to content of other languages: cartouches
   219   allow arbitrary nesting of sub-languages that respect the recursive
   220   balancing of cartouche delimiters. Quoted strings are possible as well, but
   221   require escaped quotes when nested. As a shortcut, tokens that appear as
   222   plain identifiers in the outer language may be used as inner language
   223   content without delimiters.
   224 
   225   @{rail \<open>
   226     @{syntax_def embedded}: @{syntax cartouche} | @{syntax string} |
   227       @{syntax short_ident} | @{syntax long_ident} | @{syntax sym_ident} |
   228       @{syntax term_var} | @{syntax type_ident} | @{syntax type_var} | @{syntax nat}
   229   \<close>}
   230 \<close>
   231 
   232 
   233 subsection \<open>Document text\<close>
   234 
   235 text \<open>
   236   A chunk of document @{syntax text} is usually given as @{syntax cartouche}
   237   \<open>\<open>\<dots>\<close>\<close> or @{syntax verbatim}, i.e.\ enclosed in \<^verbatim>\<open>{*\<close>~\<open>\<dots>\<close>~\<^verbatim>\<open>*}\<close>. For
   238   convenience, any of the smaller text unit that conforms to @{syntax name} is
   239   admitted as well.
   240 
   241   @{rail \<open>
   242     @{syntax_def text}: @{syntax embedded} | @{syntax verbatim}
   243   \<close>}
   244 
   245   Typical uses are document markup commands, like \<^theory_text>\<open>chapter\<close>, \<^theory_text>\<open>section\<close> etc.
   246   (\secref{sec:markup}).
   247 \<close>
   248 
   249 
   250 subsection \<open>Document comments \label{sec:comments}\<close>
   251 
   252 text \<open>
   253   Formal comments are an integral part of the document, but are logically void
   254   and removed from the resulting theory or term content. The output of
   255   document preparation (\chref{ch:document-prep}) supports various styles,
   256   according to the following kinds of comments.
   257 
   258     \<^item> Marginal comment of the form \<^verbatim>\<open>\<comment>\<close>~\<open>\<open>text\<close>\<close> or \<open>\<comment> \<open>text\<close>\<close>, usually with a
   259     single space between the comment symbol and the argument cartouche. The
   260     given argument is typeset as regular text, with formal antiquotations
   261     (\secref{sec:antiq}).
   262 
   263     \<^item> Canceled text of the form \<^verbatim>\<open>\<^cancel>\<close>\<open>\<open>text\<close>\<close> (no white space between the
   264     control symbol and the argument cartouche). The argument is typeset as
   265     formal Isabelle source and overlaid with a ``strike-through'' pattern,
   266     e.g. \<^theory_text>\<open>\<^cancel>\<open>bad\<close>\<close>.
   267 
   268     \<^item> Raw {\LaTeX} source of the form \<^verbatim>\<open>\<^latex>\<close>\<open>\<open>argument\<close>\<close> (no white space
   269     between the control symbol and the argument cartouche). This allows to
   270     augment the generated {\TeX} source arbitrarily, without any sanity
   271     checks!
   272 
   273   These formal comments work uniformly in outer syntax, inner syntax (term
   274   language), Isabelle/ML, and some other embedded languages of Isabelle.
   275 \<close>
   276 
   277 
   278 subsection \<open>Type classes, sorts and arities\<close>
   279 
   280 text \<open>
   281   Classes are specified by plain names. Sorts have a very simple inner syntax,
   282   which is either a single class name \<open>c\<close> or a list \<open>{c\<^sub>1, \<dots>, c\<^sub>n}\<close> referring
   283   to the intersection of these classes. The syntax of type arities is given
   284   directly at the outer level.
   285 
   286   @{rail \<open>
   287     @{syntax_def classdecl}: @{syntax name} (('<' | '\<subseteq>') (@{syntax name} + ','))?
   288     ;
   289     @{syntax_def sort}: @{syntax embedded}
   290     ;
   291     @{syntax_def arity}: ('(' (@{syntax sort} + ',') ')')? @{syntax sort}
   292   \<close>}
   293 \<close>
   294 
   295 
   296 subsection \<open>Types and terms \label{sec:types-terms}\<close>
   297 
   298 text \<open>
   299   The actual inner Isabelle syntax, that of types and terms of the logic, is
   300   far too sophisticated in order to be modelled explicitly at the outer theory
   301   level. Basically, any such entity has to be quoted to turn it into a single
   302   token (the parsing and type-checking is performed internally later). For
   303   convenience, a slightly more liberal convention is adopted: quotes may be
   304   omitted for any type or term that is already atomic at the outer level. For
   305   example, one may just write \<^verbatim>\<open>x\<close> instead of quoted \<^verbatim>\<open>"x"\<close>. Note that
   306   symbolic identifiers (e.g.\ \<^verbatim>\<open>++\<close> or \<open>\<forall>\<close> are available as well, provided
   307   these have not been superseded by commands or other keywords already (such
   308   as \<^verbatim>\<open>=\<close> or \<^verbatim>\<open>+\<close>).
   309 
   310   @{rail \<open>
   311     @{syntax_def type}: @{syntax embedded}
   312     ;
   313     @{syntax_def term}: @{syntax embedded}
   314     ;
   315     @{syntax_def prop}: @{syntax embedded}
   316   \<close>}
   317 
   318   Positional instantiations are specified as a sequence of terms, or the
   319   placeholder ``\<open>_\<close>'' (underscore), which means to skip a position.
   320 
   321   @{rail \<open>
   322     @{syntax_def inst}: '_' | @{syntax term}
   323     ;
   324     @{syntax_def insts}: (@{syntax inst} *)
   325   \<close>}
   326 
   327   Named instantiations are specified as pairs of assignments \<open>v = t\<close>, which
   328   refer to schematic variables in some theorem that is instantiated. Both type
   329   and terms instantiations are admitted, and distinguished by the usual syntax
   330   of variable names.
   331 
   332   @{rail \<open>
   333     @{syntax_def named_inst}: variable '=' (type | term)
   334     ;
   335     @{syntax_def named_insts}: (named_inst @'and' +)
   336     ;
   337     variable: @{syntax name} | @{syntax term_var} | @{syntax type_ident} | @{syntax type_var}
   338   \<close>}
   339 
   340   Type declarations and definitions usually refer to @{syntax typespec} on the
   341   left-hand side. This models basic type constructor application at the outer
   342   syntax level. Note that only plain postfix notation is available here, but
   343   no infixes.
   344 
   345   @{rail \<open>
   346     @{syntax_def typespec}:
   347       (() | @{syntax type_ident} | '(' ( @{syntax type_ident} + ',' ) ')') @{syntax name}
   348     ;
   349     @{syntax_def typespec_sorts}:
   350       (() | (@{syntax type_ident} ('::' @{syntax sort})?) |
   351         '(' ( (@{syntax type_ident} ('::' @{syntax sort})?) + ',' ) ')') @{syntax name}
   352   \<close>}
   353 \<close>
   354 
   355 
   356 subsection \<open>Term patterns and declarations \label{sec:term-decls}\<close>
   357 
   358 text \<open>
   359   Wherever explicit propositions (or term fragments) occur in a proof text,
   360   casual binding of schematic term variables may be given specified via
   361   patterns of the form ``\<^theory_text>\<open>(is p\<^sub>1 \<dots> p\<^sub>n)\<close>''. This works both for @{syntax
   362   term} and @{syntax prop}.
   363 
   364   @{rail \<open>
   365     @{syntax_def term_pat}: '(' (@'is' @{syntax term} +) ')'
   366     ;
   367     @{syntax_def prop_pat}: '(' (@'is' @{syntax prop} +) ')'
   368   \<close>}
   369 
   370   \<^medskip>
   371   Declarations of local variables \<open>x :: \<tau>\<close> and logical propositions \<open>a : \<phi>\<close>
   372   represent different views on the same principle of introducing a local
   373   scope. In practice, one may usually omit the typing of @{syntax vars} (due
   374   to type-inference), and the naming of propositions (due to implicit
   375   references of current facts). In any case, Isar proof elements usually admit
   376   to introduce multiple such items simultaneously.
   377 
   378   @{rail \<open>
   379     @{syntax_def vars}:
   380       (((@{syntax name} +) ('::' @{syntax type})? |
   381         @{syntax name} ('::' @{syntax type})? @{syntax mixfix}) + @'and')
   382     ;
   383     @{syntax_def props}: @{syntax thmdecl}? (@{syntax prop} @{syntax prop_pat}? +)
   384     ;
   385     @{syntax_def props'}: (@{syntax prop} @{syntax prop_pat}? +)
   386   \<close>}
   387 
   388   The treatment of multiple declarations corresponds to the complementary
   389   focus of @{syntax vars} versus @{syntax props}. In ``\<open>x\<^sub>1 \<dots> x\<^sub>n :: \<tau>\<close>'' the
   390   typing refers to all variables, while in \<open>a: \<phi>\<^sub>1 \<dots> \<phi>\<^sub>n\<close> the naming refers to
   391   all propositions collectively. Isar language elements that refer to @{syntax
   392   vars} or @{syntax props} typically admit separate typings or namings via
   393   another level of iteration, with explicit @{keyword_ref "and"} separators;
   394   e.g.\ see @{command "fix"} and @{command "assume"} in
   395   \secref{sec:proof-context}.
   396 \<close>
   397 
   398 
   399 subsection \<open>Attributes and theorems \label{sec:syn-att}\<close>
   400 
   401 text \<open>
   402   Attributes have their own ``semi-inner'' syntax, in the sense that input
   403   conforming to @{syntax args} below is parsed by the attribute a second time.
   404   The attribute argument specifications may be any sequence of atomic entities
   405   (identifiers, strings etc.), or properly bracketed argument lists. Below
   406   @{syntax atom} refers to any atomic entity, including any @{syntax keyword}
   407   conforming to @{syntax sym_ident}.
   408 
   409   @{rail \<open>
   410     @{syntax_def atom}: @{syntax name} | @{syntax type_ident} |
   411       @{syntax type_var} | @{syntax term_var} | @{syntax nat} | @{syntax float} |
   412       @{syntax keyword} | @{syntax cartouche}
   413     ;
   414     arg: @{syntax atom} | '(' @{syntax args} ')' | '[' @{syntax args} ']'
   415     ;
   416     @{syntax_def args}: arg *
   417     ;
   418     @{syntax_def attributes}: '[' (@{syntax name} @{syntax args} * ',') ']'
   419   \<close>}
   420 
   421   Theorem specifications come in several flavors: @{syntax axmdecl} and
   422   @{syntax thmdecl} usually refer to axioms, assumptions or results of goal
   423   statements, while @{syntax thmdef} collects lists of existing theorems.
   424   Existing theorems are given by @{syntax thm} and @{syntax thms}, the
   425   former requires an actual singleton result.
   426 
   427   There are three forms of theorem references:
   428 
   429     \<^enum> named facts \<open>a\<close>,
   430 
   431     \<^enum> selections from named facts \<open>a(i)\<close> or \<open>a(j - k)\<close>,
   432 
   433     \<^enum> literal fact propositions using token syntax @{syntax_ref altstring}
   434     \<^verbatim>\<open>`\<close>\<open>\<phi>\<close>\<^verbatim>\<open>`\<close> or @{syntax_ref cartouche}
   435     \<open>\<open>\<phi>\<close>\<close> (see also method @{method_ref fact}).
   436 
   437   Any kind of theorem specification may include lists of attributes both on
   438   the left and right hand sides; attributes are applied to any immediately
   439   preceding fact. If names are omitted, the theorems are not stored within the
   440   theorem database of the theory or proof context, but any given attributes
   441   are applied nonetheless.
   442 
   443   An extra pair of brackets around attributes (like ``\<open>[[simproc a]]\<close>'')
   444   abbreviates a theorem reference involving an internal dummy fact, which will
   445   be ignored later on. So only the effect of the attribute on the background
   446   context will persist. This form of in-place declarations is particularly
   447   useful with commands like @{command "declare"} and @{command "using"}.
   448 
   449   @{rail \<open>
   450     @{syntax_def axmdecl}: @{syntax name} @{syntax attributes}? ':'
   451     ;
   452     @{syntax_def thmbind}:
   453       @{syntax name} @{syntax attributes} | @{syntax name} | @{syntax attributes}
   454     ;
   455     @{syntax_def thmdecl}: thmbind ':'
   456     ;
   457     @{syntax_def thmdef}: thmbind '='
   458     ;
   459     @{syntax_def thm}:
   460       (@{syntax name} selection? | @{syntax altstring} | @{syntax cartouche})
   461         @{syntax attributes}? |
   462       '[' @{syntax attributes} ']'
   463     ;
   464     @{syntax_def thms}: @{syntax thm} +
   465     ;
   466     selection: '(' ((@{syntax nat} | @{syntax nat} '-' @{syntax nat}?) + ',') ')'
   467   \<close>}
   468 \<close>
   469 
   470 
   471 subsection \<open>Structured specifications\<close>
   472 
   473 text \<open>
   474   Structured specifications use propositions with explicit notation for the
   475   ``eigen-context'' to describe rule structure: \<open>\<And>x. A x \<Longrightarrow> \<dots> \<Longrightarrow> B x\<close> is
   476   expressed as \<^theory_text>\<open>B x if A x and \<dots> for x\<close>. It is also possible to use dummy
   477   terms ``\<open>_\<close>'' (underscore) to refer to locally fixed variables anonymously.
   478 
   479   Multiple specifications are delimited by ``\<open>|\<close>'' to emphasize separate
   480   cases: each with its own scope of inferred types for free variables.
   481 
   482 
   483   @{rail \<open>
   484     @{syntax_def for_fixes}: (@'for' @{syntax vars})?
   485     ;
   486     @{syntax_def multi_specs}: (@{syntax structured_spec} + '|')
   487     ;
   488     @{syntax_def structured_spec}:
   489       @{syntax thmdecl}? @{syntax prop} @{syntax spec_prems} @{syntax for_fixes}
   490     ;
   491     @{syntax_def spec_prems}: (@'if' ((@{syntax prop}+) + @'and'))?
   492     ;
   493     @{syntax_def specification}: @{syntax vars} @'where' @{syntax multi_specs}
   494   \<close>}
   495 \<close>
   496 
   497 
   498 section \<open>Diagnostic commands\<close>
   499 
   500 text \<open>
   501   \begin{matharray}{rcl}
   502     @{command_def "print_theory"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   503     @{command_def "print_definitions"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   504     @{command_def "print_methods"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   505     @{command_def "print_attributes"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   506     @{command_def "print_theorems"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   507     @{command_def "find_theorems"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   508     @{command_def "find_consts"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   509     @{command_def "thm_deps"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   510     @{command_def "unused_thms"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   511     @{command_def "print_facts"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   512     @{command_def "print_term_bindings"}\<open>\<^sup>*\<close> & : & \<open>context \<rightarrow>\<close> \\
   513   \end{matharray}
   514 
   515   @{rail \<open>
   516     (@@{command print_theory} |
   517       @@{command print_definitions} |
   518       @@{command print_methods} |
   519       @@{command print_attributes} |
   520       @@{command print_theorems} |
   521       @@{command print_facts}) ('!'?)
   522     ;
   523     @@{command find_theorems} ('(' @{syntax nat}? 'with_dups'? ')')? \<newline> (thm_criterion*)
   524     ;
   525     thm_criterion: ('-'?) ('name' ':' @{syntax name} | 'intro' | 'elim' | 'dest' |
   526       'solves' | 'simp' ':' @{syntax term} | @{syntax term})
   527     ;
   528     @@{command find_consts} (const_criterion*)
   529     ;
   530     const_criterion: ('-'?)
   531       ('name' ':' @{syntax name} | 'strict' ':' @{syntax type} | @{syntax type})
   532     ;
   533     @@{command thm_deps} @{syntax thmrefs}
   534     ;
   535     @@{command unused_thms} ((@{syntax name} +) '-' (@{syntax name} * ))?
   536   \<close>}
   537 
   538   These commands print certain parts of the theory and proof context. Note
   539   that there are some further ones available, such as for the set of rules
   540   declared for simplifications.
   541 
   542   \<^descr> @{command "print_theory"} prints the main logical content of the
   543   background theory; the ``\<open>!\<close>'' option indicates extra verbosity.
   544 
   545   \<^descr> @{command "print_definitions"} prints dependencies of definitional
   546   specifications within the background theory, which may be constants
   547   (\secref{sec:term-definitions}, \secref{sec:overloading}) or types
   548   (\secref{sec:types-pure}, \secref{sec:hol-typedef}); the ``\<open>!\<close>'' option
   549   indicates extra verbosity.
   550 
   551   \<^descr> @{command "print_methods"} prints all proof methods available in the
   552   current theory context; the ``\<open>!\<close>'' option indicates extra verbosity.
   553 
   554   \<^descr> @{command "print_attributes"} prints all attributes available in the
   555   current theory context; the ``\<open>!\<close>'' option indicates extra verbosity.
   556 
   557   \<^descr> @{command "print_theorems"} prints theorems of the background theory
   558   resulting from the last command; the ``\<open>!\<close>'' option indicates extra
   559   verbosity.
   560 
   561   \<^descr> @{command "print_facts"} prints all local facts of the current context,
   562   both named and unnamed ones; the ``\<open>!\<close>'' option indicates extra verbosity.
   563 
   564   \<^descr> @{command "print_term_bindings"} prints all term bindings that are present
   565   in the context.
   566 
   567   \<^descr> @{command "find_theorems"}~\<open>criteria\<close> retrieves facts from the theory or
   568   proof context matching all of given search criteria. The criterion \<open>name: p\<close>
   569   selects all theorems whose fully qualified name matches pattern \<open>p\<close>, which
   570   may contain ``\<open>*\<close>'' wildcards. The criteria \<open>intro\<close>, \<open>elim\<close>, and \<open>dest\<close>
   571   select theorems that match the current goal as introduction, elimination or
   572   destruction rules, respectively. The criterion \<open>solves\<close> returns all rules
   573   that would directly solve the current goal. The criterion \<open>simp: t\<close> selects
   574   all rewrite rules whose left-hand side matches the given term. The criterion
   575   term \<open>t\<close> selects all theorems that contain the pattern \<open>t\<close> -- as usual,
   576   patterns may contain occurrences of the dummy ``\<open>_\<close>'', schematic variables,
   577   and type constraints.
   578 
   579   Criteria can be preceded by ``\<open>-\<close>'' to select theorems that do \<^emph>\<open>not\<close> match.
   580   Note that giving the empty list of criteria yields \<^emph>\<open>all\<close> currently known
   581   facts. An optional limit for the number of printed facts may be given; the
   582   default is 40. By default, duplicates are removed from the search result.
   583   Use \<open>with_dups\<close> to display duplicates.
   584 
   585   \<^descr> @{command "find_consts"}~\<open>criteria\<close> prints all constants whose type meets
   586   all of the given criteria. The criterion \<open>strict: ty\<close> is met by any type
   587   that matches the type pattern \<open>ty\<close>. Patterns may contain both the dummy type
   588   ``\<open>_\<close>'' and sort constraints. The criterion \<open>ty\<close> is similar, but it also
   589   matches against subtypes. The criterion \<open>name: p\<close> and the prefix ``\<open>-\<close>''
   590   function as described for @{command "find_theorems"}.
   591 
   592   \<^descr> @{command "thm_deps"}~\<open>a\<^sub>1 \<dots> a\<^sub>n\<close> visualizes dependencies of facts, using
   593   Isabelle's graph browser tool (see also @{cite "isabelle-system"}).
   594 
   595   \<^descr> @{command "unused_thms"}~\<open>A\<^sub>1 \<dots> A\<^sub>m - B\<^sub>1 \<dots> B\<^sub>n\<close> displays all theorems
   596   that are proved in theories \<open>B\<^sub>1 \<dots> B\<^sub>n\<close> or their parents but not in \<open>A\<^sub>1 \<dots>
   597   A\<^sub>m\<close> or their parents and that are never used. If \<open>n\<close> is \<open>0\<close>, the end of the
   598   range of theories defaults to the current theory. If no range is specified,
   599   only the unused theorems in the current theory are displayed.
   600 \<close>
   601 
   602 end