Argp Çözümleyici İşlevleri
Önceki Argp Sonraki
Argp Çözümleyici İşlevleri
Bir struct argp (Argp Çözümleyicisinin Belirtilmesi) yapısının parser alanı ile gösterilen işlev, çözümlenen her seçenek ve argümana verilen yanıt içinde yer alan eylemi tanımlar. Ayrıca, çözümleme sırasında belirli başka noktalarda uygulanacak işlemleri mümkün kılan bir kanca işlev olarak da kullanılır.
Argp çözümleyici işlevleri şöyle bir şeydir:
    error_t çözümleyici (int anahtar, char *argüman, struct argp_state *durum)
Buradaki argümanlar:
anahtar
Çözümlenen her seçenek için, çözümleyici işlevi seçenek vektöründeki seçeneğin key alanındaki anahtar değeri ile çağrılır. çözümleyici işlevi ayrıca, seçenek olmayan argümanlar için ARGP_KEY_ARG gibi özel anahtarlarla da çağrılır.
argüman
Eğer anahtar bir seçenek belirtiyorsa, argüman onun için belirtilmiş değerdir. Hiçbir değer belirtilmemişse öntanımlı değeri sıfırdır. Sadece argüman alanı sıfırdan farklı olan seçenekler bir değer alabilir. OPTION_ARG_OPTIONAL bayrağı belirtilmedikçe bunlar daima bir değer alırlar. Eğer bir değere izin vermeyen bir seçenek için bir değer belirtilmiş bir girdi çözümleniyorsa, çözümleyici çağrısından önce bir hata oluşur.
Eğer anahtar değeri ARGP_KEY_ARG ise, argüman bir seçeneği olmayan argümandır. Diğer özel anahtarlar daima sıfır argüman değerine sahiptir.
durum
durum argümanı, çözümleyici tarafından kullanılmak için o anki çözümleme durumu hakkında bilgi içeren struct argp_state için bir gösterici içerir. Bkz. Argp Çözümleme Durumu.
çözümleyici çağrıldığında, anahtar için uygun eylemi uygular ve başarılı olursa 0 ile döner. anahtar değeri işlev tarafından elde edilemezse, işlev ARGP_ERR_UNKNOWN ile, gerçekten bir hata oluşmuşsa bir unix hata kodu ile döner. Bkz. Hata Kodları.
int ARGP_ERR_UNKNOWN
makro
Argp çözümleyici işlevi anahtar değeri olarak belirtilen değeri tanımıyorsa ya da seçeneği olmayan argümanları (anahtar == ARGP_KEY_ARG) elde etmek için çağrılmamışsa bu argümanlar için ARGP_ERR_UNKNOWN ile döner.
Tipik bir çözümleyici işlev anahtar üzerinde bir switch deyimi kullanır:
error_t
parse_opt (int anahtar, char *arg, struct argp_state *durum)
{
  switch (anahtar)
    {
    case seçenek-anahtarı:
      eylem
      break;
    …
    default:
      return ARGP_ERR_UNKNOWN;
    }
  return 0;
}
Argp Çözümleyici İşlevleri için Özel Anahtarlar
Kullanıcı seçeneklerine karşılık olan anahtar değerlerine ek olarak argp çözümleyici işlevlerinin anahtar argümanında bazı özel değerler de kullanılabilir. Aşağıdaki örnekte argüman ve durum, çözümleyici işlevin argümanlarını ifade eder. Bkz. Argp Çözümleyici İşlevleri.
ARGP_KEY_ARG
Seçeneği olmayan bir komut satırı argümanını belirtmek için argüman bu değere bir gösterici olur.
Çok sayıda argp çözümleyicinin bulunmasından dolayı çok sayıda çözümleyici işlev varsa, belli bir argümanın hangisi tarafından çözümleneceğini bilmek mümkün olmaz. Bu durumda sıfır ya da ARGP_ERR_UNKNOWN dışında bir hata döndürünceye kadar herbiri çağrılır; yine de bir argüman elde edilememişse, argp_parse işlevi başka bir argüman çözümlemesi yapmaksızın başarılı olarak döner.
Bu anahtar için bir çözümleyici işlev başarılı olmuşsa, bu kaydedilir ve ARGP_KEY_NO_ARGS durumu kullanılmaz. Ancak, bir çözümleyici işlev bir argümanı işlerken, durum argümanının next alanını azaltıyorsa, seçenek işlenmemiş varsayılacaktır; bu durumda hala bir seçenek içinde argümanı değiştirme ve onu tekrar işleme sokma imkanı olacaktır.
ARGP_KEY_ARGS
Bir çözümleyici işlev, ARGP_KEY_ARG için ARGP_ERR_UNKNOWN hatası ile dönerse, bu anahtarla benzer anlama sahip ama kalan tüm argümanlar üzerinde etkili olan ARGP_KEY_ARGS anahtarı ile çağrı hemen yinelenir. argüman 0'dır ve argüman vektörünün ucu durum->argv + durum->next ile bulunur. Bu anahtar için işlev başarılı ise ve durum->next değişmemişse, kalan tüm argümanlar tüketilmiş varsayılır. Aksi takdirde, durum->next ile belirtilen miktar kullanılmış olanların sayısına ayarlanır. Örnekte farklı argümannlar için her iki durum da kullanılmıştır:
…
  case ARGP_KEY_ARG:
    if (durum->arg_num == 0)
      /* İlk argüman */
      ilk_arg = arguman;
    else
      /* Sonra çözümlenecek.  */
      return ARGP_KEY_UNKNOWN;
    break;
  case ARGP_KEY_ARGS:
    kalan_argumanlar = durum->argv + durum->next;
    kalan_arg_sayisi = durum->argc - durum->next;
    break;
ARGP_KEY_END
Bu anahtar başka komut satırı kalmadığını belirtir. Çözümleyici işlevler farklı bir sırada (önce children) çağrılır. Bu, her çözümleyici işlevin çağrıcısı için kendi durumunu temizleme imkanı verir.
ARGP_KEY_NO_ARGS
Seçeneği olmayan argümanların yokluğunda bazı özel işlemler ortaktır. Bundan dolayı, eğer çözümleyici işlevde seçeneği olmayan argümanları başarıyla işleme yeteneği yoksa bu işlevler bu anahtarla çağrılır. Bu çağrı, önceden çözümlenmiş argümanlar üzerinde daha genel doğrulama sınamalarının yapılabilmesi için ARGP_KEY_END'li bir çağrıdan önce yapılır.
ARGP_KEY_INIT
Herhangi bir çözümleme yapılmadan önce kullanılır. Bunun ardından, durum yapısının child_input alanının her elemanının değeri, çocuk çözümleyiciler çağrılırken input üyesini ilklendirmek üzere herbirinin durumuna kopyalanır.
ARGP_KEY_SUCCESS
Bazı argümanlar kalsa bile, istenen çözümleme başarıyla tamamlandığında kullanılır.
ARGP_KEY_ERROR
Bir hata oluştuğunda ya da çözümleme tamamlandığında kullanılır. Bu takdirde ARGP_KEY_SUCCESS anahtarlı bir çağrı asla yapılmamalıdır.
ARGP_KEY_FINI
ARGP_KEY_SUCCESS ve ARGP_KEY_ERROR anahtarlı çağrılardan bile sonra kullanılan son anahtar. ARGP_KEY_INIT anahtarlı bir çağrı ile ilklendirilen özkaynaklar bu anahtar kullanılarak yapılan bir çağrı ile serbest bırakılır. Bu sırada, bir başarılı çözümleme sonrası çağrıcıya döndürülen özkaynaklar ayrılmış olarak kalır. Bu durumda, bu özkaynaklar ARGP_KEY_ERROR durumuyla serbest bırakılabilir.
Tüm durumlarda, ARGP_KEY_INIT anahtarı çözümleyici işlev tarafından görülen ilk anahtar; ARGP_KEY_INIT için çözümleyiciden bir hata döndürülmedikçe, ARGP_KEY_FINI ise son anahtardır. Diğer anahtarlar aşağıdaki sıralamalarla görünürler. sçn-anh keyfi bir seçenek anahtarını ifade eder:
sçn-anhARGP_KEY_NO_ARGS ARGP_KEY_END ARGP_KEY_SUCCESS
Çözümlenen argümanlar seçeneği olmayan argümanları içermiyorsa bu sıralama kullanılır.
( sçn-anh | ARGP_KEY_ARG )… ARGP_KEY_END ARGP_KEY_SUCCESS
Seçeneği olamayan argümanları işleme yeteneğine sahip işlev(ler) varsa bu sıralama kullanılır. Çok sayıda argp çözümleyici birlikte kullanılıyorsa çok sayıda çözümleyici işlev olabilir.
( sçn-anh | ARGP_KEY_ARG )… ARGP_KEY_SUCCESS
Seçeneği olmayan argümanlardan bilinmeyenler varsa bu sıralama kullanılır.
Çözümleyici işlevlerin hepsi bir argüman için ARGP_KEY_UNKNOWN ile döndüğünde, eğer arg_indisi bir boş gösterici ise çözümleme bu argümanda durdurulur. Aksi takdirde bir hata oluşur.
Tüm durumlarda, argp_parse'a aktarılan boş gösterici olmayan bir arg_indisi için çözümlenmemiş ilk komut satırı argümanı bu gösterici ile döndürülür.
Gerek argp tarafından gerekse bir hata değeri döndüren bir çözümleyici işlev nedeniyle bir hata değeri dönmüşse, her çözümleyici ARGP_KEY_ERROR ile çağrılır. Son çağrı olan ARGP_KEY_FINI anahtarlı çağrı dışında bir çağrı yapılmaz.
Argp Çözümleyicilere Yardımcı İşlevler
Argp arayüzü, çoğunlukla hata iletileri üretmek için argp kullanıcısında kullanmak için bazı işlevler içerir. İlk argüman olarak çözümleyici işlevin durum argümanını alırlar. Bkz. Argp Çözümleme Durumu.
void argp_usage
(const struct argp_state *durum)
işlev
Çözümleyici tarafından durum ile belirtilen standart kullanım iletisini durum->err_stream'e çıktılar ve yazılımı exit (argp_err_exit_status) çağrısı ile sonlandırır. Bkz. Argp Genel Değişkenleri.
void argp_error
(const struct argp_state *durum,
 const char              *biçim,
 …)
işlev
Yazılım isminden sonra bir iki nokta üstüste koyup, ardından biçim ile belirtilen printf biçim dizgesi ve argümanlarını bastıktan sonra buna Try … --help iletisini ekler ve yazılımı argp_err_exit_status durumu ile sonlandırır. Bkz. Argp Genel Değişkenleri.
void argp_failure
(const struct argp_state *durum,
 int                      çıkış-durumu,
 int                      hatanum,
 const char              *biçim,
 …)
işlev
Standart GNU hata raporlama işlevi olan error işlevine benzer. Yazılım isminden sonra bir iki nokta üstüste koyup, ardından biçim ile belirtilen printf biçim dizgesi ve argümanlarını basar. hatanum sıfırdan farklıysa, bu hata durumu ile ilgili standart Unix hata metnini basar. çıkış-durumu sıfırdan farklıysa bu değeri çıkış durumu olarak kullanarak yazılımı sonlandırır.
argp_failure ile argp_error arasındaki fark, argp_error hataların çözümlenmesi için iken, argp_failure çözümleme sırasında oluşan diğer sorunlar içindir, ama kuraldışı değer verilmiş seçenekler, ayın yanlış evrede olması gibi girdi ile ilgili sözdizimsel sorunları ifade etmek için değildir.
void argp_state_help
(const struct argp_state *durum,
 FILE                    *akım,
 unsigned                 bayraklar)
işlev
Çözümleyici tarafından durum ile belirtilen bir yardım iletisini akım'a çıktılar. bayraklar argümanı ile yardım iletisinin hangi sıra ile üretileceği belirtilir. Bkz. argp_help Bayrakları.
Hata çıktısı durum->err_stream'e gönderilir ve basılan yazılım ismi durum->name'dir.
Bu işlevlerin çıktıları ya da sonlandırma davranışları, argp_parse işlevine ARGP_NO_EXIT veya ARGP_NO_ERRS bayrağı aktarılarak baskılanabilir. Bkz. argp_parse Bayrakları.
Bu davranış, argp çözümleyici başka yazılımlar (örn, bir kütüphane) tarafından kullanılmak içinse yararlıdır ve çözümleme hatalarına yanıt olarak yazılımın sonlanmasının istenmediği bir bağlamda kullanılabilir. Bu tür kullanımlar için tasarlanmış argp çözümleyicilerde ve yazılımın sonlanmayacağı durum için bu işlevlerin çağrılarından sonra ilgili hata kodunu döndüren kodlar olmalıdır:
if (argüman sözdizimi hatalı)
  {
     argp_usage (durum);
     return EINVAL;
  }
Eğer bir çözümleyici işlev sadece ARGP_NO_EXIT etkin iken kullanılacaksa, dönmeyebilir.
Argp Çözümleme Durumu
Argp çözümleyici işlevlerinin üçüncü argümanı seçenek çözümleme durumu hakkında bilgi içeren struct argp_state yapısına bir göstericidir.
struct argp_state
veri türü
Bu yapının üyeleri şunlardır (değişiklik yapılabilecek üyeler belirtilmiştir):
const struct argp *const root_argp
Çözümleme için kullanılan en üst seviye argp çözümleyici. Bu çoğunlukla, yazılım tarafından çağrılan argp_parse işlevine aktarılan struct argp ile aynı değildir. Bkz. Argp. Bu, --help gibi argp_parse tarafından gerçeklenmiş seçenekleri içeren dahili argp çözümleyicidir.
int argc
char **argv
Çözümlenecek argüman vektörü. Bu üyenin değeri değiştirilebilir.
int next
Çözümlenecek sonraki argümanın argv içindeki indisi. Bu üyenin değeri değiştirilebilir.
Girdide kalan tüm argümanları tüketmenin tek yolu next alanındaki değeri kaydettikten sonra durum->next = durum->argc ataması yapmaktır. Aynı seçenek bu alanın değeri azaltılarak yeniden çözümlenebilir ve bundan sonra çözümlenecek seçenek durum->argv[durum->next] ile belirtilebilir.
unsigned flags
argp_parse'a aktarılacak bayraklar. Bazı bayraklar sadece argp_parse ilk çağrıldığında etkili olabileceğinden bu üyenin değeri değiştirilebilir. Bkz. argp_parse Bayrakları.
unsigned arg_num
Çözümleyici işlev anahtar argümanında ARGP_KEY_ARG belirtilerek çağrıldığında, bu üye, ilkinin indisi 0 olmak üzere o anki argümanın indisini gösterir. Her ARGP_KEY_ARG'lı çağrıdan sonra değeri bir artar. Bunun dışında, işlenen ARGP_KEY_ARG argümanlarının sayısını içerir.
int quoted
Sıfırdan farklıysa değeri, özel -- argümanından sonraki ilk argv argümanının indisidir. Bu indisten itibaren hiçbir argüman seçenek olarak yorumlanmaz. Bu değer sadece, bu özel seçenekten önce çözümlenmemiş seçenek kalmadığında atanır.
void *input
argp_parse işlevine girdi argümanı ile aktarılan keyfi bir gösterici.
void **child_inputs
Çocuk çözümleyicilere aktarılacak değerleri içerir. Bu vektörün eleman sayısı o anki çözümleyicideki çocukların sayısı ile aynı olacaktır. i bu çözümleyicinin children alanındaki çocuk çözümleyicinin indisi olmak üzere, durum->child_inputs[i] değeri her çocuk çözümleyicinin durum->input alanının değeri olacaktır. Bkz. Çocuk Çözümleyiciler.
void *hook
Çözümleyici işlevin kullanması içindir. 0 ile ilklendirilir, başka bir değer verilse bile argp tarafından bu değer yok sayılır.
char *name
İletileri basarken kullanılacak isim. Bu üye normalde argv[0] ile ilklendirilir. argv[0] mevcut değilse, program_invocation_name ile ilklendirilir.
FILE *err_stream
FILE *out_stream
Argp arayüzünün iletileri basarken kullandığı standart G/Ç akımları. Hata iletileri err_stream'e, tüm diğer çıktılar (örn, --help çıktısı) out_stream'e çıktılanır. Bunlar sırasıyla stderr ve stdout olarak ilklendirilir. Bkz. Standart Akımlar.
void *pstate
Argp gerçekleniminin kullanımına özeldir.
Önceki Üst Ana Başlık Sonraki
Seçenekler Başlangıç Çocuk Çözümleyiciler
Bir Linux Kitaplığı Sayfası