init

.gitattributes

@@ -0,0 +1,6 @@
+# Tell github that .ml and .mli files are OCaml
+*.ml linguist-language=OCaml
+*.mli linguist-language=OCaml
+
+# Disable syntax detection for cram tests
+*.t linguist-language=Text

.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: ci
+
+on:
+  - pull_request
+  - push
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+        ocaml-compiler:
+          - 5.1.x
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup OCaml
+        uses: ocaml/setup-ocaml@v2
+        with:
+          ocaml-compiler: ${{ matrix.ocaml-compiler }}
+          opam-repositories: |
+            default: https://github.com/ocaml/opam-repository.git
+            mbarbin: https://github.com/mbarbin/opam-repository.git
+#            janestreet-bleeding: https://ocaml.janestreet.com/opam-repository
+#            janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
+
+      - name: Install dependencies
+        run:
+          opam install . --deps-only --with-doc --with-test
+
+      - name: Build
+        run: opam exec -- dune build
+
+      - name: Run tests
+        run: opam exec -- dune runtest
+
+      - name: Lint opam
+        uses: ocaml/setup-ocaml/lint-opam@v2
+
+      - name: Lint fmt
+        uses: ocaml/setup-ocaml/lint-fmt@v2
+
+      - name: Lint doc
+        uses: ocaml/setup-ocaml/lint-doc@v2

.github/workflows/deploy-odoc.yml

@@ -0,0 +1,27 @@
+name: deploy-odoc
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup OCaml
+        uses: ocaml/setup-ocaml@v2
+        with:
+          ocaml-compiler: 5.1.x
+          dune-cache: false
+          opam-repositories: |
+            default: https://github.com/ocaml/opam-repository.git
+            mbarbin: https://github.com/mbarbin/opam-repository.git
+#            janestreet-bleeding: https://ocaml.janestreet.com/opam-repository
+#            janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
+
+      - name: Deploy odoc to GitHub Pages
+        uses: ocaml/setup-ocaml/deploy-doc@v2

.gitignore

@@ -0,0 +1 @@
+_build

.ocamlformat

@@ -0,0 +1,2 @@
+version=0.26.1
+profile=janestreet

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "janestreet"
+    ]
+}

CHANGES.md

@@ -0,0 +1,6 @@
+## unreleased
+
+### Added
+### Changed
+### Fixed
+### Removed

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mathieu Barbin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,34 @@
+.PHONY: all
+all: build
+
+.PHONY: build
+build:
+	opam exec -- dune build
+
+.PHONY: test
+test:
+	opam exec -- dune runtest
+
+.PHONY: fmt
+fmt:
+	opam exec -- dune build @fmt --auto-promote
+
+.PHONY: lint
+lint:
+	opam lint
+	opam exec -- opam-dune-lint
+
+.PHONY: deps
+deps:
+	opam install . --deps-only --with-doc --with-test
+
+.PHONY: doc
+doc:
+	opam exec -- dune build @doc
+
+.PHONY: clean
+clean:
+	opam exec -- dune clean
+
+.PHONY: check-all
+check-all: deps all test doc clean lint fmt

README.md

@@ -0,0 +1,11 @@
+# loc
+
+[![CI Status](https://github.com/mbarbin/loc/workflows/ci/badge.svg)](https://github.com/mbarbin/loc/actions/workflows/ci.yml)
+[![Deploy odoc Status](https://github.com/mbarbin/loc/workflows/deploy-odoc/badge.svg)](https://github.com/mbarbin/loc/actions/workflows/deploy-odoc.yml)
+
+`Loc.it` representing a range of lexing positions from a parsed file. It may be
+used to decorate AST nodes built by parsers so as to allow located error
+messages during file processing (compilers, interpreters, etc.)
+
+It is inspired by dune's `Loc.t`, and uses it under the hood. The type equality
+with `dune` is exposed for a better compatibility of packages that uses `loc`.

dune

@@ -0,0 +1,4 @@
+(env
+ (dev
+  (odoc
+   (warnings fatal))))

dune-project

@@ -0,0 +1,47 @@
+(lang dune 3.11)
+
+(name loc)
+
+(generate_opam_files)
+
+(license MIT)
+
+(authors "Mathieu Barbin")
+
+(maintainers "Mathieu Barbin")
+
+(source
+ (github mbarbin/loc))
+
+(documentation "https://mbarbin.github.io/loc/")
+
+(package
+ (name loc)
+ (synopsis "Representing ranges of lexing positions from parsed files")
+ (description "Representing ranges of lexing positions from parsed files")
+ (depends
+  (ocaml
+   (>= 5.1))
+  (dune
+   (>= 3.11))
+  (base
+   (and
+    (>= v0.16)
+    (< v0.17)))
+  (expect_test_helpers_core
+   (and
+    :with-test
+    (>= v0.16)
+    (< v0.17)))
+  (fpath
+   (>= 0.7.3))
+  (ppx_jane
+   (and
+    (>= v0.16)
+    (< v0.17)))
+  (ppx_js_style
+   (and
+    (>= v0.16)
+    (< v0.17)))
+  (stdune
+   (>= 3.11))))

loc.opam

@@ -0,0 +1,36 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "Representing ranges of lexing positions from parsed files"
+description: "Representing ranges of lexing positions from parsed files"
+maintainer: ["Mathieu Barbin"]
+authors: ["Mathieu Barbin"]
+license: "MIT"
+homepage: "https://github.com/mbarbin/loc"
+doc: "https://mbarbin.github.io/loc/"
+bug-reports: "https://github.com/mbarbin/loc/issues"
+depends: [
+  "ocaml" {>= "5.1"}
+  "dune" {>= "3.11" & >= "3.11"}
+  "base" {>= "v0.16" & < "v0.17"}
+  "expect_test_helpers_core" {with-test & >= "v0.16" & < "v0.17"}
+  "fpath" {>= "0.7.3"}
+  "ppx_jane" {>= "v0.16" & < "v0.17"}
+  "ppx_js_style" {>= "v0.16" & < "v0.17"}
+  "stdune" {>= "3.11"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/mbarbin/loc.git"

src/dune

@@ -0,0 +1,8 @@
+(library
+ (name loc)
+ (public_name loc)
+ (wrapped false)
+ (flags :standard -w +a-4-40-41-42-44-45-66 -warn-error +a -open Base)
+ (libraries base fpath stdune)
+ (preprocess
+  (pps ppx_jane ppx_js_style -check-doc-comments)))

src/loc.ml

@@ -0,0 +1,65 @@
+module Loc0 = struct
+  type t = Stdune.Lexbuf.Loc.t =
+    { start : Source_code_position.t
+    ; stop : Source_code_position.t
+    }
+  [@@deriving equal, sexp_of]
+end
+
+type t = Stdune.Loc.t
+
+let equal = Stdune.Loc.equal
+let sexp_of_t t = [%sexp (Stdune.Loc.to_lexbuf_loc t : Loc0.t)]
+let equal_ignores_positions = ref false
+let equal t1 t2 = !equal_ignores_positions || equal t1 t2
+let include_sexp_of_positions = ref false
+let sexp_of_t t = if !include_sexp_of_positions then sexp_of_t t else Atom "_"
+let create (start, stop) = Stdune.Loc.of_lexbuf_loc { start; stop }
+let of_pos p = Stdune.Loc.of_lexbuf_loc { start = p; stop = p }
+
+let to_string t =
+  let t = Stdune.Loc.to_lexbuf_loc t in
+  Printf.sprintf
+    "File %S, line %d, characters %d-%d:"
+    t.start.pos_fname
+    t.start.pos_lnum
+    (t.start.pos_cnum - t.start.pos_bol)
+    (t.stop.pos_cnum - t.stop.pos_bol)
+;;
+
+let to_file_colon_line t = Stdune.Loc.to_file_colon_line t
+
+let dummy_pos =
+  Stdune.Loc.of_lexbuf_loc { start = Lexing.dummy_pos; stop = Lexing.dummy_pos }
+;;
+
+let in_file_at_line ~path ~line =
+  let p =
+    { Lexing.pos_fname = path |> Fpath.to_string
+    ; pos_lnum = line
+    ; pos_cnum = 0
+    ; pos_bol = 0
+    }
+  in
+  Stdune.Loc.of_lexbuf_loc { start = p; stop = p }
+;;
+
+let in_file ~path = in_file_at_line ~path ~line:1
+
+let with_dummy_pos t =
+  let t = Stdune.Loc.to_lexbuf_loc t in
+  Stdune.Loc.of_lexbuf_loc
+    { start = { Lexing.dummy_pos with pos_fname = t.start.pos_fname }
+    ; stop = { Lexing.dummy_pos with pos_fname = t.stop.pos_fname }
+    }
+;;
+
+let path t =
+  let t = Stdune.Loc.to_lexbuf_loc t in
+  t.start.pos_fname |> Fpath.v
+;;
+
+let line t =
+  let t = Stdune.Loc.to_lexbuf_loc t in
+  t.start.pos_lnum
+;;

src/loc.mli

@@ -0,0 +1,40 @@
+(** A type used to decorate AST nodes built by parser so as to allow located
+    error messages. *)
+
+type t = Stdune.Loc.t [@@deriving equal, sexp_of]
+
+(** By default set to [false], this may be temporarily turned to [true] to
+    operates some comparison that ignores positions. *)
+val equal_ignores_positions : bool ref
+
+(** By default set to [false], this may be temporarily turned to [true] to
+    inspect positions in the dump of a program. *)
+val include_sexp_of_positions : bool ref
+
+(** To be called in the right hand side of a Menhir rule, using the [$loc]
+    special keyword provided by Menhir. For example:
+
+    {v
+     ident:
+      | ident=IDENT { Loc.create $loc }
+     ;
+    v} *)
+val create : Source_code_position.t * Source_code_position.t -> t
+
+val of_pos : Source_code_position.t -> t
+
+(** Build the first line of error messages to produce to stderr using the same
+    syntax as used by the OCaml compiler. If your editor has logic to recognize
+    it, it will allow to jump to the source file. *)
+val to_string : t -> string
+
+val to_file_colon_line : t -> string
+val dummy_pos : t
+val in_file : path:Fpath.t -> t
+val in_file_at_line : path:Fpath.t -> line:int -> t
+
+(** Same as [dummy_pos] but try and keep the original path. *)
+val with_dummy_pos : t -> t
+
+val path : t -> Fpath.t
+val line : t -> int