netlinx-workspace 0.3.0 → 1.0.0

data/lib/netlinx/rake/workspace/generate_apw.rb

@@ -0,0 +1,41 @@
+require 'rake'
+require 'rake/tasklib'
+
+module NetLinx
+  module Rake
+    module Workspace
+      
+      # Generate .apw workspace file from yaml config.
+      class GenerateAPW < ::Rake::TaskLib
+        
+        attr_accessor :name
+        
+        def initialize name = :generate_apw
+          @name = name
+          yield self if block_given?
+          
+          desc "Generate .apw workspace file from yaml config."
+          
+          task(name) do
+            require 'netlinx/workspace'
+            
+            workspace_file = 'workspace.config.yaml'
+            
+            unless File.exists? workspace_file
+              puts "File not found: #{workspace_file}"
+              next
+            end
+            
+            NetLinx::Workspace::YAML.parse_file(workspace_file).tap do |workspace|
+              return unless workspace.name
+              File.open("#{workspace.name.strip}.apw", 'w') do |f|
+                f.write workspace.to_xml
+              end
+            end
+          end
+        end
+        
+      end
+    end
+  end
+end

data/lib/netlinx/workspace.rb

@@ -1,8 +1,11 @@
+# Gem convenience includes.
+require_relative 'workspace/yaml'
+
+# File includes.
 require 'rexml/document'
-require 'netlinx/project'
+require_relative 'workspace/project'
 
 module NetLinx
-  
   # A NetLinx Studio workspace.
   # Collection of projects.
   # Workspace -> Project -> System
@@ -26,17 +29,19 @@ module NetLinx
       nil
     end
     
-    def initialize(**kvargs)
-      @name        = kvargs.fetch :name, ''
-      @description = kvargs.fetch :description, ''
+    # @option kwargs [String] :name ('') Workspace name.
+    # @option kwargs [String] :description ('')
+    def initialize **kwargs
+      @name        = kwargs.fetch :name, ''
+      @description = kwargs.fetch :description, ''
       @projects    = []
       
-      @file = kvargs.fetch :file, nil
+      @file = kwargs.fetch :file, nil
       load_workspace @file if @file
     end
     
     # Alias to add a project.
-    def <<(project)
+    def << project
       @projects << project
       project.workspace = self
     end
@@ -51,8 +56,8 @@ module NetLinx
       File.dirname @file if @file
     end
     
-    # Returns true if the workspace contains the specified file.
-    def include?(file)
+    # @return true if the workspace contains the specified file.
+    def include? file
       included = false
       
       projects.each do |project|
@@ -74,10 +79,45 @@ module NetLinx
       compiler_results
     end
     
+    # @return [REXML::Element] an XML element representing this workspace.
+    def to_xml_element
+      REXML::Element.new('Workspace').tap do |workspace|
+        workspace.attributes['CurrentVersion'] = '4.0'
+        
+        workspace.add_element('Identifier').tap { |e| e.text = name }
+        workspace.add_element('CreateVersion').tap { |e| e.text = '4.0' }
+        workspace.add_element('Comments').tap { |e| e.text = description }
+        
+        @projects.each { |project| workspace << project.to_xml_element }
+      end
+    end
+    
+    # @return [String] an XML string representing this workspace.
+    # 
+    # @todo REXML bug forces :indent to be -1 or else erroneous line feeds are added.
+    #   https://bugs.ruby-lang.org/issues/10864
+    def to_xml indent: -1
+      str = '<?xml version="1.0" encoding="UTF-8"?>' + "\n"
+      
+      REXML::Document.new.tap do |doc|
+        doc << to_xml_element
+        doc.write output: str, indent: indent
+      end
+      
+      str + "\n"
+    end
+    
+    # Generate a {NetLinx::Workspace} from an XML string.
+    # @return self
+    def parse_xml string
+      parse_xml_element REXML::Document.new(string)
+      self
+    end
+    
     private
     
     # Load the workspace from a given NetLinx Studio .apw file.
-    def load_workspace(file)
+    def load_workspace file
       raise LoadError, "File does not exist at:\n#{file}" unless File.exists? file
       
       doc = nil
@@ -85,12 +125,16 @@ module NetLinx
         doc = REXML::Document.new f
       end
       
+      parse_xml_element doc
+    end
+    
+    def parse_xml_element root
       # Load workspace params.
-      @name        = doc.elements['/Workspace/Identifier'].text.strip
-      @description = doc.elements['/Workspace/Comments'].text
-      
+      @name        = root.elements['/Workspace/Identifier'].text.strip || ''
+      @description = root.elements['/Workspace/Comments'].text || ''
+        
       # Load projects.
-      doc.each_element '/Workspace/Project' do |e|
+      root.each_element '/Workspace/Project' do |e|
         project = NetLinx::Project.new \
           element:   e,
           workspace: self

data/lib/netlinx/workspace/project.rb

@@ -0,0 +1,107 @@
+require 'rexml/document'
+require_relative 'system'
+
+module NetLinx
+  # A collection of NetLinx systems.
+  # Workspace -> Project -> System
+  class Project
+    # A reference to the project's parent workspace.
+    attr_accessor :workspace
+    attr_accessor :name
+    attr_accessor :description
+    attr_accessor :dealer
+    attr_accessor :designer
+    attr_accessor :sales_order
+    attr_accessor :purchase_order
+    attr_accessor :systems
+    
+    # @option kwargs [NetLinx::Workspace] :workspace This system's parent workspace node.
+    # @option kwargs [String] :name ('') Project name.
+    # @option kwargs [String] :description ('')
+    # @option kwargs [String] :dealer ('')
+    # @option kwargs [String] :designer ('')
+    # @option kwargs [String] :sales_order ('')
+    # @option kwargs [String] :purchase_order ('')
+    def initialize **kwargs
+      @workspace      = kwargs.fetch :workspace,      nil
+      
+      @name           = kwargs.fetch :name,           ''
+      @description    = kwargs.fetch :description,    ''
+      @dealer         = kwargs.fetch :dealer,         ''
+      @designer       = kwargs.fetch :designer,       ''
+      @sales_order    = kwargs.fetch :sales_order,    ''
+      @purchase_order = kwargs.fetch :purchase_order, ''
+      
+      @systems = []
+      
+      project_element = kwargs.fetch :element, nil
+      parse_xml_element project_element if project_element
+    end
+    
+    # Alias to add a system.
+    def << system
+      @systems << system
+      system.project = self
+    end
+    
+    # @return the project name.
+    def to_s
+      @name
+    end
+    
+    # @return true if the project contains the specified file.
+    def include? file
+      included = false
+      
+      systems.each do |system|
+        included = system.include? file
+        break if included
+      end
+      
+      included
+    end
+    
+    # Compile all systems in this project.
+    def compile
+      compiler_results = []
+      @systems.each {|system| compiler_results << (system.compile).first}
+      compiler_results
+    end
+    
+    # @return [REXML::Element] an XML element representing this project.
+    def to_xml_element
+      REXML::Element.new('Project').tap do |project|
+        project.add_element('Identifier').tap { |e| e.text = name }
+        project.add_element('Designer').tap { |e| e.text = designer }
+        project.add_element('DealerID').tap { |e| e.text = dealer }
+        project.add_element('SalesOrder').tap { |e| e.text = sales_order }
+        project.add_element('PurchaseOrder').tap { |e| e.text = purchase_order }
+        project.add_element('Comments').tap { |e| e.text = description }
+        
+        @systems.each { |system| project << system.to_xml_element }
+      end
+    end
+    
+    private
+    
+    def parse_xml_element project
+      # Load project params.
+      @name           = project.elements['Identifier'].text.strip || ''
+      @designer       = project.elements['Designer'].text || ''
+      @dealer         = project.elements['DealerID'].text || ''
+      @sales_order    = project.elements['SalesOrder'].text || ''
+      @purchase_order = project.elements['PurchaseOrder'].text || ''
+      @description    = project.elements['Comments'].text || ''
+        
+      # Load systems.
+      project.each_element 'System' do |e|
+        system = NetLinx::System.new \
+          element: e,
+          project:  self
+          
+        @systems << system
+      end
+    end
+    
+  end
+end

data/lib/netlinx/workspace/system.rb

@@ -0,0 +1,226 @@
+require 'rexml/document'
+require_relative 'system_file'
+
+module NetLinx
+  # A collection of resources loaded onto a NetLinx master.
+  # Workspace -> Project -> System
+  class System
+    # A reference to the system's parent project.
+    attr_accessor :project
+    attr_accessor :files
+    
+    attr_accessor :name
+    attr_accessor :active
+    attr_accessor :id
+    attr_accessor :description
+    
+    attr_accessor :ip_address
+    attr_accessor :ip_port
+    attr_accessor :ensure_availability
+    
+    attr_accessor :com_port
+    attr_accessor :baud_rate
+    attr_accessor :data_bits
+    attr_accessor :parity
+    attr_accessor :stop_bits
+    attr_accessor :flow_control
+    
+    # @option kwargs [NetLinx::Project] :project This system's parent project node.
+    # @option kwargs [String] :name ('') System name.
+    # @option kwargs [String] :description ('')
+    # @option kwargs [Boolean] :active (false) True if this is the active system
+    #   in the workspace.
+    # @option kwargs [Integer] :id (0) Master controller system ID.
+    #   0 connects to any master at the given communication settings.
+    #   Or in other words, 0 prevents disconnection from a master
+    #   with a different ID.
+    # 
+    # @option kwargs [String] :ip_address ('0.0.0.0')
+    # @option kwargs [String] :ip_port (1319) ICSLan port.
+    # @option kwargs [String] :ensure_availability (true) Ping the master
+    #   controller to ensure availability before connecting.
+    # 
+    # @option kwargs [Symbol] :com_port (:com1)
+    # @option kwargs [Integer] :baud_rate (38400)
+    # @option kwargs [Integer] :data_bits (8)
+    # @option kwargs [:none,:even,:odd,:mark,:space] :parity (:none)
+    # @option kwargs [Integer] :stop_bits (1)
+    # @option kwargs [:none] :flow_control (:none)
+    def initialize **kwargs
+      @project     = kwargs.fetch :project,     nil
+      
+      @name        = kwargs.fetch :name,        ''
+      @id          = kwargs.fetch :id,          0
+      @active      = kwargs.fetch :active,      false
+      @description = kwargs.fetch :description, ''
+      
+      @ip_address  = kwargs.fetch :ip_address, '0.0.0.0'
+      @ip_port     = kwargs.fetch :ip_port, 1319
+      @ensure_availability = kwargs.fetch :ensure_availability, true
+      
+      @com_port     = kwargs.fetch :com_port,     :com1
+      @baud_rate    = kwargs.fetch :baud_rate,    38400
+      @data_bits    = kwargs.fetch :data_bits,    8
+      @parity       = kwargs.fetch :parity,       :none
+      @stop_bits    = kwargs.fetch :stop_bits,    1
+      @flow_control = kwargs.fetch :flow_control, :none
+      
+      @files = []
+      
+      @compiler_target_files  = []
+      @compiler_include_paths = []
+      @compiler_module_paths  = []
+      @compiler_library_paths = []
+      
+      system_element = kwargs.fetch :element, nil
+      parse_xml_element system_element if system_element
+    end
+    
+    # Alias to add a file.
+    def << file
+      @files << file
+      file.system = self
+    end
+    
+    # @return the system name.
+    def to_s
+      @name
+    end
+    
+    # @return [REXML::Element] an XML element representing this system.
+    def to_xml_element
+      REXML::Element.new('System').tap do |system|
+        system.attributes['IsActive']  = active
+        system.attributes['Platform']  = 'Netlinx'
+        system.attributes['Transport'] = 'Serial'
+        system.attributes['TransportEx'] =
+          (ip_address == '0.0.0.0') ? 'Serial' : 'TCPIP'
+        
+        system.add_element('Identifier').tap { |e| e.text = name }
+        system.add_element('SysID').tap { |e| e.text = id }
+        system.add_element('Comments').tap { |e| e.text = description }
+        
+        # These don't seem to change in NetLinx Studio 4.0; possibly 3.x legacy.
+        # The 'Ex' suffixes are used.
+        system.add_element('TransTCPIP').tap { |e| e.text = '0.0.0.0' }
+        system.add_element('TransSerial').tap { |e| e.text = 'COM1,38400,8,None,1,None' }
+        
+        # TODO: Generate communication settings.
+        system.add_element('TransTCPIPEx').tap { |e|
+          e.text = "#{ip_address}|#{ip_port}|#{ensure_availability ? 1 : 0}|||"
+        }
+        system.add_element('TransSerialEx').tap { |e|
+          e.text = "#{com_port.upcase}|#{baud_rate}|#{data_bits}|#{parity.capitalize}|#{stop_bits}|||"
+        }
+        system.add_element('TransUSBEx').tap { |e| e.text = '|||||' }
+        system.add_element('TransVNMEx').tap { |e| e.text = '||' }
+        
+        system.add_element('UserName').tap { |e| e.text = '' }
+        system.add_element('Password').tap { |e| e.text = '' }
+        
+        @files.each { |file| system << file.to_xml_element }
+      end
+    end
+    
+    # @see Test::NetLinx::Compilable.
+    def compiler_target_files
+      @files
+        .select {|f| f.type == :master}
+        .map {|f| File.expand_path \
+          f.path.gsub('\\', '/'),
+          f.system.project.workspace.path
+        }.uniq
+    end
+    
+    # @see Test::NetLinx::Compilable.
+    def compiler_include_paths
+      @files
+        .select {|f| f.type == :include}
+        .map {|f| File.expand_path \
+          File.dirname(f.path.gsub('\\', '/')),
+          f.system.project.workspace.path
+        }.uniq
+    end
+    
+    # @see Test::NetLinx::Compilable.
+    def compiler_module_paths
+      @files
+        .select {|f| f.type == :module || f.type == :tko || f.type == :duet}
+        .map {|f| File.expand_path \
+          File.dirname(f.path.gsub('\\', '/')),
+          f.system.project.workspace.path
+        }.uniq
+    end
+    
+    # @see Test::NetLinx::Compilable.
+    def compiler_library_paths
+      []
+    end
+    
+    # @return [Boolean] true if the project contains the specified file. 
+    def include? file
+      included = false
+      
+      @files.each do |f|
+        name_included = f.name.downcase.eql? file.downcase
+        
+        # TODO: This should probably be relative to the workspace path,
+        #       which can be found by traversing @project, @workspace.
+        path_included = file.gsub(/\\/, '/').include? f.path.gsub(/\\/, '/')
+        
+        included = name_included || path_included
+        break if included
+      end
+      
+      included
+    end
+    
+    # Compile this system.
+    def compile
+      # The compiler dependency is only needed if this method is called.
+      require 'netlinx/compiler'
+      
+      compiler = NetLinx::Compiler.new
+      compiler.compile self
+    end
+    
+    private
+    
+    def parse_xml_element system
+      # Load system params.
+      @name        = system.elements['Identifier'].text.strip || ''
+      @active      = (system.attributes['IsActive'].strip == 'true') ? true : false
+      @id          = system.elements['SysID'].text.strip.to_i || 0
+      @description = system.elements['Comments'].text || ''
+      
+      if system.elements['TransTCPIPEx'] # Workspace v4.0
+        tcpip = (system.elements['TransTCPIPEx'].text || '').split('|')
+        
+        @ip_address  = tcpip[0] || '0.0.0.0'
+        @ip_port     = (tcpip[1] || 1319).to_i
+        @ensure_availability = (tcpip[2] == '0') ? false : true
+      end
+      
+      if system.elements['TransSerialEx'] # Workspace v4.0
+        serial = (system.elements['TransSerialEx'].text || '').split('|')
+        
+        @com_port     = (serial[0] || :com1).to_s.downcase.to_sym
+        @baud_rate    = (serial[1] || 38400).to_i
+        @data_bits    = (serial[2] || 8).to_i
+        @parity       = (serial[3] || :none).to_s.downcase.to_sym
+        @stop_bits    = (serial[4] || 1).to_i
+        @flow_control = (serial[5] || :none).to_s.downcase.to_sym
+      end
+      
+      # Create system files.
+      system.each_element 'File' do |e|
+        system_file = NetLinx::SystemFile.new \
+          element: e,
+          system:  self
+        
+        @files << system_file
+      end
+    end
+    
+  end
+end