I have some Ruby code that looks like this:
# some_string = "{really?}"
where the curly braces need to be part of the string. This line is commented out code that I'd like to remain there. I'm additionally using YARD to document code, so when I run yard doc it (naturally) throws a warning about being unable to link "really".
Is there a way I can tell YARD to ignore commented out code?
Is there a way I can tell YARD to ignore commented out code?
On the one hand, YARD is documented as supporting Rdoc markup. And Rdoc is documented to support a couple of ways to hide parts.
RDoc stops processing comments if it finds a comment line starting
with -- right after the # character (otherwise, it will be treated as
a rule if it has three dashes or more). This can be used to separate
external from internal comments, or to stop a comment being associated
with a method, class, or module. Commenting can be turned back on with
a line that starts with ++.
:stopdoc: / :startdoc:
Stop and start adding new documentation elements to the current
container. For example, if a class has a number of constants that you
don’t want to document, put a :stopdoc: before the first, and a
:startdoc: after the last. If you don’t specify a :startdoc: by the end
of the container, disables documentation for the rest of the current
file.
Source
On the other hand, I have never persuaded Rdoc or YARD to follow that markup. If your luck is better than mine, you can stop reading here.
If you, too, can't persuade YARD to follow that markup, I think your best bet might be to cut that line, and commit the file with a distinctive commit message--one that you'll be able to find easily by grepping the source control logs.
Finally, rake lets you transform text (code) files in arbitrary ways. You can write a Rakefile to delete lines before processing them through YARD.
$ cat silly-ruby-file.src
class Something
def this_method
end
def that_method
# some_string = "{really?}" # Hide me
end
end
I appended the text # Hide me; it's a lot easier to filter that specific text than it is to filter commented lines of arbitrary code.
$ cat Rakefile
task :default => "silly-ruby-file.rb"
sh "grep -v '# Hide me' silly-ruby-file.src > silly-ruby-file.rb"
This tells rake to run grep, copying all lines except those that have the text "# Hide me" to stdout, which is redirected to "silly-ruby-file.rb".
Related
I am trying to make the output of my CLI Ruby gem my_command --help cleaner.
There is some CLI options and flags that need a couple of sentences to explain them. I don't have found a way to properly align this text in their column when the explanation is too long to fit inside a regular terminal width view.
I want to have something like this:
ab --help as an example, note how some flags have a multiple line explanations with a proper alignment.
Right now, I am doing something like this in OptionParser to keep text aligned in their column in case we need multiple lines to explain something:
opts.on("-d", "--directory PATH", String, "Directory to save the downloaded files into\n\t\t\t\t Default is ./websites/ plus the domain name") do |t|
options[:directory] = t
end
It's working, but it doesn't seem optimal nor clean to have \t everywhere to force formatting. Plus, I can see cases where it's not being formatted correctly in other terminal configurations.
How can I align horizontally a multiline CLI help text with OptionParser in a clean way?
You can force line breaks without needing to add tabs by adding more parameters to opts.on:
opts.on("-d", "--directory PATH", String,
"Directory to save the downloaded files into",
"Default is ./websites/ plus the domain name") do |t|
options[:directory] = t
end
This isn't very clearly documented in official documentation, but you can see it used in the complete example.
So, to comment in ruby, you need the # symbol.
# this is some comments
Which is fine, but for multi-line comments, ruby has an ugly system.
=begin
comment line 1
comment line 2
=end
I have search around the internet and found nothing on the topic. I want to see if I am able to change that format to something better by defining my own commenting system. Such as:
/*
comment line 1
comment line 2
*/
I want to see if I can do something like
def /*
define comment logic
end
def */
define comment logic
end
Just something to that effect. I don't need to replace to current one, just want to see how I can define my own. I'm not looking to rewrite ruby. I just want to see if there is something simple that i can do whenever I write ruby. As an example, if I want to add a method to the String class, I can do
class String
def new_method
# some new functionality.
end
end
I want to see if I can do something like that for comments.
Nobody uses multi-line syntax. People do this instead:
# comment line 1
# comment line 2
Most editors have a shortcut that allows one to comment in multiple lines easily. You will get used to it!
A comment says "Ruby stops here, what follows is outside of Ruby". Therefore, it should be pretty obvious, that you cannot change what a comment is from inside Ruby.
But there's another problem with your proposed syntax: it is already valid Ruby. It's a multi-line Regexp literal. (Yes, it is semantically invalid, but it is a syntactically valid Regexp literal.)
I would like to highlight the arguments of a Ruby function in Sublime, when they are used inside the function. Like so:
def my_func(arg1, arg2 = nil)
puts arg1 # should be highlighted
puts arg2 # should be highlighted
end
I've been messing with Sublime's plist syntax highlighting format for a while (same as Textmate's), but having trouble figuring out how to capture one group (the args in the def line) and use them to match more expressions in another group (the whole method)
I have seen \1 and \2 being used in EndCapture groups before, which gives me hope that this is possible, for example by using \1 in a match group. But I just can't seem to get it to work. Anybody have any ideas?
(too long for comment)
If writing regexes in XML/PLIST is driving you batty, try installing the PackageDev plugin via Package Control. There is an option to convert PLIST .tmLanguage syntax files to YAML, and when you're done editing you can convert it back to PLIST. This way, you don't have to mess around with trying to get all the <dict><array><whatever> tags correct in the .tmLanguage file, and you can focus on the regexes, capturing groups, etc. It also uses the Oniguruma syntax, which I assume you're at least somewhat familiar with if you're a Rubyist. I maintain an improved syntax for Python, and my work has been so much easier since I started using the .YAML-tmlanguage format.
Good luck!
I have a ruby script that’ll do some text parsing (à lá markdown). It does it in a sequence of steps, like
string = string.gsub # more code here
string = string.gsub # more code here
# and so on
what is the best (i.e. most reliable) way to feed text into string in the first place? It’s a script, and the text it’ll be fed can vary a lot — it can be multilingual, have some characters that might trip a shell (like ", ', ’, &, $ you get the idea), and will likely be multi-line.
Is there some trick on the lines of
cat << EOF
bunch of text here
EOF
Additional considerations
I’m not looking for a markdown parser, this is something I want to do, not something I want a tool for.
I’m not a big ruby user (I’m starting to use it), so the more detailed the answer you can provide, the better.
It must be completely scriptable (i.e., no interrupting to ask the user for information).
The Kernel#gets method will read a string separated using the record separator from stdin or files specified on the command line. So if you use that you can do things like:
yourscript <filename #read from filename
yourscript file1 file2 # read both file1 and file2
yourscript #lets you type at your script
So to run something like:
cat <<'eof' |ruby yourscript.rb
This' & will $all 'eof' be 'fine'''
eof
Script might contain something like:
s = gets() # read a line
lines = readlines() # read all lines into an array
That's fairly standard for command-line scripts. If you want to have a user-interface then you'll want something more complex. There is an option to the Ruby interpreter to set the encoding of files as they are read.
Just read from stdin (which is an IO object):
$stdin.read
As you can see, stdin is provided in the global variable $stdin. Since it’s an IO object, there are a lot of other methods available if read doesn’t suit your needs.
Here’s a simple one-line example in the shell:
$ echo "foo\nbar" | ruby -e 'puts $stdin.read.upcase'
FOO
BAR
Obviously reading from stdin is extremely flexible since you can pipe input in from anywhere.
Ruby is very adept at encodings (see eg. Encoding docs). To get text into Ruby, one typically uses either gets, or reads File objects, or uses a GUI, which one can build with gtk2 gem or rugui (if already finished). In case you are getting texts from the wild internet, security should be your concern. Ruby used to have 4 $SAFE levels, but after some discussions, now there might be only 3 of them left. In any case, the best strategy to handle strings is to know as much as possible about the properties of the string that you expect in advance. Handling absolutely arbitrary strings is a surprisingly difficult task. Try to limit the number of possible encodings and figure the maximum size for the string that you expect.
Also, with respect to your original stated goal writing a markdown-processor-like something, you might want to not reinvent the wheel (unless it is for didactic purposes). There is this SO post:
Better ruby markdown interpreter?
The answer will direct you to kramdown gem, which gets a lot of praise, though I have not tried it personally.
I'm using Ruby 1.9.3 and REXML to parse an XML document, make a few changes (additions/subtractions), then re-output the file. Within this file is a block that looks like this:
<someElement>
some.namespace.something1=somevalue1
some.namespace.something2=somevalue2
some.namespace.something3=somevalue3
</someElement>
The problem is that after re-writing the file, this block always ends up looking like this:
<someElement>
some.namespace.something1=somevalue1
some.namespace.something2=somevalue2 some.namespace.something3=somevalue3
</someElement>
The newline after the second value (but never the first!) has been lost and turned into a space. Later, some other code which I have no control or influence over will be reading this file and depending on those newlines to properly parse the content. Generally in this situation i'd use a CDATA to preserve the whitespace, but this isn't an option as the code that parses this data later is not expecting one - it's essential that the inner text of this element is preserved exactly as-is.
My read/write code looks like this:
xmlFile = File.open(myFile)
contents = xmlFile.read
xmlDoc = REXML::Document.new(contents, { :respect_whitespace => :all })
xmlFile.close
{perform some tasks}
out = ""
xmlDoc.write(out, 2)
File.open(filePath, "w"){|file| file.puts(out)}
I'm looking for a way to preserve the whitespace of text between elements when reading/writing a file in this manner using REXML. I've read a number of other questions here on stackoverflow on this subject, but none that quite replicate this scenario. Any ideas or suggestions are welcome.
I get correct behavior by removing the indent (second) parameter to Document.write():
#xmlDoc.write(out, 2)
xmlDoc.write(out)
That seems like a bug in Document.write() according to my reading of the docs, but if you don't really need to set the indentation, then leaving that off should solve yor problem.