rd-ast 0.0.1

Canonical, producer-agnostic AST for R's Rd (documentation) format
Documentation 
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

use super::*;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum RdMethodKind {
    Method,
    S3Method,
    S4Method,
}

#[derive(Debug, Clone, PartialEq)]
/// A method usage node with exact Text-scalar generic and qualifier arguments.
/// The following call syntax `(x, ...)` in `\usage` is not part of this
/// method node; it remains a sibling `RCode` leaf of the parent section.
pub struct RdMethod<'a> {
    path: RdPath,
    kind: RdMethodKind,
    generic_nodes: &'a [RdNode],
    generic: String,
    qualifier_nodes: &'a [RdNode],
    qualifier: String,
}

impl<'a> RdMethod<'a> {
    pub fn path(&self) -> &RdPath {
        &self.path
    }
    pub fn kind(&self) -> RdMethodKind {
        self.kind
    }
    pub fn generic_nodes(&self) -> &'a [RdNode] {
        self.generic_nodes
    }
    pub fn generic(&self) -> &str {
        &self.generic
    }
    pub fn qualifier_nodes(&self) -> &'a [RdNode] {
        self.qualifier_nodes
    }
    /// Class for `\method`/`\S3method`, signature for `\S4method`; consumers branch on `kind()`.
    pub fn qualifier(&self) -> &str {
        &self.qualifier
    }
}

fn kind(tag: &RdTag) -> Option<RdMethodKind> {
    match tag {
        RdTag::Method => Some(RdMethodKind::Method),
        RdTag::S3Method => Some(RdMethodKind::S3Method),
        RdTag::S4Method => Some(RdMethodKind::S4Method),
        _ => None,
    }
}

impl RdNode {
    pub fn method(&self, base_path: &RdPath) -> Option<RdMethod<'_>> {
        self.inspect_method(base_path).ok().flatten()
    }

    pub fn inspect_method(&self, base_path: &RdPath) -> Result<Option<RdMethod<'_>>, RdShapeError> {
        let tagged = match self {
            RdNode::Tagged(tagged) => tagged,
            RdNode::Raw(raw) => {
                let Some(tag) = raw.tag().map(RdTag::from_rd_tag) else {
                    return Ok(None);
                };
                if kind(&tag).is_some() {
                    return Err(shape(
                        base_path.clone(),
                        Some(tag),
                        RdShapeErrorKind::UnexpectedNode {
                            expected: RdExpectedNode::Tagged,
                            actual: RdNodeKind::Raw,
                        },
                    ));
                }
                return Ok(None);
            }
            _ => return Ok(None),
        };
        let Some(kind) = kind(tagged.tag()) else {
            return Ok(None);
        };
        if tagged.option().is_some() {
            return Err(shape(
                base_path.clone(),
                Some(tagged.tag().clone()),
                RdShapeErrorKind::UnexpectedOption,
            ));
        }
        let children = tagged.children();
        if children.len() != 2 {
            return Err(shape(
                base_path.clone(),
                Some(tagged.tag().clone()),
                RdShapeErrorKind::WrongArity {
                    expected: RdArity::Exactly(2),
                    actual: children.len(),
                },
            ));
        }
        for (index, child) in children.iter().enumerate() {
            if child.as_group().is_none() {
                return Err(shape(
                    base_path.with_child(index),
                    Some(tagged.tag().clone()),
                    RdShapeErrorKind::UnexpectedNode {
                        expected: RdExpectedNode::Group,
                        actual: RdNodeKind::of(child),
                    },
                ));
            }
        }
        let generic_nodes = children[0].as_group().unwrap().children();
        let qualifier_nodes = children[1].as_group().unwrap().children();
        let generic = concat_exact(
            generic_nodes,
            RdNodeKind::Text,
            &base_path.with_child(0),
            tagged.tag(),
        )?;
        let qualifier = concat_exact(
            qualifier_nodes,
            RdNodeKind::Text,
            &base_path.with_child(1),
            tagged.tag(),
        )?;
        Ok(Some(RdMethod {
            path: base_path.clone(),
            kind,
            generic_nodes,
            generic,
            qualifier_nodes,
            qualifier,
        }))
    }
}