asciidoctor-diagram 1.0.1-java → 1.1.0-java

Sign up to get free protection for your applications and to get access to all the features.
Files changed (38) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +22 -0
  3. data/README.adoc +7 -6
  4. data/examples/Gemfile +3 -0
  5. data/examples/README.adoc +6 -0
  6. data/examples/build_example.rb +9 -0
  7. data/examples/design.adoc +78 -0
  8. data/examples/features.adoc +164 -0
  9. data/lib/asciidoctor-diagram.rb +1 -0
  10. data/lib/asciidoctor-diagram/ditaa.rb +1 -0
  11. data/lib/asciidoctor-diagram/ditaa/extension.rb +23 -50
  12. data/lib/asciidoctor-diagram/ditaa/generator.rb +31 -0
  13. data/lib/asciidoctor-diagram/graphviz.rb +8 -0
  14. data/lib/asciidoctor-diagram/graphviz/extension.rb +41 -0
  15. data/lib/asciidoctor-diagram/plantuml.rb +1 -0
  16. data/lib/asciidoctor-diagram/plantuml/extension.rb +33 -71
  17. data/lib/asciidoctor-diagram/plantuml/generator.rb +50 -0
  18. data/lib/asciidoctor-diagram/{binaryio.rb → util/binaryio.rb} +0 -0
  19. data/lib/asciidoctor-diagram/util/diagram.rb +198 -0
  20. data/lib/asciidoctor-diagram/{java.rb → util/java.rb} +0 -0
  21. data/lib/asciidoctor-diagram/{java_jruby.rb → util/java_jruby.rb} +0 -0
  22. data/lib/asciidoctor-diagram/{java_rjb.rb → util/java_rjb.rb} +0 -0
  23. data/lib/asciidoctor-diagram/{png.rb → util/png.rb} +0 -0
  24. data/lib/asciidoctor-diagram/util/svg.rb +46 -0
  25. data/lib/asciidoctor-diagram/version.rb +1 -1
  26. data/spec/ditaa_spec.rb +65 -0
  27. data/spec/graphviz_spec.rb +134 -0
  28. data/spec/plantuml_spec.rb +38 -0
  29. data/spec/test_helper.rb +1 -0
  30. metadata +32 -26
  31. data/.gitignore +0 -19
  32. data/.travis.yml +0 -10
  33. data/Gemfile +0 -4
  34. data/asciidoctor-diagram.gemspec +0 -30
  35. data/ditaamini-license.txt +0 -165
  36. data/lib/asciidoctor-diagram/diagram.rb +0 -111
  37. data/lib/asciidoctor-diagram/svg.rb +0 -18
  38. data/plantuml-license.txt +0 -202
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 3f744fe34b44f3eac8a72f5c54ba81f4d0fca756
4
- data.tar.gz: 410fa9e1683434a389503f90bfc251fff713bb7a
3
+ metadata.gz: 2da1c4f87abccf3e4453355c5b3a525b983777d6
4
+ data.tar.gz: 68d55cdeaf3c3cd604f05d4a01dae3493eed442a
5
5
  SHA512:
6
- metadata.gz: 4ad7018fb8ee56d873eb041ba9511c5866668912183837061bfd9336ec88ab74536459ef90667f82e4fcccea447b250f725b3896890c57205a7b5596bef55ffc
7
- data.tar.gz: e8b358410c6107145a70edd1e819595a46283fa6d177a8534ec65946ce1476217bd49894a169bd56d8967ae1227b2731cf84164fc64bf0467f7020a3a2c35006
6
+ metadata.gz: b88d5b7892b6ff4a8a8111a5c88839af4f89601c187c2ae798993680ded5c6ae4dc3e1c56c2bd72f6a24e92d67bcbda75a1b50736a1303a8f1cd8b1792eb76b6
7
+ data.tar.gz: 8dd9dc235bd58831981752976f04f86e902372efd90afc6b8ce5ff815d9c31711587860b9e2498677b8b8490aa0cf2371a8d97c29d745ec60c287a6915a4ce03
data/CHANGELOG.adoc ADDED
@@ -0,0 +1,22 @@
1
+ = Asciidoctor-diagram Changelog
2
+
3
+ == 1.1.0
4
+
5
+ Enhancements::
6
+
7
+ * Add support for `graphviz` blocks which may contain diagrams specified using the Graphviz DOT language
8
+ * The location of the Graphviz `dot` executable can now be specified using the `graphvizdot` document attribute
9
+ * Add support for `ditaa`, `graphivz` and `plantuml` block macros
10
+
11
+ == 1.0.1
12
+
13
+ Bug Fixes::
14
+
15
+ * Corrections to gemspec
16
+
17
+ == 1.0.0
18
+
19
+ Initial release::
20
+
21
+ * Provides Asciidoctor extension for `ditaa` and `plantuml` blocks
22
+ * PlantUML skin parameters can be injected from an external file using the `plantumlconfig` document attribute
data/README.adoc CHANGED
@@ -33,17 +33,18 @@ In your script you can then either require one or more of the following files:
33
33
 
34
34
  . `asciidoctor-diagram`: to enable all the diagramming extensions
35
35
  . `asciidoctor-diagram/ditaa`: to enable the ditaa extension
36
+ . `asciidoctor-diagram/graphviz`: to enable the graphviz extension
36
37
  . `asciidoctor-diagram/plantuml`: to enable the plantuml extension
37
38
 
38
- Requiring one or more of these files will automatically register the extensions for all processed documents. If you need
39
- more fine grained control over when the extensions are enabled or not, `asciidoctor-diagram/ditaa/extension` and `asciidoctor-diagram/plantuml/extension` can be used instead.
40
- This loads the extensions themselves but does not register them.
39
+ Requiring one or more of these files will automatically register the extensions for all processed documents.
40
+ If you need more fine grained control over when the extensions are enabled or not, `asciidoctor-diagram/ditaa/extension`, `asciidoctor-diagram/graphviz/extension` and `asciidoctor-diagram/plantuml/extension` can be used instead.
41
+ These load the extensions themselves but do not register them.
41
42
  You should then register the extensions yourself at the appropriate time using the `Asciidoctor::Extensions` API.
42
43
 
43
44
  === Using the extensions
44
45
 
45
- Once the extensions are enabled support for `plantuml` and/or `ditaa` blocks becomes available for your documents.
46
- Detailed descriptions of the supported syntax inside these blocks is available on the http://plantuml.sourceforge.net/[PlantUML] and http://ditaa.sourceforge.net/[ditaa] websites.
46
+ Once the extensions are enabled support for `ditaa`, `graphviz` and `plantuml` blocks becomes available for your documents.
47
+ Detailed descriptions of the supported syntax inside these blocks is available on the http://plantuml.sourceforge.net/[PlantUML], http://www.graphviz.org/content/dot-language[Graphviz] and http://ditaa.sourceforge.net/[ditaa] websites.
47
48
 
48
49
  At this point you can start adding diagrams to your application, like the following example:
49
50
 
@@ -64,7 +65,7 @@ DiagramBlock <|-- PlantUmlBlock
64
65
  The diagram blocks support the following attributes:
65
66
 
66
67
  . `target` (or 2nd position): the basename of the file to generate. If not specified an auto-generated name will be used.
67
- . `format` (or 3rd position): the output format. PlantUML blocks support `png`, `svg` and `txt`. Ditaa only supports `png`.
68
+ . `format` (or 3rd position): the output format. PlantUML blocks support `png`, `svg` and `txt`. Graphviz supports `png` and `svg`. Ditaa only supports `png`.
68
69
 
69
70
  == Contributing
70
71
 
data/examples/Gemfile ADDED
@@ -0,0 +1,3 @@
1
+ source 'https://rubygems.org'
2
+
3
+ gem "asciidoctor-diagram", :path => ".."
@@ -0,0 +1,6 @@
1
+ = Asciidoctor-diagram Examples
2
+
3
+ This directory contains a number of example files that illustrate how to use the asciidoctor-diagram extension.
4
+ Asciidoctor 0.1.4 does not support loading extensions via the command line.
5
+ In order to process the examples correctly you should use the `build-example.rb` script.
6
+ This wraps the regular `asciidoctor` command line tool and automatically loads the asciidoctor-diagram extension.
@@ -0,0 +1,9 @@
1
+ require 'rubygems'
2
+ require 'bundler/setup'
3
+
4
+ require 'asciidoctor'
5
+ require 'asciidoctor/cli/options'
6
+ require 'asciidoctor/cli/invoker'
7
+ require 'asciidoctor-diagram'
8
+
9
+ Asciidoctor::Cli::Invoker.new(*ARGV).invoke!
@@ -0,0 +1,78 @@
1
+ = The design of Asciidoctor-diagram
2
+
3
+ This document explains the design of Asciidoctor-diagram using PlantUML syntax.
4
+ A detailed explanation of the PlantUML syntax is out scope for this document.
5
+ This can be found on the http://www.plantuml.com[PlantUML web site].
6
+
7
+ Asciidoctor-diagram is a simple Asciidoctor extension that enables embedding of diagrams inside asciidoc documents using various plain text diagram syntaxes.
8
+ The current version of Asciidoctor-diagram support the Ditaa, Graphviz DOT and PlantUML syntax.
9
+
10
+ Asciidoctor-diagram enables a number of new block types using the Asciidoctor `BlockProcessor` extension API.
11
+
12
+ The main logic of the diagram generation is provided by the `DiagramBlock` module.
13
+ This includes the shared options for the various blocks, checksum calculation of the diagram source code, cache validation and attribute generation for the generated output blocks.
14
+ The DiagramBlock module also provides a means to register diagram output formats.
15
+
16
+ When registering an output format, the registering code must specify a number of control parameters.
17
+ The first parameter is the format name which controls when the generator is activated.
18
+ The generator that is registered first determines the default format for the block.
19
+ The second parameter is the output type of the generator.
20
+ This is either `:image` or `:literal`.
21
+ This parameter controls what type of block the `DiagramBlock` code will generate.
22
+ Finally, a block should be provided that generates the diagram and returns it as a String.
23
+ When called these blocks will receive the diagram source code and the parent Block as arguments.
24
+
25
+ The actual `BlockProcessor` implementations include the `DiagramBlock` module and the appropriate generator module.
26
+ The remainder of the implementation consists of registering format.
27
+
28
+ The diagram below illustrates the relationship between the various classes and modules.
29
+
30
+ .Asciidoctor-diagram class diagram
31
+ [plantuml, "classes", align="center"]
32
+ ----
33
+ namespace asciidoctor.extensions {
34
+ class BlockProcessor
35
+ }
36
+
37
+ namespace asciidoctor.diagram {
38
+ asciidoctor.extensions.BlockProcessor <|-- DitaaBlock
39
+ class DitaaGenerator << (M,#FF7700) >>
40
+
41
+ asciidoctor.extensions.BlockProcessor <|-- GraphvizBlock
42
+ asciidoctor.extensions.BlockProcessor <|-- PlantUmlBlock
43
+ class PlantUmlGenerator << (M,#FF7700) >>
44
+
45
+ class DiagramBlock << (M,#FF7700) >>
46
+
47
+ DitaaBlock --|> DitaaGenerator
48
+ DitaaBlock --|> DiagramBlock
49
+ GraphvizBlock --|> PlantUmlGenerator
50
+ GraphvizBlock --|> DiagramBlock
51
+ PlantUmlBlock --|> PlantUmlGenerator
52
+ PlantUmlBlock --|> DiagramBlock
53
+ }
54
+ ----
55
+
56
+ When Asciidoctor process a document it will invoke the block processors at the appropriate moment.
57
+ The sequence of method calls for a Ditaa block is shown below.
58
+
59
+ .Processing a Ditaa block
60
+ [plantuml, "processing", align="center"]
61
+ ----
62
+ Lexer->DiagramBlock : process
63
+ activate DiagramBlock #FFBBBB
64
+
65
+ DiagramBlock -> DiagramBlock: create_image_block
66
+ activate DiagramBlock #DarkSalmon
67
+
68
+ DiagramBlock -> DiagramBlock: code_checksum
69
+
70
+ DiagramBlock -> DitaaGenerator: ditaa
71
+ activate DitaaGenerator
72
+ DiagramBlock <-- DitaaGenerator: image as String
73
+ deactivate DitaaGenerator
74
+ deactivate DiagramBlock
75
+
76
+ Lexer <-- DiagramBlock: generated Block
77
+ deactivate DiagramBlock
78
+ ----
@@ -0,0 +1,164 @@
1
+ = Asciidoctor-diagram features
2
+
3
+ This document explains the various features of asciidoctor-diagram blocks using ditaa diagrams as an example.
4
+
5
+ == Simple diagrams
6
+
7
+ To mark a block as a diagram the appropriate style should be applied. This can be either `ditaa`, `graphviz` or `plantuml`.
8
+ These styles can be applied to literal, listing or open blocks.
9
+
10
+ A basic ditaa listing can be written as follows:
11
+
12
+ ---------
13
+ [ditaa]
14
+ ----
15
+ +-------------+
16
+ | asciidoctor |-------+
17
+ | diagram | |
18
+ +-------------+ | png out
19
+ ^ |
20
+ | ditaa in |
21
+ | v
22
+ +--------+ +--------+----+ /---------------\
23
+ | | --+ asciidoctor +--> | |
24
+ | Text | +-------------+ |Beatiful output|
25
+ |Document| | !magic! | | |
26
+ | {d}| | | | |
27
+ +---+----+ +-------------+ \---------------/
28
+ : ^
29
+ | Lots of work |
30
+ +-----------------------------------+
31
+ ----
32
+ ---------
33
+
34
+ results in the following image.
35
+
36
+ [ditaa]
37
+ ----
38
+ +-------------+
39
+ | asciidoctor |-------+
40
+ | diagram | |
41
+ +-------------+ | png out
42
+ ^ |
43
+ | ditaa in |
44
+ | v
45
+ +--------+ +--------+----+ /---------------\
46
+ | | --+ asciidoctor +--> | |
47
+ | Text | +-------------+ |Beatiful output|
48
+ |Document| | !magic! | | |
49
+ | {d}| | | | |
50
+ +---+----+ +-------------+ \---------------/
51
+ : ^
52
+ | Lots of work |
53
+ +-----------------------------------+
54
+ ----
55
+
56
+ == Controlling the file name
57
+
58
+ The image above gets the file name `58372f7d2ceffae9e91fd0a7cbb080b6.png`.
59
+ That long number is the checksum of the source code that was calculated by asciidoctor-diagram.
60
+ If you want to give your generated files a more meaningful name, simply fill in the `target` attribute.
61
+
62
+ This can be done by either specifying it as the first positional attribute or as a named attribute.
63
+ Both examples below would result in a file called `ditaa-diagram.png`.
64
+
65
+ ---------
66
+ [ditaa, "ditaa-diagram"]
67
+ ----
68
+ <snip>
69
+ ----
70
+
71
+ [ditaa, target="ditaa-diagram"]
72
+ ----
73
+ <snip>
74
+ ----
75
+ ---------
76
+
77
+ == Choosing an output format
78
+
79
+ By default images are generated in `PNG` format.
80
+ This can be overridden by defining the `format` (or 2nd positional) attribute.
81
+ The set of supported formats is diagram type dependent.
82
+ `ditaa` only supports the `png` format.
83
+ `graphviz` supports `png` and `svg`.
84
+ `plantuml` supports `png`, `svg` and `txt`.
85
+
86
+ The `txt` format is perhaps a bit non-obvious.
87
+ This generates an ascii art version of the UML diagrams.
88
+
89
+ The following Graphviz DOT script
90
+
91
+ ---------
92
+ [graphviz, "dot_example", "svg"]
93
+ ----
94
+ graph ethane {
95
+ C_0 -- H_0 [type=s];
96
+ C_0 -- H_1 [type=s];
97
+ C_0 -- H_2 [type=s];
98
+ C_0 -- C_1 [type=s];
99
+ C_1 -- H_3 [type=s];
100
+ C_1 -- H_4 [type=s];
101
+ C_1 -- H_5 [type=s];
102
+ }
103
+ ----
104
+ ---------
105
+
106
+ generates an SVG representation of an ethane molecule footnote:[From http://en.wikipedia.org/wiki/DOT_(graph_description_language)#A_simple_example]
107
+
108
+ [graphviz, "dot_example", "svg"]
109
+ ----
110
+ graph ethane {
111
+ C_0 -- H_0 [type=s];
112
+ C_0 -- H_1 [type=s];
113
+ C_0 -- H_2 [type=s];
114
+ C_0 -- C_1 [type=s];
115
+ C_1 -- H_3 [type=s];
116
+ C_1 -- H_4 [type=s];
117
+ C_1 -- H_5 [type=s];
118
+ }
119
+ ----
120
+
121
+ == Using standard asciidoc features
122
+
123
+ Any remaining other attributes that are specified on a diagram block are copied over to the generated block.
124
+ This means you can use the regular http://asciidoctor.org/docs/user-manual/#put-images-in-their-place[asciidoc positioning attributes] to place the diagrams where you want to.
125
+
126
+ Block titles and block ids can also be applied in the same way to diagram blocks.
127
+
128
+ As an example, the following block
129
+
130
+ --------
131
+ [[plan]]
132
+ .My plan to conquer the world
133
+ [plantuml, align="center"]
134
+ --------
135
+
136
+ results in a block with the correct caption and id applied to it.
137
+
138
+ [[plan]]
139
+ .My plan to conquer the world
140
+ [plantuml, "activity_diagram", "svg", align="center"]
141
+ ----
142
+ (*) --> "Create an Asciidoctor extension"
143
+ "Create an Asciidoctor extension" --> " ? "
144
+ " ? " --> "Profits!"
145
+ "Profits!" --> (*)
146
+ ----
147
+
148
+ == Loading diagrams from external files
149
+
150
+ Asciidoctor-diagram also supports the various diagram block in block macro form.
151
+ These are macros of the form `<name>::<target>[<attrlist>]`.
152
+
153
+ In asciidoctor-diagram the macro names are identical to the block styles: `ditaa`, `graphivz` and `plantuml`
154
+ The target is the path to the file containing the diagram source code.
155
+ When the target is a relative path it is resolved with respect to the location of the document being processed.
156
+ The attribute list behaves mostly the same as with the block styles.
157
+ The only difference is that the `target` attribute is not supported.
158
+ Instead the name of the generated image is derived from the target propery of the macro.
159
+
160
+ The previous example in block macro form would look something like this with the text from the block located in a file called `activity_diagram.txt` instead of inline in the document.
161
+
162
+ ----
163
+ plantuml:activity_diagram.txt[format="svg", align="center"]
164
+ ----
@@ -1,2 +1,3 @@
1
1
  require 'asciidoctor-diagram/ditaa'
2
+ require 'asciidoctor-diagram/graphviz'
2
3
  require 'asciidoctor-diagram/plantuml'
@@ -4,4 +4,5 @@ require_relative 'version'
4
4
  Asciidoctor::Extensions.register do
5
5
  require_relative 'ditaa/extension'
6
6
  block :ditaa, Asciidoctor::Diagram::DitaaBlock
7
+ block_macro :ditaa, Asciidoctor::Diagram::DitaaBlockMacro
7
8
  end
@@ -1,64 +1,37 @@
1
- require_relative '../diagram'
2
- require_relative '../java'
3
- require_relative '../png'
4
- require_relative '../svg'
1
+ require_relative '../util/diagram'
2
+ require_relative 'generator'
5
3
 
6
4
  module Asciidoctor
7
5
  module Diagram
8
- DITAA_JAR_PATH = File.expand_path File.join('../..', 'ditaamini0_9.jar'), File.dirname(__FILE__)
9
-
10
- class DitaaBlock < DiagramBlock
11
- option :contexts, [:listing, :literal, :open]
12
- option :content_model, :simple
13
- option :pos_attrs, ['target', 'format']
14
- option :default_attrs, {'format' => 'png'}
15
-
16
- def name
17
- "Ditaa"
18
- end
19
-
20
- def allowed_formats
21
- @allowed_formats ||= [:png]
22
- end
23
-
24
- def generate_image(parent, diagram_code, format)
25
- ditaa(diagram_code)
26
- end
6
+ module DitaaBase
7
+ include DitaaGenerator
27
8
 
28
9
  private
29
10
 
30
- Java.classpath << DITAA_JAR_PATH
31
-
32
- def ditaa(code, *flags)
33
- Java.load
34
-
35
- cmd = ['-e', 'UTF-8']
36
- cmd += flags if flags
37
-
38
- bytes = code.encode(Encoding::UTF_8).bytes.to_a
39
- bis = Java.java.io.ByteArrayInputStream.new(Java.array_to_java_array(bytes, :byte))
40
- bos = Java.java.io.ByteArrayOutputStream.new
41
- result_code = Java.org.stathissideris.ascii2image.core.CommandLineConverter.convert(Java.array_to_java_array(cmd, :string), bis, bos)
42
- bis.close
43
- bos.close
44
-
45
- result = Java.string_from_java_bytes(bos.toByteArray)
11
+ def register_formats
12
+ register_format(:png, :image) do |c|
13
+ ditaa(c)
14
+ end
15
+ end
16
+ end
46
17
 
47
- raise "Ditaa image generation failed: #{result}" unless result_code == 0
18
+ class DitaaBlock < Asciidoctor::Extensions::BlockProcessor
19
+ include DiagramProcessorBase
20
+ include DitaaBase
48
21
 
49
- result
22
+ def initialize(context, document, opts = {})
23
+ super
24
+ register_formats()
50
25
  end
26
+ end
51
27
 
52
- def get_default_flags(parent)
53
- flags = []
54
-
55
- document = parent.document
56
- config = document.attributes['plantumlconfig']
57
- if config
58
- flags += ['-config', File.expand_path(config, document.attributes['docdir'])]
59
- end
28
+ class DitaaBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
29
+ include DiagramProcessorBase
30
+ include DitaaBase
60
31
 
61
- flags
32
+ def initialize(context, document, opts = {})
33
+ super
34
+ register_formats()
62
35
  end
63
36
  end
64
37
  end
@@ -0,0 +1,31 @@
1
+ require_relative '../util/java'
2
+
3
+ module Asciidoctor
4
+ module Diagram
5
+ module DitaaGenerator
6
+ private
7
+
8
+ DITAA_JAR_PATH = File.expand_path File.join('../..', 'ditaamini0_9.jar'), File.dirname(__FILE__)
9
+ Java.classpath << DITAA_JAR_PATH
10
+
11
+ def ditaa(code)
12
+ Java.load
13
+
14
+ args = ['-e', 'UTF-8']
15
+
16
+ bytes = code.encode(Encoding::UTF_8).bytes.to_a
17
+ bis = Java.java.io.ByteArrayInputStream.new(Java.array_to_java_array(bytes, :byte))
18
+ bos = Java.java.io.ByteArrayOutputStream.new
19
+ result_code = Java.org.stathissideris.ascii2image.core.CommandLineConverter.convert(Java.array_to_java_array(args, :string), bis, bos)
20
+ bis.close
21
+ bos.close
22
+
23
+ result = Java.string_from_java_bytes(bos.toByteArray)
24
+
25
+ raise "Ditaa image generation failed: #{result}" unless result_code == 0
26
+
27
+ result
28
+ end
29
+ end
30
+ end
31
+ end