summaryrefslogtreecommitdiff
path: root/Build/source/utils/texi2html/MySimple.pod
blob: 100f9759fcd693567f6ee382beab490a2d359849 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
=head1 NAME

C<Getopt::MySimple> - Provide a simple wrapper around Getopt::Long.
=head NOTE
Based on GetOpt::Simple, with some (here undocumented) modifications
to fit texi2hml  needs.

=head1 SYNOPSIS

	use Getopt::MySimple;

	# Or ...
	# use Getopt::MySimple qw($opt);

	my($options) =
	{
	'help' =>
		{
		'type'		=> '',
		'default'	=> '',
#		'verbose'	=> '',	# Not needed on every key.
		},
	'username' =>
		{
		'type'		=> '=s',			# As per Getopt::Long.
		'default'	=> $ENV{'USER'} || 'RonSavage',	# In case $USER is undef.
		'verbose'	=> 'Specify the username on the remote machine',
		},
	'password' =>
		{
		'type'		=> '=s',
		'default'	=> 'password',
		'verbose'	=> 'Specify the password on the remote machine',
		},
	};

	my($option) = new Getopt::MySimple;

	if (! $option -> getOptions($options, "Usage: testMySimple.pl [options]") )
	{
		exit(-1);	# Failure.
	}

	print "username: $option->{'opt'}{'username'}. \n";
	print "password: $option->{'opt'}{'password'}. \n";

	# Or, after 'use Getopt::MySimple qw($opt);' ...
	# print "username: $opt->{'username'}. \n";
	# print "password: $opt->{'password'}. \n";

=head1 DESCRIPTION

The C<Getopt::MySimple> module provides a simple way of specifying:

=over 4

=item *

Command line optes

=item *

Type information for opt values

=item *

Default values for the optes

=item *

Help text per opt

=back

=head1 The C<getOptions()> function

The C<getOptions()> function takes 4 parameters:

=over 4

=item *

A hash defining the command line optes

=item *

A string to display as a help text heading

=item *

A Boolean. 0 = (Default) Use case-sensitive opt names. 1 = Ignore case

=item *

A Boolean. 0 = Return after displaying help. 1 = (Default) Terminate with exit(0)
after displaying help

=back

=head1 The $classRef -> {'opt'} hash reference

Command line option values are accessed in your code by dereferencing
the hash reference $classRef -> {'opt'}. Two examples are given above,
under synopsis.

Alternately, you can use the hash reference $opt. See below.

=head1 The $opt hash reference

Command line option values are accessed in your code by dereferencing
the hash reference $opt. Two examples are given above,
under synopsis.

Alternately, you can use the hash reference $classRef -> {'opt'}. See above.

=head1 The C<dumpOptions()> function

C<dumpOptions()> prints all your option's keys and their current values.

=head1 The C<helpOptions()> function

C<helpOptions()> prints nicely formatted help text.

=head1 WARNING re Perl bug

As always, be aware that these 2 lines mean the same thing, sometimes:

=over 4

=item *

$self -> {'thing'}

=item *

$self->{'thing'}

=back

The problem is the spaces around the ->. Inside double quotes, "...", the
first space stops the dereference taking place. Outside double quotes the
scanner correctly associates the $self token with the {'thing'} token.

I regard this as a bug.

=head1 REQUIRED MODULES

=over 4

=item *

Exporter

=item *

Getopt::Long

=back

=head1 RETURN VALUES

=over 4

=item *

C<dumpOptions()> returns nothing

=item *

C<helpOptions()> returns nothing

=item *

C<getOptions()> returns 0 for failure and 1 for success

=back

=head1 AUTHOR

C<Getopt::MySimple> was written by Ron Savage I<E<lt>rpsavage@ozemail.com.auE<gt>> in 1997.

Modifications for texi2html by Olaf Bachmann
I<E<lt>obachman@mathtematik.uni-kl.deE<gt>> in 2000.
=head1 LICENCE

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.