# HG changeset patch
# User Rik <rik@octave.org>
# Date 1373485409 25200
# Node ID 92f42d9f2ae4f3347c35330d007c03427b7e175b
# Parent  bb7b993242679236bc0dd77f4e41d8b26d67aa8e
colormap.m: Add demos, tests, and warning when using deprecated syntax.

* scripts/image/colormap.m: Add warning when using syntax 'colormap ("name")'.
Add %!demos and %!test blocks.  Shuffle documentation string a bit.

diff -r bb7b99324267 -r 92f42d9f2ae4 scripts/image/colormap.m
--- a/scripts/image/colormap.m	Wed Jul 10 12:41:27 2013 -0700
+++ b/scripts/image/colormap.m	Wed Jul 10 12:43:29 2013 -0700
@@ -26,6 +26,8 @@
 ## @deftypefnx {Function File} {@var{cmap} =} colormap ("unregister", "@var{name}")
 ## Query or set the current colormap.
 ##
+## With no input arguments, @code{colormap} returns the current color map.
+##
 ## @code{colormap (@var{map})} sets the current colormap to @var{map}.  The
 ## colormap should be an @var{n} row by 3 column matrix.  The columns
 ## contain red, green, and blue intensities respectively.  All entries
@@ -34,11 +36,10 @@
 ## @code{colormap ("default")} restores the default colormap (the
 ## @code{jet} map with 64 entries).  The default colormap is returned.
 ##
-## @code{colormap ("list")} returns a cell array with all the available
-## colormaps.  The options @code{"register"} and @code{"unregister"}
-## will add or remove the colormap @var{name} to it.
+## @code{colormap ("list")} returns a cell array with all of the available
+## colormaps.  The options "register" and "unregister" will add or remove
+## the colormap @var{name} from this list.
 ##
-## With no arguments, @code{colormap} returns the current color map.
 ## @seealso{jet}
 ## @end deftypefn
 
@@ -53,6 +54,7 @@
   endif
 
   persistent map_list = cell ();
+  persistent do_warning = true;
 
   if (nargin == 1)
 
@@ -63,6 +65,13 @@
         cmap = map_list;
         return;
       else
+        ## FIXME: This syntax is deprecated.  It is no longer mentioned in
+        ##        documentation and should probably be removed in Octave 3.12.
+        if (do_warning)
+          warning (["colormap: deprecated syntax 'colormap (\"%s\")'.  " ...
+                    "Use 'colormap (%s (64))'"], map, map);
+          do_warning = false;
+        endif
         map = feval (map);
       endif
     endif
@@ -80,7 +89,7 @@
     endif
 
   elseif (nargin == 2)
-    if (! ischar (map) || all (! strcmp (map, {"register", "unregister"})))
+    if (! ischar (map) || ! any (strcmp (map, {"register", "unregister"})))
       print_usage ();
     elseif (! ischar (name))
       error ("colormap: to register/unregister a colormap, NAME must be a string");
@@ -99,4 +108,58 @@
 endfunction
 
 
-%% FIXME: Need some demos/tests
+%!demo
+%! ## Create an image for displaying a colormap
+%! image (1:64, linspace (0, 1, 64), repmat ((1:64)', 1, 64));
+%! axis ([1, 64, 0, 1], "ticy", "xy");
+%! ## Show 'jet' colormap
+%! colormap (jet (64));
+%! title "colormap (jet (64))"
+%! disp ("Press a key to continue");
+%! pause ();
+%! ## Show 'colorcube' colormap
+%! colormap (colorcube (64));
+%! title "colormap (colorcube (64))"
+
+%!test
+%! figure ("visible", "off");
+%! cmaptst = [0 1 0; 1 0 1; 1 1 1];
+%! cmap = colormap (cmaptst);
+%! assert (cmap, cmaptst);
+%! cmap = colormap ();
+%! assert (cmap, cmaptst);
+%! cmap = (get (gcf, "colormap"));
+%! assert (cmap, cmaptst);
+%! colormap ("default");
+%! assert (colormap (), jet (64));
+%! colormap ("ocean");
+%! assert (colormap, ocean (64));
+%! close ();  # done with temp. figure
+
+%!test
+%! cmaplst = colormap ("list");
+%! assert (iscell (cmaplst));
+%! colormap ("register", "__mycmap__"); 
+%! cmaplst2 = colormap ("list");
+%! assert (numel (cmaplst2), numel (cmaplst) + 1);
+%! assert (any (strcmp (cmaplst2, "__mycmap__")));
+%! colormap ("unregister", "__mycmap__"); 
+%! cmaplst2 = colormap ("list");
+%! assert (numel (cmaplst2), numel (cmaplst));
+%! assert (! any (strcmp (cmaplst2, "__mycmap__")));
+%! ## Unregister again and verify that nothing has happened
+%! colormap ("unregister", "__mycmap__"); 
+%! cmaplst3 = colormap ("list");
+%! assert (isequal (cmaplst2, cmaplst3));
+
+## Test input validation
+%!error colormap (1,2,3)
+%!error <MAP must be a real-valued N x 3> colormap ({1,2,3})
+%!error <MAP must be a real-valued N x 3> colormap ([1 i 1])
+%!error <MAP must be a real-valued N x 3> colormap (ones(3,3,3))
+%!error <MAP must be a real-valued N x 3> colormap ([1 0 1 0])
+%!error <all MAP values must be in the range> colormap ([-1 0 0])
+%!error <all MAP values must be in the range> colormap ([2 0 0])
+%!error colormap ("invalid", "name")
+%!error <NAME must be a string> colormap ("register", 1)
+