Fix visibility of DukContext methods.

Add comments.
Update version.
This commit is contained in:
envis10n 2019-01-31 16:37:48 -06:00
parent f537c6d86c
commit b2671b10bd
2 changed files with 37 additions and 12 deletions

View file

@ -1,6 +1,6 @@
[package] [package]
name = "duktape-rs" name = "duktape-rs"
version = "0.0.3" version = "0.0.4"
authors = ["envis10n <envis10n@protonmail.com>"] authors = ["envis10n <envis10n@protonmail.com>"]
edition = "2018" edition = "2018"
repository = "https://gitlab.com/envis10n/duktape-rs" repository = "https://gitlab.com/envis10n/duktape-rs"

View file

@ -6,6 +6,7 @@ use std::fmt;
use std::f64; use std::f64;
use std::os::raw::c_void; use std::os::raw::c_void;
/// An error code representing why an error occurred.
#[allow(missing_docs)] #[allow(missing_docs)]
#[derive(Clone, Copy, PartialEq, Eq, Debug)] #[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[repr(u32)] #[repr(u32)]
@ -20,6 +21,7 @@ pub enum DukErrorCode {
NullPtr NullPtr
} }
/// Represents a JavaScript number value. JavaScript numbers can be either floats or integers, as well as NaN and Infinity.
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub enum DukNumber { pub enum DukNumber {
NaN, NaN,
@ -76,6 +78,7 @@ impl DukNumber {
} }
} }
/// A wrapper around duktape's heapptr. These represent JavaScript objects.
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct DukObject { pub struct DukObject {
context: DukContext, context: DukContext,
@ -83,7 +86,7 @@ pub struct DukObject {
} }
impl DukObject { impl DukObject {
/// Encode to JSON string. /// Encode this object to a JSON string.
pub fn encode(&mut self) -> Option<String> { pub fn encode(&mut self) -> Option<String> {
unsafe { unsafe {
match self.context.ctx { match self.context.ctx {
@ -123,6 +126,7 @@ impl DukObject {
} }
} }
} }
/// Get a property on this object as a DukValue.
pub fn get_prop(&mut self, name: &str) -> DukResult<DukValue> { pub fn get_prop(&mut self, name: &str) -> DukResult<DukValue> {
unsafe { unsafe {
let ctx = self.context.ctx.expect("Invalid context pointer."); let ctx = self.context.ctx.expect("Invalid context pointer.");
@ -136,6 +140,7 @@ impl DukObject {
} }
} }
} }
/// Set a property on this object.
pub fn set_prop(&mut self, name: &str, value: DukValue) -> DukResult<()> { pub fn set_prop(&mut self, name: &str, value: DukValue) -> DukResult<()> {
match self.context.ctx { match self.context.ctx {
Some(ctx) => { Some(ctx) => {
@ -189,6 +194,7 @@ impl DukObject {
None => Err(DukError::from(DukErrorCode::NullPtr, "Invalid context pointer.")) None => Err(DukError::from(DukErrorCode::NullPtr, "Invalid context pointer."))
} }
} }
/// Creates a new DukObject from the object at the top of the value stack.
pub fn new(context: DukContext) -> DukObject { pub fn new(context: DukContext) -> DukObject {
unsafe { unsafe {
let ctx = context.ctx.expect("Invalid context pointer."); let ctx = context.ctx.expect("Invalid context pointer.");
@ -203,6 +209,7 @@ impl DukObject {
} }
} }
/// Represents a JavaScript value type.
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub enum DukValue { pub enum DukValue {
Undefined, Undefined,
@ -214,6 +221,7 @@ pub enum DukValue {
} }
impl DukValue { impl DukValue {
/// Return the value as a string.
pub fn as_str(&self) -> Option<String> { pub fn as_str(&self) -> Option<String> {
match self { match self {
DukValue::Undefined => Some(String::from("undefined")), DukValue::Undefined => Some(String::from("undefined")),
@ -221,9 +229,10 @@ impl DukValue {
DukValue::Number(ref n) => Some(String::from(n.as_str())), DukValue::Number(ref n) => Some(String::from(n.as_str())),
DukValue::Boolean(b) => Some(b.to_string()), DukValue::Boolean(b) => Some(b.to_string()),
DukValue::String(s) => Some(s.clone()), DukValue::String(s) => Some(s.clone()),
DukValue::Object(ref _o) => Some(String::from("[object]")) DukValue::Object(ref _o) => _o.clone().encode()
} }
} }
/// Return the value as a duk_bool_t (u32).
pub fn as_duk_bool(&self) -> Option<duk_bool_t> { pub fn as_duk_bool(&self) -> Option<duk_bool_t> {
match self { match self {
DukValue::Boolean(b) => { DukValue::Boolean(b) => {
@ -236,18 +245,21 @@ impl DukValue {
_ => None _ => None
} }
} }
/// Return the value as a bool.
pub fn as_bool(&self) -> Option<bool> { pub fn as_bool(&self) -> Option<bool> {
match self { match self {
DukValue::Boolean(b) => Some(*b), DukValue::Boolean(b) => Some(*b),
_ => None _ => None
} }
} }
/// Return the value as a DukNumber.
pub fn as_number(&self) -> Option<DukNumber> { pub fn as_number(&self) -> Option<DukNumber> {
match self { match self {
DukValue::Number(ref n) => Some(n.clone()), DukValue::Number(ref n) => Some(n.clone()),
_ => None _ => None
} }
} }
/// Return the value as a DukObject.
pub fn as_object(&mut self) -> Option<&mut DukObject> { pub fn as_object(&mut self) -> Option<&mut DukObject> {
match self { match self {
DukValue::Object(ref mut o) => { DukValue::Object(ref mut o) => {
@ -256,30 +268,35 @@ impl DukValue {
_ => None _ => None
} }
} }
/// Return the value as an f64.
pub fn as_f64(&self) -> Option<f64> { pub fn as_f64(&self) -> Option<f64> {
match self { match self {
DukValue::Number(ref n) => Some(n.as_f64()), DukValue::Number(ref n) => Some(n.as_f64()),
_ => None _ => None
} }
} }
/// Check if this value is an f64.
pub fn is_f64(&self) -> bool { pub fn is_f64(&self) -> bool {
match self { match self {
DukValue::Number(ref n) => n.is_f64(), DukValue::Number(ref n) => n.is_f64(),
_ => false _ => false
} }
} }
/// Check if this value is an i64.
pub fn is_i64(&self) -> bool { pub fn is_i64(&self) -> bool {
match self { match self {
DukValue::Number(ref n) => n.is_i64(), DukValue::Number(ref n) => n.is_i64(),
_ => false _ => false
} }
} }
/// Check if this value is a bool.
pub fn is_bool(&self) -> bool { pub fn is_bool(&self) -> bool {
match self { match self {
DukValue::Boolean(_b) => true, DukValue::Boolean(_b) => true,
_ => false _ => false
} }
} }
/// Return the value as an i64.
pub fn as_i64(&self) -> Option<i64> { pub fn as_i64(&self) -> Option<i64> {
match self { match self {
DukValue::Number(ref n) => Some(n.as_i64()), DukValue::Number(ref n) => Some(n.as_i64()),
@ -288,6 +305,7 @@ impl DukValue {
} }
} }
/// Error object representing a duktape error.
#[derive(PartialEq, Eq, Debug)] #[derive(PartialEq, Eq, Debug)]
pub struct DukError { pub struct DukError {
/// The error code, if a specific one is available, or /// The error code, if a specific one is available, or
@ -301,20 +319,21 @@ pub struct DukError {
} }
impl DukError { impl DukError {
/// Create a DukError from an error code (no message).
pub fn from_code(code: DukErrorCode) -> DukError { pub fn from_code(code: DukErrorCode) -> DukError {
DukError{code: code, message: None} DukError{code: code, message: None}
} }
/// Create a DukError from an error message (no code).
pub fn from_str(message: &str) -> DukError { pub fn from_str(message: &str) -> DukError {
DukError{code: DukErrorCode::Error, message: Some(message.to_string())} DukError{code: DukErrorCode::Error, message: Some(message.to_string())}
} }
/// Create a DukError from a code and message.
pub fn from(code: DukErrorCode, message: &str) -> DukError { pub fn from(code: DukErrorCode, message: &str) -> DukError {
DukError{code: code, message: Some(message.to_string())} DukError{code: code, message: Some(message.to_string())}
} }
/// Return the message stored in the DukError (or None if there isn't one).
pub fn to_string(&self) -> Option<String> { pub fn to_string(&self) -> Option<String> {
match &self.message { self.message.clone()
Some(m) => Some(m.clone()),
None => None
}
} }
} }
@ -337,24 +356,28 @@ impl fmt::Display for DukError {
pub type DukResult<T> = std::result::Result<T, DukError>; pub type DukResult<T> = std::result::Result<T, DukError>;
/// Wrapper around a duktape context. Usable for evaluating and returning values from the context that can be used in Rust.
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct DukContext { pub struct DukContext {
pub ctx: Option<*mut duk_context>, pub ctx: Option<*mut duk_context>,
} }
impl DukContext { impl DukContext {
fn new() -> DukContext { /// Create a duktape context.
pub fn new() -> DukContext {
unsafe { unsafe {
DukContext { ctx: Some(duk_create_heap_default()) } DukContext { ctx: Some(duk_create_heap_default()) }
} }
} }
fn destroy(&mut self) { /// Destroy the duktape context's heap. Should not be used after calling this.
pub fn destroy(&mut self) {
unsafe { unsafe {
duk_destroy_heap(self.ctx.expect("Invalid context pointer.")); duk_destroy_heap(self.ctx.expect("Invalid context pointer."));
self.ctx = None; self.ctx = None;
} }
} }
fn decode_json(&mut self, json: &str) -> DukValue { /// Decode a JSON string into the context, returning a DukObject.
pub fn decode_json(&mut self, json: &str) -> DukValue {
match self.ctx { match self.ctx {
Some(ctx) => { Some(ctx) => {
unsafe { unsafe {
@ -366,7 +389,8 @@ impl DukContext {
None => DukValue::Undefined None => DukValue::Undefined
} }
} }
fn get_value(&mut self) -> DukValue { /// Get a DukValue from the value at the top of the value stack in the context.
pub fn get_value(&mut self) -> DukValue {
unsafe { unsafe {
let t = duk_get_type(self.ctx.expect("Invalid context pointer"), -1); let t = duk_get_type(self.ctx.expect("Invalid context pointer"), -1);
match t as u32 { match t as u32 {
@ -403,7 +427,8 @@ impl DukContext {
} }
} }
} }
fn eval_string(&mut self, code: &str) -> DukResult<DukValue> { /// Evaluate a string, returning the resulting value.
pub fn eval_string(&mut self, code: &str) -> DukResult<DukValue> {
unsafe { unsafe {
if duk_eval_string(self.ctx.expect("Invalid context pointer"), code) == 0 { if duk_eval_string(self.ctx.expect("Invalid context pointer"), code) == 0 {
let result = self.get_value(); let result = self.get_value();