Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Fenced Code Blocks #123

Closed
mattwynne opened this Issue · 16 comments

3 participants

@mattwynne
Owner

I'd like to add a new way of specifying DocStrings, borrowing the syntax from markdown's fenced code blocks:

Given a file named "no_cassette_error.rb" with:
```ruby
require 'vcr_cucumber_helpers'
include_http_adapter_for("<http_lib>")
```
When I run `ruby no_cassette_error.rb`

This would allow users to specify the type of content, instead of it being assumed as plain text, e.g. https://img.skitch.com/20110903-twa46gjwc4553cmepeqq8qq5md.jpg

The alternative is to add a special type of comment which Relish understands, but I think this would be a useful addition to Gherkin, to be able to add more semantics to the content of the scenario.

WDYT?

@aslakhellesoy

Any particular reason we couldn't just use the existing triple quotes?

Given a file named "no_cassette_error.rb" with:
  """ruby
  require 'vcr_cucumber_helpers'
  include_http_adapter_for("<http_lib>")
  """
When I run `ruby no_cassette_error.rb`

How would you like to access the "content type" of the DocString?

@ghnatiuk
Collaborator

Strictly as a formatting element?

@mattwynne
Owner

@aslakhellesoy, triple quotes would be fine, my thinking was that people using this would be familiar with using triple quotes on Github already, so keep it simple for them. I'd have thought it would be OK to support both, wouldn't it?

For access, I don't mind too much. I'd like it if it surfaced in the JSON formatter output, and otherwise I can't remember what the interfaces would be. There's a DocString class isn't there, so can it be a new attribute on that?

@mattwynne
Owner

@ghnatiuk my use case is to use it for formatting, but I guess there might be other uses too.

@aslakhellesoy

It shouldn't be too hard to make triple backticks an alias for triple double-quotes. Allowing a "meta" argument to be attached to the DocString should be fairly easy too.

Keep in mind that DocString is a purely an internal representation in Gherkin. It is never passed to formatters or stepdefs. A String is passed instead.

This is why I was wondering how you (as a programmer) would expect to access the information. The only way I can think of right now is to define an #doc_type instance method on the string that we pass down. -Or did you have something else in mind?

@mattwynne
Owner
@ghnatiuk
Collaborator

https://github.com/ghnatiuk/gherkin/tree/content_types_for_doc_strings
ghnatiuk@6b6a1fa

Here's a start. C and Ruby lexers, in any case, as I don't have the tests running for Java/JS. The method signature for the doc_string event changes, so Cucumber's builder/ast would have to be updated to accept the additional arg.

Triple backticks wouldn't be too hard, though it's just a bit more than just aliasing things since we'd probably want to escape content inside it differently. I'd prefer sticking with """, rather than trying to deal with mismatched start/end, nested doc_strings, etc...

@aslakhellesoy aslakhellesoy referenced this issue from a commit
@aslakhellesoy aslakhellesoy And here is the Java and JavaScript for #123. Needs a little work on …
…the Cucumber side to get features passing on JRuby.
5cdbac6
@aslakhellesoy

Fixed in 2.4.18!

@mattwynne
Owner

Awesome! Thanks guys.

@aslakhellesoy

Now we should change Cucumber::Ast::DocString to take the content_type as well.

Can any of you see any potential problems with doing something like this in it?

def to_step_definition_arg
  def @string.content_type
    @content_type
  end
  @string.instance_variable_set('@content_type', @content_type)
  @string
end

This would allow formatters and hooks to access the content type. (But the metaclass of the string would change, which might break peple's stuff in weird places).

@mattwynne
Owner
@aslakhellesoy

That works too:

  • Cucumber::Ast::DocString < String
  • Cucumber::Ast::DocString takes a Gherkin::Formatter::Model::DocString in the ctor
  • Cucumber::Ast::DocString#to_step_definition_arg returns self

Any chance you could make this change Matt?

@mattwynne
Owner
@mattwynne
Owner

That's all done now. One thing that puzzled me when I implemented it on the Cucumber side was where the word 'plaintext' was coming from in the JSON formatter. The actual DocString#content_type seems to contain an empty string for regular docstrings. I had to duplicate that decision here:

https://github.com/cucumber/cucumber/blob/master/lib/cucumber/ast/multiline_argument.rb#L17

So I hope I made the right choice.

I'm curious though (as I grepped the code and couldn't find it). Where does the 'plaintext' come from?

@ghnatiuk
Collaborator

Consumed here: https://github.com/cucumber/gherkin/blob/master/features/json_formatter.feature#L56
Emitted here: https://github.com/cucumber/gherkin/blob/master/features/json_formatter.feature#L184

Does that answer your question? I think it makes sense to assume content type is blank if we're only getting a string rather than an actual DocString.

@mattwynne
Owner
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.