aspire 0.4.0

Rust bindings for Clingo
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
138
139
140
141
142
143
144
145
146
147
148
149

use std::ffi::{CStr, CString};
use std::marker::PhantomData;
use std::os::raw::c_char;

use crate::control::Control;
use crate::error::{ClingoError, Error, check};

/// A view into clingo's configuration tree.
///
/// Borrows the `Control` mutably, preventing concurrent access.
///
/// Configuration entries are either maps (with string keys), arrays,
/// or leaf values (strings). Navigate with [`map_at`](Self::map_at),
/// [`array_at`](Self::array_at), and read/write with
/// [`value`](Self::value) / [`set_value`](Self::set_value).
///
/// For convenience, [`get`](Self::get) and [`set`](Self::set) accept
/// dot-separated paths like `"solve.models"` or `"solver.0.heuristic"`.
pub struct Configuration<'a> {
    ptr: *mut clingo_sys::clingo_configuration_t,
    key: clingo_sys::clingo_id_t,
    _lifetime: PhantomData<&'a mut Control>,
}

impl<'a> Configuration<'a> {
    /// # Safety
    /// `ptr` must be a valid configuration pointer that lives for `'a`,
    /// and no other mutable access to the underlying `Control` may occur
    /// for the lifetime `'a`.
    pub(crate) unsafe fn new(
        ptr: *mut clingo_sys::clingo_configuration_t,
        key: clingo_sys::clingo_id_t,
    ) -> Self {
        Configuration {
            ptr,
            key,
            _lifetime: PhantomData,
        }
    }

    /// Get a sub-entry of a map by name.
    pub fn map_at(&self, name: &str) -> Result<Configuration<'a>, Error> {
        let c_name = CString::new(name)?;
        let mut subkey: clingo_sys::clingo_id_t = 0;
        check(unsafe {
            clingo_sys::clingo_configuration_map_at(
                self.ptr,
                self.key,
                c_name.as_ptr(),
                &mut subkey,
            )
        })?;
        Ok(Configuration {
            ptr: self.ptr,
            key: subkey,
            _lifetime: self._lifetime,
        })
    }

    /// Get a sub-entry of an array by index.
    pub fn array_at(&self, index: usize) -> Result<Configuration<'a>, ClingoError> {
        let mut subkey: clingo_sys::clingo_id_t = 0;
        check(unsafe {
            clingo_sys::clingo_configuration_array_at(self.ptr, self.key, index, &mut subkey)
        })?;
        Ok(Configuration {
            ptr: self.ptr,
            key: subkey,
            _lifetime: self._lifetime,
        })
    }

    /// Read the string value of a leaf entry.
    pub fn value(&self) -> Result<Option<String>, ClingoError> {
        let mut assigned = false;
        check(unsafe {
            clingo_sys::clingo_configuration_value_is_assigned(self.ptr, self.key, &mut assigned)
        })?;
        if !assigned {
            return Ok(None);
        }

        let mut size: usize = 0;
        check(unsafe {
            clingo_sys::clingo_configuration_value_get_size(self.ptr, self.key, &mut size)
        })?;
        let mut buf = vec![0u8; size];
        check(unsafe {
            clingo_sys::clingo_configuration_value_get(
                self.ptr,
                self.key,
                buf.as_mut_ptr() as *mut c_char,
                size,
            )
        })?;
        buf.pop(); // remove NUL
        Ok(Some(String::from_utf8_lossy(&buf).into_owned()))
    }

    /// Set the string value of a leaf entry.
    pub fn set_value(&mut self, value: &str) -> Result<(), Error> {
        let c_value = CString::new(value)?;
        check(unsafe {
            clingo_sys::clingo_configuration_value_set(self.ptr, self.key, c_value.as_ptr())
        })?;
        Ok(())
    }

    /// Navigate a dot-separated path and read the value.
    ///
    /// Array indices are specified as numbers: `"solver.0.heuristic"`.
    pub fn get(&self, path: &str) -> Result<Option<String>, Error> {
        let entry = self.walk(path)?;
        Ok(entry.value()?)
    }

    /// Navigate a dot-separated path and set the value.
    pub fn set(&mut self, path: &str, value: &str) -> Result<(), Error> {
        let mut entry = self.walk(path)?;
        entry.set_value(value)
    }

    /// Get the description of this configuration entry.
    pub fn description(&self) -> Result<&str, ClingoError> {
        let mut ptr: *const c_char = std::ptr::null();
        check(unsafe {
            clingo_sys::clingo_configuration_description(self.ptr, self.key, &mut ptr)
        })?;
        Ok(unsafe { CStr::from_ptr(ptr) }
            .to_str()
            .expect("clingo config description not UTF-8"))
    }

    fn walk(&self, path: &str) -> Result<Configuration<'a>, Error> {
        let mut current = Configuration {
            ptr: self.ptr,
            key: self.key,
            _lifetime: self._lifetime,
        };
        for segment in path.split('.') {
            if let Ok(index) = segment.parse::<usize>() {
                current = current.array_at(index)?;
            } else {
                current = current.map_at(segment)?;
            }
        }
        Ok(current)
    }
}