Back

index_functions()

Below is an in-depth documentation for the function index_function(). This documentation explains the purpose, internal logic, variables, and workflow of the function step by step.

Documentation for the index_function() Function

1. Purpose and Overview

index_function() is a core function in the cleqc.sh script that is responsible for:

  • Indexing and registering function calls: It handles the creation and updating of file references for functions detected within the script.

  • Tracking function states: It distinguishes between when a function is being opened (started), closed (ended), or when its content is simply a comment or module.

  • Updating related files: Depending on the state of the function, it writes or updates files containing the function’s code (both in library and code directories) and maintains an index (FINDEX).

The function plays a key role in assembling and maintaining the dynamic behavior of the script by ensuring that each function is properly recorded with its source code and context.

2. Detailed Walkthrough

2.1. Initial Output and Comments

echo ''$FNCLINE'' #echo ''$FNCOPENFILE'' #doit assigner le fichier fnc, incrémenter BINDEX et inscrire FINDEX

  • Output Statement:
    The function begins by echoing the variable FNCLINE. This variable holds the current line of code being processed, which helps trace which function or code block is under evaluation.

  • Developer Comments:
    The comments indicate that the function should:

    • Assign the file for the function,

    • Increment a counter (BINDEX) if applicable,

    • Record an index (FINDEX) to keep track of the function’s instance.

These comments guide the developer by explaining the intended effects of the function.

2.2. Determining the Function Target

if [ ! -z "`echo ${OUTFUNCTION[@]}`" ]; then FNCTARGET=OUT elif [ ! -z "`echo ${INFUNCTION[@]}`" ]; then FNCTARGET=IN else FNCTARGET=MODULE fi

  • Purpose:
    This block decides which “target” or category the function belongs to. There are three possible targets:

    • OUT: If there is an existing value in the OUTFUNCTION array.

    • IN: If no OUTFUNCTION is present, but the INFUNCTION array is not empty.

    • MODULE: If neither array is set, then the function is treated as a module.

  • Explanation:

    • The use of echo ${OUTFUNCTION[@]} and echo ${INFUNCTION[@]} checks if the arrays contain any elements.

    • The target is stored in the variable FNCTARGET and later influences how the code is written to various files.

2.3. Determining the Function Status

if [ ! -z "$FNCEND" ]; then FNCSTATUS=CLOSE #FNCEND="" elif [ ! -z "$FNCBRACE" ]; then FNCSTATUS=OPEN elif [ ! -z "$COMMENTLINE" ]; then FNCSTATUS=COMMENT else FNCSTATUS=MODULE fi

  • Purpose:
    This segment sets the FNCSTATUS variable based on which indicators are present:

    • CLOSE: If FNCEND is not empty, indicating that the current function block is closing.

    • OPEN: If FNCBRACE is set, meaning that a new function is being opened.

    • COMMENT: If COMMENTLINE is not empty, indicating that the line is a comment.

    • MODULE: Default status if none of the above conditions apply.

  • Explanation:

    • The conditional structure ensures that the function can differentiate between starting and ending code blocks.

    • This status is later used in a case statement to determine the exact actions for each situation.

2.4. Handling Based on Function Status

The main logic of index_function() is implemented as a case statement on FNCSTATUS.

2.4.1. Status: OPEN

case $FNCSTATUS in OPEN) # On entre dans une fonction for indexfile in ${INFUNCTION[${#INFUNCTION[@]}-1]} ; do LIBRARYFILE[${#LIBRARYFILE[@]}]=''$sourcedir'/fonctions/'$indexfile'' INDEXFILE[${#INDEXFILE[@]}]=''$sourcedir'/codes/'$indexfile'_'$script'' if [ -f "${INDEXFILE[${#INDEXFILE[@]}-1]}" ]; then CODENBR=0 while [ -f "${INDEXFILE[${#INDEXFILE[@]}-1]}" ]; do CODENBR=$(($CODENBR+1)) unset INDEXFILE[${#INDEXFILE[@]}-1] INDEXFILE[${#INDEXFILE[@]}]=''$sourcedir'/codes/'$indexfile'_'$script''$CODENBR'' if [ "$CODENBR" -eq "100" ]; then INDEXFILE=''$sourcedir'/fonctions/'$indexfile'' fi done fi if [ -f "${LIBRARYFILE[${#LIBRARYFILE[@]}-1]}" ]; then echo ''$indexfile'() {' >> ''${INDEXFILE[${#INDEXFILE[@]}-1]}'' fi if [ -f $sourcedir/$MODULEFILE ]; then echo ''$indexfile'() {' >> "$sourcedir/$MODULEFILE" fi echo "$indexfile() { . \"../codes/$indexfile"_"$script$CODENBR\" } " > ''$sourcedir'/fonctions/'$indexfile'_code' DATEFILE=${INDEXFILE[${#INDEXFILE[@]}-1]} datefile done ;;

  • Purpose:
    When a new function block is detected (status OPEN), the function:

    1. Selects the current function name:
      It retrieves the last element from the INFUNCTION array (which stores functions currently being processed).

    2. Constructs file paths:

      • LIBRARYFILE: Points to the directory where the function will be stored as part of the library.

      • INDEXFILE: Represents the file where the function’s code will be written.

    3. Handling Duplicates:

      • The if [ -f "${INDEXFILE[...]" ] block checks if the file already exists.

      • A loop increments a counter (CODENBR) to generate a unique filename if duplicates are found.

      • There is a safeguard: if CODENBR reaches 100, it resets the file reference.

    4. Writing the Function Header:

      • If the library file exists, it writes a header line (e.g., “function_name() {”) to the corresponding code file.

      • Similarly, if a module file exists, it writes the header line there as well.

    5. Creating a Code Snippet File:

      • It writes a complete wrapper for the function that sources the actual code file. This wrapper is stored in a file named after the function (with a suffix _code).

    6. Updating the Date File:

      • The variable DATEFILE is set to the current INDEXFILE.

      • It then calls the external function datefile to possibly log the date/time of the function indexing.

  • Key Points:

    • Looping on INFUNCTION:
      The loop over the last element of INFUNCTION ensures that only the most recent (or active) function is processed.

    • Unique Filenames:
      The use of CODENBR in conjunction with file existence tests prevents overwriting previously indexed functions.

    • Modular Output:
      Output is directed to multiple files (the library, code, and module files), which aids in maintaining separation of concerns and easier management of the code base.

2.4.2. Status: CLOSE

CLOSE) unset INDEXFILE[${#INDEXFILE[@]}-1] unset LIBRARYFILE[${#LIBRARYFILE[@]}-1] #FNCEND="" ;;

  • Purpose:
    When the function block is ending (status CLOSE), the function cleans up:

    • It removes the last entries from both INDEXFILE and LIBRARYFILE arrays. This effectively “closes” the active function block, ensuring that further lines are not mistakenly attributed to the function.

  • Explanation:

    • The use of unset ensures that the file descriptors for the function are no longer active, which prevents any further code from being appended to these files.

    • The commented out line (#FNCEND="") suggests that resetting FNCEND might be handled elsewhere or was under consideration for future modifications.

2.4.3. Status: COMMENT

COMMENT) ;;

  • Purpose:
    If the current line is a comment, the function does nothing.

  • Explanation:

    • This branch is intentionally left empty since comments should not trigger any indexing or file operations.

2.4.4. Status: MODULE

MODULE) case $FNCTARGET in IN) echo "fichier index" for indexfile in ${INDEXFILE[@]} ; do echo ''$FNCLINE'' >> "$indexfile" done for libraryfile in ${LIBRARYFILE[@]} ; do echo ''$FNCLINE'' >> "$libraryfile" done ;; OUT) ;; MODULE) for indexfile in ${INFUNCTION[@]} ; do echo ''$FNCLINE'' >> "$sourcedir/$indexfile" done ;; esac ;;

  • Purpose:
    For the MODULE status, the function further differentiates behavior based on FNCTARGET.

    • If FNCTARGET is IN:

      • It writes the current FNCLINE to all files in INDEXFILE and LIBRARYFILE arrays.

      • This ensures that the module’s index is updated with the latest code line.

    • If FNCTARGET is OUT:

      • No action is taken (the branch is empty).

    • If FNCTARGET is MODULE:

      • It writes FNCLINE to a file located at $sourcedir/$indexfile for each function in the INFUNCTION array.

  • Explanation:

    • This nested case structure provides flexibility in handling different target types:

      • IN: Often used for functions that are being actively built.

      • MODULE: Might represent a standalone module or a different grouping of functions.

      • OUT: Could be reserved for functions that are called from outside or that require no further index update.

    • The echo statements append the current line of code (FNCLINE) to the appropriate files, ensuring that the module or library files are kept in sync with the latest changes.

3. Variables and Their Roles

  • FNCLINE:
    Holds the current line of code being processed. It is echoed and appended to files to record function details.

  • OUTFUNCTION and INFUNCTION:
    Arrays that store functions considered “out” or “in” respectively. Their contents determine the target for function indexing.

  • FNCTARGET:
    A variable that holds the target type (OUT, IN, or MODULE) based on the presence of functions in the above arrays.

  • FNCEND, FNCBRACE, COMMENTLINE:
    Indicators used to determine the current state of the function block:

    • FNCEND: Indicates the end of a function.

    • FNCBRACE: Indicates the opening of a function.

    • COMMENTLINE: Marks a comment line.

  • INDEXFILE and LIBRARYFILE:
    Arrays that store file paths where the function’s code and library definitions are to be written.

  • sourcedir, script:
    Global variables that specify the base directory for the source files and the script name. They are used to construct full file paths.

  • CODENBR:
    A counter used to ensure that multiple instances of the same function are uniquely identified by incrementing the filename if a file already exists.

  • DATEFILE:
    Holds the reference to the current index file and is used in conjunction with the datefile function to log timestamps.

4. Workflow Diagram Summary

  1. Display the current function line (FNCLINE).

  2. Determine the function target (FNCTARGET):

    • Check OUTFUNCTION, then INFUNCTION, otherwise default to MODULE.

  3. Determine the function status (FNCSTATUS):

    • If FNCEND is set, status is CLOSE.

    • Else if FNCBRACE is set, status is OPEN.

    • Else if COMMENTLINE is set, status is COMMENT.

    • Otherwise, status is MODULE.

  4. Case Handling Based on FNCSTATUS:

    • OPEN:

      • Process the last function in INFUNCTION.

      • Build file paths for LIBRARYFILE and INDEXFILE.

      • Check for duplicate file names and increment CODENBR as needed.

      • Write function headers to files.

      • Create a code snippet file that sources the actual code file.

      • Log the current file state via datefile.

    • CLOSE:

      • Remove the last entries in INDEXFILE and LIBRARYFILE arrays.

    • COMMENT:

      • Do nothing.

    • MODULE:

      • Further process based on FNCTARGET (IN, OUT, MODULE) by appending FNCLINE to the relevant files.

5. Conclusion

The index_function() is a multifaceted function that:

  • Indexes and tracks function blocks by writing headers and maintaining unique file references.

  • Differentiates states (OPEN, CLOSE, COMMENT, MODULE) to perform the appropriate action.

  • Utilizes arrays and counters (e.g., INFUNCTION, LIBRARYFILE, INDEXFILE, CODENBR) to ensure that each function is properly documented and that duplicate filenames are avoided.

  • Integrates with external functions (like datefile) to log activity and ensure the system’s traceability.

This comprehensive breakdown should serve as a thorough reference for developers looking to understand, maintain, or extend the functionality of the cleqc.sh script’s function indexing mechanism.