Source code: gnu/dtools/ritopt/Option.java
1 package gnu.dtools.ritopt;
2
3 /**
4 * Option.java
5 *
6 * Version
7 * $Id: Option.java,v 1.3 2001/10/19 05:40:31 googolminex Exp $
8 */
9
10 import java.util.*;
11
12 /**
13 * This is the principal base class for all Option classes. It contains
14 * constructors for short and long option initialization, utility members
15 * for help reporting and file writing, and deprecation facilities.<p>
16 *
17 * Options that provide array support should inherit from the ArrayOption
18 * class, and follow the guidelines defined both in the Option and
19 * ArrayOption class descriptions.<p>
20 *
21 * Non-abstract subclasses should implement the modify method. When an option
22 * is invoked, the value of the option is passed to the modify method.<p>
23 *
24 * Subclasses should provide several constructors so that registration is
25 * simple and uniform. Recommended constructors include a default constructor,
26 * an interface for initialization of short and long options,
27 * and one that allows both short and long option fields to be
28 * initialized. If the subclass implementation provides constructors which
29 * initialize its members then the member parameters must be before
30 * the short and long option initialization parameters.<p>
31 *
32 * Event driven option processing is provided in the NotifyOption class. In
33 * order to use a NotifyOption, the recipient object must implement the
34 * OptionListener class. Although it is not required, subclass implementations
35 * of NotifyOption should implement the OptionNotifier interface.<p>
36 *
37 * By default, the Option class considers the width of an output device
38 * to be eighty characters. It initializes the width of the help fields
39 * based on this figure. If a field exceeds its field width, it is
40 * truncated. The width constraints can be changed by invoking the appropriate
41 * static mutators.<p>
42 *
43 * Similar to the help reporting facilities, the same constraints are placed
44 * on the listing of options provided by the built-in menu interface. These
45 * constraints can be modified by executing the appropriate static mutators.
46 * <p>
47 *
48 * The Option class provides a facility for writing options files.
49 * For option file writing, there are only two field width constraints; the
50 * assignment and the comment.
51 * <pre>
52 * Assignment: Comment:
53 * --longOrShortOption=optionValue ;description goes here [d]
54 * </pre>
55 * As shown above, an assignment includes the long or short option text,
56 * an equal sign, and the option's value. The comment includes the
57 * description, and "[d]" if the option is deprecated.<p>
58 *
59 * If the assignment exceeds its field width, the comment is placed before
60 * the assignment on a separate line. The comment is truncated if it
61 * exceeds eighty characters when it is placed before the assignment.
62 * However, if the assignment does not exceeds its field width and the comment
63 * does, the comment is truncated, and continued on the next line at the
64 * columnar position defined by the assignment's field width. Field widths
65 * may be modified by invoking the appropriate static mutator.<p>
66 *
67 * This class also provides a facility for deprecating options. An option is
68 * deprecated to discourage its use without removing the functionality it
69 * provides. An option is deprecated by invoking the deprecate method.
70 * <hr>
71 *
72 * <pre>
73 * Copyright (C) Damian Ryan Eads, 2001. All Rights Reserved.
74 *
75 * ritopt is free software; you can redistribute it and/or modify
76 * it under the terms of the GNU General Public License as published by
77 * the Free Software Foundation; either version 2 of the License, or
78 * (at your option) any later version.
79
80 * ritopt is distributed in the hope that it will be useful,
81 * but WITHOUT ANY WARRANTY; without even the implied warranty of
82 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
83 * GNU General Public License for more details.
84 *
85 * You should have received a copy of the GNU General Public License
86 * along with ritopt; if not, write to the Free Software
87 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
88 * </pre>
89 *
90 * @author Damian Eads
91 */
92
93 public abstract class Option implements OptionModifiable {
94
95 /**
96 * The default width of the option field when the help usage is displayed.
97 */
98
99 public static final int DEFAULT_HELP_OPTION_SIZE = 15;
100
101 /**
102 * The default width of the type name field when the help usage is
103 * display.
104 */
105
106 public static final int DEFAULT_HELP_TYPENAME_SIZE = 10;
107
108 /**
109 * The default width of the description when the help usage is displayed.
110 */
111
112 public static final int DEFAULT_HELP_DESCRIPTION_SIZE = 48;
113
114 /**
115 * The default width of the deprecated field when the help usage is
116 * displayed.
117 */
118
119 public static final int DEFAULT_HELP_DEPRECATED_SIZE = 3;
120
121 /**
122 * The default width of the option field when the menu usage is displayed.
123 */
124
125 public static final int DEFAULT_MENU_OPTION_SIZE = 15;
126
127 /**
128 * The default width of the type name field when the menu usage is
129 * displayed.
130 */
131
132 public static final int DEFAULT_MENU_TYPENAME_SIZE = 10;
133
134 /**
135 * The default width of the description field when the menu usage is
136 * displayed.
137 */
138
139 public static final int DEFAULT_MENU_DESCRIPTION_SIZE = 48;
140
141 /**
142 * The default width of the deprecated field when the menu usage is
143 * displayed.
144 */
145
146 public static final int DEFAULT_MENU_DEPRECATED_SIZE = 3;
147
148 /**
149 * The default width of the option assignment in an option file.
150 */
151
152 public static final int DEFAULT_FILE_COMPLETE_OPTION_SIZE = 60;
153
154 /**
155 * The default width of the comment in an option file. If the option
156 * and the comment exceeds the width of the device, the comment is
157 * truncated to the next line at the same columnar position of the
158 * previous comment line. If the option assignment line is longer than
159 * the width, the comment line is put before the option assignment it
160 * refers.
161 */
162
163 public static final int DEFAULT_FILE_COMMENT_SIZE = 16;
164
165 /**
166 * The String holding the value of the long option. If there is no
167 * long option, this value is set to null.
168 */
169
170 private String longOption;
171
172 /**
173 * The character holding the value of the short option. If there is no
174 * short option,t his value is set to '\0'.
175 */
176
177 private char shortOption;
178
179 /**
180 * The String holding the description of this option.
181 */
182
183 private String description;
184
185 /**
186 * A flag identifying whether this option is deprecated.
187 */
188
189 private boolean deprecated;
190
191 /**
192 * The field width for the option specification that is reporter for
193 * help.
194 */
195
196 private static int helpOptionSpecificationSize = DEFAULT_HELP_OPTION_SIZE;
197
198 /**
199 * The field width for the type name that is reported for help.
200 */
201
202 private static int helpTypenameSize = DEFAULT_HELP_TYPENAME_SIZE;
203
204 /**
205 * The field width for the description that is reported during help.
206 */
207
208 private static int helpDescriptionSize = DEFAULT_HELP_DESCRIPTION_SIZE;
209
210 /**
211 * The field width for the deprecated flag that is reported during
212 * help.
213 */
214
215 private static int helpDeprecatedSize = DEFAULT_HELP_DEPRECATED_SIZE;
216
217 /**
218 * The field width for the option specification that is reported when
219 * the options are listed in the built-in menu.
220 */
221
222 private static int menuOptionSpecificationSize = DEFAULT_MENU_OPTION_SIZE;
223
224 /**
225 * The field width for the type name that is reported when the options
226 * are listed in the built-in menu.
227 */
228
229 private static int menuTypenameSize = DEFAULT_MENU_TYPENAME_SIZE;
230
231 /**
232 * The field width for the description that is reported when the options
233 * are listed in the built-in menu.
234 */
235
236 private static int menuDescriptionSize = DEFAULT_MENU_DESCRIPTION_SIZE;
237
238 /**
239 * The field width for the deprecated flag that is reported when the
240 * options are listed in the build-in menu.
241 */
242
243 private static int menuDeprecatedSize = DEFAULT_MENU_DEPRECATED_SIZE;
244
245 /**
246 * The field width for the assignment portion of an option that is
247 * written to a file.
248 */
249
250 private static int fileCompleteOptionSize =
251 DEFAULT_FILE_COMPLETE_OPTION_SIZE;
252
253 /**
254 * The field width for the comment portion of an option that is written
255 * to a file.
256 */
257
258 private static int fileCommentSize = DEFAULT_FILE_COMMENT_SIZE;
259
260 /**
261 * A field indicating whether an option has been invoked.
262 */
263
264 protected boolean invoked;
265
266 /**
267 * Returns this option's value as an Object.
268 *
269 * @return An object representation of this option.
270 */
271
272 public abstract Object getObject();
273
274 /**
275 * Returns the option's value as a String. This String should conform
276 * to the formatting requirements prescribed by a modify method.
277 *
278 * @return The option's value as a String conforming to formatting
279 * requirements.
280 */
281
282 public abstract String getStringValue();
283
284 /**
285 * Constructs an option with no initial short or long option value,
286 * and is by default uninvoked and undeprecated, and has a description
287 * initialized to the empty string.
288 */
289
290 public Option() {
291 super();
292 description = "";
293 }
294
295 /**
296 * Constructs an option by copying the option passed.
297 *
298 * @param option The option to copy for this object's construction.
299 */
300
301 public Option( Option option ) {
302 longOption = option.getLongOption();
303 shortOption = option.getShortOption();
304 description = option.getDescription();
305 deprecated = option.isDeprecated();
306 }
307
308 /**
309 * Constructs an option by initializing its long option with the
310 * value passed. The short option is equal to the null character,
311 * and the description is equal to the empty string.
312 *
313 * @param longOption The value of the long option
314 */
315
316 public Option( String longOption ) {
317 this.longOption = longOption;
318 this.shortOption = '\0';
319 description = "";
320 }
321
322 /**
323 * Constructs an option by initializing its short option with the
324 * value passed. The long option is equal to null, and the description
325 * is equal to the empty string.
326 *
327 * @param shortOption The value of the short option.
328 */
329
330 public Option( char shortOption ) {
331 this.shortOption = shortOption;
332 this.longOption = null;
333 description = "";
334 }
335
336 /**
337 * Constructs an option by initializing its short and long options
338 * with the values passed. The description is set to the empty string.
339 *
340 * @param longOption The value of the long option.
341 * @param shortOption The value of the short option.
342 */
343
344 public Option( String longOption, char shortOption ) {
345 this.longOption = longOption;
346 this.shortOption = shortOption;
347 description = "";
348 }
349
350 /**
351 * Sets the long option.
352 *
353 * @param longOption The value to set the long option.
354 */
355
356 public void setKey( String longOption ) {
357 this.longOption = longOption;
358 }
359
360 /**
361 * Sets the short option.
362 *
363 * @param shortOption The value to set the short option.
364 */
365
366 public void setKey( char shortOption ) {
367 this.shortOption = shortOption;
368 }
369
370 /**
371 * Sets the short option.
372 *
373 * @param shortOption The value to set the short option.
374 */
375
376 public void setShortOption( char shortOption ) {
377 setKey( shortOption );
378 }
379
380 /**
381 * Sets the long option.
382 *
383 * @param longOption The value to set the long option.
384 */
385
386 public void setLongOption( String longOption ) {
387 setKey( longOption );
388 }
389
390 /**
391 * Sets the description of this option.
392 *
393 * @param description The description of this option.
394 */
395
396 public void setDescription( String description ) {
397 this.description = description;
398 }
399
400 /**
401 * Sets the deprecated flag to the value passed.
402 *
403 * @param deprecated A flag indicating whether the option is deprecated.
404 */
405
406 public void setDeprecated( boolean deprecated ) {
407 this.deprecated = deprecated;
408 }
409
410 /**
411 * Sets the field width for the option specification displayed
412 * in the help report.
413 *
414 * @param newSize The size to set the field width.
415 */
416
417 public static void setHelpOptionSpecificationSize( int newSize ) {
418 helpOptionSpecificationSize = newSize;
419 }
420
421 /**
422 * Sets the field width for the type name displayed in the help report.
423 *
424 * @param newSize The size to set the field width.
425 */
426
427 public static void setHelpTypenameSize( int newSize ) {
428 helpTypenameSize = newSize;
429 }
430
431 /**
432 * Sets the field width for the description displayed in the help report.
433 *
434 * @param newSize The size to set the field width.
435 */
436
437 public static void setHelpDescriptionSize( int newSize ) {
438 helpDescriptionSize = newSize;
439 }
440
441 /**
442 * Sets the field width for the deprecated flag displayed in the
443 * help report.
444 *
445 * @param newSize The size to set the field width.
446 */
447
448 public static void setHelpDeprecatedSize( int newSize ) {
449 helpDeprecatedSize = newSize;
450 }
451
452 /**
453 * Sets the field width for the option specification displayed
454 * in the menu listing of options.
455 *
456 * @param newSize The size to set the field width.
457 */
458
459 public static void setMenuOptionSpecificationSize( int newSize ) {
460 menuOptionSpecificationSize = newSize;
461 }
462
463 /**
464 * Sets the field width for the type name displayed in the menu
465 * listing of options.
466 *
467 * @param newSize The size to set the field width.
468 */
469
470 public static void setMenuTypenameSize( int newSize ) {
471 menuTypenameSize = newSize;
472 }
473
474 /**
475 * Sets the field width for the option description displayed
476 * in the menu listing of options.
477 *
478 * @param newSize The size to set the field width.
479 */
480
481 public static void setMenuDescriptionSize( int newSize ) {
482 menuDescriptionSize = newSize;
483 }
484
485 /**
486 * Sets the field width for the deprecated flag displayed
487 * in the menu listing of options.
488 *
489 * @param newSize The size to set the field width.
490 */
491
492 public static void setMenuDeprecatedSize( int newSize ) {
493 menuDeprecatedSize = newSize;
494 }
495
496 /**
497 * Sets the assignment field width used when options files are written.
498 *
499 * @param newSize The size to set the field width.
500 */
501
502 public static void setFileCompleteOptionSize( int newSize ) {
503 fileCompleteOptionSize = newSize;
504 }
505
506 /**
507 * Sets the assignment field width used when options files are written.
508 *
509 * @param newSize The size to set the field width.
510 */
511
512 public static void setFileCommentSize( int newSize ) {
513 fileCommentSize = newSize;
514 }
515
516 /**
517 * Sets whether this option has been invoked.
518 *
519 * @param A boolean indicating whether this option has been invoked.
520 */
521
522 public void setInvoked( boolean b ) {
523 invoked = b;
524 }
525
526 /**
527 * Deprecates this option.
528 */
529
530 public void deprecate() {
531 setDeprecated( true );
532 }
533
534 /**
535 * Return the name of this option. This method returns the same value as
536 * the getLongOption accessor.
537 *
538 * @return The name of this otpion.
539 */
540
541 public String getName() {
542 return longOption;
543 }
544
545 /**
546 * Return the short option key. There is no short option when this
547 * character is the null character.
548 *
549 * @return The short option key of this option.
550 */
551
552 public char getShortOption() {
553 return shortOption;
554 }
555
556 /**
557 * Return the long option key. There is no long option when this value
558 * is null.
559 *
560 * @return The long option key of this option.
561 */
562
563 public String getLongOption() {
564 return longOption;
565 }
566
567
568 /**
569 * Return a line used for help reporting.
570 *
571 * @return A line used for help reporting.
572 */
573
574 public String getHelp() {
575 return getHelpOptionSpecification() + " " + getHelpTypeName() + " "
576 + getHelpDescription() + " " + getHelpDeprecated();
577 }
578
579 /**
580 * Return the option specification field used during help reporting.
581 *
582 * @return The option specification field.
583 */
584
585 public String getHelpOptionSpecification() {
586 return Utility.expandString(
587 ( ( ( shortOption != '\0' ) ? ( "-" + getShortOption() ) : " " )
588 + ( ( longOption != null && shortOption != '\0' ) ? ", " : " " )
589 + ( ( longOption != null ) ? "--" + getLongOption(): "" ) ),
590 helpOptionSpecificationSize );
591 }
592
593 /**
594 * Return the type name field used during help reporting.
595 *
596 * @return The type name field.
597 */
598
599 public String getHelpTypeName() {
600 return Utility.expandString( "<" + getTypeName() + ">",
601 helpTypenameSize );
602 }
603
604 /**
605 * Return the description field used during help reporting.
606 *
607 * @return The description field.
608 */
609
610 public String getHelpDescription() {
611 return Utility.expandString( getDescription(),
612 helpDescriptionSize );
613 }
614
615 /**
616 * Return the deprecated field used during help reporting.
617 *
618 * @return The deprecated field.
619 */
620
621 public String getHelpDeprecated() {
622 return Utility.expandString( isDeprecated() ? "[d]" : "",
623 helpDeprecatedSize );
624 }
625
626 /**
627 * Return the header displayed at the top of the help report.
628 *
629 * @return The header displayed at the top of the help report.
630 */
631
632 public static String getHelpHeader() {
633 return Utility.expandString( "Option Name",
634 helpOptionSpecificationSize ) + " "
635 + Utility.expandString( "Type", helpTypenameSize ) + " "
636 + Utility.expandString( "Description", helpDescriptionSize );
637 }
638
639 /**
640 * The description explaining the meaning of this option.
641 *
642 * @return This options description.
643 */
644
645 public String getDescription() {
646 return description;
647 }
648
649 /**
650 * The hash key of this option. This is used by classes that implement
651 * the option registrar class. This method should <b>not</b> be overrided.
652 *
653 * @return The hash key of this option.
654 */
655
656 public String getHashKey() {
657 return Option.getHashKey( longOption, shortOption );
658 }
659
660 /**
661 * The hash key of an option if there is no short option. This method
662 * should <b>not</b> be overrided.
663 *
664 * @param longOption The long option.
665 *
666 * @return The hash key of this option based on the long option.
667 */
668
669 public static String getHashKey( String longOption ) {
670 return "," + ( ( longOption != null ) ? longOption : "" );
671 }
672
673 /**
674 * The hash key of an option if there is no long option. This method
675 * should <b>not</b> be overrided.
676 *
677 * @param shortOption The short option.
678 *
679 * @return The hash key of this option based on the short option.
680 */
681
682 public static String getHashKey( char shortOption ) {
683 return "" + ( shortOption != '\0' ) + ",";
684 }
685
686 /**
687 * The hash key of an option if there both short and long options are
688 * defined.
689 *
690 * @param shortOption The short option.
691 * @param longOption The long option.
692 *
693 * @return The hash key of this option based on both the short and long
694 * options.
695 */
696
697 public static String getHashKey( String longOption, char shortOption ) {
698 return ( ( shortOption == '\0' ) ? "" : "" + shortOption ) +
699 ( ( longOption == null ) ? "," : "," + longOption );
700 }
701
702 /**
703 * Returns whether this option is deprecated.
704 *
705 * @return A boolean indicating whether this option is deprecated.
706 */
707
708 public boolean isDeprecated() {
709 return deprecated;
710 }
711
712 /**
713 * Returns whether this option has been invoked.
714 *
715 * @return A boolean indicating whether this option has been invoked.
716 */
717
718 public boolean isInvoked() {
719 return invoked;
720 }
721
722 /**
723 * Returns (a) line(s) representing this option. This line is usually
724 * later written to an options file.
725 *
726 * @return Line(s) representing this option.
727 */
728
729 public String getOptionFileLine() {
730 boolean descriptionPrinted = false;
731 String retval = "";
732 String optionText = "";
733 String strval = getStringValue();
734 if ( longOption != null ) {
735 optionText += "--" + longOption;
736 }
737 else if ( shortOption != '\0' ) {
738 optionText += "-" + shortOption;
739 }
740 if ( optionText.length() > 0
741 && Utility.trim( strval ).length() >= 0 ) {
742 optionText += "=" + strval;
743 }
744 if ( optionText.length() <= fileCompleteOptionSize ) {
745 retval += Utility.expandString( optionText,
746 fileCompleteOptionSize );
747 }
748 else {
749 retval += "; " + description + "\n";
750 retval += optionText;
751 descriptionPrinted = true;
752 }
753 if ( !descriptionPrinted ) {
754 StringBuffer descsplit = new StringBuffer( description );
755 boolean tmp = false;
756 while ( descsplit.length() > 0 ) {
757 String st = "";
758 int size = 0;
759 if ( tmp ) {
760 st += Utility.getSpaces( fileCompleteOptionSize );
761 }
762 size = ( descsplit.length() >= fileCommentSize )
763 ? fileCommentSize : descsplit.length();
764 st += "; " + descsplit.substring( 0, size );
765 descsplit.delete( 0, size );
766 retval += st + "\n";
767 tmp = true;
768 }
769 descriptionPrinted = true;
770 }
771 return retval;
772 }
773
774 /**
775 * Returns the field width for the option specification displayed in the
776 * help report.
777 *
778 * @return The field width.
779 */
780
781 public static int getHelpOptionSpecificationSize() {
782 return helpOptionSpecificationSize;
783 }
784
785 /**
786 * Returns the field width for the type name displayed in the help report.
787 *
788 * @return The field width.
789 */
790
791 public static int getHelpTypenameSize() {
792 return helpTypenameSize;
793 }
794
795 /**
796 * Returns the field width for the description displayed in the help
797 * report.
798 *
799 * @return The field width.
800 */
801
802 public static int getHelpDescriptionSize() {
803 return helpDescriptionSize;
804 }
805
806 /**
807 * Returns the field width for the deprecated flag displayed in the
808 * help report.
809 *
810 * @return The field width.
811 */
812
813 public static int getHelpDeprecatedSize() {
814 return helpDeprecatedSize;
815 }
816
817 /**
818 * Returns the field width for the option specification displayed in the
819 * menu listing of options.
820 *
821 * @return The field width.
822 */
823
824 public static int getMenuOptionSpecificationSize() {
825 return menuOptionSpecificationSize;
826 }
827
828 /**
829 * Returns the field width for the type name displayed in the
830 * menu listing of options.
831 *
832 * @return The field width.
833 */
834
835 public static int getMenuTypenameSize() {
836 return menuTypenameSize;
837 }
838
839 /**
840 * Returns the field width for the description displayed in the
841 * menu listing of options.
842 *
843 * @return The field width.
844 */
845
846 public static int getMenuDescriptionSize() {
847 return menuDescriptionSize;
848 }
849
850 /**
851 * Returns the field width for the deprecated flag displayed in the
852 * menu listing of options.
853 *
854 * @return The field width.
855 */
856
857 public static int getMenuDeprecatedSize() {
858 return menuDeprecatedSize;
859 }
860
861 /**
862 * Returns the field width for assignment portion of a option file line.
863 *
864 * @return The field width.
865 */
866
867 public static int getFileCompleteOptionSize() {
868 return fileCompleteOptionSize;
869 }
870
871 /**
872 * Returns the field width for assignment portion of a option file line.
873 *
874 * @return The field width.
875 */
876
877 public static int getFileCommentSize() {
878 return fileCommentSize;
879 }
880
881 /**
882 * Returns the type name of this option.
883 *
884 * @return The type name of this option.
885 */
886
887 public abstract String getTypeName();
888
889 /**
890 * Prepares the option for modification.
891 */
892
893 public void action() {
894 if ( deprecated ) {
895 System.err.print( "Warning: " );
896 if ( longOption != null ) {
897 System.err.print( "--" + longOption );
898 }
899 if ( shortOption != '\0' && longOption != null ) {
900 System.err.print( " or " );
901 }
902 if ( shortOption != '\0' ) {
903 System.err.println( "-" + shortOption + " is deprecated." );
904 }
905 }
906 }
907
908 } /** Option */
909
910
911
912
913