8000 Update migration guide to account for parsing changes (#437) · purescript/documentation@0e18f50 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0e18f50

Browse files
JordanMartinezJordanMartinez
authored
Update migration guide to account for parsing changes (#437)
1 parent f54c7c9 commit 0e18f50

File tree

1 file changed

+81
-2
lines changed

1 file changed

+81
-2
lines changed

‎migration-guides/0.15-Migration-Guide.md

Lines changed: 81 additions & 2 deletions
Original file line numberDiff line 10000 numberDiff line change
@@ -457,10 +457,18 @@ case foo of
457457
- `Text.Parsing.Parser.Combinators` -> `Parsing.Combinators`
458458
- `Text.Parsing.Parser.Expr` -> `Parsing.Expr`
459459
- `Text.Parsing.Parser.Language` -> `Parsing.Language`
460-
- `Text.Parsing.Parser.Pos` -> `Parsing.Pos`
461460
- `Text.Parsing.Parser.String` -> `Parsing.String`
462461
- `Text.Parsing.Parser.String.Basic` -> `Parsing.String.Basic`
463462
- `Text.Parsing.Parser.Token` -> `Parsing.Token`
463+
- The `Pos` module was renamed but the module itself is being deprecated (it currently re-exports `Parsing`):
464+
- `Text.Parsing.Parser.Pos` -> `Parsing`
465+
- The below combinators originally in the `Text.Parsing.Parser.String` module were relocated to `Parsing.String.Basic` because they are combinators, not primitive parsers:
466+
- `whitespace`
467+
- `skipSpaces`
468+
- `oneOf`
469+
- `noneOf`
470+
- `oneOfCodePoints`
471+
- `noneOfCodePoints`
464472

465473
### `groupAllBy` replaced equality function with ordering function (`purescript-lists`)
466474

@@ -644,7 +652,8 @@ See [purescript-contrib/purescript-colors#44](https://github.com/purescript-cont
644652
- If needed immediately, copy the color scheme file into your local project
645653
- Consider maintaining these files as separate libraries in the community
646654

647-
### `ParserT` got (up to) 20x performance boost (`purescript-parsing`)
655+
### Miscellaneous breaking change involving `purescript-parsing`
656+
#### `ParserT` got (up to) 20x performance boost
648657

649658
`ParserT` now has a more efficient representation. In addition to the performance, all parser execution is always stack-safe, even monadically, obviating the need to run parsers with `Trampoline` as the base Monad or to explicitly use `MonadRec`.
650659

@@ -655,6 +664,76 @@ Code that constructs parsers via the underlying representation will need to be u
655664
**To fix**:
656665
- Changes only needed if you depend on `ParserT`'s underlying representation
657666

667+
### Combinator `fooRec` can be replaced with `foo` version
668+
669+
Now that `ParserT` is stack-safe automatically, we no longer need functions that impose the `MonadRec` constraint. As such, all combinators ending in `Rec` due to the `MonadRec` constraint have been removed. The complete list is below:
670+
- `chainlRec` -> `chainl`
671+
- `chainl1Rec` -> `chainl1`
672+
- `chainrRec` -> `chainr`
673+
- `chainr1Rec` -> `chainr1`
674+
- `endByRec` -> `endBy`
675+
- `endBy1Rec` -> `endBy1`
676+
- `many1Rec` -> `many1`
677+
- `manyTillRec` -> `manyTill`
678+
- `manyTillRec_` -> `manyTill_`
679+
- `many1TillRec` -> `many1Till`
680+
- `many1TillRec_` -> `many1Till_`
681+
- `sepByRec` -> `sepBy`
682+
- `sepBy1Rec` -> `sepBy1`
683+
- `sepEndByRec` -> `sepEndBy`
684+
- `sepEndBy1Rec` -> `sepEndBy1`
685+
- `skipManyRec` -> `skipMany`
686+
- `skipMany1Rec` -> `skipMany1`
687+
688+
Combinators that were defined in the module `Text.Parsing.Parser.Combinators` are now defined in `Parsing.Combinators`.
689+
690+
**To fix:**
691+
- drop the `Rec` part of the combinator name and update imports
692+
### `MonadState` is actually usable now
693+
694+
Previously, `ParserT`'s `MonadState` instance hardcoded the `state` type to `ParserState`. If one wanted to run the parser in the context of their own state monad, they could not do so.
695+
696+
This limitation has been removed, enabling more powerful parsers.
697+
698+
If you still need to get the state of the parser, you must replace `get` with `getParserT`
699+
700+
**To fix:**
701+
- if depending on the underlying implementation, replace `get` with `getParserT`
702+
703+
### `regex` now reuses the implementation from `strings`
704+
705+
Previously, the `regex` function would use its own custom implementation. This functionality is already exposed in the `strings` package, so the function was updated to reuse that functionality:
706+
707+
```purs
708+
-- old way
709+
foo = do
710+
result <- regex { dotAll: true, global: true, ... } "finding a p[aA]ttern"
711+
712+
-- new way
713+
import Data.String.Regex (dotAll, global)
714+
715+
foo = do
716+
eitherErrOrResult <- regex "finding a p[aA]ttern" (dotAll <> global)
717+
case eitherErrOrResult of
718+
Left e -> -- invalid regex
719+
Right result -> -- usage
720+
```
721+
722+
Key differences are:
723+
- the arguments order is swapped
724+
- multiple flags are specified via a `Semigroup` rather than a `Record`
725+
- the caller is forced to handle a possible error if the regex is invalid
726+
727+
**To fix**:
728+
- use the "old way, new way" example above to update your code
729+
730+
### `Position` now has an `index` field
731+
732+
`index` is a line/column-independent position within the content being parsed. See the docs and implementation for more details.
733+
734+
**To fix**:
735+
- If relying on this internal detail, update your code to account for it.
736+
658737
## Breaking Changes in the `purescript-node` libraries
659738

660739
### Expose the `recursive` field in `mkdir'`'s options arg (`purescript-node-fs`/`purescript-node-fs-aff`)

0 commit comments

Comments
 (0)
0