आर्ग्स

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है एक ऐसा ऑब्जेक्ट जो मेमोरी को कम करने के तरीके से इनकैप्सुलेट करता है. इसमें कमांड लाइन का कोई हिस्सा या पूरा हिस्सा बनाने के लिए ज़रूरी डेटा को शामिल किया जाता है.

अक्सर ऐसा होता है कि किसी कार्रवाई के लिए एक बड़ी कमांड लाइन की ज़रूरत होती है, जिसमें ट्रांज़िटिव डिपेंडेंसी से इकट्ठा की गई वैल्यू होती हैं. उदाहरण के लिए, एक लिंकर कमांड लाइन, लिंक की जा रही सभी लाइब्रेरी के लिए ज़रूरी हर ऑब्जेक्ट फ़ाइल की सूची बना सकती है. ऐसे ट्रांज़िटिव डेटा को depset में स्टोर करना सबसे सही तरीका है, ताकि उसे एक से ज़्यादा टारगेट शेयर कर सकें. हालांकि, अगर नियम के लेखक को कोई कार्रवाई कमांड लाइन बनाने के लिए, इन डिपसेट को स्ट्रिंग की सूचियों में बदलना पड़ता है, तो वह मेमोरी शेयर करने का यह ऑप्टिमाइज़ेशन खारिज कर देगा.

इसी वजह से, ऐक्शन कंस्ट्रक्शन के फ़ंक्शन, स्ट्रिंग के साथ-साथ Args ऑब्जेक्ट भी स्वीकार करते हैं. हर Args ऑब्जेक्ट, स्ट्रिंग और डेपसेट को जोड़ने की प्रोसेस दिखाता है. साथ ही, यह डेटा में बदलाव करने के लिए वैकल्पिक ट्रांसफ़ॉर्मेशन भी दिखाता है. Args ऑब्जेक्ट, कमांड लाइन कैलकुलेट करने के दौरान, लागू किए जाने वाले फ़ेज़ तक उन डिपसेट को प्रोसेस नहीं करते हैं जिन्हें वे एनकैप्सुलेट करते हैं. इससे, विश्लेषण का चरण पूरा होने तक किसी भी महंगी कॉपी को टालने में मदद मिलती है. ज़्यादा जानकारी के लिए, परफ़ॉर्मेंस ऑप्टिमाइज़ करना पेज देखें.

Args को ctx.actions.args() को कॉल करके बनाया गया है. उन्हें ctx.actions.run() या ctx.actions.run_shell() के arguments पैरामीटर के तौर पर पास किया जा सकता है. Args ऑब्जेक्ट का हर म्यूटेशन, आखिरी कमांड लाइन में वैल्यू जोड़ता है.

map_each सुविधा की मदद से, आइटम को स्ट्रिंग में बदलने का तरीका पसंद के मुताबिक बनाया जा सकता है. अगर आपने map_each फ़ंक्शन नहीं दिया है, तो स्टैंडर्ड कन्वर्ज़न इस तरह से होगा:

  • जो वैल्यू पहले से ही स्ट्रिंग हैं उन्हें वैसी ही रहने दिया जाता है.
  • File ऑब्जेक्ट को उनकी File.path वैल्यू में बदला जाता है.
  • बाकी सभी टाइप को तय नहीं तरीके से स्ट्रिंग में बदल दिया जाता है. इस वजह से, आपको add() को ऐसी वैल्यू पास करने से बचना चाहिए जो स्ट्रिंग या File टाइप की न हों. साथ ही, अगर उन्हें add_all() या add_joined() पर पास किया जाता है, तो आपको एक map_each फ़ंक्शन देना चाहिए.

स्ट्रिंग फ़ॉर्मैटिंग (add*() तरीकों का format, format_each, और format_joined पैरामीटर) का इस्तेमाल करते समय फ़ॉर्मैट टेंप्लेट की व्याख्या, स्ट्रिंग पर %-प्रतिस्थापन की तरह की जाती है. हालांकि, टेंप्लेट में सिर्फ़ एक प्रतिस्थापन प्लेसहोल्डर होना चाहिए और यह %s होना चाहिए. लिटरल प्रतिशत को %% के तौर पर छोड़ा जा सकता है. ऊपर दी गई जानकारी के मुताबिक, वैल्यू को स्ट्रिंग में बदलने के बाद फ़ॉर्मैटिंग लागू होती है.

हर add*() के तरीके का एक वैकल्पिक फ़ॉर्म होता है, जिसमें एक और पोज़िशनल पैरामीटर, "आर्ग का नाम" स्वीकार किया जाता है स्ट्रिंग का इस्तेमाल करें. अगर क्रम खाली हो जाता है, तो add_all और add_joined के लिए अतिरिक्त स्ट्रिंग नहीं जोड़ी जाएगी. उदाहरण के लिए, इसी इस्तेमाल में कमांड लाइन में --foo val1 val2 val3 --bar या सिर्फ़ --bar जोड़ा जा सकता है. यह इस बात पर निर्भर करता है कि दिए गए क्रम में val1..val3 है या खाली है.

अगर कमांड लाइन का साइज़, सिस्टम के तय किए गए सबसे बड़े साइज़ से ज़्यादा बड़ा हो सकता है, तो आर्ग्युमेंट को पैरामीटर फ़ाइलों में डाला जा सकता है. use_param_file() और set_param_file_format() देखें.

उदाहरण: मान लीजिए कि हम कमांड लाइन जनरेट करना चाहते थे: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
हम इस Args ऑब्जेक्ट का इस्तेमाल कर सकते हैं: 
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

सदस्य

जोड़ें

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

इस कमांड लाइन में तर्क जोड़ता है.

पैरामीटर

पैरामीटर ब्यौरा
arg_name_or_value ज़रूरी है
अगर दो पोज़िशनल पैरामीटर पास किए जाते हैं, तो इसे आर्ग्युमेंट के नाम के तौर पर समझा जाता है. किसी भी प्रोसेसिंग के बिना, वैल्यू से पहले आर्ग्युमेंट का नाम जोड़ा जाता है. अगर सिर्फ़ एक पोज़िशनल पैरामीटर पास किया जाता है, तो उसे value के तौर पर समझा जाता है. इसकी जानकारी नीचे दी गई है.
value डिफ़ॉल्ट = अनबाउंड
जोड़ा जाने वाला ऑब्जेक्ट. इसे ऊपर बताए गए स्टैंडर्ड कन्वर्ज़न का इस्तेमाल करके, स्ट्रिंग में बदल दिया जाएगा. इस फ़ंक्शन के लिए कोई map_each पैरामीटर नहीं है, इसलिए value एक स्ट्रिंग या File होना चाहिए. सूची, टपल, डिप्सेट या डायरेक्ट्री File को इस तरीके के बजाय, add_all() या add_joined() को पास किया जाना चाहिए.
format string; or None; डिफ़ॉल्ट = कोई नहीं
फ़ॉर्मैट स्ट्रिंग पैटर्न, जो value के स्ट्रिंगिफ़ाइड वर्शन पर लागू होता है.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

इस कमांड लाइन में एक से ज़्यादा आर्ग्युमेंट जोड़ता है. प्लान लागू करने के दौरान, आइटम को लेज़ी तरीके से प्रोसेस किया जाता है.

ज़्यादातर प्रोसेसिंग, जोड़े जाने वाले आर्ग्युमेंट की सूची में की जाती है. इसके लिए, यह तरीका अपनाएं:

  1. हर डायरेक्ट्री File आइटम को उस डायरेक्ट्री में बार-बार होने वाले सभी File से बदल दिया जाता है.
  2. अगर map_each दिया गया है, तो इसे हर आइटम पर लागू किया जाता है. इसके बाद, नतीजे के तौर पर मिलने वाली स्ट्रिंग की सूचियां बनाई जाती हैं, ताकि शुरुआती आर्ग्युमेंट की सूची बनाई जा सके. नहीं तो, शुरुआती तर्क सूची हर आइटम पर स्टैंडर्ड कन्वर्ज़न लागू करने से मिलती है.
  3. अगर सूची में मौजूद हर आर्ग्युमेंट मौजूद है, तो उसे format_each से फ़ॉर्मैट किया जाता है.
  4. अगर uniquify सही है, तो डुप्लीकेट आर्ग्युमेंट हटा दिए जाते हैं. पहली घटना बरकरार रहती है.
  5. अगर before_each स्ट्रिंग दी जाती है, तो सूची में मौजूद हर आर्ग्युमेंट से पहले, इसे नए आर्ग्युमेंट के तौर पर डाला जाता है. यह इस पॉइंट से जोड़े जाने वाले आर्ग्युमेंट की संख्या को असरदार तरीके से दोगुना कर देता है.
  6. अगर सूची खाली है और omit_if_empty 'सही' (डिफ़ॉल्ट) है, तो आर्ग्युमेंट के नाम और terminate_with पहले और आखिरी आर्ग्युमेंट के तौर पर डाले जाते हैं. हालांकि, यह तब ही डाला जाएगा, जब ये दिए गए होंगे.
ध्यान दें कि खाली स्ट्रिंग ऐसे मान्य आर्ग्युमेंट होती हैं जिन पर प्रोसेसिंग के सभी चरण लागू होते हैं.

पैरामीटर

पैरामीटर ब्यौरा
arg_name_or_values ज़रूरी है
अगर दो पोज़िशनल पैरामीटर पास किए जाते हैं, तो इसे आर्ग्युमेंट के नाम के तौर पर समझा जाता है. किसी भी प्रोसेसिंग के बिना, आर्ग्युमेंट का नाम values से पहले जोड़ा जाता है. अगर omit_if_empty सही है (डिफ़ॉल्ट) और कोई अन्य आइटम नहीं जोड़ा जाता है, तो यह आर्ग्युमेंट नाम नहीं जोड़ा जाएगा (जैसे कि values खाली होने पर या इसके सभी आइटम फ़िल्टर किए गए हों). अगर सिर्फ़ एक पोज़िशनल पैरामीटर पास किया जाता है, तो उसे values के तौर पर समझा जाता है. इसकी जानकारी नीचे दी गई है.
values sequence; or depset; डिफ़ॉल्ट = अनबाउंड
वह सूची, टपल या डिप्सेट, जिनके आइटम जोड़े जाएंगे.
map_each callable; or None; डिफ़ॉल्ट = कोई नहीं
एक ऐसा फ़ंक्शन जो हर आइटम को शून्य या उससे ज़्यादा स्ट्रिंग में बदलता है. इन्हें जोड़ने से पहले प्रोसेस किया जा सकता है. अगर यह पैरामीटर नहीं दिया गया है, तो स्टैंडर्ड कन्वर्ज़न का इस्तेमाल किया जाता है.

फ़ंक्शन को एक या दो पोज़िशनल आर्ग्युमेंट में पास किया जाता है: वह आइटम जिसे बदलना है और उसके बाद वैकल्पिक DirectoryExpander. दूसरा आर्ग्युमेंट तभी पास किया जाएगा, जब दिया गया फ़ंक्शन, उपयोगकर्ता के हिसाब से (पहले से मौजूद नहीं) हो और एक से ज़्यादा पैरामीटर के बारे में बताता हो.

रिटर्न वैल्यू किस तरह की है, यह इस बात पर निर्भर करता है कि आइटम के लिए कितने आर्ग्युमेंट बनाए जाने हैं:

  • सामान्य स्थिति में जब प्रत्येक आइटम एक स्ट्रिंग में बदल जाता है, तो फ़ंक्शन को वह स्ट्रिंग लौटानी चाहिए.
  • अगर आइटम को पूरी तरह से फ़िल्टर करना है, तो फ़ंक्शन None को दिखाएगा.
  • अगर आइटम एक से ज़्यादा स्ट्रिंग में बदल जाता है, तो फ़ंक्शन उन स्ट्रिंग की सूची दिखाता है.
किसी एक स्ट्रिंग या None को लौटाने का असर, लंबाई 1 या लंबाई 0 की सूची जैसा ही होता है. हालांकि, ऐसी सूची बनाने से बचना ज़्यादा आसान और पढ़ने लायक है जहां इसकी ज़रूरत न हो.

आम तौर पर, expand_directories=True सेट होने पर, डायरेक्ट्री वाले आइटम अपने कॉन्टेंट में अपने-आप बड़ा हो जाते हैं. हालांकि, इससे अन्य वैल्यू में मौजूद डायरेक्ट्री का विस्तार नहीं होगा -- उदाहरण के लिए, जब आइटम ऐसे स्ट्रक्चर हैं जिनमें फ़ील्ड के तौर पर डायरेक्ट्री मौजूद हैं. ऐसे में, किसी डायरेक्ट्री की फ़ाइलों को मैन्युअल तरीके से पाने के लिए, DirectoryExpander आर्ग्युमेंट का इस्तेमाल किया जा सकता है.

विश्लेषण के चरण में, विश्लेषण के चरण वाले बड़े डेटा स्ट्रक्चर के अनचाहे रखरखाव से बचने के लिए, map_each फ़ंक्शन को टॉप-लेवल def स्टेटमेंट से एलान करना ज़रूरी है; यह डिफ़ॉल्ट रूप से नेस्ट किया गया फ़ंक्शन बंद नहीं हो सकता.

चेतावनी: print() map_each को कॉल करने के दौरान चलाए गए स्टेटमेंट, कोई आउटपुट नहीं दिखाएंगे.

format_each string; or None; डिफ़ॉल्ट = कोई नहीं
एक वैकल्पिक फ़ॉर्मैट स्ट्रिंग पैटर्न, जो map_each फ़ंक्शन से लौटाए गए हर स्ट्रिंग पर लागू किया जाता है. प्रारूप स्ट्रिंग में ठीक एक '%s' होना चाहिए प्लेसहोल्डर.
before_each string; or None; डिफ़ॉल्ट = कोई नहीं
values से मिले हर तर्क से पहले जोड़ने के लिए एक वैकल्पिक स्ट्रिंग जोड़ी जाती है.
omit_if_empty डिफ़ॉल्ट = सही
अगर सही है, तो अगर values से मिले आर्ग्युमेंट को जोड़ने के लिए कोई आर्ग्युमेंट नहीं जोड़ा जाता, तो आगे की सभी प्रोसेस को रोक दिया जाता है और कमांड लाइन में कोई बदलाव नहीं होता. अगर गलत है, तो आर्ग्युमेंट का नाम और terminate_with दिए जाने पर, उन्हें अब भी जोड़ा जाएगा. भले ही, अन्य आर्ग्युमेंट हों या न हों.
uniquify डिफ़ॉल्ट = गलत
अगर सही है, तो values से मिले डुप्लीकेट आर्ग्युमेंट का इस्तेमाल नहीं किया जाएगा. हर तर्क सिर्फ़ पहली बार दोहराया जाएगा. आम तौर पर, इस सुविधा की ज़रूरत नहीं होती है, क्योंकि डेटा से डुप्लीकेट वैल्यू हटा दी जाती हैं. हालांकि, अगर map_each एक से ज़्यादा आइटम के लिए एक ही स्ट्रिंग का उत्सर्जन करता है, तो यह मददगार हो सकती है.
expand_directories डिफ़ॉल्ट = सही
अगर सही है, तो values की सभी डायरेक्ट्री को फ़ाइलों की फ़्लैट सूची में बड़ा कर दिया जाएगा. यह map_each लागू होने से पहले होता है.
terminate_with string; or None; डिफ़ॉल्ट = कोई नहीं
दूसरे सभी आर्ग्युमेंट के बाद जोड़ने के लिए वैकल्पिक स्ट्रिंग. अगर omit_if_empty 'सही है' (डिफ़ॉल्ट) पर सेट है और कोई अन्य आइटम नहीं जोड़ा गया है, तो यह स्ट्रिंग नहीं जोड़ी जाएगी. ऐसा तब होता है, जब values खाली हो या इसके सभी आइटम फ़िल्टर कर दिए गए हों.
allow_closure डिफ़ॉल्ट = गलत
अगर सही है, तो map_each जैसे फ़ंक्शन पैरामीटर में, 'बंद है' सेटिंग के इस्तेमाल की अनुमति देता है. आम तौर पर, यह ज़रूरी नहीं होता. इससे, विश्लेषण के चरण के दौरान, विश्लेषण वाले चरण के डेटा स्ट्रक्चर को बनाए रखने का जोखिम रहता है.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

सेपरेटर का इस्तेमाल करके, एक से ज़्यादा वैल्यू को जोड़कर, इस कमांड लाइन में आर्ग्युमेंट जोड़ा जाता है. प्लान लागू करने के दौरान, आइटम को लेज़ी तरीके से प्रोसेस किया जाता है.

प्रोसेसिंग add_all() की तरह है. हालांकि, values से मिले आर्ग्युमेंट की सूची को join_with.join(...) की तरह एक आर्ग्युमेंट में जोड़ दिया जाता है और फिर दिए गए format_joined स्ट्रिंग टेंप्लेट का इस्तेमाल करके फ़ॉर्मैट किया जाता है. add_all() के उलट, कोई before_each या terminate_with पैरामीटर नहीं होता, क्योंकि जब आइटम को किसी एक आर्ग्युमेंट में जोड़ा जाता है, तो ये आम तौर पर काम के नहीं होते.

अगर फ़िल्टर करने के बाद, तर्क में शामिल करने के लिए कोई स्ट्रिंग नहीं होती और अगर omit_if_empty सही (डिफ़ॉल्ट) पर सेट है, तो प्रोसेस नहीं की जाती. ऐसा नहीं करने पर, अगर जुड़ने के लिए कोई स्ट्रिंग नहीं है, लेकिन omit_if_empty गलत है, तो जोड़ी गई स्ट्रिंग एक खाली स्ट्रिंग होगी.

पैरामीटर

पैरामीटर ब्यौरा
arg_name_or_values ज़रूरी है
अगर दो पोज़िशनल पैरामीटर पास किए जाते हैं, तो इसे आर्ग्युमेंट के नाम के तौर पर समझा जाता है. किसी भी प्रोसेसिंग के बिना, आर्ग्युमेंट का नाम values से पहले जोड़ा जाता है. अगर omit_if_empty 'सही है' (डिफ़ॉल्ट) पर सेट है, तो यह आर्ग्युमेंट नहीं जोड़ा जाएगा. साथ ही, values से एक साथ जुड़ने के लिए कोई स्ट्रिंग नहीं है (ऐसा तब हो सकता है, जब values खाली हो या इसके सभी आइटम फ़िल्टर किए गए हों). अगर सिर्फ़ एक पोज़िशनल पैरामीटर पास किया जाता है, तो उसे values के तौर पर समझा जाता है. इसकी जानकारी नीचे दी गई है.
values sequence; or depset; डिफ़ॉल्ट = अनबाउंड
वह सूची, टपल या डिप्सेट, जिनके आइटम जोड़े जाएंगे.
join_with ज़रूरी है
डेलिमिटर स्ट्रिंग का इस्तेमाल map_each और format_each को लागू करने से मिली स्ट्रिंग को string.join() की तरह ही जोड़ने के लिए किया जाता है.
map_each callable; or None; डिफ़ॉल्ट = कोई नहीं
add_all के लिए भी वैसा ही है.
format_each string; or None; डिफ़ॉल्ट = कोई नहीं
add_all के लिए भी वैसा ही है.
format_joined string; or None; डिफ़ॉल्ट = कोई नहीं
जोड़ी गई स्ट्रिंग पर एक वैकल्पिक फ़ॉर्मैट स्ट्रिंग पैटर्न लागू किया गया. प्रारूप स्ट्रिंग में ठीक एक '%s' होना चाहिए प्लेसहोल्डर.
omit_if_empty डिफ़ॉल्ट = सही
अगर सही है, तो एक साथ जोड़ने के लिए कोई स्ट्रिंग न हो (ऐसा इसलिए, क्योंकि values खाली है या उसके सभी आइटम फ़िल्टर किए गए हैं), तो आगे की सभी प्रोसेस को रोक दिया जाता है और कमांड लाइन में कोई बदलाव नहीं होता. अगर गलत है, तो भले ही एक साथ जोड़ने के लिए कोई स्ट्रिंग न हो, तब भी दो आर्ग्युमेंट जोड़ दिए जाएंगे: आर्ग्युमेंट के नाम के बाद एक खाली स्ट्रिंग (जो शून्य स्ट्रिंग का लॉजिकल जुड़ना होता है).
uniquify डिफ़ॉल्ट = गलत
add_all के बराबर ही.
expand_directories डिफ़ॉल्ट = सही
add_all के बराबर ही.
allow_closure डिफ़ॉल्ट = गलत
add_all के बराबर ही.

set_param_file_format

Args Args.set_param_file_format(format)

अगर किसी पैरामीटर फ़ाइल का इस्तेमाल किया जाता है, तो यह पैरामीटर फ़ाइल का फ़ॉर्मैट सेट करता है अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है

पैरामीटर

पैरामीटर ब्यौरा
format ज़रूरी है
इनमें से एक होना चाहिए:
  • "multiline": हर आइटम (तर्क का नाम या वैल्यू) पैरामीटर फ़ाइल में हूबहू लिखे जाते हैं जिनके बाद एक न्यूलाइन वर्ण होता है.
  • "shell": "मल्टीलाइन" की तरह, लेकिन आइटम शेल की तरह कोट किए जाते हैं
  • "flag_per_line": "multiline" की तरह, लेकिन (1) सिर्फ़ फ़्लैग ('--' से शुरू होने वाले) पैरामीटर फ़ाइल पर लिखे जाते हैं और (2) अगर फ़्लैग की कोई वैल्यू है, तो उसकी वैल्यू '=' सेपरेटर. यह Abseil फ़्लैग लाइब्रेरी के लिए अपेक्षित प्रारूप है.

यह फ़ॉर्मैट डिफ़ॉल्ट रूप से "शेल" होता है अगर कॉल नहीं किया जाता.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

आर्ग को किसी पैरामीटर फ़ाइल पर ले जाता है और उनकी जगह पैरामीटर फ़ाइल का पॉइंटर रखता है. इसका इस्तेमाल तब करें, जब आपके आर्ग, सिस्टम के कमांड की लंबाई के हिसाब से बहुत बड़े हों.

बेज़ल, बेहतर तरीके से काम करने के लिए, आउटपुट ट्री में पैरामीटर फ़ाइल को लिखने से बचने का विकल्प चुन सकता है. अगर कार्रवाइयों को डीबग किया जा रहा है और आपको पैरामीटर फ़ाइल की जांच करनी है, तो अपने बिल्ड में --materialize_param_files को पास करें.

पैरामीटर

पैरामीटर ब्यौरा
param_file_arg ज़रूरी है
सिंगल "%s" वाली फ़ॉर्मैट स्ट्रिंग. अगर आर्ग्युमेंट किसी पैरामीटर फ़ाइल में दिए जाते हैं, तो उन्हें पैरामीटर फ़ाइल के पाथ के साथ फ़ॉर्मैट की गई इस स्ट्रिंग वाले आर्ग्युमेंट से बदल दिया जाता है.

उदाहरण के लिए, अगर आर्ग्युमेंट को किसी params फ़ाइल "params.txt" में, फिर "--file=%s" तय करना हो इससे कार्रवाई कमांड लाइन में "--file=params.txt" हो जाएगा.

use_always डिफ़ॉल्ट = गलत
क्या हमेशा params फ़ाइल में आर्ग्युमेंट को बांटना है. अगर गलत है, तो बेज़ल यह तय करेगा कि आपके सिस्टम और आर्ग्युमेंट की लंबाई के हिसाब से, आर्ग्युमेंट को बांटने की ज़रूरत है या नहीं.