Elixir 1.7

OptionParser




elixir

OptionParser

इस मॉड्यूल में कमांड लाइन विकल्पों को पार्स करने के लिए कार्य शामिल हैं।

सारांश

प्रकार

argv()
errors()
options()
parsed()

कार्य

अगला (argv, opts \\ [])

निम्न-स्तरीय फ़ंक्शन जो एक विकल्प को पार्स करता है

पार्स! (argv, opts \\ [])

यदि कोई अमान्य विकल्प दिया जाता है, तो parse/2 जैसा ही, लेकिन OptionParser.ParseError अपवाद को उठाता है

parse/2

Parses एक कीवर्ड सूची में आता है

parse_head! (argv, opts \\ [])

यदि कोई अमान्य विकल्प दिए गए हैं, तो parse_head/2 जैसा ही है, लेकिन OptionParser.ParseError अपवाद को उठाता है

parse_head/2

parse/2 समान लेकिन केवल argv के सिर को पार्स करता है; जैसे ही यह एक गैर-स्विच पाता है, यह पार्स करना बंद कर देता है

split(string)

argv() विखंडू में एक स्ट्रिंग को विभाजित करता है

to_argv (enum, opts \\ [])

एक महत्वपूर्ण मान प्राप्त करता है और इसे argv() परिवर्तित करता है

प्रकार

argv ()

argv() :: [String.t()]

त्रुटियों ()

errors() :: [{String.t(), String.t() | nil}]

विकल्प ()

options() :: [switches: keyword(), strict: keyword(), aliases: keyword()]

पार्स ()

parsed() :: keyword()

कार्य

अगला (argv, opts \\ [])

next(argv(), options()) ::
  {:ok, key :: atom(), value :: term(), argv()}
  | {:invalid, String.t(), String.t() | nil, argv()}
  | {:undefined, String.t(), String.t() | nil, argv()}
  | {:error, argv()}

निम्न-स्तरीय फ़ंक्शन जो एक विकल्प को पार्स करता है।

यह parse/2 और parse_head/2 के समान विकल्पों को स्वीकार करता है क्योंकि दोनों फ़ंक्शन इस फ़ंक्शन के शीर्ष पर बनाए गए हैं। यह फ़ंक्शन वापस आ सकता है:

  • {:ok, key, value, rest} - value साथ विकल्प key को सफलतापूर्वक पार्स किया गया था

  • {:invalid, key, value, rest} - विकल्प key value साथ अमान्य है (जब स्विच प्रकार के अनुसार मान पार्स नहीं किया जा सकता है)

  • {:undefined, key, value, rest} - विकल्प key अपरिभाषित है (सख्त मोड में लौटी है जब स्विच अज्ञात है या किसी भी अकारण परमाणुओं पर)

  • {:error, rest} - दिए गए argv के सिर पर कोई स्विच नहीं हैं

पार्स! (argv, opts \\ [])

parse!(argv(), options()) :: {parsed(), argv()} | no_return()

यदि कोई अमान्य विकल्प दिया जाता है, तो parse/2 जैसा ही, लेकिन OptionParser.ParseError अपवाद को उठाता है।

यदि कोई त्रुटि नहीं है, तो एक {parsed, rest} टपल लौटाएं जहां:

  • parsed किए गए स्विच की सूची है ( parse/2 )
  • rest तर्क की सूची है ( parse/2 रूप में)

उदाहरण

iex> OptionParser.parse!(["--debug", "path/to/file"], strict: [debug: :boolean])
{[debug: true], ["path/to/file"]}

iex> OptionParser.parse!(["--limit", "xyz"], strict: [limit: :integer])
** (OptionParser.ParseError) 1 error found!
--limit : Expected type integer, got "xyz"

iex> OptionParser.parse!(["--unknown", "xyz"], strict: [])
** (OptionParser.ParseError) 1 error found!
--unknown : Unknown option

iex> OptionParser.parse!(["-l", "xyz", "-f", "bar"],
...>                     switches: [limit: :integer, foo: :integer], aliases: [l: :limit, f: :foo])
** (OptionParser.ParseError) 2 errors found!
-l : Expected type integer, got "xyz"
-f : Expected type integer, got "bar"

पार्स (argv, opts \\ [])

parse(argv(), options()) :: {parsed(), argv(), errors()}

Parses एक कीवर्ड सूची में आता है।

यह फॉर्म {parsed, args, invalid} साथ एक तीन-तत्व टपल लौटाता है, जहाँ:

  • parsed की गई {switch_name, value} साथ पार्स किए गए स्विच की एक कीवर्ड सूची है; switch_name स्विच नाम का प्रतिनिधित्व करने वाला परमाणु है, जबकि value उस स्विच के लिए मूल्य है, जो कि opts अनुसार पार्स किया गया है (अधिक जानकारी के लिए "उदाहरण" अनुभाग देखें)
  • argv स्ट्रिंग्स के रूप में argv में शेष तर्कों की एक सूची है
  • invalid अमान्य विकल्पों की एक सूची है जैसे कि {option_name, value} जहाँ option_name कच्चा विकल्प है और value nil यदि विकल्प की अपेक्षा नहीं की गई थी या स्ट्रिंग मान यदि इसी विकल्प के लिए अपेक्षित प्रकार नहीं था।

अमृत ​​स्विच को --source-path परमाणुओं में परिवर्तित करता है, इसलिए - --source-path बन जाता है :source_path यह एलिक्सिर सम्मेलनों को बेहतर बनाने के लिए किया जाता है। हालाँकि, इसका मतलब है कि स्विच में अंडरस्कोर नहीं हो सकते हैं और जो अंडरस्कोर होते हैं, वे हमेशा अमान्य स्विच की सूची में वापस आ जाते हैं।

पार्स करते समय, स्विच और उनके अपेक्षित प्रकारों की सूची बनाना आम है:

iex> OptionParser.parse(["--debug"], strict: [debug: :boolean])
{[debug: true], [], []}

iex> OptionParser.parse(["--source", "lib"], strict: [source: :string])
{[source: "lib"], [], []}

iex> OptionParser.parse(["--source-path", "lib", "test/enum_test.exs", "--verbose"],
...>                    strict: [source_path: :string, verbose: :boolean])
{[source_path: "lib", verbose: true], ["test/enum_test.exs"], []}

हम नीचे विकल्प पार्सर के मान्य स्विच और ऑपरेशन मोड का पता लगाएंगे।

विकल्प

निम्नलिखित विकल्प समर्थित हैं:

  • :switches या :strict - नीचे "स्विच परिभाषा" खंड देखें
  • :allow_nonexistent_atoms - नीचे "पार्सिंग अज्ञात स्विचेस" अनुभाग देखें
  • :aliases - नीचे "उपनाम" अनुभाग देखें

परिभाषाएँ स्विच करें

स्विच को दो विकल्पों में से एक के माध्यम से निर्दिष्ट किया जा सकता है:

  • :strict - सख्त स्विच को परिभाषित करता है। argv में कोई भी स्विच जो सूची में निर्दिष्ट नहीं है, अमान्य विकल्प सूची में वापस आ गया है।
  • :switches - कुछ स्विच और उनके प्रकार को परिभाषित करता है। यह फ़ंक्शन अभी भी स्विच को पार्स करने का प्रयास करता है जो इस सूची में नहीं हैं।

ये दोनों विकल्प {name, type} tuples की एक कीवर्ड सूची को स्वीकार करते हैं जहां name स्विच का नाम परिभाषित करने वाला एक परमाणु है और type एक परमाणु है जो इस स्विच के मान के लिए प्रकार निर्दिष्ट करता है (नीचे दिए गए "प्रकार" अनुभाग देखें) संभव प्रकार और टाइप कास्टिंग के बारे में अधिक जानकारी)।

ध्यान दें कि आपको केवल :switches या :strict विकल्प की आपूर्ति करनी चाहिए। यदि आप दोनों की आपूर्ति करते हैं, तो एक ArgumentError अपवाद उठाया जाएगा।

प्रकार

OptionParser द्वारा पार्स किए गए स्विच में शून्य या एक तर्क हो सकता है।

निम्न स्विच प्रकार कोई तर्क नहीं लेते हैं:

  • :boolean - दिए जाने पर मान को true सेट करता है (नीचे "नकारात्मक स्विच" अनुभाग भी देखें)
  • :count - गणना स्विच दिए जाने की संख्या की संख्या बताती है

निम्नलिखित स्विच एक तर्क लेते हैं:

  • :integer - :integer रूप में मान को पार्स करता है
  • :float - एक फ्लोट के रूप में मान को पार्स करता है
  • :string - एक स्ट्रिंग के रूप में मान को पार्स करता है

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

संशोधक

स्विच को संशोधक के साथ निर्दिष्ट किया जा सकता है, जो बदलते हैं कि वे कैसे व्यवहार करते हैं। निम्नलिखित संशोधक समर्थित हैं:

  • :keep - उन्हें ओवरराइड करने के बजाय डुप्लिकेट आइटम रखता है; छोड़कर सभी प्रकार के साथ काम करता है :count switch_name: :keep निर्दिष्ट करना switch_name: :keep मान लें कि प्रकार :switch_name होगा :string

उपयोग करने के लिए :keep :string अलावा किसी अन्य प्रकार के साथ :keep स्विच के प्रकार के रूप में एक सूची का उपयोग करें। उदाहरण के लिए: [foo: [:integer, :keep]]

नकारात्मक स्विच

यदि स्विच SWITCH में टाइप करने के लिए निर्दिष्ट किया जाता है :boolean , तो इसे पास किया जा सकता है --no-SWITCH साथ ही जो विकल्प को false सेट करेगा:

iex> OptionParser.parse(["--no-op", "path/to/file"], switches: [op: :boolean])
{[op: false], ["path/to/file"], []}

अज्ञात स्विच पार्स करना

जब :switches विकल्प दिया जाता है, OptionParser अज्ञात स्विच को पार्स करने का प्रयास करेगा:

iex> OptionParser.parse(["--debug"], switches: [key: :string])
{[debug: true], [], []}

भले ही हमने स्विच की सूची में --debug को निर्दिष्ट नहीं किया है, यह लौटे विकल्पों का हिस्सा है। यह भी काम करेगा:

iex> OptionParser.parse(["--debug", "value"], switches: [key: :string])
{[debug: "value"], [], []}

एक मूल्य के बाद स्विच को एक स्ट्रिंग के रूप में मान सौंपा जाएगा। बिना तर्क के स्विच स्वचालित रूप से true सेट हो जाएंगे। चूंकि हम स्विच मूल्य के प्रकार को मुखर नहीं कर सकते हैं, इसलिए इसका उपयोग करना पसंद किया जाता है :strict विकल्प जो केवल ज्ञात स्विच को स्वीकार करता है और हमेशा उनके प्रकारों को सत्यापित करता है।

यदि आप अज्ञात स्विच को पार्स करना चाहते हैं, तो याद रखें कि एलिक्सिर स्विच को परमाणुओं में परिवर्तित करता है। चूंकि परमाणु कचरा-एकत्र नहीं होते हैं, OptionParser केवल स्विच को पार्स करेगा जो कि परमाणुओं को लीक करने से बचने के लिए रनटाइम द्वारा उपयोग किए जाने वाले परमाणुओं में अनुवाद करता है। उदाहरण के लिए, नीचे दिया गया कोड --option-parser-example switch को छोड़ देगा क्योंकि :option_parser_example परमाणु कभी भी कहीं भी उपयोग नहीं किया जाता है:

OptionParser.parse(["--option-parser-example"], switches: [debug: :boolean])
# The :option_parser_example atom is not used anywhere below

हालाँकि, नीचे दिया गया कोड तब तक काम करेगा जब तक :option_parser_example परमाणु का उपयोग किसी बिंदु पर बाद में (या पहले) एक ही मॉड्यूल में किया जाता है :

{opts, _, _} = OptionParser.parse(["--option-parser-example"], switches: [debug: :boolean])
opts[:option_parser_example]

दूसरे शब्दों में, एलिक्सिर सही काम करेगा और केवल पार्स विकल्प जो रनटाइम द्वारा उपयोग किए जाते हैं, अन्य सभी को अनदेखा करते हैं। यदि आप सभी स्विच को पार्स करना चाहते हैं, भले ही वे मौजूद हों या नहीं, आप अनुमति के रूप में परमाणुओं के निर्माण को बाध्य कर सकते हैं allow_nonexistent_atoms: true विकल्प के रूप में allow_nonexistent_atoms: true । इस विकल्प का उपयोग सावधानी से करें। यह केवल तब उपयोगी होता है जब आप कमांड-लाइन अनुप्रयोगों का निर्माण कर रहे होते हैं जो गतिशील रूप से नामित तर्क प्राप्त करते हैं और लंबे समय तक चलने वाली प्रणालियों में इससे बचा जाना चाहिए।

उपनाम

उपनाम का एक सेट में निर्दिष्ट किया जा सकता है :aliases विकल्प:

iex> OptionParser.parse(["-d"], aliases: [d: :debug], strict: [debug: :boolean])
{[debug: true], [], []}

उदाहरण

यहाँ विभिन्न प्रकार और संशोधक के साथ काम करने के कुछ उदाहरण दिए गए हैं:

iex> OptionParser.parse(["--unlock", "path/to/file"], strict: [unlock: :boolean])
{[unlock: true], ["path/to/file"], []}

iex> OptionParser.parse(["--unlock", "--limit", "0", "path/to/file"],
...>                    strict: [unlock: :boolean, limit: :integer])
{[unlock: true, limit: 0], ["path/to/file"], []}

iex> OptionParser.parse(["--limit", "3"], strict: [limit: :integer])
{[limit: 3], [], []}

iex> OptionParser.parse(["--limit", "xyz"], strict: [limit: :integer])
{[], [], [{"--limit", "xyz"}]}

iex> OptionParser.parse(["--verbose"], switches: [verbose: :count])
{[verbose: 1], [], []}

iex> OptionParser.parse(["-v", "-v"], aliases: [v: :verbose], strict: [verbose: :count])
{[verbose: 2], [], []}

iex> OptionParser.parse(["--unknown", "xyz"], strict: [])
{[], ["xyz"], [{"--unknown", nil}]}

iex> OptionParser.parse(["--limit", "3", "--unknown", "xyz"],
...>                    switches: [limit: :integer])
{[limit: 3, unknown: "xyz"], [], []}

iex> OptionParser.parse(["--unlock", "path/to/file", "--unlock", "path/to/another/file"], strict: [unlock: :keep])
{[unlock: "path/to/file", unlock: "path/to/another/file"], [], []}

parse_head! (argv, opts \\ [])

parse_head!(argv(), options()) :: {parsed(), argv()} | no_return()

यदि कोई अमान्य विकल्प दिए गए हैं, तो parse_head/2 समान है, लेकिन OptionParser.ParseError अपवाद को उठाता है।

यदि कोई त्रुटि नहीं है, तो एक {parsed, rest} टपल लौटाएं जहां:

  • parsed किए गए स्विच की सूची है ( parse_head/2 )
  • rest तर्कों की सूची है ( parse_head/2 में समान)

उदाहरण

iex> OptionParser.parse_head!(["--source", "lib", "path/to/file", "--verbose"],
...>                         switches: [source: :string, verbose: :boolean])
{[source: "lib"], ["path/to/file", "--verbose"]}

iex> OptionParser.parse_head!(["--number", "lib", "test/enum_test.exs", "--verbose"],
...>                          strict: [number: :integer])
** (OptionParser.ParseError) 1 error found!
--number : Expected type integer, got "lib"

iex> OptionParser.parse_head!(["--verbose", "--source", "lib", "test/enum_test.exs", "--unlock"],
...>                          strict: [verbose: :integer, source: :integer])
** (OptionParser.ParseError) 2 errors found!
--verbose : Missing argument of type integer
--source : Expected type integer, got "lib"

parse_head (argv, opts \\ [])

parse_head(argv(), options()) :: {parsed(), argv(), errors()}

parse/2 समान लेकिन केवल argv के सिर को पार्स करता है; जैसे ही यह एक गैर-स्विच पाता है, यह पार्स करना बंद कर देता है।

अधिक जानकारी के लिए parse/2 देखें।

उदाहरण

iex> OptionParser.parse_head(["--source", "lib", "test/enum_test.exs", "--verbose"],
...>                         switches: [source: :string, verbose: :boolean])
{[source: "lib"], ["test/enum_test.exs", "--verbose"], []}

iex> OptionParser.parse_head(["--verbose", "--source", "lib", "test/enum_test.exs", "--unlock"],
...>                         switches: [source: :string, verbose: :boolean, unlock: :boolean])
{[verbose: true, source: "lib"], ["test/enum_test.exs", "--unlock"], []}

विभाजन (स्ट्रिंग)

split(String.t()) :: argv()

argv() विखंडू में एक स्ट्रिंग को विभाजित करता है।

यह फ़ंक्शन दिए गए string को कई गोले के समान तरीके से स्ट्रिंग की सूची में विभाजित करता है।

उदाहरण

iex> OptionParser.split("foo bar")
["foo", "bar"]

iex> OptionParser.split("foo \"bar baz\"")
["foo", "bar baz"]

to_argv (enum, opts \\ [])

to_argv(Enumerable.t(), options()) :: argv()

एक महत्वपूर्ण मान प्राप्त करता है और इसे argv() परिवर्तित करता है।

कुंजी में परमाणु होने चाहिए। nil मान के साथ कुंजियों को छोड़ दिया जाता है, बूलियन मान को --key या --key --no-key (यदि मान true या false , क्रमशः) में परिवर्तित किया जाता है, और अन्य सभी मानों को Kernel.to_string/1 उपयोग किया Kernel.to_string/1

parse/2 को दिए गए options में से एक ही सेट to_argv/2 को पास करने की सलाह दी जाती है। कुछ स्विच को केवल हाथ में switches जानकारी के साथ सही तरीके से फिर से बनाया जा सकता है।

उदाहरण

iex> OptionParser.to_argv(foo_bar: "baz")
["--foo-bar", "baz"]
iex> OptionParser.to_argv(bool: true, bool: false, discarded: nil)
["--bool", "--no-bool"]

कुछ स्विच स्विच ध्वज के आधार पर विभिन्न मूल्यों का उत्पादन करेंगे:

iex> OptionParser.to_argv([number: 2], switches: [])
["--number", "2"]
iex> OptionParser.to_argv([number: 2], switches: [number: :count])
["--number", "--number"]