Skip to content

Update CHANGES and remove astring #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update CHANGES and remove astring #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cbd9474
Update CHANGES.md
jonludlam Jun 6, 2023
85423ca
Remove astring dependency
jonludlam Jun 6, 2023
46d9553
Formatting
jonludlam Jun 6, 2023
b88594d
Move backported string functions to compat
jonludlam Jun 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 26 additions & 8 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,39 @@
2.0.0
-----
# 3.0.0
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This releases adds two constructors, which is a breaking change only for users that consume the entire AST. These users will break for every changes.
The Code_block constructor is changed, which breaks all known users.

These are breaking changes but require a small amount of maintenance. Given that this library exposes an AST and that every changes are breaking changes, I'd argue that we don't need to make a major release.

Also, a version number above 2.2.0 will prevent us from merging the two projects again. For which, the discussion is still open ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That all changes are breaking is a choice, because we could add versioned API support if we really wanted. I don't follow the argument about merging? It was never suggested we merge the opam packages again, so I don't see why they shouldn't have independent version numbers?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We talked about merging the git repositories ? Independent version numbers are possible but a lot of work to get right. It's also not intuitive.

Why would the two projects have independent version numbers ? Both projects evolve together, I don't see the point in the added release complexity.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is an important distinction. A comment written using odoc-parser syntax requires a particular version of the parser, not a particular version of odoc.

Copy link
Contributor

@Julow Julow Jun 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't contradict giving versions to the parser according to Odoc's. "this comment is written using the parser from odoc version x".

We more often add things to the parser than we remove. I think if a comment requires a specific version of the parser, it also constraints Odoc because it'll need a recent enough version.


### Changed

- Remove astring dependency (@jonludlam, #18)

### Fixed

- Better handling of reference syntax (@EmileTrotignon, #13)

### Added

- Delimited code blocks with associated output (@jonludlam, #17)
- New @hidden tag (@3Rafal, #16)
- Table syntax (@gpetiot, #11, @panglesd, #14)

# 2.0.0 - 2022-07-07

### Added

- New inline and display math markup (@giltho, #5)

1.0.1
-----
# 1.0.1 - 2022-07-05

### Added

- OCaml 5.0 support (@talex5, #6)

1.0.0
-----
# 1.0.0 - 2021-12-11

### Added

- New syntax to allow associating metadata with code blocks
(@Julow, #2, #3)

0.9.0
-----
# 0.9.0 - 2021-07-02

- Extracted from odoc repository

3 changes: 1 addition & 2 deletions dune-project
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
(lang dune 2.8)
(name odoc-parser)
(version 2.0.0)
(version 3.0.0)

(generate_opam_files true)

Expand All @@ -18,7 +18,6 @@ understood by ocamldoc.")
(depends
dune
(ocaml (>= 4.02.0))
astring
result
camlp-streams
(ppx_expect :with-test)))
Expand Down
3 changes: 1 addition & 2 deletions odoc-parser.opam
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# This file is generated by dune, edit dune-project instead
opam-version: "2.0"
version: "2.0.0"
version: "3.0.0"
synopsis: "Parser for ocaml documentation comments"
description: """
Odoc_parser is a library for parsing the contents of OCaml documentation
Expand All @@ -18,7 +18,6 @@ doc: "https://ocaml-doc.github.io/odoc-parser/"
depends: [
"dune" {>= "2.8"}
"ocaml" {>= "4.02.0"}
"astring"
"result"
"camlp-streams"
"ppx_expect" {with-test}
Expand Down
1 change: 0 additions & 1 deletion odoc-parser.opam.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ doc: "https://ocaml-doc.github.io/odoc-parser/"
depends: [
"dune" {>= "2.8"}
"ocaml" {>= "4.02.0"}
"astring"
"result"
"camlp-streams"
"ppx_expect" {with-test}
Expand Down
1 change: 0 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@
"buildsInSource": "_build"
},
"dependencies": {
"@opam/astring": "^0.8.3",
"@opam/dune": "^2.8.5",
"@opam/result": "*",
"@opam/ppx_expect": "*",
Expand Down
33 changes: 33 additions & 0 deletions src/compat.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,37 @@ module String = struct
else false
in
aux 0

(* This is taken from the OCaml stdlib (more or less) - only here because we support
4.02 and capitalize_ascii only arrived in 4.03. When we drop support
for 4.02 we can remove the following 3 functions *)

let capitalize_ascii =
let uppercase_ascii =
let open Char in
function 'a' .. 'z' as c -> unsafe_chr (code c - 32) | c -> c
in

let apply1 f s =
let open String in
if length s = 0 then s
else
let r = sub s 1 (length s - 1) in
make 1 (f (unsafe_get s 0)) ^ r
in

apply1 uppercase_ascii

(* The following function is taken from the OCaml stdlib. It's here because we support building
om OCaml < 4.04. Once we drop support for 4.03 and before we can remove the following function *)
let split_on_char sep s =
let open String in
let r = ref [] in
let j = ref (length s) in
for i = length s - 1 downto 0 do
if unsafe_get s i = sep then (
r := sub s (i + 1) (!j - i - 1) :: !r;
j := i)
done;
sub s 0 !j :: !r
end
2 changes: 1 addition & 1 deletion src/dune
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@
(backend bisect_ppx))
(flags
(:standard -w -50))
(libraries astring result camlp-streams))
(libraries result camlp-streams))
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is removing astring useful while Odoc uses it too ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

odoc-parser is used by more than just odoc. In this particular case, since once we drop support for <=4.03 the functionality we need is entirely in stdlib, it seems just good hygiene. I'm quite keen to drop old OCaml support fairly soon (and at a major version number).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The drop of support is not planned for this release ? Then I think this can wait.

This effectively remove a dependency from OCamlformat (the only user of the parser that I know of and don't use astring) so this is still welcome. Though, I don't think accumulating "compat" code is good hygiene.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why wait?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right, with the planned removal of the new compat functions, I don't see a problem with adding them.

2 changes: 1 addition & 1 deletion src/lexer.mll
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ let trim_leading_whitespace : first_line_offset:int -> string -> string =
count_leading_whitespace' 0 len
in

let lines = Astring.String.cuts ~sep:"\n" s in
let lines = String.split_on_char '\n' s in

let least_amount_of_whitespace =
List.fold_left (fun least_so_far line ->
Expand Down
14 changes: 7 additions & 7 deletions src/parse_error.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
let capitalize_ascii = Astring.String.Ascii.capitalize

let bad_markup : ?suggestion:string -> string -> Loc.span -> Warning.t =
fun ?suggestion -> Warning.make ?suggestion "'%s': bad markup."

let leading_zero_in_heading_level : string -> Loc.span -> Warning.t =
Warning.make "'%s': leading zero in heading level."

let should_not_be_empty : what:string -> Loc.span -> Warning.t =
fun ~what -> Warning.make "%s should not be empty." (capitalize_ascii what)
fun ~what ->
Warning.make "%s should not be empty." (String.capitalize_ascii what)

let markup_should_not_be_used : what:string -> Loc.span -> Warning.t =
fun ~what ->
Warning.make "%s should not be used because it has no effect."
(capitalize_ascii what)
(String.capitalize_ascii what)

let should_begin_on_its_own_line : what:string -> Loc.span -> Warning.t =
fun ~what ->
Warning.make "%s should begin on its own line." (capitalize_ascii what)
Warning.make "%s should begin on its own line." (String.capitalize_ascii what)

let should_be_followed_by_whitespace : what:string -> Loc.span -> Warning.t =
fun ~what ->
Warning.make "%s should be followed by space, a tab, or a new line."
(capitalize_ascii what)
(String.capitalize_ascii what)

let not_allowed :
?suggestion:string -> what:string -> in_what:string -> Loc.span -> Warning.t
=
fun ?suggestion ~what ~in_what ->
Warning.make ?suggestion "%s is not allowed in %s." (capitalize_ascii what)
Warning.make ?suggestion "%s is not allowed in %s."
(String.capitalize_ascii what)
in_what

let unclosed_bracket :
Expand Down