| James Farrell | 63fd73a | 2024-09-18 20:36:59 +0000 | [diff] [blame] | 1 | //! # Migrating from `nom` |
| 2 | //! |
| 3 | //! For comparisons with `nom`, see |
| 4 | //! - [Why `winnow`][super::why] |
| 5 | //! - [parse-rosetta-rs](https://github.com/rosetta-rs/parse-rosetta-rs/) |
| 6 | //! |
| 7 | //! What approach you take depends on the size and complexity of your parser. |
| 8 | //! For small, simple parsers, its likely easiest to directly port from `nom`. |
| 9 | //! When trying to look for the equivalent of a `nom` combinator, search in the docs for the name |
| 10 | //! of the `nom` combinator. It is expected that, where names diverge, a doc alias exists. |
| 11 | //! See also the [List of combinators][crate::combinator]. |
| 12 | //! |
| 13 | //! For larger parsers, it is likely best to take smaller steps |
| 14 | //! - Easier to debug when something goes wrong |
| 15 | //! - Deprecation messages will help assist through the process |
| 16 | //! |
| 17 | //! The workflow goes something like: |
| 18 | //! 1. Run `cargo rm nom && cargo add winnow@0.3` |
| 19 | //! 1. Ensure everything compiles and tests pass, ignoring deprecation messages (see [migration |
| 20 | //! notes](https://github.com/winnow-rs/winnow/blob/v0.3-main/CHANGELOG.md#nom-migration-guide)) |
| 21 | //! 1. Commit |
| 22 | //! 1. Switch any `impl FnMut(I) -> IResult<I, O, E>` to `impl Parser<I, O, E>` |
| 23 | //! 1. Resolve deprecation messages |
| 24 | //! 1. Commit |
| 25 | //! 1. Run `cargo add winnow@0.4` |
| 26 | //! 1. Ensure everything compiles and tests pass, ignoring deprecation messages (see [changelog](https://github.com/winnow-rs/winnow/blob/v0.4-main/CHANGELOG.md#compatibility-2) for more details) |
| 27 | //! 1. Commit |
| 28 | //! 1. Resolve deprecation messages |
| 29 | //! 1. Commit |
| 30 | //! 1. Run `cargo add winnow@0.5` |
| 31 | //! 1. Ensure everything compiles and tests pass, ignoring deprecation messages (see [migration |
| 32 | //! notes](https://github.com/winnow-rs/winnow/blob/v0.5.0/CHANGELOG.md)) |
| 33 | //! 1. Commit |
| 34 | //! 1. Resolve deprecation messagess |
| 35 | //! 1. Commit |
| 36 | //! |
| 37 | //! For example migrations, see |
| 38 | //! - [git-config-env](https://github.com/gitext-rs/git-config-env/pull/11) (nom to winnow 0.3) |
| 39 | //! - [git-conventional](https://github.com/crate-ci/git-conventional/pull/37) (nom to winnow 0.3, |
| 40 | //! adds explicit tracing for easier debugging) |
| 41 | //! - [typos](https://github.com/crate-ci/typos/pull/664) (nom to winnow 0.3) |
| 42 | //! - [cargo-smart-release](https://github.com/Byron/gitoxide/pull/948) (gradual migration from nom |
| 43 | //! to winnow 0.5) |
| 44 | //! - [gix-config](https://github.com/Byron/gitoxide/pull/951) (gradual migration from nom |
| 45 | //! to winnow 0.5) |
| 46 | //! - [gix-protocol](https://github.com/Byron/gitoxide/pull/1009) (gradual migration from nom |
| 47 | //! to winnow 0.5) |
| 48 | //! - [gitoxide](https://github.com/Byron/gitoxide/pull/956) (gradual migration from nom |
| 49 | //! to winnow 0.5) |
