[catagits/Gitalist.git] / local-lib5 / man / man3 / Task::Weaken.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Task::Weaken 3"
.TH Task::Weaken 3 "2009-06-12" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Task::Weaken \- Ensure that a platform has weaken support
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
One recurring problem in modules that use Scalar::Util's \f(CW\*(C`weaken\*(C'\fR
function is that it is not present in the pure-perl variant.
.PP
While this isn't necesarily always a problem in a straight CPAN-based
Perl environment, some operating system distributions only include the
pure-Perl versions, don't include the \s-1XS\s0 version, and so weaken is
then \*(L"missing\*(R" from the platform, \fBdespite\fR passing a dependency on
Scalar::Util successfully.
.PP
Most notably this is RedHat Linux at time of writing, but other come
and go and do the same thing, hence \*(L"recurring problem\*(R".
.PP
The normal solution is to manually write tests in each distribution
to ensure that \f(CW\*(C`weaken\*(C'\fR is available.
.PP
This restores the functionality testing to a dependency you do once
in your \fIMakefile.PL\fR, rather than something you have to write extra
tests for each time you write a module.
.PP
It should also help make the package auto-generators for the various
operating systems play more nicely, because it introduces a dependency
that they \fBhave\fR to have a proper weaken in order to work.
.Sh "How this Task works"
.IX Subsection "How this Task works"
Part of the problem seems to stem from the fact that some distributions
continue to include modules even if they fail some of their tests.
.PP
To get around that for this module, it will do a few dirty tricks.
.PP
If Scalar::Util is not available at all, it will issue a normal
dependency on the module. However, if Scalar::Util is relatively
new ( it is >= 1.19 ) and the module does \fBnot\fR have weaken, the
install will bail out altogether with a long error encouraging the
user to seek support from their vendor (this problem happens most
often in vendor-packaged Perl versions).
.PP
This distribution also contains tests to ensure that weaken is
available using more normal methods.
.PP
So if your module uses \f(CW\*(C`weaken\*(C'\fR, you can just add the following to
your Module::Install\-based \fIMakefile.PL\fR (or equivalent).
.PP
.Vb 1
\&  requires 'Task::Weaken' => 0;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>, <http://ali.as/>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Task, Scalar::Util, <http://ali.as/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006 \- 2009 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.
Commit	Line	Data
3fea05b9	1	.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
	2	.\"
	3	.\" Standard preamble:
	4	.\" ========================================================================
	5	.de Sh \" Subsection heading
	6	.br
	7	.if t .Sp
	8	.ne 5
	9	.PP
	10	\fB\\$1\fR
	11	.PP
	12	..
	13	.de Sp \" Vertical space (when we can't use .PP)
	14	.if t .sp .5v
	15	.if n .sp
	16	..
	17	.de Vb \" Begin verbatim text
	18	.ft CW
	19	.nf
	20	.ne \\$1
	21	..
	22	.de Ve \" End verbatim text
	23	.ft R
	24	.fi
	25	..
	26	.\" Set up some character translations and predefined strings. \*(-- will
	27	.\" give an unbreakable dash, \(PI will give pi, \(L" will give a left
	28	.\" double quote, and \*(R" will give a right double quote. \| will give a
	29	.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
	30	.\" do unbreakable dashes and therefore won't be available. \(C` and \(C'
	31	.\" expand to `' in nroff, nothing in troff, for use with C<>.
	32	.tr \(W-\|\(bv\(Tr
	33	.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
	34	.ie n \{\
	35	. ds -- \(*W-
	36	. ds PI pi
	37	. if (\n(.H=4u)&(1m=24u) .ds -- \(W\h'-12u'\(W\h'-12u'-\" diablo 10 pitch
	38	. if (\n(.H=4u)&(1m=20u) .ds -- \(W\h'-12u'\(W\h'-8u'-\" diablo 12 pitch
	39	. ds L" ""
	40	. ds R" ""
	41	. ds C` ""
	42	. ds C' ""
	43	'br\}
	44	.el\{\
	45	. ds -- \\|\(em\\|
	46	. ds PI \(*p
	47	. ds L" ``
	48	. ds R" ''
	49	'br\}
	50	.\"
	51	.\" If the F register is turned on, we'll generate index entries on stderr for
	52	.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
	53	.\" entries marked with X<> in POD. Of course, you'll have to process the
	54	.\" output yourself in some meaningful fashion.
	55	.if \nF \{\
	56	. de IX
	57	. tm Index:\\$1\t\\n%\t"\\$2"
	58	..
	59	. nr % 0
	60	. rr F
	61	.\}
	62	.\"
	63	.\" For nroff, turn off justification. Always turn off hyphenation; it makes
	64	.\" way too many mistakes in technical documents.
65	.hy 0
66	.if n .na
67	.\"
68	.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69	.\" Fear. Run. Save yourself. No user-serviceable parts.
70	. \" fudge factors for nroff and troff
71	.if n \{\
72	. ds #H 0
73	. ds #V .8m
74	. ds #F .3m
75	. ds #[ \f1
76	. ds #] \fP
77	.\}
78	.if t \{\
79	. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80	. ds #V .6m
81	. ds #F 0
82	. ds #[ \&
83	. ds #] \&
84	.\}
85	. \" simple accents for nroff and troff
86	.if n \{\
87	. ds ' \&
88	. ds ` \&
89	. ds ^ \&
90	. ds , \&
91	. ds ~ ~
92	. ds /
93	.\}
94	.if t \{\
95	. ds ' \\k:\h'-(\\n(.wu8/10-\(#H)'\'\h"\|\\n:u"
96	. ds ` \\k:\h'-(\\n(.wu8/10-\(#H)'\`\h'\|\\n:u'
97	. ds ^ \\k:\h'-(\\n(.wu10/11-\(#H)'^\h'\|\\n:u'
98	. ds , \\k:\h'-(\\n(.wu*8/10)',\h'\|\\n:u'
99	. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'\|\\n:u'
100	. ds / \\k:\h'-(\\n(.wu8/10-\(#H)'\z\(sl\h'\|\\n:u'
101	.\}
102	. \" troff and (daisy-wheel) nroff accents
103	.ds : \\k:\h'-(\\n(.wu8/10-\(#H+.1m+\(#F)'\v'-\(#V'\z.\h'.2m+\(#F'.\h'\|\\n:u'\v'\(#V'
104	.ds 8 \h'\(#H'\(b\h'-\*(#H'
105	.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\(#H)/2u'\v'-.3n'\(#[\z\(de\v'.3n'\h'\|\\n:u'\*(#]
106	.ds d- \h'\(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\(#H'
107	.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'\|\\n:u'
108	.ds th \(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u2/3)'\s-1o\s+1\*(#]
109	.ds Th \(#[\s+2I\s-2\h'-\w'I'u3/5'\v'-.3m'o\v'.3m'\*(#]
110	.ds ae a\h'-(\w'a'u*4/10)'e
111	.ds Ae A\h'-(\w'A'u*4/10)'E
112	. \" corrections for vroff
113	.if v .ds ~ \\k:\h'-(\\n(.wu9/10-\(#H)'\s-2\u~\d\s+2\h'\|\\n:u'
114	.if v .ds ^ \\k:\h'-(\\n(.wu10/11-\(#H)'\v'-.4m'^\v'.4m'\h'\|\\n:u'
115	. \" for low resolution devices (crt and lpr)
116	.if \n(.H>23 .if \n(.V>19 \
117	\{\
118	. ds : e
119	. ds 8 ss
120	. ds o a
121	. ds d- d\h'-1'\(ga
122	. ds D- D\h'-1'\(hy
123	. ds th \o'bp'
124	. ds Th \o'LP'
125	. ds ae ae
126	. ds Ae AE
127	.\}
128	.rm #[ #] #H #V #F C
129	.\" ========================================================================
130	.\"
131	.IX Title "Task::Weaken 3"
132	.TH Task::Weaken 3 "2009-06-12" "perl v5.8.7" "User Contributed Perl Documentation"
133	.SH "NAME"
134	Task::Weaken \- Ensure that a platform has weaken support
135	.SH "DESCRIPTION"
136	.IX Header "DESCRIPTION"
137	One recurring problem in modules that use Scalar::Util's \f(CW\(C`weaken\(C'\fR
138	function is that it is not present in the pure-perl variant.
139	.PP
140	While this isn't necesarily always a problem in a straight CPAN-based
141	Perl environment, some operating system distributions only include the
142	pure-Perl versions, don't include the \s-1XS\s0 version, and so weaken is
143	then \(L"missing\(R" from the platform, \fBdespite\fR passing a dependency on
144	Scalar::Util successfully.
145	.PP
146	Most notably this is RedHat Linux at time of writing, but other come
147	and go and do the same thing, hence \(L"recurring problem\(R".
148	.PP
149	The normal solution is to manually write tests in each distribution
150	to ensure that \f(CW\(C`weaken\(C'\fR is available.
151	.PP
152	This restores the functionality testing to a dependency you do once
153	in your \fIMakefile.PL\fR, rather than something you have to write extra
154	tests for each time you write a module.
155	.PP
156	It should also help make the package auto-generators for the various
157	operating systems play more nicely, because it introduces a dependency
158	that they \fBhave\fR to have a proper weaken in order to work.
159	.Sh "How this Task works"
160	.IX Subsection "How this Task works"
161	Part of the problem seems to stem from the fact that some distributions
162	continue to include modules even if they fail some of their tests.
163	.PP
164	To get around that for this module, it will do a few dirty tricks.
165	.PP
166	If Scalar::Util is not available at all, it will issue a normal
167	dependency on the module. However, if Scalar::Util is relatively
168	new ( it is >= 1.19 ) and the module does \fBnot\fR have weaken, the
169	install will bail out altogether with a long error encouraging the
170	user to seek support from their vendor (this problem happens most
171	often in vendor-packaged Perl versions).
172	.PP
173	This distribution also contains tests to ensure that weaken is
174	available using more normal methods.
175	.PP
176	So if your module uses \f(CW\(C`weaken\(C'\fR, you can just add the following to
177	your Module::Install\-based \fIMakefile.PL\fR (or equivalent).
178	.PP
179	.Vb 1
180	\& requires 'Task::Weaken' => 0;
181	.Ve
182	.SH "AUTHOR"
183	.IX Header "AUTHOR"
184	Adam Kennedy <adamk@cpan.org>, <http://ali.as/>
185	.SH "SEE ALSO"
186	.IX Header "SEE ALSO"
187	Task, Scalar::Util, <http://ali.as/>
188	.SH "COPYRIGHT"
189	.IX Header "COPYRIGHT"
190	Copyright 2006 \- 2009 Adam Kennedy.
191	.PP
192	This program is free software; you can redistribute
193	it and/or modify it under the same terms as Perl itself.
194	.PP
195	The full text of the license can be found in the
196	\&\s-1LICENSE\s0 file included with this module.