sv_reftype second argument is not described #15012

p5pRT · 2015-10-28T04:37:18Z

Migrated from rt.perl.org#126469 (status was 'resolved')

Searchable as RT126469$

p5pRT · 2015-10-28T04:37:19Z

From bkb@cpan.org

There is no documentation of the second argument of sv_reftype.

Looking at the code in sv.c, it looks like

if (ob && SvOBJECT(sv)) {
return SvPV_nolen_const(sv_ref(NULL, sv, ob));
}
else {
// only returns Perl-internal types like "SCALAR", not object types.
}

Thus it seems "ob" should be true if we want to return object information, and false if we don't. I suggest documenting the second argument. Also, in case this is an omission, I'd like to point out that the SvOBJECT, SvOBJECT_on, and SvOBJECT_off macros are not documented anywhere in perlapi.

I am using Perl 5.18.2, but I checked the documentation of perlapi in 22.0 using the following web page:

http://perldoc.perl.org/perlapi.html

The documentation of sv_reftype, SvOBJECT, and SvOBJECT_on/off don't seem to have altered.

Thanks.

p5pRT · 2015-10-29T04:11:17Z

From @tonycoz

On Tue Oct 27 21:37:19 2015, bkbullock wrote:

There is no documentation of the second argument of sv_reftype.

Looking at the code in sv.c, it looks like

if (ob && SvOBJECT(sv)) {
return SvPV_nolen_const(sv_ref(NULL, sv, ob));
}
else {
// only returns Perl-internal types like "SCALAR", not object
types.
}

Thus it seems "ob" should be true if we want to return object
information, and false if we don't. I suggest documenting the second
argument. Also, in case this is an omission, I'd like to point out
that the SvOBJECT, SvOBJECT_on, and SvOBJECT_off macros are not
documented anywhere in perlapi.

I am using Perl 5.18.2, but I checked the documentation of perlapi in
22.0 using the following web page:

http://perldoc.perl.org/perlapi.html

The documentation of sv_reftype, SvOBJECT, and SvOBJECT_on/off don't
seem to have altered.

I've attached two patches, the first makes sv_ref()* part of the API, the second documents the ob parameter to sv_reftype().

Tony

* a unicode class name aware version of sv_reftype()

p5pRT · 2015-10-29T04:11:17Z

From @tonycoz

0001-make-sv_ref-part-of-the-API.patch

From 5b647175f347880c87074de7c6c56c665254cbc0 Mon Sep 17 00:00:00 2001
From: Tony Cook <tony@develop-help.com>
Date: Thu, 29 Oct 2015 15:05:59 +1100
Subject: make sv_ref() part of the API

The existing sv_reftype() returns the class of a blessed SV only
as a const char *, so we can't tell if it's UTF8 or not.

This probably should have been API from the beginning.
---
 embed.fnc | 2 +-
 embed.h   | 2 +-
 sv.c      | 6 ++++++
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/embed.fnc b/embed.fnc
index c7dfead..27659fc 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -1467,7 +1467,7 @@ Apd	|char*	|sv_recode_to_utf8	|NN SV* sv|NN SV *encoding
 Apd	|bool	|sv_cat_decode	|NN SV* dsv|NN SV *encoding|NN SV *ssv|NN int *offset \
 				|NN char* tstr|int tlen
 ApdR	|const char*	|sv_reftype	|NN const SV *const sv|const int ob
-pd	|SV*	|sv_ref	|NULLOK SV *dst|NN const SV *const sv|const int ob
+Apd	|SV*	|sv_ref	|NULLOK SV *dst|NN const SV *const sv|const int ob
 Apd	|void	|sv_replace	|NN SV *const sv|NN SV *const nsv
 Apd	|void	|sv_report_used
 Apd	|void	|sv_reset	|NN const char* s|NULLOK HV *const stash
diff --git a/embed.h b/embed.h
index 5472b07..78942d6 100644
--- a/embed.h
+++ b/embed.h
@@ -648,6 +648,7 @@
 #define sv_pvutf8n(a,b)		Perl_sv_pvutf8n(aTHX_ a,b)
 #define sv_pvutf8n_force(a,b)	Perl_sv_pvutf8n_force(aTHX_ a,b)
 #define sv_recode_to_utf8(a,b)	Perl_sv_recode_to_utf8(aTHX_ a,b)
+#define sv_ref(a,b,c)		Perl_sv_ref(aTHX_ a,b,c)
 #define sv_reftype(a,b)		Perl_sv_reftype(aTHX_ a,b)
 #define sv_replace(a,b)		Perl_sv_replace(aTHX_ a,b)
 #define sv_report_used()	Perl_sv_report_used(aTHX)
@@ -1319,7 +1320,6 @@
 #define sv_free_arenas()	Perl_sv_free_arenas(aTHX)
 #define sv_len_utf8_nomg(a)	Perl_sv_len_utf8_nomg(aTHX_ a)
 #define sv_mortalcopy_flags(a,b)	Perl_sv_mortalcopy_flags(aTHX_ a,b)
-#define sv_ref(a,b,c)		Perl_sv_ref(aTHX_ a,b,c)
 #define sv_resetpvn(a,b,c)	Perl_sv_resetpvn(aTHX_ a,b,c)
 #define sv_sethek(a,b)		Perl_sv_sethek(aTHX_ a,b)
 #ifndef PERL_IMPLICIT_CONTEXT
diff --git a/sv.c b/sv.c
index f0c1553..1d467d3 100644
--- a/sv.c
+++ b/sv.c
@@ -9991,6 +9991,12 @@ Perl_sv_reftype(pTHX_ const SV *const sv, const int ob)
 
 Returns a SV describing what the SV passed in is a reference to.
 
+dst can be a SV to be set to the description or NULL, in which case a
+mortal SV is returned.
+
+If ob is true and the SV is blessed, the description is the class
+name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
+
 =cut
 */
 
-- 
2.1.4

p5pRT · 2015-10-29T04:11:17Z

From @tonycoz

0002-perl-126469-document-the-ob-parameter-to-sv_reftype.patch

From 620583fa11f7b02d6cc6c493bc5542c291230eee Mon Sep 17 00:00:00 2001
From: Tony Cook <tony@develop-help.com>
Date: Thu, 29 Oct 2015 15:07:09 +1100
Subject: [perl #126469] document the ob parameter to sv_reftype()

---
 sv.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/sv.c b/sv.c
index 1d467d3..1538614 100644
--- a/sv.c
+++ b/sv.c
@@ -9933,6 +9933,9 @@ Perl_sv_pvutf8n_force(pTHX_ SV *const sv, STRLEN *const lp)
 
 Returns a string describing what the SV is a reference to.
 
+If ob is true and the SV is blessed, the string is the class name,
+otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
+
 =cut
 */
 
-- 
2.1.4

p5pRT · 2015-10-29T04:11:17Z

The RT System itself - Status changed from 'new' to 'open'

p5pRT · 2015-11-09T01:11:43Z

From @tonycoz

On Wed Oct 28 21:11:17 2015, tonyc wrote:

On Tue Oct 27 21:37:19 2015, bkbullock wrote:

There is no documentation of the second argument of sv_reftype.

Looking at the code in sv.c, it looks like

if (ob && SvOBJECT(sv)) {
return SvPV_nolen_const(sv_ref(NULL, sv, ob));
}
else {
// only returns Perl-internal types like "SCALAR", not object
types.
}

Thus it seems "ob" should be true if we want to return object
information, and false if we don't. I suggest documenting the second
argument. Also, in case this is an omission, I'd like to point out
that the SvOBJECT, SvOBJECT_on, and SvOBJECT_off macros are not
documented anywhere in perlapi.

I am using Perl 5.18.2, but I checked the documentation of perlapi in
22.0 using the following web page:

http://perldoc.perl.org/perlapi.html

The documentation of sv_reftype, SvOBJECT, and SvOBJECT_on/off don't
seem to have altered.

I've attached two patches, the first makes sv_ref()* part of the API,
the second documents the ob parameter to sv_reftype().

Applied as b1744e1 and 28aaeb3.

Tony

p5pRT · 2015-11-09T01:11:44Z

@tonycoz - Status changed from 'open' to 'resolved'

p5pRT closed this as completed Nov 9, 2015

p5pRT added the Severity Low label Oct 19, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

sv_reftype second argument is not described #15012

sv_reftype second argument is not described #15012

p5pRT commented Oct 28, 2015

p5pRT commented Oct 28, 2015

p5pRT commented Oct 29, 2015

p5pRT commented Oct 29, 2015

p5pRT commented Oct 29, 2015

p5pRT commented Oct 29, 2015

p5pRT commented Nov 9, 2015

p5pRT commented Nov 9, 2015

sv_reftype second argument is not described #15012

sv_reftype second argument is not described #15012

Comments

p5pRT commented Oct 28, 2015

p5pRT commented Oct 28, 2015

From bkb@cpan.org

p5pRT commented Oct 29, 2015

From @tonycoz

p5pRT commented Oct 29, 2015

From @tonycoz

p5pRT commented Oct 29, 2015

From @tonycoz

p5pRT commented Oct 29, 2015

p5pRT commented Nov 9, 2015

From @tonycoz

p5pRT commented Nov 9, 2015