Scilab Home Page | Wiki | Bug Tracker | Forge | Mailing List Archives | Scilab Online Help | File Exchange
ATOMS : Apifun details
Please login or create an account

Apifun

Check input arguments in macros.
(7494 downloads for this version - 77759 downloads for all versions)
Details
Version
0.3
A more recent valid version exists: 0.4.2
Author
Michael Baudin
Owner Organization
DIGITEO
Maintainers
Michael Baudin
Allan Cornet
License
Creation Date
October 13, 2011
Source created on
Scilab 5.2.x
Binaries available on
Scilab 5.2.x:
Windows 64-bit Windows 32-bit Linux 64-bit Linux 32-bit MacOSX
Install command
--> atomsInstall("apifun")
Description
            Purpose

The goal of this module is to provide a set to function to check input arguments
in macros.

In functions with a variable number of input arguments,
we often have the following source code, which checks that 
the number of input arguments provided by the user is 
consistent with the number of expected arguments :

[lhs,rhs]=argn()
if ( rhs < 2 | rhs > 5 ) then
  errmsg = msprintf(gettext("%s: Unexpected number of input arguments : %d
provided while from %d to %d are expected."), "myfunction", rhs,2,5);
  error(errmsg)
end

Writing this code is error-prone and boring.
Moreover, this fragment of source code is duplicated in 
many functions, leading to small variations depending on the 
developer.
In particular, this makes the localization of the error messages 
difficult, because the message can be slightly different 
depending on the function.
It can also lead to unexpected errors, for example when the 
string containing the error message is wrongly formatted. 
In this case, instead of the expected error, the user gets a message telling 
that the argument of the msprintf function has a wrong format ; this 
is an information which can let the user confused about the source 
of the error.
Moreover, because writing this source code is boring, many existing functions 
are not sufficiently robust against wrong uses.

The goal of the apifun module is to simplify this task. 
For example, the apifun_checkrhs function checks that the number of 
input arguments provided by the user of the function corresponds 
to the number of expected arguments.
The following function takes 2/3 input arguments and 1 output arguments.

function y = myfunction ( varargin )
  [lhs, rhs] = argn()
  apifun_checkrhs ( "myfunction" , rhs , 2:3 )
  apifun_checklhs ( "myfunction" , lhs , 1 )
  x1 = varargin(1)
  x2 = varargin(2)
  if ( rhs >= 3 ) then
    x3 = varargin(3)
  else
    x3 = 2
  end
  y = x1 + x2 + x3
endfunction

When called with 1 or 4 arguments, an error will be 
generated.

// Calling sequences which work
y = myfunction ( 1 , 2 )
y = myfunction ( 1 , 2 , 3 )
// Calling sequences which generate an error
y = myfunction ( 1 )
y = myfunction ( 1 , 2 , 3 , 4 )

The following session shows the kind of error message which is
produced by the apifun module, for example when the number of input argument is
wrong.
The error message is clear about the function which generates the message (e.g.
"myfunction").

-->y = myfunction ( 1 )
 !--error 10000 
myfunction: Unexpected number of input arguments : 1 provided while the number
of expected input arguments should be in the set [2 3].
at line     131 of function apifun_checkrhs called by :  
at line       3 of function myfunction called by :  
y = myfunction ( 1 )

The advantages of using the current module are the following.
 * Designing robust functions is much simpler which improves both the 
   quality and the robustness of functions.
 * The provided source code is factored into one single 
   module. 
 * It is similar to what is provided to the developers of Scilab gateways,
   at the C level.

The following is a list of the function currently implemented in this module:

The following is a list of the function currently implemented in this module:

 * apifun_overview — An overview of the Apifun toolbox.
 * apifun_checklhs — Generates an error if the number of LHS is not in given
set.
 * apifun_checkrhs — Generates an error if the number of RHS is not in given
set.

Support

 * apifun_argindefault — Returns the value of an input argument.
 * apifun_expandfromsize — Expand variables from a size.
 * apifun_expandvar — Expand variables so that they all have the same shape.
 * apifun_keyvaluepairs — Returns options from key-value pairs.
 
Check content

 * apifun_checkcomplex — Generates an error if the variable has a zero
imaginary part.
 * apifun_checkflint — Generates an error if the variable is not a floating
point integer.
 * apifun_checkgreq — Check that the value is greater or equal than a
threshold.
 * apifun_checkloweq — Checks that the value is lower or equal than a
threshold.
 * apifun_checkoption — Generates an error if the value of an input argument
is not expected.
 * apifun_checkrange — Check that the value is in a given range.
 * apifun_checkreal — Generates an error if the variable has an imaginary
part.
 
Check size

 * apifun_checkdims — Generates an error if the variable has not the required
size.
 * apifun_checkscalar — Generates an error if the variable is not a scalar.
 * apifun_checksquare — Generates an error if the variable is not a square
matrix.
 * apifun_checkveccol — Generates an error if the variable is not a column
vector.
 * apifun_checkvecrow — Generates an error if the variable is not a row
vector.
 * apifun_checkvector — Generates an error if the variable is not a vector.
 
Check type

 * apifun_checkcallable — Generates an error if the variable is not a callable
function.
 * apifun_checktype — Generates an error if the given variable is not of
expected type.


            
Files (2)
[117.40 kB]
Source code archive

[206.32 kB]
OS-independent binary for Scilab 5.2.x
Binary version
Automatically generated by the ATOMS compilation chain

News (0)
Comments (3)     Leave a comment 
Comment from Michael Baudin -- October 19, 2011, 08:54:09 AM    
Here is the changelog of the version 0.2.


apifun (0.2)
    * Removed unnecessary commas.
	* Fixed bug #480 in the name of the library 
	  http://forge.scilab.org/index.php/p/apifun/issues/480/
	* Added warning if already loaded.
	* Added help cleaner.
	* Removed auto-generated demos.
	* Fixed bug #129: created apifun_argindefault 
	  http://forge.scilab.org/index.php/p/apifun/issues/129/
	* Created unit tests for checkvector
	* Created unit tests for checkveccol
	* Created unit tests for checkvecrow
	* Fixed bug #153 
	  http://forge.scilab.org/index.php/p/apifun/issues/153/
		* Update apifun_checkvector to make the nbval optionnal
		* Update apifun_checkveccol to make the nbval optionnal
		* Update apifun_checkvecrow to make the nbval optionnal
	* Created unit test for checkrange.
	* Created unit test for checkoption.
	* Created unit test for checkgreq.
	* Created unit test for checkloweq.
	* Created unit test for checksquare.
	* Fixed bug #232: The apifun_checkrange function did not manage NANs.
	  http://forge.scilab.org/index.php/p/apifun/issues/232/
	* Fixed bug #327: The expandvar function has been added to apifun.
	  http://forge.scilab.org/index.php/p/apifun/issues/327/
	* Fixed bug #142: Add a apifun_checkcallable function
	  http://forge.scilab.org/index.php/p/apifun/issues/142/
	* Fixed bug #141: Added a apifun_checkflint function.
	  http://forge.scilab.org/index.php/p/apifun/issues/141/
	* Fixed internal error messages, when type of input arguments 
	  given to apifun_* functions is wrong.
 -- Michael Baudin <michael.baudin@scilab.org>  July 2011

Regards,

Michaël
Comment from Michael Baudin -- October 19, 2011, 08:54:35 AM    
Here is the changelog of version 0.3.


apifun (0.3)
    * Removed warnings in 2 unit tests.
	* Created apifun_keyvaluepairs (fixed bug #539).
	* Fixed bug #540: 
	  assert_typecallable did not manage compiled functions.
	* Clarified help of apifun_expandvar.
	* Added message on apifun_overview at startup.
	* Created apifun_expandfromsize (fixed bug #334).
	* Created apifun_checkreal (bug #233).
	  Created apifun_checkcomplex.
	* Organized help pages into sections.

Regards,

Michaël
Comment from Michael Baudin -- October 19, 2011, 08:56:13 AM    
The version 0.3 is correctly packaged on my Scilab 5.3.2 on Win XP.

-->atomsGetInstalled()
 ans  =
!apifun  0.3-1  allusers  SCI\contrib\apifun\0.3-1  I  !
-->atomsTest("apifun")
   TMPDIR = C:\Users\baudin\AppData\Local\Temp\SCI_TMP_3976_
   001/024 - [SCI\contrib\apifun\0.3-1] argindefault...............passed 
   002/024 - [SCI\contrib\apifun\0.3-1] checkcallable..............passed 
   003/024 - [SCI\contrib\apifun\0.3-1] checkcomplex...............passed 
   004/024 - [SCI\contrib\apifun\0.3-1] checkdims..................passed 
   005/024 - [SCI\contrib\apifun\0.3-1] checkflint.................passed 
   006/024 - [SCI\contrib\apifun\0.3-1] checkgreq..................passed 
   007/024 - [SCI\contrib\apifun\0.3-1] checklhs...................passed 
   008/024 - [SCI\contrib\apifun\0.3-1] checkloweq.................passed 
   009/024 - [SCI\contrib\apifun\0.3-1] checkoption................passed 
   010/024 - [SCI\contrib\apifun\0.3-1] checkrange.................passed 
   011/024 - [SCI\contrib\apifun\0.3-1] checkreal..................passed 
   012/024 - [SCI\contrib\apifun\0.3-1] checkrhs...................passed 
   013/024 - [SCI\contrib\apifun\0.3-1] checkscalar................passed 
   014/024 - [SCI\contrib\apifun\0.3-1] checksquare................passed 
   015/024 - [SCI\contrib\apifun\0.3-1] checktype..................passed 
   016/024 - [SCI\contrib\apifun\0.3-1] checkveccol................passed 
   017/024 - [SCI\contrib\apifun\0.3-1] checkvecrow................passed 
   018/024 - [SCI\contrib\apifun\0.3-1] checkvector................passed 
   019/024 - [SCI\contrib\apifun\0.3-1] complete...................passed 
   020/024 - [SCI\contrib\apifun\0.3-1] complete2..................passed 
   021/024 - [SCI\contrib\apifun\0.3-1] expandfromsize.............passed 
   022/024 - [SCI\contrib\apifun\0.3-1] expandvar..................passed 
   023/024 - [SCI\contrib\apifun\0.3-1] keyvaluepairs..............passed 
   024/024 - [SCI\contrib\apifun\0.3-1] bug_540....................passed 

Leave a comment
You must register and log in before leaving a comment.
Email notifications
Send me email when this toolbox has changes, new files or a new release.
You must register and log in before setting up notifications.