torch / argcheck

A powerful (and blazing fast) argument checker and function overloading system for Lua or LuaJIT

THIS REPOSITORY IS DEPRECEATED.

Please use https://github.com/torch/torch7

For install scripts, please look at: https://github.com/torch/ezinstall

Torch7 Library.

Torch7 provides a Matlab-like environment for state-of-the-art machine learning algorithms. It is easy to use and provides a very efficient implementation, thanks to an easy and fast scripting language (Lua) and a underlying C implementation.

In order to install Torch7 you can follow these simple instructions, but we suggest reading the detailed manual at http://www.torch.ch/manual/install/index

Requirements

• C/C++ compiler
• cmake
• gnuplot
• git

Optional

• Readline
• QT (QT4.8 is now supported)
• CBLAS
• LAPACK

Installation

$ git clone git://github.com/andresy/torch.git
$ cd torch
$ mkdir build
$ cd build

$ cmake .. 
OR
$ cmake .. -DCMAKE_INSTALL_PREFIX=/my/install/path

$make install

Running

$torch
Type help() for more info
Torch 7.0  Copyright (C) 2001-2011 Idiap, NEC Labs, NYU
Lua 5.1  Copyright (C) 1994-2008 Lua.org, PUC-Rio
t7> 

3rd Party Packages

Torch7 comes with a package manager based on Luarocks. With it it's easy to install new packages:

$ torch-rocks install image
$ torch-rocks list
$ torch-rocks search --all

Documentation

The full documentation is installed in /my/install/path/share/torch/html/index.html

Also, http://www.torch.ch/manual/index points to the latest documentation of Torch7.

argcheck's Issues

Tables as first argument introduces ambiguity - proposal: table wrappers classes

I'm struggling to grasp how to approach argument that can either be a string or a table for the __init function. I figured that if I go with ordered arguments the argcheck should just use the env.istype and let me worry about the implementation details. Unfortunately nothing seems to happen when using the nonamed argument, here's an example:

local argcheck = require 'argcheck'

test = torch.class('test')
env = require 'argcheck.env' -- retrieve argcheck environement
env.istype = function(obj, typename)
  if (typename == "table|string") then
    return torch.type(obj) == "table" or
      torch.type(obj) == "string"
  end
  if (typename == "torch.*Tensor") then
    -- regular expressions don't work therefore this
    return torch.type(obj) == "torch.IntTensor" or
      torch.type(obj) == "torch.FloatTensor" or
      torch.type(obj) == "torch.DoubleTensor"
  end
  return torch.type(obj) == typename
end

test.__init = argcheck{
  nonamed=true,
  {name="self", type = "test"},
  {name="tbl", type = "table|string", default=false},
  call = function(self, tbl) -- called in case of success
    print(tbl)
   end
}

print("-- No arguments")
a = test.new()

print("\n-- String")
a = test.new("test")

print("\n-- Table")
a = test.new({1,2,3})

print("\n-- Should throw error")
a = test.new{tbl={1,2,3}}

Outputs:

-- No arguments 
false   

-- String   
test    

-- Table    
{
  1 : 1
  2 : 2
  3 : 3
}

-- Should throw error   
{
  tbl : 
    {
      1 : 1
      2 : 2
      3 : 3
    }
}

The documentation is a little thin on classes, if I'm missing something please consider extending the docs a little so that this awesome package gets easier to implement.

Fails when default and no type

This fails with an assertion error:

local testCheck = require('argcheck'){
   {name="formats", default=10, help="authorized formats"},
}

Am I missing something?

default sets given argument to last slot

exfunc = argcheck{
{name='dim1', type='number'},
{name='dim2', type='number', default=0},
{name='dim3', type='number', default=0},
{name='dim4', type='number', default=0},
nonamed=true,
call =
function(dim1, dim2, dim3, dim4)
print(dim1, dim2, dim3, dim4)
end
}

exfunc(1,2)

Output:
1 0 0 2

Expected:
1 2 0 0

Beggining a doc line with an hyphen fails

Just found that sundown is bugging when a line in the argcheck documentation bloc begins with an hyphen. Check the following code :

Dataframe.upgrade_frame = argcheck{doc =  [[
<a name="Dataframe.upgrade_frame">
### Dataframe.upgrade_frame(@ARGP)

Some text :
- First point
- Second point

@ARGT

_Return value_: void
]],
    {name = "self", type = "Dataframe"},
    call = function(self)
end}

Here is the error I have with Lua 5.1, 5.2 and 5.3 :

ascii.lua:227: attempt to index global 'bit' (a nil value)

Everything works perfectly with Luajit. Replacing the hyphen by an underscore or preceding it by a random letter do the trick.

Here is the full stacktrace :

/opt/torch/install/share/lua/5.1/sundown/ascii.lua:227: attempt to index global 'bit' (a nil value)
stack traceback:
    /opt/torch/install/share/lua/5.1/trepl/init.lua:501: in function </opt/torch/install/share/lua/5.1/trepl/init.lua:494>
    /opt/torch/install/share/lua/5.1/sundown/ascii.lua:227: in function </opt/torch/install/share/lua/5.1/sundown/ascii.lua:223>
    [C]: in function 'sd_markdown_render'
    /opt/torch/install/share/lua/5.1/sundown/ascii.lua:391: in function 'preprocess'
    /opt/torch/install/share/lua/5.1/sundown/ascii.lua:583: in function 'render'
    /opt/torch/install/share/lua/5.1/argcheck/usage.lua:84: in function 'render'
    /opt/torch/install/share/lua/5.1/argcheck/init.lua:102: in function 'argcheck'
    ...dataframe/sub_classes/subset_extensions/samplers.lua:23: in main chunk
    /opt/torch-dataframe/sub_classes/subset.lua:220: in main chunk
    /opt/torch-dataframe/init.lua:39: in main chunk
    [C]: in function 'dofile'
    /opt/torch/install/share/lua/5.1/trepl/init.lua:361: in function 'require'
    [string "_RESULT={require './init.lua'}"]:1: in main chunk
    [C]: in function 'xpcall'
    /opt/torch/install/share/lua/5.1/trepl/init.lua:651: in function 'repl'
    .../torch/install/lib/luarocks/rocks/trepl/scm-1/bin/th:199: in main chunk
    [C]: ?

bugs wrt order of arguments and defaults

I found two bugs. Both can be reproduced with this gist:
https://gist.github.com/c10bc2ad64e5facccf7d

Bug 1:
If you run the gist as is, you will see that "split" is given the value of 90 (which is default), even though it is sent split=15 in the constructor.
I noticed that if you interchange lines 12 <-> 13, this bug goes away

Bug 2:
The gist as is will give the output:
{
split : 90
paths :
{
1 : ../../toyset
}
sampleSize :
{
1 : 3
2 : 100
3 : 100
}
}

However, if you remove line 10, you will get the output:
{
sampleSize :
{
split : 15
paths :
{
1 : ../../toyset
}
sampleSize :
{
1 : 3
2 : 100
3 : 100
}
}
split : 90
}

Notice that inside of sampleSize, there is now a member variable split: 15, apart from the last line having a split: 90

Preparing the argcheck.doc for large projects

As projects grow bigger the API-documentation can be difficult to manage. I would like to see (1) support for multiple files and (2) automated generation of table of contents (TOC).

Allowing direct markdown output to multiple files.

In our Dataframe package we use th doc.lua > Doc/README.md in order to create the docs. As the Dataframe has grown in functionality we have split the package into main functions and extensions. The latter are in a subdirectory and therefore easy to navigate and find. Unfortunately argcheck.doc relies on detecting the output being a tty and we aren’t sure how to separate each extension file in the th doc.lua call. The only solution it seems is to add a bash-script outside Lua that does this. Could you consider amending the usage.render/doc.stop?

Adding a table of contents

I saw in your Cairo-ffi that all function definitions are accommodated with a an anchor, i.e. <a name="ImageSurface.new">. We have copied that structure, unfortunately I can’t find any way to autogenerate a table of contents using that information. Atom has a neat package that allows this, perhaps it could work as a template for the Lua implementation?

Thanks for an awesome package!

Installation fails; rock not found

What am I missing?

$ luarocks install argcheck
Warning: falling back to curl - install luasec to get native HTTPS support

Error: No results matching query were found.

I'm on a Mac. Other rocks install fine.

Bug with tables?

This fails, with a weird nested table:

local opt = require('argcheck') {
   pack = true,
   {name = 'a', type = 'number', default = 10},
   {name = 'b', type = 'table', default = {100,2}},
   {name = 'c', type = 'boolean', default = false},
}

print( opt({a= 10, b= {1,2}}) )

Normal?

torch/rational broken

argcheck cause error :

th> rat = require 'rational'
                                                                      [0.0622s]
th> print(rat(5, 4) * rat(3, 6))
[string "argcheck"]:42: 
Arguments:

({
   a = rational.number  -- 
   b = rational.number  -- 
})


Got: table, table
invalid arguments!
stack traceback:
        [C]: in function 'error'
        [string "argcheck"]:42: in function '__mul'
        [string "print(rat(5, 4) * rat(3, 6))"]:1: in main chunk
        [C]: in function 'xpcall'
        ...lya/devel/lua/torch/install/share/lua/5.1/trepl/init.lua:679: in function 'repl'
        .../lua/torch/install/lib/luarocks/rocks/trepl/scm-1/bin/th:204: in main chunk
        [C]: at 0x562db81c3e00
                                                                      [0.0005s]

Missing argument description when help main field is provided

In the documentation we have

> addfive('')
stdin:2: invalid arguments

This function is going to do a simple addition.
Give a number, it adds 5. Amazing.

arguments:
{
   [x = number]  -- the age of the captain [default=0]
}

in my terminal I get

th> addfive('')
[string "argcheck"]:49: 
This function is going to do a simple addition. Give a number, it adds 5.
Amazing.

Got: string
invalid arguments!
stack traceback:
        [C]: in function 'error'
        [string "argcheck"]:49: in function 'check'
        [string "function addfive(...)..."]:2: in function 'addfive'
        [string "_RESULT={addfive('')}"]:1: in main chunk
        [C]: in function 'xpcall'
        /Users/atcold/torch/install/share/lua/5.1/trepl/init.lua:651: in function 'repl'
        ...cold/torch/install/lib/luarocks/rocks/trepl/scm-1/bin/th:199: in main chunk
        [C]: at 0x010ca74630
                                                                      [0.0009s]

1. So, the last part, with the argument explanation, is missing.
2. Moreover, it looks like the \n is ignored.

Also ? addfive does not show the documentation. How do I get to see it?

In the same way, for the multi argument case, on the documentation it's shown that one may expect an explanation like the following

arguments:
{
  [x   = number]  -- the age of the captain [default=0]
   msg = string   -- a message
}

where one knows that msg does not have any default value, but what I get instead is

Got: number
invalid arguments!
stack traceback:
        [C]: in function 'error'
        [string "argcheck"]:74: in function 'check'
        [string "function addfive(...)..."]:2: in function 'addfive'
        [string "_RESULT={addfive(4)}"]:1: in main chunk
        [C]: in function 'xpcall'
        /Users/atcold/torch/install/share/lua/5.1/trepl/init.lua:651: in function 'repl'
        ...cold/torch/install/lib/luarocks/rocks/trepl/scm-1/bin/th:199: in main chunk
        [C]: at 0x010ca74630

Problem parsing more than 9 input arguments

The following code snippet reproduces the problem:

argcheck = require 'argcheck'
initcheck = argcheck{
  {name="x1",type="string",help="x1",default="a"},
  {name="x2",type="string",help="x2",default="a"},
  {name="x3",type="string",help="x3",default="a"},
  {name="x4",type="string",help="x4",default="a"},
  {name="x5",type="string",help="x5",default="a"},
  {name="x6",type="string",help="x6",default="a"},
  {name="x7",type="string",help="x7",default="a"},
  {name="x8",type="string",help="x8",default="a"},
  {name="x9",type="string",help="x9",default="a"},
  {name="x10",type="string",help="x10",default="a"}
}

Here is the error I get:

/usr/local/share/lua/5.1/argcheck/init.lua:105: could not generate argument checker: [string "argcheck"]:35093: control structure too long near 'end'
stack traceback:
    [C]: in function 'error'
    /usr/local/share/lua/5.1/argcheck/init.lua:105: in function 'argcheck'
    [string "initcheck = argcheck{..."]:1: in main chunk
    [C]: in function 'xpcall'
    /usr/local/share/lua/5.1/trepl/init.lua:567: in function </usr/local/share/lua/5.1/trepl/init.lua:468>