Improve error messages and documentation.

dec.cc

@@ -210,7 +210,7 @@ bool block::transAsTemplatedField(
   receiveTypedefDec *dec = dynamic_cast<receiveTypedefDec *>(*p);
   if (!dec) {
     em.error(getPos());
-    em << "Expected 'typedef import(<types>);'";
+    em << "expected 'typedef import(<types>);'";
     em.sync();
     return false;
   }
@@ -1152,11 +1152,9 @@ void receiveTypedefDec::transAsField(coenv& e, record *r) {
   types::ty *intTy = e.e.lookupType(intSymbol());
   assert(intTy);
   if (e.e.lookupVarByType(templatedSymbol(), intTy)) {
-    em << "'typedef import' must be at the start of the file, preceeding any "
-          "other code (including imports)";
+    em << "'typedef import(<types>)' must precede any other code";
   } else {
-    em << "Improper file access: tried to access a templated file without "
-          "template parameters";
+    em << "templated module access requires template parameters";
   }
   em.sync();
 }
@@ -1359,9 +1357,8 @@ void recorddec::transAsField(coenv &e, record *parent)
   record *r = parent ? parent->newRecord(id, e.c.isStatic()) :
     e.c.newRecord(id);
 
-  addTypeWithPermission(
-      e, parent, new trans::tyEntry(r,0,parent,getPos()), id
-  );
+  addTypeWithPermission(e, parent, new trans::tyEntry(r,0,parent,getPos()),
+                        id);
   e.e.addRecordOps(r);
   if (parent)
     parent->e.addRecordOps(r);

doc/asymptote.texi

@@ -11,7 +11,7 @@ This file documents @code{Asymptote}, version @value{VERSION}.
 
 @url{https://asymptote.sourceforge.io}
 
-Copyright @copyright{} 2004-23 Andy Hammerlindl, John Bowman, and Tom Prince.
+Copyright @copyright{} 2004-24 Andy Hammerlindl, John Bowman, and Tom Prince.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -133,6 +133,10 @@ Arrays
 
 * Slices::                      Python-style array slices
 
+Import
+
+* Templated imports::
+
 Base modules
 
 * plain::                       Default @code{Asymptote} base file
@@ -6139,43 +6143,46 @@ void list(string s, bool imports=false);
 Imported global functions and variables are also listed if
 @code{imports} is @code{true}.
 
+@menu
+* Templated imports::
+@end menu
+
 @node Templated imports
 @subsection Templated imports
 @cindex template
 
-@strong{Warning:} This feature is experimental. It has known bugs/misfeatures
-and its behavior may (hopefully will) change in the future.
+@strong{Warning:} This feature is experimental: it has known issues and its behavior may change in the future.
 
 In Asymptote, it is possible to create modules that must have one or more
-types specified when they are imported. The first line of any such module must
-be of the form @code{typedef import(<stuff>)}, where @code{<stuff>} is a list
-of the type parameters. For instance,
+types specified when they are imported. The first executable line of any such
+module must be of the form @code{typedef import(<types>)}, where
+@code{<types>} is a list of required type parameters. For instance,
 @verbatim
 typedef import(T, S, Number);
 @end verbatim
 @noindent
-would be the first line of a file that requires three type parameters. The
-remaining code in the file can then use @code{T}, @code{S}, and @code{Number}
+could be the first line of a module that requires three type parameters. The
+remaining code in the module can then use @code{T}, @code{S}, and @code{Number}
 as types.
 
 To import such a module, one must specify the types to be used. For instance,
-if the file above were named @code{numberstuff.asy}, it could be accessed
+if the module above were named @code{templatedModule}, it could be accessed
 for types @code{string}, @code{int[]}, and @code{real} with the import
 command
 @verbatim
-access numberstuff(T=string, S=int[], Number=real)
-    as numberstuff_string_int_real;
+access templatedModule(T=string, S=int[], Number=real)
+    as templatedModule_string_int_real;
 @end verbatim
 @noindent
 Note that this is actually an @emph{access} command rather than an
 @emph{import} command, so the names of types, functions, etc. would have to be
-stated as e.g. @code{numberstuff_string_int_real.Wrapper_Number} rather than
+stated as e.g. @code{templatedModule_string_int_real.Wrapper_Number} rather than
 just @code{Wrapper_Number} (where @code{Wrapper_Number} is a type defined in
-@code{numberstuff.asy}).
+@code{templatedModule.asy}).
 
 Alternatively, the module could be imported via a command like
 @verbatim
-from numberstuff(T=string, S=int[], Number=real) access
+from templatedModule(T=string, S=int[], Number=real) access
     Wrapper_Number as Wrapper_real,
     operator ==;
 @end verbatim
@@ -6187,10 +6194,9 @@ overloads defined in the module.
 For more information, see the examples in
 @url{https://github.com/vectorgraphics/asymptote/tree/647b6c5732ec94a48f0f0b2446f02c86888fe7e7/tests/template}.
 
-Known bugs/misfeatures: Certain standard features of almost any type (such as
-@code{==}, @code{new}, and the ability to call static methods on the type) are
-not necessarily available for type arguments. (They should be available for
-types that are builtin or defined in the @code{plain} module.)
+Issues: Certain standard features of almost any type (such as
+@code{==}, @code{new}, and the ability to call static methods on the type) may
+only be available for type arguments that are builtin or defined in the @code{plain} module.
 
 @node Static,  , Import, Programming
 @section Static
@@ -10355,7 +10361,7 @@ developed the @code{Asymptote Web Application} hosted at
 @c  LocalWords:  differentiable vectorization vectorized asydir normals quartic
 @c  LocalWords:  wavepacket kerned parametrized specular hyperboloid Bourke's
 @c  LocalWords:  Michail 0pt 1filll 's 3D labelpath3 2D graph3 0pt 3D
-@c  LocalWords:  grid3 contour3 x86_64 psv a4 freeglut 'load '
+@c  LocalWords:  grid3 contour3 x86_64 psv a4 freeglut 'load ' 0pt 's
 @c  LocalWords:  'asy 'lasy 'auto 5bp 1cm sqrtx01 4g extenda extendb
 @c  LocalWords:  bb llx 2S 100pt 3t bezier2 bool3 x0 angle1 angle2 z1
 @c  LocalWords:  z2 before' struct X11 x11colors type1cm 12pt OT1 5mm
@@ -10420,4 +10426,70 @@ developed the @code{Asymptote Web Application} hosted at
 @c  LocalWords:  renderers 2E ESC AsyGL 48kB 2n 100d 5z 5y 5unit 10cm
 @c  LocalWords:  unicode 144x144 Pedram Emami 204e 10x Ai Ai Ai Ai Ai
 @c  LocalWords:  Ai Ai Ai 5a 5E 5cm 2N 2E devicepixelratio 48kB 2n 5z
-@c  LocalWords:  100d 5y 5unit 144x144
+@c  LocalWords:  100d 5y 5unit 144x144 2004-23 2004-24 top-level 3D
+@c  LocalWords:  1filll Command-line Command-Line command-line 2D 15
+@c  LocalWords:  high-order User-defined Python-style Templated V3D
+@c  LocalWords:  coordinate-based high-quality high-level de-facto 56
+@c  LocalWords:  command-driven graphical-user-interface full-fledged
+@c  LocalWords:  script-generated script-based fixed-sized ASYMPTOTE_
+@c  LocalWords:  user-written Debian-based self-extracting disable-gc
+@c  LocalWords:  google-chrome installation-dependent microsoft-edge
+@c  LocalWords:  ASYMPTOTE_PAPERTYPE Right-click ASYMPTOTE_DIR C-c 72
+@c  LocalWords:  ASYMPTOTE_HOME asymptote-x DCMAKE_INSTALL_PREFIX M-x
+@c  LocalWords:  DCMAKE_C_FLAGS texinfo-tex system-wide asy-mode C-h
+@c  LocalWords:  lasy-mode add-to-list 'load-path 'asy-mode asy-kate
+@c  LocalWords:  'lasy-mode 'asy-insinuate-latex 'auto-mode-alist 100
+@c  LocalWords:  two-mode-mode latex-mode space-separated apt-get 5bp
+@c  LocalWords:  ASYMPTOTE_SITEDIR build-dep Vector_Graphics_Language
+@c  LocalWords:  1cm double-quoted 06 left-hand right-hand even-odd
+@c  LocalWords:  two-dimensional three-dimensional 4g fixed-size a--b
+@c  LocalWords:  bottom-left 45 10 picture-transformed plain_Label 2S
+@c  LocalWords:  comma-separated boundary-drawing plain_boxes 100pt
+@c  LocalWords:  z_0 c_0 z_1 c_1 1-t 3t third-order m_5 first-order
+@c  LocalWords:  m_0 m_1 m_2 m_3 m_4 second-order 14 75 1986 x-I 360
+@c  LocalWords:  inflection-free Java-style user-defined built-in a-c
+@c  LocalWords:  highest-precision floating-point element-by-element
+@c  LocalWords:  a--b--c--cycle b-c counterclockwise-oriented 377 01
+@c  LocalWords:  C-style 1970 02 2007 24 60 non-zero z2-c z1-c b-a 68
+@c  LocalWords:  counter-clockwise t-floor 137 P--Q p--q cubic-spline
+@c  LocalWords:  two-element non-default 255 6-character 140 180 375
+@c  LocalWords:  plain_pens z--z 12pt 2018 UTF-8 CJKfamily right-top
+@c  LocalWords:  foreground--background left-bottom 5mm 90 25 25cm 50
+@c  LocalWords:  end-of-file one-dimensional 64-bit 32-bit C-like i-1
+@c  LocalWords:  end-of-line asy_history_ path-joining 3x 5x 3y 2x 2y
+@c  LocalWords:  602e-19 3sin 10cm 204e-19 non-function 17 L-values
+@c  LocalWords:  so-called 10x 34 43 keyword-only 77 42 Keyword-only
+@c  LocalWords:  21 six-element zero-length n-k Ai_deriv Bi_deriv n-1
+@c  LocalWords:  zero_Ai zero_Bi zero_Ai_deriv zero_Bi_deriv i_scaled
+@c  LocalWords:  k_scaled zero_J Newton-Raphson real-valued f_i T2 T1
+@c  LocalWords:  out-of-bounds higher-indexed Dst n-2 realschur schur
+@c  LocalWords:  quasitriangular 19 33 white-space Python-like 12 103
+@c  LocalWords:  comma-separated-value non-cyclic 107 Non-bridging 5a
+@c  LocalWords:  866025403784439 non-private d-b templatedModule k-1
+@c  LocalWords:  templatedModule_string_int_real Wrapper_Number 36 5E
+@c  LocalWords:  Wrapper_real higher-order Three-dimensional log-log
+@c  LocalWords:  two-variable true-element higher-quality post-scaled
+@c  LocalWords:  polar-coordinate auto-generated textbook-style 1000
+@c  LocalWords:  scientific-style graphwithderiv least-squares 5cm 38
+@c  LocalWords:  256 32766 32761 divs quantized fillcontour 67 57 48
+@c  LocalWords:  shape-invariant 2010021-2010022 vice-versa ibl EXR
+@c  LocalWords:  three_surface three_light plain_prethree image-based
+@c  LocalWords:  pre-rendered imageDir imageURL cudareflect teapotIBL
+@c  LocalWords:  patch-dependent vertex-dependent O--X 2N--2E--E 561
+@c  LocalWords:  vertex-specific three-dimensions Ctrl-q iframe 321
+@c  LocalWords:  frameborder 48kB stand-alone 2n 100d v3d pyv3d v2-c
+@c  LocalWords:  importv3d v1-c O--O u--O v--O v--cycle x-0 5z y-0 5y
+@c  LocalWords:  z-0 O--v u--v a-d b-d c-d near_earth c--c nslice 20
+@c  LocalWords:  O--1 5unit three_arrows diamond-shaped right-angled
+@c  LocalWords:  2-y public-domain in-depth field-defining 144x144 'e
+@c  LocalWords:  ASYMPTOTE_CONFIG non-writable 200 semi-colon ctrl-C
+@c  LocalWords:  asy_history auto-completion Button-1 Button-2 LSP
+@c  LocalWords:  rsvg-convert librsvg2-tools dvisvgmMultipleFiles lsp
+@c  LocalWords:  data-binary 'import lsp-mode 'package melpa 'asyls
+@c  LocalWords:  'package-archives package-initialize package-install
+@c  LocalWords:  package-refresh-contents 'lsp-mode make-lsp-client
+@c  LocalWords:  'lsp-language-id-configuration lsp-register-client
+@c  LocalWords:  new-connection lsp-stdio-connection activation-fn
+@c  LocalWords:  lsp-activate-on major-modes server-id user-generated
+@c  LocalWords:  line-based code-based plain_debugger Guib Skitsko
+@c  LocalWords:  Chaumont Cheng

errors

@@ -159,12 +159,12 @@ errortest.asy: 518.29: expected 'as'
 errortest.asy: 519.30: expected 'as'
 errortest.asy: 520.23: expected typename=
 errortest.asy: 521.3: Parametrized imports disallowed to reduce naming conflicts. Try 'access <module>(<type parameters>) as <newname>;'.
-errortest.asy: 524.3: Improper file access: tried to access a templated file without template parameters
+errortest.asy: 524.3: templated module access requires template parameters
 errortest.asy: 525.3: Expected 'typedef import(<types>);'
 errortest.asy: 529.30: too few types passed: got 2, expected 3
 errortest.asy: 529.3: could not load module 'errortestTemplate'
 errortest.asy: 531.47: template argument name does not match module: passed T, expected C
 errortest.asy: 531.3: could not load module 'errortestTemplate'
 errortest.asy: 533.37: template argument name does not match module: passed C, expected B
 errortest.asy: 533.3: could not load module 'errortestTemplate'
-errortestTemplate.asy: 5.1: 'typedef import' must be at the start of the file, preceeding any other code (including imports)
+errortestTemplate.asy: 5.1: 'typedef import(<types>)' must precede any other code

types.h

@@ -413,7 +413,7 @@ struct signature : public gc {
 
   size_t hash() const;
 
-  // Return a unique hash for this signature
+  // Return a unique handle for this signature
   size_t handle();
 };