Asciidoctor :: Discussion

Including Files from Git Repository

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

8 messages Options

devunwired

Including Files from Git Repository

Hello All -

In Asciidoc Python, we made heavy use of the sys::[] macro to include code files from a local Git repository. We did this because is was an easy way to include different versions of the file (from different branches, etc.) without requiring some way to check out the different versions simultaneously. Something like:

[source,java]
----
sys::[git --git-dir=code/MyProject/.git show origin/project-start:app/src/main/java/MyClass.java]
----

[source,java]
----
sys::[git --git-dir=code/MyProject/.git show origin/project-solution:app/src/main/java/MyClass.java]
----

I have discovered that the sys::[] macro is disabled in Asciidoctor, so my question is this: How can we achieve the same output in the Asciidoctor paradigm?

mojavelinux

Re: Including Files from Git Repository

Administrator

On Thu, Feb 18, 2016 at 11:38 AM, devunwired [via Asciidoctor :: Discussion] <[hidden email]> wrote:

How can we achieve the same output in the Asciidoctor paradigm?

That's where the block macro comes in. The reason we dropped sys was two-fold. First and foremost, security. But second, because it was super limiting what you could implement. With a custom block macro, you can make the block macro do anything that Ruby can do.

Here's an example (which uses the tree command)

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/tree-block-macro/extension.rb

-Dan

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

mojavelinux

Re: Including Files from Git Repository

Administrator

In reply to this post by devunwired

On Thu, Feb 18, 2016 at 12:09 PM, Dan Allen <[hidden email]> wrote:

That's where the block macro comes in.

A custom block macro, that is.

-Dan

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

devunwired

Re: Including Files from Git Repository

Okay, so just to be clear I have to write my own extension to do this. Nothing exists already?

Is there some doc on how to write one? I see the usage examples in the extensions-lab, so I think I have an idea of how to invoke it. However, I'm not so certain on the API required to build one.

mojavelinux

Re: Including Files from Git Repository

Administrator

I have to write my own extension to do this. Nothing exists already?

That is correct.

Is there some doc on how to write one? I see the usage examples in the extensions-lab, so I think I have an idea of how to invoke it. However, I'm not so certain on the API required to build one.

There's some documentation in the user manual. I've promised to write an extension writer's guide, but I'm just haven't been able to dedicate time to it yet.

* http://asciidoctor.org/docs/user-manual/#extensions

* https://github.com/asciidoctor/asciidoctor.org/issues/347

If you get stuck, just e-mail the list with some draft code and I'm sure we can help you through it in the meantime.

Cheers,

-Dan

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

devunwired

Re: Including Files from Git Repository

Okay, so if I want to make the following happen:

[source,java]
----
gitlocal::app/src/main/java/MyClass.java["repodir","branch"]
----

…this is what I have so far to execute the shell command, but how do I dump the output of that command into the block?

require 'asciidoctor'
require 'asciidoctor/extensions'

class GitInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
use_dsl

named :gitlocal
name_positional_attributes 'repodir'
name_positional_attributes 'branch'

def process parent, target, attrs
# Exec git show command
cmd = %(git --git-dir=#{attrs['repodir']} show #{branch}:#{target})
result = %x(#{cmd})

# WHAT DO I DO HERE??
end
end

devunwired

Re: Including Files from Git Repository

Never mind, I figured out how to do it with an IncludeProcessor:

require 'asciidoctor'
require 'asciidoctor/extensions'

class GitIncludeMacro < Asciidoctor::Extensions::IncludeProcessor
use_dsl

def handles? target
(target.start_with? 'git@')
end

def process doc, reader, target, attributes
# Trim off the prefix
target.slice! "git@"
#Check attributes
repodir = attributes['repodir']
if repodir == nil
repodir = '.'
end
branch = attributes['branch']
if branch == nil
branch = 'master'
end

# Exec git show command
cmd = %(git --git-dir=#{repodir}/.git show #{}:#{target})
content = %x(#{cmd})

reader.push_include content, target, target, 1, attributes
reader
end
end

Will process the input:

[source,java]
----
include::git@app/src/main/java/MyClass.java[repodir="repodir", branch="branch"]
----

mojavelinux

Re: Including Files from Git Repository

Administrator

In reply to this post by devunwired

The return value of a block macro is an AST node. There are a few convenience methods for making a node (e.g., create_paragraph), though you can go low-level and use create_block.

Since you want to use the block macro inside a literal block, then I agree it make more sense to use an IncludeProcessor. Another approach is to replace the whole listing block with a block macro like:

gitsource::app/src/main/java/MyClass.java["repodir","branch"]

Then you would create a listing block in the process method and return it. That's similar to this line:

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/tree-block-macro/extension.rb#L41

-Dan

On Thu, Feb 18, 2016 at 2:07 PM, devunwired [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Okay, so if I want to make the following happen:

[source,java]
----
gitlocal::app/src/main/java/MyClass.java["repodir","branch"]
----

…this is what I have so far to execute the shell command, but how do I dump the output of that command into the block?

require 'asciidoctor'
require 'asciidoctor/extensions'

class GitInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
use_dsl

named :gitlocal
name_positional_attributes 'repodir'
name_positional_attributes 'branch'

def process parent, target, attrs
# Exec git show command
cmd = %(git --git-dir=#{attrs['repodir']} show #{branch}:#{target})
result = %x(#{cmd})

# WHAT DO I DO HERE??
end
end

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Including-Files-from-Git-Repository-tp4342p4351.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen