REPLACE ----- remove the " * " prefix first -----------------*- mode:python -*-
^[ ]\*[ ]
WITH --------------------------------------------------------------------------
REPLACE ----- remove the " *" lines -------------------------------------------
^[ ]\*\s*\n
WITH --------------------------------------------------------------------------
\n
REPLACE ----- for the template functions --------------------------------------
FUNCTION\(
(?P[^, \)]*)\s*,\s*
(?P[^\)]*)
\)\s*
WITH
\g_\g
REPLACE ----- template type ---------------------------------------------------
TYPE\(
(?P[^\)]*)
\)
WITH
\g_t
REPLACE ----- template base type, we cowardly assume real number --------------
BASE
WITH
igraph_real_t
REPLACE ----- function object, extract its signature --------------------------
(?P\A.*?) # head of the comment
\\function\s+ # \function keyword
(?P(?P
(igraph_)|(IGRAPH_)|())(?P\w+)) # the keyword, remove igraph_ prefix
[\s]*(?P[^\n]*?)\n # brief description
(?P.*?)\*\/ # tail of the comment
\s*
(IGRAPH_EXPORT )? # strip IGRAPH_EXPORT from prototype
(?P.*?\)) # function head
(?=(\s*;)|(\s*\{)) # prototype ends with ; function head with {
.*\Z # and the remainder
WITH --------------------------------------------------------------------------
<function>\g<name></function> — \g<brief>\g
\g;
\g
\g
REPLACE ----- for functions (not used currently) -------------------
(?P[^<]*)\n
RUN ---------------------------------------------------------------------------
dr_params=string.split(matched.group("params"), ',')
dr_out=""
for dr_i in dr_params:
dr_i=string.strip(dr_i)
if dr_i=="...":
dr_out=dr_out+""
else:
dr_words=re.match(r"([\w\*\&\s]+)(\b\w+)$", dr_i).groups()
dr_out=dr_out+""+dr_words[0]+""+dr_words[1]+ \
"\n"
actch=actch[0:matched.start()]+dr_out+actch[matched.end():]
REPLACE ----- function parameter descriptions, head ---------------------------
(?P\A.*?) # head of the comment
\\param\b # first \param commant
WITH --------------------------------------------------------------------------
\gArguments:
\\param
REPLACE ----- function parameter descriptions, tail ---------------------------
# the end of the params is either an empty line after the last \param
# command or a \return or \sa statement (others might be added later)
# or the end of the comment
\\param\b # the last \param command
(?P.*?) # the text of the \param command
(?P # this marks the end of the \param text
(\\return\b)|(\\sa\b)| # it is either a \return or \sa or
(\n\s*?\n)| # (at least) one empty line or
(\*\/)) # the end of the comment
(?P.*?\Z) # remaining part
WITH
\\param\g
\g\g
REPLACE ----- function parameter descriptions ---------------------------------
\\param\b\s* # \param command
(?P(\w+)|(...))\s+ # name of the parameter
(?P.*?) # text of the \param command
(?=(\\param)|()|
(\n\s*\n))
WITH --------------------------------------------------------------------------
\g:
\g
REPLACE ----- \return command -------------------------------------------------
# a return statement ends with an empty line or the end of the comment
\\return\b\s* # \return command
(?P.*?) # the text
(?=(\n\s*?\n)| # empty line or
(\*\/)| # the end of the comment or
(\\sa\b)) # \sa command
WITH ----------------------------------------------------------------------TODO
Returns:
\g
REPLACE ----- variables -------------------------------------------------------
(?P\A.*?) # head of the comment
\\var\s+ # \var keyword + argument
(?P(?P
(igraph_)|(IGRAPH_)|())(?P\w+))
[\s]*(?P[^\n]*?)\n # brief description
(?P.*?)\*\/ # tail of the comment
\s*(?P[^;]*;) # the definition of the variable
.*\Z # and the remainder
WITH --------------------------------------------------------------------------
<function>\g<name></function> — \g<brief>\g
\g
\g\g
REPLACE ----- \define ---------------------------------------------------------
(?P\A.*?) # head of the comment
\\define\s+ # \define command
(?P(?P
(igraph_)|(IGRAPH_)|())(?P\w+))
[\s]*(?P[^\n]*?)\n # brief description
(?P.*?)\*\/ # tail of the comment
\s* # whitespace
(?P\#define\s+[\w0-9,]+\s* # macro name
(\([\w0-9, ]+\))?) # macro args (optional)
.*\Z # drop the remainder
WITH --------------------------------------------------------------------------
<function>\g<name></function> — \g<brief>\g
\g
\g\g
REPLACE ----- \section without title ------------------------------------------
(?P\A.*?) # head of the comment
\\section\s+(?P\w+)\s*$ # \section + argument
(?P.*?)\*\/ # tail of the comment
.*\Z # and the remainder, this is dropped
WITH
\g
\g
REPLACE ----- \section with title ---------------------------------------------
(?P\A.*?) # head of the comment
\\section\s+(?P\w+) # \section + argument
(?P.*?) # section title
\n\s*?\n # empty line
(?P<after>.*?)\*\/ # tail of the comment
.*\Z # and the remainder, this is dropped
WITH
<title>\g<title>
\g
\g
REPLACE ----- \section with title ---------------------------------------------
(?P\A.*?) # head of the comment
\\section\s+(?P\w+) # \section + argument
(?P.*?)\s*\*\/ # section title
.*\Z # and the remainder, this is dropped
WITH
<title>\g<title>
\g
REPLACE ----- an enumeration typedef ------------------------------------------
(?P\A.*?) # head of the comment
\\typedef\s+ # \typedef command
(?P(?P
(igraph_)|(IGRAPH_)|())(?P\w+))
[\s]*(?P[^\n]*?)\n # brief description
(?P.*?) # tail of the comment
\*\/\s* # closing the comment
(?Ptypedef\s*enum\s*\{ # typedef enum
[^\}]*\}\s*\w+\s*;) # rest of the definition
.*\Z
WITH --------------------------------------------------------------------------
<function>\g<name></function> — \g<brief>\g
\g
\g\g
REPLACE ----- enumeration value descriptions, head ----------------------------
(?P\A.*?) # head of the comment
\\enumval\b # first \param commant
WITH --------------------------------------------------------------------------
\g
Values:
\\enumval
REPLACE ----- enumeration value descriptions, tail ----------------------------
\\enumval\b # the last \enumval command
(?P.*?) # the text of the \enumval command
(?P # this marks the end of the \enumval text
(\\return\b)|(\\sa\b)| # it is either a \return or \sa or
(\n\s*?\n)| # (at least) one empty line or
(\*\/)) # the end of the comment
(?P.*?\Z) # remaining part
WITH
\\enumval\g
\g\g
REPLACE ----- enumeration value descriptions ----------------------------------
\\enumval\b\s* # \enumval command
(?P(\w+)|(...))\s+ # name of the parameter
(?P.*?) # text of the \enumval command
(?=(\\enumval)|()|
(\n\s*\n))
WITH --------------------------------------------------------------------------
\g:
\g
REPLACE ----- \struct ---------------------------------------------------------
(?P\A.*?) # head of the comment
\\struct\s+ # \struct command
(?P(?P
(igraph_)|(IGRAPH_)|())(?P[\w_]+))
[\s]*(?P[^\n]*?)(?=\n) # brief description
(?P.*?) # tail of the command
\*\/\s* # closing the comment
(?Ptypedef \s*struct\s*\w+\s*\{
.*\}\s*\w+\s*;)
.*\Z
WITH --------------------------------------------------------------------------
<function>\g<name></function> — \g<brief>\g
\g
\g\g
REPLACE ----- structure member descriptions, one block ------------------------
^[\s]*\n
(?P.*?) # empty line+text
(?P\\member\b.*?) # member commands
(?= # this marks the end of the \member text
(\\return\b)|(\\sa\b)| # it is either a \return or \sa or
(^[\s]*\n)| # (at least) one empty line or
(\*\/)) # the end of the comment
WITH --------------------------------------------------------------------------
\gValues:
\g
REPLACE ----- structure member descriptions -----------------------------------
\\member\b\s* # \enumval command
(?P(\w+)|(...))\s+ # name of the parameter
(?P.*?) # text of the \enumval command
(?=(\\member)|()|
(\n\s*\n))
WITH --------------------------------------------------------------------------
\g:
\g
REPLACE ----- \typedef function -----------------------------------------------
(?P\A.*?) # comment head
\\typedef\s+ # \typedef command
(?P(?P
(igraph_)|(IGRAPH_)|())(?P\w+))
[\s]*(?P[^\n]*?)\n # brief description
(?P.*?) # comment tail
\*\/ # end of comment block
\s*
(?Ptypedef\s+[^;]*;) # the typedef definition
.*\Z
WITH --------------------------------------------------------------------------
<function>\g<name></function> — \g<brief>\g
\g
\g\g
REPLACE ----- ignore doxygen \ingroup command ---------------------------------
\\ingroup\s+\w+
WITH --------------------------------------------------------------------------
REPLACE ----- ignore doxygen \defgroup command --------------------------------
\\defgroup\s+\w+
WITH --------------------------------------------------------------------------
REPLACE ----- add the contents of \brief to the description -------------------
\\brief\b
WITH --------------------------------------------------------------------------
REPLACE ----- \varname command ------------------------------------------------
\\varname\b\s*
(?P\w+\b)
WITH
\g
REPLACE ----- references, \ref command ----------------------------------------
\\ref\b\s*
(?P\w+)(?P([\(][\)])?)
WITH --------------------------------------------------------------------------
\g\g
REPLACE ----- \sa command -----------------------------------------------------
\\sa\b
\s*
(?P.*?)
(?=(\n\s*?\n)|(\*\/))
WITH ----------------------------------------------------------------------TODO
See also:
\g
REPLACE ----- \em command -----------------------------------------------------
\\em\b
\s*
(?P[^\s]+)
WITH
\g
REPLACE ----- \emb command ----------------------------------------------------
\\emb\b
WITH
REPLACE ----- \eme command ----------------------------------------------------
\\eme\b
WITH
REPLACE ----- \verbatim -------------------------------------------------------
\\verbatim\b
WITH
REPLACE ----- \endverbatim ----------------------------------------------------
\\endverbatim\b
WITH
REPLACE ----- \clist ----------------------------------------------------------
\\clist\b
WITH
REPLACE ----- \cli ------------------------------------------------------------
\\cli\s+(?P.*?)$
(?P.*?)
(?=(\\cli)|(\\endclist))
WITH --------------------------------------------------------------------------
\g
\g
REPLACE ----- \endclist -------------------------------------------------------
\\endclist\b
WITH
REPLACE ----- \olist ----------------------------------------------------------
\\olist\b
WITH
REPLACE ----- \oli ------------------------------------------------------------
\\oli\s+(?P.*?)
(?=(\\oli)|(\\endolist))
WITH
\g
REPLACE ----- \endolist -------------------------------------------------------
\\endolist\b
WITH
REPLACE ----- \ilist ----------------------------------------------------------
\\ilist\b
WITH
REPLACE ----- \ili ------------------------------------------------------------
\\ili\s+(?P.*?)
(?=(\\ili)|(\\endilist))
WITH
\g
REPLACE ----- \endilist -------------------------------------------------------
\\endilist\b
WITH
REPLACE ----- doxygen \c command is for ----------------------------
\\c\s+(?P[\w\-^\']+)\b
WITH
\g
REPLACE ----- doxygen \p command is for ---------------------------
\\p\s+(?P\w+)\b
WITH
\g
REPLACE ----- doxygen \type command is for -----------------------------
\\type\s+(?P\w+)\b
WITH
\g
REPLACE ----- doxygen \a command is for -----------------------------
\\a\s+(?P\w+)\b
WITH
\g
REPLACE ----- doxygen \quote command is for ---------------------------
\\quote\s+
WITH
REPLACE ----- doxygen \endquote command is for -----------------------
\s*\\endquote\b
WITH
REPLACE ----- replace with -----------------------------------
<(?P/?)code>
WITH --------------------------------------------------------------------------
<\gliteral>
REPLACE ----- add http:// and https:// links ----------------------------------
(?Phttps?:\/\/[-\+=&;%@./~()'\w_]*[-\+=&;%@/~'\w_])
WITH --------------------------------------------------------------------------
\g
REPLACE ----- blockquote ------------------------------------------------------
\\blockquote
WITH --------------------------------------------------------------------------
REPLACE ----- blockquote ------------------------------------------------------
\\endblockquote
WITH --------------------------------------------------------------------------
REPLACE ----- example file ---------------------------------------------------
\\example\b\s*
(?P[^\n]*?)\n
WITH --------------------------------------------------------------------------
File <code>\g<filename></code>
REPLACE ----- \deprecated-by --------------------------------------------------
\\deprecated-by\b\s*
(?P[^ \n]+)\s*
(?P[^\n]+)\n
WITH --------------------------------------------------------------------------
Deprecated since version \g. Please do not use this function in new
code; use \g()
instead.
REPLACE ----- \deprecated -----------------------------------------------------
\\deprecated\b\s*
(?P[^\n]*?)\n
WITH --------------------------------------------------------------------------
Deprecated since version \g. Please do not use this function in new
code.
REPLACE ----- \experimental ---------------------------------------------------
\\experimental\b\s*\n
WITH --------------------------------------------------------------------------
This function is experimental and its signature is not considered final yet.
We reserve the right to change the function signature without changing the
major version of igraph. Use it at your own risk.