src/Doc/IsarRef/Spec.thy
author wenzelm
Tue Mar 25 13:18:10 2014 +0100 (2014-03-25 ago)
changeset 56275 600f432ab556
parent 55837 154855d9a564
permissions -rw-r--r--
added command 'SML_file' for Standard ML without Isabelle/ML add-ons;
     1 theory Spec
     2 imports Base Main
     3 begin
     4 
     5 chapter {* Specifications *}
     6 
     7 text {*
     8   The Isabelle/Isar theory format integrates specifications and
     9   proofs, supporting interactive development with unlimited undo
    10   operation.  There is an integrated document preparation system (see
    11   \chref{ch:document-prep}), for typesetting formal developments
    12   together with informal text.  The resulting hyper-linked PDF
    13   documents can be used both for WWW presentation and printed copies.
    14 
    15   The Isar proof language (see \chref{ch:proofs}) is embedded into the
    16   theory language as a proper sub-language.  Proof mode is entered by
    17   stating some @{command theorem} or @{command lemma} at the theory
    18   level, and left again with the final conclusion (e.g.\ via @{command
    19   qed}).  Some theory specification mechanisms also require a proof,
    20   such as @{command typedef} in HOL, which demands non-emptiness of
    21   the representing sets.
    22 *}
    23 
    24 
    25 section {* Defining theories \label{sec:begin-thy} *}
    26 
    27 text {*
    28   \begin{matharray}{rcl}
    29     @{command_def "theory"} & : & @{text "toplevel \<rightarrow> theory"} \\
    30     @{command_def (global) "end"} & : & @{text "theory \<rightarrow> toplevel"} \\
    31   \end{matharray}
    32 
    33   Isabelle/Isar theories are defined via theory files, which may
    34   contain both specifications and proofs; occasionally definitional
    35   mechanisms also require some explicit proof.  The theory body may be
    36   sub-structured by means of \emph{local theory targets}, such as
    37   @{command "locale"} and @{command "class"}.
    38 
    39   The first proper command of a theory is @{command "theory"}, which
    40   indicates imports of previous theories and optional dependencies on
    41   other source files (usually in ML).  Just preceding the initial
    42   @{command "theory"} command there may be an optional @{command
    43   "header"} declaration, which is only relevant to document
    44   preparation: see also the other section markup commands in
    45   \secref{sec:markup}.
    46 
    47   A theory is concluded by a final @{command (global) "end"} command,
    48   one that does not belong to a local theory target.  No further
    49   commands may follow such a global @{command (global) "end"},
    50   although some user-interfaces might pretend that trailing input is
    51   admissible.
    52 
    53   @{rail \<open>
    54     @@{command theory} @{syntax name} imports keywords? \<newline> @'begin'
    55     ;
    56     imports: @'imports' (@{syntax name} +)
    57     ;
    58     keywords: @'keywords' (keyword_decls + @'and')
    59     ;
    60     keyword_decls: (@{syntax string} +)
    61       ('::' @{syntax name} @{syntax tags})? ('==' @{syntax name})?
    62   \<close>}
    63 
    64   \begin{description}
    65 
    66   \item @{command "theory"}~@{text "A \<IMPORTS> B\<^sub>1 \<dots> B\<^sub>n \<BEGIN>"}
    67   starts a new theory @{text A} based on the merge of existing
    68   theories @{text "B\<^sub>1 \<dots> B\<^sub>n"}.  Due to the possibility to import more
    69   than one ancestor, the resulting theory structure of an Isabelle
    70   session forms a directed acyclic graph (DAG).  Isabelle takes care
    71   that sources contributing to the development graph are always
    72   up-to-date: changed files are automatically rechecked whenever a
    73   theory header specification is processed.
    74 
    75   The optional @{keyword_def "keywords"} specification declares outer
    76   syntax (\chref{ch:outer-syntax}) that is introduced in this theory
    77   later on (rare in end-user applications).  Both minor keywords and
    78   major keywords of the Isar command language need to be specified, in
    79   order to make parsing of proof documents work properly.  Command
    80   keywords need to be classified according to their structural role in
    81   the formal text.  Examples may be seen in Isabelle/HOL sources
    82   itself, such as @{keyword "keywords"}~@{verbatim "\"typedef\""}
    83   @{text ":: thy_goal"} or @{keyword "keywords"}~@{verbatim
    84   "\"datatype\""} @{text ":: thy_decl"} for theory-level declarations
    85   with and without proof, respectively.  Additional @{syntax tags}
    86   provide defaults for document preparation (\secref{sec:tags}).
    87 
    88   It is possible to specify an alternative completion via @{text "==
    89   text"}, while the default is the corresponding keyword name.
    90   
    91   \item @{command (global) "end"} concludes the current theory
    92   definition.  Note that some other commands, e.g.\ local theory
    93   targets @{command locale} or @{command class} may involve a
    94   @{keyword "begin"} that needs to be matched by @{command (local)
    95   "end"}, according to the usual rules for nested blocks.
    96 
    97   \end{description}
    98 *}
    99 
   100 
   101 section {* Local theory targets \label{sec:target} *}
   102 
   103 text {*
   104   \begin{matharray}{rcll}
   105     @{command_def "context"} & : & @{text "theory \<rightarrow> local_theory"} \\
   106     @{command_def (local) "end"} & : & @{text "local_theory \<rightarrow> theory"} \\
   107   \end{matharray}
   108 
   109   A local theory target is a context managed separately within the
   110   enclosing theory.  Contexts may introduce parameters (fixed
   111   variables) and assumptions (hypotheses).  Definitions and theorems
   112   depending on the context may be added incrementally later on.
   113 
   114   \emph{Named contexts} refer to locales (cf.\ \secref{sec:locale}) or
   115   type classes (cf.\ \secref{sec:class}); the name ``@{text "-"}''
   116   signifies the global theory context.
   117 
   118   \emph{Unnamed contexts} may introduce additional parameters and
   119   assumptions, and results produced in the context are generalized
   120   accordingly.  Such auxiliary contexts may be nested within other
   121   targets, like @{command "locale"}, @{command "class"}, @{command
   122   "instantiation"}, @{command "overloading"}.
   123 
   124   @{rail \<open>
   125     @@{command context} @{syntax nameref} @'begin'
   126     ;
   127     @@{command context} @{syntax_ref "includes"}? (@{syntax context_elem} * ) @'begin'
   128     ;
   129     @{syntax_def target}: '(' @'in' @{syntax nameref} ')'
   130   \<close>}
   131 
   132   \begin{description}
   133   
   134   \item @{command "context"}~@{text "c \<BEGIN>"} opens a named
   135   context, by recommencing an existing locale or class @{text c}.
   136   Note that locale and class definitions allow to include the
   137   @{keyword "begin"} keyword as well, in order to continue the local
   138   theory immediately after the initial specification.
   139 
   140   \item @{command "context"}~@{text "bundles elements \<BEGIN>"} opens
   141   an unnamed context, by extending the enclosing global or local
   142   theory target by the given declaration bundles (\secref{sec:bundle})
   143   and context elements (@{text "\<FIXES>"}, @{text "\<ASSUMES>"}
   144   etc.).  This means any results stemming from definitions and proofs
   145   in the extended context will be exported into the enclosing target
   146   by lifting over extra parameters and premises.
   147   
   148   \item @{command (local) "end"} concludes the current local theory,
   149   according to the nesting of contexts.  Note that a global @{command
   150   (global) "end"} has a different meaning: it concludes the theory
   151   itself (\secref{sec:begin-thy}).
   152   
   153   \item @{text "("}@{keyword_def "in"}~@{text "c)"} given after any
   154   local theory command specifies an immediate target, e.g.\
   155   ``@{command "definition"}~@{text "(\<IN> c) \<dots>"}'' or ``@{command
   156   "theorem"}~@{text "(\<IN> c) \<dots>"}''.  This works both in a local or
   157   global theory context; the current target context will be suspended
   158   for this command only.  Note that ``@{text "(\<IN> -)"}'' will
   159   always produce a global result independently of the current target
   160   context.
   161 
   162   \end{description}
   163 
   164   The exact meaning of results produced within a local theory context
   165   depends on the underlying target infrastructure (locale, type class
   166   etc.).  The general idea is as follows, considering a context named
   167   @{text c} with parameter @{text x} and assumption @{text "A[x]"}.
   168   
   169   Definitions are exported by introducing a global version with
   170   additional arguments; a syntactic abbreviation links the long form
   171   with the abstract version of the target context.  For example,
   172   @{text "a \<equiv> t[x]"} becomes @{text "c.a ?x \<equiv> t[?x]"} at the theory
   173   level (for arbitrary @{text "?x"}), together with a local
   174   abbreviation @{text "c \<equiv> c.a x"} in the target context (for the
   175   fixed parameter @{text x}).
   176 
   177   Theorems are exported by discharging the assumptions and
   178   generalizing the parameters of the context.  For example, @{text "a:
   179   B[x]"} becomes @{text "c.a: A[?x] \<Longrightarrow> B[?x]"}, again for arbitrary
   180   @{text "?x"}.
   181 
   182   \medskip The Isabelle/HOL library contains numerous applications of
   183   locales and classes, e.g.\ see @{file "~~/src/HOL/Algebra"}.  An
   184   example for an unnamed auxiliary contexts is given in @{file
   185   "~~/src/HOL/Isar_Examples/Group_Context.thy"}.  *}
   186 
   187 
   188 section {* Bundled declarations \label{sec:bundle} *}
   189 
   190 text {*
   191   \begin{matharray}{rcl}
   192     @{command_def "bundle"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   193     @{command_def "print_bundles"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow> "} \\
   194     @{command_def "include"} & : & @{text "proof(state) \<rightarrow> proof(state)"} \\
   195     @{command_def "including"} & : & @{text "proof(prove) \<rightarrow> proof(prove)"} \\
   196     @{keyword_def "includes"} & : & syntax \\
   197   \end{matharray}
   198 
   199   The outer syntax of fact expressions (\secref{sec:syn-att}) involves
   200   theorems and attributes, which are evaluated in the context and
   201   applied to it.  Attributes may declare theorems to the context, as
   202   in @{text "this_rule [intro] that_rule [elim]"} for example.
   203   Configuration options (\secref{sec:config}) are special declaration
   204   attributes that operate on the context without a theorem, as in
   205   @{text "[[show_types = false]]"} for example.
   206 
   207   Expressions of this form may be defined as \emph{bundled
   208   declarations} in the context, and included in other situations later
   209   on.  Including declaration bundles augments a local context casually
   210   without logical dependencies, which is in contrast to locales and
   211   locale interpretation (\secref{sec:locale}).
   212 
   213   @{rail \<open>
   214     @@{command bundle} @{syntax target}? \<newline>
   215     @{syntax name} '=' @{syntax thmrefs} (@'for' (@{syntax vars} + @'and'))?
   216     ;
   217     (@@{command include} | @@{command including}) (@{syntax nameref}+)
   218     ;
   219     @{syntax_def "includes"}: @'includes' (@{syntax nameref}+)
   220   \<close>}
   221 
   222   \begin{description}
   223 
   224   \item @{command bundle}~@{text "b = decls"} defines a bundle of
   225   declarations in the current context.  The RHS is similar to the one
   226   of the @{command declare} command.  Bundles defined in local theory
   227   targets are subject to transformations via morphisms, when moved
   228   into different application contexts; this works analogously to any
   229   other local theory specification.
   230 
   231   \item @{command print_bundles} prints the named bundles that are
   232   available in the current context.
   233 
   234   \item @{command include}~@{text "b\<^sub>1 \<dots> b\<^sub>n"} includes the declarations
   235   from the given bundles into the current proof body context.  This is
   236   analogous to @{command "note"} (\secref{sec:proof-facts}) with the
   237   expanded bundles.
   238 
   239   \item @{command including} is similar to @{command include}, but
   240   works in proof refinement (backward mode).  This is analogous to
   241   @{command "using"} (\secref{sec:proof-facts}) with the expanded
   242   bundles.
   243 
   244   \item @{keyword "includes"}~@{text "b\<^sub>1 \<dots> b\<^sub>n"} is similar to
   245   @{command include}, but works in situations where a specification
   246   context is constructed, notably for @{command context} and long
   247   statements of @{command theorem} etc.
   248 
   249   \end{description}
   250 
   251   Here is an artificial example of bundling various configuration
   252   options: *}
   253 
   254 bundle trace = [[simp_trace, linarith_trace, metis_trace, smt_trace]]
   255 
   256 lemma "x = x"
   257   including trace by metis
   258 
   259 
   260 section {* Basic specification elements \label{sec:basic-spec} *}
   261 
   262 text {*
   263   \begin{matharray}{rcll}
   264     @{command_def "axiomatization"} & : & @{text "theory \<rightarrow> theory"} & (axiomatic!) \\
   265     @{command_def "definition"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   266     @{attribute_def "defn"} & : & @{text attribute} \\
   267     @{command_def "print_defn_rules"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow> "} \\
   268     @{command_def "abbreviation"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   269     @{command_def "print_abbrevs"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow> "} \\
   270   \end{matharray}
   271 
   272   These specification mechanisms provide a slightly more abstract view
   273   than the underlying primitives of @{command "consts"}, @{command
   274   "defs"} (see \secref{sec:consts}), and raw axioms.  In particular,
   275   type-inference covers the whole specification as usual.
   276 
   277   @{rail \<open>
   278     @@{command axiomatization} @{syntax "fixes"}? (@'where' specs)?
   279     ;
   280     @@{command definition} @{syntax target}? \<newline>
   281       (decl @'where')? @{syntax thmdecl}? @{syntax prop}
   282     ;
   283     @@{command abbreviation} @{syntax target}? @{syntax mode}? \<newline>
   284       (decl @'where')? @{syntax prop}
   285     ;
   286 
   287     @{syntax_def "fixes"}: ((@{syntax name} ('::' @{syntax type})?
   288       @{syntax mixfix}? | @{syntax vars}) + @'and')
   289     ;
   290     specs: (@{syntax thmdecl}? @{syntax props} + @'and')
   291     ;
   292     decl: @{syntax name} ('::' @{syntax type})? @{syntax mixfix}?
   293   \<close>}
   294 
   295   \begin{description}
   296   
   297   \item @{command "axiomatization"}~@{text "c\<^sub>1 \<dots> c\<^sub>m \<WHERE> \<phi>\<^sub>1 \<dots> \<phi>\<^sub>n"}
   298   introduces several constants simultaneously and states axiomatic
   299   properties for these.  The constants are marked as being specified
   300   once and for all, which prevents additional specifications being
   301   issued later on.
   302   
   303   Note that axiomatic specifications are only appropriate when
   304   declaring a new logical system; axiomatic specifications are
   305   restricted to global theory contexts.  Normal applications should
   306   only use definitional mechanisms!
   307 
   308   \item @{command "definition"}~@{text "c \<WHERE> eq"} produces an
   309   internal definition @{text "c \<equiv> t"} according to the specification
   310   given as @{text eq}, which is then turned into a proven fact.  The
   311   given proposition may deviate from internal meta-level equality
   312   according to the rewrite rules declared as @{attribute defn} by the
   313   object-logic.  This usually covers object-level equality @{text "x =
   314   y"} and equivalence @{text "A \<leftrightarrow> B"}.  End-users normally need not
   315   change the @{attribute defn} setup.
   316   
   317   Definitions may be presented with explicit arguments on the LHS, as
   318   well as additional conditions, e.g.\ @{text "f x y = t"} instead of
   319   @{text "f \<equiv> \<lambda>x y. t"} and @{text "y \<noteq> 0 \<Longrightarrow> g x y = u"} instead of an
   320   unrestricted @{text "g \<equiv> \<lambda>x y. u"}.
   321 
   322   \item @{command "print_defn_rules"} prints the definitional rewrite rules
   323   declared via @{attribute defn} in the current context.
   324 
   325   \item @{command "abbreviation"}~@{text "c \<WHERE> eq"} introduces a
   326   syntactic constant which is associated with a certain term according
   327   to the meta-level equality @{text eq}.
   328   
   329   Abbreviations participate in the usual type-inference process, but
   330   are expanded before the logic ever sees them.  Pretty printing of
   331   terms involves higher-order rewriting with rules stemming from
   332   reverted abbreviations.  This needs some care to avoid overlapping
   333   or looping syntactic replacements!
   334   
   335   The optional @{text mode} specification restricts output to a
   336   particular print mode; using ``@{text input}'' here achieves the
   337   effect of one-way abbreviations.  The mode may also include an
   338   ``@{keyword "output"}'' qualifier that affects the concrete syntax
   339   declared for abbreviations, cf.\ @{command "syntax"} in
   340   \secref{sec:syn-trans}.
   341   
   342   \item @{command "print_abbrevs"} prints all constant abbreviations
   343   of the current context.
   344   
   345   \end{description}
   346 *}
   347 
   348 
   349 section {* Generic declarations *}
   350 
   351 text {*
   352   \begin{matharray}{rcl}
   353     @{command_def "declaration"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   354     @{command_def "syntax_declaration"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   355     @{command_def "declare"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   356   \end{matharray}
   357 
   358   Arbitrary operations on the background context may be wrapped-up as
   359   generic declaration elements.  Since the underlying concept of local
   360   theories may be subject to later re-interpretation, there is an
   361   additional dependency on a morphism that tells the difference of the
   362   original declaration context wrt.\ the application context
   363   encountered later on.  A fact declaration is an important special
   364   case: it consists of a theorem which is applied to the context by
   365   means of an attribute.
   366 
   367   @{rail \<open>
   368     (@@{command declaration} | @@{command syntax_declaration})
   369       ('(' @'pervasive' ')')? \<newline> @{syntax target}? @{syntax text}
   370     ;
   371     @@{command declare} @{syntax target}? (@{syntax thmrefs} + @'and')
   372   \<close>}
   373 
   374   \begin{description}
   375 
   376   \item @{command "declaration"}~@{text d} adds the declaration
   377   function @{text d} of ML type @{ML_type declaration}, to the current
   378   local theory under construction.  In later application contexts, the
   379   function is transformed according to the morphisms being involved in
   380   the interpretation hierarchy.
   381 
   382   If the @{text "(pervasive)"} option is given, the corresponding
   383   declaration is applied to all possible contexts involved, including
   384   the global background theory.
   385 
   386   \item @{command "syntax_declaration"} is similar to @{command
   387   "declaration"}, but is meant to affect only ``syntactic'' tools by
   388   convention (such as notation and type-checking information).
   389 
   390   \item @{command "declare"}~@{text thms} declares theorems to the
   391   current local theory context.  No theorem binding is involved here,
   392   unlike @{command "theorems"} or @{command "lemmas"} (cf.\
   393   \secref{sec:theorems}), so @{command "declare"} only has the effect
   394   of applying attributes as included in the theorem specification.
   395 
   396   \end{description}
   397 *}
   398 
   399 
   400 section {* Locales \label{sec:locale} *}
   401 
   402 text {*
   403   A locale is a functor that maps parameters (including implicit type
   404   parameters) and a specification to a list of declarations.  The
   405   syntax of locales is modeled after the Isar proof context commands
   406   (cf.\ \secref{sec:proof-context}).
   407 
   408   Locale hierarchies are supported by maintaining a graph of
   409   dependencies between locale instances in the global theory.
   410   Dependencies may be introduced through import (where a locale is
   411   defined as sublocale of the imported instances) or by proving that
   412   an existing locale is a sublocale of one or several locale
   413   instances.
   414 
   415   A locale may be opened with the purpose of appending to its list of
   416   declarations (cf.\ \secref{sec:target}).  When opening a locale
   417   declarations from all dependencies are collected and are presented
   418   as a local theory.  In this process, which is called \emph{roundup},
   419   redundant locale instances are omitted.  A locale instance is
   420   redundant if it is subsumed by an instance encountered earlier.  A
   421   more detailed description of this process is available elsewhere
   422   \cite{Ballarin2014}.
   423 *}
   424 
   425 
   426 subsection {* Locale expressions \label{sec:locale-expr} *}
   427 
   428 text {*
   429   A \emph{locale expression} denotes a context composed of instances
   430   of existing locales.  The context consists of the declaration
   431   elements from the locale instances.  Redundant locale instances are
   432   omitted according to roundup.
   433 
   434   @{rail \<open>
   435     @{syntax_def locale_expr}: (instance + '+') (@'for' (@{syntax "fixes"} + @'and'))?
   436     ;
   437     instance: (qualifier ':')? @{syntax nameref} (pos_insts | named_insts)
   438     ;
   439     qualifier: @{syntax name} ('?' | '!')?
   440     ;
   441     pos_insts: ('_' | @{syntax term})*
   442     ;
   443     named_insts: @'where' (@{syntax name} '=' @{syntax term} + @'and')
   444   \<close>}
   445 
   446   A locale instance consists of a reference to a locale and either
   447   positional or named parameter instantiations.  Identical
   448   instantiations (that is, those that instantiate a parameter by itself)
   449   may be omitted.  The notation `@{text "_"}' enables to omit the
   450   instantiation for a parameter inside a positional instantiation.
   451 
   452   Terms in instantiations are from the context the locale expressions
   453   is declared in.  Local names may be added to this context with the
   454   optional @{keyword "for"} clause.  This is useful for shadowing names
   455   bound in outer contexts, and for declaring syntax.  In addition,
   456   syntax declarations from one instance are effective when parsing
   457   subsequent instances of the same expression.
   458 
   459   Instances have an optional qualifier which applies to names in
   460   declarations.  Names include local definitions and theorem names.
   461   If present, the qualifier itself is either optional
   462   (``\texttt{?}''), which means that it may be omitted on input of the
   463   qualified name, or mandatory (``\texttt{!}'').  If neither
   464   ``\texttt{?}'' nor ``\texttt{!}'' are present, the command's default
   465   is used.  For @{command "interpretation"} and @{command "interpret"}
   466   the default is ``mandatory'', for @{command "locale"} and @{command
   467   "sublocale"} the default is ``optional''.  Qualifiers play no role
   468   in determining whether one locale instance subsumes another.
   469 *}
   470 
   471 
   472 subsection {* Locale declarations *}
   473 
   474 text {*
   475   \begin{matharray}{rcl}
   476     @{command_def "locale"} & : & @{text "theory \<rightarrow> local_theory"} \\
   477     @{command_def "print_locale"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   478     @{command_def "print_locales"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   479     @{command_def "locale_deps"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   480     @{method_def intro_locales} & : & @{text method} \\
   481     @{method_def unfold_locales} & : & @{text method} \\
   482   \end{matharray}
   483 
   484   \indexisarelem{fixes}\indexisarelem{constrains}\indexisarelem{assumes}
   485   \indexisarelem{defines}\indexisarelem{notes}
   486   @{rail \<open>
   487     @@{command locale} @{syntax name} ('=' @{syntax locale})? @'begin'?
   488     ;
   489     @@{command print_locale} '!'? @{syntax nameref}
   490     ;
   491     @{syntax_def locale}: @{syntax context_elem}+ |
   492       @{syntax locale_expr} ('+' (@{syntax context_elem}+))?
   493     ;
   494     @{syntax_def context_elem}:
   495       @'fixes' (@{syntax "fixes"} + @'and') |
   496       @'constrains' (@{syntax name} '::' @{syntax type} + @'and') |
   497       @'assumes' (@{syntax props} + @'and') |
   498       @'defines' (@{syntax thmdecl}? @{syntax prop} @{syntax prop_pat}? + @'and') |
   499       @'notes' (@{syntax thmdef}? @{syntax thmrefs} + @'and')
   500   \<close>}
   501 
   502   \begin{description}
   503   
   504   \item @{command "locale"}~@{text "loc = import + body"} defines a
   505   new locale @{text loc} as a context consisting of a certain view of
   506   existing locales (@{text import}) plus some additional elements
   507   (@{text body}).  Both @{text import} and @{text body} are optional;
   508   the degenerate form @{command "locale"}~@{text loc} defines an empty
   509   locale, which may still be useful to collect declarations of facts
   510   later on.  Type-inference on locale expressions automatically takes
   511   care of the most general typing that the combined context elements
   512   may acquire.
   513 
   514   The @{text import} consists of a locale expression; see
   515   \secref{sec:proof-context} above.  Its @{keyword "for"} clause defines
   516   the parameters of @{text import}.  These are parameters of
   517   the defined locale.  Locale parameters whose instantiation is
   518   omitted automatically extend the (possibly empty) @{keyword "for"}
   519   clause: they are inserted at its beginning.  This means that these
   520   parameters may be referred to from within the expression and also in
   521   the subsequent context elements and provides a notational
   522   convenience for the inheritance of parameters in locale
   523   declarations.
   524 
   525   The @{text body} consists of context elements.
   526 
   527   \begin{description}
   528 
   529   \item @{element "fixes"}~@{text "x :: \<tau> (mx)"} declares a local
   530   parameter of type @{text \<tau>} and mixfix annotation @{text mx} (both
   531   are optional).  The special syntax declaration ``@{text
   532   "("}@{keyword_ref "structure"}@{text ")"}'' means that @{text x} may
   533   be referenced implicitly in this context.
   534 
   535   \item @{element "constrains"}~@{text "x :: \<tau>"} introduces a type
   536   constraint @{text \<tau>} on the local parameter @{text x}.  This
   537   element is deprecated.  The type constraint should be introduced in
   538   the @{keyword "for"} clause or the relevant @{element "fixes"} element.
   539 
   540   \item @{element "assumes"}~@{text "a: \<phi>\<^sub>1 \<dots> \<phi>\<^sub>n"}
   541   introduces local premises, similar to @{command "assume"} within a
   542   proof (cf.\ \secref{sec:proof-context}).
   543 
   544   \item @{element "defines"}~@{text "a: x \<equiv> t"} defines a previously
   545   declared parameter.  This is similar to @{command "def"} within a
   546   proof (cf.\ \secref{sec:proof-context}), but @{element "defines"}
   547   takes an equational proposition instead of variable-term pair.  The
   548   left-hand side of the equation may have additional arguments, e.g.\
   549   ``@{element "defines"}~@{text "f x\<^sub>1 \<dots> x\<^sub>n \<equiv> t"}''.
   550 
   551   \item @{element "notes"}~@{text "a = b\<^sub>1 \<dots> b\<^sub>n"}
   552   reconsiders facts within a local context.  Most notably, this may
   553   include arbitrary declarations in any attribute specifications
   554   included here, e.g.\ a local @{attribute simp} rule.
   555 
   556   \end{description}
   557 
   558   Both @{element "assumes"} and @{element "defines"} elements
   559   contribute to the locale specification.  When defining an operation
   560   derived from the parameters, @{command "definition"}
   561   (\secref{sec:basic-spec}) is usually more appropriate.
   562   
   563   Note that ``@{text "(\<IS> p\<^sub>1 \<dots> p\<^sub>n)"}'' patterns given
   564   in the syntax of @{element "assumes"} and @{element "defines"} above
   565   are illegal in locale definitions.  In the long goal format of
   566   \secref{sec:goals}, term bindings may be included as expected,
   567   though.
   568   
   569   \medskip Locale specifications are ``closed up'' by
   570   turning the given text into a predicate definition @{text
   571   loc_axioms} and deriving the original assumptions as local lemmas
   572   (modulo local definitions).  The predicate statement covers only the
   573   newly specified assumptions, omitting the content of included locale
   574   expressions.  The full cumulative view is only provided on export,
   575   involving another predicate @{text loc} that refers to the complete
   576   specification text.
   577   
   578   In any case, the predicate arguments are those locale parameters
   579   that actually occur in the respective piece of text.  Also these
   580   predicates operate at the meta-level in theory, but the locale
   581   packages attempts to internalize statements according to the
   582   object-logic setup (e.g.\ replacing @{text \<And>} by @{text \<forall>}, and
   583   @{text "\<Longrightarrow>"} by @{text "\<longrightarrow>"} in HOL; see also
   584   \secref{sec:object-logic}).  Separate introduction rules @{text
   585   loc_axioms.intro} and @{text loc.intro} are provided as well.
   586   
   587   \item @{command "print_locale"}~@{text "locale"} prints the
   588   contents of the named locale.  The command omits @{element "notes"}
   589   elements by default.  Use @{command "print_locale"}@{text "!"} to
   590   have them included.
   591 
   592   \item @{command "print_locales"} prints the names of all locales
   593   of the current theory.
   594 
   595   \item @{command "locale_deps"} visualizes all locales and their
   596   relations as a Hasse diagram. This includes locales defined as type
   597   classes (\secref{sec:class}).  See also @{command
   598   "print_dependencies"} below.
   599 
   600   \item @{method intro_locales} and @{method unfold_locales}
   601   repeatedly expand all introduction rules of locale predicates of the
   602   theory.  While @{method intro_locales} only applies the @{text
   603   loc.intro} introduction rules and therefore does not descend to
   604   assumptions, @{method unfold_locales} is more aggressive and applies
   605   @{text loc_axioms.intro} as well.  Both methods are aware of locale
   606   specifications entailed by the context, both from target statements,
   607   and from interpretations (see below).  New goals that are entailed
   608   by the current context are discharged automatically.
   609 
   610   \end{description}
   611 *}
   612 
   613 
   614 subsection {* Locale interpretation *}
   615 
   616 text {*
   617   \begin{matharray}{rcl}
   618     @{command_def "interpretation"} & : & @{text "theory | local_theory \<rightarrow> proof(prove)"} \\
   619     @{command_def "interpret"} & : & @{text "proof(state) | proof(chain) \<rightarrow> proof(prove)"} \\
   620     @{command_def "sublocale"} & : & @{text "theory | local_theory \<rightarrow> proof(prove)"} \\
   621     @{command_def "print_dependencies"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   622     @{command_def "print_interps"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   623   \end{matharray}
   624 
   625   Locales may be instantiated, and the resulting instantiated
   626   declarations added to the current context.  This requires proof (of
   627   the instantiated specification) and is called \emph{locale
   628   interpretation}.  Interpretation is possible in locales (@{command
   629   "sublocale"}), global and local theories (@{command
   630   "interpretation"}) and also within proof bodies (@{command
   631   "interpret"}).
   632 
   633   @{rail \<open>
   634     @@{command interpretation} @{syntax locale_expr} equations?
   635     ;
   636     @@{command interpret} @{syntax locale_expr} equations?
   637     ;
   638     @@{command sublocale} (@{syntax nameref} ('<' | '\<subseteq>'))? @{syntax locale_expr} \<newline>
   639       equations?
   640     ;
   641     @@{command print_dependencies} '!'? @{syntax locale_expr}
   642     ;
   643     @@{command print_interps} @{syntax nameref}
   644     ;
   645 
   646     equations: @'where' (@{syntax thmdecl}? @{syntax prop} + @'and')
   647   \<close>}
   648 
   649   \begin{description}
   650 
   651   \item @{command "interpretation"}~@{text "expr \<WHERE> eqns"}
   652   interprets @{text expr} in a global or local theory.  The command
   653   generates proof obligations for the instantiated specifications.
   654   Once these are discharged by the user, instantiated declarations (in
   655   particular, facts) are added to the theory in a post-processing
   656   phase.
   657 
   658   The command is aware of interpretations that are already active.
   659   Post-processing is achieved through a variant of roundup that takes
   660   the interpretations of the current global or local theory into
   661   account.  In order to simplify the proof obligations according to
   662   existing interpretations use methods @{method intro_locales} or
   663   @{method unfold_locales}.
   664 
   665   When adding declarations to locales, interpreted versions of these
   666   declarations are added to the global theory for all interpretations
   667   in the global theory as well. That is, interpretations in global
   668   theories dynamically participate in any declarations added to
   669   locales.
   670 
   671   In contrast, the lifetime of an interpretation in a local theory is
   672   limited to the current context block.  At the closing @{command end}
   673   of the block the interpretation and its declarations disappear.
   674   This enables establishing facts based on interpretations without
   675   creating permanent links to the interpreted locale instances, as
   676   would be the case with @{command sublocale}.
   677   While @{command "interpretation"}~@{text "(\<IN> c)
   678   \<dots>"} is technically possible, it is not useful since its result is
   679   discarded immediately.
   680 
   681   Free variables in the interpreted expression are allowed.  They are
   682   turned into schematic variables in the generated declarations.  In
   683   order to use a free variable whose name is already bound in the
   684   context --- for example, because a constant of that name exists ---
   685   add it to the @{keyword "for"} clause.
   686 
   687   The equations @{text eqns} yield \emph{rewrite morphisms}, which are
   688   unfolded during post-processing and are useful for interpreting
   689   concepts introduced through definitions.  The equations must be
   690   proved.
   691 
   692   \item @{command "interpret"}~@{text "expr \<WHERE> eqns"} interprets
   693   @{text expr} in the proof context and is otherwise similar to
   694   interpretation in local theories.  Note that for @{command
   695   "interpret"} the @{text eqns} should be
   696   explicitly universally quantified.
   697 
   698   \item @{command "sublocale"}~@{text "name \<subseteq> expr \<WHERE>
   699   eqns"}
   700   interprets @{text expr} in the locale @{text name}.  A proof that
   701   the specification of @{text name} implies the specification of
   702   @{text expr} is required.  As in the localized version of the
   703   theorem command, the proof is in the context of @{text name}.  After
   704   the proof obligation has been discharged, the locale hierarchy is
   705   changed as if @{text name} imported @{text expr} (hence the name
   706   @{command "sublocale"}).  When the context of @{text name} is
   707   subsequently entered, traversing the locale hierarchy will involve
   708   the locale instances of @{text expr}, and their declarations will be
   709   added to the context.  This makes @{command "sublocale"}
   710   dynamic: extensions of a locale that is instantiated in @{text expr}
   711   may take place after the @{command "sublocale"} declaration and
   712   still become available in the context.  Circular @{command
   713   "sublocale"} declarations are allowed as long as they do not lead to
   714   infinite chains.
   715 
   716   If interpretations of @{text name} exist in the current global
   717   theory, the command adds interpretations for @{text expr} as well,
   718   with the same qualifier, although only for fragments of @{text expr}
   719   that are not interpreted in the theory already.
   720 
   721   The equations @{text eqns} amend the morphism through
   722   which @{text expr} is interpreted.  This enables mapping definitions
   723   from the interpreted locales to entities of @{text name} and can
   724   help break infinite chains induced by circular @{command
   725   "sublocale"} declarations.
   726 
   727   In a named context block the @{command sublocale} command may also
   728   be used, but the locale argument must be omitted.  The command then
   729   refers to the locale (or class) target of the context block.
   730 
   731   \item @{command "print_dependencies"}~@{text "expr"} is useful for
   732   understanding the effect of an interpretation of @{text "expr"} in
   733   the current context.  It lists all locale instances for which
   734   interpretations would be added to the current context.  Variant
   735   @{command "print_dependencies"}@{text "!"} does not generalize
   736   parameters and assumes an empty context --- that is, it prints all
   737   locale instances that would be considered for interpretation.  The
   738   latter is useful for understanding the dependencies of a locale
   739   expression.
   740 
   741   \item @{command "print_interps"}~@{text "locale"} lists all
   742   interpretations of @{text "locale"} in the current theory or proof
   743   context, including those due to a combination of an @{command
   744   "interpretation"} or @{command "interpret"} and one or several
   745   @{command "sublocale"} declarations.
   746 
   747   \end{description}
   748 
   749   \begin{warn}
   750     If a global theory inherits declarations (body elements) for a
   751     locale from one parent and an interpretation of that locale from
   752     another parent, the interpretation will not be applied to the
   753     declarations.
   754   \end{warn}
   755 
   756   \begin{warn}
   757     Since attributes are applied to interpreted theorems,
   758     interpretation may modify the context of common proof tools, e.g.\
   759     the Simplifier or Classical Reasoner.  As the behavior of such
   760     tools is \emph{not} stable under interpretation morphisms, manual
   761     declarations might have to be added to the target context of the
   762     interpretation to revert such declarations.
   763   \end{warn}
   764 
   765   \begin{warn}
   766     An interpretation in a local theory or proof context may subsume previous
   767     interpretations.  This happens if the same specification fragment
   768     is interpreted twice and the instantiation of the second
   769     interpretation is more general than the interpretation of the
   770     first.  The locale package does not attempt to remove subsumed
   771     interpretations.
   772   \end{warn}
   773 *}
   774 
   775 
   776 section {* Classes \label{sec:class} *}
   777 
   778 text {*
   779   \begin{matharray}{rcl}
   780     @{command_def "class"} & : & @{text "theory \<rightarrow> local_theory"} \\
   781     @{command_def "instantiation"} & : & @{text "theory \<rightarrow> local_theory"} \\
   782     @{command_def "instance"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   783     @{command "instance"} & : & @{text "theory \<rightarrow> proof(prove)"} \\
   784     @{command_def "subclass"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
   785     @{command_def "print_classes"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   786     @{command_def "class_deps"}@{text "\<^sup>*"} & : & @{text "context \<rightarrow>"} \\
   787     @{method_def intro_classes} & : & @{text method} \\
   788   \end{matharray}
   789 
   790   A class is a particular locale with \emph{exactly one} type variable
   791   @{text \<alpha>}.  Beyond the underlying locale, a corresponding type class
   792   is established which is interpreted logically as axiomatic type
   793   class \cite{Wenzel:1997:TPHOL} whose logical content are the
   794   assumptions of the locale.  Thus, classes provide the full
   795   generality of locales combined with the commodity of type classes
   796   (notably type-inference).  See \cite{isabelle-classes} for a short
   797   tutorial.
   798 
   799   @{rail \<open>
   800     @@{command class} class_spec @'begin'?
   801     ;
   802     class_spec: @{syntax name} '='
   803       ((@{syntax nameref} '+' (@{syntax context_elem}+)) |
   804         @{syntax nameref} | (@{syntax context_elem}+))      
   805     ;
   806     @@{command instantiation} (@{syntax nameref} + @'and') '::' @{syntax arity} @'begin'
   807     ;
   808     @@{command instance} (() | (@{syntax nameref} + @'and') '::' @{syntax arity} |
   809       @{syntax nameref} ('<' | '\<subseteq>') @{syntax nameref} )
   810     ;
   811     @@{command subclass} @{syntax target}? @{syntax nameref}
   812   \<close>}
   813 
   814   \begin{description}
   815 
   816   \item @{command "class"}~@{text "c = superclasses + body"} defines
   817   a new class @{text c}, inheriting from @{text superclasses}.  This
   818   introduces a locale @{text c} with import of all locales @{text
   819   superclasses}.
   820 
   821   Any @{element "fixes"} in @{text body} are lifted to the global
   822   theory level (\emph{class operations} @{text "f\<^sub>1, \<dots>,
   823   f\<^sub>n"} of class @{text c}), mapping the local type parameter
   824   @{text \<alpha>} to a schematic type variable @{text "?\<alpha> :: c"}.
   825 
   826   Likewise, @{element "assumes"} in @{text body} are also lifted,
   827   mapping each local parameter @{text "f :: \<tau>[\<alpha>]"} to its
   828   corresponding global constant @{text "f :: \<tau>[?\<alpha> :: c]"}.  The
   829   corresponding introduction rule is provided as @{text
   830   c_class_axioms.intro}.  This rule should be rarely needed directly
   831   --- the @{method intro_classes} method takes care of the details of
   832   class membership proofs.
   833 
   834   \item @{command "instantiation"}~@{text "t :: (s\<^sub>1, \<dots>, s\<^sub>n)s
   835   \<BEGIN>"} opens a target (cf.\ \secref{sec:target}) which
   836   allows to specify class operations @{text "f\<^sub>1, \<dots>, f\<^sub>n"} corresponding
   837   to sort @{text s} at the particular type instance @{text "(\<alpha>\<^sub>1 :: s\<^sub>1,
   838   \<dots>, \<alpha>\<^sub>n :: s\<^sub>n) t"}.  A plain @{command "instance"} command in the
   839   target body poses a goal stating these type arities.  The target is
   840   concluded by an @{command_ref (local) "end"} command.
   841 
   842   Note that a list of simultaneous type constructors may be given;
   843   this corresponds nicely to mutually recursive type definitions, e.g.\
   844   in Isabelle/HOL.
   845 
   846   \item @{command "instance"} in an instantiation target body sets
   847   up a goal stating the type arities claimed at the opening @{command
   848   "instantiation"}.  The proof would usually proceed by @{method
   849   intro_classes}, and then establish the characteristic theorems of
   850   the type classes involved.  After finishing the proof, the
   851   background theory will be augmented by the proven type arities.
   852 
   853   On the theory level, @{command "instance"}~@{text "t :: (s\<^sub>1, \<dots>,
   854   s\<^sub>n)s"} provides a convenient way to instantiate a type class with no
   855   need to specify operations: one can continue with the
   856   instantiation proof immediately.
   857 
   858   \item @{command "subclass"}~@{text c} in a class context for class
   859   @{text d} sets up a goal stating that class @{text c} is logically
   860   contained in class @{text d}.  After finishing the proof, class
   861   @{text d} is proven to be subclass @{text c} and the locale @{text
   862   c} is interpreted into @{text d} simultaneously.
   863 
   864   A weakend form of this is available through a further variant of
   865   @{command instance}:  @{command instance}~@{text "c\<^sub>1 \<subseteq> c\<^sub>2"} opens
   866   a proof that class @{text "c\<^sub>2"} implies @{text "c\<^sub>1"} without reference
   867   to the underlying locales;  this is useful if the properties to prove
   868   the logical connection are not sufficent on the locale level but on
   869   the theory level.
   870 
   871   \item @{command "print_classes"} prints all classes in the current
   872   theory.
   873 
   874   \item @{command "class_deps"} visualizes all classes and their
   875   subclass relations as a Hasse diagram.
   876 
   877   \item @{method intro_classes} repeatedly expands all class
   878   introduction rules of this theory.  Note that this method usually
   879   needs not be named explicitly, as it is already included in the
   880   default proof step (e.g.\ of @{command "proof"}).  In particular,
   881   instantiation of trivial (syntactic) classes may be performed by a
   882   single ``@{command ".."}'' proof step.
   883 
   884   \end{description}
   885 *}
   886 
   887 
   888 subsection {* The class target *}
   889 
   890 text {*
   891   %FIXME check
   892 
   893   A named context may refer to a locale (cf.\ \secref{sec:target}).
   894   If this locale is also a class @{text c}, apart from the common
   895   locale target behaviour the following happens.
   896 
   897   \begin{itemize}
   898 
   899   \item Local constant declarations @{text "g[\<alpha>]"} referring to the
   900   local type parameter @{text \<alpha>} and local parameters @{text "f[\<alpha>]"}
   901   are accompanied by theory-level constants @{text "g[?\<alpha> :: c]"}
   902   referring to theory-level class operations @{text "f[?\<alpha> :: c]"}.
   903 
   904   \item Local theorem bindings are lifted as are assumptions.
   905 
   906   \item Local syntax refers to local operations @{text "g[\<alpha>]"} and
   907   global operations @{text "g[?\<alpha> :: c]"} uniformly.  Type inference
   908   resolves ambiguities.  In rare cases, manual type annotations are
   909   needed.
   910   
   911   \end{itemize}
   912 *}
   913 
   914 
   915 subsection {* Co-regularity of type classes and arities *}
   916 
   917 text {* The class relation together with the collection of
   918   type-constructor arities must obey the principle of
   919   \emph{co-regularity} as defined below.
   920 
   921   \medskip For the subsequent formulation of co-regularity we assume
   922   that the class relation is closed by transitivity and reflexivity.
   923   Moreover the collection of arities @{text "t :: (\<^vec>s)c"} is
   924   completed such that @{text "t :: (\<^vec>s)c"} and @{text "c \<subseteq> c'"}
   925   implies @{text "t :: (\<^vec>s)c'"} for all such declarations.
   926 
   927   Treating sorts as finite sets of classes (meaning the intersection),
   928   the class relation @{text "c\<^sub>1 \<subseteq> c\<^sub>2"} is extended to sorts as
   929   follows:
   930   \[
   931     @{text "s\<^sub>1 \<subseteq> s\<^sub>2 \<equiv> \<forall>c\<^sub>2 \<in> s\<^sub>2. \<exists>c\<^sub>1 \<in> s\<^sub>1. c\<^sub>1 \<subseteq> c\<^sub>2"}
   932   \]
   933 
   934   This relation on sorts is further extended to tuples of sorts (of
   935   the same length) in the component-wise way.
   936 
   937   \smallskip Co-regularity of the class relation together with the
   938   arities relation means:
   939   \[
   940     @{text "t :: (\<^vec>s\<^sub>1)c\<^sub>1 \<Longrightarrow> t :: (\<^vec>s\<^sub>2)c\<^sub>2 \<Longrightarrow> c\<^sub>1 \<subseteq> c\<^sub>2 \<Longrightarrow> \<^vec>s\<^sub>1 \<subseteq> \<^vec>s\<^sub>2"}
   941   \]
   942   \noindent for all such arities.  In other words, whenever the result
   943   classes of some type-constructor arities are related, then the
   944   argument sorts need to be related in the same way.
   945 
   946   \medskip Co-regularity is a very fundamental property of the
   947   order-sorted algebra of types.  For example, it entails principle
   948   types and most general unifiers, e.g.\ see \cite{nipkow-prehofer}.
   949 *}
   950 
   951 
   952 section {* Unrestricted overloading *}
   953 
   954 text {*
   955   \begin{matharray}{rcl}
   956     @{command_def "overloading"} & : & @{text "theory \<rightarrow> local_theory"} \\
   957   \end{matharray}
   958 
   959   Isabelle/Pure's definitional schemes support certain forms of
   960   overloading (see \secref{sec:consts}).  Overloading means that a
   961   constant being declared as @{text "c :: \<alpha> decl"} may be
   962   defined separately on type instances
   963   @{text "c :: (\<beta>\<^sub>1, \<dots>, \<beta>\<^sub>n) t decl"}
   964   for each type constructor @{text t}.  At most occassions
   965   overloading will be used in a Haskell-like fashion together with
   966   type classes by means of @{command "instantiation"} (see
   967   \secref{sec:class}).  Sometimes low-level overloading is desirable.
   968   The @{command "overloading"} target provides a convenient view for
   969   end-users.
   970 
   971   @{rail \<open>
   972     @@{command overloading} ( spec + ) @'begin'
   973     ;
   974     spec: @{syntax name} ( '==' | '\<equiv>' ) @{syntax term} ( '(' @'unchecked' ')' )?
   975   \<close>}
   976 
   977   \begin{description}
   978 
   979   \item @{command "overloading"}~@{text "x\<^sub>1 \<equiv> c\<^sub>1 :: \<tau>\<^sub>1 \<AND> \<dots> x\<^sub>n \<equiv> c\<^sub>n :: \<tau>\<^sub>n \<BEGIN>"}
   980   opens a theory target (cf.\ \secref{sec:target}) which allows to
   981   specify constants with overloaded definitions.  These are identified
   982   by an explicitly given mapping from variable names @{text "x\<^sub>i"} to
   983   constants @{text "c\<^sub>i"} at particular type instances.  The
   984   definitions themselves are established using common specification
   985   tools, using the names @{text "x\<^sub>i"} as reference to the
   986   corresponding constants.  The target is concluded by @{command
   987   (local) "end"}.
   988 
   989   A @{text "(unchecked)"} option disables global dependency checks for
   990   the corresponding definition, which is occasionally useful for
   991   exotic overloading (see \secref{sec:consts} for a precise description).
   992   It is at the discretion of the user to avoid
   993   malformed theory specifications!
   994 
   995   \end{description}
   996 *}
   997 
   998 
   999 section {* Incorporating ML code \label{sec:ML} *}
  1000 
  1001 text {*
  1002   \begin{matharray}{rcl}
  1003     @{command_def "SML_file"} & : & @{text "theory \<rightarrow> theory"} \\
  1004     @{command_def "ML_file"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1005     @{command_def "ML"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1006     @{command_def "ML_prf"} & : & @{text "proof \<rightarrow> proof"} \\
  1007     @{command_def "ML_val"} & : & @{text "any \<rightarrow>"} \\
  1008     @{command_def "ML_command"} & : & @{text "any \<rightarrow>"} \\
  1009     @{command_def "setup"} & : & @{text "theory \<rightarrow> theory"} \\
  1010     @{command_def "local_setup"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1011     @{command_def "attribute_setup"} & : & @{text "theory \<rightarrow> theory"} \\
  1012   \end{matharray}
  1013 
  1014   @{rail \<open>
  1015     (@@{command SML_file} | @@{command ML_file}) @{syntax name}
  1016     ;
  1017     (@@{command ML} | @@{command ML_prf} | @@{command ML_val} |
  1018       @@{command ML_command} | @@{command setup} | @@{command local_setup}) @{syntax text}
  1019     ;
  1020     @@{command attribute_setup} @{syntax name} '=' @{syntax text} @{syntax text}?
  1021   \<close>}
  1022 
  1023   \begin{description}
  1024 
  1025   \item @{command "SML_file"}~@{text "name"} reads and evaluates the
  1026   given Standard ML file.  Top-level SML bindings are stored within
  1027   the theory context; the initial environment is restricted to the
  1028   Standard ML implementation of Poly/ML, without the many add-ons of
  1029   Isabelle/ML.  Multiple @{command "SML_file"} commands may be used to
  1030   build larger Standard ML projects, independently of the regular
  1031   Isabelle/ML environment.
  1032 
  1033   \item @{command "ML_file"}~@{text "name"} reads and evaluates the
  1034   given ML file.  The current theory context is passed down to the ML
  1035   toplevel and may be modified, using @{ML "Context.>>"} or derived ML
  1036   commands.  Top-level ML bindings are stored within the (global or
  1037   local) theory context.
  1038   
  1039   \item @{command "ML"}~@{text "text"} is similar to @{command
  1040   "ML_file"}, but evaluates directly the given @{text "text"}.
  1041   Top-level ML bindings are stored within the (global or local) theory
  1042   context.
  1043 
  1044   \item @{command "ML_prf"} is analogous to @{command "ML"} but works
  1045   within a proof context.  Top-level ML bindings are stored within the
  1046   proof context in a purely sequential fashion, disregarding the
  1047   nested proof structure.  ML bindings introduced by @{command
  1048   "ML_prf"} are discarded at the end of the proof.
  1049 
  1050   \item @{command "ML_val"} and @{command "ML_command"} are diagnostic
  1051   versions of @{command "ML"}, which means that the context may not be
  1052   updated.  @{command "ML_val"} echos the bindings produced at the ML
  1053   toplevel, but @{command "ML_command"} is silent.
  1054   
  1055   \item @{command "setup"}~@{text "text"} changes the current theory
  1056   context by applying @{text "text"}, which refers to an ML expression
  1057   of type @{ML_type "theory -> theory"}.  This enables to initialize
  1058   any object-logic specific tools and packages written in ML, for
  1059   example.
  1060 
  1061   \item @{command "local_setup"} is similar to @{command "setup"} for
  1062   a local theory context, and an ML expression of type @{ML_type
  1063   "local_theory -> local_theory"}.  This allows to
  1064   invoke local theory specification packages without going through
  1065   concrete outer syntax, for example.
  1066 
  1067   \item @{command "attribute_setup"}~@{text "name = text description"}
  1068   defines an attribute in the current theory.  The given @{text
  1069   "text"} has to be an ML expression of type
  1070   @{ML_type "attribute context_parser"}, cf.\ basic parsers defined in
  1071   structure @{ML_structure Args} and @{ML_structure Attrib}.
  1072 
  1073   In principle, attributes can operate both on a given theorem and the
  1074   implicit context, although in practice only one is modified and the
  1075   other serves as parameter.  Here are examples for these two cases:
  1076 
  1077   \end{description}
  1078 *}
  1079 
  1080   attribute_setup my_rule = {*
  1081     Attrib.thms >> (fn ths =>
  1082       Thm.rule_attribute
  1083         (fn context: Context.generic => fn th: thm =>
  1084           let val th' = th OF ths
  1085           in th' end)) *}
  1086 
  1087   attribute_setup my_declaration = {*
  1088     Attrib.thms >> (fn ths =>
  1089       Thm.declaration_attribute
  1090         (fn th: thm => fn context: Context.generic =>
  1091           let val context' = context
  1092           in context' end)) *}
  1093 
  1094 
  1095 section {* Primitive specification elements *}
  1096 
  1097 subsection {* Sorts *}
  1098 
  1099 text {*
  1100   \begin{matharray}{rcll}
  1101     @{command_def "default_sort"} & : & @{text "local_theory \<rightarrow> local_theory"}
  1102   \end{matharray}
  1103 
  1104   @{rail \<open>
  1105     @@{command default_sort} @{syntax sort}
  1106   \<close>}
  1107 
  1108   \begin{description}
  1109 
  1110   \item @{command "default_sort"}~@{text s} makes sort @{text s} the
  1111   new default sort for any type variable that is given explicitly in
  1112   the text, but lacks a sort constraint (wrt.\ the current context).
  1113   Type variables generated by type inference are not affected.
  1114 
  1115   Usually the default sort is only changed when defining a new
  1116   object-logic.  For example, the default sort in Isabelle/HOL is
  1117   @{class type}, the class of all HOL types.
  1118 
  1119   When merging theories, the default sorts of the parents are
  1120   logically intersected, i.e.\ the representations as lists of classes
  1121   are joined.
  1122 
  1123   \end{description}
  1124 *}
  1125 
  1126 
  1127 subsection {* Types and type abbreviations \label{sec:types-pure} *}
  1128 
  1129 text {*
  1130   \begin{matharray}{rcll}
  1131     @{command_def "type_synonym"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1132     @{command_def "typedecl"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1133   \end{matharray}
  1134 
  1135   @{rail \<open>
  1136     @@{command type_synonym} (@{syntax typespec} '=' @{syntax type} @{syntax mixfix}?)
  1137     ;
  1138     @@{command typedecl} @{syntax typespec} @{syntax mixfix}?
  1139   \<close>}
  1140 
  1141   \begin{description}
  1142 
  1143   \item @{command "type_synonym"}~@{text "(\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>n) t = \<tau>"}
  1144   introduces a \emph{type synonym} @{text "(\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>n) t"} for the
  1145   existing type @{text "\<tau>"}.  Unlike actual type definitions, as are
  1146   available in Isabelle/HOL for example, type synonyms are merely
  1147   syntactic abbreviations without any logical significance.
  1148   Internally, type synonyms are fully expanded.
  1149   
  1150   \item @{command "typedecl"}~@{text "(\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>n) t"} declares a new
  1151   type constructor @{text t}.  If the object-logic defines a base sort
  1152   @{text s}, then the constructor is declared to operate on that, via
  1153   the axiomatic type-class instance @{text "t :: (s, \<dots>, s)s"}.
  1154 
  1155   \end{description}
  1156 *}
  1157 
  1158 
  1159 subsection {* Constants and definitions \label{sec:consts} *}
  1160 
  1161 text {*
  1162   \begin{matharray}{rcl}
  1163     @{command_def "consts"} & : & @{text "theory \<rightarrow> theory"} \\
  1164     @{command_def "defs"} & : & @{text "theory \<rightarrow> theory"} \\
  1165   \end{matharray}
  1166 
  1167   Definitions essentially express abbreviations within the logic.  The
  1168   simplest form of a definition is @{text "c :: \<sigma> \<equiv> t"}, where @{text
  1169   c} is a newly declared constant.  Isabelle also allows derived forms
  1170   where the arguments of @{text c} appear on the left, abbreviating a
  1171   prefix of @{text \<lambda>}-abstractions, e.g.\ @{text "c \<equiv> \<lambda>x y. t"} may be
  1172   written more conveniently as @{text "c x y \<equiv> t"}.  Moreover,
  1173   definitions may be weakened by adding arbitrary pre-conditions:
  1174   @{text "A \<Longrightarrow> c x y \<equiv> t"}.
  1175 
  1176   \medskip The built-in well-formedness conditions for definitional
  1177   specifications are:
  1178 
  1179   \begin{itemize}
  1180 
  1181   \item Arguments (on the left-hand side) must be distinct variables.
  1182 
  1183   \item All variables on the right-hand side must also appear on the
  1184   left-hand side.
  1185 
  1186   \item All type variables on the right-hand side must also appear on
  1187   the left-hand side; this prohibits @{text "0 :: nat \<equiv> length ([] ::
  1188   \<alpha> list)"} for example.
  1189 
  1190   \item The definition must not be recursive.  Most object-logics
  1191   provide definitional principles that can be used to express
  1192   recursion safely.
  1193 
  1194   \end{itemize}
  1195 
  1196   The right-hand side of overloaded definitions may mention overloaded constants
  1197   recursively at type instances corresponding to the immediate
  1198   argument types @{text "\<beta>\<^sub>1, \<dots>, \<beta>\<^sub>n"}.  Incomplete
  1199   specification patterns impose global constraints on all occurrences,
  1200   e.g.\ @{text "d :: \<alpha> \<times> \<alpha>"} on the left-hand side means that all
  1201   corresponding occurrences on some right-hand side need to be an
  1202   instance of this, general @{text "d :: \<alpha> \<times> \<beta>"} will be disallowed.
  1203 
  1204   @{rail \<open>
  1205     @@{command consts} ((@{syntax name} '::' @{syntax type} @{syntax mixfix}?) +)
  1206     ;
  1207     @@{command defs} opt? (@{syntax axmdecl} @{syntax prop} +)
  1208     ;
  1209     opt: '(' @'unchecked'? @'overloaded'? ')'
  1210   \<close>}
  1211 
  1212   \begin{description}
  1213 
  1214   \item @{command "consts"}~@{text "c :: \<sigma>"} declares constant @{text
  1215   c} to have any instance of type scheme @{text \<sigma>}.  The optional
  1216   mixfix annotations may attach concrete syntax to the constants
  1217   declared.
  1218   
  1219   \item @{command "defs"}~@{text "name: eqn"} introduces @{text eqn}
  1220   as a definitional axiom for some existing constant.
  1221   
  1222   The @{text "(unchecked)"} option disables global dependency checks
  1223   for this definition, which is occasionally useful for exotic
  1224   overloading.  It is at the discretion of the user to avoid malformed
  1225   theory specifications!
  1226   
  1227   The @{text "(overloaded)"} option declares definitions to be
  1228   potentially overloaded.  Unless this option is given, a warning
  1229   message would be issued for any definitional equation with a more
  1230   special type than that of the corresponding constant declaration.
  1231   
  1232   \end{description}
  1233 *}
  1234 
  1235 
  1236 section {* Naming existing theorems \label{sec:theorems} *}
  1237 
  1238 text {*
  1239   \begin{matharray}{rcll}
  1240     @{command_def "lemmas"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1241     @{command_def "theorems"} & : & @{text "local_theory \<rightarrow> local_theory"} \\
  1242   \end{matharray}
  1243 
  1244   @{rail \<open>
  1245     (@@{command lemmas} | @@{command theorems}) @{syntax target}? \<newline>
  1246       (@{syntax thmdef}? @{syntax thmrefs} + @'and')
  1247       (@'for' (@{syntax vars} + @'and'))?
  1248   \<close>}
  1249 
  1250   \begin{description}
  1251   
  1252   \item @{command "lemmas"}~@{text "a = b\<^sub>1 \<dots> b\<^sub>n"}~@{keyword_def
  1253   "for"}~@{text "x\<^sub>1 \<dots> x\<^sub>m"} evaluates given facts (with attributes) in
  1254   the current context, which may be augmented by local variables.
  1255   Results are standardized before being stored, i.e.\ schematic
  1256   variables are renamed to enforce index @{text "0"} uniformly.
  1257 
  1258   \item @{command "theorems"} is the same as @{command "lemmas"}, but
  1259   marks the result as a different kind of facts.
  1260 
  1261   \end{description}
  1262 *}
  1263 
  1264 
  1265 section {* Oracles *}
  1266 
  1267 text {*
  1268   \begin{matharray}{rcll}
  1269     @{command_def "oracle"} & : & @{text "theory \<rightarrow> theory"} & (axiomatic!) \\
  1270   \end{matharray}
  1271 
  1272   Oracles allow Isabelle to take advantage of external reasoners such
  1273   as arithmetic decision procedures, model checkers, fast tautology
  1274   checkers or computer algebra systems.  Invoked as an oracle, an
  1275   external reasoner can create arbitrary Isabelle theorems.
  1276 
  1277   It is the responsibility of the user to ensure that the external
  1278   reasoner is as trustworthy as the application requires.  Another
  1279   typical source of errors is the linkup between Isabelle and the
  1280   external tool, not just its concrete implementation, but also the
  1281   required translation between two different logical environments.
  1282 
  1283   Isabelle merely guarantees well-formedness of the propositions being
  1284   asserted, and records within the internal derivation object how
  1285   presumed theorems depend on unproven suppositions.
  1286 
  1287   @{rail \<open>
  1288     @@{command oracle} @{syntax name} '=' @{syntax text}
  1289   \<close>}
  1290 
  1291   \begin{description}
  1292 
  1293   \item @{command "oracle"}~@{text "name = text"} turns the given ML
  1294   expression @{text "text"} of type @{ML_text "'a -> cterm"} into an
  1295   ML function of type @{ML_text "'a -> thm"}, which is bound to the
  1296   global identifier @{ML_text name}.  This acts like an infinitary
  1297   specification of axioms!  Invoking the oracle only works within the
  1298   scope of the resulting theory.
  1299 
  1300   \end{description}
  1301 
  1302   See @{file "~~/src/HOL/ex/Iff_Oracle.thy"} for a worked example of
  1303   defining a new primitive rule as oracle, and turning it into a proof
  1304   method.
  1305 *}
  1306 
  1307 
  1308 section {* Name spaces *}
  1309 
  1310 text {*
  1311   \begin{matharray}{rcl}
  1312     @{command_def "hide_class"} & : & @{text "theory \<rightarrow> theory"} \\
  1313     @{command_def "hide_type"} & : & @{text "theory \<rightarrow> theory"} \\
  1314     @{command_def "hide_const"} & : & @{text "theory \<rightarrow> theory"} \\
  1315     @{command_def "hide_fact"} & : & @{text "theory \<rightarrow> theory"} \\
  1316   \end{matharray}
  1317 
  1318   @{rail \<open>
  1319     ( @{command hide_class} | @{command hide_type} |
  1320       @{command hide_const} | @{command hide_fact} ) ('(' @'open' ')')? (@{syntax nameref} + )
  1321   \<close>}
  1322 
  1323   Isabelle organizes any kind of name declarations (of types,
  1324   constants, theorems etc.) by separate hierarchically structured name
  1325   spaces.  Normally the user does not have to control the behavior of
  1326   name spaces by hand, yet the following commands provide some way to
  1327   do so.
  1328 
  1329   \begin{description}
  1330 
  1331   \item @{command "hide_class"}~@{text names} fully removes class
  1332   declarations from a given name space; with the @{text "(open)"}
  1333   option, only the base name is hidden.
  1334 
  1335   Note that hiding name space accesses has no impact on logical
  1336   declarations --- they remain valid internally.  Entities that are no
  1337   longer accessible to the user are printed with the special qualifier
  1338   ``@{text "??"}'' prefixed to the full internal name.
  1339 
  1340   \item @{command "hide_type"}, @{command "hide_const"}, and @{command
  1341   "hide_fact"} are similar to @{command "hide_class"}, but hide types,
  1342   constants, and facts, respectively.
  1343   
  1344   \end{description}
  1345 *}
  1346 
  1347 end