tla-sbuilder 0.1.0

data/lib/sbuilder/mustache/template.rb

@@ -0,0 +1,125 @@
+require 'mustache'                   # extendending implementation of
+
+module Sbuilder
+
+  class Template < Mustache
+
+    include Sbuilder::Utils::MyLogger   # mix logger
+    PROGNAME = "template"               # progname for logger
+
+    
+    # ------------------------------------------------------------------
+    # Attributes
+
+    # instance
+    attr_writer :partials            # f: partial-name --> template string
+    attr_reader :reader              # Sbuilder::TemplateReader implementing
+                                     # 'get_template', 'get_template_filepath'
+    
+    extend Forwardable               # for easy delegation
+    def_delegators :reader,:get_template, :get_template_filepath, :configSetup, :template_read
+    
+    # ------------------------------------------------------------------
+    # Constructor
+    
+    def initialize( reader, options={} )
+      @logger = getLogger( PROGNAME, options )
+      @logger.info( "#{__method__} created" )
+      @logger.debug( "#{__method__}, options='#{options}" )
+
+      # init partial cache
+      @partials = {}
+
+      # inject reader
+      #@reader = Sbuilder::TemplateReader.new( options )
+      @reader = reader
+
+    end
+
+    # ------------------------------------------------------------------
+    # Services
+    
+    def to_str( template_name, data )
+      @logger.info( "#{__method__}: template_name=#{template_name}" )
+      @logger.debug( "#{__method__}: template_name=#{template_name}" ) if @logger.debug?
+      # @logger.debug( "#{__method__}: nodes=#{data.nodes}" )
+      
+      # data = add_dynamic_load( data )
+      
+      @data = data
+      
+      template = get_template( template_name )
+      # render( template, @data )
+      
+      render( template, @data )
+    end
+
+    def render_str( template, data )
+      render( template, data )
+    end
+
+    # ------------------------------------------------------------------
+    # Integrate with mustache
+
+    # method used by mustache framework - delegate to 'get_partial'
+    def partial(name)
+      @logger.debug( "#{__method__} name=#{name}" )
+
+      return resolve_partial_direct(name[2..-1])  if name[0..1]  == '!!'
+      get_partial( resolve_partial_name(name) )
+    end
+
+    #
+    # @param path_template [String] mustache template string to intepret for path
+    #
+    # @return [String] content of file pointed by rendering 'path_template'
+    def resolve_partial_direct( path_template )
+      # change mustache delimerters to allow rendering
+      # templ = "{{=%% %%=}}#{path_template}<%={{ }}=%>"
+      puts path_template
+      templ = path_template
+      path = render( templ, @data )
+      template_read( path )
+    end
+
+    # lookup
+    def resolve_partial_name( name )
+      return name unless name[0..0]  == '!'
+      # remove !, split, and use injected traves to access data
+      ret = @data.traverse( *(name[1..-1].split( "." )) )
+      if ret.nil?
+        raise <<-EOS 
+                  Could not resolve #{name} in template data
+
+                  #{@data.to_yaml}
+
+        EOS
+      end
+      @logger.info( "#{__method__} name=#{name} --> #{ret}" )
+      ret
+    end
+
+    # ------------------------------------------------------------------
+    # Cache partials once resoved
+
+    # cache @partials - for easier extension
+    def get_partial( name ) 
+      @logger.debug( "#{__method__} name=#{name}" )
+      return @partials[name] if @partials[name]
+      @logger.info( "#{__method__} read partial_file=#{name}" )
+      
+      @partials[name] = get_template( name )
+      return @partials[name]
+
+      # partial_file = get_template_filepath( name )
+      # @logger.info( "#{__method__} read partial_file=#{partial_file}" )
+      # @partials[name] = File.read( partial_file )
+      # @partials[name]
+    end
+
+
+  end # class
+
+end # module
+
+

data/lib/sbuilder/mustache/template_reader.rb

@@ -0,0 +1,206 @@
+require 'mustache'                   # extendending implementation of
+
+# ------------------------------------------------------------------
+#
+# Entry-poinsts
+# - get_template
+# - get_template_filepath
+
+module Sbuilder
+
+  class TemplateReader
+
+    include Sbuilder::Utils::MyLogger   # mix logger
+    PROGNAME = "treader"                # progname for logger
+
+    
+    # ------------------------------------------------------------------
+    # Attributes
+
+    # instance
+    attr_reader :template_paths      # array of paths to search for templates
+    attr_writer :partials            # f: partial-name --> template string
+    attr_writer :templates           # f: template-name --> template string
+
+    # ------------------------------------------------------------------
+    # Constructor
+    
+    def initialize( controller, options={} )
+      @logger = getLogger( PROGNAME, options )
+      @logger.info( "#{__method__} created, options='#{options}" )
+
+      # use default templates - prefix with user specified templates
+      @template_paths = options[:default_templates]
+      # for mustache templates
+      if options[:templates] then
+        @template_paths = options[:templates] + (options[:default_templates] || [] )
+      end
+      
+      # # init partial cache
+      # @partials = {}
+
+    end
+
+    # ------------------------------------------------------------------
+    # Config - after contructor
+
+    # Null operation: no configuration actions taken. Maybe subclasses
+    # will implement something usefull
+    #
+    # @param steps [Hash] from 'model#templateData('steps')' with "steps"=>{'process', 'interface_name'}
+    # @param interfaces [Hash] from 'model#templateData('interfaces')' with "interface"=>{'interface_name', 'implementation'}    
+    
+    # def configSetup( steps, interfaces )
+    #   @logger.info( "#{__method__} steps=#{steps["steps"].join('\n')}" )
+    #   interfaces = interfaces["interfaces"] ? interfaces["interfaces"] : []
+    #   @logger.info( "#{__method__} interfaces=#{interfaces.join('\n')}" )
+    # end
+
+
+    # ------------------------------------------------------------------
+    # filter actions
+    
+    # default template when filtered
+    # @return [String] emptpy string for filtered templtae
+    def filtered_template
+      ""
+    end
+
+    # To override in sub-classes
+    #
+    # @return [Boolean] true - show allways
+    def show_template( name )
+      true
+    end
+    
+    
+
+    # ------------------------------------------------------------------
+    # Services
+
+    # Check whether template 'name' should be be shown, next resolve
+    # location of a template file, and do 'File.read' on the file path
+    #
+    # @return [String] for template content
+    def get_template( name )
+
+      if !show_template( name )
+        @logger.info( "#{__method__} filtered, name=#{name}" )
+        return filtered_template
+      end
+
+      template_file = get_template_filepath( name )
+      @logger.info( "#{__method__} read template_file=#{template_file}" )
+      #File.read( template_file )
+      template_read( template_file )
+
+    end # get_template( name )
+
+    # @param path [String] path name to template
+    # @return [String] for template content    
+    def template_read( path )
+      File.read( path  )
+    end
+                       
+          
+
+
+    # return path to an existing template file name
+    # @exception if template not found
+    def get_template_filepath( name ) 
+
+      @template_paths.each do |directory_or_gemname|
+        
+        template_path = get_template_filepath_resolve( directory_or_gemname, name ) 
+        return template_path if template_path && File.exists?( template_path ) 
+
+      end # each 
+
+
+      # could not find 
+      
+      raise <<-eos
+
+          No such template '#{name}' found in directories: #{@template_paths.join(", ")}
+        
+        eos
+      
+    end
+
+    # ------------------------------------------------------------------
+    # private
+
+    private
+    # return path to plain 'directory' or to gem directory
+    def get_template_filepath_resolve( directory_or_gemname, template_file )
+      @logger.info( "#{__method__} directory_or_gemname=#{directory_or_gemname}" )
+      if directory_or_gemname[-1] == '/' then
+        return get_template_filepath_in_directory( directory_or_gemname[0..-2], template_file )
+      else
+        directory = gemname_to_directory( directory_or_gemname )
+        return get_template_filepath_in_directory( directory, template_file )
+      end
+    end
+
+    # return directory to 'gemspec'
+    def gemname_to_directory( gemname_and_spec ) 
+
+      # The version requirements are optional.
+      # You can also specify multiple version requirements, just append more at the end
+      gem_spec = gemname_and_spec.split(',')
+      gem_name, *gem_ver_reqs = gem_spec[0], gem_spec[1]
+      @logger.debug( "#{__method__}, gem_name=#{gem_name}, *gem_ver_reqs=#{gem_ver_reqs}" )
+      gdep = Gem::Dependency.new(gem_name, *gem_ver_reqs)
+      # find latest that satisifies
+      found_gspec = gdep.matching_specs.sort_by(&:version).last
+      @logger.debug( "#{__method__}, found_gspec=#{found_gspec}" )
+      # instead of using Gem::Dependency, you can also do:
+      # Gem::Specification.find_all_by_name(gem_name, *gem_ver_reqs)
+
+      if found_gspec
+        @logger.debug( "#{__method__}, Requirement '#{gdep}' already satisfied by #{found_gspec.name}-#{found_gspec.version}" )
+        template_path = "#{found_gspec.gem_dir}/mustache"
+        @logger.debug( "#{__method__}, template_path=#{template_path}" )
+      else
+        #puts "Requirement '#{gdep}' not satisfied; installing..."
+        # ver_args = gdep.requirements_list.map{|s| ['-v', s] }.flatten
+        # # multi-arg is safer, to avoid injection attacks
+        # system('gem', 'install', gem_name, *ver_args)
+        raise "Could not find gem '#{gdep}' - try 'gem install #{gdep}'"
+      end
+      
+      return template_path
+
+    end
+    
+
+    # return path to 'template_file' in an existing 'directory'
+    def get_template_filepath_in_directory( directory, template_file ) 
+      @logger.debug( "#{__method__} directory=#{directory}, template_file=#{template_file}" )
+
+      if ! File.exists?( directory ) then
+        @logger.info( "#{__method__} skipping directory #{directory} - it does not exist" )
+        return nil
+      end
+
+      if ! File.exists?( directory ) then
+        raise <<-eos
+
+          No such directory '#{directory}'.
+        
+        eos
+
+      end
+
+      template_path = "#{directory}/#{template_file}"
+      @logger.info( "#{__method__} read template_path=#{template_path}" )
+      
+      return template_path
+
+    end
+
+  end # class
+
+end # module
+
+

data/lib/sbuilder/mustache/template_reader_context.rb

@@ -0,0 +1,371 @@
+require 'tla-parser-s'       # TLA+ parser && resolver
+
+module Sbuilder
+
+  
+  # ------------------------------------------------------------------
+  # Use setup configuration to filter out part of reander templates.
+  #
+  # Implementation overrides 'whitelist' method in 'TemplateReader'.
+  # Uses 'TlaParserS::Resolver' to parse TLA+ snippets, and resolve
+  # modules to put in whitelist'
+  #
+  # Overview:
+  #
+  # - configSetup -methods receives 'steps' ie. array of interface
+  #   names called in setup, and array of 'interfaces', which map
+  #   interfaces to interface implementations
+  #
+  # - TlaParserS::Resolver#initSnippets parses tla-sbuilder code
+  # - repository
+  #
+  # - TlaParserS::Resolver#entryPoints resolves modules required to
+  #   satisfy interface implementations used in setup
+
+  class TemplateContextReader < TemplateReader
+
+    extend Forwardable                  # for easy delegation
+    
+    def_delegators :controller,
+                   :getEntryPoints,     # [String:Array] of
+                                        # implemenation names
+                                        # extracted from 'configSetup'
+                   :getSetupPossibilities,
+                                        # [String:Array] names of
+                                        # possiblity operators defined
+                                        # for current setup
+    
+                   :isOptFilterSrc,     # [Boolean] true when
+                                        # filtering
+                   :output,             # (level,msg) to output
+                   :output_show,        # (level)[Boolean] if show
+                   :getModelNames       # [String:Array] of names in model
+
+    # ------------------------------------------------------------------
+    # constructore
+
+
+    include Sbuilder::Utils::MyLogger   # mix logger
+    PROGNAME = "creader"                # progname for logger
+
+    # TLA+ standard library symbols
+    GLOBALS = %w( TRUE FALSE Cardinality)
+
+    # Sbuilder constant symbols
+    SBUILDER = %w( Nil InfrastructureServiceReturn InfrastructureServiceGetStatus 
+    InfrastructureServiceGetResponse)
+
+    # these directories not unmustached
+    DOC_DIRS= [ "docs", "doc" ]
+    
+    # ------------------------------------------------------------------
+    # Attributes
+    attr_reader :options                # hash{:filter_list}
+
+    attr_reader :resolver               # [TlaParserS::Resolver] to
+                                        # resolve entry point modules
+
+
+    attr_reader :controller             # [Sbuilder::Controller] 
+
+
+    attr_reader :setupName              # currently generating
+    
+    # ------------------------------------------------------------------
+    # Constructor
+    
+    def initialize( controller, options={} )
+      super( controller, options )
+      @logger = getLogger( PROGNAME, options )
+      @logger.info( "#{__method__} created, options='#{options}" )
+
+      @controller = controller
+
+      @options = options
+
+
+      # # create '@resolver' && parse snippet repository
+      # if  isOptFilterSrc then
+      # end
+      
+    end
+
+    # ------------------------------------------------------------------
+    # Lazy intialize (so that configuration can take place)
+    def resolver
+      return @resolver if @resolver
+
+      raise "No option :cache_dir" unless options[:cache_dir] && !options[:cache_dir].empty?
+      unmustache_dir = "#{options[:cache_dir]}/unmustache"
+
+      # copy unmustached version for templates
+      unmustache( unmustache_dir )
+
+      # init resovelver using 'unmustache_dir'
+      @resolver = initResolver( unmustache_dir, options )
+      return @resolver
+    end
+
+    # ------------------------------------------------------------------
+    # Options
+
+
+    # @return [string] file path for filter list
+    def filter_list
+      options[:filter_list]
+    end
+
+
+    # ------------------------------------------------------------------
+    # config
+
+    def setSetupName( setupName )
+      @logger.info( "#{__method__} setupName=#{setupName}" )
+      @setupName = setupName
+    end
+    
+    # ------------------------------------------------------------------
+    #
+    # Try to find a reason to show template
+    # 
+    # @param [String] name of template to check @return [boolean] true
+    # when template should be shown normally, else false
+    #
+    # @return [Bool,String] show and text description
+    def show_template_do( name )
+
+      @logger.debug( "#{__method__}: check name=#{name}" )
+      
+      # show all 'mustache templates'
+      return true, "mustache-template" if /.+\.mustache$/ =~ name
+
+      # show template witout extesions
+      return true, "no extension" if /^[^\/\.]*$/ =~ name
+
+      # show template if name is in whitelist 'opts[:filter_list]'
+      # puts "#{whitelist.join(',')}: '#{name}'--> #{whitelist.include?(name)}"
+      return true, "in whitelist" if whitelist.include?( name.to_s  )
+
+      # (failed) there is no reason to show the template
+      return false, "default false"
+    end
+
+    # Overridden from super class. Wrapper around check actual check
+    # routine to simplify logging.
+    #
+    # @param [String] name of template to check
+    #
+    # @return [boolean] true when shown normally,else false
+    def show_template( name )
+      ret = show_template_do( name )
+      @logger.info( "#{__method__}: check show=#{name}-#{ret[1]} -> #{ret[0]}" )            
+      ret[0]
+    end
+
+    # ------------------------------------------------------------------
+    # whitelist
+
+    # Return whitelisted template names.
+    #
+    # Implementation reads, and caches lines, in a file pointed by
+    # options[:filter_list]
+    #
+    # @return [Array] of whitelistes template names
+    def whitelist_file
+      return [] unless filter_list
+      File.readlines( filter_list ).each {|l| l.chomp! } || []
+    end
+
+    # Add Globals, Sbuilder and model symbols to resolver
+    # 
+    #
+    def initResolverContext( resolver )
+
+      output( 1, " Initialize resolver context symbols" )
+
+      
+      output( 2, "   TLA+ symbols: #{GLOBALS.join( ',')}" )      
+      output( 1, "   #{GLOBALS.length} TLA+ symbols" )
+      resolver.initContext( GLOBALS )
+
+      output( 2, "   Sbuilder symbols: #{SBUILDER.join( ',')}" )            
+      output( 1, "   #{SBUILDER.length} SBuilder symbols" )
+      resolver.initContext( SBUILDER )
+
+      model_names = getModelNames
+      output( 2, "   Model symbols: #{model_names.join( ',')}" )            
+      output( 1, "   #{model_names.length} model symbols" )
+      resolver.initContext( model_names )
+
+      output( 1, " Initialize resolver context symbols - done" )      
+      
+    end
+
+    # Access controller to get information needed in un-mustache
+    # operation
+    def unmustache( unmustache_dir )
+      
+      if ! Dir.exists?( unmustache_dir )
+        `mkdir #{unmustache_dir}`
+        exit unless $?.success?
+      end
+      
+      unmustacheDo( controller.getCodeRepository, unmustache_dir, controller.getPreferencesData(setupName) )
+    end
+
+    # Unmustache files in 'src_dir' to 'target_dir'. Pass preferences
+    # json to mustache rendering
+    #
+    # @param src_dir [String] path source directory
+    # @param dest_dir [String] path destination directory    
+    
+    def unmustacheDo( src_dir, target_dir, preferences )
+      @logger.info( "#{__method__}, src_dir=#{src_dir}, target_dir=#{target_dir}, preferences=#{preferences}" )
+
+      output( 1, "Unmustache  #{src_dir} --> #{target_dir} - start" )
+
+      source_files = Dir::glob(  "#{src_dir}/**/*" )
+      source_files.each do |file|
+        
+        next if File.directory?( file )
+
+        # extract relatve path in respect to src_dir
+        source = Pathname.new( File.expand_path( file) )
+        source_root = Pathname.new( File.expand_path( src_dir )  )
+        src = source.relative_path_from( source_root )
+
+        # do not unmustache anythins under docs, doc directory
+        if DOC_DIRS.include?( File.dirname( src ).split(File::SEPARATOR).first )
+          output( 1, "   document file  #{src} not unmustached" )          
+          next
+        end
+
+        
+        target = "#{target_dir}/#{src}"
+        # puts "#{source} --> #{target}"
+        
+        if !File.exists?( File.dirname(target) )
+          cmd = "mkdir -p #{File.dirname(target)}"
+          output( 1, cmd )
+          `#{cmd}`
+          exit unless $?.success?
+        end # create dir
+
+        if !File.exists?(target) or (File.mtime( source ) > File.mtime(target))
+          cmd =  "echo '#{preferences.to_json}' | mustache - #{source} > #{target}"
+          output( 2, "   " + cmd )
+          `#{cmd}`
+          exit unless $?.success?
+        end # create file
+      end
+
+      output( 1, "Unmustache  #{src_dir} --> #{target_dir} - done" )
+
+      
+    end
+    
+    
+
+    # Create '@resolver' and initSnippets in 'snippet_repository'
+    #
+    # @param options [Hash] defining options for 'Resolver'
+    def initResolver( snippet_repository, options={} )
+      
+      
+      output( 1, "Parse snippet from repository #{snippet_repository} - start" )
+
+      cnt = 0
+      resolver = nil
+      Dir.chdir( snippet_repository ) do
+        
+        @logger.info( "#{__method__}: init snippets in snippet_repository=#{snippet_repository}" )
+        snippet_files = Dir.glob( "**/*").map { |fileName| File.new(fileName)}
+        resolver =  TlaParserS::Resolver.new( options )
+
+        # Add Globals, Sbuilder and model symbols to resolver
+        initResolverContext( resolver )
+
+        # Parse 'snippet_files' - 
+        resolver.initSnippets( snippet_files ) do |stat,entry,e|
+          
+          if stat
+            # success output dots no newline
+            output( 1, ".", false )
+            cnt += 1
+            true
+          else
+
+            # parses error
+            if filter_list
+              msg = <<-EOS
+
+              Parser error: option '--filter-list' set --> continue
+              #{e.message} 
+              EOS
+              @logger.error( msg )
+              warn msg
+              true
+            else
+              msg = <<-EOS
+              Parser error:  option '--filter-list' not set --> exiting
+              #{e.message} 
+              EOS
+              @logger.error( msg )
+              warn msg
+              false
+            end # if filter_list
+            
+          end # else - false: error
+        end # block
+        
+      end # chdir
+      
+      # start new line
+      output( 1, "" )
+      output( 1, "Parse snippet from repository #{snippet_repository} - done: parsed #{cnt} snippets" )
+
+      resolver
+    end
+    
+    # Call resolver#resolveModule to find out the whitelist modules.
+    # Implementation uses 'entry_points' configured in 'configSetup'
+    #
+    # @return [String:Array] of white listed modules
+    def whitelist_resolved
+      rslv = resolver
+      output( 1, "Resolving symbols - start" )
+      entrypoints = getEntryPoints + getSetupPossibilities
+      @logger.debug("#{__method__}: entrypoints=#{entrypoints}")
+      ret =  rslv.resolveModules( entrypoints  ) do |type,arr|
+        case type
+        when "unresolved"
+          # defult to output unresolved - if some unresolved symbols
+          output( arr.any? ? 1 : 2, " #{type} : [#{arr.join(',')}]" )
+          output( 1, " #{type} : count #{arr.length}" )          
+        else
+          output( 2, " #{type} : [#{arr.join(',')}]" )
+          output( 1, " #{type} : count #{arr.length} #{ !output_show( 2 ) ? '(add verbosity to show list)' : '' }" )
+        end
+      end
+      output( 1, "Resolving symbols - done" )
+      return ret
+    end
+    
+
+    # Return whitelisted template names.
+    #
+    #
+    # @return [Array] of whitelistes template names
+    
+    def whitelist
+      return @whitelist if @whitelist      
+      @whitelist = whitelist_file + whitelist_resolved
+      @logger.info( "#{__method__}, whitelist=#{@whitelist}" )
+      @whitelist
+    end
+
+    private
+
+
+  end
+end