]> git.nihav.org Git - nihav.git/blob - nihav-core/src/options.rs
core/soundcvt: typo
[nihav.git] / nihav-core / src / options.rs
1 //! Options support.
2 //!
3 //! This module contains the definitions for options and names for common options.
4 //! Options are used to set custom parameters in e.g. decoders or muxers.
5 //!
6 //! As a rule target for options should provide a list of supported options and ignore unknown options.
7
8 use std::sync::Arc;
9 use std::fmt;
10
11 pub use crate::compr::deflate::{DEFLATE_MODE_DESCRIPTION, DEFLATE_OPTION_VALUES, DEFLATE_MODE_NONE, DEFLATE_MODE_FAST, DEFLATE_MODE_BETTER, DEFLATE_MODE_BEST};
12
13 /// Common name for keyframe interval option.
14 pub const KEYFRAME_OPTION: &str = "key_int";
15 /// Common description for keyframe interval option.
16 pub const KEYFRAME_OPTION_DESC: &str = "Keyframe interval (0 - automatic)";
17
18 /// Common name for frame skipping mode.
19 pub const FRAME_SKIP_OPTION: &str = "frame_skip";
20 /// Common description for frame skipping mode.
21 pub const FRAME_SKIP_OPTION_DESC: &str = "Frame skipping mode";
22 /// Frame skipping option value for no skipped frames.
23 pub const FRAME_SKIP_OPTION_VAL_NONE: &str = "none";
24 /// Frame skipping option value for decoding only keyframes.
25 pub const FRAME_SKIP_OPTION_VAL_KEYFRAME: &str = "keyframes";
26 /// Frame skipping option value for decoding only intra frames.
27 pub const FRAME_SKIP_OPTION_VAL_INTRA: &str = "intra";
28
29 /// A list specifying option parsing and validating errors.
30 #[derive(Clone,Copy,Debug,PartialEq)]
31 pub enum OptionError {
32 /// Input is not intended for the current option definition.
33 WrongName,
34 /// Option value is not in the expected format.
35 InvalidFormat,
36 /// Option value was not in the range.
37 InvalidValue,
38 /// Parse error.
39 ParseError,
40 }
41
42 /// A specialised `Result` type for option parsing/validation.
43 pub type OptionResult<T> = Result<T, OptionError>;
44
45 /// Option definition type.
46 #[derive(Debug)]
47 pub enum NAOptionDefinitionType {
48 /// Option may just be present.
49 None,
50 /// Option is a boolean value.
51 Bool,
52 /// Option is an integer with optional minimum and maximum value.
53 Int(Option<i64>, Option<i64>),
54 /// Option is a floating point number with optional minimum and maximum value.
55 Float(Option<f64>, Option<f64>),
56 /// Option is a string with an optional list of allowed values.
57 String(Option<&'static [&'static str]>),
58 /// Option is some binary data.
59 Data,
60 }
61
62 /// Option definition.
63 #[derive(Debug)]
64 pub struct NAOptionDefinition {
65 /// Option name.
66 pub name: &'static str,
67 /// Option meaning.
68 pub description: &'static str,
69 /// Option type.
70 pub opt_type: NAOptionDefinitionType,
71 }
72
73 impl NAOptionDefinition {
74 /// Tries to parse input string(s) as an option and returns new option and number of arguments used (1 or 2) on success.
75 pub fn parse(&self, name: &str, value: Option<&String>) -> OptionResult<(NAOption, usize)> {
76 let no_name = "no".to_owned() + self.name;
77 let opt_no_name = "--no".to_owned() + self.name;
78 if name == no_name || name == opt_no_name {
79 match self.opt_type {
80 NAOptionDefinitionType::Bool => return Ok((NAOption { name: self.name, value: NAValue::Bool(false) }, 1)),
81 _ => return Err(OptionError::InvalidFormat),
82 };
83 }
84 let opt_name = "--".to_owned() + self.name;
85 if self.name != name && opt_name != name {
86 return Err(OptionError::WrongName);
87 }
88 match self.opt_type {
89 NAOptionDefinitionType::None => Ok((NAOption { name: self.name, value: NAValue::None }, 1)),
90 NAOptionDefinitionType::Bool => Ok((NAOption { name: self.name, value: NAValue::Bool(true) }, 1)),
91 NAOptionDefinitionType::Int(_, _) => {
92 if let Some(strval) = value {
93 let ret = strval.parse::<i64>();
94 if let Ok(val) = ret {
95 let opt = NAOption { name: self.name, value: NAValue::Int(val) };
96 self.check(&opt)?;
97 Ok((opt, 2))
98 } else {
99 Err(OptionError::ParseError)
100 }
101 } else {
102 Err(OptionError::ParseError)
103 }
104 },
105 NAOptionDefinitionType::Float(_, _) => {
106 if let Some(strval) = value {
107 let ret = strval.parse::<f64>();
108 if let Ok(val) = ret {
109 let opt = NAOption { name: self.name, value: NAValue::Float(val) };
110 self.check(&opt)?;
111 Ok((opt, 2))
112 } else {
113 Err(OptionError::ParseError)
114 }
115 } else {
116 Err(OptionError::ParseError)
117 }
118 },
119 NAOptionDefinitionType::String(_) => {
120 if let Some(strval) = value {
121 let opt = NAOption { name: self.name, value: NAValue::String(strval.to_string()) };
122 self.check(&opt)?;
123 Ok((opt, 2))
124 } else {
125 Err(OptionError::ParseError)
126 }
127 },
128 _ => unimplemented!(),
129 }
130 }
131 /// Checks whether input option conforms to the definition i.e. whether it has proper format and it lies in range.
132 pub fn check(&self, option: &NAOption) -> OptionResult<()> {
133 if option.name != self.name {
134 return Err(OptionError::WrongName);
135 }
136 match option.value {
137 NAValue::None => Ok(()),
138 NAValue::Bool(_) => Ok(()),
139 NAValue::Int(intval) => {
140 match self.opt_type {
141 NAOptionDefinitionType::Int(minval, maxval) => {
142 if let Some(minval) = minval {
143 if intval < minval { return Err(OptionError::InvalidValue); }
144 }
145 if let Some(maxval) = maxval {
146 if intval > maxval { return Err(OptionError::InvalidValue); }
147 }
148 },
149 NAOptionDefinitionType::Float(minval, maxval) => {
150 let fval = intval as f64;
151 if let Some(minval) = minval {
152 if fval < minval { return Err(OptionError::InvalidValue); }
153 }
154 if let Some(maxval) = maxval {
155 if fval > maxval { return Err(OptionError::InvalidValue); }
156 }
157 },
158 _ => return Err(OptionError::InvalidFormat),
159 };
160 Ok(())
161 },
162 NAValue::Float(fval) => {
163 match self.opt_type {
164 NAOptionDefinitionType::Int(minval, maxval) => {
165 let intval = fval as i64;
166 if let Some(minval) = minval {
167 if intval < minval { return Err(OptionError::InvalidValue); }
168 }
169 if let Some(maxval) = maxval {
170 if intval > maxval { return Err(OptionError::InvalidValue); }
171 }
172 },
173 NAOptionDefinitionType::Float(minval, maxval) => {
174 if let Some(minval) = minval {
175 if fval < minval { return Err(OptionError::InvalidValue); }
176 }
177 if let Some(maxval) = maxval {
178 if fval > maxval { return Err(OptionError::InvalidValue); }
179 }
180 },
181 _ => return Err(OptionError::InvalidFormat),
182 };
183 Ok(())
184 },
185 NAValue::String(ref cur_str) => {
186 if let NAOptionDefinitionType::String(Some(strings)) = self.opt_type {
187 for string in strings.iter() {
188 if cur_str == string {
189 return Ok(());
190 }
191 }
192 Err(OptionError::InvalidValue)
193 } else {
194 Ok(())
195 }
196 },
197 NAValue::Data(_) => Ok(()),
198 }
199 }
200 }
201
202 impl fmt::Display for NAOptionDefinition {
203 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
204 match self.opt_type {
205 NAOptionDefinitionType::None => write!(f, "{}: {}", self.name, self.description),
206 NAOptionDefinitionType::Bool => write!(f, "[no]{}: {}", self.name, self.description),
207 NAOptionDefinitionType::String(ref str_list) => {
208 if let Some(opts) = str_list {
209 write!(f, "{} {}: {}", self.name, opts.join("|"), self.description)
210 } else {
211 write!(f, "{} <string>: {}", self.name, self.description)
212 }
213 },
214 NAOptionDefinitionType::Int(minval, maxval) => {
215 let range = match (&minval, &maxval) {
216 (Some(minval), None) => format!("{}-..", minval),
217 (None, Some(maxval)) => format!("..-{}", maxval),
218 (Some(minval), Some(maxval)) => format!("{}-{}", minval, maxval),
219 _ => "<integer>".to_string(),
220 };
221 write!(f, "{} {}: {}", self.name, range, self.description)
222 },
223 NAOptionDefinitionType::Float(minval, maxval) => {
224 let range = match (&minval, &maxval) {
225 (Some(minval), None) => format!("{}-..", minval),
226 (None, Some(maxval)) => format!("..-{}", maxval),
227 (Some(minval), Some(maxval)) => format!("{}-{}", minval, maxval),
228 _ => "<float>".to_string(),
229 };
230 write!(f, "{} {}: {}", self.name, range, self.description)
231 },
232 NAOptionDefinitionType::Data => write!(f, "{} <binary data>: {}", self.name, self.description),
233 }
234 }
235 }
236
237 /// Option.
238 #[derive(Clone,Debug,PartialEq)]
239 pub struct NAOption {
240 /// Option name.
241 pub name: &'static str,
242 /// Option value.
243 pub value: NAValue,
244 }
245
246 /// A list of accepted option values.
247 #[derive(Debug,Clone,PartialEq)]
248 pub enum NAValue {
249 /// Empty value.
250 None,
251 /// Boolean value.
252 Bool(bool),
253 /// Integer value.
254 Int(i64),
255 /// Floating point value.
256 Float(f64),
257 /// String value.
258 String(String),
259 /// Binary data value.
260 Data(Arc<Vec<u8>>),
261 }
262
263 /// Trait for all objects that handle `NAOption`.
264 pub trait NAOptionHandler {
265 /// Returns the options recognised by current object.
266 fn get_supported_options(&self) -> &[NAOptionDefinition];
267 /// Passes options for the object to set (or ignore).
268 fn set_options(&mut self, options: &[NAOption]);
269 /// Queries the current option value in the object (if present).
270 fn query_option_value(&self, name: &str) -> Option<NAValue>;
271 }
272
273 #[cfg(test)]
274 mod test {
275 use super::*;
276 #[test]
277 fn test_option_validation() {
278 let option = NAOption {name: "option", value: NAValue::Int(42) };
279 let mut def = NAOptionDefinition { name: "option", description: "", opt_type: NAOptionDefinitionType::Int(None, None) };
280 assert!(def.check(&option).is_ok());
281 def.opt_type = NAOptionDefinitionType::Int(None, Some(30));
282 assert_eq!(def.check(&option), Err(OptionError::InvalidValue));
283 def.opt_type = NAOptionDefinitionType::Int(Some(40), None);
284 assert!(def.check(&option).is_ok());
285 def.name = "option2";
286 assert_eq!(def.check(&option), Err(OptionError::WrongName));
287 let option = NAOption {name: "option", value: NAValue::String("test".to_string()) };
288 let mut def = NAOptionDefinition { name: "option", description: "", opt_type: NAOptionDefinitionType::String(None) };
289 assert!(def.check(&option).is_ok());
290 def.opt_type = NAOptionDefinitionType::String(Some(&["a string", "test string"]));
291 assert_eq!(def.check(&option), Err(OptionError::InvalidValue));
292 def.opt_type = NAOptionDefinitionType::String(Some(&["a string", "test"]));
293 assert!(def.check(&option).is_ok());
294 }
295 #[test]
296 fn test_option_parsing() {
297 let mut def = NAOptionDefinition { name: "option", description: "", opt_type: NAOptionDefinitionType::Float(None, None) };
298 assert_eq!(def.parse("--option", None), Err(OptionError::ParseError));
299 assert_eq!(def.parse("--nooption", None), Err(OptionError::InvalidFormat));
300 assert_eq!(def.parse("--option", Some(&"42".to_string())),
301 Ok((NAOption{name:"option",value: NAValue::Float(42.0)}, 2)));
302 def.opt_type = NAOptionDefinitionType::Float(None, Some(40.0));
303 assert_eq!(def.parse("--option", Some(&"42".to_string())),
304 Err(OptionError::InvalidValue));
305 let def = NAOptionDefinition { name: "option", description: "", opt_type: NAOptionDefinitionType::Bool };
306 assert_eq!(def.parse("option", None),
307 Ok((NAOption{name: "option", value: NAValue::Bool(true) }, 1)));
308 assert_eq!(def.parse("nooption", None),
309 Ok((NAOption{name: "option", value: NAValue::Bool(false) }, 1)));
310 }
311 }