Add support for Arrangements.

Package.swift

@@ -20,7 +20,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
-        .package(url: "https://github.com/mipalgu/VHDLMachines", from: "2.0.0"),
+        .package(url: "https://github.com/mipalgu/VHDLMachines", from: "2.1.0"),
         .package(url: "https://github.com/mipalgu/VHDLParsing", from: "2.4.0"),
         .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
         .package(url: "https://github.com/mipalgu/VHDLKripkeStructureGenerator.git", from: "0.2.0"),

Sources/JavascriptModel/ArrangementModel.swift

@@ -0,0 +1,97 @@
+// ArrangementModel.swift
+// LLFSMGenerate
+// 
+// Created by Morgan McColl.
+// Copyright © 2024 Morgan McColl. All rights reserved.
+// 
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+// 
+// 1. Redistributions of source code must retain the above copyright
+//    notice, this list of conditions and the following disclaimer.
+// 
+// 2. Redistributions in binary form must reproduce the above
+//    copyright notice, this list of conditions and the following
+//    disclaimer in the documentation and/or other materials
+//    provided with the distribution.
+// 
+// 3. All advertising materials mentioning features or use of this
+//    software must display the following acknowledgement:
+// 
+//    This product includes software developed by Morgan McColl.
+// 
+// 4. Neither the name of the author nor the names of contributors
+//    may be used to endorse or promote products derived from this
+//    software without specific prior written permission.
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+// OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// 
+// -----------------------------------------------------------------------
+// This program is free software; you can redistribute it and/or
+// modify it under the above terms or under the terms of the GNU
+// General Public License as published by the Free Software Foundation;
+// either version 2 of the License, or (at your option) any later version.
+// 
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// 
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, see http://www.gnu.org/licenses/
+// or write to the Free Software Foundation, Inc., 51 Franklin Street,
+// Fifth Floor, Boston, MA  02110-1301, USA.
+
+/// This struct represents an `Arrangement`.
+/// 
+/// An arrangement is the top-level structure of a group of Logic-Labelled Finite-State Machines. The
+/// arrangement defines which variables are sensors/actuators/clocks and which variables are local to the
+/// arrangement. It also contains a list of machines that are executing in the arrangement.
+public struct ArrangementModel: Equatable, Hashable, Codable, Sendable {
+
+    /// The clocks used in this arrangement. Clocks exist outside the scope of the arrangement.
+    public var clocks: [ClockModel]
+
+    /// The external variables used in this arrangement. External variables represent external
+    /// actuators/sensors and may affect the environment.
+    public var externalVariables: String
+
+    /// The machines executing within the arrangement, and the relavent variable mapping to each machine.
+    public var machines: [MachineReference]
+
+    /// The variables that are local to the arrangement. These variables may be shared amongst many machines
+    /// but cannot affect the outside world.
+    public var globalVariables: String
+
+    /// Initialise the arrangement from it's stored properties.
+    /// - Parameters:
+    ///   - clocks: The clocks used in this arrangement.
+    ///   - externalVariables: The external variables used in this arrangement.
+    ///   - machines: The machines executing within the arrangement.
+    ///   - globalVariables: The variables accessible to all machines within the arrangement but local to the
+    /// arrangement.
+    @inlinable
+    public init(
+        clocks: [ClockModel],
+        externalVariables: String,
+        machines: [MachineReference],
+        globalVariables: String
+    ) {
+        self.clocks = clocks
+        self.externalVariables = externalVariables
+        self.machines = machines
+        self.globalVariables = globalVariables
+    }
+
+}

Sources/JavascriptModel/MachineReference.swift

@@ -0,0 +1,87 @@
+// MachineReference.swift
+// LLFSMGenerate
+// 
+// Created by Morgan McColl.
+// Copyright © 2024 Morgan McColl. All rights reserved.
+// 
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+// 
+// 1. Redistributions of source code must retain the above copyright
+//    notice, this list of conditions and the following disclaimer.
+// 
+// 2. Redistributions in binary form must reproduce the above
+//    copyright notice, this list of conditions and the following
+//    disclaimer in the documentation and/or other materials
+//    provided with the distribution.
+// 
+// 3. All advertising materials mentioning features or use of this
+//    software must display the following acknowledgement:
+// 
+//    This product includes software developed by Morgan McColl.
+// 
+// 4. Neither the name of the author nor the names of contributors
+//    may be used to endorse or promote products derived from this
+//    software without specific prior written permission.
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+// OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// 
+// -----------------------------------------------------------------------
+// This program is free software; you can redistribute it and/or
+// modify it under the above terms or under the terms of the GNU
+// General Public License as published by the Free Software Foundation;
+// either version 2 of the License, or (at your option) any later version.
+// 
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// 
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, see http://www.gnu.org/licenses/
+// or write to the Free Software Foundation, Inc., 51 Franklin Street,
+// Fifth Floor, Boston, MA  02110-1301, USA.
+
+/// This struct represents an instance of a machine within the Arrangement context.
+/// 
+/// A `MachineReference` acts as an instance of a particular machine within an `Arrangement`. The reference
+/// consists of a `name` that identifies it as a unique instance of a machine, a `path` that points to the
+/// machine that it references, and a list of `mappings` that map variables from the arrangement into the
+/// machine's external variable and clock definitions.
+public struct MachineReference: Equatable, Hashable, Codable, Sendable {
+
+    /// The name of the reference.
+    public var name: String
+
+    /// The path to the machine that this reference points to.
+    public var path: String
+
+    /// The mappings from variables within the arrangement to the external variables and clocks within the
+    /// machines context.
+    public var mappings: [VariableMapping]
+
+    /// Create a new `MachineReference` from it's stored properties.
+    /// - Parameters:
+    ///   - name: The name of the reference.
+    ///   - path: The path to the machine that this reference points to.
+    ///   - mappings: The variable mappings from the external context into the machine's external and clock
+    /// variables.
+    @inlinable
+    public init(name: String, path: String, mappings: [VariableMapping]) {
+        self.name = name
+        self.path = path
+        self.mappings = mappings
+    }
+
+}

Sources/JavascriptModel/VariableMapping.swift

@@ -0,0 +1,78 @@
+// VariableMapping.swift
+// LLFSMGenerate
+// 
+// Created by Morgan McColl.
+// Copyright © 2024 Morgan McColl. All rights reserved.
+// 
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+// 
+// 1. Redistributions of source code must retain the above copyright
+//    notice, this list of conditions and the following disclaimer.
+// 
+// 2. Redistributions in binary form must reproduce the above
+//    copyright notice, this list of conditions and the following
+//    disclaimer in the documentation and/or other materials
+//    provided with the distribution.
+// 
+// 3. All advertising materials mentioning features or use of this
+//    software must display the following acknowledgement:
+// 
+//    This product includes software developed by Morgan McColl.
+// 
+// 4. Neither the name of the author nor the names of contributors
+//    may be used to endorse or promote products derived from this
+//    software without specific prior written permission.
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+// OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+// 
+// -----------------------------------------------------------------------
+// This program is free software; you can redistribute it and/or
+// modify it under the above terms or under the terms of the GNU
+// General Public License as published by the Free Software Foundation;
+// either version 2 of the License, or (at your option) any later version.
+// 
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// 
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, see http://www.gnu.org/licenses/
+// or write to the Free Software Foundation, Inc., 51 Franklin Street,
+// Fifth Floor, Boston, MA  02110-1301, USA.
+
+/// A mapping of a variables value in one domain into a variables in another domain.
+///
+/// This struct represents data flow from a `source` to a `destination`. The `source` and `destination`
+/// properties represent the respective variable names for the data flow.
+public struct VariableMapping: Equatable, Hashable, Codable, Sendable {
+
+    /// The name of the source variable.
+    public var source: String
+
+    /// The name of the destination variable.
+    public var destination: String
+
+    /// Initialise the variable mapping with a source and destination.
+    /// - Parameters:
+    ///   - source: The name of the source variable.
+    ///   - destination: The name of the destination variable.
+    @inlinable
+    public init(source: String, destination: String) {
+        self.source = source
+        self.destination = destination
+    }
+
+}

Sources/MachineGenerator/CleanCommand.swift

@@ -83,6 +83,12 @@ struct CleanCommand: ParsableCommand {
             return
         }
         try cleanBuildFolder(manager: manager)
+        guard !options.pathURL.lastPathComponent.lowercased().hasSuffix(".arrangement") else {
+            _ = try? manager.removeItem(
+                at: options.pathURL.appendingPathComponent("arrangement.json", isDirectory: false)
+            )
+            return
+        }
         try cleanMachine(manager: manager)
     }
 

Sources/MachineGenerator/Generate.swift

@@ -74,7 +74,7 @@ struct Generate: ParsableCommand {
     /// Whether to perform a model generation. If this flag is specified, the program will
     /// generate the javascript model from the existing machine on the file system.
     @Flag(
-        help: "Regenerate the Javascript model. If this flag is specified, the program will generate the javascript model from the existing machine on the file system."
+        help: "Regenerate the Javascript model. If this flag is specified, the program will generate the javascript model from the existing LLFSM format on the file system."
     )
     var exportModel = false
 
@@ -132,12 +132,25 @@ struct Generate: ParsableCommand {
     @inlinable
     mutating func run() throws {
         guard exportModel else {
+            guard !pathURL.lastPathComponent.lowercased().hasSuffix(".arrangement") else {
+                try createArrangement()
+                return
+            }
             try createMachine()
             return
         }
         try createModel()
     }
 
+    func createArrangement() throws {
+        let model = try decoder.decode(ArrangementModel.self, from: model)
+        guard let arrangement = Arrangement(model: model) else {
+            throw GenerationError.invalidGeneration(message: "Cannot create valid arrangement from model.")
+        }
+        let data = try encoder.encode(arrangement)
+        try data.write(to: pathURL.appendingPathComponent("arrangement.json", isDirectory: false))
+    }
+
     /// Create a machine from the model.
     /// - Throws: `GenerationError.invalidGeneration` if the machine cannot be created from the model.
     @inlinable

Sources/MachineGenerator/LLFSMGenerate.swift

@@ -64,7 +64,7 @@ struct LLFSMGenerate: ParsableCommand {
     static var configuration = CommandConfiguration(
         commandName: "llfsmgenerate",
         abstract: "A utility for performing operations on LLFSM formats.",
-        version: "1.2.0",
+        version: "1.3.0",
         subcommands: [Generate.self, VHDLGenerator.self, CleanCommand.self, InstallCommand.self]
     )