1 //! Bit level parsers and combinators 2 //! 3 //! Bit parsing is handled by tweaking the input in most macros. 4 //! In byte level parsing, the input is generally a `&[u8]` passed from combinator 5 //! to combinator as the slices are manipulated. 6 //! 7 //! Bit parsers take a `(&[u8], usize)` as input. The first part of the tuple is a byte slice, 8 //! the second part is a bit offset in the first byte of the slice. 9 //! 10 //! By passing a pair like this, we can leverage most of the existing combinators, and avoid 11 //! transforming the whole slice to a vector of booleans. This should make it easy 12 //! to see a byte slice as a bit stream, and parse code points of arbitrary bit length. 13 //! 14 15 /// Transforms its byte slice input into a bit stream for the underlying parser. This allows the 16 /// given bit stream parser to work on a byte slice input. 17 /// 18 /// Signature: 19 /// `bits!( parser ) => ( &[u8], (&[u8], usize) -> IResult<(&[u8], usize), T> ) -> IResult<&[u8], T>` 20 /// 21 /// ``` 22 /// # #[macro_use] extern crate nom; 23 /// # use nom::{Err, Needed}; 24 /// # fn main() { 25 /// named!( take_4_bits<u8>, bits!( take_bits!( 4u8 ) ) ); 26 /// 27 /// let input = vec![0xAB, 0xCD, 0xEF, 0x12]; 28 /// let sl = &input[..]; 29 /// 30 /// assert_eq!(take_4_bits( sl ), Ok( (&sl[1..], 0xA) )); 31 /// assert_eq!(take_4_bits( &b""[..] ), Err(Err::Incomplete(Needed::Size(1)))); 32 /// # } 33 #[macro_export(local_inner_macros)] 34 macro_rules! bits ( 35 ($i:expr, $submac:ident!( $($args:tt)* )) => ({ 36 $crate::bits::bitsc($i, move |i| { $submac!(i, $($args)*) }) 37 }); 38 ($i:expr, $f:expr) => ( 39 bits!($i, call!($f)) 40 ); 41 ); 42 43 /// Counterpart to bits, bytes! transforms its bit stream input into a byte slice for the underlying 44 /// parser, allowing byte-slice parsers to work on bit streams. 45 /// 46 /// Signature: 47 /// `bytes!( parser ) => ( (&[u8], usize), &[u8] -> IResult<&[u8], T> ) -> IResult<(&[u8], usize), T>`, 48 /// 49 /// A partial byte remaining in the input will be ignored and the given parser will start parsing 50 /// at the next full byte. 51 /// 52 /// ``` 53 /// # #[macro_use] extern crate nom; 54 /// # use nom::combinator::rest; 55 /// # use nom::error::ErrorKind; 56 /// # fn main() { 57 /// 58 /// named!( parse<(u8, u8, &[u8])>, bits!( tuple!( 59 /// take_bits!(4u8), 60 /// take_bits!(8u8), 61 /// bytes!(rest::<_, (_, ErrorKind)>) 62 /// ))); 63 /// 64 /// let input = &[0xde, 0xad, 0xbe, 0xaf]; 65 /// 66 /// assert_eq!(parse( input ), Ok(( &[][..], (0xd, 0xea, &[0xbe, 0xaf][..]) ))); 67 /// # } 68 #[macro_export(local_inner_macros)] 69 macro_rules! bytes ( 70 ($i:expr, $submac:ident!( $($args:tt)* )) => ({ 71 $crate::bits::bytesc($i, move |i| { $submac!(i, $($args)*) }) 72 }); 73 ($i:expr, $f:expr) => ( 74 bytes!($i, call!($f)) 75 ); 76 ); 77 78 /// Consumes the specified number of bits and returns them as the specified type. 79 /// 80 /// Signature: 81 /// `take_bits!(type, count) => ( (&[T], usize), U, usize) -> IResult<(&[T], usize), U>` 82 /// 83 /// ``` 84 /// # #[macro_use] extern crate nom; 85 /// # fn main() { 86 /// named!(bits_pair<(&[u8], usize), (u8, u8)>, pair!( take_bits!(4u8), take_bits!(4u8) ) ); 87 /// named!( take_pair<(u8, u8)>, bits!( bits_pair ) ); 88 /// 89 /// let input = vec![0xAB, 0xCD, 0xEF]; 90 /// let sl = &input[..]; 91 /// 92 /// assert_eq!(take_pair( sl ), Ok((&sl[1..], (0xA, 0xB))) ); 93 /// assert_eq!(take_pair( &sl[1..] ), Ok((&sl[2..], (0xC, 0xD))) ); 94 /// # } 95 /// ``` 96 #[macro_export(local_inner_macros)] 97 macro_rules! take_bits ( 98 ($i:expr, $count:expr) => ( 99 { 100 let res: $crate::IResult<_, _> = $crate::bits::streaming::take($count)($i); 101 res 102 } 103 ); 104 ); 105 106 /// Matches the given bit pattern. 107 /// 108 /// Signature: 109 /// `tag_bits!(type, count, pattern) => ( (&[T], usize), U, usize, U) -> IResult<(&[T], usize), U>` 110 /// 111 /// The caller must specify the number of bits to consume. The matched value is included in the 112 /// result on success. 113 /// 114 /// ``` 115 /// # #[macro_use] extern crate nom; 116 /// # fn main() { 117 /// named!( take_a<u8>, bits!( tag_bits!(4usize, 0xA) ) ); 118 /// 119 /// let input = vec![0xAB, 0xCD, 0xEF]; 120 /// let sl = &input[..]; 121 /// 122 /// assert_eq!(take_a( sl ), Ok((&sl[1..], 0xA)) ); 123 /// # } 124 /// ``` 125 #[macro_export(local_inner_macros)] 126 macro_rules! tag_bits ( 127 ($i:expr, $count:expr, $p: expr) => ( 128 { 129 let res: $crate::IResult<_, _> = $crate::bits::streaming::tag($p, $count)($i); 130 res 131 } 132 ) 133 ); 134 135 #[cfg(test)] 136 mod tests { 137 use crate::lib::std::ops::{AddAssign, Shl, Shr}; 138 use crate::internal::{Err, Needed, IResult}; 139 use crate::error::ErrorKind; 140 141 #[test] 142 fn take_bits() { 143 let input = [0b10_10_10_10, 0b11_11_00_00, 0b00_11_00_11]; 144 let sl = &input[..]; 145 146 assert_eq!(take_bits!((sl, 0), 0u8), Ok(((sl, 0), 0))); 147 assert_eq!(take_bits!((sl, 0), 8u8), Ok(((&sl[1..], 0), 170))); 148 assert_eq!(take_bits!((sl, 0), 3u8), Ok(((&sl[0..], 3), 5))); 149 assert_eq!(take_bits!((sl, 0), 6u8), Ok(((&sl[0..], 6), 42))); 150 assert_eq!(take_bits!((sl, 1), 1u8), Ok(((&sl[0..], 2), 0))); 151 assert_eq!(take_bits!((sl, 1), 2u8), Ok(((&sl[0..], 3), 1))); 152 assert_eq!(take_bits!((sl, 1), 3u8), Ok(((&sl[0..], 4), 2))); 153 assert_eq!(take_bits!((sl, 6), 3u8), Ok(((&sl[1..], 1), 5))); 154 assert_eq!(take_bits!((sl, 0), 10u8), Ok(((&sl[1..], 2), 683))); 155 assert_eq!(take_bits!((sl, 0), 8u8), Ok(((&sl[1..], 0), 170))); 156 assert_eq!(take_bits!((sl, 6), 10u8), Ok(((&sl[2..], 0), 752))); 157 assert_eq!(take_bits!((sl, 6), 11u8), Ok(((&sl[2..], 1), 1504))); 158 assert_eq!(take_bits!((sl, 0), 20u8), Ok(((&sl[2..], 4), 700_163))); 159 assert_eq!(take_bits!((sl, 4), 20u8), Ok(((&sl[3..], 0), 716_851))); 160 let r: IResult<_,u32> = take_bits!((sl, 4), 22u8); 161 assert_eq!( 162 r, 163 Err(Err::Incomplete(Needed::Size(22))) 164 ); 165 } 166 167 #[test] 168 fn tag_bits() { 169 let input = [0b10_10_10_10, 0b11_11_00_00, 0b00_11_00_11]; 170 let sl = &input[..]; 171 172 assert_eq!(tag_bits!((sl, 0), 3u8, 0b101), Ok(((&sl[0..], 3), 5))); 173 assert_eq!(tag_bits!((sl, 0), 4u8, 0b1010), Ok(((&sl[0..], 4), 10))); 174 } 175 176 named!(ch<(&[u8],usize),(u8,u8)>, 177 do_parse!( 178 tag_bits!(3u8, 0b101) >> 179 x: take_bits!(4u8) >> 180 y: take_bits!(5u8) >> 181 (x,y) 182 ) 183 ); 184 185 #[test] 186 fn chain_bits() { 187 let input = [0b10_10_10_10, 0b11_11_00_00, 0b00_11_00_11]; 188 let sl = &input[..]; 189 assert_eq!(ch((&input[..], 0)), Ok(((&sl[1..], 4), (5, 15)))); 190 assert_eq!(ch((&input[..], 4)), Ok(((&sl[2..], 0), (7, 16)))); 191 assert_eq!(ch((&input[..1], 0)), Err(Err::Incomplete(Needed::Size(5)))); 192 } 193 194 named!(ch_bytes<(u8, u8)>, bits!(ch)); 195 #[test] 196 fn bits_to_bytes() { 197 let input = [0b10_10_10_10, 0b11_11_00_00, 0b00_11_00_11]; 198 assert_eq!(ch_bytes(&input[..]), Ok((&input[2..], (5, 15)))); 199 assert_eq!(ch_bytes(&input[..1]), Err(Err::Incomplete(Needed::Size(1)))); 200 assert_eq!( 201 ch_bytes(&input[1..]), 202 Err(Err::Error(error_position!(&input[1..], ErrorKind::TagBits))) 203 ); 204 } 205 206 named!(bits_bytes_bs, bits!(bytes!(crate::combinator::rest::<_, (&[u8], ErrorKind)>))); 207 #[test] 208 fn bits_bytes() { 209 let input = [0b10_10_10_10]; 210 assert_eq!(bits_bytes_bs(&input[..]), Ok((&[][..], &[0b10_10_10_10][..]))); 211 } 212 213 #[derive(PartialEq, Debug)] 214 struct FakeUint(u32); 215 216 impl AddAssign for FakeUint { 217 fn add_assign(&mut self, other: FakeUint) { 218 *self = FakeUint(self.0 + other.0); 219 } 220 } 221 222 impl Shr<usize> for FakeUint { 223 type Output = FakeUint; 224 225 fn shr(self, shift: usize) -> FakeUint { 226 FakeUint(self.0 >> shift) 227 } 228 } 229 230 impl Shl<usize> for FakeUint { 231 type Output = FakeUint; 232 233 fn shl(self, shift: usize) -> FakeUint { 234 FakeUint(self.0 << shift) 235 } 236 } 237 238 impl From<u8> for FakeUint { 239 fn from(i: u8) -> FakeUint { 240 FakeUint(u32::from(i)) 241 } 242 } 243 244 #[test] 245 fn non_privitive_type() { 246 let input = [0b10_10_10_10, 0b11_11_00_00, 0b00_11_00_11]; 247 let sl = &input[..]; 248 249 assert_eq!( 250 take_bits!((sl, 0), 20u8), 251 Ok(((&sl[2..], 4), FakeUint(700_163))) 252 ); 253 assert_eq!( 254 take_bits!((sl, 4), 20u8), 255 Ok(((&sl[3..], 0), FakeUint(716_851))) 256 ); 257 let r3: IResult<_, FakeUint> = take_bits!((sl, 4), 22u8); 258 assert_eq!( 259 r3, 260 Err(Err::Incomplete(Needed::Size(22))) 261 ); 262 } 263 } 264