Clearer Names / module hierarchy

[epage]

Some of the original nom naming is confusing for new people. How can we name things so a casual programmer (not steeped in specific parsing backgrounds) can walk up and use this crate while being technically clear to help as people need to do more advanced things?

e.g.

• confusion over tag
• hard to search all the modules

I've started a spreadsheet of the current names, with comparisons to some other parsers. I'd also be open to comparing with more parsers (not just Rust ones) if there are good points of inspiration.

[epage]

See also

• map_res! has a misleading name rust-bakery/nom#590
• Proposal: rename take_till or take_until rust-bakery/nom#968
• Number module parsers are potentially confusing rust-bakery/nom#1468

[epage]

Running list of whats been done

• fix!: Move core combinators to combinators mod #4 Move Map, etc to combinator::Map, etc
• feat: Auto-detect whether to use complete/streaming parser #28 Move *::complete::* / *::streaming::* into *::* by auto-detecting complete/streaming
• fix: Move float parsing to character #38 Moved number::float to character::f32 and number::double to character::f64
• feat: Move non-grammar combinators to Parser #40
  • Renamed combinator::map_res with Parser::map_res
  • Renamed combinator::map_opt with Parser::map_opt
  • Renamed combinator::complete with Parser::complete
  • Renamed combinator::verify with Parser::verify
  • Renamed combinator::value with Parser::value
  • Renamed combinator::recognize with Parser::recognize
  • Renamed combinator::consumed with Parser::with_recognized
  • Renamed error::context with Parser::context
  • Renamed error::dbg_dmp with Parser::dbg_err
• fix(bytes): Generalize byte/char APIs #44 Generalized character::*::anychar into bytes::any
• fix(parser)!: Split Parser::into into Parser::output_into and Parser::err_into #48 Replace Parser::into with Parser::output_into and Parser::err_into (Parser::into conflicted with Into::into)
• fix(bits)!: Don't re-export in root namespace  #52 pub use bits::* in root namespace
• refactor!: Clarify module names #13 + fix(error)!: Move ErrorConvert to error module #73 Move ErrorConvert to error::ErrorConvert
• fix!: Transition from Parser::parse to Parser::parse_next #76 Renamed Parser::parse to Parsr::parse_next to clarify the incremental nature
• fix(input)!: Cleanup to prepare for trait merger #105 misc renames related to input that don't affect most users
• fix(char): Move escaped from bytes to character #108 moved bytes::escaped into character::escaped
• fix(error)!: Clarify role of different error elements #117
  • Renamed Err { Incomplete, Error, Failure } to ErrMode { Incomplete, Backtrack, Cut }
  • Renamed cut to cut_err
  • Copied IResult into error
  • Moved Needed and ErrMode into error
  • Moved error::Context and err::DbgDump into combinator
• fix(char)!: Generalize textual number parsing #129
  • Merge character::f32 and character::f64 into character::float
  • Generalize number::hex_u32 into character::hex_uint
  • Merge character::u8, character::u16, etc into character::dec_uint and character::dec_int
• feat(multi): Switch from Vec to impl Accumulate  #127 Deprecate many0_count, etc in favor of many0 with new inferred output parameter
• fix!: Consistently apply 0 suffix to parsers #132 Renamed combinators that were missing the 0 suffix
• feat(multi): Left and right associated fold support #140 separated_list0 to separated0 and separated_list1 to separated1 to open the room for other separated functions
• refactor!: Clarify module names #13 + fix(stream)!: Change from "input" terminology to "stream" #142 Moved input types to stream
• fix(stream)!: Change from "input" terminology to "stream" #142
  • Streaming to Partial to open the door for changing some uses of "input" to "stream" which both makes it clearer that its incremental, like in fix!: Transition from Parser::parse to Parser::parse_next #76, and in case we change how we use it in Parsing takes 30% longer just by adding Located to the input #72
  • misc renames related to input that don't affect most users
• fix(parser)!: Rename Parser::map_opt to Parser::verify_map  #145 Renamed Parser::map_opt to Parser::verify_map as its a verify + map, paralleling filter + map is filter_map
• fix: Clarify naming #239 Handles module moves
• fix(multi): Rename 'many' as 'repeat'  #240

[epage]

nom tries to use the module heiarchy as a ToC for the different combinators (e.g. sequence) with a catch-all (combinators).

I think I want to instead switch it around based on roles:

• combinators has all the role-agnostic combinators (combinators, sequence, bytes, etc)
• str is the new name for character
• binary is the new name for number
• binary::bits is the new name for bits (since they overlap with other combinators like tag, this keeps them scoped with wildcard imports)

This means the error types in #103 will likely be role specific (BStrError and BinError). That, combined with the above, makes me wonder if we should have role-based IResult aliases that default the error to their role's specific one. That then makes me wonder if we should have role-specific preludes.

[epage]

#239 implements this

[vwkd]

It seems the naming currently uses a mix of verbs, nouns, adjectives, and other parts of speech.

For example, currently the name of the separated combinator is an adjective while the name of the repeat combinator is a verb, which previously was yet another part of speech (many).

It would be good to specify a naming convention.

Some more examples of current names:

verbs

• repeat
• fill
• fold_repeat
• fail
• map
• peek
• parse
• etc.

adjectives

• separated
• escaped
• terminated
• delimited
• preceded
• etc.

nouns

• alt(ernative)
• success
• digit
• newline
• etc.

other (?)

• any
• one_of
• none_of

[epage]

I expect we'll at least have a mix of nouns and verbs or adjectives considering the different role different parsers may take. Whether we do both verbs and adjectives or lean on one is yet to be decided.

I did an incomplete survey of other parsers. Might be worth looking at those for ideas

I've started a spreadsheet of the current names, with comparisons to some other parsers. I'd also be open to comparing with more parsers (not just Rust ones) if there are good points of inspiration.