Skip to main content

ruby_prism/
string_query.rs

1//! Queries for whether a string is a valid name of a given kind in Ruby.
2
3use std::ffi::{c_char, CString};
4use std::fmt;
5
6use ruby_prism_sys::{pm_string_query_constant, pm_string_query_keyword, pm_string_query_local, pm_string_query_method_name, pm_string_query_t, PM_STRING_QUERY_ERROR_VERSION, PM_STRING_QUERY_FALSE, PM_STRING_QUERY_TRUE};
7
8use crate::Version;
9
10/// The error returned when a string query is given an encoding that prism
11/// does not know or that is not ASCII-compatible.
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13pub struct InvalidEncodingError;
14
15impl fmt::Display for InvalidEncodingError {
16    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
17        write!(f, "Invalid or non ascii-compatible encoding")
18    }
19}
20
21impl std::error::Error for InvalidEncodingError {}
22
23/// Queries whether a string is a valid name of a given kind in Ruby.
24///
25/// The string is interpreted as UTF-8 unless another encoding is given with
26/// [`StringQuery::encoding`], and the answer is for the latest version of Ruby
27/// unless another version is given with [`StringQuery::version`].
28///
29/// ```
30/// use ruby_prism::StringQuery;
31///
32/// assert_eq!(Ok(true), StringQuery::new(b"foo").is_local());
33/// assert_eq!(Ok(true), StringQuery::new(b"Foo").is_constant());
34/// assert_eq!(Ok(true), StringQuery::new(b"foo?").is_method_name());
35/// assert_eq!(Ok(true), StringQuery::new(b"defined?").is_keyword());
36/// ```
37#[derive(Debug, Clone, Copy)]
38pub struct StringQuery<'a> {
39    source: &'a [u8],
40    encoding: &'a str,
41    version: Version,
42}
43
44impl<'a> StringQuery<'a> {
45    /// Creates a query for the given UTF-8 string.
46    #[must_use]
47    pub const fn new(source: &'a [u8]) -> Self {
48        Self { source, encoding: "UTF-8", version: Version::Latest }
49    }
50
51    /// Sets the name of the encoding that the string is in, such as
52    /// `"Windows-31J"` or `"US-ASCII"`.
53    #[must_use]
54    pub const fn encoding(mut self, encoding: &'a str) -> Self {
55        self.encoding = encoding;
56        self
57    }
58
59    /// Sets the version of Ruby to answer for. Which letters begin a constant
60    /// name depends on the version of Unicode that it uses.
61    #[must_use]
62    pub const fn version(mut self, version: Version) -> Self {
63        self.version = version;
64        self
65    }
66
67    /// Returns whether the string is a valid local variable name.
68    ///
69    /// # Errors
70    ///
71    /// Returns [`InvalidEncodingError`] if the encoding is unknown or not
72    /// ASCII-compatible.
73    pub fn is_local(&self) -> Result<bool, InvalidEncodingError> {
74        self.query(pm_string_query_local)
75    }
76
77    /// Returns whether the string is a valid constant name.
78    ///
79    /// # Errors
80    ///
81    /// Returns [`InvalidEncodingError`] if the encoding is unknown or not
82    /// ASCII-compatible.
83    pub fn is_constant(&self) -> Result<bool, InvalidEncodingError> {
84        self.query(pm_string_query_constant)
85    }
86
87    /// Returns whether the string is a valid method name.
88    ///
89    /// # Errors
90    ///
91    /// Returns [`InvalidEncodingError`] if the encoding is unknown or not
92    /// ASCII-compatible.
93    pub fn is_method_name(&self) -> Result<bool, InvalidEncodingError> {
94        self.query(pm_string_query_method_name)
95    }
96
97    /// Returns whether the string is a keyword (reserved word), such as `if`,
98    /// `defined?`, or `__FILE__`.
99    ///
100    /// # Errors
101    ///
102    /// Returns [`InvalidEncodingError`] if the encoding is unknown or not
103    /// ASCII-compatible.
104    pub fn is_keyword(&self) -> Result<bool, InvalidEncodingError> {
105        self.query(pm_string_query_keyword)
106    }
107
108    fn query(&self, function: unsafe extern "C" fn(*const u8, usize, *const c_char, *const c_char) -> pm_string_query_t) -> Result<bool, InvalidEncodingError> {
109        // An encoding name with an interior null byte cannot name a known encoding.
110        let encoding = CString::new(self.encoding).map_err(|_| InvalidEncodingError)?;
111
112        match unsafe { function(self.source.as_ptr(), self.source.len(), encoding.as_ptr(), self.version.as_ptr()) } {
113            PM_STRING_QUERY_TRUE => Ok(true),
114            PM_STRING_QUERY_FALSE => Ok(false),
115            PM_STRING_QUERY_ERROR_VERSION => unreachable!("every Version is a version that prism knows"),
116            _ => Err(InvalidEncodingError),
117        }
118    }
119}
120
121#[cfg(test)]
122mod tests {
123    use super::{InvalidEncodingError, StringQuery};
124
125    fn query(source: &str) -> StringQuery<'_> {
126        StringQuery::new(source.as_bytes())
127    }
128
129    #[test]
130    fn local_test() {
131        assert_eq!(Ok(true), query("a").is_local());
132        assert_eq!(Ok(true), query("a1").is_local());
133        assert_eq!(Ok(true), query("self").is_local());
134
135        assert_eq!(Ok(true), query("_a").is_local());
136        assert_eq!(Ok(true), query("_1").is_local());
137
138        assert_eq!(Ok(true), query("😀").is_local());
139        assert_eq!(Ok(true), StringQuery::new(b"\x83\x41").encoding("Windows-31J").is_local());
140
141        assert_eq!(Ok(false), query("1").is_local());
142        assert_eq!(Ok(false), query("A").is_local());
143    }
144
145    #[test]
146    fn constant_test() {
147        assert_eq!(Ok(true), query("A").is_constant());
148        assert_eq!(Ok(true), query("A1").is_constant());
149        assert_eq!(Ok(true), query("A_B").is_constant());
150        assert_eq!(Ok(true), query("BEGIN").is_constant());
151
152        assert_eq!(Ok(true), query("À").is_constant());
153        assert_eq!(Ok(true), query("A").encoding("US-ASCII").is_constant());
154
155        assert_eq!(Ok(false), query("a").is_constant());
156        assert_eq!(Ok(false), query("1").is_constant());
157    }
158
159    #[test]
160    fn method_name_test() {
161        assert_eq!(Ok(true), query("a").is_method_name());
162        assert_eq!(Ok(true), query("A").is_method_name());
163        assert_eq!(Ok(true), query("__FILE__").is_method_name());
164
165        assert_eq!(Ok(true), query("a?").is_method_name());
166        assert_eq!(Ok(true), query("a!").is_method_name());
167        assert_eq!(Ok(true), query("a=").is_method_name());
168
169        assert_eq!(Ok(true), query("+").is_method_name());
170        assert_eq!(Ok(true), query("<<").is_method_name());
171        assert_eq!(Ok(true), query("===").is_method_name());
172
173        assert_eq!(Ok(true), query("_0").is_method_name());
174
175        assert_eq!(Ok(false), query("1").is_method_name());
176        assert_eq!(Ok(false), query("_1").is_method_name());
177    }
178
179    #[test]
180    fn keyword_test() {
181        assert_eq!(Ok(true), query("end").is_keyword());
182        assert_eq!(Ok(true), query("defined?").is_keyword());
183        assert_eq!(Ok(true), query("__FILE__").is_keyword());
184        assert_eq!(Ok(true), query("end").encoding("US-ASCII").is_keyword());
185
186        assert_eq!(Ok(false), query("").is_keyword());
187        assert_eq!(Ok(false), query("foo").is_keyword());
188        assert_eq!(Ok(false), query("defined").is_keyword());
189        assert_eq!(Ok(false), query("End").is_keyword());
190    }
191
192    #[test]
193    fn subslice_test() {
194        // The byte after the slice is outside it and must not affect the result.
195        assert_eq!(Ok(true), StringQuery::new(&b"a!"[..1]).is_local());
196        assert_eq!(Ok(true), StringQuery::new(&b"Foo="[..3]).is_constant());
197        assert_eq!(Ok(true), StringQuery::new(&b"foo?"[..3]).is_method_name());
198    }
199
200    #[test]
201    fn invalid_encoding_test() {
202        assert_eq!(Err(InvalidEncodingError), query("A").encoding("UTF-16LE").is_local());
203        assert_eq!(Err(InvalidEncodingError), query("end").encoding("UTF-16LE").is_keyword());
204        assert_eq!(Err(InvalidEncodingError), query("end").encoding("UTF-\08").is_keyword());
205        assert_eq!(Err(InvalidEncodingError), query("end").encoding("not-an-encoding").is_keyword());
206    }
207}