Mentions légales du service

Skip to content
Snippets Groups Projects
Commit 000aa27e authored by hhakim's avatar hhakim
Browse files

Add a script for editing Faust.m to generate a Matlab inline doc from doxygen code doc. 

- Goal: avoiding doc duplication in Faust.m.
- Update matlab wrapper cmake script to call the parser script.
- By the way update slightly API doc for both wrappers.
parent ada0c0d6
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
gen_doc/gen_matlab_inline_doc_from_doxy_blocks.sh 0 → 100755
+ 106
− 0
View file @ 000aa27e
#!/bin/bash
# this script takes a matlab script documented as defined by doxygen matlab plugin
# parse the doxy doc block and generate a new file .m with inline doc corresponding to the doxygen doc (filtering doxygen tags)
# if a inner code comment block is already present in a function (in the start, just after its name) it will be replaced
function usage {
echo "USAGE: $0 <input_path.m> <output_path.m>"
}
function usage_exit {
usage
exit $1
}
function parse_doxy_block {
local FUNC=$(echo $1 | tr '[a-z]' '[A-Z]')
local FUNC_LINE=$(echo "$3" | sed -e 's/^[[:blank:]]\+//')
echo -e "$2" | sed -e "{
s/^\s*%=\+//;
s/%>\s*@brief/%% $FUNC/;
s/^\([[:blank:]]\+\)%> @param F/\1% SPECS: $FUNC_LINE:\n\1\t% - Parameter F: /;
s/%>/%/;
s/^/\t/;
s/Usage/Usage:/
s/@param\s\([^[:blank:]]\+\)/- Parameter \1: /;
s/@code/=========== code ===========/;
s/@endcode/========= end code =========/;
s/\(Examples\?\)/\1:/
s/<[^>]*>//g;
s/&nbsp;/ /g;
s/@retval/Returns/g;
s/@[^[:blank:]]* \?//g;
s/\\\./\./g
}"
}
# parse input args
[[ $# -ge 2 && -r "$1" ]] && INPUT_FILE="$1" || usage_exit 1
[[ -z $(dirname "$2") || -d "$(dirname $2)" ]] && OUTPUT_FILE="$2" || usage_exit 2
# get function names
FUNCTIONS=$(sed -ne 's/^\s*function[[:blank:]]\+\([^=]\+=\)\?\s*\([^([:blank:]]\+\).*$/\2/p' "$INPUT_FILE")
[[ -z "${FUNCTIONS}" ]] && echo "ERROR in getting the list of functions in $INPUT_FILE" && exit 3
cp "$INPUT_FILE" "$OUTPUT_FILE"
[ ! "$?" = 0 ] && echo "ERROR in copying file." >&2 && exit 4
DOXY_BLOCKS_LIMITS=($(sed -ne '/\s*\%=\+\s*/=' "$INPUT_FILE"))
typeset -i DOXY_BLOCK_ID=0
for FUNC in $FUNCTIONS
do
# get the line numbers of the current inline code block
INLINE_DOC_LINE_NUMS=($(sed -ne '/^\s*function[[:blank:]]\+\([^=]\+=\)\?\s*\('$FUNC'\)[[:blank:]]*(.*$/,/^[[:blank:]]*[^%]\+$/=' $OUTPUT_FILE))
# delete not empty inline code doc block
if [ ${#INLINE_DOC_LINE_NUMS[*]} -gt 2 ]
then
INLINE_DOC_START_NUM=${INLINE_DOC_LINE_NUMS[1]}
INLINE_DOC_END_NUM=${INLINE_DOC_LINE_NUMS[-2]}
[[ $INLINE_DOC_START_NUM =~ [[:digit:]]+ && $INLINE_DOC_END_NUM =~ [[:digit:]]+ ]] && sed -i "${INLINE_DOC_START_NUM},${INLINE_DOC_END_NUM}d" ${OUTPUT_FILE}
[ ! "$?" = 0 ] && echo "ERROR sed deleting old inline doc block." >&2 && exit 5
fi
# get the doxy block for the function
DOXY_BLOCK=$(sed -ne "$((${DOXY_BLOCKS_LIMITS[$DOXY_BLOCK_ID]}+1)),$((${DOXY_BLOCKS_LIMITS[$(($DOXY_BLOCK_ID+1))]}-1))p" "$INPUT_FILE")
[[ "$DEBUG" = "DOXY_BLOCK" ]] && echo "DOXY_BLOCK=$DOXY_BLOCK"
# get the new line position of the function
FUNC_LINE=$(sed -ne '/^\s*function[[:blank:]]\+\([^=]\+=\)\?\s*\('$FUNC'\)[[:blank:]]*(.*$/=' "$OUTPUT_FILE")
[[ "$DEBUG" = "FUNC_LINE" ]] && echo FUNC_LINE=$FUNC_LINE FUNC=$FUNC >&2
[[ ! $FUNC_LINE =~ [[:digit:]]+ ]] && echo "ERROR in getting function $FUNC line number in $OUTPUT_FILE." >&2 && DOXY_BLOCK_ID+=2 && continue
# insert parsed block
FUNC_DEF_LINE=$(sed -ne $FUNC_LINE'p' $OUTPUT_FILE)
sed -ne '1,'$FUNC_LINE'p' $OUTPUT_FILE > ${OUTPUT_FILE}_tmp
# parse doxy block for inline block
INLINE_BLOCK=$(parse_doxy_block $FUNC "$DOXY_BLOCK" "$FUNC_DEF_LINE")
echo -e "$INLINE_BLOCK" >> ${OUTPUT_FILE}_tmp
sed -ne $(($FUNC_LINE+1))','$(wc -l ${OUTPUT_FILE} | awk '{print $1}')'p' $OUTPUT_FILE >> ${OUTPUT_FILE}_tmp
[ "$?" = 0 ] && mv ${OUTPUT_FILE}_tmp ${OUTPUT_FILE}
DOXY_BLOCK_ID+=2
done
# filter header for class doc
HEADER_START_END=($(sed -ne '/^[[:blank:]]*% ==*/=' $OUTPUT_FILE))
OUT_NUM_LINES=$(wc -l ${OUTPUT_FILE}| awk '{print $1}')
DOXY_HEADER=$(sed -ne "$((${HEADER_START_END[0]}+1)),$((${HEADER_START_END[1]}-1))p" ${OUTPUT_FILE})
[[ "$DEBUG" = "DOXY_HEADER" ]] && echo "DOXY_HEADER=$DOXY_HEADER"
INLINE_HEADER=$(parse_doxy_block "FAUST" "$DOXY_HEADER")
[[ "$DEBUG" = "INLINE_HEADER" ]] && echo "INLINE_HEADER=$INLINE_HEADER"
echo -e "$INLINE_HEADER" | sed 's/^[[:blank:]]\+//' > ${OUTPUT_FILE}_tmp
echo -e '\n\n' >> ${OUTPUT_FILE}_tmp
sed -ne "${HEADER_START_END[0]},${OUT_NUM_LINES}p" $OUTPUT_FILE >> ${OUTPUT_FILE}_tmp
[ "$?" = 0 ] && mv ${OUTPUT_FILE}_tmp ${OUTPUT_FILE}
wrapper/matlab/CMakeLists.txt
+ 5
− 2
View file @ 000aa27e
......@@ -14,10 +14,13 @@ foreach(MATLAB_TOOLS FaustCore faust_decompose generate_params)
endforeach()
# install Faust.m in the CMAKE_INSTALL_MATLAB_PREFIX directory
if(WIN32)
configure_file(${FAUST_MATLAB_SRC_DIR}/Faust.m ${FAUST_MATLAB_BIN_DIR}/Faust.m COPYONLY)
#install(FILES ${FAUST_MATLAB_BIN_DIR}/Faust.m DESTINATION ${CMAKE_INSTALL_MATLAB_PREFIX} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE)
else()
execute_process(COMMAND ${FAUST_DOC_SRC_DIR}/gen_matlab_inline_doc_from_doxy_blocks.sh ${FAUST_MATLAB_SRC_DIR}/Faust.m ${FAUST_MATLAB_BIN_DIR}/Faust.m ERROR_QUIET)
#TODO: get back error result with ERROR_VARIABLE SCRIPT_ERROR_VARIABLE and copy simply the script as a fallback solution
endif()
file(GLOB CPP_MEXTOOLS_FILES "${FAUST_MATLAB_TOOLS_SRC_DIR}/*.cpp")
# include directory
......
wrapper/matlab/Faust.m
+ 25
− 16
View file @ 000aa27e
......@@ -40,7 +40,7 @@
%%
% ======================================================================
%> @brief FAµST Matlab class
%> @brief FAµST Matlab wrapper main class.
%>
%> This class represents a given dense matrix by a product of sparse matrices (i.e. Faust).
%> The main goal of Faust representation is to speed up operations on that matrix, especially the multiplication. Besides the time optimization, a Faust can reduce the memory space size needed both for storage and loading.
......@@ -60,6 +60,8 @@
%> Other important limitation is that contrary to a Matlab native dense matrix a Faust is immutable. It means that you cannot affect elements of a Faust using the affectation operator `=' like you do with a Matlab matrix (e.g. `M(i,j) = 2').
%> That limitation is the reason why the Matlab built-in `SUBSASGN()' is not implemented in this class.
%>
%> For more information about FAµST take a look at http://faust.inria.fr.
%>
% ======================================================================
classdef Faust
properties (SetAccess = private, Hidden = true)
......@@ -240,15 +242,21 @@ classdef Faust
%======================================================================
%> @brief Multiplies the Faust or its transpose by the A dense matrix.
%> @brief Multiplies the Faust F by A.' or A which is a dense matrix or a Faust object.
%>
%> This function overloads a Matlab built-in function.
%>
%> @b WARNING: this function costs as much as Faust.mtimes.
%> @b WARNING: if A is a matrix the function costs get_num_factors(F) matrix multiplications.
%> In that case its use is discouraged except for test purpose. However if A is a Faust object,
%> it costs the same that a Faust initialization with a number of factors equal to
%> F.get_num_factors()+A.get_num_factors() (like you can do directly with Faust.Faust).
%>
%> @param A the matrix to multiply (dense matrix).
%> @param F the Faust object.
%> @param A The dense matrix to multiply or a Faust object.
%> @param trans equals 1 to calculate C=F'*A
%> or 0 to calculate C=F*A.
%>
%> @retval C The multiplication result (dense matrix).
%> @retval C The multiplication result (a dense matrix or a Faust object depending on what A is).
%>
%> <p> @b See @b also mtimes.
%======================================================================
......@@ -391,7 +399,7 @@ classdef Faust
%> <p/>@b See @b also Faust.transpose, Faust.conj
%>
%======================================================================
function F_ctrans=ctranspose(F)
function F_ctrans = ctranspose(F)
%% CTRANSPOSE ' Complex conjugate transposed Faust (overloaded Matlab built-in function).
%
% F_trans = ctranspose(F) is called for syntax F' (complex conjugate transpose) when F is a Faust.
......@@ -429,7 +437,7 @@ classdef Faust
%> <p/>@b See @b also Faust.get_factor, Faust.get_num_factors, Faust.ctranspose
%>
%======================================================================
function F_conj=conj(F)
function F_conj = conj(F)
%% CONJ ' Complex conjugate Faust (overloaded Matlab built-in function).
%
% F_conj = conj(F) For a complex F, F_conj == REAL(F) - i*IMAG(F)
......@@ -697,9 +705,9 @@ classdef Faust
%> @retval The Faust object requested.
%>
%> @b Example
%> @code
%> F = Faust.rand([2, 5], [50, 100], .5)
%> i = randi(min(size(F)), 1, 2)
%> @code
%> F = Faust.rand([2, 5], [50, 100], .5)
%> i = randi(min(size(F)), 1, 2)
%> i1 = i(1);i2 = i(2)
%>
%> F(i1,i2) % a Faust representing a matrix with only one element
......@@ -710,11 +718,11 @@ classdef Faust
%> F(3:4,2:5) % from row 3 to line 4, each row containing only elements from column 2 to 5.
%>
%> F(1:end,5:end-1) % from row 1 to end row, each one containing only elements from column 5 to column before the last one.
%> @endcode
%> @endcode
%>
%> <p>@b See @b also Faust.end.
%==========================================================================================
function submatrix=subsref(F,S)
function submatrix = subsref(F,S)
%% SUBSREF Subscripted reference (overloaded Matlab built-in function).
%
% F(I,J) is an array formed from the elements of the rectangular
......@@ -784,6 +792,7 @@ classdef Faust
%> @param F the Faust to display information about.
%>
%>
%======================================================================
function F = subsasgn(F,S,B)
%% SUBSASGN (WARNING not implemented) (overloaded Matlab built-in function)
%
......@@ -876,7 +885,7 @@ classdef Faust
%>
%>
%======================================================================
function norm=norm(F,varargin)
function norm = norm(F,varargin)
%% NORM Faust norm (overloaded Matlab built-in function).
%
% norm(F,1) when F is a Faust returns L1 norm of F (the largest
......@@ -931,7 +940,7 @@ classdef Faust
%>
%> <p>@b See @b also Faust.rcg, Faust.density.
%==========================================================================================
function nz=nnz_sum(F)
function nz = nnz_sum(F)
%% NNZ Number of nonzero elements in a Faust (overloaded Matlab built-in function).
%
% nz = nnz_sum(F) is the number of nonzero elements in the Faust F.
......@@ -963,7 +972,7 @@ classdef Faust
%>
%> <p/>@b See @b also Faust.nnz_sum, Faust.rcg
%======================================================================
function dens=density(F)
function dens = density(F)
%% DENSITY Density of the Faust.
%
% dens = density(F) when F is a Faust returns the
......@@ -998,7 +1007,7 @@ classdef Faust
%>
%> <p>@b See @b also Faust.density, Faust.nnz_sum.
%==========================================================================================
function speed_up=rcg(F)
function speed_up = rcg(F)
%% RCG Relative Complexity Gain (inverse of the density)
%
% speed_up = rcg(F) when F is Faust, returns the
......
wrapper/python/pyfaust.py
+ 2
− 1
View file @ 000aa27e
......@@ -48,7 +48,7 @@ import FaustCorePy
class Faust:
"""FAµST Python class.
"""FAµST Python wrapper main class.
This class represents a given dense matrix by a product of sparse matrices
(i.e. Faust).
The main goal of Faust representation is to speed up operations on that
......@@ -88,6 +88,7 @@ class Faust:
That limitation is the reason why the Python built-in `__setitem__()' is not
implemented in this class.
For more information about FAµST take a look at http://faust.inria.fr.
"""
def __init__(F, factors=None, scale=1.0, filepath=None, core_obj=None):
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment