ArgsOptionParser

public class ArgsOptionParser
extends OptionSetter

java.lang.Object
   ↳ com.android.tradefed.config.OptionSetter
     ↳ com.android.tradefed.config.ArgsOptionParser


הארגומנטים של שורת הפקודה מנותחים ומאכלסים את השדות Option.

מחרוזות במערך String[] ‎ המועברות מתפרקות משמאל לימין. כל מחרוזת מסווגת כאפשרות קצרה (למשל '-v'), אפשרות ארוכה (למשל '‎--verbose'), ארגומנט לאפשרות (למשל 'out.txt' ב-'-f out.txt') או ארגומנט אופוזיציוני לא אופציונלי.

כל ארגומנט של אפשרות צריך להיות ממופה לשדה Option אחד או יותר. אפשרות ארוכה ממופה לשם Option, ואפשרות קצרה ממופה לשם המקוצר Option. כל שם של אפשרות ושם מקוצר של אפשרות חייבים להיות ייחודיים ביחס לכל שדות ה-Option האחרים באותו אובייקט.

אפשר למפות ארגומנט אפשרות יחיד למספר שדות Option עם אותו שם במספר אובייקטים. אפשר להקצות למשתני Option מרחב שמות כדי להפנות באופן ייחודי לשדה Option בתוך אובייקט יחיד באמצעות שם הכיתה המלא של האובייקט או ערך החלופית OptionClass שלו, מופרדים באמצעות ':'. למשל:

 --classname:optionname optionvalue or
 --optionclassalias:optionname optionvalue.
 

אפשרות קצרה פשוטה היא "-" ואחריה תו של אפשרות קצרה. אם האפשרות דורשת ארגומנט (זה נכון לכל אפשרות שאינה בוליאנית), אפשר לכתוב אותה כפרמטר נפרד, אבל לא חייבים. כלומר, אפשר להשתמש גם ב-"-f out.txt" וגם ב-"-fout.txt".

אפשר לציין כמה אפשרויות קצרות אחרי סימן "-" יחיד, כל עוד כולן (חוץ מהאפשרות האחרונה, אולי) לא דורשות ארגומנטים.

אפשרות ארוכה מתחילה ב-'--' ואחריה כמה תווים. אם האפשרות דורשת ארגומנט, אפשר לכתוב אותו ישירות אחרי שם האפשרות, מפריד אותו ב-"=" או כארגומנט הבא. (כלומר, '‎--file=out.txt' או '‎--file out.txt').

אפשרות ארוכה בוליאנית '‎--name' מקבלת באופן אוטומטי אפשרות '‎--no-name'. אם נותנים את האפשרות '‎--flag', כל הערכים הבאים תקפים: ‎--flag,‏ ‎--no-flag,‏ ‎--flag=true ו-‎--flag=false. עם זאת, הערכים ‎--flag true ו-‎--flag false אסורים (מכיוון ש-‎-flag לבדו מספיק, הערך 'true' או 'false' הבא מפורש בנפרד). אפשר להשתמש ב-'yes' וב-'no' כמילים נרדפות ל-'true' ול-'false'.

כל מחרוזת שלא מתחילה ב-‎- ולא ארגומנט נדרש של אפשרות קודמת היא ארגומנט אופציונלי תלויי מיקום, וכך גם כל המחרוזות הבאות. כל מחרוזת אחרי הסימן '--' היא ארגומנט אופציונלי תלויי מיקום.

השדות התואמים לאפשרויות מתעדכנים כשהאפשרויות שלהם עוברות עיבוד. כל שאר הארגומנטים המיקומיים מוחזרים כ-List<String>.

הנה דוגמה פשוטה:

 // Non-@Option fields will be ignored.
 class Options {
     @Option(name = "quiet", shortName = 'q')
     boolean quiet = false;

     // Here the user can use --no-color.
     @Option(name = "color")
     boolean color = true;

     @Option(name = "mode", shortName = 'm')
     String mode = "standard; // Supply a default just by setting the field.

     @Option(name = "port", shortName = 'p')
     int portNumber = 8888;

     // There's no need to offer a short name for rarely-used options.
     @Option(name = "timeout" )
     double timeout = 1.0;

     @Option(name = "output-file", shortName = 'o' })
     File output;

     // Multiple options are added to the collection.
     // The collection field itself must be non-null.
     @Option(name = "input-file", shortName = 'i')
     List<File> inputs = new ArrayList<File>();

 }

 Options options = new Options();
 List<String> posArgs = new OptionParser(options).parse("--input-file", "/tmp/file1.txt");
 for (File inputFile : options.inputs) {
     if (!options.quiet) {
        ...
     }
     ...

 }

 
מידע נוסף:
  • דף העזרה getopt(1)
  • המודול optparse של Python‏ (http://docs.python.org/library/optparse.html)
  • "הנחיות לסינטקס של כלי שירות" של POSIX (http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap12.html#tag_12_02)
  • 'הסטנדרטים של ממשקי שורת הפקודה' של GNU‏ (http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces)

מידע נוסף:

סיכום

קונסטרוקטורים גלויים לכולם

ArgsOptionParser( optionSources)

יצירת ArgsOptionParser לאוסף של אובייקטים.

ArgsOptionParser(Object... optionSources)

יצירת ArgsOptionParser לאובייקט אחד או יותר.

שיטות ציבוריות

getInopOptions()

הפונקציה מחזירה את קבוצת האפשרויות שלא השתנו בהן ערכי ברירת מחדל.

static String getOptionHelp(boolean importantOnly, Object optionObject)

הפלט של טקסט העזרה לכל השדות Option ב-optionObject.

parse(String... args)

הפונקציה מפענחת את הארגומנטים של שורת הפקודה 'args', ומגדירה את השדות של @Option ב-'optionSource' שסופק ל-constructor.

parse( args)

שיטה חלופית של parse(String) שמקבלת ERROR(/List) של ארגומנטים

parseBestEffort( args)

שיטה חלופית parseBestEffort(String) עם ERROR(/List) של ארגומנטים

parseBestEffort( args, boolean forceContinue)

שיטה חלופית של parseBestEffort(String) שמקבלת ERROR(/List) של ארגומנטים, ואפשר לאלץ אותה להמשיך לנתח עד הסוף, גם אם חלק מהארגומנטים לא ניתנים לניתוח.

parseBestEffort(String... args)

גרסה של parse(String) שמבוססת על הניסיון שלנו.

void validateMandatoryOptions()

אימות של כל השדות שסומנו כחובה.

קונסטרוקטורים גלויים לכולם

ArgsOptionParser

public ArgsOptionParser ( optionSources)

יצירת ArgsOptionParser לאוסף של אובייקטים.

פרמטרים
optionSources : אובייקטי התצורה.

זריקות
ConfigurationException אם אובייקטים של הגדרות אישיות מוגדרים בצורה שגויה.

ArgsOptionParser

public ArgsOptionParser (Object... optionSources)

יצירת ArgsOptionParser לאובייקט אחד או יותר.

פרמטרים
optionSources Object: אובייקטי התצורה.

זריקות
ConfigurationException אם אובייקטים של הגדרות אישיות מוגדרים בצורה שגויה.

שיטות ציבוריות

getInopOptions

public  getInopOptions ()

הפונקציה מחזירה את קבוצת האפשרויות שלא השתנו בהן ערכי ברירת מחדל.

החזרות

getOptionHelp

public static String getOptionHelp (boolean importantOnly, 
                Object optionObject)

הפלט של טקסט העזרה לכל השדות Option ב-optionObject.

טקסט העזרה של כל אפשרות יהיה בפורמט הבא

   [-option_shortname, --option_name]          [option_description] Default:
   [current option field's value in optionObject]
 
הטקסט 'ברירת מחדל...' יושמט אם שדה האפשרות ריק או שהוא null.

פרמטרים
importantOnly boolean: אם true מודפסת רק עזרה לגבי האפשרויות החשובות

optionObject Object: האובייקט שעבורו רוצים להדפיס את טקסט העזרה

החזרות
String מחרוזת שמכילה טקסט עזרה ידידותי למשתמש לכל שדות האפשרויות

לנתח

public  parse (String... args)

הפונקציה מפענחת את הארגומנטים של שורת הפקודה 'args', ומגדירה את השדות של @Option ב-'optionSource' שסופק ל-constructor.

פרמטרים
args String

החזרות
ERROR(/List) של הארגומנטים תלויי המיקום שנותרו אחרי עיבוד כל האפשרויות.

זריקות
ConfigurationException אם אירעה שגיאה בניתוח הארגומנטים.

לנתח

public  parse ( args)

שיטה חלופית של parse(String) עם ERROR(/List) של ארגומנטים

פרמטרים
args

החזרות
ERROR(/List) של הארגומנטים תלויי המיקום שנותרו אחרי עיבוד כל האפשרויות.

זריקות
ConfigurationException אם אירעה שגיאה בניתוח הארגומנטים.

parseBestEffort

public  parseBestEffort ( args)

שיטה חלופית parseBestEffort(String) עם ERROR(/List) של ארגומנטים

פרמטרים
args

החזרות
ERROR(/List) מהארגומנטים הנותרים

parseBestEffort

public  parseBestEffort ( args, 
                boolean forceContinue)

שיטה חלופית של parseBestEffort(String) שמקבלת ERROR(/List) של ארגומנטים, ואפשר לאלץ אותה להמשיך לנתח עד הסוף, גם אם חלק מהארגומנטים לא ניתנים לניתוח.

פרמטרים
args : רשימה שתכלול את שאר הארגומנטים.

forceContinue boolean: הערך True (נכון) אם יש להמשיך לנתח גם אם חלק מהארגומנטים לא ניתנים לניתוח.

החזרות
ERROR(/List) מהארגומנטים הנותרים

parseBestEffort

public  parseBestEffort (String... args)

גרסה של parse(String) שמבוססת על הניסיון שלנו. אם מתרחשת הטלת ConfigurationException, החריגה מתועדת באופן פנימי והארגומנטים הנותרים (כולל הארגומנט שגרם להטלת החריגה) מוחזרים. השיטה הזו לא גורמת להשלכה.

פרמטרים
args String

החזרות
ERROR(/List) מהארגומנטים הנותרים

validateMandatoryOptions

public void validateMandatoryOptions ()

אימות של כל השדות שסומנו כחובה.

זריקות
com.android.tradefed.config.ConfigurationException
ConfigurationException