bash args

Bash-args

Ini adalah kerangka kerja untuk menulis skrip bash yang menerima opsi dan/atau argumen. Tentukan opsi dan argumen yang diterima oleh skrip Anda menggunakan sintaks deklaratif sederhana dan biarkan bash-args :

• Parsing argumen perintah
• Hasilkan halaman bantuan
• Tangani pelengkapan otomatis

Ini dirancang agar mudah digunakan, tidak mengganggu, dan memberikan pengalaman pengguna yang sempurna.

Ini bertujuan untuk menjadi portabel, rangkaian pengujian meneruskan semua versi utama bash >= 3.2.

Daftar isi

• Mulai cepat
  • Sub-Perintah
• Metadata skrip
• Mendefinisikan pilihan
• Penyelesaian otomatis
  • Jenis argumen
  • Jenis argumen khusus

Mulai cepat

Untuk menggunakan bash-args dalam skrip Anda, cukup sumber file init.sh

Berikut ini contoh skrip eval-command.sh :

 #! /usr/bin/env bash
# Summary : My first bash script using bash-args.
#
# Description : This takes a command as argument, and runs it.
#
# Argument : command
#
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#

. path/to/bash-args/init.sh

# After sourcing the script, you can use the $directory and the $dry_run
# variables to get the values of the options typed (or not) in the command line.
# The other arguments are available as standard bash arguments $1, $2, etc.

command= " cd $directory && $1 "

if [[ $dry_run -eq 1 ]] ; then
    echo " $command "
else
    eval " $command "
fi

Mari kita coba jalankan perintah ini dengan opsi :

 $ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello

Anda dapat menggunakan opsi pendek, dan opsi tersebut dapat dikelompokkan :

 $ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello

Penyetelan tab selesai dengan perintah sederhana:

 $ eval $(eval-command.sh _register_completion)

Halaman bantuan disediakan:

 $ eval-command.sh --help
My first bash script using bash-args.

Usage : eval-command.sh [OPTIONS] [COMMAND]

This takes a command as argument, and runs it.

Options :

  --help | -h
          Show this help.

  --dry-run | -n
          Don't execute, just print.

  --directory | -d [DIRECTORY]
          The directory in which to run the command.

Sub-Perintah

Bash-args juga dapat mengelola sub-perintah:

• Halaman bantuan tersedia untuk setiap perintah menggunakan main-script.sh help subcmd1 , atau main-script.sh subcmd1 --help .
• Pelengkapan otomatis menyarankan sub-perintah, opsinya, dan argumennya.

Untuk mewujudkannya, panggil fungsi cmd_run di akhir skrip utama Anda, dan tentukan sub-perintah dengan menambahkan skrip shell ke direktori cmd/ . Struktur proyek Anda akan terlihat seperti:

 main-script.sh
cmd/
  - subcmd1.sh
  - subcmd2.sh

Untuk mendokumentasikan sub-perintah, dan menentukan opsi dan argumennya, tulis metadata di blok komentar pertama setiap sub-perintah, seperti di skrip utama.

Opsi yang ditentukan dalam skrip utama tersedia untuk semua sub-perintah, sedangkan opsi yang ditentukan dalam sub-perintah hanya tersedia untuk sub-perintah khusus ini.

Metadata skrip

Metadata skrip mengikuti sintaks yang sangat sederhana: di blok komentar pertama, setiap baris yang dimulai dengan kata diikuti dengan titik koma mendefinisikan bidang baru, dan segala sesuatu yang mengikuti titik koma menentukan nilainya. Baris berikut, hingga awal bidang berikutnya, ditambahkan ke nilai.

Berikut adalah bidang yang digunakan oleh bash-args .

• Ringkasan : Deskripsi satu baris naskah.
• Deskripsi : Deskripsi naskah yang panjang.
• Versi : String versi. Jika skrip utama Anda memiliki kolom version meta, ia akan mendapatkan opsi --version yang mencetak nama dan versinya.
• Penggunaan : Jika baris penggunaan default di halaman bantuan tidak sesuai dengan Anda, Anda dapat menggantinya di sini.
• Argumen : Mendefinisikan tipe argumen yang digunakan untuk pelengkapan otomatis. lihat Jenis argumen
• Options : Tentukan opsi skrip Anda. lihat Menentukan opsi

Mendefinisikan pilihan

Opsi ditentukan dalam metadata Opsi , seperti dalam contoh skrip :

 # Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#

Sebuah opsi dimulai dengan % diikuti dengan namanya. Nama opsi hanya boleh berisi karakter alfanumerik, _ atau - .

Baris berikut menentukan parameter opsi. Ketika skrip dijalankan, ini sebenarnya dievaluasi sebagai kode bash. Variabel yang ditentukan adalah parameter opsi. Ini berarti bahwa aturan kutipan umum untuk string berlaku, dan Anda dapat menentukan opsi secara dinamis, seperti pada contoh di atas, di mana parameter default opsi directory diatur ke $(pwd) .

Sebuah opsi harus menentukan setidaknya type dan parameter variable :

• type dapat berupa flag atau option . Bendera tidak menerima argumen, opsi menerima.
• variable adalah nama variabel yang nilai argumen opsinya akan tersedia di skrip Anda.

Sebuah opsi dapat menentukan parameter lain berikut:

• desc adalah deskripsi opsi, yang digunakan di halaman bantuan.
• short adalah huruf tunggal, digunakan untuk opsi pendek.
• argument adalah tipe argumen. lihat Jenis argumen
• default adalah nilai yang diambil opsi ketika opsi tersebut tidak ditentukan dalam perintah yang diketik oleh pengguna.
• value adalah nilai yang diambil opsi saat opsi ditentukan , tetapi tanpa argumen.

Variabel yang ditentukan oleh opsi dijamin akan ditentukan dalam skrip Anda: jika bash-args tidak dapat menemukan nilai untuk suatu opsi, maka akan keluar dengan kesalahan. Artinya, jika Anda tidak menentukan default suatu opsi, menjalankan skrip utama tanpa opsi ini akan menghasilkan kesalahan.

Dengan kata lain, jika Anda tidak ingin suatu opsi diperlukan, tentukan parameter default dalam definisinya.

Parameter value bekerja dengan cara yang sama. Jika Anda tidak menentukannya, opsi tersebut, saat digunakan, memerlukan argumen. Jika ya, opsi tersebut dapat digunakan tanpa argumen.

Opsi tanda bekerja dengan cara yang sama, dan karena opsi tersebut tidak menggunakan argumen, Anda harus menentukan parameter default dan value .

Penyelesaian otomatis

Bash-args dapat menangani penyelesaian otomatis untuk skrip Anda menggunakan API penyelesaian Bash. Untuk mengaktifkan pelengkapan otomatis untuk perintah Anda, jalankan perintah berikut:

 eval $( my-command.sh _register_completion )

Penyelesaian tab kemudian akan menyarankan opsi yang ditentukan jika kata pada titik dimulai dengan - , dan menyarankan sub-perintah dan argumen sebaliknya.

Jenis argumen

Untuk memberi tahu bash-args apa yang disarankan sebagai argumen, Anda menentukan tipe argumen dalam metadata Argument skrip Anda (atau sub-perintah), atau dalam parameter argument dari sebuah opsi.

Berikut adalah tipe argumen bawaan:

• file akan menyarankan file.
• direktori akan menyarankan direktori.

Jenis argumen khusus

Untuk membuat tipe argumen baru dan menyiapkannya untuk pelengkapan otomatis, tentukan fungsi yang disebut _complete_my_arg_type . Fungsi ini harus tersedia untuk skrip init.sh , sehingga harus didefinisikan sebelum . init.sh baris . init.sh

Fungsi penyelesaian seharusnya menambahkan sarannya ke array COMP_REPLIES global. Mereka mendapatkan kata saat ini sebagai parameter untuk kenyamanan, tetapi Anda juga dapat menggunakan variabel global COMP_LINE dan COMP_POINT , sama seperti di semua skrip penyelesaian bash.

Berikut adalah cara mendefinisikan tipe argumen file :

 _complete_file () {

    # $1 is the word being typed that we want to complete.
    for file in " ${1-} " * ; do
        # add each file to the completion candidates.
        COMP_REPLIES+=( " $file " )
    done
}