asciidoctor-sail 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c02b2d48c65bd2e04e77fe09135f4ac55b41567e3ed6cfa8ca477ac650fe064
+  data.tar.gz: 5519b40e6be23cf4388d4ce15940f142ba3ee956f3027512ebd3d349d9a96816
+SHA512:
+  metadata.gz: 217a7edc3c5b47ef72261cc21330949ec8b368863ae18857cf18f038c72e6ddcea6e6f27ff50c9c79809a8680d898840e99509063994fca58a069c500c741819
+  data.tar.gz: 8a9f7db2589280023e8e219b2db0ede1f546aa530c80b8bf3c8bddbe18e383ae7a6416b2e73d9f421540d81bb3fe59ebccd39ec02325d4e3535b5c34a093366b

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Alasdair Armstrong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,7 @@
+= Sail Asciidoctor Plugin
+
+An https://asciidoctor.org[Asciidoctor] extension for including code from
+https://github.com/rems-project/sail[Sail] ISA specifications into
+Asciidoc documents, primarily aimed at supporting documentation for
+RISC-V extensions using the
+https://github.com/riscv/sail-riscv[sail-riscv] model.

data/lib/asciidoctor-sail/highlighter.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'rouge'
+
+# We define a rouge lexer for Sail source
+class SailLexer < Rouge::RegexLexer
+  title 'Sail'
+  desc 'Sail ISA Description Language (https://github.com/rems-project/sail)'
+  tag 'sail'
+  filenames '*.sail'
+
+  id = /[a-zA-Z_?][a-zA-Z0-9_?#]*/
+
+  tyvar = /'[a-zA-Z_?][a-zA-Z0-9_?#]*/
+
+  # We are careful with the definition of operators to ensure openers
+  # like // and /* cannot prefix valid operators
+  op_char = '[!%&*+-./:<=>@^|]'
+  op_char_no_slash = '[!%&*+-.:<=>@^|]'
+  op_char_no_slash_star = '[!%&+-.:<=>@^|]'
+
+  # Sail operators can be suffixed with an underscore followed by a
+  # regular identifier i.e. <=_u for unsigned less that or equal to
+  op_suffix = "#{op_char}*(_#{id.source})"
+
+  # Operators of length 1, 2, and n > 2
+  operator1 = Regexp.new(op_char)
+  operator2 = Regexp.new("(#{op_char}#{op_char_no_slash_star})|(#{op_char_no_slash}#{op_char})")
+  operatorn = Regexp.new("(#{op_char}#{op_char_no_slash_star}#{op_suffix})|(#{op_char_no_slash}#{op_char}#{op_suffix})")
+
+  def self.keywords
+    @keywords ||= Set.new %w[
+      and as by match clause operator default end enum else forall foreach function mapping overload throw
+      try catch if in let var ref pure monadic register return scattered struct then type union newtype with
+      val outcome instantiation impl repeat until while do bitfield forwards backwards to
+    ]
+  end
+
+  # Keywords that appear in types, and builtin special types
+  def self.keywords_type
+    @keywords_type ||= Set.new %w[
+      dec inc Int Order Bool Type bits bool int option unit implicit
+    ]
+  end
+
+  # These keywords appear like special functions rather than regular
+  # keywords, i.e. `assert(cond, "message")`
+  def self.builtins
+    @builtins ||= Set.new %w[
+      bitzero bitone exit false sizeof constraint true undefined
+    ]
+  end
+
+  # Reserved and internal keywords, as well as deprecated keywords
+  def self.reserved
+    @reserved ||= Set.new %w[
+      effect cast constant import module mutual configuration termination_measure internal_plet internal_return
+    ]
+  end
+
+  state :whitespace do
+    rule(/\s+/, Text::Whitespace)
+  end
+
+  state :root do
+    mixin :whitespace
+
+    rule(/0x[0-9A-Fa-f_]+/, Num::Hex)
+    rule(/0b[0-1_]+/, Num::Bin)
+    rule(/[0-9]+\.[0-9]+/, Num::Float)
+    rule(/[0-9_]+/, Num::Integer)
+
+    rule(/"/, Str, :string)
+
+    rule tyvar, Name::Variable
+
+    rule(/(val\b)(\s+)(#{id})/) do
+      groups Keyword, Text::Whitespace, Name::Function
+    end
+
+    rule(/(function\b)(\s+)(#{id})/) do
+      groups Keyword, Text::Whitespace, Name::Function
+    end
+
+    rule %r{//}, Comment, :line_comment
+    rule %r{/\*}, Comment, :comment
+    rule(/\$\[/, Comment::Preproc, :attribute)
+    rule(/\$#{id}/, Comment::Preproc, :pragma)
+
+    # Function arrows
+    rule(/->/, Punctuation)
+
+    # Two character brackets
+    rule(/\[\|/, Punctuation)
+    rule(/\|\]/, Punctuation)
+    rule(/{\|/, Punctuation)
+    rule(/\|}/, Punctuation)
+
+    rule(/[,@=(){}\[\];:]/, Punctuation)
+    rule operatorn, Operator
+    rule operator2, Operator
+    rule operator1, Operator
+
+    rule id do |m|
+      name = m[0]
+
+      if self.class.keywords.include? name
+        token Keyword
+      elsif self.class.keywords_type.include? name
+        token Keyword::Type
+      elsif self.class.builtins.include? name
+        token Name::Builtin
+      elsif self.class.reserved.include? name
+        token Keyword::Reserved
+      else
+        token Name
+      end
+    end
+  end
+
+  state :string do
+    rule(/"/, Str, :pop!)
+    # Sail escape sequences are a subset of OCaml's https://v2.ocaml.org/manual/lex.html#escape-sequence
+    rule(/\\([\\ntbr"']|x[a-fA-F0-9]{2}|[0-7]{3})/, Str::Escape)
+    rule(/[^\\"\n]+/, Str)
+  end
+
+  state :attribute do
+    rule(/\]/, Comment::Preproc, :pop!)
+    rule(/[^\]]+/, Comment::Preproc)
+  end
+
+  state :pragma do
+    rule(/\n/, Text::Whitespace, :pop!)
+    rule(/[^\n]+/, Comment::Preproc)
+  end
+
+  state :line_comment do
+    rule(/\n/, Text::Whitespace, :pop!)
+    rule(/[^\n]+/, Comment)
+  end
+
+  state :comment do
+    rule %r{/\*}, Comment, :comment
+    rule %r{\*/}, Comment, :pop!
+    rule(/\n/, Text::Whitespace)
+    rule(/./, Comment)
+  end
+end

data/lib/asciidoctor-sail/macros.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Sail
+    module SourceMacro
+      # Should match Docinfo.docinfo_version in Sail OCaml source
+      VERSION = 1
+      PLUGIN_NAME = 'Sail Asciidoc plugin'
+
+      def get_sourcemap(doc, attrs)
+        from = attrs.delete('from') { 'sail-doc' }
+        source_map = doc.attr(from)
+        ::Asciidoctor::Sail::Sources.register(from, source_map)
+        json = ::Asciidoctor::Sail::Sources.get(from)
+        if json['version'] != VERSION
+          raise "#{PLUGIN_NAME}: Version does not match version in source map #{source_map}"
+        end
+
+        json
+      end
+
+      def get_type(attrs)
+        attrs.delete('type') { 'function' }
+      end
+
+      def get_part(attrs)
+        attrs.delete('part') { 'source' }
+      end
+
+      def get_split(attrs)
+        attrs.delete('split') { '' }
+      end
+
+      def read_source(json, part)
+        source = ''
+        
+        if json.is_a? String
+          source = json
+        elsif json[part].is_a? String
+          source = json[part]
+        else
+          file = File.read(json['file'])
+          loc = json[part]['loc']
+
+          # Get the source code, adjusting for the indentation of the first line of the span
+          indent = loc[2] - loc[1]
+
+          source = file.byteslice(loc[2], loc[5] - loc[2])
+          source = (' ' * indent) + source
+        end
+
+        source
+      end
+
+      def get_sail_object(json, target, attrs)
+        type = get_type(attrs)
+        json = json["#{type}s"]
+        if json.nil?
+          raise "#{PLUGIN_NAME}: No Sail objects of type #{type}"
+        end
+        json = json[target]
+        if json.nil?
+          raise "#{PLUGIN_NAME}: No Sail #{type} #{target} could be found" 
+        end
+        json = json[type]
+
+        if attrs.key? 'clause'
+          clause = attrs.delete('clause')
+          json.each do |child|
+            if match_clause(clause, child['pattern'])
+              json = child
+              break
+            end
+          end
+        elsif attrs.key? 'left-clause'
+          clause = attrs.delete('left-clause')
+          json.each do |child|
+            if match_clause(clause, child['left'])
+              json = child
+              break
+            end
+          end
+        elsif attrs.key? 'right-clause'
+          clause = attrs.delete('right-clause')
+          json.each do |child|
+            if match_clause(clause, child['right'])
+              json = child
+              break
+            end
+          end
+        elsif attrs.key? 'grep'
+          grep = attrs.delete('grep')
+          json.each do |child|
+            source = read_source(child, 'body')
+            if source =~ Regexp.new(grep)
+              json = child
+            end
+          end
+        end
+
+        json
+      end
+
+      # Compute the minimum indentation for any line in a source block
+      def minindent(tabwidth, source)
+        indent = -1
+        source.each_line do |line|
+          line_indent = 0
+          line.chars.each do |c|
+            case c
+            when ' '
+              line_indent += 1
+            when "\t"
+              line_indent += tabwidth
+            else
+              break
+            end
+          end
+          indent = line_indent if indent == -1 || line_indent < indent
+        end
+        indent
+      end
+
+      def get_source(doc, target, attrs)
+        json = get_sourcemap doc, attrs
+        json = get_sail_object json, target, attrs
+        dedent = attrs.any? { |k, v| (k.is_a? Integer) && %w[dedent unindent].include?(v) }
+        strip = attrs.any? { |k, v| (k.is_a? Integer) && %w[trim strip].include?(v) }
+
+        part = get_part attrs
+        split = get_split attrs
+
+        source = ''
+        if split != ''
+          source = json['splits'][split]
+        else
+          source = read_source(json, part)
+        end
+          
+        source.strip! if strip
+
+        if dedent
+          lines = ''
+          min = minindent 4, source
+
+          source.each_line do |line|
+            lines += line[min..]
+          end
+          source = lines
+        end
+
+        source
+      end
+
+      def match_clause(desc, json)
+        if desc =~ /^([a-zA-Z_?][a-zA-Z0-9_?#]*)(\(.*\))$/
+          return false unless json['type'] == 'app' && json['id'] == ::Regexp.last_match(1)
+
+          patterns = json['patterns']
+          if patterns.length == 1
+            patterns = patterns[0]
+          end
+          
+          match_clause ::Regexp.last_match(2), patterns
+        elsif desc.length.positive? && desc[0] == '('
+          tuples = nil
+          if json.is_a? Array
+            tuples = json
+          elsif json['type'] == 'tuple'
+            tuples = json['patterns']
+          else
+            tuples = [json]
+          end
+
+          results = []
+          desc[1...-1].split(',').each_with_index do |desc, i|
+            results.push(match_clause(desc.strip, tuples[i]))
+          end
+          results.all?
+        elsif desc == '_'
+          true
+        elsif desc =~ /^([a-zA-Z_?][a-zA-Z0-9_?#]*)$/
+          json['type'] == 'id' && json['id'] == ::Regexp.last_match(1)
+        elsif desc =~ /^(0[bx][a-fA-F0-9]*)$/
+          json['type'] == 'literal' && json['value'] == ::Regexp.last_match(1)
+        else
+          false
+        end
+      end
+    end
+
+    class SourceBlockMacro < ::Asciidoctor::Extensions::BlockMacroProcessor
+      include SourceMacro
+
+      use_dsl
+
+      named :sail
+
+      def process(parent, target, attrs)
+        source = get_source parent.document, target, attrs
+
+        create_listing_block parent, source, { 'style' => 'source', 'language' => 'sail' }
+      end
+    end
+
+    class SourceIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include SourceMacro
+
+      def handles? target
+        target.start_with? 'sail:'
+      end
+
+      def process doc, reader, target, attrs
+        target.delete_prefix! 'sail:'
+
+        source = get_source doc, target, attrs
+
+        reader.push_include source, target, target, 1, {}
+        reader
+      end
+    end
+
+    class WavedromIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include SourceMacro
+
+      def handles? target
+        target.start_with? 'sailwavedrom:'
+      end
+
+      def process doc, reader, target, attrs
+        target.delete_prefix! 'sailwavedrom:'
+        json = get_sourcemap doc, attrs
+        json = get_sail_object json, target, attrs
+        
+        key = 'wavedrom'
+        if attrs.any? { |k, v| (k.is_a? Integer) && v == 'right' }
+          key = 'right_wavedrom'
+        elsif attrs.any? { |k, v| (k.is_a? Integer) && v == 'left' }
+          key = 'left_wavedrom'
+        end
+
+        if attrs.key? 'raw'
+          diagram = json[key]
+        else
+          diagram = "[wavedrom, , svg]\n....\n#{json[key]}\n...."
+        end
+          
+        reader.push_include diagram, target, target, 1, {}
+        reader
+      end
+    end
+
+    class DocCommentIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include SourceMacro
+      
+      def handles? target
+        target.start_with? 'sailcomment:'
+      end
+
+      def process doc, reader, target, attrs
+        target.delete_prefix! 'sailcomment:'
+        json = get_sourcemap doc, attrs
+        json = get_sail_object json, target, attrs
+
+        if json.nil? || json.is_a?(Array)
+          raise "#{PLUGIN_NAME}: Could not find Sail object for #{target} when processing include::sailcomment. You may need to specify a clause."
+        end
+
+        comment = json['comment']
+        if comment.nil?
+          raise "#{PLUGIN_NAME}: No documentation comment for Sail object #{target}"
+        end
+        
+        reader.push_include comment, target, target, 1, attrs
+        reader
+      end
+    end
+  end
+end

data/lib/asciidoctor-sail/sources.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Asciidoctor
+  module Sail
+    class Sources
+      @sources = {}
+
+      def self.register(key, sourcemap_path)
+        return if @sources.key?(key)
+
+        file = File.read(sourcemap_path)
+        @sources[key] = JSON.parse(file)
+      end
+
+      def self.get(key)
+        @sources[key]
+      end
+    end
+  end
+end

data/lib/asciidoctor-sail.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'asciidoctor/extensions'
+
+require_relative 'asciidoctor-sail/sources'
+require_relative 'asciidoctor-sail/macros'
+require_relative 'asciidoctor-sail/highlighter'
+
+Asciidoctor::Extensions.register do
+  block_macro Asciidoctor::Sail::SourceBlockMacro
+  include_processor Asciidoctor::Sail::SourceIncludeProcessor
+  include_processor Asciidoctor::Sail::DocCommentIncludeProcessor
+  include_processor Asciidoctor::Sail::WavedromIncludeProcessor
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-sail
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Alasdair Armstrong
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-03-26 00:00:00.000000000 Z
+dependencies: []
+description: Asciidoctor extension for documenting Sail models
+email:
+- alasdair.armstrong@cl.cam.ac.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.adoc
+- lib/asciidoctor-sail.rb
+- lib/asciidoctor-sail/highlighter.rb
+- lib/asciidoctor-sail/macros.rb
+- lib/asciidoctor-sail/sources.rb
+homepage: https://github.com/Alasdair/asciidoctor-sail
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.9
+signing_key:
+specification_version: 4
+summary: An Asciidoctor extension that supports including formatted Sail source in
+  ISA manuals
+test_files: []