def make_signature_for_desc(self,
f,
is_constructor=False,
is_free_function=False):
"""Given a node of a function/methods, it makes the signature for desc file"""
# first format the arguments
def cls(t):
tname = util.decay(t)
tname = tname.replace(' ', '')
for ns in self.namespace_to_factor:
tname = re.sub(ns + '::', '', tname)
return tname
if util.use_parameter_class(f):
r = '**%s' % cls(CL.get_params(f).next().type.spelling)
else:
plist = [(cls(p.type.spelling), p.spelling,
CL.get_param_default_value(p)) for p in CL.get_params(f)]
r = ', '.join("%s %s" % (t, n) +
(" = %s" % d.replace('"', '\\"') if d else "")
for t, n, d in plist)
if is_constructor:
return "(%s)" % r
else:
f_name = f.spelling if not is_free_function else CL.fully_qualified(
f)
return ("%s %s (%s)" %
(cls(f.result_type.spelling), f_name, r)).strip()
def make_synopsis(m, pdoc, decal):
#assert not m.tparams, "template functions "
#try :
syn = pdoc.elements['synopsis']
if syn: return [syn]
s = " {name} ({args}) {qualif}"
if hasattr(m, 'result_type'):
s = process_rtype(m.result_type.spelling) + s
#if not CL.is_constructor(m) :
# s = process_rtype(getattr(m, 'result_type', None)) + s
s = make_synopsis_template_decl(m) + "\n" + decal * ' ' + s
# filter to remove enable_if dummies from the API
def no_dummy(t, n):
return not ('enable_if' in t and 'dummy' in n)
params = [(p.type.spelling, p.spelling, CL.get_param_default_value(p))
for p in CL.get_params(m)]
args = ', '.join([
"%s %s" % (process_param_type(t), n) + (" = %s" % d if d else "")
for t, n, d in params if no_dummy(t, n)
])
s = s.format(args=args,
name=m.spelling.strip(),
qualif=CL.get_method_qualification(m))
if getattr(m, 'noexcept', False): s += ' noexcept'
r = [x.strip() for x in s.split('\n')]
L = [x for x in r if x]
L_lb = [add_linebreaks(x) for x in L]
return L_lb
def get_all_params_ret_type(self, param_cls_list):
"""Yields every parameters and return type of every methods and functions"""
for f in self.all_functions_gen():
yield getattr(f, 'result_type', None)
for p in CL.get_params(f):
yield p.type
for x in itertools.chain(param_cls_list, self.all_classes_gen()):
for m in CL.get_members(x, False): # False : no inherited
yield m.type
for m in itertools.chain(CL.get_constructors(x),
CL.get_methods(x)):
yield getattr(m, 'result_type', None)
for p in CL.get_params(m):
yield p.type
def get_decl_param_class(f):
""" Given a node f of a function, returns the node of declaration of the param class or None"""
if 'use_parameter_class' not in CL.get_annotations(f) :
return None
p = list(CL.get_params(f))
assert len(p) == 1, "A function/method with PARAM technique must have exacly one parameter"
return CL.jump_to_declaration(p[0].type)
def get_all_params_ret_type(self, param_cls_list):
"""Yields every parameters and return type of every methods and functions"""
for f in self.all_functions_gen():
yield getattr(f, 'result_type', None)
for p in CL.get_params(f) :
yield p.type
for x in itertools.chain(param_cls_list, self.all_classes_gen()):
for m in CL.get_members(x, False): # False : no inherited
yield m.type
for m in itertools.chain(CL.get_constructors(x), CL.get_methods(x)):
# A minimal filter, do not reuse self.keep_fnt here, because the namespace is N1::N2:...::ClassName
if CL.is_template(m) or ("ignore_in_python" in CL.get_annotations(m)): continue
yield getattr(m, 'result_type', None)
for p in CL.get_params(m) :
yield p.type
def has_hdf5_scheme(self, c):
"""True iif the class c has a static method std::string hdf5_scheme()"""
keep = lambda m: CL.is_public(m)
for m in CL.get_methods(c, True, keep):
if m.spelling == "hdf5_scheme" and m.is_static_method() and (
'string' in m.result_type.spelling) and len(
list(CL.get_params(m))) == 0:
return True
return False
def get_decl_param_class(f):
""" Given a node f of a function, returns the node of declaration of the param class or None"""
if 'use_parameter_class' not in CL.get_annotations(f):
return None
p = list(CL.get_params(f))
assert len(
p
) == 1, "A function/method with PARAM technique must have exacly one parameter"
return CL.jump_to_declaration(p[0].type)
def separate_method_and_properties(self, c):
"""
Treatment of properties
Parameters
-----------
method_list : a generator of the methods to treat
Returns
--------
Tuple (proplist, methodlist) where
proplist : a list of property_
methodlist : the others methods
"""
method_list = list(self.get_public_methods(c)) # MUST be a list, or the generator will be exhausted later in mlist = ...
if not self.use_properties : return method_list, ()
class property_:
def __init__ (self, **kw) :
self.__dict__.update(kw)
def maybe_prop(m):
return len(list(CL.get_params(m))) == 0 and not m.is_static_method()
plist1 = [m for m in method_list if maybe_prop(m)]
mlist = [m for m in method_list if not maybe_prop(m)]
plist = []
OUT, SEP = '', ' '
for m in plist1:
n, set_m = m.spelling, None
if n.startswith('set_') : continue # do nothing, will be treated with the get_
if n.startswith('get_') :
# treat the corresponding setter
n = n[4:]
set_m = next( (m for m in plist1 if m.spelling == 'set_' + n), None)
if set_m :
p = list(CL.get_params(set_m))
if set_m.result_type.spelling == "void" and len(p) ==1 :
if not util.decay(p[0].spelling) == m.result_type.spelling :
OUT += SEP + "Warning :\n"
OUT += SEP + " in get_%s/set_%s\n" %(X,X)
OUT += SEP + " The type taken from set_%s is not the return type of get_%s\n"%(X,X)
OUT += SEP + " Expected %s\n"%m.result_type.spelling
OUT += SEP + " Got %s\n"% decay(p[0].spelling)
OUT += SEP + " I am not adding the setter to the property\n"
set_m = None
OUT += SEP + "%s %s\n" %(m.spelling, set_m.spelling if set_m else '')
plist.append(property_(name= n, doc = doc.make_doc(m), getter = m, setter = set_m))
if OUT:
print " Class %s : transforming to property : \n%s"%(c.spelling, OUT)
return mlist, plist
def get_all_params_ret_type(self, param_cls_list):
"""Yields every parameters and return type of every methods and functions"""
for f in self.all_functions_gen():
yield getattr(f, 'result_type', None)
for p in CL.get_params(f):
yield p.type
for x in itertools.chain(param_cls_list, self.all_classes_gen()):
for m in CL.get_members(x, False): # False : no inherited
yield m.type
for m in itertools.chain(CL.get_constructors(x),
CL.get_methods(x)):
# A minimal filter, do not reuse self.keep_fnt here, because the namespace is N1::N2:...::ClassName
if CL.is_template(m) or ("ignore_in_python"
in CL.get_annotations(m)):
continue
yield getattr(m, 'result_type', None)
for p in CL.get_params(m):
yield p.type
def make_synopsis_one_function(f, number):
"""
Given the AST node for a function f, returns the synopsis
number : the number of the function (in a list of overloads)
"""
ns = CL.get_namespace(
f) + '::' # to remove the myclass:: from the types of arg and rtype
is_not_constructor = not getattr(f, 'is_constructor', False)
template = make_synopsis_template_decl(f)
result_type = (process_type_name(f.result_type) +
' ') if is_not_constructor else ''
name = " %s " % f.spelling.strip(
) if is_not_constructor else f.spelling.split(
'<', 1)[0] # eliminate the <> in the constructor name
qualif = CL.get_method_qualification(f) + (' noexcept' if getattr(
f, 'noexcept', False) else '')
params1 = [(p.type, p.spelling, CL.get_param_default_value(p))
for p in CL.get_params(f)]
params = [
"%s %s" % (process_type_name(t), ":param:`%s`" % n if n else '') +
(" = %s" % d if d else "") for t, n, d in params1
]
# same with no rst decoration
params_no_role = [
"%s %s" % (t.spelling, n) + (" = %s" % d if d else "")
for t, n, d in params1
]
# first attempt : one line, else multiple line
nspace = 8 if number >= 10 else 7
sep = nspace * ' ' + '| '
sep2 = ',\n' + sep + ' ' * len(name)
res1 = sep + result_type + ":red:`%s` " % name.strip() + '('
# First compute the result without any rst decoroation to compute the lengths
res_no_role = res1 + ', '.join(x for x in params_no_role)
if len(res_no_role
) > global_vars.synopsis_maxlen_function: # not good, need to split
res = res1 + sep2.join(
x for x in params
) # DEBUG + "%s %s"%(len(res_no_role) , global_vars.synopsis_maxlen_function)
else:
res = res1 + ', '.join(x for x in params)
# brief = f.processed_doc.brief_doc
#r = ('%s:cppbrief:`%s`\n'%(sep,brief) if brief else '') + ('%s:green:`%s`\n'%(sep,template) if template else '') + res + ') ' + qualif
r = ('%s:green:`%s`\n' %
(sep, template) if template else '') + res + ') ' + qualif
return r.strip()
def make_synopsis_one_function(f, number):
"""
Given the AST node for a function f, returns the synopsis
"""
# If @synopsis was given manually
#syn = f.processed_doc.elements.pop('synopsis', '')
#if syn : return [syn]
ns = CL.get_namespace(
f) + '::' # to remove the myclass:: from the types of arg and rtype
is_not_constructor = not getattr(f, 'is_constructor', False)
template = make_synopsis_template_decl(f)
result_type = (process_rtype(f.result_type.spelling, remove=ns) +
' ') if is_not_constructor else ''
name = " %s " % f.spelling.strip(
) if is_not_constructor else f.spelling.split(
'<', 1)[0] # eliminate the <> in the constructor name
qualif = CL.get_method_qualification(f) + (' noexcept' if getattr(
f, 'noexcept', False) else '')
#for p in CL.get_params(f):
# print p.type.get_canonical().spelling
params1 = [(p.type.spelling, p.spelling, CL.get_param_default_value(p))
for p in CL.get_params(f)]
params = [
"%s %s" %
(process_param_type(t, remove=ns), ":param:`%s`" % n if n else '') +
(" = %s" % d if d else "") for t, n, d in params1
]
# first attempt : one line
nspace = 8 if number >= 10 else 7
sep = nspace * ' ' + '| '
sep2 = ',\n' + sep + ' '
res1 = sep + result_type + ":red:`%s` " % name.strip() + '('
res = res1 + ', '.join(x for x in params)
if len(res) > maxlen: # not good, need to split
res = res1 + sep2.join(x for x in params)
brief = f.processed_doc.brief_doc
r = ('%s:cppbrief:`%s`\n' % (sep, brief) if brief else
'') + ('%s:green:`%s`\n' %
(sep, template) if template else '') + res + ') ' + qualif
return r.strip()
def make_signature_for_desc(self, f, is_constructor = False, is_free_function = False):
"""Given a node of a function/methods, it makes the signature for desc file"""
# first format the arguments
def cls(t) :
tname = util.decay(t)
tname = tname.replace(' ','')
for ns in self.namespace_to_factor :
tname = re.sub(ns + '::','',tname)
return tname
if util.use_parameter_class(f) :
r = '**%s'%cls(CL.get_params(f).next().type.spelling)
else:
plist = [ (cls(p.type.spelling), p.spelling, CL.get_param_default_value(p)) for p in CL.get_params(f)]
r = ', '.join("%s %s"%(t, n) + (" = %s"%d.replace('"','\\"') if d else "") for t, n, d in plist )
if is_constructor:
return "(%s)"%r
else :
f_name = f.spelling if not is_free_function else CL.fully_qualified(f)
return ("%s %s (%s)"%(cls(f.result_type.spelling), f_name, r)).strip()
def make_synopsis_one_function(f, number):
"""
Given the AST node for a function f, returns the synopsis
number : the number of the function (in a list of overloads)
"""
ns = CL.get_namespace(f) + '::' # to remove the myclass:: from the types of arg and rtype
is_not_constructor = not getattr(f, 'is_constructor', False)
template = make_synopsis_template_decl(f)
result_type = (process_type_name(f.result_type) + ' ') if is_not_constructor else ''
name = " %s "%f.spelling.strip() if is_not_constructor else f.spelling.split('<',1)[0] # eliminate the <> in the constructor name
qualif = CL.get_method_qualification(f) + (' noexcept' if getattr(f,'noexcept',False) else '')
params1 = [(p.type, p.spelling, CL.get_param_default_value(p)) for p in CL.get_params(f)]
params = ["%s %s"%(process_type_name(t), ":param:`%s`"%n if n else '') + (" = %s"%d if d else "") for t,n,d in params1]
# same with no rst decoration
params_no_role = ["%s %s"%(t.spelling, n) + (" = %s"%d if d else "") for t,n,d in params1]
# first attempt : one line, else multiple line
nspace = 8 if number>=10 else 7
sep = nspace*' ' + '| '
sep2 = ',\n' + sep + ' '
res1 = sep + result_type + ":red:`%s` "%name.strip() + '('
# First compute the result without any rst decoroation to compute the lengths
res_no_role = res1 + ', '.join(x for x in params_no_role)
if len(res_no_role) > global_vars.synopsis_maxlen_function: # not good, need to split
res = res1 + sep2.join(x for x in params) # DEBUG + "%s %s"%(len(res_no_role) , global_vars.synopsis_maxlen_function)
else:
res = res1 + ', '.join(x for x in params)
brief = f.processed_doc.brief_doc
r = ('%s:cppbrief:`%s`\n'%(sep,brief) if brief else '') + ('%s:green:`%s`\n'%(sep,template) if template else '') + res + ') ' + qualif
return r.strip()
def maybe_prop(m):
return len(list(
CL.get_params(m))) == 0 and not m.is_static_method()
def separate_method_and_properties(self, c):
"""
Treatment of properties
Parameters
-----------
method_list : a generator of the methods to treat
Returns
--------
Tuple (proplist, methodlist) where
proplist : a list of property_
methodlist : the others methods
"""
method_list = list(
self.get_public_methods(c)
) # MUST be a list, or the generator will be exhausted later in mlist = ...
if not self.use_properties: return method_list, ()
class property_:
def __init__(self, **kw):
self.__dict__.update(kw)
def maybe_prop(m):
return len(list(
CL.get_params(m))) == 0 and not m.is_static_method()
plist1 = [m for m in method_list if maybe_prop(m)]
mlist = [m for m in method_list if not maybe_prop(m)]
plist = []
OUT, SEP = '', ' '
for m in plist1:
n, set_m = m.spelling, None
if n.startswith('set_'):
continue # do nothing, will be treated with the get_
if n.startswith('get_'):
# treat the corresponding setter
n = n[4:]
set_m = next((m for m in plist1 if m.spelling == 'set_' + n),
None)
if set_m:
p = list(CL.get_params(set_m))
if set_m.result_type.spelling == "void" and len(p) == 1:
if not util.decay(
p[0].spelling) == m.result_type.spelling:
OUT += SEP + "Warning :\n"
OUT += SEP + " in get_%s/set_%s\n" % (X, X)
OUT += SEP + " The type taken from set_%s is not the return type of get_%s\n" % (
X, X)
OUT += SEP + " Expected %s\n" % m.result_type.spelling
OUT += SEP + " Got %s\n" % decay(p[0].spelling)
OUT += SEP + " I am not adding the setter to the property\n"
set_m = None
OUT += SEP + "%s %s\n" % (m.spelling,
set_m.spelling if set_m else '')
plist.append(
property_(name=n, doc=doc.make_doc(m), getter=m, setter=set_m))
if OUT:
print " Class %s : transforming to property : \n%s" % (
c.spelling, OUT)
return mlist, plist
def maybe_prop(m):
return len(list(CL.get_params(m))) == 0 and not m.is_static_method()
def has_hdf5_scheme(self, c):
"""True iif the class c has a static method std::string hdf5_scheme()"""
keep = lambda m : CL.is_public(m)
for m in CL.get_methods(c, True, keep):
if m.spelling == "hdf5_scheme" and m.is_static_method() and ('string' in m.result_type.spelling) and len(list(CL.get_params(m))) == 0:
return True
return False
