Struct Cv 

pub struct Cv(/* private fields */);

Non-null pointer to a Perl CV. Same ABI as *mut CV.

Implementations

impl Cv

pub unsafe fn from_raw_unchecked(p: *mut CV) -> Self

Wrap a raw *mut CV without checking for null.

Safety

Caller must guarantee p is non-null and points to a valid CV for at least the lifetime of the resulting Cv.

pub fn from_raw(p: *mut CV) -> Option<Self>

Wrap a raw *mut CV, returning None on null input.

pub fn from_coderef(sv: *mut SV) -> Option<Cv>

Dereference a Perl-level coderef SV (\&sub, sub {...}) into its CV. Returns None when sv is null, not a reference, or references something other than a CODE value.

pub fn as_ptr(&self) -> *mut CV

Raw *mut CV for FFI calls.

pub fn is_xsub(&self) -> bool

True when this CV is an XSUB (C-implemented). XSUBs have no OP tree; root / start / padlist return null for them.

pub fn root(&self) -> *const OP

Root of the CV’s OP tree (CvROOT), or null for XSUBs.

pub fn start(&self) -> *const OP

First OP in execution order (CvSTART), or null for XSUBs.

pub fn padlist(&self) -> *const PADLIST

The CV’s PADLIST (lexical scratchpad), or null for XSUBs.

pub fn file(&self) -> Option<String>

Source file the sub was compiled from (CvFILE); "(eval N)" for string-eval’d subs.

Examples found in repository

examples/walker_stash.rs (line 39)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        let file = e.cv.file();
        println!("sub {}::{} file {:?}", e.package, e.name, file);
        if file.as_deref() == Some(main_file.as_str()) {
            if let Some(root) = e.cv.root_op() {
                print_tree(&perl, root, 1);
            }
        }
    });
}

examples/walker_subs.rs (line 29)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        if e.cv.file().as_deref() != Some(main_file.as_str()) {
            return;
        }
        let qual = e
            .cv
            .names(&perl)
            .map(|(full, _)| full)
            .unwrap_or_else(|| format!("{}::{}", e.package, e.name));
        let line = e.cv.first_cop(&perl).map(|c| c.line());
        println!("sub {qual} (first statement at line {line:?})");

        let lexicals: Vec<String> = e
            .cv
            .pad_names()
            .flatten() // skip unnamed slots
            .filter_map(|pn| {
                // Target/temporary slots have a non-null but empty PV;
                // only real `my`/`our` names are interesting here.
                let pv = pn.pv().filter(|s| !s.is_empty())?;
                Some(match pn.type_stash_name() {
                    Some(t) => format!("{pv}: {t}"),
                    None => pv,
                })
            })
            .collect();
        println!("  lexicals: {lexicals:?}");

        let ops: Vec<&str> = e
            .cv
            .start_op()
            .into_iter()
            .flat_map(|s| s.next_iter())
            .take(20)
            .map(|o| o.name().unwrap_or("<custom>"))
            .collect();
        println!("  ops (execution order, first 20): {}", ops.join(" "));
    });
}

pub fn root_op(&self) -> Option<Op>

Cv::root as an Op handle (None for XSUBs).

Examples found in repository

examples/walker_stash.rs (line 42)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        let file = e.cv.file();
        println!("sub {}::{} file {:?}", e.package, e.name, file);
        if file.as_deref() == Some(main_file.as_str()) {
            if let Some(root) = e.cv.root_op() {
                print_tree(&perl, root, 1);
            }
        }
    });
}

pub fn start_op(&self) -> Option<Op>

Cv::start as an Op handle (None for XSUBs).

Examples found in repository

examples/walker_subs.rs (line 58)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        if e.cv.file().as_deref() != Some(main_file.as_str()) {
            return;
        }
        let qual = e
            .cv
            .names(&perl)
            .map(|(full, _)| full)
            .unwrap_or_else(|| format!("{}::{}", e.package, e.name));
        let line = e.cv.first_cop(&perl).map(|c| c.line());
        println!("sub {qual} (first statement at line {line:?})");

        let lexicals: Vec<String> = e
            .cv
            .pad_names()
            .flatten() // skip unnamed slots
            .filter_map(|pn| {
                // Target/temporary slots have a non-null but empty PV;
                // only real `my`/`our` names are interesting here.
                let pv = pn.pv().filter(|s| !s.is_empty())?;
                Some(match pn.type_stash_name() {
                    Some(t) => format!("{pv}: {t}"),
                    None => pv,
                })
            })
            .collect();
        println!("  lexicals: {lexicals:?}");

        let ops: Vec<&str> = e
            .cv
            .start_op()
            .into_iter()
            .flat_map(|s| s.next_iter())
            .take(20)
            .map(|o| o.name().unwrap_or("<custom>"))
            .collect();
        println!("  ops (execution order, first 20): {}", ops.join(" "));
    });
}

pub fn gv(&self, perl: &Perl) -> Option<Gv>

The GV the sub was defined through (CvGV), if any. Gives access to the sub’s package-qualified name and the glob’s file / line.

pub fn names(&self, perl: &Perl) -> Option<(String, String)>

The sub’s (qualified, unqualified) name pair (("Foo::bar", "bar")), resolved via Cv::gv. None for nameless subs.

Examples found in repository

examples/walker_subs.rs (line 34)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        if e.cv.file().as_deref() != Some(main_file.as_str()) {
            return;
        }
        let qual = e
            .cv
            .names(&perl)
            .map(|(full, _)| full)
            .unwrap_or_else(|| format!("{}::{}", e.package, e.name));
        let line = e.cv.first_cop(&perl).map(|c| c.line());
        println!("sub {qual} (first statement at line {line:?})");

        let lexicals: Vec<String> = e
            .cv
            .pad_names()
            .flatten() // skip unnamed slots
            .filter_map(|pn| {
                // Target/temporary slots have a non-null but empty PV;
                // only real `my`/`our` names are interesting here.
                let pv = pn.pv().filter(|s| !s.is_empty())?;
                Some(match pn.type_stash_name() {
                    Some(t) => format!("{pv}: {t}"),
                    None => pv,
                })
            })
            .collect();
        println!("  lexicals: {lexicals:?}");

        let ops: Vec<&str> = e
            .cv
            .start_op()
            .into_iter()
            .flat_map(|s| s.next_iter())
            .take(20)
            .map(|o| o.name().unwrap_or("<custom>"))
            .collect();
        println!("  ops (execution order, first 20): {}", ops.join(" "));
    });
}

pub fn first_cop(&self, perl: &Perl) -> Option<Cop>

The first COP (nextstate) in the sub’s OP tree, in tree order — i.e. the sub’s first statement, whose line / file locate the sub body in its source. None for XSUBs and bodiless subs.

Walks tree order (preorder), not the op_next chain, so loop back-edges cannot cycle the search.

Examples found in repository

examples/walker_subs.rs (line 37)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        if e.cv.file().as_deref() != Some(main_file.as_str()) {
            return;
        }
        let qual = e
            .cv
            .names(&perl)
            .map(|(full, _)| full)
            .unwrap_or_else(|| format!("{}::{}", e.package, e.name));
        let line = e.cv.first_cop(&perl).map(|c| c.line());
        println!("sub {qual} (first statement at line {line:?})");

        let lexicals: Vec<String> = e
            .cv
            .pad_names()
            .flatten() // skip unnamed slots
            .filter_map(|pn| {
                // Target/temporary slots have a non-null but empty PV;
                // only real `my`/`our` names are interesting here.
                let pv = pn.pv().filter(|s| !s.is_empty())?;
                Some(match pn.type_stash_name() {
                    Some(t) => format!("{pv}: {t}"),
                    None => pv,
                })
            })
            .collect();
        println!("  lexicals: {lexicals:?}");

        let ops: Vec<&str> = e
            .cv
            .start_op()
            .into_iter()
            .flat_map(|s| s.next_iter())
            .take(20)
            .map(|o| o.name().unwrap_or("<custom>"))
            .collect();
        println!("  ops (execution order, first 20): {}", ops.join(" "));
    });
}

pub fn pad_names(&self) -> PadNames

Iterate the sub’s lexical-name slots (pad names), in pad-offset order starting at offset 0. Empty for XSUBs. See PadNames.

Examples found in repository

examples/walker_subs.rs (line 42)

fn main() {
    let mut perl = Perl::new();
    perl.parse_env_args(env::args(), env::vars());

    let sv0 = perl.get_sv("0", 0).expect("$0 is always set");
    let main_file = String::from_utf8_lossy(sv0.pv(&perl)).into_owned();
    println!("$0 = {main_file:?}");

    let mut walker = StashWalker::new(&perl);
    walker.walk("main", &mut |e| {
        if e.cv.file().as_deref() != Some(main_file.as_str()) {
            return;
        }
        let qual = e
            .cv
            .names(&perl)
            .map(|(full, _)| full)
            .unwrap_or_else(|| format!("{}::{}", e.package, e.name));
        let line = e.cv.first_cop(&perl).map(|c| c.line());
        println!("sub {qual} (first statement at line {line:?})");

        let lexicals: Vec<String> = e
            .cv
            .pad_names()
            .flatten() // skip unnamed slots
            .filter_map(|pn| {
                // Target/temporary slots have a non-null but empty PV;
                // only real `my`/`our` names are interesting here.
                let pv = pn.pv().filter(|s| !s.is_empty())?;
                Some(match pn.type_stash_name() {
                    Some(t) => format!("{pv}: {t}"),
                    None => pv,
                })
            })
            .collect();
        println!("  lexicals: {lexicals:?}");

        let ops: Vec<&str> = e
            .cv
            .start_op()
            .into_iter()
            .flat_map(|s| s.next_iter())
            .take(20)
            .map(|o| o.name().unwrap_or("<custom>"))
            .collect();
        println!("  ops (execution order, first 20): {}", ops.join(" "));
    });
}

pub fn proto(&self) -> Option<String>

The sub’s prototype string (CvPROTO), if any. A CV stores its prototype in its own PV slot, so this is SvPOK + SvPVX_const/SvCUR on the CV itself.

Trait Implementations

impl Clone for Cv

fn clone(&self) -> Cv

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Cv