There are three main aims for this change:
1. Don't rely so much on users having knowledge of Prolog (ideally we
wouldn't require it at all, but this change probably doesn't fully achieve
that). Present the information more linearly, i.e., without requiring
so many forward references.
2. Make important information less likely to be overlooked. As it stands,
we give a lot of semantics in the Syntax chapter where users wouldn't
expect to find it (they're more likely to just skim over such a chapter).
3. Remove some inconsistencies in our descriptions and use of terminology,
and try to remove ambiguities.
Changes to terminology
----------------------
These are aimed at being more consistent, as well as dividing things up
into concepts that we need to refer to later on.
- A term is now a core term or a special term. The latter are for list
syntax, etc. Avoid the use of "is parsed as", the significance of which
is not clear, and instead define an equivalence relation via a term
normalization procedure.
- Define "functor" and "principal functor". Don't use "functor" to talk
about terms: the functor is defined as the name/arity pair. Also give
some synonyms we use for functor.
- Core terms are divided into variables, constants, and functor terms.
Functor terms are names on their own or names with arguments
(i.e., "functor terms" are those terms that have meaningful functors).
- "Higher-order terms" are now called "apply terms", since they aren't
necessarily higher-order themselves, and because that is a semantic
concept anyway.
- Data-terms are now referred to as expressions.
- Refer to "field access" rather than "record syntax". It's not made clear
that these are referring to the same feature, so it's better to stick to
one term (at least until full definitions are given).
Changes to document structure
-----------------------------
The Syntax chapter as a whole has been split into two chapters,
Syntax and Clauses. The new structure is as follows:
Syntax
- Additional sections are added for comments and line number directives.
- The Tokens section is split into token types (so that, e.g., variables
can be looked up quickly).
- "Operators" covers everything about operator syntax, not just builtin
operators.
- "Terms" covers the material previously in that section. It adds a summary
in the form of grammar rules (but makes it clear all the information is
also in the prose), and a term normalization procedure that is _not_
written in pseudo-Mercury. The grammar is there for people who are likely
to skip the prose but less likely to skip a grammar, and the prose is there
because that's the best way to describe things.
- "Items" covers the material previously in "Items", "Declarations",
"Facts", and "Rules".
Clauses
- Added an overview of Mercury semantics.
- "Goals" covers the same material as before, but I have rearranged the
order of the goals so as to avoid forward references, and to put more
commonly used goals earlier.
- "Expressions" covers the material previously in "Data-terms" and its
subsections. The expressions are (mostly) collected into one table, but
field access expressions are kept separate as they require a bit more
explanation. I've used an anchor on this separate bit, however, so maybe
it should be in a section that follows Expressions (i.e., Expressions
should say "see next section for details" or whatever).
- "State variables", "Variable scoping", "Implicit quantifiaction", and
"Elimination of double negation" are kept largely as is.
- "Definite Clause Grammars" is added which collects all the information
relating to DCGs.
Other changes
-------------
- Names now include sequences of graphic chars and a single semicolon,
which is what our parser actually allows.
- Use hyphens in meta-variables rather than underscore, per the texinfo
guidelines.
- Explain that operators are a syntactic concept and you need to import
a module to get, e.g., arithmetic operations. Point out the user defined
operator in the prose rather than in a footnote. And fix the formatting
of that table!
- Try to use a more consistent writing style.
doc/*.texi:
Use @copyright{} in the HTML version fo the copyright notices.
Use long dashes in date ranges as per the PDF version.
Put each copyright holder on their own line.
These are effectively a review of Zoltan's recent changes.
doc/transition_guide.texi:
The there is no longer a bintree module in the standard library and
rtree is very definitely a map ADT with a specialized purpose.
Fix spelling, typos and missing words.
Avoid breaking examples across pages it the PDF version.
Fix the years in copyright messages so that they record move from The
University of Melbourne to The Mercury Team correctly.
I recall the time correctly because it's when i submitted my thesis :-)
.README.in:
bindist/bindist.README:
compiler/handle_options.m:
doc/faq.texi:
doc/library.texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
profiler/mercury_profile.m:
trace/mercury_trace_internal.c:
As above.
Other documentation fixes.
compiler/options.m:
Add missing quotes around options referred to in the bodies of option
descriptions.
s/Don't warn/Do not warn/ throughout the warning options section.
Fix inconsistent hyphenation:
- s/up to date/up-to-date/
- s/backend/back-end/
The 'csharp' and 'erlang' grade components were missing from
the description of the --grade option. (They are present in the User's
Guide version.)
Do not include an "=" between the option and its argument description
fo the --experimental-complexity option, we don't do this anywhere
else.
Add a sentence saying that the '--single-prec-float' option is not
supported on the non-C backends. (The User's Guide had this sentence,
the usage message did not.)
The description of `--higher-order-arg-limit' was missing the fact
that it takes an argument.
Be consistent about how alternative option values are shown:
{alt1, alt2, ... altN} rather than {alt1|alt2|...|altN}.
doc/user_guide.texi:
Make this consistent with the usage message (or vice versa).
doc/reference_manual.texi:
Add missing markup around "pragma foreign_proc".
doc/transition_guide.texi:
Add markup around library predicate names.
Branches: main, 11.07
.README.in:
bindist/bindist.README:
compiler/handle_options.m:
doc/*.texi:
profiler/mercury_profile.m:
trace/mercury_trace_internal.c:
Bump the year in the copyright messages.
Branches: main, 11.01
Fix a number of documentation issues.
doc/reference_manual.texi:
Briefly describe event goals and point the user towards the User's
Guide for the actual documentation of that feature.
This addresses bug #198.
Extend the ``Tabled evaluation'' section to describe tabling
of foreign types.
Add a pointer from the ``Using foreign types from Mercury'' section
to the ``Tabled evaluation'' section. The former describes the
foreign type assertions that make tabling of foreign types possible.
Fix an inconsistency: it should be (and usually is) "I/O" rather than "IO"
in all but code examples.
Fix some texinfo style issues.
doc/transition_guide.texi:
s/IO/I\/O/ as above.
Branches: main, 11.01
.README.in:
bindist/bindist.README:
compiler/handle_options.m:
doc/*.texi:
profiler/mercury_profile.m:
trace/mercury_trace_internal.c:
Bump the year in the usage messages.
Branches: main, 10.04
Update the TODO and WORK_IN_PROGRESS files.
Don't give the impression that we might support user-defined operators at
some point in the future; this is not likely to happen.
compiler/notes/todo:
Remove some things that have now been implemented from the todo list.
Remove user-defined operators from the wishlist.
compiler/notes/work_in_progress.html:
Remove the Java backend and lco from the list of work-in-progress.
doc/transition_guide.texi:
Don't give the impression that Mercury might support user-defined
operators.
.README.in:
bindist/bindist.README:
compiler/handle_options.m:
doc/*.texi:
profiler/mercury_profile.m:
trace/mercury_trace_internal.c:
Bump the year in the copyright message.
.README.in:
bindist/bindist.README:
compiler/handle_options.m:
doc/faq.texi:
doc/library/texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
profiler/mercury_profile.m:
trace/mercury_trace_internal.c:
Bump the year in the usage messages.
Estimated hours taken: 0.1
Branches: main
Update copyright messages.
.README.in:
compiler/handle_options.m:
doc/faq.texi:
doc/library/texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
profiler/mercury_profile.m:
trace/mercury_trace_internal.c:
Bump the year in the copyright messages to 2008.
INSTALL_CVS:
Update a comment: we now require autoconf version 2.58 or greater.
Estimated hours taken: 0.5
Branches: main
Use `.' as a module qualification operator throughout
the compiler documentation.
Make sure that the documentation does not refer to syntax
that is now deprecated.
XXX The library reference still uses `__' in most places
but that will have to wait until those library modules are
changed over to use the new syntax.
doc/reference_manual.texi:
Remove the comment saying we should make this change.
s/is/=/ in a few spots.
doc/transition_guide.texi:
Replace an instance of the old-style lambda syntax.
doc/faq.texi:
doc/user_guide.texi:
As above.
Estimated hours taken: 0.1
Branches: main
doc/faq.texi:
doc/library.texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
Change some copyright dates from 2003 to 2004 in various
places.
Estimated hours taken: 3
Branches: main
doc/Mmakefile:
Use `makeinfo --html' rather than `perl texi2html' for creating
the HTML version of the documentation. Since makeinfo outputs
the HTML to different file names than texi2html, this also required
various other changes to handle the different file names.
doc/faq.texi:
doc/library.texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
Change @ifinfo to @ifnottex.
Uncomment the @dircategory commands, which were previously commented
out because they weren't supported by (our old version of) texi2html.
Update copyright dates.
Estimated hours taken: 2
Typographical changes for printed output.
Very little change made to the produced info files.
Also fix a C code example in reference_manual.texi.
doc/faq.texi:
doc/library.texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
Change en dashes to --, em dashes to ---, minus sign as @minus{}.
(Rendered as -,--,- respectively in info.)
Use @: after `e.g.', `i.e.', etc. to indicate word space rather than
sentence space.
Change `...' to `@dots{}'.
Change " to `` or '' (other than in code). (Rendered as " in info.)
doc/reference_manual.texi:
(Language specific bindings): Wrap `"C"', `"IL"' etc. in @code{}.
(Using pragma foreign_decl for C): Fix a C code example: append `;' to
struct definition.
Estimated hours taken: 0.1
Branches: main
doc/transition_guide.texi:
Avoid saying that we have a ! predicate, since we don't anymore.
Fix some other minor problems.
Estimated hours taken: 0.1
doc/transition_guide.texi:
Remove the copy of the operator table -- there's no
point having a copy here when there is also a copy
in the reference manual. The transition guide copy
was missing some operators (`rem' and `use_module').
Estimated hours taken: 1.5
Branches: main, release
Put version identifiers in the documentation.
doc/Mmakefile:
Preprocess the `.texi' files to produce `.texi_pp' files.
The `.texi_pp' files contain the contents of the `.texi'
files with the string <VERSION> replaced by the value
of $(VERSION), which is taken from the file VERSION
in the top-level `mercury' directory.
The rules to automatically generate the `.texi' files
for the library reference manual now generate `.texi_pp' files.
This makes it clearer that they are not to be edited.
Fix a bug which was causing the library documentation on the
web page to be out of date -- library_1.html needs to depend
on library-chapters.texi_pp.
doc/faq.texi:
doc/library.texi:
doc/reference_manual.texi:
doc/transition_guide.texi:
doc/user_guide.texi:
Add version information.
Put a proper heading at the top of mercury_ref.info.
doc/mercury.html.in:
doc/mercury.info.in:
doc/mercury.html:
doc/mercury.info:
Add `.in' files which are preprocessed as for the `.texi' files.
Remove the old unpreprocessed versions.
doc/texi2html:
Allow `.texi_pp' as a suffix for the texinfo files to process.
w3/information/Makefile
Create the VERSION file, and include it in the generated
Mmake.common.
Estimated hours taken: 0.5
Branches: main
doc/texinfo.tex:
Update to the version from GNU TexInfo 4.0.
doc/*.texi:
Move the table of contents from the end of the document
to the start of the document (just after the title page).
The only reason that it was at the end was that previous
versions of TexInfo didn't support putting it at the start.
Estimated hours taken: 30
Implement builtin tuple types, similar to those in Haskell.
Tuples are constructed and deconstructed using
the syntax X = {Arg1, Arg2, ...}.
Tuples have type `{Arg1, Arg2, ...}'.
Unary tuples (X = {Arg}) do work, unlike in Haskell. The rationale
for this is that it is useful to be able to construct unary tuples
to be passed to a polymorphic predicate which uses std_util__deconstruct
to deal with a tuple of any arity. Since this is probably the only
use for unary tuples, it's not really worth the effort of treating
them as no_tag types, so we don't.
The type-infos for tuples have the same structure as for higher-order
types. There is a single type_ctor_info for tuples, and the arity
is placed before the argument type_infos.
library/parser.m:
Change the way '{}/N' terms are parsed, so that the parsed
representation is consistent with the way other functors
are represented (previously the arguments were left as
unparsed ','/2 terms). This avoids special case code
in prog_io__parse_qualified_term, term__term_to_type
and term__type_to_term.
compiler/prog_io_dcg.m:
compiler/prog_io_util.m:
Handle the new structure of '{}/N' terms when parsing DCG escapes
by converting the argument list back into a single ','/2 term.
compiler/module_qual.m:
Treat tuples as a builtin type.
compiler/typecheck.m:
Typecheck tuple constructors.
compiler/mode_util.m:
Propagate types into tuple bound insts.
compiler/type_util.m:
Add type_is_tuple/2 and type_id_is_tuple/1 to identify tuple types.
Add tuples to the list of types which are not atomic types.
Handle tuple types in `type_constructors' and
`get_cons_id_arg_types' and `switch_type_num_functors'.
compiler/tabling.m:
Handle tabling of tuples.
compiler/term_util.m:
Handle tuples in the code to compute functor norms.
compiler/magic_util.m:
compiler/rl.m:
compiler/rl_key.m:
Handle tuple types in the Aditi back end.
compiler/mercury_to_mercury.m:
library/io.m:
library/term_io.m:
Handle output of '{}/N' terms.
compiler/higher_order.m:
compiler/simplify.m:
Don't specialize complicated unifications of tuple
types into calls to a specific unification procedure --
even if the procedure were implemented, it probably
wouldn't be that much more efficient.
compiler/unify_proc.m:
Generate unification procedures for complicated unifications
of tuples (other than in-in unifications). These are generated
lazily as required.
compiler/make_hlds.m:
Export add_special_pred for use by unify_proc.m.
compiler/polymorphism.m:
Export polymorphism__process_pred for use by unify_proc.m.
compiler/bytecode_gen.m:
compiler/code_util.m:
compiler/ml_code_util.m:
Handle unify procedure names and tags for tuple types.
compiler/mlds_to_c.m:
Output tuple types as MR_Tuple.
compiler/ml_unify_gen.m:
Compute the field types for tuples.
compiler/polymorphism.m:
compiler/pseudo_type_info.m:
Treat tuple type_infos in a similar way to higher-order type_infos.
compiler/hlds_data.m:
Document how cons_ids for tuple types are represented.
compiler/switch_gen.m:
compiler/table_gen.m:
Add tuple types to switches on type_util__builtin_type.
compiler/llds_out.m:
util/mdemangle.c:
profiler/demangle.m:
Transform items named "{}" to "f_tuple" when mangling symbols.
library/builtin.m:
Define the type_ctor_info used for tuples.
library/private_builtin.m:
Add `builtin_unify_tuple/2' and `builtin_compare_tuple/3',
both of which abort. All comparisons and in-in unifications
of tuples are performed by the generic unification functions
in runtime/mercury_ho_call.c and runtime/mercury.c.
library/std_util.m:
Implement the various RTTI functions for tuples.
Encode tuple `TypeCtorDesc's in a similar way to that
used for higher-order types. This has the consequence that the limit
on the arity of higher-order types is now MAX_VIRTUAL_REG,
rather than 2*MAX_VIRTUAL_REG.
Avoid calling MR_GC_free for the type-info vector returned
from ML_expand() for tuples because unlike the vectors
for du types, it is not copied.
runtime/mercury_type_info.h:
Add macros for extracting fields from tuple type-infos.
These just call the macros for extracting fields from higher-order
type-infos.
Add a macro MR_type_ctor_rep_is_variable_arity(), which
returns TRUE for tuples and higher-order types.
The distinction between higher-order and first-order types
is now misnamed -- the distinction is really between fixed arity
types and builtin variable arity types. I'm not sure whether
it's worth renaming everything.
runtime/mercury.h:
runtime/mercury.c:
Define unification and comparison of tuples in
high-level code grades.
runtime/mercury_deep_copy_body.h:
runtime/mercury_make_type_info_body.h:
runtime/mercury_tabling.c:
runtime/mercury_unify_compare_body.h:
Handle tuple types in code which traverses data using RTTI.
tests/hard_coded/construct.{m,exp}:
tests/hard_coded/expand.{m,exp}:
Test RTTI functions from std_util.m applied to tuples.
tests/hard_coded/tuple_test.{m,exp}:
Test unification, comparison, term_to_type etc. applied to tuples.
tests/hard_coded/deep_copy.{m,exp}:
Test deep copy of tuples.
tests/hard_coded/typeclasses/tuple_instance.{m,exp}:
Test instance declarations for tuples.
tests/tabling/expand_tuple.{m,exp}:
Test tabling of tuples.
tests/hard_coded/write.m:
Add some module qualifications for code which uses
`{}/1' constructors which are not tuples.
tests/invalid/errors2.{m,err_exp,err_exp2}:
Test handling of tuples in type errors messages.
NEWS:
doc/reference_manual.texi:
w3/news/newsdb.inc:
Document tuples.
doc/transition_guide.texi:
Document the change to the parsing of '{}/N' terms.
Estimated hours taken: 1.25
Add the ++ and -- operators for future use as list append and
remove_suffix operators.
library/ops.m:
Add the ++ and -- operators.
compiler/mercury_to_mercury.m:
Add the ++ and -- operators to mercury_infix_op.
doc/transition_guide.texi:
Add the ++ and -- operators to the list of Mercury
operators.
Estimated hours taken: 1
Address some issues Fergus raised in his review of the record syntax
documentation.
compiler/make_hlds.m:
tests/hard_coded/record_syntax.m:
Change the syntax for DCG field extraction from
`Value := ^ field' to `Value =^ field'.
NEWS:
doc/reference_manual.texi:
Document the changed syntax.
doc/reference_manual.texi:
Clear up the description of how to construct higher-order
terms for field access functions.
library/ops.m:
compiler/mercury_to_mercury.m:
doc/transition_guide.texi:
Add `=^' and `:=' to the operator table.
Estimated hours taken: 70
Implement syntax for getting and setting fields of constructors.
compiler/make_hlds.m:
Add information about field definitions to the module_info.
Check that user-defined field access functions for exported
fields are also exported, otherwise predicates in other modules
could use a different method to access a field than predicates
in module defining the field.
Add a `predicate preds_add_implicit_report_error' to allow that check
to be performed for functions which are added to the module_info
by some means other than a `:- func' declaration.
Parse field access goals and expressions.
Add predicates `insert_arg_unifications_with_supplied_contexts',
and `append_arg_unification', which allow more control over
the contexts given to the added unifications. These are
useful because the field value for an update is really an
argument of the inner-most update function call, while the
input term is an argument of the outer-most function call.
compiler/prog_io_dcg.m:
Allow DCG goals of the form `:=(DCGArg)', which unifies `DCGArg'
with the output DCG argument, ignoring the input DCG argument.
The rationale for this change is that if we have convenient syntax
for updating parts of a DCG argument, we should also have convenient
syntax for updating the whole DCG argument.
compiler/typecheck.m:
Add a default clause for field access functions for which
the user has supplied type and mode declarations but no
clauses.
Typecheck field access function calls.
Use `io__write_list' to remove some duplication of code
to write out comma separated lists of error descriptions.
compiler/post_typecheck.m:
Expand field accessor goals into the equivalent unifications.
They are expanded inline rather than generating new get and set
predicates for field name to avoid having to work out how to mode
the generated predicates.
Remove an unnecessary goal traversal to qualify function
calls and constructors. That code is now called from purity.m.
compiler/prog_data.m:
compiler/prog_io.m:
compiler/mercury_to_goedel.m:
compiler/mercury_to_mercury.m:
Store field names as `sym_name's rather than strings.
Use a `maybe' type rather than an empty string to designate
an unlabelled field.
compiler/hlds_data.m:
Define data structures to hold information about
the field names visible in a module.
compiler/hlds_module.m:
Add a field to type module_info to hold information
about the fields visible in a module.
compiler/hlds_pred.m:
Add predicates to identify field access function names,
and to handle the arguments of field access functions.
compiler/make_hlds.m:
compiler/hlds_goal.m:
compiler/modecheck_call.m:
compiler/higher_order.m:
compiler/purity.m:
compiler/polymorphism.m:
compiler/dnf.m:
compiler/cse_detection.m:
compiler/lambda.m:
Move `create_atomic_unification' from make_hlds.m to hlds_goal.m
because it is used by several other modules.
compiler/hlds_goal.m:
Add a version of goal_info_init which takes the context of
the goal, for use by make_hlds.m.
compiler/type_util.m:
Add a predicate `type_util__get_type_and_cons_defn' to
get the hlds_type_defn and hlds_cons_defn for a user-defined
constructor.
compiler/prog_util.m:
Add predicates to add and remove prefixes or suffixes
from the unqualified part of a sym_name.
compiler/prog_out.m:
Add a predicate to convert a `sym_name/arity' to a string.
compiler/hlds_out.m:
Add `hlds_out__simple_call_id_to_string' to convert a
`pred_or_func - sym_name/arity' to a string for use in
error messages.
compiler/purity.m:
Thread through the pred_info so that the expansion of field accessor
goals can add new variables.
compiler/mercury_to_mercury.m:
library/ops.m:
Reduce precedence of `^/2' for use as a field name separator.
Add operator `^'/1 to designate which side of the `:=' is
the field name in a DCG field access goal.
Add operator `:=/2' for field update expressions.
doc/reference_manual.texi:
Document the new syntax.
doc/transition_guide.texi:
Document the new operators.
tests/hard_coded/Mmakefile:
tests/hard_coded/record_syntax.m:
tests/hard_coded/record_syntax.exp:
tests/invalid/Mmakefile:
tests/invalid/record_syntax_errors.m:
tests/invalid/record_syntax_errors.err_exp:
Test cases.
