maraiah: more documentation
parent
e64f652281
commit
17b5456aca
|
|
@ -9,13 +9,7 @@ is derived from the Japanese transliteration of "Mariah," and is pronounced
|
|||
The basis of this project is the Rust project `maraiah` which provides functions
|
||||
and structures to build applications which work with Marathon's data.
|
||||
|
||||
Maraiah comes with a set of almost fully portable tools written in Rust,
|
||||
including binary file reading, safe C-like `enum` reading, improved error
|
||||
handling, FFI tools, fixed point numbers, and image and sound structures.
|
||||
|
||||
Maraiah also comes with APIs for working with various data formats, primarily
|
||||
Marathon's. It also handles Macintosh PICT files, Portable PixMap, TARGA, RIFF
|
||||
WAVE, and more.
|
||||
See [the crate documentation](source/lib.rs) for more information.
|
||||
|
||||
## `maraiah-leela`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
#![doc(hidden)]
|
||||
|
||||
/// Creates an enumeration and function for converting a representation into
|
||||
/// the enumeration type.
|
||||
/// Creates an enumeration and function for converting a representation into the
|
||||
/// enumeration type.
|
||||
///
|
||||
/// The syntax is similar to the `bitflags` macro, but each value has the
|
||||
/// syntax `value => enumeration`. `enum` is used instead of `struct`.
|
||||
/// The syntax is similar to the `bitflags` macro, but each value has the syntax
|
||||
/// `value = enumeration`. `enum` is used instead of `struct`.
|
||||
///
|
||||
/// This will generate an `enum $t` as well as implement `TryFrom` on it which
|
||||
/// will return `Result<$t, ReprError>`.
|
||||
|
|
@ -39,7 +39,7 @@ macro_rules! c_enum
|
|||
$(#[$outer:meta])*
|
||||
$vi:vis enum $t:ident: $ti:ident
|
||||
{
|
||||
$($en:ident = $va:expr),+ $(,)?
|
||||
$($(#[$vouter:meta])* $en:ident = $va:expr),+ $(,)?
|
||||
}
|
||||
) => {
|
||||
$(#[$outer])*
|
||||
|
|
@ -47,7 +47,7 @@ macro_rules! c_enum
|
|||
#[repr($ti)]
|
||||
$vi enum $t
|
||||
{
|
||||
$($en = $va,)+
|
||||
$($(#[$vouter])* $en = $va,)+
|
||||
}
|
||||
|
||||
#[allow(unused_qualifications)]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,22 @@
|
|||
#![doc(hidden)]
|
||||
|
||||
/// Macro-izes `#[doc = x]`.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use maraiah::doc_comment;
|
||||
///
|
||||
/// doc_comment! {
|
||||
/// concat!("Have a nice", " day", "!"),
|
||||
/// const A: u32 = 5;
|
||||
/// }
|
||||
///
|
||||
/// assert_eq!(A, 5);
|
||||
/// ```
|
||||
#[macro_export]
|
||||
macro_rules! doc_comment {
|
||||
($x:expr, $($tt:tt)*) => {#[doc = $x] $($tt)*}
|
||||
}
|
||||
|
||||
// EOF
|
||||
|
|
@ -1,11 +1,27 @@
|
|||
//! Foreign function interface utilities.
|
||||
|
||||
use crate::err::*;
|
||||
pub use std::{ffi::*,
|
||||
os::raw::*,
|
||||
ptr::{null, null_mut}};
|
||||
|
||||
pub use std::{ffi::*, os::raw::*, ptr::{null, null_mut}};
|
||||
|
||||
/// Creates a C string from a literal.
|
||||
///
|
||||
/// This is done by concatenating a null byte with the string and converting it
|
||||
/// to a pointer.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use maraiah::c_str;
|
||||
///
|
||||
/// let st = c_str!("test");
|
||||
///
|
||||
/// assert!(!st.is_null());
|
||||
///
|
||||
/// unsafe {
|
||||
/// assert_eq!(std::slice::from_raw_parts(st, 5), &[116, 101, 115, 116, 0]);
|
||||
/// }
|
||||
/// ```
|
||||
#[macro_export]
|
||||
macro_rules! c_str {
|
||||
($s:expr) => {
|
||||
|
|
@ -13,9 +29,17 @@ macro_rules! c_str {
|
|||
};
|
||||
}
|
||||
|
||||
/// Returns [`null`] as a [`*const c_void`].
|
||||
///
|
||||
/// [`null`]: fn.null.html
|
||||
/// [`*const c_void`]: enum.c_void.html
|
||||
#[inline]
|
||||
pub const fn null_void() -> *const c_void {null()}
|
||||
|
||||
/// Returns [`null_mut`] as a [`*mut c_void`].
|
||||
///
|
||||
/// [`null_mut`]: fn.null_mut.html
|
||||
/// [`*mut c_void`]: enum.c_void.html
|
||||
#[inline]
|
||||
pub const fn null_mut_void() -> *mut c_void {null_mut()}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,19 @@
|
|||
//! This is the base library for the Maraiah tool set. This library contains
|
||||
//! functions and structures for reading many file formats, primarily those used
|
||||
//! by Marathon, Marathon 2, and Marathon Infinity.
|
||||
//!
|
||||
//! Maraiah comes with a set of almost fully portable tools written in Rust,
|
||||
//! including binary file reading, safe C-like `enum` reading, improved error
|
||||
//! handling, FFI tools, fixed point numbers, and image and sound structures.
|
||||
//!
|
||||
//! Maraiah also comes with APIs for working with various data formats,
|
||||
//! primarily Marathon's. It also handles Macintosh PICT files, Portable PixMap,
|
||||
//! TARGA, RIFF WAVE, and more.
|
||||
//!
|
||||
//! # Features
|
||||
//!
|
||||
//! Maraiah supports serializing and deserializing through `serde` with the
|
||||
//! `serde_obj` feature.
|
||||
#![deny(anonymous_parameters)]
|
||||
#![deny(bare_trait_objects)]
|
||||
#![deny(elided_lifetimes_in_paths)]
|
||||
|
|
@ -47,12 +63,14 @@
|
|||
#![deny(clippy::use_self)]
|
||||
#![deny(clippy::used_underscore_binding)]
|
||||
|
||||
#[macro_use]
|
||||
mod doc;
|
||||
#[macro_use]
|
||||
pub mod ffi;
|
||||
#[macro_use]
|
||||
pub mod err;
|
||||
#[macro_use]
|
||||
pub mod cenum;
|
||||
mod cenum;
|
||||
#[macro_use]
|
||||
pub mod bin;
|
||||
|
||||
|
|
|
|||
|
|
@ -1,28 +1,51 @@
|
|||
//! Meta-information of this crate.
|
||||
|
||||
use crate::ffi;
|
||||
|
||||
macro_rules! meta_str {
|
||||
($($name:ident = $cname:ident = $e:expr;)*) => {
|
||||
($($(#[$outer:meta])* $name:ident = $cname:ident = $e:expr;)*) => {
|
||||
$(
|
||||
pub const $name: &'static str = $e;
|
||||
pub const $cname: ffi::NT = c_str!($e);
|
||||
$(#[$outer])* pub const $name: &'static str = $e;
|
||||
)*
|
||||
pub mod ffi
|
||||
{
|
||||
$(
|
||||
doc_comment! {
|
||||
concat!("FFI variant of [`",
|
||||
stringify!($name),
|
||||
"`]\n\n[`",
|
||||
stringify!($name),
|
||||
"`]: ../constant.",
|
||||
stringify!($name),
|
||||
".html"),
|
||||
pub const $cname: crate::ffi::NT = c_str!($e);
|
||||
}
|
||||
)*
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
meta_str!(
|
||||
AUTHORS = C_AUTHORS = env!("CARGO_PKG_AUTHORS");
|
||||
DESCRIPTION = C_DESCRIPTION = env!("CARGO_PKG_DESCRIPTION");
|
||||
HOMEPAGE = C_HOMEPAGE = env!("CARGO_PKG_HOMEPAGE");
|
||||
LICENSE_TEXT = C_LICENSE_TEXT = include_str!("../LICENSE");
|
||||
NAME = C_NAME = env!("CARGO_PKG_NAME");
|
||||
REPOSITORY = C_REPOSITORY = env!("CARGO_PKG_REPOSITORY");
|
||||
VERSION = C_VERSION = env!("CARGO_PKG_VERSION");
|
||||
VERSION_MAJOR = C_VERSION_MAJOR = env!("CARGO_PKG_VERSION_MAJOR");
|
||||
VERSION_MINOR = C_VERSION_MINOR = env!("CARGO_PKG_VERSION_MINOR");
|
||||
VERSION_PATCH = C_VERSION_PATCH = env!("CARGO_PKG_VERSION_PATCH");
|
||||
VERSION_PRE = C_VERSION_PRE = env!("CARGO_PKG_VERSION_PRE");
|
||||
/// The authors of this crate, `:` separated.
|
||||
AUTHORS = AUTHORS_C = env!("CARGO_PKG_AUTHORS");
|
||||
/// The description of this crate.
|
||||
DESCRIPTION = DESCRIPTION_C = env!("CARGO_PKG_DESCRIPTION");
|
||||
/// The home page of this crate.
|
||||
HOMEPAGE = HOMEPAGE_C = env!("CARGO_PKG_HOMEPAGE");
|
||||
/// The full license text of this crate.
|
||||
LICENSE_TEXT = LICENSE_TEXT_C = include_str!("../LICENSE");
|
||||
/// The name of this crate.
|
||||
NAME = NAME_C = env!("CARGO_PKG_NAME");
|
||||
/// The repository of this crate.
|
||||
REPOSITORY = REPOSITORY_C = env!("CARGO_PKG_REPOSITORY");
|
||||
/// The full version of this crate.
|
||||
VERSION = VERSION_C = env!("CARGO_PKG_VERSION");
|
||||
/// The major version of this crate.
|
||||
VERSION_MAJOR = VERSION_MAJOR_C = env!("CARGO_PKG_VERSION_MAJOR");
|
||||
/// The minor version of this crate.
|
||||
VERSION_MINOR = VERSION_MINOR_C = env!("CARGO_PKG_VERSION_MINOR");
|
||||
/// The patch version of this crate.
|
||||
VERSION_PATCH = VERSION_PATCH_C = env!("CARGO_PKG_VERSION_PATCH");
|
||||
/// The pre-release version of this crate.
|
||||
VERSION_PRE = VERSION_PRE_C = env!("CARGO_PKG_VERSION_PRE");
|
||||
);
|
||||
|
||||
// EOF
|
||||
|
|
|
|||
|
|
@ -15,11 +15,11 @@ macro_rules! meta_str {
|
|||
}
|
||||
|
||||
meta_str!(
|
||||
tychoAuthors = meta::C_AUTHORS;
|
||||
tychoHomepage = meta::C_HOMEPAGE;
|
||||
tychoLicenseText = meta::C_LICENSE_TEXT;
|
||||
tychoRepository = meta::C_REPOSITORY;
|
||||
tychoVersion = meta::C_VERSION;
|
||||
tychoAuthors = meta::ffi::AUTHORS_C;
|
||||
tychoHomepage = meta::ffi::HOMEPAGE_C;
|
||||
tychoLicenseText = meta::ffi::LICENSE_TEXT_C;
|
||||
tychoRepository = meta::ffi::REPOSITORY_C;
|
||||
tychoVersion = meta::ffi::VERSION_C;
|
||||
);
|
||||
|
||||
// EOF
|
||||
|
|
|
|||
Loading…
Reference in New Issue