perlmod/src/lib.rs

   1 //! Crate for creating perl packages/bindings for rust code.
   2 //!
   3 //! The main feature of this crate is the [`package`] macro provided by the `perlmod-macro` crate
   4 //! and documented here.
   5 //!
   6 //! The underlying machinery for these macros is contained in this crate and provides ways to
   7 //! serialize and deserialize data between perl and rust.
   8 //!
   9 //! # Blessed Values
  10 //!
  11 //! This crate also provides all the tools required to bless perl values into packages, and
  12 //! associate rust data with perl values.
  13 //! There are multiple ways to do this, and they come with different issues.
  14 //!
  15 //! The currently recommended way is found in the documentation of the [`magic`] module, which is
  16 //! considered the least error prone.
  17 //!
  18 //! A less safe (and lower-level) example can be found in the documentation of the
  19 //! [`Value::bless`](Value::bless()) method.
  20 //!
  21 //! [`package`]: attr.package.html
  22 //! [`export`]: attr.export.html
  23
  24 pub mod error;
  25 pub use error::Error;
  26
  27 #[macro_use]
  28 mod macros;
  29
  30 #[macro_use]
  31 pub mod ffi;
  32
  33 pub mod de;
  34 pub mod ser;
  35
  36 #[doc(inline)]
  37 pub use de::{from_ref_value, from_value};
  38 #[doc(inline)]
  39 pub use ser::to_value;
  40
  41 pub mod scalar;
  42 #[doc(inline)]
  43 pub use scalar::{Mortal, Scalar, ScalarRef};
  44
  45 pub mod array;
  46 #[doc(inline)]
  47 pub use array::Array;
  48
  49 pub mod hash;
  50 #[doc(inline)]
  51 pub use hash::Hash;
  52
  53 pub mod value;
  54 #[doc(inline)]
  55 pub use value::Value;
  56
  57 pub(crate) mod raw_value;
  58 pub use raw_value::RawValue;
  59
  60 pub mod magic;
  61 #[doc(inline)]
  62 pub use magic::{MagicSpec, MagicTag};
  63
  64 #[cfg(feature = "exporter")]
  65 #[doc(inline)]
  66 pub use perlmod_macro::package;
  67
  68 #[cfg(feature = "exporter")]
  69 #[doc(inline)]
  70 /// Attribute to export a function so that it can be installed as an `xsub` in perl. See the
  71 /// [`package!`](macro@package) macro for a usage example.
  72 ///
  73 /// This macro has the following optional arguments:
  74 ///
  75 /// * `raw_return`: specifies that the return type, which must be a [`Value`], will be returned as
  76 ///   is, and not go through serialization. As of perlmod
  77 ///   0.6, serialization of a [`Value`] will not produce a clone, so this is mostly an
  78 ///   optimization.
  79 /// * `prototype`: The perl prototype for the function. By default, this will be guessed from the
  80 ///   parameters as a chain of '$', with trailing `Option<>` parameters behind a `;`. So for
  81 ///   example, an `fn(i32, Option<i32>, i32, Option<i32>)` has the prototype `$$$;$`.
  82 /// * `xs_name`: override the name of the exported xsub, this is not recommended and only makes
  83 ///   sense when *not* using the `#[package]` macro, as with the `#[package]` macro, these aren't
  84 ///   publicly visible.
  85 /// * `name`: the name the function should be using in perl. This only makes sense with the
  86 ///   `#[package]` macro, as otherwise the user is responsible for loading the function via perl's
  87 ///   `DynaLoader` on their own.
  88 ///
  89 /// Additionally, function parameters can also use the following attributes:
  90 ///
  91 /// * `#[raw]` with a parameter of type [`Value`]: The parameter will be passed as
  92 ///   is and not go through deserialization. As of perlmod 0.6, deserialization will not produce
  93 ///   clones anymore, so this is mostly an optimization.
  94 /// * `#[try_from_ref]`: Instead of regular deserialization, `TryFrom::try_from(&Value)` will be
  95 ///   used.
  96 ///
  97 ///   Implementing the `TryFrom` trait accordingly can make using blessed references more
  98 ///   convenient, but at the cost of hiding underlying `unsafe` code.
  99 ///
 100 /// For an example on making blessed objects, see [`Value::bless_box`](Value::bless_box()).
 101 pub use perlmod_macro::export;