Renamed can_ok() to has_function() and deprecated the old name.

Changes

@@ -21,6 +21,10 @@ Revision history for pgTAP
 * Added `hasnt_trigger()` and `hasnt_index()`.
 * Documented `hasnt_enum()`, which has actually been around for as long as
   `has_enum()`.
+* Changed `can_ok()` to `has_function()`, so that it's named like all of the
+  other functions that check for the presence of database objects. The old
+  `can_ok()` function is still available as an alias, but it emits a warning
+  and will be removed in a future version of pgTAP.
 
 0.20 2009-03-29T19:05:40
 -------------------------

README.pgtap

@@ -1379,7 +1379,7 @@ If `:schema` is omitted, then `can()` will look for functions defined in
 schemas defined in the search path. No matter how many functions are listed in
 `:functions[]`, a single call to `can()` counts as one test. If you want
 otherwise, call `can()` once for each function -- or better yet, use
-`can_ok()`.
+`has_function()`.
 
 If any of the functions are not defined, the test will fail and the
 diagnostics will output a list of the functions that are missing, like so:
@@ -1388,48 +1388,9 @@ diagnostics will output a list of the functions that are missing, like so:
     #     pg_catalog.foo() missing
     #     pg_catalog.bar() missing
 
-### `can_ok( schema, function, args[], description )` ###
-### `can_ok( schema, function, args[] )` ###
-### `can_ok( schema, function, description )` ###
-### `can_ok( schema, function )` ###
-### `can_ok( function, args[], description )` ###
-### `can_ok( function, args[] )` ###
-### `can_ok( function, description )` ###
-### `can_ok( function )` ###
-
-    SELECT can_ok(
-        'pg_catalog',
-        'decode',
-        ARRAY[ 'text', 'text' ],
-        'Function decode(text, text) should exist'
-    );
-
-    SELECT can_ok( 'do_something' );
-    SELECT can_ok( 'do_something', ARRAY['integer'] );
-    SELECT can_ok( 'do_something', ARRAY['numeric'] );
-
-Checks to be sure that the given function exists in the named schema and with
-the specified argument data types. If `:schema` is omitted, `can_ok()` will
-search for the function in the schemas defined in the search path. If
-`:args[]` is omitted, `can_ok()` will see if the function exists without
-regard to its arguments.
-
-The `:args[]` argument should be formatted as it would be displayed in the
-view of a function using the `\df` command in `psql`. For example, even if you
-have a numeric column with a precision of 8, you should specify
-`ARRAY['numeric']`". If you created a `varchar(64)` column, you should pass
-the `:args[]` argument as `ARRAY['character varying']`.
-
-If you wish to use the two-argument form of `can_ok()`, specifying only the
-schema and the function name, you must cast the `:function` argument to
-`:name` in order to disambiguate it from from the
-`can_ok(`:function`, `:description)` form. If you neglect to do so, your
-results will be unexpected.
-
-Also, if you use the string form to specify the `:args[]` array, be sure to
-cast it to `name[]` to disambiguate it from a text string:
-
-    SELECT can_ok( 'lower', '{text}'::name[] );
+**Deprecation notice:** The old name for this test function `can_ok()`, is
+still available, but emits a warning when called. It will be removed in a
+future version of pgTAP.
 
 ### `has_cast( source_type, target_type, schema, function, description )` ###
 ### `has_cast( source_type, target_type, schema, function )` ###

expected/cantap.out

@@ -1,5 +1,5 @@
 \unset ECHO
-1..63
+1..105
 ok 1 - simple function should pass
 ok 2 - simple function should have the proper description
 ok 3 - simple function should have the proper diagnostics
@@ -42,24 +42,66 @@ ok 39 - custom numeric function should have the proper diagnostics
 ok 40 - failure output should fail
 ok 41 - failure output should have the proper description
 ok 42 - failure output should have the proper diagnostics
-ok 43 - can(schema) with desc should pass
-ok 44 - can(schema) with desc should have the proper description
-ok 45 - can(schema) with desc should have the proper diagnostics
-ok 46 - can(schema) should pass
-ok 47 - can(schema) should have the proper description
-ok 48 - can(schema) should have the proper diagnostics
-ok 49 - fail can(schema) with desc should fail
-ok 50 - fail can(schema) with desc should have the proper description
-ok 51 - fail can(schema) with desc should have the proper diagnostics
-ok 52 - fail can(someschema) with desc should fail
-ok 53 - fail can(someschema) with desc should have the proper description
-ok 54 - fail can(someschema) with desc should have the proper diagnostics
-ok 55 - can() with desc should pass
-ok 56 - can() with desc should have the proper description
-ok 57 - can() with desc should have the proper diagnostics
-ok 58 - can(schema) should pass
-ok 59 - can(schema) should have the proper description
-ok 60 - can(schema) should have the proper diagnostics
-ok 61 - fail can() with desc should fail
-ok 62 - fail can() with desc should have the proper description
-ok 63 - fail can() with desc should have the proper diagnostics
+ok 43 - simple function should pass
+ok 44 - simple function should have the proper description
+ok 45 - simple function should have the proper diagnostics
+ok 46 - simple schema.function should pass
+ok 47 - simple schema.function should have the proper description
+ok 48 - simple schema.function should have the proper diagnostics
+ok 49 - simple function desc should pass
+ok 50 - simple function desc should have the proper description
+ok 51 - simple function desc should have the proper diagnostics
+ok 52 - simple with 0 args should pass
+ok 53 - simple with 0 args should have the proper description
+ok 54 - simple with 0 args should have the proper diagnostics
+ok 55 - simple with 0 args desc should pass
+ok 56 - simple with 0 args desc should have the proper description
+ok 57 - simple with 0 args desc should have the proper diagnostics
+ok 58 - simple schema.func with 0 args should pass
+ok 59 - simple schema.func with 0 args should have the proper description
+ok 60 - simple schema.func with 0 args should have the proper diagnostics
+ok 61 - simple schema.func with desc should pass
+ok 62 - simple schema.func with desc should have the proper description
+ok 63 - simple schema.func with desc should have the proper diagnostics
+ok 64 - simple scchma.func with 0 args, desc should pass
+ok 65 - simple scchma.func with 0 args, desc should have the proper description
+ok 66 - simple scchma.func with 0 args, desc should have the proper diagnostics
+ok 67 - simple function with 1 arg should pass
+ok 68 - simple function with 1 arg should have the proper description
+ok 69 - simple function with 1 arg should have the proper diagnostics
+ok 70 - simple function with 2 args should pass
+ok 71 - simple function with 2 args should have the proper description
+ok 72 - simple function with 2 args should have the proper diagnostics
+ok 73 - simple array function should pass
+ok 74 - simple array function should have the proper description
+ok 75 - simple array function should have the proper diagnostics
+ok 76 - custom array function should pass
+ok 77 - custom array function should have the proper description
+ok 78 - custom array function should have the proper diagnostics
+ok 79 - custom numeric function should pass
+ok 80 - custom numeric function should have the proper description
+ok 81 - custom numeric function should have the proper diagnostics
+ok 82 - failure output should fail
+ok 83 - failure output should have the proper description
+ok 84 - failure output should have the proper diagnostics
+ok 85 - can(schema) with desc should pass
+ok 86 - can(schema) with desc should have the proper description
+ok 87 - can(schema) with desc should have the proper diagnostics
+ok 88 - can(schema) should pass
+ok 89 - can(schema) should have the proper description
+ok 90 - can(schema) should have the proper diagnostics
+ok 91 - fail can(schema) with desc should fail
+ok 92 - fail can(schema) with desc should have the proper description
+ok 93 - fail can(schema) with desc should have the proper diagnostics
+ok 94 - fail can(someschema) with desc should fail
+ok 95 - fail can(someschema) with desc should have the proper description
+ok 96 - fail can(someschema) with desc should have the proper diagnostics
+ok 97 - can() with desc should pass
+ok 98 - can() with desc should have the proper description
+ok 99 - can() with desc should have the proper diagnostics
+ok 100 - can(schema) should pass
+ok 101 - can(schema) should have the proper description
+ok 102 - can(schema) should have the proper diagnostics
+ok 103 - fail can() with desc should fail
+ok 104 - fail can() with desc should have the proper description
+ok 105 - fail can() with desc should have the proper diagnostics

pgtap.sql.in

@@ -2011,8 +2011,8 @@ RETURNS TEXT AS $$
     SELECT fk_ok( $1, ARRAY[$2], $3, ARRAY[$4] );
 $$ LANGUAGE sql;
 
--- can_ok( schema, func_name, args[], description )
-CREATE OR REPLACE FUNCTION can_ok ( NAME, NAME, NAME[], TEXT )
+-- has_function( schema, func_name, args[], description )
+CREATE OR REPLACE FUNCTION has_function ( NAME, NAME, NAME[], TEXT )
 RETURNS TEXT AS $$
     SELECT ok(
         EXISTS(
@@ -2026,15 +2026,15 @@ RETURNS TEXT AS $$
     );
 $$ LANGUAGE SQL;
 
--- can_ok( schema, func_name, args[] )
-CREATE OR REPLACE FUNCTION can_ok( NAME, NAME, NAME[] )
+-- has_function( schema, func_name, args[] )
+CREATE OR REPLACE FUNCTION has_function( NAME, NAME, NAME[] )
 RETURNS TEXT AS $$
-    SELECT can_ok( $1, $2, $3, 'Function ' || quote_ident($1) || '.' || quote_ident($2) || '(' ||
+    SELECT has_function( $1, $2, $3, 'Function ' || quote_ident($1) || '.' || quote_ident($2) || '(' ||
     array_to_string($3, ', ') || ') should exist' );
 $$ LANGUAGE sql;
 
--- can_ok( schema, func_name, description )
-CREATE OR REPLACE FUNCTION can_ok ( NAME, NAME, TEXT )
+-- has_function( schema, func_name, description )
+CREATE OR REPLACE FUNCTION has_function ( NAME, NAME, TEXT )
 RETURNS TEXT AS $$
     SELECT ok(
         EXISTS(
@@ -2047,14 +2047,14 @@ RETURNS TEXT AS $$
     );
 $$ LANGUAGE SQL;
 
--- can_ok( schema, func_name )
-CREATE OR REPLACE FUNCTION can_ok( NAME, NAME )
+-- has_function( schema, func_name )
+CREATE OR REPLACE FUNCTION has_function( NAME, NAME )
 RETURNS TEXT AS $$
-    SELECT can_ok( $1, $2, 'Function ' || quote_ident($1) || '.' || quote_ident($2) || '() should exist' );
+    SELECT has_function( $1, $2, 'Function ' || quote_ident($1) || '.' || quote_ident($2) || '() should exist' );
 $$ LANGUAGE sql;
 
--- can_ok( func_name, args[], description )
-CREATE OR REPLACE FUNCTION can_ok ( NAME, NAME[], TEXT )
+-- has_function( func_name, args[], description )
+CREATE OR REPLACE FUNCTION has_function ( NAME, NAME[], TEXT )
 RETURNS TEXT AS $$
     SELECT ok(
         EXISTS(
@@ -2067,15 +2067,15 @@ RETURNS TEXT AS $$
     );
 $$ LANGUAGE SQL;
 
--- can_ok( func_name, args[] )
-CREATE OR REPLACE FUNCTION can_ok( NAME, NAME[] )
+-- has_function( func_name, args[] )
+CREATE OR REPLACE FUNCTION has_function( NAME, NAME[] )
 RETURNS TEXT AS $$
-    SELECT can_ok( $1, $2, 'Function ' || quote_ident($1) || '(' ||
+    SELECT has_function( $1, $2, 'Function ' || quote_ident($1) || '(' ||
     array_to_string($2, ', ') || ') should exist' );
 $$ LANGUAGE sql;
 
--- can_ok( func_name, description )
-CREATE OR REPLACE FUNCTION can_ok( NAME, TEXT )
+-- has_function( func_name, description )
+CREATE OR REPLACE FUNCTION has_function( NAME, TEXT )
 RETURNS TEXT AS $$
     SELECT ok(
         EXISTS(
@@ -2087,12 +2087,76 @@ RETURNS TEXT AS $$
     );
 $$ LANGUAGE sql;
 
--- can_ok( func_name )
-CREATE OR REPLACE FUNCTION can_ok( NAME )
+-- has_function( func_name )
+CREATE OR REPLACE FUNCTION has_function( NAME )
 RETURNS TEXT AS $$
-    SELECT can_ok( $1, 'Function ' || quote_ident($1) || '() should exist' );
+    SELECT has_function( $1, 'Function ' || quote_ident($1) || '() should exist' );
 $$ LANGUAGE sql;
 
+CREATE OR REPLACE FUNCTION can_ok ( NAME, NAME, NAME[], TEXT )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2, $3, $4);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok( NAME, NAME, NAME[] )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2, $3);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok ( NAME, NAME, TEXT )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2, $3);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok( NAME, NAME )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok ( NAME, NAME[], TEXT )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2, $3);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok( NAME, NAME[] )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok( NAME, TEXT )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1, $2);
+END;
+$$ LANGUAGE PLPGSQL;
+
+CREATE OR REPLACE FUNCTION can_ok( NAME )
+RETURNS TEXT AS $$
+BEGIN
+    RAISE WARNING '%', 'can_ok() is deprecated; use has_function() instead';
+    RETURN has_function($1);
+END;
+$$ LANGUAGE PLPGSQL;
+
 CREATE OR REPLACE FUNCTION _pg_sv_type_array( OID[] )
 RETURNS NAME[] AS $$
     SELECT ARRAY(