In the Mercury standard library, every exported predicate or function
has (or at least *should* have) a comment that documents it, including
the meanings of its arguments. About 35-40% of these modules put `'s
(left and right quotes) around the names of the variable representing
those arguments. Some tried to do it consistently (though there were spots
with unquoted or half quoted names), while some did it only a few places.
This is inconsistent: we should either do it everywhere, or nowhere.
This diff makes it nowhere, because
- this is what the majority of the standard library modules do;
- this is what virtually all of the modules in the compiler, profiler,
deep_profiler etc directories do;
- typing all those quotes when adding new predicates in modules that
follow this convention is a pain in the ass; and because
- on many modern terminals, `' looks non-symmetrical and weird.
Likewise, the comment explaining a predicate often started with
% `predname(arguments)' returns ...
This diff deletes these quotes as well, since they add nothing useful.
This diff does leave in place quotes around code fragments, both terms
and goals, where this helps delineate the boundaries of that fragment.
Also, throw software_error/1 exceptions rather than directly throwing strings
in a few spots.
Undo special Ralph-style formatting.
library/*.:
As above.
tests/hard_coded/array2d_from_array.exp:
tests/hard_coded/array2d.exp:
tests/hard_coded/test_injection.exp:
Update to conform with the above change.
Discussion of these changes can be found on the Mercury developers
mailing list archives from June 2018.
COPYING.LIB:
Add a special linking exception to the LGPL.
*:
Update references to COPYING.LIB.
Clean up some minor errors that have accumulated in copyright
messages.
One option, --warn-non-contiguous-decls, generates warnings if the
mode declarations of a predicate or function aren't in a contiguous block
immediately following the pred or func declaration. Since this is a rare
kind of "style error", this option is enabled by default.
Two options, --warn-inconsistent-pred-order-clauses and
--warn-inconsistent-pred-order-foreign-procs, warn about inconsistencies
between (a) the order in which predicates (and functions) are declared,
and (b) the order in which they are defined. The two options differ in
their scope. The latter applies to all predicates and functions defined
in the module, while the former applies only to those whose definitions
include Mercury clauses.
Since an exported predicate or function may need nonexported auxiliary
predicates and/or functions, imposing a single order the declarations and
definitions of *all* the predicates and functions in a module is not a good
idea. Instead, both options divide the predicates and functions defined
in a module two groups, the exported and the nonexported, and expect
a consistent order only within each group.
The result is output that looks like this:
time.m:021: Warning: the order of the declarations and definitions of the
time.m:021: exported predicates is inconsistent, as shown by this diff:
time.m:021:
time.m:021: --- declaration order
time.m:021: +++ definition order
time.m:021: @@ -1,7 +1,7 @@
time.m:021: predicate `clock'/3
time.m:021: -predicate `time'/3
time.m:021: predicate `times'/4
time.m:021: function `clk_tck'/0
time.m:021: +predicate `time'/3
time.m:021: function `difftime'/2
time.m:021: predicate `localtime'/4
time.m:021: function `localtime'/1
compiler/options.m:
doc/user_guide.texi:
Add the new options.
compiler/style_checks.m:
A new module that generates the new warnings if warranted.
compiler/check_hlds.m:
compiler/notes/compiler_design.html:
Include and document the new module.
compiler/mercury_compile_front_end.m:
Invoke the new module if any of the three new options is set.
compiler/hlds_pred.m:
Record the item number of every predicate, function, and mode declaration
in the module being compiled. We need this for information for the
new warnings.
compiler/hlds_module.m:
Record the context of the module declaration. We use this context
for warnings about inconsistent order, since there isn't a better one.
compiler/hlds_clauses.m:
Add a mechanism to retrieve the item numbers of a set of clauses
even if they are contiguous.
Document some old data types.
compiler/error_util.m:
Add a new phase for style checks.
compiler/accumulator.m:
compiler/add_class.m:
compiler/add_mutable_aux_preds.m:
compiler/add_pragma_tabling.m:
compiler/add_pred.m:
compiler/add_solver.m:
compiler/add_special_pred.m:
compiler/check_typeclass.m:
compiler/clause_to_proc.m:
compiler/from_ground_term_util.m:
compiler/lambda.m:
compiler/make_hlds.m:
compiler/make_hlds_passes.m:
compiler/mercury_compile.m:
compiler/par_loop_control.m:
compiler/polymorphism.m:
compiler/stm_expand.m:
compiler/table_gen.m:
compiler/unify_proc.m:
Conform the changes to the HLDS above.
compiler/typecheck_errors.m:
Fix style of error messages.
library/array2d.m:
library/assoc_list.m:
library/benchmarking.m:
library/bit_buffer.write.m:
library/bool.m:
library/builtin.m:
library/construct.m:
library/cord.m:
library/counter.m:
library/float.m:
library/injection.m:
library/lazy.m:
library/lexer.m:
library/ops.m:
library/private_builtin.m:
library/profiling_builtin.m:
library/prolog.m:
library/queue.m:
library/rational.m:
library/require.m:
library/stack.m:
library/std_util.m:
library/store.m:
library/thread.semaphore.m:
library/tree234.m:
library/univ.m:
library/version_store.m:
Move declarations or definitions around to avoid some of the warnings
that we can now generate. (There are many more left.)
Make some minor style improvements in the process.
tests/warnings/inconsistent_pred_order.{m,exp}:
tests/warnings/non_contiguous_decls.{m,exp}:
New test cases to test the new options. They are both copies of
tests/benchmarks/queens.m, with intentionally-screwed-up style.
tests/warnings/Mmakefile:
Enable the new test cases.
tests/warnings/Mercury.options:
Specify the options being tested for the new test cases.
tests/benchmarks/queens.m:
Bring the style of this module up to date (before copying it).
tests/invalid/mode_decl_in_wrong_section.err_exp:
Expect the warnings we now generate.
NOTE: this change does not affect the io module -- I've left that for a
separate change.
library/*.m:
As per the recent change to the coding standard, avoid module
qualification in library interfaces where possible.
Reformat declarations and descriptive comments to better utilise
any space freed up by the above.
Branches: main
Add functions for creating singleton maps (of various sorts) to the standard
library. The rationale for this to replace the following sequence of code,
which occurs a lot throughout the Mercury system:
map.init(Map0),
map.det_insert(SomeKey, SomeValue, Map0, Map)
library/bimap.m:
library/injection.m:
library/map.m:
library/rbtree.m:
library/tree234.m:
Add the new function singleton/2 that takes single key-value
pair as arguments and returns a new map.
compiler/disj_gen.m:
Avoid ambiguity in a spot.
NEWS:
Announce the additions.
Branches: main
Change the argument order of many of the predicates in the map, bimap, and
multi_map modules so they are more conducive to the use of state variable
notation, i.e. make the order the same as in the sv* modules.
Prepare for the deprecation of the sv{bimap,map,multi_map} modules by
removing their use throughout the system.
library/bimap.m:
library/map.m:
library/multi_map.m:
As above.
NEWS:
Announce the change.
Separate out the "highlights" from the "detailed listing" for
the post-11.01 NEWS.
Reorganise the announcement of the Unicode support.
benchmarks/*/*.m:
browser/*.m:
compiler/*.m:
deep_profiler/*.m:
extras/*/*.m:
mdbcomp/*.m:
profiler/*.m:
tests/*/*.m:
ssdb/*.m:
samples/*/*.m
slice/*.m:
Conform to the above change.
Remove any dependencies on the sv{bimap,map,multi_map} modules.
Estimated hours taken: 80
Branches: main
The existing representation of goal_paths is suboptimal for several reasons.
- Sometimes we need forward goal paths (e.g. to look up goals), and sometimes
we need reverse goal paths (e.g. when computing goal paths in the first
place). We had two types for them, but
- their names, goal_path and goal_path_consable, were not expressive, and
- we could store only one of them in goal_infos.
- Testing whether goal A is a subgoal of goal B is quite error-prone using
either form of goal paths.
- Using a goal path as a key in a map, which several compiler passes want to
do, requires lots of expensive comparisons.
This diff replaces most uses of goal paths with goal ids. A goal id is an
integer, so it can be used as a key in faster maps, or even in arrays.
Every goal in the body of a procedure gets its id allocated in a depth first
search. Since we process each goal before we dive into is descendants,
the goal representing the whole body of a procedure always gets goal id 0.
The depth first traversal also builds up a map (the containing goal map)
that tells us the parent goal of ever subgoal, with the obvious exception
of the root goal itself. From the containing goal map, one can compute
both reverse and forward goal paths. It can also serve as the basis of an
efficient test of whether the goal identified by goal id A is an ancestor
of another goal identified by goal id B. We don't yet use this test,
but I expect we will in the future.
mdbcomp/program_representation.m:
Add the goal_id type.
Replace the existing goal_path and goal_path_consable types
with two new types, forward_goal_path and reverse_goal_path.
Since these now have wrappers around the list of goal path steps
that identify each kind of goal path, it is now ok to expose their
representations. This makes several compiler passes easier to code.
Update the set of operations on goal paths to work on the new data
structures.
Add a couple of step types to represent lambdas and try goals.
Their omission prior to this would have been a bug for constraint-based
mode analysis, or any other compiler pass prior to the expansion out
of lambda and try goals that wanted to use goal paths to identify
subgoals.
browser/declarative_tree.m:
mdbcomp/rtti_access.m:
mdbcomp/slice_and_dice.m:
mdbcomp/trace_counts.m:
slice/mcov.m:
deep_profiler/*.m:
Conform to the changes in goal path representation.
compiler/hlds_goal:
Replace the goal_path field with a goal_id field in the goal_info,
indicating that from now on, this should be used to identify goals.
Keep a reverse_goal_path field in the goal_info for use by RBMM and
CTGC. Those analyses were too hard to convert to using goal_ids,
especially since RBMM uses goal_paths to identify goals in multi-pass
algorithms that should be one-pass and should not NEED to identify
any goals for later processing.
compiler/goal_path:
Add predicates to fill in goal_ids, and update the predicates
filling in the now deprecated reverse goal path fields.
Add the operations needed by the rest of the compiler
on goal ids and containing goal maps.
Remove the option to set goal paths using "mode equivalent steps".
Constraint based mode analysis now uses goal ids, and can now
do its own equivalent optimization quite simply.
Move the goal_path module from the check_hlds package to the hlds
package.
compiler/*.m:
Conform to the changes in goal path representation.
Most modules now use goal_ids to identify goals, and use a containing
goal map to convert the goal ids to goal paths when needed.
However, the ctgc and rbmm modules still use (reverse) goal paths.
library/digraph.m:
library/group.m:
library/injection.m:
library/pprint.m:
library/pretty_printer.m:
library/term_to_xml.m:
Minor style improvements.
Estimated hours taken: 1
Branches: main
Various minor cleanups and syntax updates for the standard library.
There are no changes to any algorithms.
library/injection.m:
library/set.m:
library/sparse_bitset.m:
Use promise_equivalent_clauses where appropriate.
library/set_ordlist.m:
library/set_unordlist.m:
Convert these module to 4-space indentation:
Convert these module to 4-space indentation
library/*.m:
Convert some if-then-elses into switches.
Remove unnecessary module qualification - this is related
mainly to the breakup of std_util and the fact that on
the 0.13 branche we had two versions of the all-solutions
predicates.
Various other style cleanups.
vim/syntax/mercury.vim:
Highlight promise_equivalent_clauses appropriately.
Estimated hours taken: 0.2
Branches: main, release
library/*.m:
Improve the library reference manual by formatting the beginning of
library modules consistently.
library/integer.m:
Fix some bad indentation.
Estimated hours taken: 18
Branches: main
Move the univ, maybe, pair and unit types from std_util into their own
modules. std_util still contains the general purpose higher-order programming
constructs.
library/std_util.m:
Move univ, maybe, pair and unit (plus any other related types
and procedures) into their own modules.
library/maybe.m:
New module. This contains the maybe and maybe_error types and
the associated procedures.
library/pair.m:
New module. This contains the pair type and associated procedures.
library/unit.m:
New module. This contains the types unit/0 and unit/1.
library/univ.m:
New module. This contains the univ type and associated procedures.
library/library.m:
Add the new modules.
library/private_builtin.m:
Update the declaration of the type_ctor_info struct for univ.
runtime/mercury.h:
Update the declaration for the type_ctor_info struct for univ.
runtime/mercury_mcpp.h:
runtime/mercury_hlc_types.h:
Update the definition of MR_Univ.
runtime/mercury_init.h:
Fix a comment: ML_type_name is now exported from type_desc.m.
compiler/mlds_to_il.m:
Update the the name of the module that defines univs (which are
handled specially by the il code generator.)
library/*.m:
compiler/*.m:
browser/*.m:
mdbcomp/*.m:
profiler/*.m:
deep_profiler/*.m:
Conform to the above changes. Import the new modules where they
are needed; don't import std_util where it isn't needed.
Fix formatting in lots of modules. Delete duplicate module
imports.
tests/*:
Update the test suite to confrom to the above changes.
Estimated hours taken: 4
Branches: main
library/*.m:
Convert to four-space indentation most of the library modules that
weren't already indented that way. Use predmode syntax where possible.
In some modules, shorten long lines by deleting module name prefixes.
Fix departures from our coding standards.
In some modules, simplify code, mostly using field names and/or state
variables.
There are no changes in algorithms, except for neg_list in integer.m.
Estimated hours taken: 3
Branches: main
tests/hard_coded/Mmakefile:
tests/hard_coded/test_injection.exp:
tests/hard_coded/test_injection.m:
Add a test case for the injection library module.
library/injection.m:
injection.merge and injection.overlay do not actually throw exceptions
like the documentation says. The reason is that the underlying map
implementation does not throw exceptions in these circumstances, but
silently accepts the error. We therefore continue to do the same,
but update the documentation to reflect this.
Note that getting map.m to throw exceptions in these circumstances
would probably be the better solution.
Estimated hours taken: 25
Branches: main
Package the type_info_varmap and typeclass_info_varmap types into an ADT
called rtti_varmaps. There are two main purposes for this:
- We wish to extend this set of maps with new maps. Doing this
will be a lot easier and less error prone if all of the maps are
packaged in a single data structure.
- Any new maps that we add may contain redundant information that
just makes searching the maps more efficient. Therefore they must
be kept consistent with the existing maps. Having all the maps
inside an ADT makes it easier to ensure this.
This change also includes two extensions to the maps. First, the
typeclass_info_map is made reversible so that it is possible to efficiently
look up the constraint for a given typeclass_info variable. Second, a new
map from prog_vars to types makes it possible to efficiently look up the
type that a given type_info variable is for. These two changes mean that
it is no longer necessary to consult the argument of type_info/1 or
typeclass_info/1 to find this information. (We still do put that information
there, though; changing the RTTI is left for a separate change.)
compiler/hlds_pred.m:
Move items relating to type_infos and typeclass_infos into a section
of their own.
Add a type `rtti_var_info' to hold information about the contents
of a type_info or typeclass_info variable.
Define the rtti_varmaps abstract data type. This data structure
consists of the type_info_varmap and the typeclass_info_varmap.
Add a new map, type_info_type_map, which is like the inverse
to the type_info_varmap. The difference is that the latter can
point to locations that are inside a typeclass_info variable,
whereas the former only refers to type_info variables. Note that
the combined maps do not form a bijection, or even an injection,
since it is possible for two different type variables to point to
the same location (that is, if they are aliased).
Make the typeclass_info_varmap reversible, by using the new module
injection.m. Unlike the type_info_varmap, this map is always
injective since the same typeclass_info cannot be used for two
different constraints.
The predicates rtti_det_insert_type_info_locn and set_type_info_locn,
which update the type_info_varmap, contain sanity checks to ensure
that only type variables that have already been registered with
the type_info_type_map are used, and that the information in both
maps is consistent.
Use the rtti_varmaps structure in proc_info and clauses_info, in
place of type_info_varmap and typeclass_info_varmap.
compiler/polymorphism.m:
Remove polymorphism__type_info_or_ctor_type/2 and
polymorphism__typeclass_info_class_constraint/2, to ensure that
nobody tries to use the information in the type argument. Replace
them with two similar predicates that test if a type is type_info
or typeclass_info, but that don't return the argument.
Ensure that the new type_info_type_map in the rtti_varmaps is kept
up to date by threading the rtti_varmaps through a few more places.
Some of these places are exported, so this part of the change
affects other modules as well.
Fix a comment that referred to a non-existent predicate.
compiler/type_util.m:
Remove the predicates apply_substitutions_to_var_map/5 and
apply_substitutions_to_typeclass_var_map/5. The functionality
is now provided by the new ADT.
compiler/cse_detection.m:
Rewrite update_existential_data_structures/4 to use the interface
provided by rtti_varmaps. The algorithm for doing this has changed
in the following ways:
- The first pass, which builds a map from changed locations
in the first branch to the tvars concerned, is modified
slightly to traverse over the keys instead of over key-value
pairs.
- The second pass, which previously calculated the induced
type substitution and reconstructed the type_info_varmap
now only does the former.
- Applying the prog_var transformation and the induced type
substitution is done at the end, using the interface to
rtti_varmaps.
compiler/goal_util.m:
Rewrite goal_util__extra_nonlocal_typeinfos/6 to avoid the need
for using map__member/3 on the typeclass_info_varmap (about which
the existing comments say "this is probably not very efficient..."),
and to be more efficient in general.
Previously, we nondeterministically generated non-local type vars
and then tested each constraint to see if it had the type var in it.
Now, we go through each constraint one at a time and check if any of
the type variables in it are non-local. This is more efficient
because we only need to find one non-local type in order to include
the typeclass_info in the non-locals -- the remaining (duplicate)
solutions are pruned away.
compiler/higher_order.m:
Use the new maps instead of looking at the arguments of type_info/1
and typeclass_info/1 types. We plan to remove this information
from type_info and typeclass_info types in future.
Previously, this module used the type argument in order to update
the varmaps when the curried arguments of a higher order call are
added as arguments to the procedure in which the call occurs.
We now look up this information at the point where the curried arg
variables are known, and store this information in higher_order_arg
alongside the types where it used to be stored. This structure is
threaded through to the place where the information is needed.
Fix a cut and paste bug in higher_order_arg_depth/1. It was
previously calling higher_order_args_size/1 in the recursive
call, instead of calling higher_order_args_depth/1.
compiler/inlining.m:
In inlining__do_inline_call, apply the substitutions to the entire
rtti_varmaps structure, not just to the type_info_varmap. (XXX Is
there a good reason why the substitution should _not_ be applied
to the typeclass_info varmap?)
compiler/magic_util.m:
Avoid using polymorphism__type_info_or_ctor_type/2 and
polymorphism__typeclass_info_class_constraint/2, as these are
no longer supported.
compiler/*.m:
Straightforward changes to use the new ADT.
library/injection.m:
New library module. This provides an `injection' type which is
similar to the existing `bimap' type in that it implements
back-to-back maps, but doesn't have such stringent invariants
imposed. In particular, the reverse map is not required to be
injective.
This type is used to model the relationship between prog_constraints
and program variables that hold typeclass_infos for them. Namely,
the typeclass_info for a constraint can be held in two different
variables, but one variable can never hold the typeclass_info for
two distinct constraints.
library/library.m:
Add the new library module.
library/list.m:
Add list__foldl_corresponding and list__foldl2_corresponding, which
traverse two lists in parallel, which one or two accumulators, and
abort if there is a length mismatch.
NEWS:
Mention the changes to the standard library.
