extern crate self as fig;
mod diagnostics;
mod editor;
mod error;
mod language_crate;
mod value;
pub(crate) use fig_sys as ffi;
#[cfg(feature = "derive")]
mod convert;
#[cfg(feature = "serde")]
mod de;
#[cfg(feature = "serde")]
mod ser;
use std::os::raw::c_int;
use std::ptr::NonNull;
pub use diagnostics::{Warning, WarningCause, WarningCode};
pub use editor::{Editor, Segment};
#[cfg(feature = "helper")]
pub mod helper;
pub mod kit;
pub mod language;
#[cfg(test)]
mod test_languages;
pub use error::{Error, LanguageFailure, ParseError};
pub use value::{ExtKind, Value};
#[cfg(feature = "derive")]
pub use convert::{FromValue, ToValue};
#[cfg(feature = "derive")]
#[doc(hidden)]
pub use convert::{field, field_or_default, map_get};
#[cfg(feature = "derive")]
pub use fig_macros::{FromValue, ToValue};
#[cfg(feature = "serde")]
pub use de::from_slice;
#[cfg(feature = "serde")]
pub use ser::to_value;
use ffi::{FIG_NODE_NONE, FigNodeId, FigNodeKind};
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub struct Span {
pub start: usize,
pub end: usize,
}
impl From<std::ops::Range<usize>> for Span {
fn from(r: std::ops::Range<usize>) -> Self {
Span {
start: r.start,
end: r.end,
}
}
}
impl From<Span> for std::ops::Range<usize> {
fn from(s: Span) -> Self {
s.start..s.end
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Format(c_int);
impl Format {
pub(crate) fn to_c(self) -> c_int {
self.0
}
pub(crate) fn from_c(value: c_int) -> Option<Format> {
if value <= 0 || unsafe { ffi::fig_format_name(value) }.is_null() {
return None;
}
Some(Format(value))
}
pub fn by_name(name: &str) -> Option<Format> {
let c = std::ffi::CString::new(name).ok()?;
let value = unsafe { ffi::fig_format_by_name(c.as_ptr()) };
if value <= 0 {
return None;
}
Some(Format(value))
}
pub fn name(self) -> &'static str {
let ptr = unsafe { ffi::fig_format_name(self.0) };
if ptr.is_null() {
return "";
}
unsafe { std::ffi::CStr::from_ptr(ptr) }
.to_str()
.unwrap_or("")
}
pub fn split_stream(self, input: &[u8]) -> Result<Vec<language::StreamDocument>, Error> {
let mut docs: *mut ffi::FigStreamDoc = std::ptr::null_mut();
let mut count = 0usize;
let mut err = ffi::FigError::new();
let status = unsafe {
ffi::fig_stream_split(
input.as_ptr(),
input.len(),
self.to_c(),
&mut docs,
&mut count,
&mut err,
)
};
if status == ffi::FigStatus::PARSE_ERROR {
return Err(Error::Parse(crate::error::ParseError::from_ffi(&err)));
}
Error::from_status(status)?;
let out = (0..count)
.map(|i| {
let d = unsafe { *docs.add(i) };
language::StreamDocument {
start: d.start,
end: d.end,
explicit: d.marked,
}
})
.collect();
unsafe { ffi::fig_stream_free(docs, count) };
Ok(out)
}
pub fn detect(input: &[u8], order: &[&str]) -> Option<Format> {
let names: Vec<std::ffi::CString> = order
.iter()
.filter_map(|n| std::ffi::CString::new(*n).ok())
.collect();
let ptrs: Vec<*const std::os::raw::c_char> = names.iter().map(|n| n.as_ptr()).collect();
let mut out: std::os::raw::c_int = -1;
let status = unsafe {
ffi::fig_detect_order(
input.as_ptr(),
input.len(),
ptrs.as_ptr(),
ptrs.len(),
&mut out,
)
};
if status != ffi::FigStatus::OK {
return None;
}
Format::from_c(out)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct SerializeOptions {
pub pretty: bool,
pub indent: u8,
pub strip_comments: bool,
pub lossless: bool,
pub width: u16,
}
impl Default for SerializeOptions {
fn default() -> Self {
Self {
pretty: true,
indent: 2,
strip_comments: false,
lossless: false,
width: 80,
}
}
}
impl SerializeOptions {
pub fn compact() -> Self {
Self {
pretty: false,
..Self::default()
}
}
pub fn pretty(indent: u8) -> Self {
Self {
pretty: true,
indent,
..Self::default()
}
}
pub fn indent(self, indent: u8) -> Self {
Self { indent, ..self }
}
pub fn lossless(self) -> Self {
Self {
lossless: true,
..self
}
}
pub fn strip_comments(self) -> Self {
Self {
strip_comments: true,
..self
}
}
pub fn width(self, width: u16) -> Self {
Self { width, ..self }
}
}
impl From<SerializeOptions> for ffi::FigSerializeOptions {
fn from(o: SerializeOptions) -> Self {
ffi::FigSerializeOptions {
size: std::mem::size_of::<ffi::FigSerializeOptions>() as u32,
pretty: u8::from(o.pretty),
indent: o.indent,
strip_comments: u8::from(o.strip_comments),
lossless: u8::from(o.lossless),
width: o.width,
flow: 0,
splice: 0,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct Version {
pub major: u8,
pub minor: u8,
pub patch: u8,
}
pub fn version() -> Version {
let packed = unsafe { ffi::fig_version() };
Version {
major: (packed >> 16) as u8,
minor: (packed >> 8) as u8,
patch: packed as u8,
}
}
pub fn version_string() -> &'static str {
let ptr = unsafe { ffi::fig_version_string() };
unsafe { std::ffi::CStr::from_ptr(ptr) }
.to_str()
.unwrap_or("")
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct Capabilities {
pub read: bool,
pub edit: bool,
pub serialize: bool,
pub references: bool,
}
impl Capabilities {
pub const fn new(read: bool, edit: bool, serialize: bool) -> Self {
Capabilities {
read,
edit,
serialize,
references: false,
}
}
pub const fn with_references(mut self, references: bool) -> Self {
self.references = references;
self
}
}
pub fn capabilities(format: Format) -> Capabilities {
let bits = unsafe { ffi::fig_format_capabilities(format.to_c()) };
Capabilities {
read: bits & (1 << 0) != 0,
edit: bits & (1 << 1) != 0,
serialize: bits & (1 << 2) != 0,
references: bits & (1 << 3) != 0,
}
}
#[derive(Debug)]
pub struct Document {
raw: NonNull<ffi::FigDocument>,
}
unsafe impl Send for Document {}
impl Document {
pub fn parse(input: &[u8], format: Format) -> Result<Self, Error> {
let mut raw = std::ptr::null_mut();
let mut err = ffi::FigError::new();
let status = unsafe {
ffi::fig_parse_ex(
input.as_ptr(),
input.len(),
format.to_c(),
&mut raw,
&mut err,
)
};
if status != ffi::FigStatus::OK {
if status == ffi::FigStatus::PARSE_ERROR {
return Err(Error::Parse(crate::error::ParseError::from_ffi(&err)));
}
Error::from_status(status)?;
}
let raw = NonNull::new(raw).ok_or(Error::Internal)?;
Ok(Self { raw })
}
}
impl Document {
pub fn to_value(&self) -> Result<Value, Error> {
let resolved = self.resolve_aliases()?;
let doc = resolved.as_ref().unwrap_or(self);
match doc.root() {
None => Ok(Value::Null),
Some(id) => doc.node_to_value(id),
}
}
pub(crate) fn resolve_aliases(&self) -> Result<Option<Document>, Error> {
let mut raw = std::ptr::null_mut();
let mut err = ffi::FigError::new();
let status = unsafe { ffi::fig_document_resolve_aliases(self.ptr(), &mut raw, &mut err) };
if status == ffi::FigStatus::PARSE_ERROR {
return Err(Error::Parse(crate::error::ParseError::from_ffi(&err)));
}
Error::from_status(status)?;
Ok(NonNull::new(raw).map(|raw| Document { raw }))
}
fn node_to_value(&self, id: FigNodeId) -> Result<Value, Error> {
if let Some((kind, text)) = self.extended(id) {
return Ok(Value::Extended { kind, text });
}
let kind = self.kind(id);
match kind {
FigNodeKind::Null => Ok(Value::Null),
FigNodeKind::Bool => Ok(Value::Bool(self.get_bool(id).ok_or(Error::Internal)?)),
FigNodeKind::Int | FigNodeKind::Float => {
let raw = self.number_raw(id).ok_or(Error::Internal)??;
Value::parse_number(raw, kind == FigNodeKind::Float)
}
FigNodeKind::String => Ok(Value::Str(
self.get_str(id).ok_or(Error::Internal)??.to_owned(),
)),
FigNodeKind::Sequence => {
let mut items = Vec::with_capacity(self.child_count(id));
let mut next = self.first_child(id);
while let Some(child) = next {
items.push(self.node_to_value(child)?);
next = self.next_sibling(child);
}
Ok(Value::Seq(items))
}
FigNodeKind::Mapping => {
let mut entries = Vec::with_capacity(self.child_count(id));
let mut next = self.first_child(id);
while let Some(kv) = next {
let key = self.kv_key(kv).ok_or(Error::Internal)?;
let value = match self.kv_value(kv) {
Some(vid) => self.node_to_value(vid)?,
None => Value::Null,
};
entries.push((self.node_to_value(key)?, value));
next = self.next_sibling(kv);
}
Ok(Value::Map(entries))
}
FigNodeKind::Keyvalue
| FigNodeKind::Invalid
| FigNodeKind::Alias
| FigNodeKind::Extended => Err(Error::Internal),
}
}
fn ptr(&self) -> *const ffi::FigDocument {
self.raw.as_ptr()
}
pub(crate) fn root(&self) -> Option<FigNodeId> {
normalize(unsafe { ffi::fig_document_root(self.ptr()) })
}
pub(crate) fn kind(&self, node: FigNodeId) -> FigNodeKind {
match FigNodeKind::from_c(unsafe { ffi::fig_node_kind(self.ptr(), node) }) {
FigNodeKind::Extended => match self.extended(node) {
Some((ExtKind::CharLiteral, _)) => FigNodeKind::Int,
_ => FigNodeKind::String,
},
k => k,
}
}
pub(crate) fn first_child(&self, node: FigNodeId) -> Option<FigNodeId> {
normalize(unsafe { ffi::fig_node_first_child(self.ptr(), node) })
}
pub(crate) fn next_sibling(&self, node: FigNodeId) -> Option<FigNodeId> {
normalize(unsafe { ffi::fig_node_next_sibling(self.ptr(), node) })
}
pub(crate) fn child_count(&self, node: FigNodeId) -> usize {
unsafe { ffi::fig_node_child_count(self.ptr(), node) }
}
pub(crate) fn kv_key(&self, node: FigNodeId) -> Option<FigNodeId> {
normalize(unsafe { ffi::fig_keyvalue_key(self.ptr(), node) })
}
pub(crate) fn kv_value(&self, node: FigNodeId) -> Option<FigNodeId> {
normalize(unsafe { ffi::fig_keyvalue_value(self.ptr(), node) })
}
pub(crate) fn get_bool(&self, node: FigNodeId) -> Option<bool> {
let mut out = false;
unsafe { ffi::fig_node_bool(self.ptr(), node, &mut out) }.then_some(out)
}
pub(crate) fn number_raw(&self, node: FigNodeId) -> Option<Result<&str, Error>> {
self.scalar_bytes(node, ffi::fig_node_number)
.map(|bytes| std::str::from_utf8(bytes).map_err(|_| Error::Utf8))
}
pub(crate) fn get_str(&self, node: FigNodeId) -> Option<Result<&str, Error>> {
self.scalar_bytes(node, ffi::fig_node_string)
.map(|bytes| std::str::from_utf8(bytes).map_err(|_| Error::Utf8))
}
pub(crate) fn extended(&self, node: FigNodeId) -> Option<(ExtKind, String)> {
let mut kind: c_int = 0;
let mut ptr: *const u8 = std::ptr::null();
let mut len: usize = 0;
let ok = unsafe { ffi::fig_node_extended(self.ptr(), node, &mut kind, &mut ptr, &mut len) };
if !ok {
return None;
}
let ext = ExtKind::from_c(kind)?;
let text = if len == 0 {
String::new()
} else {
let bytes = unsafe { std::slice::from_raw_parts(ptr, len) };
std::str::from_utf8(bytes).ok()?.to_owned()
};
Some((ext, text))
}
fn scalar_bytes(
&self,
node: FigNodeId,
accessor: unsafe extern "C" fn(
*const ffi::FigDocument,
FigNodeId,
*mut *const u8,
*mut usize,
) -> bool,
) -> Option<&[u8]> {
let mut ptr: *const u8 = std::ptr::null();
let mut len: usize = 0;
let ok = unsafe { accessor(self.ptr(), node, &mut ptr, &mut len) };
if !ok {
return None;
}
if len == 0 {
return Some(&[]);
}
Some(unsafe { std::slice::from_raw_parts(ptr, len) })
}
}
impl Document {
pub fn serialize(&self, format: Format) -> Result<String, Error> {
self.serialize_with(format, SerializeOptions::default())
}
pub fn serialize_with(
&self,
format: Format,
options: SerializeOptions,
) -> Result<String, Error> {
let ffi_options: ffi::FigSerializeOptions = options.into();
let mut ptr_out: *const u8 = std::ptr::null();
let mut len: usize = 0;
Error::from_status(unsafe {
ffi::fig_document_serialize(
self.raw.as_ptr(),
format.to_c(),
&ffi_options,
&mut ptr_out,
&mut len,
)
})?;
let bytes = if len == 0 {
&[][..]
} else {
unsafe { std::slice::from_raw_parts(ptr_out, len) }
};
Ok(std::str::from_utf8(bytes)
.map_err(|_| Error::Utf8)?
.to_owned())
}
pub fn diagnose(
&self,
format: Format,
options: SerializeOptions,
) -> Result<Vec<Warning>, Error> {
let ffi_options: ffi::FigSerializeOptions = options.into();
let mut count: usize = 0;
Error::from_status(unsafe {
ffi::fig_document_diagnose(self.raw.as_ptr(), format.to_c(), &ffi_options, &mut count)
})?;
let mut out = Vec::with_capacity(count);
for i in 0..count {
let mut w = ffi::FigWarning::new();
Error::from_status(unsafe { ffi::fig_document_warning(self.raw.as_ptr(), i, &mut w) })?;
out.push(unsafe { Warning::from_ffi(&w) });
}
Ok(out)
}
}
impl Drop for Document {
fn drop(&mut self) {
unsafe {
ffi::fig_document_destroy(self.raw.as_ptr());
}
}
}
fn normalize(id: FigNodeId) -> Option<FigNodeId> {
if id == FIG_NODE_NONE { None } else { Some(id) }
}
#[cfg(test)]
mod tests {
use super::{Document, Error};
use crate::test_languages::by_name;
#[test]
fn parses_json_document() {
let doc = Document::parse(br#"{"name":"fig","ok":true}"#, by_name("json"));
assert!(doc.is_ok());
}
#[test]
fn parse_error_is_reported() {
let err = Document::parse(br#"{"name":"fig""#, by_name("json")).unwrap_err();
let Error::Parse(detail) = &err else {
panic!("expected Error::Parse, got {err:?}");
};
assert!(!detail.message.is_empty());
assert_eq!(detail.byte_offset, Some(13));
}
#[test]
fn version_and_capabilities() {
use super::{capabilities, version, version_string};
let v = version();
assert_eq!(
version_string(),
format!("{}.{}.{}", v.major, v.minor, v.patch)
);
let json = capabilities(by_name("json"));
assert!(json.read && json.edit && json.serialize);
}
#[test]
fn document_serialize_converts_cross_format() {
let doc = Document::parse(b"name: fig\nnums:\n- 1\n- 2\n", by_name("yaml")).unwrap();
assert_eq!(
doc.serialize(by_name("json")).unwrap(),
"{\n \"name\": \"fig\",\n \"nums\": [\n 1,\n 2\n ]\n}\n",
);
}
#[test]
fn document_diagnose_reports_dropped_null() {
use super::{SerializeOptions, WarningCause, WarningCode};
let doc = Document::parse(b"a: null\nb: 1\n", by_name("yaml")).unwrap();
let warns = doc
.diagnose(by_name("toml"), SerializeOptions::default())
.unwrap();
assert_eq!(warns.len(), 1);
assert_eq!(warns[0].code, WarningCode::ValueDropped);
assert_eq!(warns[0].cause, WarningCause::FormatLimitation);
assert_eq!(warns[0].path, "a");
let none = doc
.diagnose(by_name("toml"), SerializeOptions::default().lossless())
.unwrap();
assert!(none.is_empty());
}
#[test]
fn parse_error_message_is_surfaced_in_display() {
let err = Document::parse(br#"{"name":"fig""#, by_name("json")).unwrap_err();
assert!(err.to_string().starts_with("failed to parse input: "));
}
#[test]
fn editor_comment_ops_add_set_and_delete() {
use super::{Editor, Segment};
let mut ed = Editor::open(b"a: 1\nb: 2\n", by_name("yaml")).unwrap();
ed.add_leading_comment(&[Segment::Key("b")], "why").unwrap();
ed.set_trailing_comment(&[Segment::Key("b")], "two")
.unwrap();
assert_eq!(ed.source().unwrap(), "a: 1\n# why\nb: 2 # two\n");
ed.delete_trailing_comment(&[Segment::Key("b")]).unwrap();
ed.delete_leading_comment(&[Segment::Key("b")]).unwrap();
assert_eq!(ed.source().unwrap(), "a: 1\nb: 2\n");
}
#[test]
fn editor_comments_unsupported_in_strict_json() {
use super::{Editor, Error, Segment};
let mut ed = Editor::open(br#"{"a":1}"#, by_name("json")).unwrap();
assert!(matches!(
ed.add_leading_comment(&[Segment::Key("a")], "x"),
Err(Error::UnsupportedFormat)
));
}
}