Add linter, doctests

.JuliaFormatter.toml

@@ -0,0 +1 @@
+style = "sciml"

.dev/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Git = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2"
+JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"

.dev/herb_format.jl

@@ -0,0 +1,70 @@
+"""
+Formatting script inspired by that of the `Flux.jl` package, which
+can be found at:
+https://github.com/FluxML/Flux.jl/blob/caa1ceef9cf59bd817b7bf5c94d0ffbec5a0f32c/dev/flux_format.jl
+"""
+
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+using JuliaFormatter
+
+help = """
+Usage: herb_format [flags] [FILE/PATH]...
+Formats the given julia files using the Herb formatting options.
+If paths are given instead, it will format all *.jl files under
+the paths. If nothing is given, all changed julia files are formatted.
+    -v, --verbose
+        Print the name of the files being formatted with relevant details.
+    -h, --help
+        Print this help message.
+    --check
+        Check if the files are formatted without changing them.
+"""
+
+options = Dict{Symbol, Bool}()
+indices_to_remove = []      # used to delete options once processed
+
+for (index, arg) in enumerate(ARGS)
+    if arg[1] != '-'
+        continue
+    end
+    val = true
+    if arg in ["-v", "--verbose"]
+        opt = :verbose
+        push!(indices_to_remove, index)
+    elseif arg in ["-h", "--help"]
+        opt = :help
+        push!(indices_to_remove, index)
+    elseif arg == "--check"
+        opt = :overwrite
+        val = false
+        write(stdout, "Checking files.\n")
+        push!(indices_to_remove, index)
+    else
+        error("Option $arg is not supported.")
+    end
+    options[opt] = val
+end
+
+# remove options from args
+deleteat!(ARGS, indices_to_remove)
+
+# print help message if asked
+if haskey(options, :help)
+    write(stdout, help)
+    exit(0)
+end
+
+# otherwise format files
+if isempty(ARGS)
+    filenames = readlines(`git ls-files "*.jl"`)
+else
+    filenames = ARGS
+end
+
+write(stdout, "Formatting in progress.\n")
+# format returns true if the files were already formatted
+# and false if they were not (had to be formatted)
+exit(format(filenames; options...) ? 0 : 1)

.dev/setup.jl

@@ -0,0 +1,20 @@
+"""
+Dev environment setup script inspired by that of the `Flux.jl` package, which
+can be found at:
+https://github.com/FluxML/Flux.jl/blob/caa1ceef9cf59bd817b7bf5c94d0ffbec5a0f32c/dev/setup.jl
+"""
+
+# instantiate the environment
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+# setup the custom git hook
+using Git
+
+# set the local hooks path
+const git = Git.git()
+run(`$git config --local core.hooksPath .githooks/`)
+
+# set file permission for hook
+Base.Filesystem.chmod(".githooks", 0o777; recursive = true)

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Migrate code style to SciML
+d89ecffc1ffd7b7a09093e7a4e58ef21a27ff51e

.githooks/pre-commit

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# Get the list of files that are about to be committed and filter out only the .jl files
+files=$(git diff --cached --name-only --diff-filter=ACM | grep "\.jl$")
+
+# If no files are found, exit
+if [ -z "$files" ]; then
+    exit 0
+fi
+
+# Run the herb formatter on the list of files
+julia --startup-file=no -O1 --color=yes .dev/herb_format.jl --check $files
+
+# If the formatter exited with an error, abort the commit
+if [ $? -ne 0 ]; then
+    echo "Error: formatter must be run on the files before committing."
+    echo "Please run julia .dev/herb_format.jl YOUR_CHANGED_FILES.jl"
+    exit 1
+fi

.github/workflows/check_docs.yml

@@ -0,0 +1,54 @@
+name: Check Docs
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Julia
+      uses: julia-actions/setup-julia@v1
+      with:
+        version: '1' # Use the latest stable Julia version
+    - name: Install dependencies
+      run: |
+        julia --project=docs -e '
+          using Pkg;
+          Pkg.develop(PackageSpec(path=pwd()));
+          Pkg.instantiate();
+          Pkg.add("Documenter");
+        '
+    - name: Try building documentation and run doctests
+      run: |
+        julia --project=docs -e '
+          using Documenter, HerbSpecification;
+          content = """
+            ```@meta
+            CurrentModule = HerbSpecification
+            DocTestSetup = quote
+                using HerbSpecification
+            end
+            ```
+            ```@autodocs
+            Modules = [HerbSpecification]
+            ```
+          """
+          mkpath("src/")
+          open("src/index.md", "w") do file
+            write(file, content)
+          end
+          makedocs(
+            sitename="HerbSpecification.jl",
+            modules=[HerbSpecification],
+            format=Documenter.HTML(),
+            doctest=true,
+            warnonly=[:missing_docs],
+            pages=["index.md"]
+          );
+        '

JuliaFormatter.yml

@@ -0,0 +1,53 @@
+name: Formatting Check
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  format:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            julia_file_change:
+              - added|modified: '**.jl'
+          list-files: 'shell'
+
+      - uses: julia-actions/setup-julia@latest
+        if: steps.filter.outputs.julia_file_change == 'true'
+        with:
+          version: ${{ matrix.version }}
+
+      - uses: julia-actions/cache@v1
+
+      - name: Apply JuliaFormatter
+        if: steps.filter.outputs.julia_file_change == 'true'
+        run: |
+          julia --color=yes .dev/herb_format.jl --verbose ${{ steps.filter.outputs.julia_file_change_files }}
+      - name: Check formatting diff
+        if: steps.filter.outputs.julia_file_change == 'true'
+        run: |
+          git diff --color=always --exit-code 

src/HerbSpecification.jl

@@ -2,20 +2,12 @@ module HerbSpecification
 
 include("problem.jl")
 
-export 
-    Problem,
-    MetricProblem,
-    AbstractSpecification,
-
-    IOExample,
-
-    AbstractFormalSpecification,
-    SMTSpecification,
-
-    Trace,
-
-    AbstractTypeSpecification,
-    DependentTypeSpecification,
-    AgdaSpecification
+export
+       Problem,
+       MetricProblem,
+       AbstractSpecification, IOExample, AbstractFormalSpecification,
+       SMTSpecification, Trace, AbstractTypeSpecification,
+       DependentTypeSpecification,
+       AgdaSpecification
 
 end # module HerbSpecification

src/problem.jl

@@ -2,7 +2,7 @@
     struct IOExample
 
 An input-output example.
-`in` is a [`Dict`](@ref) of `{Symbol,Any}` where the symbol represents a variable in a program.
+`in` is a `Dict` of `{Symbol,Any}` where the symbol represents a variable in a program.
 `out` can be anything.
 """
 struct IOExample
@@ -31,7 +31,6 @@
     formula::Function
 end
 
-
 abstract type AbstractTypeSpecification end
 
 """
@@ -50,12 +49,13 @@
     formula::Function
 end
 
-const AbstractSpecification = Union{Vector{IOExample}, AbstractFormalSpecification, Vector{Trace}, AbstractTypeSpecification}
+const AbstractSpecification = Union{Vector{IOExample}, AbstractFormalSpecification,
+    Vector{Trace}, AbstractTypeSpecification}
 
 """
     struct Problem
 
-Program synthesis problem defined by an [`AbstractSpecification`](@ref)s. Has a name and a specification of type `T`.
+Program synthesis problem defined by an `AbstractSpecification`. Has a name and a specification of type `T`.
 
 !!! warning
     Please care that concrete `Problem` types with different values of `T` are never subtypes of each other. 
@@ -64,10 +64,10 @@
     name::AbstractString
     spec::T
 
-    function Problem(spec::T) where T <: AbstractSpecification
+    function Problem(spec::T) where {T <: AbstractSpecification}
         new{T}("", spec)
     end
-    function Problem(name::AbstractString, spec::T) where T <: AbstractSpecification
+    function Problem(name::AbstractString, spec::T) where {T <: AbstractSpecification}
         new{T}(name, spec)
     end
 end
@@ -82,23 +82,20 @@
     cost_function::Function
     spec::T
 
-    function MetricProblem(cost_function::Function, spec::T) where T<:Vector{IOExample}
+    function MetricProblem(cost_function::Function, spec::T) where {T <: Vector{IOExample}}
         new{T}("", cost_function, spec)
     end
 
-    function MetricProblem(name::AbstractString, cost_function::Function, spec::T) where T<:Vector{IOExample}
+    function MetricProblem(name::AbstractString, cost_function::Function,
+            spec::T) where {T <: Vector{IOExample}}
         new{T}(name, cost_function, spec)
     end
-
 end
 
-
 """
     Base.getindex(p::Problem{Vector{IOExample}}, indices)
 
 Overwrite `Base.getindex` to allow for slicing of input/output-based problems.
 """
 Base.getindex(p::Problem{Vector{IOExample}}, indices) = Problem(p.spec[indices])
 Base.getindex(p::MetricProblem{Vector{IOExample}}, indices) = Problem(p.spec[indices])
-
-

test/runtests.jl

@@ -2,5 +2,5 @@ using HerbSpecification
 using Test
 
 @testset "HerbSpecification.jl" verbose=true begin
-    include("test_ioproblem.jl") 
+    include("test_ioproblem.jl")
 end

test/test_ioproblem.jl

@@ -11,7 +11,8 @@ end
 # Tests for Problem
 @testset "Problem Tests" begin
     # Create a vector of IOExample instances as specification
-    spec = [IOExample(Dict(:var1 => 1, :var2 => 2), 3), IOExample(Dict(:var1 => 4, :var2 => 5), 6)]
+    spec = [IOExample(Dict(:var1 => 1, :var2 => 2), 3),
+        IOExample(Dict(:var1 => 4, :var2 => 5), 6)]
 
     # Test constructor without a name
     problem1 = Problem(spec)