Add helper attribute macros for writing free function parsers/writers

binrw/doc/attribute.md

@@ -1067,6 +1067,9 @@ a type, or to parse types which have no `BinRead` implementation at all:
 #[br(parse_with = $parse_fn:expr)] or #[br(parse_with($parse_fn:expr))]
 ```
 
+Use the [`#[parser]`](crate::parser) attribute macro to create compatible
+functions.
+
 Any earlier field or [import](#arguments) can be referenced by the
 expression in the directive (for example, to construct a parser function at
 runtime by calling a function generator).
@@ -1082,6 +1085,9 @@ implementation at all:
 #[bw(write_with = $write_fn:expr)] or #[bw(write_with($write_fn:expr))]
 ```
 
+Use the [`#[writer]`](crate::writer) attribute macro to create compatible
+functions.
+
 Any field or [import](#arguments) can be referenced by the expression in the
 directive (for example, to construct a serialisation function at runtime by
 calling a function generator).
@@ -1096,9 +1102,8 @@ calling a function generator).
 ```
 # use binrw::{prelude::*, io::{prelude::*, Cursor}, Endian};
 # use std::collections::HashMap;
-fn custom_parser<R: Read + Seek>(reader: &mut R, endian: Endian, _: ())
-    -> BinResult<HashMap<u16, u16>>
-{
+#[binrw::parser(reader, endian)]
+fn custom_parser() -> BinResult<HashMap<u16, u16>> {
     let mut map = HashMap::new();
     map.insert(
         <_>::read_options(reader, endian, ())?,
@@ -1124,11 +1129,9 @@ struct MyType {
 ```
 # use binrw::{prelude::*, io::{prelude::*, Cursor}, Endian};
 # use std::collections::BTreeMap;
-fn custom_writer<R: Write + Seek>(
+#[binrw::writer(writer, endian)]
+fn custom_writer(
     map: &BTreeMap<u16, u16>,
-    writer: &mut R,
-    endian: Endian,
-    _: ()
 ) -> BinResult<()> {
     for (key, val) in map.iter() {
         key.write_options(writer, endian, ())?;

binrw/src/file_ptr.rs

@@ -173,13 +173,9 @@ impl<Ptr: BinRead<Args = ()> + IntoSeekFrom, Value> FilePtr<Ptr, Value> {
     /// # Errors
     ///
     /// If reading fails, an [`Error`](crate::Error) variant will be returned.
-    pub fn parse<R, Args>(
-        reader: &mut R,
-        endian: Endian,
-        args: FilePtrArgs<Args>,
-    ) -> BinResult<Value>
+    #[binrw::parser(reader, endian)]
+    pub fn parse<Args>(args: FilePtrArgs<Args>, ...) -> BinResult<Value>
     where
-        R: Read + Seek,
         Args: Clone,
         Value: BinRead<Args = Args>,
     {

binrw/src/helpers.rs

@@ -475,13 +475,8 @@ where
     }
 }
 
-// Lint: Non-consumed argument is required to match the API.
-#[allow(clippy::trivially_copy_pass_by_ref)]
-fn default_reader<R: Read + Seek, Arg: Clone, T: BinRead<Args = Arg>>(
-    reader: &mut R,
-    endian: Endian,
-    args: T::Args,
-) -> BinResult<T> {
+#[binrw::parser(reader, endian)]
+fn default_reader<Arg: Clone, T: BinRead<Args = Arg>>(args: T::Args, ...) -> BinResult<T> {
     let mut value = T::read_options(reader, endian, args.clone())?;
     value.after_parse(reader, endian, args)?;
     Ok(value)

binrw/src/lib.rs

@@ -141,6 +141,180 @@ pub use binrw_derive::binrw;
 /// ```
 pub use binrw_derive::NamedArgs;
 
+/// Attribute macro used to generate
+/// [`parse_with`](docs::attribute#custom-parserswriters) functions.
+///
+/// Rust functions are transformed by this macro to match the binrw API.
+///
+/// # Attribute options
+///
+/// * `#[parser(reader)]` or `#[parser(reader: $ident)]`: Exposes the write
+///   stream to the function. If no variable name is given, `reader` is used.
+/// * `#[parser(endian)]` or `#[parser(endian: $ident)]`: Exposes the endianness
+///   to the function. If no variable name is given, `endian` is used.
+///
+/// Options are comma-separated.
+///
+/// # Function parameters
+///
+/// Parameters are transformed into either
+/// [tuple-style arguments](docs::attribute#tuple-style-arguments) or
+/// [raw arguments](docs::attribute#raw-arguments) depending upon the function
+/// signature.
+///
+/// ## Tuple-style arguments
+///
+/// Use a normal function signature. The parameters in the signature will be
+/// converted to a tuple. For example:
+///
+/// ```
+/// #[binrw::parser(reader: r, endian)]
+/// fn custom_parser(v0: u8, v1: i16) -> binrw::BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_parser(&mut binrw::io::Cursor::new(b""), binrw::Endian::Little, (0, 0)).unwrap();
+/// ```
+///
+/// The transformed output for this function is:
+///
+/// ```
+/// use binrw::{BinResult, Endian, io::{Read, Seek}};
+/// fn custom_parser<R: Read + Seek>(
+///     r: &mut R,
+///     endian: Endian,
+///     (v0, v1): (u8, i16)
+/// ) -> BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_parser(&mut binrw::io::Cursor::new(b""), binrw::Endian::Little, (0, 0)).unwrap();
+/// ```
+///
+/// ## Raw arguments
+///
+/// Use a *variadic* function signature with a single parameter. The name and
+/// type of the parameter will be used as the raw argument. For example:
+///
+/// ```
+/// # struct ArgsType;
+/// #[binrw::parser]
+/// fn custom_parser(args: ArgsType, ...) -> binrw::BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_parser(&mut binrw::io::Cursor::new(b""), binrw::Endian::Little, ArgsType).unwrap();
+/// ```
+///
+/// The transformed output for this function is:
+///
+/// ```
+/// # struct ArgsType;
+/// use binrw::{BinResult, Endian, io::{Read, Seek}};
+/// fn custom_parser<R: Read + Seek>(
+///     _: &mut R,
+///     _: Endian,
+///     args: ArgsType
+/// ) -> BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_parser(&mut binrw::io::Cursor::new(b""), binrw::Endian::Little, ArgsType).unwrap();
+/// ```
+///
+/// # Return value
+///
+/// The return value of a parser function must be [`BinResult<T>`](BinResult),
+/// where `T` is the type of the object being parsed.
+pub use binrw_derive::parser;
+
+/// Attribute macro used to generate
+/// [`write_with`](docs::attribute#custom-parserswriters) functions.
+///
+/// Rust functions are transformed by this macro to match the binrw API.
+///
+/// # Attribute options
+///
+/// * `#[writer(writer)]` or `#[writer(writer: $ident)]`: Exposes the write
+///   stream to the function. If no variable name is given, `writer` is used.
+/// * `#[writer(endian)]` or `#[writer(endian: $ident)]`: Exposes the endianness
+///   to the function. If no variable name is given, `endian` is used.
+///
+/// Options are comma-separated.
+///
+/// # Function parameters
+///
+/// The first parameter is required and receives a reference to the object being
+/// written.
+///
+/// Subsequent parameters are transformed into either
+/// [tuple-style arguments](docs::attribute#tuple-style-arguments) or
+/// [raw arguments](docs::attribute#raw-arguments) depending upon the function
+/// signature.
+///
+/// ## Tuple-style arguments
+///
+/// Use a normal function signature. The remaining parameters in the signature
+/// will be converted to a tuple. For example:
+///
+/// ```
+/// # struct Object;
+/// #[binrw::writer(writer: w, endian)]
+/// fn custom_writer(obj: &Object, v0: u8, v1: i16) -> binrw::BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_writer(&Object, &mut binrw::io::Cursor::new(vec![]), binrw::Endian::Little, (0, 0)).unwrap();
+/// ```
+///
+/// The transformed output for this function is:
+///
+/// ```
+/// # struct Object;
+/// use binrw::{BinResult, Endian, io::{Seek, Write}};
+/// fn custom_writer<W: Write + Seek>(
+///     obj: &Object,
+///     w: &mut W,
+///     endian: Endian,
+///     (v0, v1): (u8, i16)
+/// ) -> BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_writer(&Object, &mut binrw::io::Cursor::new(vec![]), binrw::Endian::Little, (0, 0)).unwrap();
+/// ```
+///
+/// ## Raw arguments
+///
+/// Use a *variadic* function signature with a second parameter. The name and
+/// type of the second parameter will be used as the raw argument. For example:
+///
+/// ```
+/// # struct Object;
+/// # struct ArgsType;
+/// #[binrw::writer]
+/// fn custom_writer(obj: &Object, args: ArgsType, ...) -> binrw::BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_writer(&Object, &mut binrw::io::Cursor::new(vec![]), binrw::Endian::Little, ArgsType).unwrap();
+/// ```
+///
+/// The transformed output for this function is:
+///
+/// ```
+/// # struct Object;
+/// # struct ArgsType;
+/// use binrw::{BinResult, Endian, io::{Seek, Write}};
+/// fn custom_writer<W: Write + Seek>(
+///     obj: &Object,
+///     _: &mut W,
+///     _: Endian,
+///     args: ArgsType
+/// ) -> BinResult<()> {
+///     Ok(())
+/// }
+/// # custom_writer(&Object, &mut binrw::io::Cursor::new(vec![]), binrw::Endian::Little, ArgsType).unwrap();
+/// ```
+///
+/// # Return value
+///
+/// The return value of a writer function must be [`BinResult<()>`](BinResult).
+pub use binrw_derive::writer;
+
 /// A specialized [`Result`] type for binrw operations.
 pub type BinResult<T> = core::result::Result<T, Error>;
 

binrw/src/punctuated.rs

@@ -1,9 +1,6 @@
 //! Type definitions for wrappers which parse interleaved data.
 
-use crate::{
-    io::{Read, Seek},
-    BinRead, BinResult, Endian, VecArgs,
-};
+use crate::{BinRead, BinResult, VecArgs};
 use alloc::vec::Vec;
 use core::fmt;
 
@@ -74,13 +71,8 @@ impl<T: BinRead, P: BinRead<Args = ()>> Punctuated<T, P> {
     /// # assert_eq!(*y.x, vec![3, 2, 1]);
     /// # assert_eq!(y.x.separators, vec![0, 1]);
     /// ```
-    // Lint: Non-consumed argument is required to match the API.
-    #[allow(clippy::needless_pass_by_value)]
-    pub fn separated<R: Read + Seek>(
-        reader: &mut R,
-        endian: Endian,
-        args: VecArgs<T::Args>,
-    ) -> BinResult<Self> {
+    #[crate::parser(reader, endian)]
+    pub fn separated(args: VecArgs<T::Args>, ...) -> BinResult<Self> {
         let mut data = Vec::with_capacity(args.count);
         let mut separators = Vec::with_capacity(args.count.max(1) - 1);
 
@@ -102,13 +94,8 @@ impl<T: BinRead, P: BinRead<Args = ()>> Punctuated<T, P> {
     /// # Errors
     ///
     /// If reading fails, an [`Error`](crate::Error) variant will be returned.
-    // Lint: Non-consumed argument is required to match the API.
-    #[allow(clippy::needless_pass_by_value)]
-    pub fn separated_trailing<R: Read + Seek>(
-        reader: &mut R,
-        endian: Endian,
-        args: VecArgs<T::Args>,
-    ) -> BinResult<Self> {
+    #[crate::parser(reader, endian)]
+    pub fn separated_trailing(args: VecArgs<T::Args>, ...) -> BinResult<Self> {
         let mut data = Vec::with_capacity(args.count);
         let mut separators = Vec::with_capacity(args.count);
 

binrw/tests/derive/struct.rs

@@ -1,7 +1,7 @@
 use binrw::{
     args, binread,
-    io::{Cursor, Read, Seek, SeekFrom},
-    BinRead, BinResult, Endian, FilePtr, NullString,
+    io::{Cursor, Seek, SeekFrom},
+    BinRead, BinResult, FilePtr, NullString,
 };
 
 #[test]
@@ -26,11 +26,8 @@ fn all_the_things() {
         calc_test: u32,
     }
 
-    fn read_offsets<R: Read + Seek>(
-        reader: &mut R,
-        endian: Endian,
-        _: (),
-    ) -> BinResult<(u16, u16)> {
+    #[binrw::parser(reader, endian)]
+    fn read_offsets() -> BinResult<(u16, u16)> {
         Ok((
             u16::read_options(reader, endian, ())?,
             u16::read_options(reader, endian, ())?,

binrw/tests/derive/write/custom_writer.rs

@@ -10,12 +10,8 @@ fn custom_writer() {
         y: u16,
     }
 
-    fn custom_writer<W: binrw::io::Write + binrw::io::Seek>(
-        _this: &u16,
-        writer: &mut W,
-        _: Endian,
-        _: (),
-    ) -> binrw::BinResult<()> {
+    #[binrw::writer(writer)]
+    fn custom_writer(_this: &u16) -> binrw::BinResult<()> {
         writer.write_all(b"abcd")?;
         Ok(())
     }

binrw/tests/ui/bad_parse_with_fn.rs

@@ -1,6 +1,7 @@
 use binrw::{BinRead, BinResult};
 
-fn wrong<R: binrw::io::Read + binrw::io::Seek>(_: R, _: binrw::Endian, _: ()) -> BinResult<bool> {
+#[binrw::parser]
+fn wrong() -> BinResult<bool> {
     Ok(true)
 }