waky.ru

bash скрипты для начинающих — урок №14: Usage и комментарии.

Написано

waky.ru

в

Предыдущий урок: bash скрипты для начинающих — урок №13: Ключи.

Мы уже практически на финишной прямой, мы многое знаем и умеем. Сегодняшний урок будет больше посвящен тому, как сделать скрипты понятнее и удобнее в использовании. Ведь мало написать функциональный скрипт, важно, чтобы пользователь мог его применить.

Зачем использовать комментарии и usage?

Комментарии помогают другим пользователям понять, что делает скрипт. Это особенно важно, если скрипт сложный или пишется для общего использования. Комментарии будут полезны не только посторонним пользователям, но и автору скрипта, когда понадобится вспомнить, как работает тот или иной скрипт.

Раздел usage показывает, как запускать скрипт, какие аргументы он принимает, и что означает каждый из них. Обычно он выводится при вызове скрипта с флагом -h или —help, или при неправильных аргументах.

Usage и комментарии

Скопируем для сегодняшнего занятия скрипт из предыдущего урока:

[root@waky bash_practice]# cp -a script_13.sh script_14.sh
[root@waky bash_practice]#

Шаг 1: Добавляем комментарии

Комментарий — любая строка текста, поясняющая процессы, прописанные в скрипте. В bash комментарий начинается со знака #. Добавьте в скрипт комментарии, которые в дальнейшем будут напоминать вам, что и зачем происходит в скрипте. У меня получилось так:

#!/bin/bash

#A dummy script to count files in target directory

error_log_file=./script_14.error_log

#A function to log error messages with a timestamp
log_errors() {
    local log_file=$1
    local error_message=$2
    local timestamp=$(date +%d/%m/%Y-%H:%M:%S)

    echo "$timestamp: $error_message" >> $log_file
}

#A function to count files in a directory
count_files_in_directory() {
    local directory=$1
    files_in_dir=$( ls $directory )
    #Check if previous command was success
    if [ $? -ne 0 ]; then
        #Log errors if enabled
        if [ "$err_log_enabled" == "true" ]; then
            log_errors $error_log_file "ERROR: Failed to count files in $directory."
        fi
    else
        files_count=$( echo $files_in_dir | wc -w )
        echo "There are $files_count files in $directory directory."
    fi
}

#Get keys
VALID_ARGS=$(getopt -o t:e: --long target:,errlog: -- "$@")
if [ $? -ne 0 ]; then
    echo "Wrong keys were used"
    exit 1
fi
eval set -- "$VALID_ARGS"
while [ : ];
do
    case "$1" in
        -t | --target)
            target=$2
            shift 2;;
        -e | --errlog)
            err_log_enabled=$2
            shift 2;;
        *)
            break;;
    esac
done

count_files_in_directory $target

Нет строгих правил на количество и содержание комментариев. В первую очередь, в своих скриптах вы вольны размещать столько комментариев, сколько вам требуется для вашего удобства. Но если вы работаете над скриптом совместно с другими людьми, старайтесь чтобы обилие комментариев не мешало читаемости самого кода.

Шаг 2: Добавляем раздел usage

Добавим usage в наш скрипт:

#!/bin/bash

#A dummy script to count files in target directory

#A function to print usage manual
usage() {
    echo "This is a dummy script to count files in target directory."
    echo "-h | --help       Show this help."
    echo "-t | --target     Points a directory to use with the script."
    echo "-e | --errlog     Turns on error logs."
    echo "Usage example:"
    echo "./script_14.sh -t ./path -e true"
}

error_log_file=./script_14.error_log

#A function to log error messages with a timestamp
log_errors() {
    local log_file=$1
    local error_message=$2
    local timestamp=$(date +%d/%m/%Y-%H:%M:%S)

    echo "$timestamp: $error_message" >> $log_file
}

#A function to count files in a directory
count_files_in_directory() {
    local directory=$1
    files_in_dir=$( ls $directory )
    #Check if previous command was success
    if [ $? -ne 0 ]; then
        #Log errors if enabled
        if [ "$err_log_enabled" == "true" ]; then
            log_errors $error_log_file "ERROR: Failed to count files in $directory."
        fi
    else
        files_count=$( echo $files_in_dir | wc -w )
        echo "There are $files_count files in $directory directory."
    fi
}

#Get keys
VALID_ARGS=$(getopt -o ht:e: --long help,target:,errlog: -- "$@")
if [ $? -ne 0 ]; then
    echo "Wrong keys were used"
    usage
    exit 1
fi
eval set -- "$VALID_ARGS"
while [ : ];
do
    case "$1" in
        -h | --help)
            usage
            exit;;
        -t | --target)
            target=$2
            shift 2;;
        -e | --errlog)
            err_log_enabled=$2
            shift 2;;
        *)
            break;;
    esac
done

count_files_in_directory $target

По сути, это простая функция выводящая текст с базовой информацией и подсказками по скрипту. Мы добавили ее вызов по ключу -h (—help):

[root@waky bash_practice]# ./script_14.sh --help
This is a dummy script to count files in target directory.
-h | --help       Show this help.
-t | --target     Points a directory to use with the script.
-e | --errlog     Turns on error logs.
Usage example:
./script_14.sh -t ./path -e true
[root@waky bash_practice]#

И в случае ввода неправильного ключа:

[root@waky bash_practice]# ./script_14.sh --test
getopt: unrecognized option '--test'
Wrong keys were used
This is a dummy script to count files in target directory.
-h | --help       Show this help.
-t | --target     Points a directory to use with the script.
-e | --errlog     Turns on error logs.
Usage example:
./script_14.sh -t ./path -e true
[root@waky bash_practice]#

Итоги:

Использование комментариев сделало наш скрипт понятнее изнутри, а добавление вспомогательной информации через usage сделало скрипт более дружелюбным к пользователю. Теперь другому человеку будет проще понять что и как делает скрипт.

Следующий урок: bash скрипты для начинающих — урок №15: Что дальше?

Больше записей