asciidoctor-sail 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c02b2d48c65bd2e04e77fe09135f4ac55b41567e3ed6cfa8ca477ac650fe064
-  data.tar.gz: 5519b40e6be23cf4388d4ce15940f142ba3ee956f3027512ebd3d349d9a96816
+  metadata.gz: 64902e55e5a314105d5cf7b74686c7791c4ba72b0778f2048c51e3c0a32522f5
+  data.tar.gz: ec176896d3dab99ae5ceaa3fb64b88cf6dc2fadc004010edecb4e85e984c1846
 SHA512:
-  metadata.gz: 217a7edc3c5b47ef72261cc21330949ec8b368863ae18857cf18f038c72e6ddcea6e6f27ff50c9c79809a8680d898840e99509063994fca58a069c500c741819
-  data.tar.gz: 8a9f7db2589280023e8e219b2db0ede1f546aa530c80b8bf3c8bddbe18e383ae7a6416b2e73d9f421540d81bb3fe59ebccd39ec02325d4e3535b5c34a093366b
+  metadata.gz: 693ece551f08ebe8385f30b2e33dc7d2dc1d8dd6b3366a4da37d5f537b4ba15c4c37e3525ebf2929fee7f0785097628e40e9f779a1ec1268ff5f44e702a5610e
+  data.tar.gz: b403b703dbfb130a3938c50df22c3f344031007cda868784c7af3ab4ff60a03453c475e0ce127703b4e73c5bd0c0624d4ea7bc82c04a3a4133980be4cc4e4c6d

data/README.adoc

@@ -5,3 +5,24 @@ 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.
+
+== Installation
+
+asciidoctor-sail is published on https://rubygems.org[rubygems], so it can be installed with gem install:
+
+[source,sh]
+----
+gem install asciidoctor-sail
+----
+
+The requirements are simply asciidoctor itself, or asciidoctor and
+asciidoctor-diagram if encoding diagrams are generated (which also
+require the https://wavedrom.com[WaveDrom] editor to be installed).
+asciidoctor-pdf is also supported for PDF generation.
+
+== Documentation
+
+Documentation is available as a PDF
+https://github.com/Alasdair/asciidoctor-sail/blob/master/doc/built/sail_to_asciidoc.pdf[here]. The
+PDF is itself built with asciidoctor-pdf and asciidoctor-sail, using
+the various examples in `doc/examples`.

data/lib/asciidoctor-sail/highlighter.rb

@@ -32,7 +32,7 @@ class SailLexer < Rouge::RegexLexer
     @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
+      val outcome instantiation impl repeat until while do bitfield forwards backwards to from
     ]
   end
 
@@ -126,8 +126,9 @@ class SailLexer < Rouge::RegexLexer
   end
 
   state :attribute do
+    rule(/\[/, Comment::Preproc, :attribute)
     rule(/\]/, Comment::Preproc, :pop!)
-    rule(/[^\]]+/, Comment::Preproc)
+    rule(/[^\[\]]+/, Comment::Preproc)
   end
 
   state :pragma do

data/lib/asciidoctor-sail/macros.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Asciidoctor
   module Sail
     module SourceMacro
@@ -16,7 +18,7 @@ module Asciidoctor
           raise "#{PLUGIN_NAME}: Version does not match version in source map #{source_map}"
         end
 
-        json
+        return json, from
       end
 
       def get_type(attrs)
@@ -33,13 +35,19 @@ module Asciidoctor
 
       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'])
+          path = json['file']
+
+          if not File.exist?(path)
+            raise "#{PLUGIN_NAME}: File #{path} does not exist"
+          end
+
+          file = File.read(path)
           loc = json[part]['loc']
 
           # Get the source code, adjusting for the indentation of the first line of the span
@@ -98,7 +106,7 @@ module Asciidoctor
           end
         end
 
-        json
+        return json, type
       end
 
       # Compute the minimum indentation for any line in a source block
@@ -122,8 +130,8 @@ module Asciidoctor
       end
 
       def get_source(doc, target, attrs)
-        json = get_sourcemap doc, attrs
-        json = get_sail_object json, target, attrs
+        json, from = get_sourcemap doc, attrs
+        json, type = 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) }
 
@@ -136,7 +144,7 @@ module Asciidoctor
         else
           source = read_source(json, part)
         end
-          
+
         source.strip! if strip
 
         if dedent
@@ -149,7 +157,7 @@ module Asciidoctor
           source = lines
         end
 
-        source
+        return source, type, from
       end
 
       def match_clause(desc, json)
@@ -160,7 +168,7 @@ module Asciidoctor
           if patterns.length == 1
             patterns = patterns[0]
           end
-          
+
           match_clause ::Regexp.last_match(2), patterns
         elsif desc.length.positive? && desc[0] == '('
           tuples = nil
@@ -196,10 +204,25 @@ module Asciidoctor
 
       named :sail
 
+      @@ids = Set.new()
+
       def process(parent, target, attrs)
-        source = get_source parent.document, target, attrs
+        source, type, from = get_source parent.document, target, attrs
 
-        create_listing_block parent, source, { 'style' => 'source', 'language' => 'sail' }
+        if type == 'function' then
+          id = "#{from}-#{target}"
+        else
+          id = "#{from}-#{type}-#{target}"
+        end
+
+        if not @@ids.member?(id) then
+          @@ids.add(id)
+          block = create_listing_block parent, source, { 'id' => id, 'style' => 'source', 'language' => 'sail' }
+        else
+          block = create_listing_block parent, source, { 'style' => 'source', 'language' => 'sail' }
+        end
+
+        block
       end
     end
 
@@ -213,7 +236,7 @@ module Asciidoctor
       def process doc, reader, target, attrs
         target.delete_prefix! 'sail:'
 
-        source = get_source doc, target, attrs
+        source, type, from = get_source doc, target, attrs
 
         reader.push_include source, target, target, 1, {}
         reader
@@ -229,9 +252,9 @@ module Asciidoctor
 
       def process doc, reader, target, attrs
         target.delete_prefix! 'sailwavedrom:'
-        json = get_sourcemap doc, attrs
-        json = get_sail_object json, target, attrs
-        
+        json, from = get_sourcemap doc, attrs
+        json, type = get_sail_object json, target, attrs
+
         key = 'wavedrom'
         if attrs.any? { |k, v| (k.is_a? Integer) && v == 'right' }
           key = 'right_wavedrom'
@@ -239,12 +262,12 @@ module Asciidoctor
           key = 'left_wavedrom'
         end
 
-        if attrs.key? 'raw'
+        if attrs.any? { |k, v| (k.is_a? Integer) && v == 'raw' }
           diagram = json[key]
         else
-          diagram = "[wavedrom, , svg]\n....\n#{json[key]}\n...."
+          diagram = "[wavedrom, ,]\n....\n#{json[key]}\n...."
         end
-          
+
         reader.push_include diagram, target, target, 1, {}
         reader
       end
@@ -252,15 +275,15 @@ module Asciidoctor
 
     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
+        json, from = get_sourcemap doc, attrs
+        json, type = 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."
@@ -270,7 +293,7 @@ module Asciidoctor
         if comment.nil?
           raise "#{PLUGIN_NAME}: No documentation comment for Sail object #{target}"
         end
-        
+
         reader.push_include comment, target, target, 1, attrs
         reader
       end

data/lib/asciidoctor-sail/sources.rb

@@ -10,6 +10,10 @@ module Asciidoctor
       def self.register(key, sourcemap_path)
         return if @sources.key?(key)
 
+        if not File.exist?(sourcemap_path)
+          raise "Sail Asciidoc plugin: File #{sourcemap_path} does not exist"
+        end
+
         file = File.read(sourcemap_path)
         @sources[key] = JSON.parse(file)
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-sail
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - Alasdair Armstrong
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-26 00:00:00.000000000 Z
+date: 2023-04-11 00:00:00.000000000 Z
 dependencies: []
 description: Asciidoctor extension for documenting Sail models
 email: