ci: add rust continuous integration

Author: Dekker1

.github/workflows/rust.yml

@@ -0,0 +1,75 @@
+name: Rust
+
+on:
+  pull_request:
+  push:
+    branches:
+      - develop
+
+jobs:
+  test:
+    name: Test (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: no-default-features
+            args: "--no-default-features"
+          - name: default-features (serde)
+            args: ""
+          - name: fzn
+            args: "--no-default-features --features fzn"
+          - name: all-features
+            args: "--all-features"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: cargo build ${{ matrix.args }}
+      - name: Test
+        run: cargo test ${{ matrix.args }}
+
+  clippy:
+    name: Clippy (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: no-default-features
+            args: "--no-default-features"
+          - name: default-features (serde)
+            args: ""
+          - name: fzn
+            args: "--no-default-features --features fzn"
+          - name: all-features
+            args: "--all-features"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: clippy
+      - name: Cache cargo artifacts
+        uses: Swatinem/rust-cache@v2
+      - name: Run clippy
+        run: cargo clippy --all-targets ${{ matrix.args }} -- -D warnings
+
+  fmt:
+    name: Rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
+      - name: Run rustfmt
+        run: cargo fmt --all --check

Cargo.toml

@@ -40,7 +40,6 @@ trivial_numeric_casts = "warn"
 unit_bindings = "warn"
 unnameable_types = "warn"
 unreachable_pub = "warn"
-unused_crate_dependencies = "deny"
 unused_import_braces = "warn"
 unused_lifetimes = "warn"
 unused_macro_rules = "warn"

src/fzn.rs

@@ -15,8 +15,8 @@ use annotations::*;
 pub use error::FznParseError;
 use primitives::*;
 use winnow::{
-	combinator::{alt, delimited, opt, preceded, separated, separated_pair},
 	Parser, Result, Stateful,
+	combinator::{alt, delimited, opt, preceded, separated, separated_pair},
 };
 
 use crate::{
@@ -35,18 +35,28 @@ enum Declaration<Identifier> {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
+/// Represents the current parsing phase.
 enum ParsePhase {
+	/// Accepting all items, possibly already parsed a predicate declaration.
 	Predicates,
+	/// Parsed a array/variable declaration item, no longer accepting predicate
+	/// declarations.
 	Declarations,
+	/// Parsed a constraint item, no longer accepting predicate or
+	/// array/variable declarations.
 	Constraints,
+	/// Parsed a solve item, no longer accepting any items.
 	Solve,
 }
 
 #[derive(Debug, PartialEq)]
+/// State used during parsing.
 struct ParseState<'s, Identifier> {
+	/// Collection of parsed parameters to be replaced in constraint arguments.
 	parameters: &'s mut HashMap<String, Literal<Identifier>>,
 }
 
+/// Type used for the parser input and state.
 type Stream<'source, 'state, Identifier> = Stateful<&'source str, ParseState<'state, Identifier>>;
 
 /// Parses a constraint argument.
@@ -127,8 +137,8 @@ where
 
 /// Parses the domain in a variable declaration.
 ///
-/// Has no direct analogue in the grammar. However, it is essentially the `<basic-var-type>`
-/// without the "var" token preceding it:
+/// Has no direct analogue in the grammar. However, it is essentially the
+/// `<basic-var-type>` without the "var" token preceding it:
 ///
 /// ```bnf
 /// <basic-var-type> ::= "var" <basic-par-type>
@@ -197,6 +207,7 @@ where
 	.parse_next(input)
 }
 
+/// Parse a parameter declaration item.
 fn parameter_item<Identifier>(
 	input: &mut Stream<'_, '_, Identifier>,
 ) -> Result<(String, Literal<Identifier>)>
@@ -537,7 +548,7 @@ where
 		.parse_next(input)
 }
 
-/// Parse a variable model item.
+/// Parse a variable declaration item.
 fn variable<Identifier>(
 	input: &mut Stream<'_, '_, Identifier>,
 ) -> Result<(Identifier, Variable<Identifier>, bool)>
@@ -583,15 +594,15 @@ mod tests {
 
 	use rangelist::RangeList;
 	use ustr::Ustr;
-	use winnow::{error::ParserError, Parser, Stateful};
+	use winnow::{Parser, Stateful, error::ParserError};
 
 	use crate::{
-		fzn::{
-			array_item, constraint, parameter_item, predicate_item, solve_objective, variable,
-			ParseState, Stream,
-		},
 		Annotation, AnnotationArgument, AnnotationCall, AnnotationLiteral, Argument, Array,
 		Constraint, FlatZinc, FznParseError, Literal, Method, SolveObjective, Type, Variable,
+		fzn::{
+			ParseState, Stream, array_item, constraint, parameter_item, predicate_item,
+			solve_objective, variable,
+		},
 	};
 
 	#[test]

src/fzn/annotations.rs

@@ -6,20 +6,23 @@ use std::{
 };
 
 use winnow::{
-	combinator::{alt, delimited, opt, preceded, repeat, separated},
 	Parser, Result,
+	combinator::{alt, delimited, opt, preceded, repeat, separated},
 };
 
 use crate::{
-	fzn::{identifier, identifier_raw, literal, token, Stream},
 	Annotation, AnnotationArgument, AnnotationCall, AnnotationLiteral, FznParseError, Literal,
+	fzn::{Stream, identifier, identifier_raw, literal, token},
 };
 
 /// Semantic flags projected out of special FlatZinc annotations.
 #[derive(Default)]
 pub(crate) struct AnnotationFlags {
+	/// Whether the variable is defined by a constraint
 	pub(crate) defined: bool,
+	/// Whether the variable was additionally introduced by the compiler.
 	pub(crate) introduced: bool,
+	/// Whether the variable is an output variable.
 	pub(crate) output: bool,
 }
 
@@ -77,8 +80,8 @@ where
 
 /// Parses an annotation with arguments.
 ///
-/// This does not have an analogue in the FZN grammar. It is only used to parse annotation
-/// arguments that are nested annotation calls.
+/// This does not have an analogue in the FZN grammar. It is only used to parse
+/// annotation arguments that are nested annotation calls.
 fn annotation_call<Identifier>(
 	input: &mut Stream<'_, '_, Identifier>,
 ) -> Result<AnnotationCall<Identifier>>
@@ -120,6 +123,8 @@ where
 	.parse_next(input)
 }
 
+/// Parses the annotations for a constraint, returning optionally the identifier
+/// of the defined variable and a list of annotations.
 pub(super) fn constraint_annotations<Identifier>(
 	input: &mut Stream<'_, '_, Identifier>,
 ) -> Result<(Option<Identifier>, Vec<Annotation<Identifier>>)>
@@ -167,6 +172,7 @@ where
 		.parse_next(input)
 }
 
+/// Parses a general list of annotations.
 pub(super) fn general_annotations<Identifier>(
 	input: &mut Stream<'_, '_, Identifier>,
 ) -> Result<Vec<Annotation<Identifier>>>
@@ -199,6 +205,8 @@ where
 		.parse_next(input)
 }
 
+/// Parses the annotations for a variable declaration, returning flags for
+/// standard annotations and a list of other annotations.
 pub(super) fn variable_annotations<Identifier>(
 	input: &mut Stream<'_, '_, Identifier>,
 ) -> Result<(AnnotationFlags, Vec<Annotation<Identifier>>)>
@@ -257,8 +265,8 @@ mod tests {
 	use rangelist::RangeList;
 
 	use crate::{
-		fzn::{general_annotations, tests::check_parser},
 		Annotation, AnnotationArgument, AnnotationCall, AnnotationLiteral, Literal,
+		fzn::{general_annotations, tests::check_parser},
 	};
 
 	#[test]

src/fzn/primitives.rs

@@ -7,15 +7,15 @@ use std::{
 
 use rangelist::RangeList;
 use winnow::{
+	Parser, Result,
 	ascii::{digit1, hex_digit1, multispace1, oct_digit1},
 	combinator::{alt, delimited, opt, separated, separated_pair, trace},
 	error::{ContextError, FromExternalError},
 	stream::AsChar,
 	token::{one_of, take_till, take_until, take_while},
-	Parser, Result,
 };
 
-use crate::{fzn::Stream, FznParseError, Literal};
+use crate::{FznParseError, Literal, fzn::Stream};
 
 /// Parse a `/* ... */` block comment.
 fn block_comment<I>(input: &mut Stream<'_, '_, I>) -> Result<()>
@@ -37,8 +37,8 @@ pub(super) fn boolean<I: Debug>(input: &mut Stream<'_, '_, I>) -> Result<bool> {
 	alt(("true".map(|_| true), "false".map(|_| false))).parse_next(input)
 }
 
-/// Parses a list of elements seperated by a comma, and delimited by `open_token` and
-/// `close_token`.
+/// Parses a list of elements seperated by a comma, and delimited by
+/// `open_token` and `close_token`.
 pub(super) fn delimited_list<'source, 'state, T, I>(
 	open_token: &'static str,
 	element_parser: impl Parser<Stream<'source, 'state, I>, T, ContextError>,
@@ -212,9 +212,10 @@ where
 	Identifier: Clone + Debug + FromStr,
 	<Identifier as FromStr>::Err: Display,
 {
-	// This can be optimized if it turns out to be a bottleneck. At the moment, to parse a literal,
-	// it will first attempt to parse a float and, if that fails, parse an integer. We can be more
-	// clever about that by peeking at the next character to determine what is being parsed.
+	// This can be optimized if it turns out to be a bottleneck. At the moment, to
+	// parse a literal, it will first attempt to parse a float and, if that fails,
+	// parse an integer. We can be more clever about that by peeking at the next
+	// character to determine what is being parsed.
 
 	let parsed_literal = alt((
 		set(int).map(Literal::IntSet),
@@ -255,7 +256,9 @@ where
 ///
 /// Works with either interval sets or sparse sets.
 ///
-/// The grammar is modified from the documentation. Here we abstract the element type.
+/// The grammar is modified from the documentation. Here we abstract the element
+/// type.
+///
 /// ```bnf
 /// <set-literal> ::= <set-term> [ "union" <set-term> ] ...
 ///
@@ -306,8 +309,8 @@ mod tests {
 	use winnow::{Parser, Stateful};
 
 	use crate::{
-		fzn::{literal, tests::check_parser, ParseState},
 		Literal,
+		fzn::{ParseState, literal, tests::check_parser},
 	};
 
 	#[test]

src/lib.rs

@@ -671,6 +671,7 @@ impl<Identifier: Display> Display for SolveObjective<Identifier> {
 }
 
 impl Type {
+	/// Return the canonical FlatZinc type name without any domain restriction.
 	fn base_name(&self) -> &'static str {
 		match self {
 			Type::Bool => "bool",

src/serde.rs

@@ -4,9 +4,9 @@
 use std::{fmt, marker::PhantomData};
 
 use serde::{
+	Deserialize, Deserializer, Serialize, Serializer,
 	de::{MapAccess, Visitor},
 	ser::SerializeMap,
-	Deserialize, Deserializer, Serialize, Serializer,
 };
 
 use crate::{Annotation, Literal, Method, RangeList, SolveObjective, Type, Variable};
@@ -58,7 +58,8 @@ pub(crate) enum VariableDomain {
 	/// Integer domain payload serialized as a JSON array of inclusive bounds.
 	#[serde(deserialize_with = "deserialize_set", serialize_with = "serialize_set")]
 	Int(RangeList<i64>),
-	/// Floating-point domain payload serialized as a JSON array of inclusive bounds.
+	/// Floating-point domain payload serialized as a JSON array of inclusive
+	/// bounds.
 	#[serde(deserialize_with = "deserialize_set", serialize_with = "serialize_set")]
 	Float(RangeList<f64>),
 }
@@ -160,6 +161,7 @@ where
 	deserializer.deserialize_map(KeyValueObjectVisitor(PhantomData))
 }
 
+/// Deserialize a raw `(start, end)` range list into a [`RangeList`].
 pub(crate) fn deserialize_set<
 	'de,
 	D: Deserializer<'de>,