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
//! # High-level bindings to quickjs //! The `quickrjs` crate provides safe high-level bindings to the [quickjs](https://bellard.org/quickjs/) javascript engine. This crate is heavily inspired by the [rlua](https://crates.io/crates/rlua) crate. # The `Runtime` and `Context` objects The main entry point of this library is the [`Runtime`] struct. //! It represents the interperter state and is used to create [`Context`] //! objects. As the quickjs library does not support threading the runtime is locked behind a //! mutex. Multiple threads cannot run as script or create objects from the same runtime at the //! same time. //! The [`Context`] object represents a global environment and a stack. Contexts of the same runtime //! can share javascript objects like in browser between frames of the same origin. //! //! # Converting Values //! //! This library has multiple traits for converting to and from javascript. //! The [`ToJs`], [`ToJsMulti`] traits are used for taking rust values //! and turning them into javascript values. //! [`ToJsMulti`] is specificly used for place where a specific number of values //! need to be converted to javascript like for example the arguments of functions. //! [`FromJs`] is for converting javascript value to rust. //! Note that this trait does some automatic coercion. //! For values which represent the name of variables or indecies the //! trait [`ToAtom`] is available to convert values to the represention //! quickjs requires. //! //! //! [`Runtime`]: struct.Runtime.html //! [`Context`]: struct.Context.html //! [`ToJs`]: trait.ToJs.html //! [`ToJsMulti`]: trait.ToJsMulti.html //! [`FromJs`]: trait.FromJs.html //! [`ToAtom`]: trait.ToAtom.html #![allow(clippy::needless_lifetimes)] use quick_error::quick_error; use std::{ffi::NulError, io, str}; mod context; mod registery_key; pub use registery_key::RegisteryKey; mod runtime; pub use context::{Context, ContextBuilder, Ctx, MultiWith}; pub use runtime::Runtime; mod markers; mod value; use std::result::Result as StdResult; use std::string::String as StdString; pub use value::*; quick_error! { /// Error type of the library. #[derive(Debug)] pub enum Error{ /// Could not allocate memory /// This is generally only triggered when out of memory. Allocation{ display("Allocation failed while creating object") } /// Found a string with a internal null byte while converting /// to C string. InvalidString(e: NulError){ display("string contained internal null bytes: {}",e) from() cause(e) } /// String from rquickjs was not UTF-8 Utf8(e: str::Utf8Error){ display("Conversion from string failed: {}",e) from() cause(e) } /// An error from quickjs which i do not know the specifics about yet. /// Should eventually be removed as development progresses. Unknown{ display("quickjs library created a unknown error") } /// An exception raised by quickjs itself. Exception{message: StdString, file: StdString, line: u32, stack: StdString}{ display("exception generated by quickjs: [{}]:{} {}\n{}",file, line, message,stack) } /// Error converting from javascript to a rust type. FromJsConversion{from: &'static str, to: &'static str, message: Option<StdString>} { display("error converting from js from type '{}', to '{}': {}",from,to,message.as_ref().unwrap_or(&StdString::new())) } /// Error converting to javascript from a rust type. ToJsConversion{from: &'static str, to: &'static str, message: Option<StdString>} { display("error converting from type '{}', to '{}': {}",from,to,message.as_ref().unwrap_or(&StdString::new())) } /// An io error IO(e: io::Error){ display("IO Error: {}",e) from() cause(e) } } } impl Error { /// Returns wheter the error is a quickjs generated exception. pub fn is_exception(&self) -> bool { match *self { Error::Exception { message: _, file: _, line: _, stack: _, } => true, _ => false, } } } /// Result type used throught the library. pub type Result<T> = StdResult<T, Error>; #[cfg(test)] mod test { use super::*; #[test] fn base_runtime() { let _rt = Runtime::new().unwrap(); } }