<%= erb(:breadcrumb) %>
<%= erb(:search) %>
<%= yieldall %>
<%= erb(:footer) %>
Alphabetic Index
<%= yieldall %>Method: <%= object.path %>
- Defined in:
-
<%= object.file %><% if object.files.size > 1 %>,
<%= object.files[1..-1].map {|f| f.first }.join(",
") %>
<%= yieldall :index => 0 %>
<%= link_file item %>
';
$('#content').prepend(html);
$('#toc').append(_toc);
$('#toc .hide_toc').toggle(function() {
$('#toc .top').slideUp('fast');
$('#toc').toggleClass('hidden');
$('#toc .title small').toggle();
}, function() {
$('#toc .top').slideDown('fast');
$('#toc').toggleClass('hidden');
$('#toc .title small').toggle();
});
}
function navResizeFn(e) {
if (e.which !== 1) {
navResizeFnStop();
return;
}
sessionStorage.navWidth = e.pageX.toString();
$('.nav_wrap').css('width', e.pageX);
$('.nav_wrap').css('-ms-flex', 'inherit');
}
function navResizeFnStop() {
$(window).unbind('mousemove', navResizeFn);
window.removeEventListener('message', navMessageFn, false);
}
function navMessageFn(e) {
if (e.data.action === 'mousemove') navResizeFn(e.data.event);
if (e.data.action === 'mouseup') navResizeFnStop();
}
function navResizer() {
$('#resizer').mousedown(function(e) {
e.preventDefault();
$(window).mousemove(navResizeFn);
window.addEventListener('message', navMessageFn, false);
});
$(window).mouseup(navResizeFnStop);
if (sessionStorage.navWidth) {
navResizeFn({which: 1, pageX: parseInt(sessionStorage.navWidth, 10)});
}
}
function navExpander() {
var done = false, timer = setTimeout(postMessage, 500);
function postMessage() {
if (done) return;
clearTimeout(timer);
var opts = { action: 'expand', path: pathId };
document.getElementById('nav').contentWindow.postMessage(opts, '*');
done = true;
}
window.addEventListener('message', function(event) {
if (event.data === 'navReady') postMessage();
return false;
}, false);
}
function mainFocus() {
$('#main')[0].focus();
}
$(document).ready(function() {
navResizer();
navExpander();
createSourceLinks();
createDefineLinks();
createFullTreeLinks();
searchFrameButtons();
linkSummaries();
summaryToggle();
generateTOC();
mainFocus();
});
})();
yard-0.9.7/templates/default/fulldoc/html/js/full_list.js 0000644 0000041 0000041 00000013162 13035234564 023513 0 ustar www-data www-data (function() {
var $clicked = $(null);
var searchTimeout = null;
var searchCache = [];
var caseSensitiveMatch = false;
var ignoreKeyCodeMin = 8;
var ignoreKeyCodeMax = 46;
var commandKey = 91;
RegExp.escape = function(text) {
return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
}
function escapeShortcut() {
$(document).keydown(function(evt) {
if (evt.which == 27) {
window.parent.postMessage('navEscape', '*');
}
});
}
function navResizer() {
$(window).mousemove(function(e) {
window.parent.postMessage({
action: 'mousemove', event: {pageX: e.pageX, which: e.which}
}, '*');
}).mouseup(function(e) {
window.parent.postMessage({action: 'mouseup'}, '*');
});
window.parent.postMessage("navReady", "*");
}
function clearSearchTimeout() {
clearTimeout(searchTimeout);
searchTimeout = null;
}
function enableLinks() {
// load the target page in the parent window
$('#full_list li').on('click', function(evt) {
$('#full_list li').removeClass('clicked');
$clicked = $(this);
$clicked.addClass('clicked');
evt.stopPropagation();
if (evt.target.tagName === 'A') return true;
var elem = $clicked.find('> .item .object_link a')[0];
var e = evt.originalEvent;
var newEvent = new MouseEvent(evt.originalEvent.type);
newEvent.initMouseEvent(e.type, e.canBubble, e.cancelable, e.view, e.detail, e.screenX, e.screenY, e.clientX, e.clientY, e.ctrlKey, e.altKey, e.shiftKey, e.metaKey, e.button, e.relatedTarget);
elem.dispatchEvent(newEvent);
evt.preventDefault();
return false;
});
}
function enableToggles() {
// show/hide nested classes on toggle click
$('#full_list a.toggle').on('click', function(evt) {
evt.stopPropagation();
evt.preventDefault();
$(this).parent().parent().toggleClass('collapsed');
highlight();
});
}
function populateSearchCache() {
$('#full_list li .item').each(function() {
var $node = $(this);
var $link = $node.find('.object_link a');
if ($link.length > 0) {
searchCache.push({
node: $node,
link: $link,
name: $link.text(),
fullName: $link.attr('title').split(' ')[0]
});
}
});
}
function enableSearch() {
$('#search input').keyup(function(event) {
if (ignoredKeyPress(event)) return;
if (this.value === "") {
clearSearch();
} else {
performSearch(this.value);
}
});
$('#full_list').after("");
}
function ignoredKeyPress(event) {
if (
(event.keyCode > ignoreKeyCodeMin && event.keyCode < ignoreKeyCodeMax) ||
(event.keyCode == commandKey)
) {
return true;
} else {
return false;
}
}
function clearSearch() {
clearSearchTimeout();
$('#full_list .found').removeClass('found').each(function() {
var $link = $(this).find('.object_link a');
$link.text($link.text());
});
$('#full_list, #content').removeClass('insearch');
$clicked.parents().removeClass('collapsed');
highlight();
}
function performSearch(searchString) {
clearSearchTimeout();
$('#full_list, #content').addClass('insearch');
$('#noresults').text('').hide();
partialSearch(searchString, 0);
}
function partialSearch(searchString, offset) {
var lastRowClass = '';
var i = null;
for (i = offset; i < Math.min(offset + 50, searchCache.length); i++) {
var item = searchCache[i];
var searchName = (searchString.indexOf('::') != -1 ? item.fullName : item.name);
var matchString = buildMatchString(searchString);
var matchRegexp = new RegExp(matchString, caseSensitiveMatch ? "" : "i");
if (searchName.match(matchRegexp) == null) {
item.node.removeClass('found');
item.link.text(item.link.text());
}
else {
item.node.addClass('found');
item.node.removeClass(lastRowClass).addClass(lastRowClass == 'r1' ? 'r2' : 'r1');
lastRowClass = item.node.hasClass('r1') ? 'r1' : 'r2';
item.link.html(item.name.replace(matchRegexp, "$&"));
}
}
if(i == searchCache.length) {
searchDone();
} else {
searchTimeout = setTimeout(function() {
partialSearch(searchString, i);
}, 0);
}
}
function searchDone() {
searchTimeout = null;
highlight();
if ($('#full_list li:visible').size() === 0) {
$('#noresults').text('No results were found.').hide().fadeIn();
} else {
$('#noresults').text('').hide();
}
$('#content').removeClass('insearch');
}
function buildMatchString(searchString, event) {
caseSensitiveMatch = searchString.match(/[A-Z]/) != null;
var regexSearchString = RegExp.escape(searchString);
if (caseSensitiveMatch) {
regexSearchString += "|" +
$.map(searchString.split(''), function(e) { return RegExp.escape(e); }).
join('.+?');
}
return regexSearchString;
}
function highlight() {
$('#full_list li:visible').each(function(n) {
$(this).removeClass('even odd').addClass(n % 2 == 0 ? 'odd' : 'even');
});
}
/**
* Expands the tree to the target element and its immediate
* children.
*/
function expandTo(path) {
var $target = $(document.getElementById('object_' + path));
$target.addClass('clicked');
$target.removeClass('collapsed');
$target.parentsUntil('#full_list', 'li').removeClass('collapsed');
if($target[0]) {
window.scrollTo(window.scrollX, $target.offset().top - 250);
highlight();
}
}
function windowEvents(event) {
var msg = event.data;
if (msg.action === "expand") {
expandTo(msg.path);
}
return false;
}
window.addEventListener("message", windowEvents, false);
$(document).ready(function() {
escapeShortcut();
navResizer();
enableLinks();
enableToggles();
populateSearchCache();
enableSearch();
});
})();
yard-0.9.7/templates/default/fulldoc/html/js/jquery.js 0000644 0000041 0000041 00000267254 13035234564 023052 0 ustar www-data www-data /*! jQuery v1.7.1 jquery.com | jquery.org/license */
(function(a,b){function cy(a){return f.isWindow(a)?a:a.nodeType===9?a.defaultView||a.parentWindow:!1}function cv(a){if(!ck[a]){var b=c.body,d=f("<"+a+">").appendTo(b),e=d.css("display");d.remove();if(e==="none"||e===""){cl||(cl=c.createElement("iframe"),cl.frameBorder=cl.width=cl.height=0),b.appendChild(cl);if(!cm||!cl.createElement)cm=(cl.contentWindow||cl.contentDocument).document,cm.write((c.compatMode==="CSS1Compat"?"":"")+""),cm.close();d=cm.createElement(a),cm.body.appendChild(d),e=f.css(d,"display"),b.removeChild(cl)}ck[a]=e}return ck[a]}function cu(a,b){var c={};f.each(cq.concat.apply([],cq.slice(0,b)),function(){c[this]=a});return c}function ct(){cr=b}function cs(){setTimeout(ct,0);return cr=f.now()}function cj(){try{return new a.ActiveXObject("Microsoft.XMLHTTP")}catch(b){}}function ci(){try{return new a.XMLHttpRequest}catch(b){}}function cc(a,c){a.dataFilter&&(c=a.dataFilter(c,a.dataType));var d=a.dataTypes,e={},g,h,i=d.length,j,k=d[0],l,m,n,o,p;for(g=1;g
"+"
| t |
","
"]),f.fn.extend({text:function(a){if(f.isFunction(a))return this.each(function(b){var c=f(this);c.text(a.call(this,b,c.text()))});if(typeof a!="object"&&a!==b)return this.empty().append((this[0]&&this[0].ownerDocument||c).createTextNode(a));return f.text(this)},wrapAll:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapAll(a.call(this,b))});if(this[0]){var b=f(a,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&b.insertBefore(this[0]),b.map(function(){var a=this;while(a.firstChild&&a.firstChild.nodeType===1)a=a.firstChild;return a}).append(this)}return this},wrapInner:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapInner(a.call(this,b))});return this.each(function(){var b=f(this),c=b.contents();c.length?c.wrapAll(a):b.append(a)})},wrap:function(a){var b=f.isFunction(a);return this.each(function(c){f(this).wrapAll(b?a.call(this,c):a)})},unwrap:function(){return this.parent().each(function(){f.nodeName(this,"body")||f(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this)});if(arguments.length){var a=f.clean(arguments);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this.nextSibling)});if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,f.clean(arguments));return a}},remove:function(a,b){for(var c=0,d;(d=this[c])!=null;c++)if(!a||f.filter(a,[d]).length)!b&&d.nodeType===1&&(f.cleanData(d.getElementsByTagName("*")),f.cleanData([d])),d.parentNode&&d.parentNode.removeChild(d);return this},empty:function()
{for(var a=0,b;(b=this[a])!=null;a++){b.nodeType===1&&f.cleanData(b.getElementsByTagName("*"));while(b.firstChild)b.removeChild(b.firstChild)}return this},clone:function(a,b){a=a==null?!1:a,b=b==null?a:b;return this.map(function(){return f.clone(this,a,b)})},html:function(a){if(a===b)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(W,""):null;if(typeof a=="string"&&!ba.test(a)&&(f.support.leadingWhitespace||!X.test(a))&&!bg[(Z.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Y,"<$1>");try{for(var c=0,d=this.length;c
3 |
# File '(stdin)', line 3
def foo; end
|
#xyz Originally defined in module Foo
Docs for xyz
Method: #m
- Defined in:
- (stdin)
#m(x) ⇒ String (private) Also known as: x
Deprecated.
Comments
for great justice
9 |
# File '(stdin)', line 9
def m(x) end
|
Module: A
- Defined in:
- (stdin)
Foo collapse
-
#foo_attr
Returns the value of attribute foo_attr.
Foo collapse
Bar collapse
Class Method Summary collapse
Instance Attribute Details
#foo_attr
Returns the value of attribute foo_attr
3 4 5 |
# File '(stdin)', line 3
def foo_attr
@foo_attr
end
|
Class Method Details
.bar
5 |
# File '(stdin)', line 5
def self.bar; end
|
.baz
12 |
# File '(stdin)', line 12
def self.baz; end
|
Instance Method Details
#baz
8 |
# File '(stdin)', line 8
def baz; end
|
#foo
4 |
# File '(stdin)', line 4
def foo; end
|
Class: A Abstract
- Inherits:
-
B
- Object
- B
- A
- Defined in:
- (stdin)
Overview
This class is abstract.
Comments
override this class
Direct Known Subclasses
C
Instance Method Summary collapse
- #a deprecated Deprecated.
-
#initialize(test) ⇒ A
constructor
constructor method!.
-
#method_missing(*args)
HI.
Constructor Details
#initialize(test) ⇒ A
constructor method!
15 |
# File '(stdin)', line 15
def initialize(test) end
|
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(*args)
HI
10 |
# File '(stdin)', line 10
def method_missing(*args) end
|
Instance Method Details
#a
Deprecated.
12 |
# File '(stdin)', line 12
def a; end
|
Module: A
- Includes:
- B
- Defined in:
- (stdin)
Constant Summary
- FOO =
2
Instance Attribute Summary collapse
-
#bar
readonly
Returns the value of attribute bar.
Instance Method Summary collapse
Instance Attribute Details
#bar (readonly)
Returns the value of attribute bar
11 12 13 |
# File '(stdin)', line 11
def bar
@bar
end
|
Instance Method Details
#foo
10 |
# File '(stdin)', line 10
def foo; end
|
Module: A
- Includes:
- B, BaseMod
- Included in:
- TMP, TMP2
- Defined in:
- (stdin)
Overview
Comments
Defined Under Namespace
Modules: Z Classes: Q, X, Y
Constant Summary
- CONSTANT =
A long docstring for the constant. With extra text and newlines.
'value'
- @@cvar =
Deprecated.
'value'
Instance Attribute Summary collapse
-
#attr1
Returns the value of attribute attr1.
-
#attr2
readonly
Returns the value of attribute attr2.
- #attr3
-
#attr4
writeonly
Sets the attribute attr4.
Attributes included from BaseMod
#base_attr1, #base_attr2, #base_attr3
Class Method Summary collapse
Instance Method Summary collapse
- #a (also: #b)
- #test_multi_overload(*args)
-
#test_overload(a)
hello2.
- #void_meth
Methods included from B
#c, #d
Instance Attribute Details
#attr1
Returns the value of attribute attr1
17 18 19 |
# File '(stdin)', line 17
def attr1
@attr1
end
|
#attr2 (readonly)
Returns the value of attribute attr2
18 19 20 |
# File '(stdin)', line 18
def attr2
@attr2
end
|
#attr3 ⇒ String #attr3=(value)
25 26 27 |
# File '(stdin)', line 25
def attr3
@attr3
end
|
#attr4=(value) (writeonly)
Sets the attribute attr4
27 28 29 |
# File '(stdin)', line 27
def attr4=(value)
@attr4 = value
end
|
Class Method Details
.a
29 |
# File '(stdin)', line 29
def self.a; end
|
Instance Method Details
#a Also known as: b
30 |
# File '(stdin)', line 30
def a; end
|
#test_multi_overload(a) #test_multi_overload(a, b)
40 |
# File '(stdin)', line 40
def test_multi_overload(*args) end
|
#test_overload(a)
36 |
# File '(stdin)', line 36
def test_overload(*args) end
|
#void_meth
This method returns an undefined value.
43 |
# File '(stdin)', line 43
def void_meth; end
|
Method: #m
- Defined in:
- (stdin)
#m(a) ⇒ void #m(b)
5 |
# File '(stdin)', line 5
def m(*args) end
|
Method: #m
- Defined in:
- (stdin)
#m(*args) ⇒ void
This method returns an undefined value.
2 |
# File '(stdin)', line 2
def m(*args) end
|
Method: #m
- Defined in:
- (stdin)
#m(x, y) (private)
Comments
6 |
# File '(stdin)', line 6
def m(x) end
|
Method: #m
- Defined in:
- (stdin)
#m(x, y, *args, kword1: 123, kword2:)
5 |
# File '(stdin)', line 5
def m(x, y, *args, kword1: 123, kword2:, **) end
|
Class: D
- Inherits:
-
Object
- Object
- D
- Defined in:
- (stdin)
Method: #m
- Defined in:
- (stdin)
#m(x, y) (private) #m(x, y, z) (private)
Method comments
11 |
# File '(stdin)', line 11
def m(*args) end
|
+')).to eq 'Hello <code>
'
end
end
describe "#fix_typewriter" do
def fix_typewriter(text)
YARD::Templates::Helpers::Markup::RDocMarkup.new('').send(:fix_typewriter, text)
end
it "converts +text+ to text" do
expect(fix_typewriter("Some +typewriter text <+.")).to eq "Some typewriter text <."
expect(fix_typewriter("Not +typewriter text.")).to eq "Not +typewriter text."
expect(fix_typewriter("Alternating +type writer+ text +here+.")).to eq "Alternating type writer text here."
expect(fix_typewriter("No ++problem.")).to eq "No ++problem."
expect(fix_typewriter("Math + stuff +is ok+")).to eq "Math + stuff is ok"
expect(fix_typewriter("Hello +{Foo}+ World")).to eq "Hello {Foo} World"
end
it "does not apply to code blocks" do
expect(fix_typewriter("Hello +hello+")).to eq "Hello +hello+"
end
it "does not apply to HTML tag attributes" do
expect(fix_typewriter("A+b+c")).to eq "A+b+c"
expect(fix_typewriter("+foo+
")).to eq "foo
"
end
end
end
yard-0.9.7/spec/templates/helpers/module_helper_spec.rb 0000644 0000041 0000041 00000001763 13035234564 023307 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Templates::Helpers::ModuleHelper do
include YARD::Templates::Helpers::BaseHelper
include YARD::Templates::Helpers::ModuleHelper
describe "#prune_method_listing" do
before { YARD::Registry.clear }
let(:options) { OpenStruct.new }
let(:object) { YARD::Registry.at("Foo#bar") }
let(:objects) { [object] }
it "filters aliases" do
YARD.parse_string "class Foo; def orig; end; alias bar orig end"
expect(prune_method_listing(objects)).to eq []
end
it "filters attributes" do
YARD.parse_string "class Foo; attr_accessor :bar end"
expect(prune_method_listing(objects)).to eq []
end
it "ignores methods if namespace object is filtered" do
YARD.parse_string <<-eof
# @author test
class Foo
def bar; end
end
eof
options.verifier = YARD::Verifier.new('@author.text != "test"')
expect(prune_method_listing(objects)).to eq []
end
end
end
yard-0.9.7/spec/templates/helpers/shared_signature_examples.rb 0000644 0000041 0000041 00000007231 13035234564 024672 0 ustar www-data www-data # frozen_string_literal: true
RSpec.shared_examples_for "signature" do
before do
YARD::Registry.clear
@options = Templates::TemplateOptions.new
@options.reset_defaults
allow(self).to receive(:options).and_return(@options)
end
def trim(sig) sig.gsub(/\s+/, ' ') end
it "shows signature for regular instance method" do
YARD.parse_string "def foo; end"
expect(trim(signature(Registry.at('#foo')))).to eq @results[:regular]
end
it "allows default return type to be changed" do
@options.default_return = "Hello"
YARD.parse_string "def foo; end"
expect(trim(signature(Registry.at('#foo')))).to eq @results[:default_return]
end
it "allows default return type to be omitted" do
@options.default_return = ""
YARD.parse_string "def foo; end"
expect(trim(signature(Registry.at('#foo')))).to eq @results[:no_default_return]
end
it "shows signature for private class method" do
YARD.parse_string "class A; private; def self.foo; end end"
expect(trim(signature(Registry.at('A.foo')))).to eq @results[:private_class]
end
it "shows return type for single type" do
YARD.parse_string <<-'eof'
# @return [String]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:single]
end
it "shows return type for 2 types" do
YARD.parse_string <<-'eof'
# @return [String, Symbol]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:two_types]
end
it "shows return type for 2 types over multiple tags" do
YARD.parse_string <<-'eof'
# @return [String]
# @return [Symbol]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:two_types_multitag]
end
it "shows 'Type?' if return types are [Type, nil]" do
YARD.parse_string <<-'eof'
# @return [Type, nil]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:type_nil]
end
it "shows 'Type?' if return types are [Type, nil, nil] (extra nil)" do
YARD.parse_string <<-'eof'
# @return [Type, nil]
# @return [nil]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:type_nil]
end
it "shows 'Type+' if return types are [Type, Array]" do
YARD.parse_string <<-'eof'
# @return [Type, ]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:type_array]
end
it "shows (Type, ...) for more than 2 return types" do
YARD.parse_string <<-'eof'
# @return [Type, ]
# @return [AnotherType]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:multitype]
end
it "shows (void) for @return [void] by default" do
YARD.parse_string <<-'eof'
# @return [void]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:void]
end
it "does not show return for @return [void] if :hide_void_return is true" do
@options.hide_void_return = true
YARD.parse_string <<-'eof'
# @return [void]
def foo; end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:hide_void]
end
it "shows block for method with yield" do
YARD.parse_string <<-'eof'
def foo; yield(a, b, c) end
eof
expect(trim(signature(Registry.at('#foo')))).to eq @results[:block]
end
it "uses regular return tag if the @overload is empty" do
YARD.parse_string <<-'eof'
# @overload foobar
# Hello world
# @return [String]
def foo; end
eof
expect(trim(signature(Registry.at('#foo').tag(:overload)))).to eq @results[:empty_overload]
end
end
yard-0.9.7/spec/templates/helpers/markup_helper_spec.rb 0000644 0000041 0000041 00000012364 13035234564 023320 0 ustar www-data www-data # frozen_string_literal: true
module YARD::Templates::Helpers::MarkupHelper
public :load_markup_provider, :markup_class, :markup_provider
end
class GeneratorMock
attr_accessor :options
include YARD::Templates::Helpers::MarkupHelper
def initialize(options = Templates::TemplateOptions.new)
self.options = options
end
end
RSpec.describe YARD::Templates::Helpers::MarkupHelper do
before do
YARD::Templates::Helpers::MarkupHelper.clear_markup_cache
end
describe "#load_markup_provider" do
before do
allow(log).to receive(:error)
@gen = GeneratorMock.new
@gen.options.reset_defaults
end
it "exits on an invalid markup type" do
@gen.options.markup = :invalid
expect(@gen.load_markup_provider).to be false
end
it "fails when an invalid markup provider is specified" do
@gen.options.update(:markup => :markdown, :markup_provider => :invalid)
expect(@gen.load_markup_provider).to be false
expect(@gen.markup_class).to eq nil
end
it "loads RDocMarkup if rdoc is specified and it is installed" do
@gen.options.markup = :rdoc
expect(@gen.load_markup_provider).to be true
expect(@gen.markup_class).to eq YARD::Templates::Helpers::Markup::RDocMarkup
end
it "fails if RDoc cannot be loaded" do
@gen.options.markup = :rdoc
expect(@gen).to receive(:eval).with('::YARD::Templates::Helpers::Markup::RDocMarkup').and_raise(NameError)
expect(@gen.load_markup_provider).to be false
expect(@gen.markup_provider).to eq nil
end
it "searches through available markup providers for the markup type if none is set" do
expect(@gen).to receive(:eval).with('::RedcarpetCompat').and_return(double(:bluecloth))
expect(@gen).to receive(:require).with('redcarpet').and_return(true)
expect(@gen).not_to receive(:require).with('maruku')
@gen.options.markup = :markdown
# this only raises an exception because we mock out require to avoid
# loading any libraries but our implementation tries to return the library
# name as a constant
expect(@gen.load_markup_provider).to be true
expect(@gen.markup_provider).to eq :redcarpet
end
it "continues searching if some of the providers are unavailable" do
expect(@gen).to receive(:require).with('redcarpet').and_raise(LoadError)
expect(@gen).to receive(:require).with('rdiscount').and_raise(LoadError)
expect(@gen).to receive(:require).with('kramdown').and_raise(LoadError)
expect(@gen).to receive(:require).with('bluecloth').and_raise(LoadError)
expect(@gen).to receive(:require).with('maruku').and_raise(LoadError)
expect(@gen).to receive(:require).with('rpeg-markdown').and_return(true)
expect(@gen).to receive(:eval).with('::PEGMarkdown').and_return(true)
@gen.options.markup = :markdown
# this only raises an exception because we mock out require to avoid
# loading any libraries but our implementation tries to return the library
# name as a constant
@gen.load_markup_provider
expect(@gen.markup_provider).to eq :"rpeg-markdown"
end
it "overrides the search if `:markup_provider` is set in options" do
expect(@gen).to receive(:require).with('rdiscount').and_return(true)
expect(@gen).to receive(:eval).with('::RDiscount').and_return(true)
@gen.options.update(:markup => :markdown, :markup_provider => :rdiscount)
@gen.load_markup_provider
expect(@gen.markup_provider).to eq :rdiscount
end
it "fails if no provider is found" do
YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].each do |p|
expect(@gen).to receive(:require).with(p[:lib].to_s).and_raise(LoadError)
end
@gen.options.markup = :markdown
expect(@gen.load_markup_provider).to be false
expect(@gen.markup_provider).to eq nil
end
it "fails if overridden provider is not found" do
expect(@gen).to receive(:require).with('rdiscount').and_raise(LoadError)
@gen.options.update(:markup => :markdown, :markup_provider => :rdiscount)
expect(@gen.load_markup_provider).to be false
expect(@gen.markup_provider).to eq nil
end
it "fails if the markup type is not found" do
expect(log).to receive(:error).with(/Invalid markup/)
@gen.options.markup = :xxx
expect(@gen.load_markup_provider).to be false
expect(@gen.markup_provider).to eq nil
end
end
describe "#markup_for_file" do
include YARD::Templates::Helpers::MarkupHelper
it "looks for a shebang line" do
expect(markup_for_file("#!text\ntext here", 'file.rdoc')).to eq :text
end
it "returns the default markup type if no shebang is found or no valid ext is found" do
allow(self).to receive(:options).and_return(Options.new.update(:markup => :default_type))
expect(markup_for_file('', 'filename')).to eq :default_type
end
it "looks for a file extension if no shebang is found" do
expect(markup_for_file('', 'filename.MD')).to eq :markdown
end
Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS.each do |type, exts|
exts.each do |ext|
it "recognizes .#{ext} as #{type} markup type" do
expect(markup_for_file('', "filename.#{ext}")).to eq type
end
end
end
end
end
yard-0.9.7/spec/templates/helpers/method_helper_spec.rb 0000644 0000041 0000041 00000004557 13035234564 023306 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Templates::Helpers::MethodHelper do
include YARD::Templates::Helpers::BaseHelper
include YARD::Templates::Helpers::MethodHelper
describe "#format_args" do
it "displays keyword arguments" do
params = [['a:', '1'], ['b:', '2'], ['**kwargs', nil]]
YARD.parse_string 'def foo; end'
allow(Registry.at('#foo')).to receive(:parameters) { params }
expect(format_args(Registry.at('#foo'))).to eq '(a: 1, b: 2, **kwargs)'
end
it "does not show &blockarg if no @param tag and has @yield" do
YARD.parse_string <<-'eof'
# @yield blah
def foo(&block); end
eof
expect(format_args(Registry.at('#foo'))).to eq ''
end
it "does not show &blockarg if no @param tag and has @yieldparam" do
YARD.parse_string <<-'eof'
# @yieldparam blah test
def foo(&block); end
eof
expect(format_args(Registry.at('#foo'))).to eq ''
end
it "shows &blockarg if @param block is documented (even with @yield)" do
YARD.parse_string <<-'eof'
# @yield [a,b]
# @yieldparam a test
# @param block test
def foo(&block) end
eof
expect(format_args(Registry.at('#foo'))).to eq '(&block)'
end
end
describe "#format_block" do
before { YARD::Registry.clear }
it "shows block for method with yield" do
YARD.parse_string <<-'eof'
def foo; yield(a, b, c) end
eof
expect(format_block(Registry.at('#foo'))).to eq "{|a, b, c| ... }"
end
it "shows block for method with @yieldparam tags" do
YARD.parse_string <<-'eof'
# @yieldparam _self me!
def foo; end
eof
expect(format_block(Registry.at('#foo'))).to eq "{|_self| ... }"
end
it "shows block for method with @yield but no types" do
YARD.parse_string <<-'eof'
# @yield blah
# @yieldparam a
def foo; end
# @yield blah
def foo2; end
eof
expect(format_block(Registry.at('#foo'))).to eq "{|a| ... }"
expect(format_block(Registry.at('#foo2'))).to eq "{ ... }"
end
it "shows block for method with @yield and types" do
YARD.parse_string <<-'eof'
# @yield [a, b, c] blah
# @yieldparam a
def foo; end
eof
expect(format_block(Registry.at('#foo'))).to eq "{|a, b, c| ... }"
end
end
end
yard-0.9.7/spec/templates/helpers/html_helper_spec.rb 0000644 0000041 0000041 00000062454 13035234564 022772 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + "/shared_signature_examples"
require 'ostruct'
RSpec.describe YARD::Templates::Helpers::HtmlHelper do
include YARD::Templates::Helpers::BaseHelper
include YARD::Templates::Helpers::HtmlHelper
include YARD::Templates::Helpers::MethodHelper
def options
Templates::TemplateOptions.new.tap do |o|
o.reset_defaults
o.default_return = nil
end
end
describe "#h" do
it "uses #h to escape HTML" do
expect(h('Usage: foo "bar" ')).to eq "Usage: foo "bar" <baz>"
end
end
describe "#charset" do
it "returns foo if LANG=foo" do
expect(ENV).to receive(:[]).with('LANG').and_return('shift_jis') if YARD.ruby18?
expect(Encoding.default_external).to receive(:name).and_return('shift_jis') if defined?(Encoding)
expect(charset).to eq 'shift_jis'
end
['US-ASCII', 'ASCII-7BIT', 'ASCII-8BIT'].each do |type|
it "converts #{type} to iso-8859-1" do
expect(ENV).to receive(:[]).with('LANG').and_return(type) if YARD.ruby18?
expect(Encoding.default_external).to receive(:name).and_return(type) if defined?(Encoding)
expect(charset).to eq 'iso-8859-1'
end
end
it "supports utf8 as an encoding value for utf-8" do
type = 'utf8'
expect(ENV).to receive(:[]).with('LANG').and_return(type) if YARD.ruby18?
expect(Encoding.default_external).to receive(:name).and_return(type) if defined?(Encoding)
expect(charset).to eq 'utf-8'
end
it "takes file encoding if there is a file" do
@file = OpenStruct.new(:contents => String.new('foo').force_encoding('sjis'))
# not the correct charset name, but good enough
expect(['Shift_JIS', 'Windows-31J']).to include(charset)
end if YARD.ruby19?
it "takes file encoding if there is a file" do
allow(ENV).to receive(:[]).with('LANG').and_return('utf-8') if YARD.ruby18?
@file = OpenStruct.new(:contents => 'foo')
expect(charset).to eq 'utf-8'
end if YARD.ruby18?
if YARD.ruby18?
it "returns utf-8 if no LANG env is set" do
expect(ENV).to receive(:[]).with('LANG').and_return(nil)
expect(charset).to eq 'utf-8'
end
it "only returns charset part of lang" do
expect(ENV).to receive(:[]).with('LANG').and_return('en_US.UTF-8')
expect(charset).to eq 'utf-8'
end
end
end
describe "#format_types" do
it "includes brackets by default" do
text = ["String"]
expect(self).to receive(:linkify).at_least(1).times.with("String", "String").and_return("String")
expect(format_types(text)).to eq format_types(text, true)
expect(format_types(text)).to eq "(String)"
end
it "avoids brackets if brackets=false" do
expect(self).to receive(:linkify).with("String", "String").and_return("String")
expect(self).to receive(:linkify).with("Symbol", "Symbol").and_return("Symbol")
expect(format_types(["String", "Symbol"], false)).to eq "String, Symbol"
end
{"String" => [["String"],
"String"],
"A::B::C" => [["A::B::C"],
"A::B::C"],
"Array" => [["Array", "String"],
"Array<String>"],
"Array" => [["Array", "String", "Symbol"],
"Array<String, Symbol>"],
"Array<{String => Array}>" => [["Array", "String", "Array", "Symbol"],
"Array<{String => " \
"Array<Symbol>}>"]}.each do |text, values|
it "links all classes in #{text}" do
if text.count('<') > 0
expect(self).to receive(:h).with('<').at_least(text.count('<')).times.and_return("<")
end
if text.count('>') > 0
expect(self).to receive(:h).with('>').at_least(text.count('>')).times.and_return(">")
end
values[0].each {|v| expect(self).to receive(:linkify).with(v, v).and_return("#{v}") }
expect(format_types([text], false)).to eq values[1]
end
end
end
describe "#htmlify" do
it "does not use hard breaks for textile markup (RedCloth specific)" do
begin; require 'redcloth'; rescue LoadError; pending 'test requires redcloth gem' end
expect(htmlify("A\nB", :textile)).not_to include("", :pre)).to eq "fo\no\n\nbar<>
"
end
it "returns regular text with :text markup" do
expect(htmlify("fo\no\n\nbar<>", :text)).to eq "fo
o
bar<>"
end
it "returns unmodified text with :none markup" do
expect(htmlify("fo\no\n\nbar<>", :none)).to eq "fo\no\n\nbar<>"
end
it "highlights ruby if markup is :ruby" do
expect(htmlify("class Foo; end", :ruby)).to match(/\AHI"
end
it "allows inline includes for {include:} in the middle of a line" do
load_markup_provider(:rdoc)
expect(File).to receive(:file?).with('foo.rdoc').and_return(true)
expect(File).to receive(:read).with('foo.rdoc').and_return('HI')
expect(htmlify("test {include:file:foo.rdoc}", :rdoc).gsub(/[\r?\n]+/, '')).to eq 'test HI
'
end
it "autolinks URLs (markdown specific)" do
log.enter_level(Logger::FATAL) do
unless markup_class(:markdown).to_s == "RedcarpetCompat"
pending 'This test depends on a markdown engine that supports autolinking'
end
end
expect(htmlify('http://example.com', :markdown).chomp.gsub('/', '/')).to eq(
''
)
end
it "does not autolink URLs inside of {} (markdown specific)" do
log.enter_level(Logger::FATAL) do
pending 'This test depends on markdown' unless markup_class(:markdown)
end
expect(htmlify('{http://example.com Title}', :markdown).chomp).to match(
%r{}
)
expect(htmlify('{http://example.com}', :markdown).chomp).to match(
%r{}
)
end
it "creates tables (markdown specific)" do
log.enter_level(Logger::FATAL) do
unless markup_class(:markdown).to_s == "RedcarpetCompat"
pending "This test depends on a markdown engine that supports tables"
end
end
markdown = <<-EOF.strip
City | State | Country
--------|-------|--------
Raleigh | NC | US
Seattle | WA | US
EOF
html = htmlify(markdown, :markdown)
expect(html).to match(//)
expect(html).to match %r{City }
expect(html).to match %r{NC }
end
it "handles fenced code blocks (Redcarpet specific)" do
log.enter_level(Logger::FATAL) do
unless markup_class(:markdown).to_s == 'RedcarpetCompat'
pending 'This test is Redcarpet specific'
end
end
markdown = "Introduction:\n```ruby\nputs\n\nputs\n```"
html = htmlify(markdown, :markdown)
expect(html).to match %r{^Introduction:
.*}m
end
end
describe "#link_object" do
let(:object) { CodeObjects::NamespaceObject.new(nil, :YARD) }
it "returns the object path if there's no serializer and no title" do
allow(self).to receive(:serializer).and_return(nil)
expect(link_object(CodeObjects::NamespaceObject.new(nil, :YARD))).to eq "YARD"
end
it "returns the title if there's a title but no serializer" do
allow(self).to receive(:serializer).and_return(nil)
expect(link_object(CodeObjects::NamespaceObject.new(nil, :YARD), 'title')).to eq "title"
end
it "links objects from overload tag" do
YARD.parse_string <<-'eof'
module Foo
class Bar; def a; end end
class Baz
# @overload a
def a; end
end
end
eof
obj = Registry.at('Foo::Baz#a').tag(:overload)
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
allow(self).to receive(:object).and_return(obj)
expect(link_object("Bar#a")).to match(/href="Bar.html#a-instance_method"/)
end
it "uses relative path in title" do
CodeObjects::ModuleObject.new(:root, :YARD)
CodeObjects::ClassObject.new(P('YARD'), :Bar)
allow(self).to receive(:object).and_return(CodeObjects::ModuleObject.new(P('YARD'), :Foo))
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
expect(link_object("Bar")).to match %r{>Bar}
end
it "uses #title if overridden" do
CodeObjects::ModuleObject.new(:root, :YARD)
CodeObjects::ClassObject.new(P('YARD'), :Bar)
allow(Registry.at('YARD::Bar')).to receive(:title).and_return('TITLE!')
allow(self).to receive(:object).and_return(Registry.at('YARD::Bar'))
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
expect(link_object("Bar")).to match %r{>TITLE!}
end
it "uses relative path to parent class in title" do
root = CodeObjects::ModuleObject.new(:root, :YARD)
obj = CodeObjects::ModuleObject.new(root, :SubModule)
allow(self).to receive(:object).and_return(obj)
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
expect(link_object("YARD")).to match %r{>YARD}
end
it "uses Klass.foo when linking to class method in current namespace" do
root = CodeObjects::ModuleObject.new(:root, :Klass)
CodeObjects::MethodObject.new(root, :foo, :class)
allow(self).to receive(:object).and_return(root)
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
expect(link_object("foo")).to match %r{>Klass.foo}
end
it "escapes method name in title" do
YARD.parse_string <<-'eof'
class Array
def &(other)
end
end
eof
obj = Registry.at('Array#&')
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
allow(self).to receive(:object).and_return(obj)
expect(link_object("Array#&")).to match(/title="Array#& \(method\)"/)
end
end
describe "#url_for" do
before { Registry.clear }
it "returns nil if serializer is nil" do
allow(self).to receive(:serializer).and_return nil
allow(self).to receive(:object).and_return Registry.root
expect(url_for(P("Mod::Class#meth"))).to be nil
end
it "returns nil if object is hidden" do
yard = CodeObjects::ModuleObject.new(:root, :YARD)
allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
allow(self).to receive(:object).and_return Registry.root
allow(self).to receive(:options).and_return OpenStruct.new(:verifier => Verifier.new('false'))
expect(url_for(yard)).to be nil
end
it "returns nil if serializer does not implement #serialized_path" do
allow(self).to receive(:serializer).and_return Serializers::Base.new
allow(self).to receive(:object).and_return Registry.root
expect(url_for(P("Mod::Class#meth"))).to be nil
end
it "links to a path/file for a namespace object" do
allow(self).to receive(:serializer).and_return Serializers::FileSystemSerializer.new
allow(self).to receive(:object).and_return Registry.root
yard = CodeObjects::ModuleObject.new(:root, :YARD)
expect(url_for(yard)).to eq 'YARD.html'
end
it "links to the object's namespace path/file and use the object as the anchor" do
allow(self).to receive(:serializer).and_return Serializers::FileSystemSerializer.new
allow(self).to receive(:object).and_return Registry.root
yard = CodeObjects::ModuleObject.new(:root, :YARD)
meth = CodeObjects::MethodObject.new(yard, :meth)
expect(url_for(meth)).to eq 'YARD.html#meth-instance_method'
end
it "properly urlencodes methods with punctuation in links" do
obj = CodeObjects::MethodObject.new(nil, :/)
serializer = double(:serializer, :serialized_path => "file.html")
allow(self).to receive(:serializer).and_return serializer
allow(self).to receive(:object).and_return obj
expect(url_for(obj)).to eq "#%2F-instance_method"
end
end
describe "#anchor_for" do
it "does not urlencode data when called directly" do
obj = CodeObjects::MethodObject.new(nil, :/)
expect(anchor_for(obj)).to eq "/-instance_method"
end
end
describe "#resolve_links" do
def parse_link(link)
results = {}
link =~ %r{(.+?)}m
params = $1
results[:inner_text] = $2
params.scan(/\s*(\S+?)=['"](.+?)['"]\s*/).each do |key, value|
results[key.to_sym] = value.gsub(/^["'](.+)["']$/, '\1')
end
results
end
it "escapes {} syntax with backslash (\\{foo bar})" do
input = '\{foo bar} \{XYZ} \{file:FOO} $\{N-M}'
output = '{foo bar} {XYZ} {file:FOO} ${N-M}'
expect(resolve_links(input)).to eq output
end
it "escapes {} syntax with ! (!{foo bar})" do
input = '!{foo bar} !{XYZ} !{file:FOO} $!{N-M}'
output = '{foo bar} {XYZ} {file:FOO} ${N-M}'
expect(resolve_links(input)).to eq output
end
it "links static files with file: prefix" do
allow(self).to receive(:serializer).and_return Serializers::FileSystemSerializer.new
allow(self).to receive(:object).and_return Registry.root
expect(parse_link(resolve_links("{file:TEST.txt#abc}"))).to eq(
:inner_text => "TEST",
:title => "TEST",
:href => "file.TEST.html#abc"
)
expect(parse_link(resolve_links("{file:TEST.txt title}"))).to eq(
:inner_text => "title",
:title => "title",
:href => "file.TEST.html"
)
end
it "creates regular links with http:// or https:// prefixes" do
expect(parse_link(resolve_links("{http://example.com}"))).to eq(
:inner_text => "http://example.com",
:target => "_parent",
:href => "http://example.com",
:title => "http://example.com"
)
expect(parse_link(resolve_links("{http://example.com title}"))).to eq(
:inner_text => "title",
:target => "_parent",
:href => "http://example.com",
:title => "title"
)
end
it "creates mailto links with mailto: prefixes" do
expect(parse_link(resolve_links('{mailto:joanna@example.com}'))).to eq(
:inner_text => 'mailto:joanna@example.com',
:target => '_parent',
:href => 'mailto:joanna@example.com',
:title => 'mailto:joanna@example.com'
)
expect(parse_link(resolve_links('{mailto:steve@example.com Steve}'))).to eq(
:inner_text => 'Steve',
:target => '_parent',
:href => 'mailto:steve@example.com',
:title => 'Steve'
)
end
it "ignores {links} that begin with |...|" do
expect(resolve_links("{|x|x == 1}")).to eq "{|x|x == 1}"
end
it "gracefully ignores {} in links" do
allow(self).to receive(:linkify).with('Foo', 'Foo').and_return('FOO')
expect(resolve_links("{} {} {Foo Foo}")).to eq '{} {} FOO'
end
%w(tt code pre).each do |tag|
it "ignores links in <#{tag}>" do
text = "<#{tag}>{Foo}"
expect(resolve_links(text)).to eq text
end
end
it "resolves {Name}" do
expect(self).to receive(:link_file).with('TEST', nil, nil).and_return('')
resolve_links("{file:TEST}")
end
it "resolves ({Name})" do
expect(self).to receive(:link_file).with('TEST', nil, nil).and_return('')
resolve_links("({file:TEST})")
end
it "resolves link with newline in title-part" do
expect(parse_link(resolve_links("{http://example.com foo\nbar}"))).to eq(
:inner_text => "foo bar",
:target => "_parent",
:href => "http://example.com",
:title => "foo bar"
)
end
it "resolves links to methods whose names have been escaped" do
expect(self).to receive(:linkify).with('Object#<<', nil).and_return('')
resolve_links("{Object#<<}")
end
it "warns about missing reference at right file location for object" do
YARD.parse_string <<-eof
# Comments here
# And a reference to {InvalidObject}
class MyObject; end
eof
logger = double(:log)
expect(logger).to receive(:warn).ordered.with(
"In file `(stdin)':2: Cannot resolve link to InvalidObject from text:\n\t...{InvalidObject}"
)
allow(self).to receive(:log).and_return(logger)
allow(self).to receive(:object).and_return(Registry.at('MyObject'))
resolve_links(object.docstring)
end
it "shows ellipsis on either side if there is more on the line in a reference warning" do
YARD.parse_string <<-eof
# {InvalidObject1} beginning of line
# end of line {InvalidObject2}
# Middle of {InvalidObject3} line
# {InvalidObject4}
class MyObject; end
eof
logger = double(:log)
expect(logger).to receive(:warn).ordered.with("In file `(stdin)':1: Cannot resolve link to InvalidObject1 from text:\n\t{InvalidObject1}...")
expect(logger).to receive(:warn).ordered.with("In file `(stdin)':2: Cannot resolve link to InvalidObject2 from text:\n\t...{InvalidObject2}")
expect(logger).to receive(:warn).ordered.with("In file `(stdin)':3: Cannot resolve link to InvalidObject3 from text:\n\t...{InvalidObject3}...")
expect(logger).to receive(:warn).ordered.with("In file `(stdin)':4: Cannot resolve link to InvalidObject4 from text:\n\t{InvalidObject4}")
allow(self).to receive(:log).and_return(logger)
allow(self).to receive(:object).and_return(Registry.at('MyObject'))
resolve_links(object.docstring)
end
it "warns about missing reference for file template (no object)" do
@file = CodeObjects::ExtraFileObject.new('myfile.txt', '')
logger = double(:log)
expect(logger).to receive(:warn).ordered.with("In file `myfile.txt':3: Cannot resolve link to InvalidObject from text:\n\t...{InvalidObject Some Title}")
allow(self).to receive(:log).and_return(logger)
allow(self).to receive(:object).and_return(Registry.root)
resolve_links(<<-eof)
Hello world
This is a line
And {InvalidObject Some Title}
And more.
eof
end
end
describe "#signature" do
before do
arrow = "⇒"
@results = {
:regular => "#foo #{arrow} Object",
:default_return => "#foo #{arrow} Hello",
:no_default_return => "#foo",
:private_class => ".foo #{arrow} Object (private)",
:single => "#foo #{arrow} String",
:two_types => "#foo #{arrow} String, Symbol",
:two_types_multitag => "#foo #{arrow} String, Symbol",
:type_nil => "#foo #{arrow} Type?",
:type_array => "#foo #{arrow} Type+",
:multitype => "#foo #{arrow} Type, ...",
:void => "#foo #{arrow} void",
:hide_void => "#foo",
:block => "#foo {|a, b, c| ... } #{arrow} Object",
:empty_overload => "#foobar #{arrow} String"
}
end
def format_types(types, _brackets = false) types.join(", ") end
def signature(obj, link = false) super(obj, link).strip end
it_should_behave_like "signature"
it "links to regular method if overload name does not have the same method name" do
YARD.parse_string <<-eof
class Foo
# @overload bar(a, b, c)
def foo; end
end
eof
serializer = double(:serializer)
allow(serializer).to receive(:serialized_path).with(Registry.at('Foo')).and_return('')
allow(self).to receive(:serializer).and_return(serializer)
allow(self).to receive(:object).and_return(Registry.at('Foo'))
expect(signature(Registry.at('Foo#foo').tag(:overload), true)).to eq(
"#bar(a, b, c) "
)
end
end
describe "#html_syntax_highlight" do
subject do
obj = OpenStruct.new
obj.options = options
obj.object = Registry.root
obj.extend(Templates::Helpers::HtmlHelper)
obj
end
it "returns empty string on nil input" do
expect(subject.html_syntax_highlight(nil)).to eq ''
end
it "calls #html_syntax_highlight_ruby by default" do
Registry.root.source_type = nil
expect(subject).to receive(:html_syntax_highlight_ruby).with('def x; end')
subject.html_syntax_highlight('def x; end')
end
it "calls #html_syntax_highlight_NAME if there's an object with a #source_type" do
subject.object = OpenStruct.new(:source_type => :NAME)
expect(subject).to receive(:html_markup_html) {|text| text }
expect(subject).to receive(:html_syntax_highlight_NAME).and_return("foobar")
expect(subject.htmlify('def x; end
', :html)).to eq(
'foobar
'
)
end
it "adds !!!LANG to className in outputted pre tag" do
subject.object = OpenStruct.new(:source_type => :LANG)
expect(subject).to receive(:html_markup_html) {|text| text }
expect(subject).to receive(:html_syntax_highlight_LANG).and_return("foobar")
expect(subject.htmlify("!!!LANG\ndef x; end
", :html)).to eq(
'foobar
'
)
end
it "calls html_syntax_highlight_NAME if source starts with !!!NAME" do
expect(subject).to receive(:html_syntax_highlight_NAME).and_return("foobar")
expect(subject.html_syntax_highlight(<<-eof
!!!NAME
def x; end
eof
)).to eq "foobar"
end
it "does not highlight if highlight option is false" do
subject.options.highlight = false
expect(subject).not_to receive(:html_syntax_highlight_ruby)
expect(subject.html_syntax_highlight('def x; end')).to eq 'def x; end'
end
it "does not highlight if there is no highlight method specified by !!!NAME" do
def subject.respond_to?(method, include_all = false)
return false if method == 'html_syntax_highlight_NAME'
super
end
expect(subject).not_to receive(:html_syntax_highlight_NAME)
expect(subject.html_syntax_highlight("!!!NAME\ndef x; end")).to eq "def x; end"
end
it "highlights as ruby if htmlify(text, :ruby) is called" do
expect(subject).to receive(:html_syntax_highlight_ruby).with('def x; end').and_return('x')
expect(subject.htmlify('def x; end', :ruby)).to eq 'x
'
end
it "does not prioritize object source type when called directly" do
expect(subject).to receive(:html_syntax_highlight_ruby).with('def x; end').and_return('x')
subject.object = OpenStruct.new(:source_type => :c)
expect(subject.html_syntax_highlight("def x; end")).to eq "x"
end
it "doesn't escape code snippets twice" do
expect(subject.htmlify('{"foo" => 1}
', :html)).to eq(
'{"foo" => 1}
'
)
end
it "highlights source when matching a pre lang= tag" do
expect(subject.htmlify('x = 1
', :html)).to eq(
'x = 1
'
)
end
it "highlights source when matching a code class= tag" do
expect(subject.htmlify('x = 1
', :html)).to eq(
'x = 1
'
)
end
end
describe "#link_url" do
it "adds target if scheme is provided" do
expect(link_url("http://url.com")).to include(" target=\"_parent\"")
expect(link_url("https://url.com")).to include(" target=\"_parent\"")
expect(link_url("irc://url.com")).to include(" target=\"_parent\"")
expect(link_url("../not/scheme")).not_to include("target")
end
end
end
yard-0.9.7/spec/templates/helpers/base_helper_spec.rb 0000644 0000041 0000041 00000013420 13035234564 022725 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Templates::Helpers::BaseHelper do
include YARD::Templates::Helpers::BaseHelper
describe "#run_verifier" do
it "runs verifier proc against list if provided" do
mock = Verifier.new
expect(mock).to receive(:call).with(1)
expect(mock).to receive(:call).with(2)
expect(mock).to receive(:call).with(3)
expect(self).to receive(:options).at_least(1).times.and_return(Options.new.update(:verifier => mock))
run_verifier [1, 2, 3]
end
it "prunes list if lambda returns false and only false" do
mock = Verifier.new
expect(self).to receive(:options).at_least(1).times.and_return(Options.new.update(:verifier => mock))
expect(mock).to receive(:call).with(1).and_return(false)
expect(mock).to receive(:call).with(2).and_return(true)
expect(mock).to receive(:call).with(3).and_return(nil)
expect(mock).to receive(:call).with(4).and_return("value")
expect(run_verifier([1, 2, 3, 4])).to eq [2, 3, 4]
end
it "returns list if no verifier exists" do
expect(self).to receive(:options).at_least(1).times.and_return(Options.new)
expect(run_verifier([1, 2, 3])).to eq [1, 2, 3]
end
end
describe "#h" do
it "returns just the text" do
expect(h("hello world")).to eq "hello world"
expect(h(nil)).to eq nil
end
end
describe "#link_object" do
it "returns the title if provided" do
expect(link_object(1, "title")).to eq "title"
expect(link_object(Registry.root, "title")).to eq "title"
end
it "returns a path if argument is a Proxy or object" do
expect(link_object(Registry.root)).to eq "Top Level Namespace"
expect(link_object(P("Array"))).to eq "Array"
end
it "returns path of Proxified object if argument is a String or Symbol" do
expect(link_object("Array")).to eq "Array"
expect(link_object(:"A::B")).to eq "A::B"
end
it "returns the argument if not an object, proxy, String or Symbol" do
expect(link_object(1)).to eq 1
end
end
describe "#link_url" do
it "returns the URL" do
expect(link_url("http://url")).to eq "http://url"
end
end
describe "#linkify" do
let(:object) { Registry.root }
# before do
# stub!(:object).and_return(Registry.root)
# end
it "calls #link_url for mailto: links" do
expect(self).to receive(:link_url)
linkify("mailto:steve@example.com")
end
it "calls #link_url for URL schemes (http://)" do
expect(self).to receive(:link_url)
linkify("http://example.com")
end
it "calls #link_file for file: links" do
expect(self).to receive(:link_file).with('Filename', nil, 'anchor')
linkify("file:Filename#anchor")
end
it "passes off to #link_object if argument is an object" do
obj = CodeObjects::NamespaceObject.new(nil, :YARD)
expect(self).to receive(:link_object).with(obj)
linkify obj
end
it "returns empty string and warn if object does not exist" do
expect(log).to receive(:warn).with(/Cannot find object .* for inclusion/)
expect(linkify('include:NotExist')).to eq ''
end
it "passes off to #link_url if argument is recognized as a URL" do
url = "http://yardoc.org/"
expect(self).to receive(:link_url).with(url, nil, :target => '_parent')
linkify url
end
it "calls #link_include_object for include:ObjectName" do
obj = CodeObjects::NamespaceObject.new(:root, :Foo)
expect(self).to receive(:link_include_object).with(obj)
linkify 'include:Foo'
end
it "calls #link_include_file for include:file:path/to/file" do
expect(File).to receive(:file?).with('path/to/file').and_return(true)
expect(File).to receive(:read).with('path/to/file').and_return('FOO')
expect(linkify('include:file:path/to/file')).to eq 'FOO'
end
it "does not allow include:file for path above pwd" do
expect(log).to receive(:warn).with("Cannot include file from path `a/b/../../../../file'")
expect(linkify('include:file:a/b/../../../../file')).to eq ''
end
it "warns if include:file:path does not exist" do
expect(log).to receive(:warn).with(/Cannot find file .+ for inclusion/)
expect(linkify('include:file:notexist')).to eq ''
end
end
describe "#format_types" do
it "returns the list of types separated by commas surrounded by brackets" do
expect(format_types(['a', 'b', 'c'])).to eq '(a, b, c)'
end
it "returns the list of types without brackets if brackets=false" do
expect(format_types(['a', 'b', 'c'], false)).to eq 'a, b, c'
end
it "returns an empty string if list is empty or nil" do
expect(format_types(nil)).to eq ""
expect(format_types([])).to eq ""
end
end
describe "#format_object_type" do
it "returns Exception if type is Exception" do
obj = double(:object, :is_exception? => true)
allow(obj).to receive(:is_a?) {|arg| arg == YARD::CodeObjects::ClassObject }
expect(format_object_type(obj)).to eq "Exception"
end
it "returns Class if type is Class" do
obj = double(:object, :is_exception? => false)
allow(obj).to receive(:is_a?) {|arg| arg == YARD::CodeObjects::ClassObject }
expect(format_object_type(obj)).to eq "Class"
end
it "returns object type in other cases" do
obj = double(:object, :type => "value")
expect(format_object_type(obj)).to eq "Value"
end
end
describe "#format_object_title" do
it "returns Top Level Namespace for root object" do
expect(format_object_title(Registry.root)).to eq "Top Level Namespace"
end
it "returns 'type: title' in other cases" do
obj = double(:object, :type => :class, :title => "A::B::C")
expect(format_object_title(obj)).to eq "Class: A::B::C"
end
end
end
yard-0.9.7/spec/templates/helpers/html_syntax_highlight_helper_spec.rb 0000644 0000041 0000041 00000006311 13035234564 026415 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Templates::Helpers::HtmlSyntaxHighlightHelper do
include YARD::Templates::Helpers::HtmlHelper
include YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
describe "#html_syntax_highlight" do
let(:object) { CodeObjects::NamespaceObject.new(:root, :YARD) }
before do
Registry.root.source_type = :ruby
end
it "does not highlight source if options.highlight is false" do
expect(self).to receive(:options).and_return(Options.new.update(:highlight => false))
expect(html_syntax_highlight("def x\nend")).to eq "def x\nend"
end
it "highlights source (legacy)" do
type = Parser::SourceParser.parser_type
Parser::SourceParser.parser_type = :ruby18
expect(self).to receive(:options).and_return(Options.new.update(:highlight => true))
expect = "defx
'x'+
/x/iend"
result = html_syntax_highlight("def x\n 'x' + /x/i\nend")
html_equals_string(result, expect)
Parser::SourceParser.parser_type = type
end
it "highlights source (ripper)" do
expect(self).to receive(:options).and_return(Options.new.update(:highlight => true))
Parser::SourceParser.parser_type = :ruby
expect = "def x
'
x'
+
/x
/i\nend"
result = html_syntax_highlight("def x\n 'x' + /x/i\nend")
html_equals_string(result, expect)
end if HAVE_RIPPER
it "returns escaped unhighlighted source if a syntax error is found (ripper)" do
allow(self).to receive(:options).and_return(Options.new.update(:highlight => true))
expect(html_syntax_highlight("def &x; ... end")).to eq "def &x; ... end"
end if HAVE_RIPPER
it "returns escaped unhighlighted source if a syntax error is found (ripper)" do
allow(self).to receive(:options).and_return(Options.new.update(:highlight => true))
expect(html_syntax_highlight("$ git clone http://url")).to eq "$ git clone http://url"
end if HAVE_RIPPER
it "links constants/methods" do
other = CodeObjects::NamespaceObject.new(:root, :Other)
allow(self).to receive(:options).and_return(Options.new.update(:highlight => true))
allow(self).to receive(:run_verifier).with([other]).and_return([other])
allow(self).to receive(:link_object).with(other, "Other").and_return("LINK!")
result = html_syntax_highlight("def x; Other end")
html_equals_string(result, "def
x;
LINK! end")
end if HAVE_RIPPER
end
end
yard-0.9.7/spec/templates/helpers/text_helper_spec.rb 0000644 0000041 0000041 00000003720 13035234564 023001 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + "/shared_signature_examples"
RSpec.describe YARD::Templates::Helpers::TextHelper do
include YARD::Templates::Helpers::BaseHelper
include YARD::Templates::Helpers::TextHelper
include YARD::Templates::Helpers::MethodHelper
describe "#signature" do
before do
@results = {
:regular => "root.foo -> Object",
:default_return => "root.foo -> Hello",
:no_default_return => "root.foo",
:private_class => "A.foo -> Object (private)",
:single => "root.foo -> String",
:two_types => "root.foo -> (String, Symbol)",
:two_types_multitag => "root.foo -> (String, Symbol)",
:type_nil => "root.foo -> Type?",
:type_array => "root.foo -> Type+",
:multitype => "root.foo -> (Type, ...)",
:void => "root.foo -> void",
:hide_void => "root.foo",
:block => "root.foo {|a, b, c| ... } -> Object",
:empty_overload => 'root.foobar -> String'
}
end
def signature(obj) super(obj).strip end
it_should_behave_like "signature"
end
describe "#align_right" do
it "aligns text right" do
text = "Method: #some_method (SomeClass)"
expect(align_right(text)).to eq ' ' * 40 + text
end
it "truncates text that is longer than allowed width" do
text = "(Defined in: /home/user/.rip/.packages/some_gem-2460672e333ac07b9190ade88ec9a91c/long/path.rb)"
expect(align_right(text)).to eq ' ' + text[0, 68] + '...'
end
end
describe "#h" do
let(:object) do
YARD::CodeObjects::MethodObject.new(:root, :foo, :instance).tap do |o|
o.docstring = "test"
end
end
it "resolves links" do
expect(h("{include:#foo} 1 2 3").strip).to eq "test 1 2 3"
end
it "uses title when present" do
expect(h("{A b}").strip).to eq "b"
end
it "uses object name when no title is present" do
expect(h("{A}").strip).to eq "A"
end
end
end
yard-0.9.7/spec/templates/template_spec.rb 0000644 0000041 0000041 00000032102 13035234564 020623 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Templates::Template do
def template(path)
YARD::Templates::Engine.template!(path, '/full/path/' + path.to_s)
end
before :each do
YARD::Templates::ErbCache.clear!
end
describe ".include_parent" do
it "does not include parent directory if parent directory is a template root path" do
mod = template('q')
expect(mod).not_to include(template(''))
end
it "includes overridden parent directory" do
allow(Engine).to receive(:template_paths).and_return(['/foo', '/bar'])
expect(File).to receive(:directory?).with('/foo/a/b').and_return(true)
expect(File).to receive(:directory?).with('/bar/a/b').and_return(false)
expect(File).to receive(:directory?).with('/foo/a').at_least(1).times.and_return(true)
expect(File).to receive(:directory?).with('/bar/a').at_least(1).times.and_return(true)
ancestors = Engine.template('a/b').ancestors.map(&:class_name)
expect(ancestors[0, 3]).to eq %w(Template__foo_a_b Template__bar_a Template__foo_a)
end
it "includes parent directory template if exists" do
mod1 = template('x')
mod2 = template('x/y')
expect(mod2).to include(mod1)
end
end
describe ".full_paths" do
it "lists full_path" do
mod = template(:a)
expect(mod.full_paths).to eq ['/full/path/a']
end
it "lists paths of included modules" do
mod = template(:a)
mod.send(:include, template(:b))
expect(mod.full_paths).to eq ['/full/path/a', '/full/path/b']
end
it "lists paths from modules of included modules" do
mod = template(:c)
mod.send(:include, template(:d))
mod.send(:include, template(:a))
expect(mod.full_paths).to eq ['c', 'a', 'b', 'd'].map {|o| '/full/path/' + o }
end
it "only lists full paths of modules that respond to full_paths" do
mod = template(:d)
mod.send(:include, Enumerable)
expect(mod.full_paths).to eq ['/full/path/d']
end
end
describe ".load_setup_rb" do
it "loads setup.rb file for module" do
expect(File).to receive(:file?).with('/full/path/e/setup.rb').and_return(true)
expect(File).to receive(:read).with('/full/path/e/setup.rb').and_return(String.new('def success; end'))
expect(template(:e).new).to respond_to(:success)
end
end
describe ".T" do
it "loads template from absolute path" do
mod = template(:a)
expect(Engine).to receive(:template).with('other')
mod.T('other')
end
end
describe ".find_file" do
it "finds file in the module's full_path" do
expect(File).to receive(:file?).with('/full/path/a/basename').and_return(false)
expect(File).to receive(:file?).with('/full/path/b/basename').and_return(true)
expect(template(:a).find_file('basename')).to eq '/full/path/b/basename'
end
it "returns nil if no file is found" do
expect(File).to receive(:file?).with('/full/path/a/basename').and_return(false)
expect(File).to receive(:file?).with('/full/path/b/basename').and_return(false)
expect(template(:a).find_file('basename')).to be nil
end
end
describe ".find_nth_file" do
it "finds 2nd existing file in template paths" do
expect(File).to receive(:file?).with('/full/path/a/basename').and_return(true)
expect(File).to receive(:file?).with('/full/path/b/basename').and_return(true)
expect(template(:a).find_nth_file('basename', 2)).to eq '/full/path/b/basename'
end
it "returns nil if no file is found" do
expect(File).to receive(:file?).with('/full/path/a/basename').and_return(true)
expect(File).to receive(:file?).with('/full/path/b/basename').and_return(true)
expect(template(:a).find_nth_file('basename', 3)).to be nil
end
end
describe ".extra_includes" do
it "is included when a module is initialized" do
module MyModule; end
Template.extra_includes << MyModule
expect(template(:e).new).to be_kind_of(MyModule)
end
it "supports lambdas in list" do
module MyModule2; end
Template.extra_includes << lambda {|opts| MyModule2 if opts.format == :html }
expect(template(:f).new(:format => :html)).to be_kind_of(MyModule2)
metaclass = (class << template(:g).new(:format => :text); self end)
expect(metaclass.ancestors).not_to include(MyModule2)
end
end
describe ".is_a?" do
it "is kind of Template" do
expect(template(:e).is_a?(Template)).to be true
end
end
describe "#T" do
it "delegates to class method" do
expect(template(:e)).to receive(:T).with('test')
template(:e).new.T('test')
end
end
describe "#init" do
it "is called during initialization" do
module YARD::Templates::Engine::Template__full_path_e # rubocop:disable Style/ClassAndModuleCamelCase
def init; sections 1, 2, 3 end
end
expect(template(:e).new.sections).to eq Section.new(nil, 1, 2, 3)
end
end
describe "#file" do
it "reads the file if it exists" do
expect(File).to receive(:file?).with('/full/path/e/abc').and_return(true)
expect(IO).to receive(:read).with('/full/path/e/abc').and_return('hello world')
expect(template(:e).new.file('abc')).to eq 'hello world'
end
it "raises ArgumentError if the file does not exist" do
expect(File).to receive(:file?).with('/full/path/e/abc').and_return(false)
expect { template(:e).new.file('abc') }.to raise_error(ArgumentError)
end
it "replaces {{{__super__}}} with inherited template contents if allow_inherited=true" do
expect(File).to receive(:file?).with('/full/path/a/abc').twice.and_return(true)
expect(File).to receive(:file?).with('/full/path/b/abc').and_return(true)
expect(IO).to receive(:read).with('/full/path/a/abc').and_return(String.new('foo {{{__super__}}}'))
expect(IO).to receive(:read).with('/full/path/b/abc').and_return(String.new('bar'))
expect(template(:a).new.file('abc', true)).to eq "foo bar"
end
it "does not replace {{{__super__}}} with inherited template contents if allow_inherited=false" do
expect(File).to receive(:file?).with('/full/path/a/abc').and_return(true)
expect(IO).to receive(:read).with('/full/path/a/abc').and_return('foo {{{__super__}}}')
expect(template(:a).new.file('abc')).to eq "foo {{{__super__}}}"
end
end
describe "#superb" do
it "returns the inherited erb template contents" do
expect(File).to receive(:file?).with('/full/path/a/test.erb').and_return(true)
expect(File).to receive(:file?).with('/full/path/b/test.erb').and_return(true)
expect(IO).to receive(:read).with('/full/path/b/test.erb').and_return('bar')
template = template(:a).new
template.section = :test
expect(template.superb).to eq "bar"
end
it "works inside an erb template" do
expect(File).to receive(:file?).with('/full/path/a/test.erb').twice.and_return(true)
expect(File).to receive(:file?).with('/full/path/b/test.erb').and_return(true)
expect(IO).to receive(:read).with('/full/path/a/test.erb').and_return('foo<%= superb %>!')
expect(IO).to receive(:read).with('/full/path/b/test.erb').and_return('bar')
template = template(:a).new
template.section = :test
expect(template.erb(:test)).to eq "foobar!"
end
end
describe "#sections" do
it "allows sections to be set if arguments are provided" do
mod = template(:e).new
mod.sections 1, 2, [3]
expect(mod.sections).to eq Section.new(nil, 1, 2, [3])
end
end
describe "#run" do
it "renders all sections" do
mod = template(:e).new
allow(mod).to receive(:render_section) {|section| section.name.to_s }
mod.sections :a, :b, :c
expect(mod.run).to eq 'abc'
end
it "renders all sections with options" do
mod = template(:e).new
allow(mod).to receive(:render_section) {|section| section.name.to_s }
expect(mod).to receive(:add_options).with(:a => 1).and_yield
mod.sections :a
expect(mod.run(:a => 1)).to eq 'a'
end
it "runs section list if provided" do
mod = template(:e).new
expect(mod).to receive(:render_section).exactly(2).times do |section|
expect([:q, :x]).to include(section.name)
section.name.to_s
end
mod.run({}, [:q, :x])
end
it "accepts a nil section as empty string" do
mod = template(:e).new
allow(mod).to receive(:render_section) { nil }
mod.sections :a
expect(mod.run).to eq ""
end
end
describe "#add_options" do
it "sets instance variables in addition to options" do
mod = template(:f).new
mod.send(:add_options, :a => 1, :b => 2)
expect(mod.options).to eq(:a => 1, :b => 2)
expect(mod.instance_variable_get("@a")).to eq 1
expect(mod.instance_variable_get("@b")).to eq 2
end
it "sets instance variables and options only for the block" do
mod = template(:f).new
mod.send(:add_options, :a => 100, :b => 200) do
expect(mod.options).to eq(:a => 100, :b => 200)
end
expect(mod.options).not_to eq(:a => 100, :b => 200)
end
end
describe "#render_section" do
it "calls method if method exists by section name as Symbol" do
mod = template(:f).new
expect(mod).to receive(:respond_to?).with(:a).and_return(true)
expect(mod).to receive(:respond_to?).with('a').and_return(true)
expect(mod).to receive(:send).with(:a).and_return('a')
expect(mod).to receive(:send).with('a').and_return('a')
expect(mod.run({}, [:a, 'a'])).to eq 'aa'
end
it "calls erb if no method exists by section name" do
mod = template(:f).new
expect(mod).to receive(:respond_to?).with(:a).and_return(false)
expect(mod).to receive(:respond_to?).with('a').and_return(false)
expect(mod).to receive(:erb).with(:a).and_return('a')
expect(mod).to receive(:erb).with('a').and_return('a')
expect(mod.run({}, [:a, 'a'])).to eq 'aa'
end
it "runs a template if section is one" do
mod2 = template(:g)
expect(mod2).to receive(:run)
mod = template(:f).new
mod.sections mod2
mod.run
end
it "runs a template instance if section is one" do
mod2 = template(:g).new
expect(mod2).to receive(:run)
mod = template(:f).new
mod.sections mod2
mod.run
end
end
describe "#yield" do
it "yields a subsection" do
mod = template(:e).new
mod.sections :a, [:b, :c]
class << mod
def a; "(" + yield + ")" end
def b; "b" end
def c; "c" end
end
expect(mod.run).to eq "(b)"
end
it "yields a subsection within a yielded subsection" do
mod = template(:e).new
mod.sections :a, [:b, [:c]]
class << mod
def a; "(" + yield + ")" end
def b; yield end
def c; "c" end
end
expect(mod.run).to eq "(c)"
end
it "supports arbitrary nesting" do
mod = template(:e).new
mod.sections :a, [:b, [:c, [:d, [:e]]]]
class << mod
def a; "(" + yield + ")" end
def b; yield end
def c; yield end
def d; yield end
def e; "e" end
end
expect(mod.run).to eq "(e)"
end
it "yields first two elements if yield is called twice" do
mod = template(:e).new
mod.sections :a, [:b, :c, :d]
class << mod
def a; "(" + yield + yield + ")" end
def b; 'b' end
def c; "c" end
end
expect(mod.run).to eq "(bc)"
end
it "ignores any subsections inside subsection yields" do
mod = template(:e).new
mod.sections :a, [:b, [:c], :d]
class << mod
def a; "(" + yield + yield + ")" end
def b; 'b' end
def d; "d" end
end
expect(mod.run).to eq "(bd)"
end
it "allows extra options passed via yield" do
mod = template(:e).new
mod.sections :a, [:b]
class << mod
def a; "(" + yield(:x => "a") + ")" end
def b; options.x + @x end
end
expect(mod.run).to eq "(aa)"
end
end
describe "#yieldall" do
it "yields all subsections" do
mod = template(:e).new
mod.sections :a, [:b, [:d, [:e]], :c]
class << mod
def a; "(" + yieldall + ")" end
def b; "b" + yieldall end
def c; "c" end
def d; 'd' + yieldall end
def e; 'e' end
end
expect(mod.run).to eq "(bdec)"
end
it "yields options to all subsections" do
mod = template(:e).new
mod.sections :a, [:b, :c]
class << mod
def a; "(" + yieldall(:x => "2") + ")" end
def b; @x end
def c; @x end
end
expect(mod.run).to eq "(22)"
end
it "yields all subsections more than once" do
mod = template(:e).new
mod.sections :a, [:b]
class << mod
def a; "(" + yieldall + yieldall + ")" end
def b; "b" end
end
expect(mod.run).to eq "(bb)"
end
it "does not yield if no yieldall is called" do
mod = template(:e).new
mod.sections :a, [:b]
class << mod
def a; "()" end
def b; "b" end
end
expect(mod.run).to eq "()"
end
end
end
yard-0.9.7/spec/templates/engine_spec.rb 0000644 0000041 0000041 00000011432 13035234564 020260 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Templates::Engine do
before { @paths = Engine.template_paths }
after { Engine.template_paths = @paths }
describe ".register_template_path" do
it "registers a String path" do
Engine.register_template_path('.')
expect(Engine.template_paths.pop).to eq '.'
end
it "does not duplicate paths" do
Engine.template_paths = []
Engine.register_template_path('foo')
Engine.register_template_path('foo')
expect(Engine.template_paths).to eq ['foo']
end
end
describe ".template!" do
it "creates a module including Template" do
mod = Engine.template!('path/to/template')
expect(mod).to include(Template)
expect(mod.full_path.to_s).to eq 'path/to/template'
end
it "creates a module including Template with full_path" do
mod = Engine.template!('path/to/template2', '/full/path/to/template2')
expect(mod).to include(Template)
expect(mod.full_path.to_s).to eq '/full/path/to/template2'
end
end
describe ".template" do
it "raises an error if the template is not found" do
expect { Engine.template(:a, :b, :c) }.to raise_error(ArgumentError)
end
it "creates a module including Template" do
mock = double(:template)
expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(['/full/path/template/name'])
expect(Engine).to receive(:template!).with('template/name', ['/full/path/template/name']).and_return(mock)
expect(Engine.template('template/name')).to eq mock
end
it "creates a Template from a relative Template path" do
expect(Engine).to receive(:template_paths).and_return([])
expect(File).to receive(:directory?).with("/full/path/template/notname").and_return(true)
start_template = double(:start_template,
:full_path => '/full/path/template/name',
:full_paths => ['/full/path/template/name'])
expect(start_template).to receive(:is_a?).with(Template).and_return(true)
mod = Engine.template(start_template, '..', 'notname')
expect(mod).to include(Template)
expect(mod.full_path.to_s).to eq "/full/path/template/notname"
end
it "creates a Template including other matching templates in path" do
paths = ['/full/path/template/name', '/full/path2/template/name']
expect(Engine).to receive(:find_template_paths).with(nil, 'template').at_least(1).times.and_return([])
expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(paths)
ancestors = Engine.template('template/name').ancestors.map(&:class_name)
expect(ancestors).to include("Template__full_path2_template_name")
end
it "includes parent directories before other template paths" do
paths = ['/full/path/template/name', '/full/path2/template/name']
expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(paths)
ancestors = Engine.template('template/name').ancestors.map(&:class_name)
expect(ancestors[0, 4]).to eq ["Template__full_path_template_name", "Template__full_path_template",
"Template__full_path2_template_name", "Template__full_path2_template"]
end
end
describe ".generate" do
it "generates with fulldoc template" do
mod = double(:template)
options = TemplateOptions.new
options.reset_defaults
options.objects = [:a, :b, :c]
options.object = Registry.root
expect(mod).to receive(:run).with(options)
expect(Engine).to receive(:template).with(:default, :fulldoc, :text).and_return(mod)
Engine.generate([:a, :b, :c])
end
end
describe ".render" do
def loads_template(*args)
expect(Engine).to receive(:template).with(*args).and_return(@template)
end
before(:all) do
@object = CodeObjects::MethodObject.new(:root, :method)
end
before do
@options = TemplateOptions.new
@options.reset_defaults
@options.object = @object
@options.type = @object.type
@template = double(:template, :include => nil)
expect(@template).to receive(:run).with(@options)
end
it "accepts method call with no parameters" do
loads_template(:default, :method, :text)
@object.format
end
it "allows template key to be changed" do
loads_template(:javadoc, :method, :text)
@options.template = :javadoc
@object.format(:template => :javadoc)
end
it "allows type key to be changed" do
loads_template(:default, :fulldoc, :text)
@options.type = :fulldoc
@object.format(:type => :fulldoc)
end
it "allows format key to be changed" do
loads_template(:default, :method, :html)
@options.format = :html
@object.format(:format => :html)
end
end
end
yard-0.9.7/spec/templates/tag_spec.rb 0000644 0000041 0000041 00000002660 13035234564 017571 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Templates::Engine.template(:default, :tags) do
before { Registry.clear }
describe "all known tags" do
before do
YARD.parse_string <<-'eof'
# Comments
# @abstract override me
# @param [Hash] opts the options
# @option opts :key ('') hello
# @option opts :key2 (X) hello
# @return [String] the result
# @raise [Exception] Exception class
# @deprecated for great justice
# @see A
# @see http://url.com
# @see http://url.com Example
# @author Name
# @since 1.0
# @version 1.0
# @yield a block
# @yieldparam [String] a a value
# @yieldreturn [Hash] a hash
# @example Wash your car
# car.wash
# @example To kill a mockingbird
# a = String.new
# flip(a.reverse)
def m(opts = {}) end
eof
end
it "renders text format correctly" do
text_equals(Registry.at('#m').format(text_options), :tag001)
end
end
describe "param tags on non-methods" do
it "does not display @param tags on non-method objects" do
YARD.parse_string <<-'eof'
# @param [#to_s] name the name
module Foo; end
eof
proc = lambda { Registry.at('Foo').format(html_options) }
expect(proc).not_to raise_error
end
end
end
yard-0.9.7/spec/rubygems/ 0000755 0000041 0000041 00000000000 13035234564 015312 5 ustar www-data www-data yard-0.9.7/spec/rubygems/doc_manager_spec.rb 0000644 0000041 0000041 00000007344 13035234564 021120 0 ustar www-data www-data # frozen_string_literal: true
require File.join(YARD::ROOT, 'rubygems_plugin')
require 'fileutils'
RSpec.describe Gem::DocManager do
before do
# Ensure filesystem integrity
allow(FileUtils).to receive(:mkdir_p)
allow(FileUtils).to receive(:rm_rf)
allow(Dir).to receive(:chdir)
allow(YARD::CLI::Yardoc).to receive(:run)
@spec_file = File.join(YARD::ROOT, '..', 'yard.gemspec')
@spec = Gem::SourceIndex.load_specification(@spec_file)
@spec.has_yardoc = false # no yardoc docs for now
@yardopts = File.join(@spec.full_gem_path, '.yardopts')
@doc = Gem::DocManager.new(@spec)
allow(@doc).to receive(:install_ri_yard_orig)
allow(@doc).to receive(:install_rdoc_yard_orig)
end
def runs; expect(YARD::CLI::Yardoc).to receive(:run) end
describe ".load_yardoc" do
it "properly loads YARD" do
expect(Gem::DocManager).to receive(:require) do |path|
expect(File.expand_path(path)).to eq YARD::ROOT + '/yard'
end
Gem::DocManager.load_yardoc
end
end
describe "#install_ri_yard" do
def install
msg = "Building YARD (yri) index for #{@spec.full_name}..."
expect(@doc).to receive(:say).with(msg)
@doc.install_ri_yard
end
it "passes --quiet to all documentation" do
runs.with('-c', '-n', '--quiet', 'lib')
install
end
it "passes extra_rdoc_files to documentation" do
@spec.extra_rdoc_files = %w(README LICENSE)
runs.with('-c', '-n', '--quiet', 'lib', '-', 'README', 'LICENSE')
install
end
it "adds --backtrace if Gem.configuration.backtrace" do
Gem.configuration.backtrace = true
runs.with('-c', '-n', '--quiet', '--backtrace', 'lib')
install
Gem.configuration.backtrace = false
end
it "adds require_paths if there is no .yardopts" do
expect(File).to receive(:file?).with(@yardopts).and_return(true)
runs.with('-c', '-n', '--quiet')
install
end
it "adds extra_rdoc_files if there is no .yardopts" do
@spec.extra_rdoc_files = %w(README LICENSE)
expect(File).to receive(:file?).with(@yardopts).and_return(true)
runs.with('-c', '-n', '--quiet')
install
end
it "switches to directory before running command" do
old = Dir.pwd
expect(Dir).to receive(:chdir).with(@spec.full_gem_path)
expect(Dir).to receive(:chdir).with(old)
install
end
it "ensures that directory is switched back at end of command in failure" do
old = Dir.pwd
expect(Dir).to receive(:chdir).with(@spec.full_gem_path)
expect(Dir).to receive(:chdir).with(old)
expect(@doc.ui.errs).to receive(:puts).with(/ERROR:\s*While generating documentation/)
expect(@doc.ui.errs).to receive(:puts).with(/MESSAGE:\s*foo/)
expect(@doc.ui.errs).to receive(:puts).with(/YARDOC args:\s*-c -n --quiet lib/)
expect(@doc.ui.errs).to receive(:puts).with("(continuing with the rest of the installation)")
expect(YARD::CLI::Yardoc).to receive(:run).and_raise(RuntimeError.new("foo"))
install
end
it "handles permission errors" do
expect(YARD::CLI::Yardoc).to receive(:run).and_raise(Errno::EACCES.new("- dir"))
expect { install }.to raise_error(Gem::FilePermissionError)
end
end
describe "#install_rdoc_yard" do
def install
msg = "Installing YARD documentation for #{@spec.full_name}..."
expect(@doc).to receive(:say).with(msg)
@doc.install_rdoc_yard
end
it "adds -o outdir when generating docs" do
expect(File).to receive(:file?).with(@yardopts).and_return(true)
@spec.has_yardoc = true
doc_dir = File.join(@doc.instance_variable_get("@doc_dir"), 'rdoc')
runs.with('-o', doc_dir, '--quiet')
install
end
end
end if Gem::VERSION < '2.0.0'
yard-0.9.7/spec/rake/ 0000755 0000041 0000041 00000000000 13035234564 014377 5 ustar www-data www-data yard-0.9.7/spec/rake/yardoc_task_spec.rb 0000644 0000041 0000041 00000006130 13035234564 020241 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Rake::YardocTask do
before do
@yardoc = YARD::CLI::Yardoc.new
@yardoc.statistics = false
@yardoc.use_document_file = false
@yardoc.use_yardopts_file = false
@yardoc.generate = false
allow(Templates::Engine).to receive(:render)
allow(Templates::Engine).to receive(:generate)
allow(YARD).to receive(:parse)
allow(Registry).to receive(:load)
allow(Registry).to receive(:save)
allow(YARD::CLI::Yardoc).to receive(:new).and_return(@yardoc)
::Rake.application.clear
end
def run
::Rake.application.tasks[0].invoke
end
describe "#initialize" do
it "allows separate rake task name to be set" do
YARD::Rake::YardocTask.new(:notyardoc)
expect(::Rake.application.tasks[0].name).to eq "notyardoc"
end
end
describe "#files" do
it "allows files to be set" do
YARD::Rake::YardocTask.new do |t|
t.files = ['a', 'b', 'c']
end
run
expect(@yardoc.files).to eq %w(a b c)
end
end
describe "#options" do
it "allows extra options to be set" do
YARD::Rake::YardocTask.new do |t|
t.options = ['--private', '--protected']
end
run
expect(@yardoc.visibilities).to eq [:public, :private, :protected]
end
it "allows --api and --no-api" do
YARD::Rake::YardocTask.new do |t|
t.options = %w(--api public --no-api)
end
run
expect(@yardoc.options.verifier.expressions).to include('["public"].include?(@api.text) || !@api')
end
end
describe "#stats_options" do
before do
@yard_stats = Object.new
allow(@yard_stats).to receive(:run)
allow(YARD::CLI::Stats).to receive(:new).and_return(@yard_stats)
end
it "invokes stats" do
expect(@yard_stats).to receive(:run).with('--list-undoc', '--use-cache')
@yardoc.statistics = true
YARD::Rake::YardocTask.new do |t|
t.stats_options = %w(--list-undoc)
end
run
expect(@yardoc.statistics).to be false
end
end
describe "#before" do
it "allows before callback" do
proc = lambda {}
expect(proc).to receive(:call)
expect(@yardoc).to receive(:run)
YARD::Rake::YardocTask.new {|t| t.before = proc }
run
end
end
describe "#after" do
it "allows after callback" do
proc = lambda {}
expect(proc).to receive(:call)
expect(@yardoc).to receive(:run)
YARD::Rake::YardocTask.new {|t| t.after = proc }
run
end
end
describe "#verifier" do
it "allows a verifier proc to be set" do
verifier = Verifier.new
expect(@yardoc).to receive(:run) do
expect(@yardoc.options[:verifier]).to eq verifier
end
YARD::Rake::YardocTask.new {|t| t.verifier = verifier }
run
end
it "overrides --query options" do
verifier = Verifier.new
expect(@yardoc).to receive(:run) do
expect(@yardoc.options[:verifier]).to eq verifier
end
YARD::Rake::YardocTask.new do |t|
t.options += ['--query', '@return']
t.verifier = verifier
end
run
end
end
end
yard-0.9.7/spec/docstring_spec.rb 0000644 0000041 0000041 00000027746 13035234564 017030 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Docstring do
before { YARD::Registry.clear }
describe "#initialize" do
it "handles docstrings with empty newlines" do
expect(Docstring.new("\n\n")).to eq ""
end
end
describe "#+" do
it "adds another Docstring" do
d = Docstring.new("FOO") + Docstring.new("BAR")
expect(d).to eq "FOO\nBAR"
end
it "copies over tags" do
d1 = Docstring.new("FOO\n@api private\n")
d2 = Docstring.new("BAR\n@param foo descr")
d = (d1 + d2)
expect(d).to have_tag(:api)
expect(d).to have_tag(:param)
end
it "adds a String" do
d = Docstring.new("FOO") + "BAR"
expect(d).to eq "FOOBAR"
end
end
describe "#line" do
it "returns nil if #line_range is not set" do
expect(Docstring.new('foo').line).to be nil
end
it "returns line_range.first if #line_range is set" do
doc = Docstring.new('foo')
doc.line_range = (1..10)
expect(doc.line).to eq doc.line_range.first
end
end
describe "#summary" do
it "handles empty docstrings" do
o1 = Docstring.new
expect(o1.summary).to eq ""
end
it "handles multiple calls" do
o1 = Docstring.new("Hello. world")
5.times { expect(o1.summary).to eq "Hello." }
end
it "strips newlines in first paragraph before summarizing" do
doc = Docstring.new("Foo\n== bar.")
expect(doc.summary).to eq 'Foo == bar.'
end
it "returns the first sentence" do
o = Docstring.new("DOCSTRING. Another sentence")
expect(o.summary).to eq "DOCSTRING."
end
it "returns the first paragraph" do
o = Docstring.new("DOCSTRING, and other stuff\n\nAnother sentence.")
expect(o.summary).to eq "DOCSTRING, and other stuff."
end
it "returns proper summary when docstring is changed" do
o = Docstring.new "DOCSTRING, and other stuff\n\nAnother sentence."
expect(o.summary).to eq "DOCSTRING, and other stuff."
o = Docstring.new "DOCSTRING."
expect(o.summary).to eq "DOCSTRING."
end
it "does not double the ending period" do
o = Docstring.new("Returns a list of tags specified by +name+ or all tags if +name+ is not specified.\n\nTest")
expect(o.summary).to eq "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
doc = Docstring.new(<<-eof)
Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
@param name the tag name to return data for, or nil for all tags
@return [Array] the list of tags by the specified tag name
eof
expect(doc.summary).to eq "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
end
it "does not attach period if entire summary is include" do
YARD.parse_string "# docstring\ndef foo; end"
expect(Docstring.new("{include:#foo}").summary).to eq '{include:#foo}'
Registry.clear
end
it "handles references embedded in summary" do
expect(Docstring.new("Aliasing {Test.test}. Done.").summary).to eq "Aliasing {Test.test}."
end
it "only ends first sentence when outside parentheses" do
expect(Docstring.new("Hello (the best.) world. Foo bar.").summary).to eq "Hello (the best.) world."
expect(Docstring.new("A[b.]c.").summary).to eq "A[b.]c."
end
it "only sees '.' as period if whitespace (or eof) follows" do
expect(Docstring.new("hello 1.5 times.").summary).to eq "hello 1.5 times."
expect(Docstring.new("hello... me").summary).to eq "hello..."
expect(Docstring.new("hello.").summary).to eq "hello."
end
it "returns summary if there is a newline and parentheses count doesn't match" do
expect(Docstring.new("Happy method call :-)\n\nCall any time.").summary).to eq "Happy method call :-)."
expect(Docstring.new("Sad method call :-(\n\nCall any time.").summary).to eq "Sad method call :-(."
expect(Docstring.new("Hello (World. Forget to close.\n\nNew text").summary).to eq "Hello (World. Forget to close."
expect(Docstring.new("Hello (World. Forget to close\n\nNew text").summary).to eq "Hello (World. Forget to close."
end
end
describe "#ref_tags" do
it "parses reference tag into ref_tags" do
doc = Docstring.new("@return (see Foo#bar)")
expect(doc.ref_tags.size).to eq 1
expect(doc.ref_tags.first.owner).to eq P("Foo#bar")
expect(doc.ref_tags.first.tag_name).to eq "return"
expect(doc.ref_tags.first.name).to be nil
end
it "parses named reference tag into ref_tags" do
doc = Docstring.new("@param blah \n (see Foo#bar )")
expect(doc.ref_tags.size).to eq 1
expect(doc.ref_tags.first.owner).to eq P("Foo#bar")
expect(doc.ref_tags.first.tag_name).to eq "param"
expect(doc.ref_tags.first.name).to eq "blah"
end
it "fails to parse named reference tag into ref_tags" do
doc = Docstring.new("@param blah THIS_BREAKS_REFTAG (see Foo#bar)")
expect(doc.ref_tags.size).to eq 0
end
it "returns all valid reference tags along with #tags" do
o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
o.docstring.add_tag Tags::Tag.new('return', 'testing')
doc = Docstring.new("@return (see Foo#bar)")
tags = doc.tags
expect(tags.size).to eq 1
expect(tags.first.text).to eq 'testing'
expect(tags.first).to be_kind_of(Tags::RefTag)
expect(tags.first.owner).to eq o
end
it "returns all valid named reference tags along with #tags(name)" do
o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
o.docstring.add_tag Tags::Tag.new('param', 'testing', nil, '*args')
o.docstring.add_tag Tags::Tag.new('param', 'NOTtesting', nil, 'notargs')
doc = Docstring.new("@param *args (see Foo#bar)")
tags = doc.tags('param')
expect(tags.size).to eq 1
expect(tags.first.text).to eq 'testing'
expect(tags.first).to be_kind_of(Tags::RefTag)
expect(tags.first.owner).to eq o
end
it "ignores invalid reference tags" do
doc = Docstring.new("@param *args (see INVALID::TAG#tag)")
tags = doc.tags('param')
expect(tags.size).to eq 0
end
it "resolves references to methods in the same class with #methname" do
klass = CodeObjects::ClassObject.new(:root, "Foo")
o = CodeObjects::MethodObject.new(klass, "bar")
ref = CodeObjects::MethodObject.new(klass, "baz")
o.docstring.add_tag Tags::Tag.new('param', 'testing', nil, 'arg1')
ref.docstring = "@param (see #bar)"
tags = ref.docstring.tags("param")
expect(tags.size).to eq 1
expect(tags.first.text).to eq "testing"
expect(tags.first).to be_kind_of(Tags::RefTag)
expect(tags.first.owner).to eq o
end
it "returns an empty list (and warning) if circular reftags are found" do
YARD.parse_string <<-eof
class Foo
# @param (see #b)
def a; end
# @param (see #a)
def b; end
end
eof
expect(log.io.string).to match(/error.*circular reference tag in `Foo#b'/)
expect(Registry.at('Foo#a').tags).to be_empty
expect(Registry.at('Foo#b').tags).to be_empty
end
it "returns an empty list (and warning) if self-circular reftags are found" do
YARD.parse_string <<-eof
class Foo
# @param (see #bar)
def bar; end
end
eof
expect(log.io.string).to match(/error.*circular reference tag in `Foo#bar'/)
expect(Registry.at('Foo#bar').tags).to be_empty
end
end
describe "#empty?/#blank?" do
before(:all) do
Tags::Library.define_tag "Invisible", :invisible_tag
end
it "is blank and empty if it has no content and no tags" do
expect(Docstring.new).to be_blank
expect(Docstring.new).to be_empty
end
it "isn't empty or blank if it has content" do
d = Docstring.new("foo bar")
expect(d).not_to be_empty
expect(d).not_to be_blank
end
it "is empty but not blank if it has tags" do
d = Docstring.new("@param foo")
expect(d).to be_empty
expect(d).not_to be_blank
end
it "is empty but not blank if it has ref tags" do
o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
o.docstring.add_tag Tags::Tag.new('return', 'testing')
d = Docstring.new("@return (see Foo#bar)")
expect(d).to be_empty
expect(d).not_to be_blank
end
it "is blank if it has no visible tags" do
d = Docstring.new("@invisible_tag value")
expect(d).to be_blank
end
it "is not blank if it has invisible tags and only_visible_tags = false" do
d = Docstring.new("@invisible_tag value")
d.add_tag Tags::Tag.new('invisible_tag', nil, nil)
expect(d.blank?(false)).to be false
end
end
describe "#delete_tags" do
it "deletes tags by a given tag name" do
doc = Docstring.new("@param name x\n@param name2 y\n@return foo")
doc.delete_tags(:param)
expect(doc.tags.size).to eq 1
end
end
describe "#delete_tag_if" do
it "deletes tags for a given block" do
doc = Docstring.new("@param name x\n@param name2 y\n@return foo")
doc.delete_tag_if {|t| t.name == 'name2' }
expect(doc.tags.size).to eq 2
end
end
describe "#to_raw" do
it "returns a clean representation of tags" do
doc = Docstring.new("Hello world\n@return [String, X] foobar\n@param name the name\nBYE!")
expect(doc.to_raw).to eq "Hello world\nBYE!\n@param [Array] name\n the name\n@return [String, X] foobar"
end
it "handles tags with newlines and indentation" do
doc = Docstring.new("@example TITLE\n the \n example\n @foo\n@param [X] name\n the name")
expect(doc.to_raw).to eq "@example TITLE\n the \n example\n @foo\n@param [X] name\n the name"
end
it "handles deleted tags" do
doc = Docstring.new("@example TITLE\n the \n example\n @foo\n@param [X] name\n the name")
doc.delete_tags(:param)
expect(doc.to_raw).to eq "@example TITLE\n the \n example\n @foo"
end
it "handles added tags" do
doc = Docstring.new("@example TITLE\n the \n example\n @foo")
doc.add_tag(Tags::Tag.new('foo', 'foo'))
expect(doc.to_raw).to eq "@example TITLE\n the \n example\n @foo\n@foo foo"
end
it "is equal to .all if not modified" do
doc = Docstring.new("123\n@param")
expect(doc.to_raw).to eq doc.all
end
# @bug gh-563
it "handles full @option tags" do
doc = Docstring.new("@option foo [String] bar (nil) baz")
expect(doc.to_raw).to eq "@option foo [String] bar (nil) baz"
end
# @bug gh-563
it "handles simple @option tags" do
doc = Docstring.new("@option foo :key bar")
expect(doc.to_raw).to eq "@option foo :key bar"
end
end
describe "#dup" do
it "duplicates docstring text" do
doc = Docstring.new("foo")
expect(doc.dup).to eq doc
expect(doc.dup.all).to eq doc
end
it "duplicates tags to new list" do
doc = Docstring.new("@param x\n@return y")
doc2 = doc.dup
doc2.delete_tags(:param)
expect(doc.tags.size).to eq 2
expect(doc2.tags.size).to eq 1
end
it "preserves summary" do
doc = Docstring.new("foo. bar")
expect(doc.dup.summary).to eq doc.summary
end
it "preserves hash_flag" do
doc = Docstring.new
doc.hash_flag = 'foo'
expect(doc.dup.hash_flag).to eq doc.hash_flag
end
it "preserves line_range" do
doc = Docstring.new
doc.line_range = (1..2)
expect(doc.dup.line_range).to eq doc.line_range
end
end
describe "reference docstrings" do
it "allows for construction of docstring with ref object" do
YARD.parse_string <<-eof
class A
# Docstring
# @return [Boolean]
def a; end
# (see #a)
def b; end
end
eof
object = YARD::Registry.at('A#b')
expect(object.docstring).to eq 'Docstring'
expect(object.tags.map(&:tag_name)).to eq ['return']
YARD::Registry.clear
end
end
end
yard-0.9.7/spec/options_spec.rb 0000644 0000041 0000041 00000011141 13035234564 016505 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Options do
class FooOptions < YARD::Options
attr_accessor :foo
def initialize; self.foo = "abc" end
end
describe ".default_attr" do
it "allows default attributes to be defined with symbols" do
class DefaultOptions1 < YARD::Options
default_attr :foo, 'HELLO'
end
o = DefaultOptions1.new
o.reset_defaults
expect(o.foo).to eq 'HELLO'
end
it "calls lambda if value is a Proc" do
class DefaultOptions2 < YARD::Options
default_attr :foo, lambda { 100 }
end
o = DefaultOptions2.new
o.reset_defaults
expect(o.foo).to eq 100
end
end
describe "#reset_defaults" do
it "does not define defaults until reset is called" do
class ResetDefaultOptions1 < YARD::Options
default_attr :foo, 'FOO'
end
expect(ResetDefaultOptions1.new.foo).to be nil
o = ResetDefaultOptions1.new
o.reset_defaults
expect(o.foo).to eq 'FOO'
end
it "uses defaults from superclass as well" do
class ResetDefaultOptions2 < YARD::Options
default_attr :foo, 'FOO'
end
class ResetDefaultOptions3 < ResetDefaultOptions2
end
o = ResetDefaultOptions3.new
o.reset_defaults
expect(o.foo).to eq 'FOO'
end
end
describe "#delete" do
it "deletes an option" do
o = FooOptions.new
o.delete(:foo)
expect(o.to_hash).to eq({})
end
it "does not error if an option is deleted that does not exist" do
o = FooOptions.new
o.delete(:foo)
o.delete(:foo)
expect(o.to_hash).to eq({})
end
end
describe "#[]" do
it "handles getting option values using hash syntax" do
expect(FooOptions.new[:foo]).to eq "abc"
end
end
describe "#[]=" do
it "handles setting options using hash syntax" do
o = FooOptions.new
o[:foo] = "xyz"
expect(o[:foo]).to eq "xyz"
end
it "allows setting of unregistered keys" do
o = FooOptions.new
o[:bar] = "foo"
expect(o[:bar]).to eq "foo"
end
end
describe "#method_missing" do
it "allows setting of unregistered keys" do
o = FooOptions.new
o.bar = 'foo'
expect(o.bar).to eq 'foo'
end
it "allows getting values of unregistered keys (return nil)" do
expect(FooOptions.new.bar).to be nil
end
it "prints debugging messages about unregistered keys" do
expect(log).to receive(:debug).with("Attempting to access unregistered key bar on FooOptions")
FooOptions.new.bar
expect(log).to receive(:debug).with("Attempting to set unregistered key bar on FooOptions")
FooOptions.new.bar = 1
end
end
describe "#update" do
it "allows updating of options" do
expect(FooOptions.new.update(:foo => "xyz").foo).to eq "xyz"
end
it "does not ignore keys with no setter (OpenStruct behaviour)" do
o = FooOptions.new
o.update(:bar => "xyz")
expect(o.to_hash).to eq(:foo => "abc", :bar => "xyz")
end
end
describe "#merge" do
it "updates a new object" do
o = FooOptions.new
expect(o.merge(:foo => "xyz").object_id).not_to eq o.object_id
expect(o.merge(:foo => "xyz").to_hash).to eq(:foo => "xyz")
end
it "adds in values from original object" do
o = FooOptions.new
o.update(:bar => "foo")
expect(o.merge(:baz => 1).to_hash).to eq(:foo => "abc", :bar => "foo", :baz => 1)
end
end
describe "#to_hash" do
it "converts all instance variables and symbolized keys" do
class ToHashOptions1 < YARD::Options
attr_accessor :foo, :bar, :baz
def initialize; @foo = 1; @bar = 2; @baz = "hello" end
end
o = ToHashOptions1.new
hash = o.to_hash
expect(hash.keys).to include(:foo, :bar, :baz)
expect(hash[:foo]).to eq 1
expect(hash[:bar]).to eq 2
expect(hash[:baz]).to eq "hello"
end
it "uses accessor when converting values to hash" do
class ToHashOptions2 < YARD::Options
def initialize; @foo = 1 end
def foo; "HELLO#{@foo}" end
end
o = ToHashOptions2.new
expect(o.to_hash).to eq(:foo => "HELLO1")
end
it "ignores ivars with no accessor" do
class ToHashOptions3 < YARD::Options
attr_accessor :foo
def initialize; @foo = 1; @bar = "NOIGNORE" end
end
o = ToHashOptions3.new
expect(o.to_hash).to eq(:foo => 1, :bar => "NOIGNORE")
end
end
describe "#tap" do
it "supports #tap(&block) (even in 1.8.6)" do
o = FooOptions.new.tap {|obj| obj.foo = :BAR }
expect(o.to_hash).to eq(:foo => :BAR)
end
end
end
yard-0.9.7/spec/server/ 0000755 0000041 0000041 00000000000 13035234564 014763 5 ustar www-data www-data yard-0.9.7/spec/server/adapter_spec.rb 0000644 0000041 0000041 00000002201 13035234564 017735 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Server::Adapter do
after(:all) { Server::Adapter.shutdown }
describe "#add_library" do
it "adds a library" do
lib = LibraryVersion.new('yard')
a = Adapter.new({})
expect(a.libraries).to be_empty
a.add_library(lib)
expect(a.libraries['yard']).to eq [lib]
end
end
describe "#start" do
it "does not implement #start" do
expect { Adapter.new({}).start }.to raise_error(NotImplementedError)
end
end
describe ".setup" do
it "adds template paths and helpers" do
Adapter.setup
expect(Templates::Template.extra_includes).to include(DocServerHelper)
expect(Templates::Engine.template_paths).to include(YARD::ROOT + '/yard/server/templates')
end
end
describe ".shutdown" do
it "cleans up template paths and helpers" do
Adapter.setup
Adapter.shutdown
expect(Templates::Template.extra_includes).not_to include(DocServerHelper)
expect(Templates::Engine.template_paths).not_to include(YARD::ROOT + '/yard/server/templates')
end
end
end
yard-0.9.7/spec/server/commands/ 0000755 0000041 0000041 00000000000 13035234564 016564 5 ustar www-data www-data yard-0.9.7/spec/server/commands/library_command_spec.rb 0000644 0000041 0000041 00000002034 13035234564 023264 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
RSpec.describe YARD::Server::Commands::LibraryCommand do
before do
allow(Templates::Engine).to receive(:render)
allow(Templates::Engine).to receive(:generate)
allow(YARD).to receive(:parse)
allow(Registry).to receive(:load)
allow(Registry).to receive(:save)
@cmd = LibraryCommand.new(:adapter => mock_adapter)
@request = mock_request("/foo", :xhr? => false)
@library = OpenStruct.new(:source_path => '.')
@cmd.library = @library
allow(@cmd).to receive(:load_yardoc).and_return(nil)
end
def call
expect { @cmd.call(@request) }.to raise_error(NotImplementedError)
end
describe "#call" do
it "raises NotImplementedError" do
call
end
it "sets :rdoc as the default markup in incremental mode" do
@cmd.incremental = true
call
expect(@cmd.options[:markup]).to eq :rdoc
end
it "sets :rdoc as the default markup in regular mode" do
call
expect(@cmd.options[:markup]).to eq :rdoc
end
end
end
yard-0.9.7/spec/server/commands/base_spec.rb 0000644 0000041 0000041 00000005237 13035234564 021044 0 ustar www-data www-data # frozen_string_literal: true
class MyProcCommand < Base
def initialize(&block)
self.class.send(:undef_method, :run)
self.class.send(:define_method, :run, &block)
end
end
class MyCacheCommand < Base
def run; cache 'foo' end
end
RSpec.describe YARD::Server::Commands::Base do
describe "#cache" do
before do
@command = MyCacheCommand.new(:adapter => mock_adapter, :caching => true)
@command.request = mock_request(nil)
end
it "does not cache if caching == false" do
expect(File).not_to receive(:open)
@command.caching = false
@command.run
end
it "requires document root to cache" do
expect(File).not_to receive(:open)
@command.adapter.document_root = nil
@command.run
end
it "caches to path/to/file.html and create directories" do
expect(FileUtils).to receive(:mkdir_p).with('/public/path/to')
expect(File).to receive(:open).with('/public/path/to/file.html', anything)
@command.request.path_info = '/path/to/file.html'
@command.run
end
end
describe "#redirect" do
it "returns a valid redirection" do
cmd = MyProcCommand.new { redirect '/foo' }
expect(cmd.call(mock_request('/foo'))).to eq(
[302, {"Content-Type" => "text/html", "Location" => "/foo"}, [""]]
)
end
end
describe "#call" do
it "handles a NotFoundError and use message as body" do
cmd = MyProcCommand.new { raise NotFoundError, "hello world" }
s, _, b = *cmd.call(mock_request('/foo'))
expect(s).to eq 404
expect(b).to eq ["hello world"]
end
it "does not use message as body if not provided in NotFoundError" do
cmd = MyProcCommand.new { raise NotFoundError }
s, _, b = *cmd.call(mock_request('/foo'))
expect(s).to eq 404
expect(b).to eq ["Not found: /foo"]
end
it "handles 404 status code from #run" do
cmd = MyProcCommand.new { self.status = 404 }
s, _, b = *cmd.call(mock_request('/foo'))
expect(s).to eq 404
expect(b).to eq ["Not found: /foo"]
end
it "does not override body if status is 404 and body is defined" do
cmd = MyProcCommand.new { self.body = "foo"; self.status = 404 }
s, _, b = *cmd.call(mock_request('/bar'))
expect(s).to eq 404
expect(b).to eq ['foo']
end
it "handles body as Array" do
cmd = MyProcCommand.new { self.body = ['a', 'b', 'c'] }
_, _, b = *cmd.call(mock_request('/foo'))
expect(b).to eq %w(a b c)
end
it "allows headers to be defined" do
cmd = MyProcCommand.new { headers['Foo'] = 'BAR' }
_, h, = *cmd.call(mock_request('/foo'))
expect(h['Foo']).to eq 'BAR'
end
end
end
yard-0.9.7/spec/server/spec_helper.rb 0000644 0000041 0000041 00000001212 13035234564 017575 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
include Server
include Commands
def mock_adapter(opts = {})
opts[:libraries] ||= {'project' => [LibraryVersion.new('project', '1.0.0'), LibraryVersion.new('project', '1.0.1')]}
opts[:document_root] ||= '/public'
opts[:options] ||= {:single_library => false, :caching => false}
opts[:server_options] ||= {}
OpenStruct.new(opts)
end
class MockRequest < OpenStruct
def path; "#{script_name}#{path_info}" end
end
def mock_request(path_info = '/', script_name = '', extra_env = {})
opts = {:path_info => path_info, :script_name => script_name}
MockRequest.new(extra_env.merge(opts))
end
yard-0.9.7/spec/server/doc_server_serializer_spec.rb 0000644 0000041 0000041 00000004063 13035234564 022711 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Server::DocServerSerializer do
describe "#serialized_path" do
before do
Registry.clear
@serializer = Server::DocServerSerializer.new
end
after(:all) { Server::Adapter.shutdown }
it "returns '/PREFIX/library/toplevel' for root" do
expect(@serializer.serialized_path(Registry.root)).to eq "toplevel"
end
it "returns /PREFIX/library/Object for Object in a library" do
expect(@serializer.serialized_path(P('A::B::C'))).to eq 'A/B/C'
end
it "links to instance method as Class:method" do
obj = CodeObjects::MethodObject.new(:root, :method)
expect(@serializer.serialized_path(obj)).to eq 'toplevel:method'
end
it "links to class method as Class.method" do
obj = CodeObjects::MethodObject.new(:root, :method, :class)
expect(@serializer.serialized_path(obj)).to eq 'toplevel.method'
end
it "links to anchor for constant" do
obj = CodeObjects::ConstantObject.new(:root, :FOO)
expect(@serializer.serialized_path(obj)).to eq 'toplevel#FOO-constant'
end
it "links to anchor for class variable" do
obj = CodeObjects::ClassVariableObject.new(:root, :@@foo)
expect(@serializer.serialized_path(obj)).to eq 'toplevel#@@foo-classvariable'
end
it "links files using file/ prefix" do
file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
expect(@serializer.serialized_path(file)).to eq 'file/FooBar'
end
it "escapes special characters" do
obj = CodeObjects::MethodObject.new(:root, :method?)
expect(@serializer.serialized_path(obj)).to eq 'toplevel:method%3F'
end
it "handles unicode data" do
file = CodeObjects::ExtraFileObject.new("test\u0160", '')
if file.name.encoding == Encoding.find("Windows-1252")
expect(@serializer.serialized_path(file)).to eq 'file/test_8A'
else
expect(@serializer.serialized_path(file)).to eq 'file/test_C5A0'
end
end if defined?(::Encoding)
end
end
yard-0.9.7/spec/server/rack_adapter_spec.rb 0000644 0000041 0000041 00000001356 13035234564 020747 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"
RSpec.describe "YARD::Server::RackMiddleware" do
before do
begin; require 'rack'; rescue LoadError; pending "rack required for these tests" end
@superapp = double(:superapp)
@app = YARD::Server::RackMiddleware.new(@superapp, :libraries => {'foo' => [LibraryVersion.new('foo', nil)]})
end
after(:all) { YARD::Server::Adapter.shutdown }
it "handles requests" do
expect(@app.call(Rack::MockRequest.env_for('/'))[0]).to eq 200
end
it "passes up to the next middleware on 404" do
expect(@superapp).to receive(:call).and_return([200, {}, ['OK']])
expect(@app.call(Rack::MockRequest.env_for('/INVALID'))).to eq [200, {}, ['OK']]
end
end
yard-0.9.7/spec/server/webrick_servlet_spec.rb 0000644 0000041 0000041 00000001231 13035234564 021511 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Server::WebrickServlet do
describe "#do_GET" do
it "performs a GET" do
resp = OpenStruct.new
class << resp
def []=(name, value) (self.headers ||= {})[name] = value end
end
server = double(:server, :[] => nil)
adapter = mock_adapter
adapter.router = proc { [200, {'Header' => 'foo'}, ['body']] }
WebrickServlet.new(server, adapter).do_GET(mock_request('/foo'), resp)
expect(resp.status).to eq 200
expect(resp.headers).to eq('Header' => 'foo')
expect(resp.body).to eq 'body'
end
end
end
yard-0.9.7/spec/server/doc_server_helper_spec.rb 0000644 0000041 0000041 00000004520 13035234564 022015 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"
class MyDocServerSerializerRouter
attr_accessor :request
def docs_prefix; 'PREFIX' end
def initialize; @request = mock_request end
end
class MockDocServerHelper
include YARD::Templates::Helpers::BaseHelper
include YARD::Templates::Helpers::HtmlHelper
include YARD::Server::DocServerHelper
attr_accessor :adapter
attr_accessor :single_library
attr_accessor :library
def initialize
@single_library = false
@library = LibraryVersion.new('foo')
@adapter = mock_adapter(:router => MyDocServerSerializerRouter.new)
@serializer = YARD::Server::DocServerSerializer.new
@object = YARD::Registry.root
end
def options; OpenStruct.new end
end
RSpec.describe YARD::Server::DocServerHelper do
before do
@helper = MockDocServerHelper.new
end
describe "#url_for" do
it "does not link to /library/ if single_library = true" do
@helper.single_library = true
expect(@helper.url_for(Registry.root)).to eq "/PREFIX/toplevel"
end
it "returns /PREFIX/foo/version if foo has a version" do
@helper.library = LibraryVersion.new('foo', 'bar')
@helper.adapter.router.request.version_supplied = true
expect(@helper.url_for(P('A'))).to eq '/PREFIX/foo/bar/A'
end
it "uses script name prefix if set" do
@helper.adapter.router.request.script_name = '/mount/point'
@helper.library = LibraryVersion.new('foo', 'bar')
@helper.adapter.router.request.version_supplied = true
expect(@helper.url_for(P('A'))).to eq '/mount/point/PREFIX/foo/bar/A'
end
end
describe "#url_for_file" do
it "properly links file objects using file/ prefix" do
file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
expect(@helper.url_for_file(file)).to eq '/PREFIX/foo/file/a/b/FooBar.md'
end
it "properly links anchor portion" do
file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
expect(@helper.url_for_file(file, 'anchor')).to eq '/PREFIX/foo/file/a/b/FooBar.md#anchor'
end
it "uses script name prefix if set" do
@helper.adapter.router.request.script_name = '/mount/point'
file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
expect(@helper.url_for_file(file)).to eq '/mount/point/PREFIX/foo/file/a/b/FooBar.md'
end
end
end
yard-0.9.7/spec/server/static_caching_spec.rb 0000644 0000041 0000041 00000003333 13035234564 021267 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::Server::StaticCaching do
include StaticCaching
describe "#check_static_cache" do
def adapter; @adapter ||= mock_adapter end
def request; @request ||= MockRequest.new end
it "returns nil if document root is not set" do
adapter.document_root = nil
expect(check_static_cache).to be nil
end
it "reads a file from document root if path matches file on system" do
request.path_info = '/hello/world.html'
expect(File).to receive(:file?).with('/public/hello/world.html').and_return(true)
expect(File).to receive(:open).with('/public/hello/world.html', anything).and_return('body')
s, _, b = *check_static_cache
expect(s).to eq 200
expect(b).to eq ["body"]
end
it "reads a file if path matches file on system + .html" do
request.path_info = '/hello/world'
expect(File).to receive(:file?).with('/public/hello/world.html').and_return(true)
expect(File).to receive(:open).with('/public/hello/world.html', anything).and_return('body')
s, _, b = *check_static_cache
expect(s).to eq 200
expect(b).to eq ["body"]
end
it "returns nil if no matching file is found" do
request.path_info = '/hello/foo'
expect(File).to receive(:file?).with('/public/hello/foo.html').and_return(false)
expect(check_static_cache).to eq nil
end
it "adds mount point to cache location" do
request.path_info = '/hello/world.html'
request.script_name = '/mount/point'
expect(File).to receive(:file?).with('/public/mount/point/hello/world.html').and_return(false)
expect(check_static_cache).to eq nil
end
end
end
yard-0.9.7/spec/server/router_spec.rb 0000644 0000041 0000041 00000007741 13035234564 017653 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
class MyRouterSpecRouter < Router
def docs_prefix; 'mydocs/foo' end
def list_prefix; 'mylist/foo' end
def search_prefix; 'mysearch/foo' end
def check_static_cache; nil end
end
RSpec.describe YARD::Server::Router do
before do
@adapter = mock_adapter
@projects = @adapter.libraries['project']
@request = mock_request
end
describe "#parse_library_from_path" do
def parse(*args)
@request.path_info = '/' + args.join('/')
@router = MyRouterSpecRouter.new(@adapter)
@router.request = @request
@router.parse_library_from_path(args.flatten)
end
it "parses library and version name out of path" do
expect(parse('project', '1.0.0')).to eq [@projects[0], []]
expect(@request.version_supplied).to be true
end
it "parses library and use latest version if version is not supplied" do
expect(parse('project')).to eq [@projects[1], []]
expect(@request.version_supplied).to be false
end
it "parses library and use latest version if next component is not a version" do
expect(parse('project', 'notaversion')).to eq [@projects[1], ['notaversion']]
expect(@request.version_supplied).to be false
end
it "returns nil library if no library is found" do
expect(parse('notproject')).to eq [nil, ['notproject']]
end
it "does not parse library or version if single_library == true" do
allow(@adapter).to receive(:options).and_return(:single_library => true)
expect(parse('notproject')).to eq [@projects[0], ['notproject']]
end
end
describe "#route" do
def route_to(route, command, script_name = '')
req = mock_request(route, script_name)
router = MyRouterSpecRouter.new(@adapter)
expect(command).to receive(:new) do |*args|
@command = command.allocate
@command.send(:initialize, *args)
class << @command; define_method(:call) {|*| self } end
@command
end
router.call(req)
end
it "routes /docs/OBJECT to object if single_library = true" do
allow(@adapter).to receive(:options).and_return(:single_library => true)
route_to('/mydocs/foo/FOO', DisplayObjectCommand)
end
it "routes /docs" do
route_to('/mydocs/foo', LibraryIndexCommand)
end
it "routes /docs as index for library if single_library == true" do
allow(@adapter).to receive(:options).and_return(:single_library => true)
route_to('/mydocs/foo/', DisplayObjectCommand)
end
it "routes /docs/name/version" do
route_to('/mydocs/foo/project/1.0.0', DisplayObjectCommand)
expect(@command.library).to eq @projects[0]
end
it "routes /docs/name/ to latest version of library" do
route_to('/mydocs/foo/project', DisplayObjectCommand)
expect(@command.library).to eq @projects[1]
end
it "routes /list/name/version/class" do
route_to('/mylist/foo/project/1.0.0/class', ListCommand)
expect(@command.library).to eq @projects[0]
end
it "routes /list/name/version/methods" do
route_to('/mylist/foo/project/1.0.0/methods', ListCommand)
expect(@command.library).to eq @projects[0]
end
it "routes /list/name/version/files" do
route_to('/mylist/foo/project/1.0.0/files', ListCommand)
expect(@command.library).to eq @projects[0]
end
it "routes /list/name to latest version of library" do
route_to('/mylist/foo/project/class', ListCommand)
expect(@command.library).to eq @projects[1]
end
it "routes /search/name/version" do
route_to('/mysearch/foo/project/1.0.0', SearchCommand)
expect(@command.library).to eq @projects[0]
end
it "routes /search/name to latest version of library" do
route_to('/mysearch/foo/project', SearchCommand)
expect(@command.library).to eq @projects[1]
end
it "searches static files for non-existent library" do
route_to('/mydocs/foo/notproject', RootRequestCommand)
end
end
end
yard-0.9.7/spec/spec_helper.rb 0000644 0000041 0000041 00000016735 13035234564 016307 0 ustar www-data www-data # frozen_string_literal: true
require "rubygems"
begin
require "rspec"
rescue LoadError
require "spec"
end
begin
require 'bundler/setup'
rescue LoadError
nil # noop
end
require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'yard'))
unless defined?(HAVE_RIPPER)
begin require 'ripper'; rescue LoadError; nil end
HAVE_RIPPER = defined?(::Ripper) && !ENV['LEGACY'] ? true : false
LEGACY_PARSER = !HAVE_RIPPER
class YARD::Parser::SourceParser
def self.parser_type; @parser_type == :ruby ? :ruby18 : @parser_type end
end if ENV['LEGACY']
end
begin
require 'coveralls'
Coveralls.wear!
end if ENV['CI'] && HAVE_RIPPER
NAMED_OPTIONAL_ARGUMENTS = RUBY_VERSION >= '2.1.0'
def parse_file(file, thisfile = __FILE__, log_level = log.level, ext = '.rb.txt')
Registry.clear
path = File.join(File.dirname(thisfile), 'examples', file.to_s + ext)
YARD::Parser::SourceParser.parse(path, [], log_level)
end
def described_in_docs(klass, meth, file = nil)
YARD::Tags::Library.define_tag "RSpec Specification", :it, :with_raw_title_and_text
# Parse the file (could be multiple files)
if file
filename = File.join(YARD::ROOT, file)
YARD::Parser::SourceParser.new.parse(filename)
else
underscore = klass.class_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.gsub('::', '/')
$LOADED_FEATURES.find_all {|p| p.include? underscore }.each do |found_fname|
next unless File.exist? found_fname
YARD::Parser::SourceParser.new.parse(found_fname)
end
end
# Get the object
objname = klass.name + (meth[0, 1] == '#' ? meth : '::' + meth)
obj = Registry.at(objname)
raise "Cannot find object #{objname} described by spec." unless obj
raise "#{obj.path} has no @it tags to spec." unless obj.has_tag? :it
# Run examples
describe(klass, meth) do
obj.tags(:it).each do |it|
path = File.relative_path(YARD::ROOT, obj.file)
it(it.name + " (from #{path}:#{obj.line})") do
begin
eval(it.text)
rescue => e
e.set_backtrace(["#{path}:#{obj.line}:in @it tag specification"])
raise e
end
end
end
end
end
def docspec(objname = self.class.description, klass = self.class.described_type)
# Parse the file (could be multiple files)
underscore = klass.class_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.gsub('::', '/')
$LOADED_FEATURES.find_all {|p| p.include? underscore }.each do |filename|
filename = File.join(YARD::ROOT, filename)
next unless File.exist? filename
YARD::Parser::SourceParser.new.parse(filename)
end
# Get the object
objname = klass.name + objname if objname =~ /^[^A-Z]/
obj = Registry.at(objname)
raise "Cannot find object #{objname} described by spec." unless obj
raise "#{obj.path} has no @example tags to spec." unless obj.has_tag? :example
# Run examples
obj.tags(:example).each do |exs|
exs.text.split(/\n/).each do |ex|
begin
hash = eval("{ #{ex} }")
expect(hash.keys.first).to eq hash.values.first
rescue => e
raise e, "#{e.message}\nInvalid spec example in #{objname}:\n\n\t#{ex}\n"
end
end
end
end
module Kernel
require 'cgi'
def p(*args)
puts args.map {|arg| CGI.escapeHTML(arg.inspect) }.join("
\n")
args.first
end
def puts(str = '')
STDOUT.puts str + "
\n"
str
end
end if ENV['TM_APP_PATH']
RSpec.configure do |config|
config.before(:each) { log.io = StringIO.new }
# isolate environment of each test
# any other global settings which might be modified by a test should also
# be saved and restored here
config.around(:each) do |example|
saved_level = log.level
example.run
log.level = saved_level
end
# rspec-expectations config goes here. You can use an alternate
# assertion/expectation library such as wrong or the stdlib/minitest
# assertions if you prefer.
config.expect_with :rspec do |expectations|
# This option will default to `true` in RSpec 4. It makes the `description`
# and `failure_message` of custom matchers include text for helper methods
# defined using `chain`, e.g.:
# be_bigger_than(2).and_smaller_than(4).description
# # => "be bigger than 2 and smaller than 4"
# ...rather than:
# # => "be bigger than 2"
expectations.include_chain_clauses_in_custom_matcher_descriptions = true
end
# rspec-mocks config goes here. You can use an alternate test double
# library (such as bogus or mocha) by changing the `mock_with` option here.
config.mock_with :rspec do |mocks|
# Prevents you from mocking or stubbing a method that does not exist on
# a real object. This is generally recommended, and will default to
# `true` in RSpec 4.
# mocks.verify_partial_doubles = true # FIXME: Not yet working
end
# This option will default to `:apply_to_host_groups` in RSpec 4 (and will
# have no way to turn it off -- the option exists only for backwards
# compatibility in RSpec 3). It causes shared context metadata to be
# inherited by the metadata hash of host groups and examples, rather than
# triggering implicit auto-inclusion in groups with matching metadata.
config.shared_context_metadata_behavior = :apply_to_host_groups
# This allows you to limit a spec run to individual examples or groups
# you care about by tagging them with `:focus` metadata. When nothing
# is tagged with `:focus`, all examples get run. RSpec also provides
# aliases for `it`, `describe`, and `context` that include `:focus`
# metadata: `fit`, `fdescribe` and `fcontext`, respectively.
config.filter_run_when_matching :focus
# Allows RSpec to persist some state between runs in order to support
# the `--only-failures` and `--next-failure` CLI options. We recommend
# you configure your source control system to ignore this file.
config.example_status_persistence_file_path = "spec/examples.txt"
# Limits the available syntax to the non-monkey patched syntax that is
# recommended. For more details, see:
# - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
# - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
# - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
config.disable_monkey_patching!
# This setting enables warnings. It's recommended, but in some cases may
# be too noisy due to issues in dependencies.
config.warnings = false
# Many RSpec users commonly either run the entire suite or an individual
# file, and it's useful to allow more verbose output when running an
# individual spec file.
if config.files_to_run.one?
# Use the documentation formatter for detailed output,
# unless a formatter has already been configured
# (e.g. via a command-line flag).
config.default_formatter = 'doc'
end
# Print the N slowest examples and example groups at the
# end of the spec run, to help surface which specs are running
# particularly slow.
config.profile_examples = 5
# Run specs in random order to surface order dependencies. If you find an
# order dependency and want to debug it, you can fix the order by providing
# the seed, which is printed after each run.
# --seed 1234
# config.order = :random # FIXME: Not yet working
# Seed global randomization in this process using the `--seed` CLI option.
# Setting this allows you to use `--seed` to deterministically reproduce
# test failures related to randomization by passing the same `--seed` value
# as the one that triggered the failure.
Kernel.srand config.seed
end
include YARD
yard-0.9.7/spec/parser/ 0000755 0000041 0000041 00000000000 13035234564 014751 5 ustar www-data www-data yard-0.9.7/spec/parser/examples/ 0000755 0000041 0000041 00000000000 13035234564 016567 5 ustar www-data www-data yard-0.9.7/spec/parser/examples/multifile.c.txt 0000644 0000041 0000041 00000000570 13035234564 021545 0 ustar www-data www-data struct hoge *
rb_fuga(VALUE obj)
{
return Qtrue;
}
/*
* Hello Mars
*/
VALUE
rb_hello_mars(VALUE obj, VALUE n)
{
return Qtrue;
}
void
Init_Multifile(void)
{
rb_cMultifile = rb_define_class("Multifile", rb_cObject);
rb_define_method(rb_cMultifile, "extra", rb_extra, 1); /* in extra.c */
rb_define_method(rb_cMultifile, "hello_mars", rb_hello_mars, 1);
}
yard-0.9.7/spec/parser/examples/extrafile.c.txt 0000644 0000041 0000041 00000000105 13035234564 021530 0 ustar www-data www-data /*
* foo
*/
VALUE
rb_extra(VALUE obj, VALUE n)
{
return Qtrue;
}
yard-0.9.7/spec/parser/examples/example1.rb.txt 0000644 0000041 0000041 00000000117 13035234564 021445 0 ustar www-data www-data module Hello
class Hi
# Docstring
def me
"Value"
end
end
end yard-0.9.7/spec/parser/examples/parse_in_order_001.rb.txt 0000644 0000041 0000041 00000000034 13035234564 023302 0 ustar www-data www-data class MyModule::MyClass
end
yard-0.9.7/spec/parser/examples/tag_handler_001.rb.txt 0000644 0000041 0000041 00000000077 13035234564 022566 0 ustar www-data www-data class Foo
# @api public
# @return nil
def foo
end
end yard-0.9.7/spec/parser/examples/array.c.txt 0000644 0000041 0000041 00000274217 13035234564 020704 0 ustar www-data www-data /**********************************************************************
array.c -
$Author: yugui $
created at: Fri Aug 6 09:46:12 JST 1993
Copyright (C) 1993-2007 Yukihiro Matsumoto
Copyright (C) 2000 Network Applied Communication Laboratory, Inc.
Copyright (C) 2000 Information-technology Promotion Agency, Japan
**********************************************************************/
#include "ruby/ruby.h"
#include "ruby/util.h"
#include "ruby/st.h"
#ifndef ARRAY_DEBUG
# define NDEBUG
#endif
#include
VALUE rb_cArray;
static ID id_cmp;
#define ARY_DEFAULT_SIZE 16
#define ARY_MAX_SIZE (LONG_MAX / sizeof(VALUE))
void
rb_mem_clear(register VALUE *mem, register long size)
{
while (size--) {
*mem++ = Qnil;
}
}
static inline void
memfill(register VALUE *mem, register long size, register VALUE val)
{
while (size--) {
*mem++ = val;
}
}
# define ARY_SHARED_P(ary) \
(assert(!FL_TEST(ary, ELTS_SHARED) || !FL_TEST(ary, RARRAY_EMBED_FLAG)), \
FL_TEST(ary,ELTS_SHARED))
# define ARY_EMBED_P(ary) \
(assert(!FL_TEST(ary, ELTS_SHARED) || !FL_TEST(ary, RARRAY_EMBED_FLAG)), \
FL_TEST(ary, RARRAY_EMBED_FLAG))
#define ARY_HEAP_PTR(a) (assert(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.ptr)
#define ARY_HEAP_LEN(a) (assert(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.len)
#define ARY_EMBED_PTR(a) (assert(ARY_EMBED_P(a)), RARRAY(a)->as.ary)
#define ARY_EMBED_LEN(a) \
(assert(ARY_EMBED_P(a)), \
(long)((RBASIC(a)->flags >> RARRAY_EMBED_LEN_SHIFT) & \
(RARRAY_EMBED_LEN_MASK >> RARRAY_EMBED_LEN_SHIFT)))
#define ARY_OWNS_HEAP_P(a) (!FL_TEST(a, ELTS_SHARED|RARRAY_EMBED_FLAG))
#define FL_SET_EMBED(a) do { \
assert(!ARY_SHARED_P(a)); \
assert(!OBJ_FROZEN(a)); \
FL_SET(a, RARRAY_EMBED_FLAG); \
} while (0)
#define FL_UNSET_EMBED(ary) FL_UNSET(ary, RARRAY_EMBED_FLAG|RARRAY_EMBED_LEN_MASK)
#define FL_SET_SHARED(ary) do { \
assert(!ARY_EMBED_P(ary)); \
FL_SET(ary, ELTS_SHARED); \
} while (0)
#define FL_UNSET_SHARED(ary) FL_UNSET(ary, ELTS_SHARED)
#define ARY_SET_PTR(ary, p) do { \
assert(!ARY_EMBED_P(ary)); \
assert(!OBJ_FROZEN(ary)); \
RARRAY(ary)->as.heap.ptr = (p); \
} while (0)
#define ARY_SET_EMBED_LEN(ary, n) do { \
long tmp_n = n; \
assert(ARY_EMBED_P(ary)); \
assert(!OBJ_FROZEN(ary)); \
RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK; \
RBASIC(ary)->flags |= (tmp_n) << RARRAY_EMBED_LEN_SHIFT; \
} while (0)
#define ARY_SET_HEAP_LEN(ary, n) do { \
assert(!ARY_EMBED_P(ary)); \
RARRAY(ary)->as.heap.len = n; \
} while (0)
#define ARY_SET_LEN(ary, n) do { \
if (ARY_EMBED_P(ary)) { \
ARY_SET_EMBED_LEN(ary, n); \
} \
else { \
ARY_SET_HEAP_LEN(ary, n); \
} \
assert(RARRAY_LEN(ary) == n); \
} while (0)
#define ARY_INCREASE_PTR(ary, n) do { \
assert(!ARY_EMBED_P(ary)); \
assert(!OBJ_FROZEN(ary)); \
RARRAY(ary)->as.heap.ptr += n; \
} while (0)
#define ARY_INCREASE_LEN(ary, n) do { \
assert(!OBJ_FROZEN(ary)); \
if (ARY_EMBED_P(ary)) { \
ARY_SET_EMBED_LEN(ary, RARRAY_LEN(ary)+n); \
} \
else { \
RARRAY(ary)->as.heap.len += n; \
} \
} while (0)
#define ARY_CAPA(ary) (ARY_EMBED_P(ary) ? RARRAY_EMBED_LEN_MAX : \
ARY_SHARED_ROOT_P(ary) ? RARRAY_LEN(ary) : RARRAY(ary)->as.heap.aux.capa)
#define ARY_SET_CAPA(ary, n) do { \
assert(!ARY_EMBED_P(ary)); \
assert(!ARY_SHARED_P(ary)); \
assert(!OBJ_FROZEN(ary)); \
RARRAY(ary)->as.heap.aux.capa = (n); \
} while (0)
#define ARY_SHARED(ary) (assert(ARY_SHARED_P(ary)), RARRAY(ary)->as.heap.aux.shared)
#define ARY_SET_SHARED(ary, value) do { \
assert(!ARY_EMBED_P(ary)); \
assert(ARY_SHARED_P(ary)); \
assert(ARY_SHARED_ROOT_P(value)); \
RARRAY(ary)->as.heap.aux.shared = (value); \
} while (0)
#define RARRAY_SHARED_ROOT_FLAG FL_USER5
#define ARY_SHARED_ROOT_P(ary) (FL_TEST(ary, RARRAY_SHARED_ROOT_FLAG))
#define ARY_SHARED_NUM(ary) \
(assert(ARY_SHARED_ROOT_P(ary)), RARRAY(ary)->as.heap.aux.capa)
#define ARY_SET_SHARED_NUM(ary, value) do { \
assert(ARY_SHARED_ROOT_P(ary)); \
RARRAY(ary)->as.heap.aux.capa = (value); \
} while (0)
#define FL_SET_SHARED_ROOT(ary) do { \
assert(!ARY_EMBED_P(ary)); \
FL_SET(ary, RARRAY_SHARED_ROOT_FLAG); \
} while (0)
static void
ary_resize_capa(VALUE ary, long capacity)
{
assert(RARRAY_LEN(ary) <= capacity);
assert(!OBJ_FROZEN(ary));
assert(!ARY_SHARED_P(ary));
if (capacity > RARRAY_EMBED_LEN_MAX) {
if (ARY_EMBED_P(ary)) {
long len = ARY_EMBED_LEN(ary);
VALUE *ptr = ALLOC_N(VALUE, (capacity));
MEMCPY(ptr, ARY_EMBED_PTR(ary), VALUE, len);
FL_UNSET_EMBED(ary);
ARY_SET_PTR(ary, ptr);
ARY_SET_HEAP_LEN(ary, len);
}
else {
REALLOC_N(RARRAY(ary)->as.heap.ptr, VALUE, (capacity));
}
ARY_SET_CAPA(ary, (capacity));
}
else {
if (!ARY_EMBED_P(ary)) {
long len = RARRAY_LEN(ary);
VALUE *ptr = RARRAY_PTR(ary);
MEMCPY(RARRAY(ary)->as.ary, ptr, VALUE, len);
FL_SET_EMBED(ary);
ARY_SET_LEN(ary, len);
xfree(ptr);
}
}
}
static void
rb_ary_decrement_share(VALUE shared)
{
if (shared) {
int num = ARY_SHARED_NUM(shared) - 1;
if (num == 0) {
rb_ary_free(shared);
rb_gc_force_recycle(shared);
}
else if (num > 0) {
ARY_SET_SHARED_NUM(shared, num);
}
}
}
static void
rb_ary_unshare(VALUE ary)
{
VALUE shared = RARRAY(ary)->as.heap.aux.shared;
rb_ary_decrement_share(shared);
FL_UNSET_SHARED(ary);
}
static inline void
rb_ary_unshare_safe(VALUE ary) {
if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
rb_ary_unshare(ary);
}
}
static VALUE
rb_ary_increment_share(VALUE shared) {
int num = ARY_SHARED_NUM(shared);
if (num >= 0) {
ARY_SET_SHARED_NUM(shared, num + 1);
}
return shared;
}
static void
rb_ary_set_shared(VALUE ary, VALUE shared)
{
rb_ary_increment_share(shared);
FL_SET_SHARED(ary);
ARY_SET_SHARED(ary, shared);
}
static inline void
rb_ary_modify_check(VALUE ary)
{
if (OBJ_FROZEN(ary)) rb_error_frozen("array");
if (!OBJ_UNTRUSTED(ary) && rb_safe_level() >= 4)
rb_raise(rb_eSecurityError, "Insecure: can't modify array");
}
static void
rb_ary_modify(VALUE ary)
{
rb_ary_modify_check(ary);
if (ARY_SHARED_P(ary)) {
long len = RARRAY_LEN(ary);
if (len <= RARRAY_EMBED_LEN_MAX) {
VALUE *ptr = ARY_HEAP_PTR(ary);
VALUE shared = ARY_SHARED(ary);
FL_UNSET_SHARED(ary);
FL_SET_EMBED(ary);
MEMCPY(ARY_EMBED_PTR(ary), ptr, VALUE, len);
rb_ary_decrement_share(shared);
ARY_SET_EMBED_LEN(ary, len);
}
else {
VALUE *ptr = ALLOC_N(VALUE, len);
MEMCPY(ptr, RARRAY_PTR(ary), VALUE, len);
rb_ary_unshare(ary);
ARY_SET_CAPA(ary, len);
ARY_SET_PTR(ary, ptr);
}
}
}
VALUE
rb_ary_freeze(VALUE ary)
{
return rb_obj_freeze(ary);
}
/*
* call-seq:
* array.frozen? -> true or false
*
* Return true if this array is frozen (or temporarily frozen
* while being sorted).
*/
static VALUE
rb_ary_frozen_p(VALUE ary)
{
if (OBJ_FROZEN(ary)) return Qtrue;
return Qfalse;
}
static VALUE
ary_alloc(VALUE klass)
{
NEWOBJ(ary, struct RArray);
OBJSETUP(ary, klass, T_ARRAY);
FL_SET_EMBED((VALUE)ary);
ARY_SET_EMBED_LEN((VALUE)ary, 0);
return (VALUE)ary;
}
static VALUE
ary_new(VALUE klass, long len)
{
VALUE ary;
if (len < 0) {
rb_raise(rb_eArgError, "negative array size (or size too big)");
}
if (len > ARY_MAX_SIZE) {
rb_raise(rb_eArgError, "array size too big");
}
ary = ary_alloc(klass);
if (len > RARRAY_EMBED_LEN_MAX) {
FL_UNSET_EMBED(ary);
ARY_SET_PTR(ary, ALLOC_N(VALUE, len));
ARY_SET_CAPA(ary, len);
ARY_SET_HEAP_LEN(ary, 0);
}
return ary;
}
VALUE
rb_ary_new2(long len)
{
return ary_new(rb_cArray, len);
}
VALUE
rb_ary_new(void)
{
return rb_ary_new2(RARRAY_EMBED_LEN_MAX);
}
#include
VALUE
rb_ary_new3(long n, ...)
{
va_list ar;
VALUE ary;
long i;
ary = rb_ary_new2(n);
va_start(ar, n);
for (i=0; i 0 && elts) {
MEMCPY(RARRAY_PTR(ary), elts, VALUE, n);
ARY_SET_LEN(ary, n);
}
return ary;
}
VALUE
rb_ary_tmp_new(long len)
{
return ary_new(0, len);
}
void
rb_ary_free(VALUE ary)
{
if (ARY_OWNS_HEAP_P(ary)) {
xfree(RARRAY_PTR(ary));
}
}
static VALUE
ary_make_shared(VALUE ary)
{
assert(!ARY_EMBED_P(ary));
if (ARY_SHARED_P(ary)) {
return ARY_SHARED(ary);
}
else {
NEWOBJ(shared, struct RArray);
OBJSETUP(shared, 0, T_ARRAY);
FL_UNSET_EMBED(shared);
ARY_SET_LEN((VALUE)shared, RARRAY_LEN(ary));
ARY_SET_PTR((VALUE)shared, RARRAY_PTR(ary));
FL_SET_SHARED_ROOT(shared);
ARY_SET_SHARED_NUM((VALUE)shared, 1);
FL_SET_SHARED(ary);
ARY_SET_SHARED(ary, (VALUE)shared);
OBJ_FREEZE(shared);
return (VALUE)shared;
}
}
static VALUE
ary_make_substitution(VALUE ary)
{
if (RARRAY_LEN(ary) <= RARRAY_EMBED_LEN_MAX) {
VALUE subst = rb_ary_new2(RARRAY_LEN(ary));
MEMCPY(ARY_EMBED_PTR(subst), RARRAY_PTR(ary), VALUE, RARRAY_LEN(ary));
ARY_SET_EMBED_LEN(subst, RARRAY_LEN(ary));
return subst;
}
else {
return rb_ary_increment_share(ary_make_shared(ary));
}
}
VALUE
rb_assoc_new(VALUE car, VALUE cdr)
{
return rb_ary_new3(2, car, cdr);
}
static VALUE
to_ary(VALUE ary)
{
return rb_convert_type(ary, T_ARRAY, "Array", "to_ary");
}
VALUE
rb_check_array_type(VALUE ary)
{
return rb_check_convert_type(ary, T_ARRAY, "Array", "to_ary");
}
/*
* call-seq:
* Array.try_convert(obj) -> array or nil
*
* Try to convert obj into an array, using to_ary method.
* Returns converted array or nil if obj cannot be converted
* for any reason. This method is to check if an argument is an
* array.
*
* Array.try_convert([1]) # => [1]
* Array.try_convert("1") # => nil
*
* if tmp = Array.try_convert(arg)
* # the argument is an array
* elsif tmp = String.try_convert(arg)
* # the argument is a string
* end
*
*/
static VALUE
rb_ary_s_try_convert(VALUE dummy, VALUE ary)
{
return rb_check_array_type(ary);
}
/*
* call-seq:
* Array.new(size=0, obj=nil)
* Array.new(array)
* Array.new(size) {|index| block }
*
* Returns a new array. In the first form, the new array is
* empty. In the second it is created with _size_ copies of _obj_
* (that is, _size_ references to the same
* _obj_). The third form creates a copy of the array
* passed as a parameter (the array is generated by calling
* to_ary on the parameter). In the last form, an array
* of the given size is created. Each element in this array is
* calculated by passing the element's index to the given block and
* storing the return value.
*
* Array.new
* Array.new(2)
* Array.new(5, "A")
*
* # only one copy of the object is created
* a = Array.new(2, Hash.new)
* a[0]['cat'] = 'feline'
* a
* a[1]['cat'] = 'Felix'
* a
*
* # here multiple copies are created
* a = Array.new(2) { Hash.new }
* a[0]['cat'] = 'feline'
* a
*
* squares = Array.new(5) {|i| i*i}
* squares
*
* copy = Array.new(squares)
*/
static VALUE
rb_ary_initialize(int argc, VALUE *argv, VALUE ary)
{
long len;
VALUE size, val;
rb_ary_modify(ary);
if (argc == 0) {
if (ARY_OWNS_HEAP_P(ary) && RARRAY_PTR(ary)) {
xfree(RARRAY_PTR(ary));
}
rb_ary_unshare_safe(ary);
FL_SET_EMBED(ary);
ARY_SET_EMBED_LEN(ary, 0);
if (rb_block_given_p()) {
rb_warning("given block not used");
}
return ary;
}
rb_scan_args(argc, argv, "02", &size, &val);
if (argc == 1 && !FIXNUM_P(size)) {
val = rb_check_array_type(size);
if (!NIL_P(val)) {
rb_ary_replace(ary, val);
return ary;
}
}
len = NUM2LONG(size);
if (len < 0) {
rb_raise(rb_eArgError, "negative array size");
}
if (len > ARY_MAX_SIZE) {
rb_raise(rb_eArgError, "array size too big");
}
rb_ary_modify(ary);
ary_resize_capa(ary, len);
if (rb_block_given_p()) {
long i;
if (argc == 2) {
rb_warn("block supersedes default value argument");
}
for (i=0; i 0 && argv) {
MEMCPY(RARRAY_PTR(ary), argv, VALUE, argc);
ARY_SET_LEN(ary, argc);
}
return ary;
}
void
rb_ary_store(VALUE ary, long idx, VALUE val)
{
if (idx < 0) {
idx += RARRAY_LEN(ary);
if (idx < 0) {
rb_raise(rb_eIndexError, "index %ld out of array",
idx - RARRAY_LEN(ary));
}
}
else if (idx >= ARY_MAX_SIZE) {
rb_raise(rb_eIndexError, "index %ld too big", idx);
}
rb_ary_modify(ary);
if (idx >= ARY_CAPA(ary)) {
long new_capa = ARY_CAPA(ary) / 2;
if (new_capa < ARY_DEFAULT_SIZE) {
new_capa = ARY_DEFAULT_SIZE;
}
if (new_capa >= ARY_MAX_SIZE - idx) {
new_capa = (ARY_MAX_SIZE - idx) / 2;
}
new_capa += idx;
ary_resize_capa(ary, new_capa);
}
if (idx > RARRAY_LEN(ary)) {
rb_mem_clear(RARRAY_PTR(ary) + RARRAY_LEN(ary),
idx-RARRAY_LEN(ary) + 1);
}
if (idx >= RARRAY_LEN(ary)) {
ARY_SET_LEN(ary, idx + 1);
}
RARRAY_PTR(ary)[idx] = val;
}
static VALUE
ary_make_partial(VALUE ary, VALUE klass, long offset, long len)
{
assert(offset >= 0);
assert(len >= 0);
assert(offset+len <= RARRAY_LEN(ary));
if (len <= RARRAY_EMBED_LEN_MAX) {
VALUE result = ary_alloc(klass);
MEMCPY(ARY_EMBED_PTR(result), RARRAY_PTR(ary) + offset, VALUE, len);
ARY_SET_EMBED_LEN(result, len);
return result;
}
else {
VALUE shared, result = ary_alloc(klass);
FL_UNSET_EMBED(result);
shared = ary_make_shared(ary);
ARY_SET_PTR(result, RARRAY_PTR(ary));
ARY_SET_LEN(result, RARRAY_LEN(ary));
rb_ary_set_shared(result, shared);
ARY_INCREASE_PTR(result, offset);
ARY_SET_LEN(result, len);
return result;
}
}
static VALUE
ary_make_shared_copy(VALUE ary)
{
return ary_make_partial(ary, rb_obj_class(ary), 0, RARRAY_LEN(ary));
}
enum ary_take_pos_flags
{
ARY_TAKE_FIRST = 0,
ARY_TAKE_LAST = 1
};
static VALUE
ary_take_first_or_last(int argc, VALUE *argv, VALUE ary, enum ary_take_pos_flags last)
{
VALUE nv;
long n;
long offset = 0;
rb_scan_args(argc, argv, "1", &nv);
n = NUM2LONG(nv);
if (n > RARRAY_LEN(ary)) {
n = RARRAY_LEN(ary);
}
else if (n < 0) {
rb_raise(rb_eArgError, "negative array size");
}
if (last) {
offset = RARRAY_LEN(ary) - n;
}
return ary_make_partial(ary, rb_cArray, offset, n);
}
/*
* call-seq:
* array << obj -> array
*
* Append---Pushes the given object on to the end of this array. This
* expression returns the array itself, so several appends
* may be chained together.
*
* [ 1, 2 ] << "c" << "d" << [ 3, 4 ]
* #=> [ 1, 2, "c", "d", [ 3, 4 ] ]
*
*/
VALUE
rb_ary_push(VALUE ary, VALUE item)
{
rb_ary_store(ary, RARRAY_LEN(ary), item);
return ary;
}
/*
* call-seq:
* array.push(obj, ... ) -> array
*
* Append---Pushes the given object(s) on to the end of this array. This
* expression returns the array itself, so several appends
* may be chained together.
*
* a = [ "a", "b", "c" ]
* a.push("d", "e", "f")
* #=> ["a", "b", "c", "d", "e", "f"]
*/
static VALUE
rb_ary_push_m(int argc, VALUE *argv, VALUE ary)
{
rb_ary_modify_check(ary);
while (argc--) {
rb_ary_push(ary, *argv++);
}
return ary;
}
VALUE
rb_ary_pop(VALUE ary)
{
long n;
rb_ary_modify_check(ary);
if (RARRAY_LEN(ary) == 0) return Qnil;
if (ARY_OWNS_HEAP_P(ary) &&
RARRAY_LEN(ary) * 3 < ARY_CAPA(ary) &&
ARY_CAPA(ary) > ARY_DEFAULT_SIZE)
{
ary_resize_capa(ary, RARRAY_LEN(ary) * 2);
}
n = RARRAY_LEN(ary)-1;
ARY_SET_LEN(ary, n);
return RARRAY_PTR(ary)[n];
}
/*
* call-seq:
* array.pop -> obj or nil
* array.pop(n) -> array
*
* Removes the last element from self and returns it, or
* nil if the array is empty.
*
* If a number _n_ is given, returns an array of the last n elements
* (or less) just like array.slice!(-n, n) does.
*
* a = [ "a", "b", "c", "d" ]
* a.pop #=> "d"
* a.pop(2) #=> ["b", "c"]
* a #=> ["a"]
*/
static VALUE
rb_ary_pop_m(int argc, VALUE *argv, VALUE ary)
{
VALUE result;
if (argc == 0) {
return rb_ary_pop(ary);
}
rb_ary_modify_check(ary);
result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
ARY_INCREASE_LEN(ary, -RARRAY_LEN(result));
return result;
}
VALUE
rb_ary_shift(VALUE ary)
{
VALUE top;
rb_ary_modify_check(ary);
if (RARRAY_LEN(ary) == 0) return Qnil;
top = RARRAY_PTR(ary)[0];
if (!ARY_SHARED_P(ary)) {
if (RARRAY_LEN(ary) < ARY_DEFAULT_SIZE) {
MEMMOVE(RARRAY_PTR(ary), RARRAY_PTR(ary)+1, VALUE, RARRAY_LEN(ary)-1);
ARY_INCREASE_LEN(ary, -1);
return top;
}
assert(!ARY_EMBED_P(ary)); /* ARY_EMBED_LEN_MAX < ARY_DEFAULT_SIZE */
RARRAY_PTR(ary)[0] = Qnil;
ary_make_shared(ary);
}
ARY_INCREASE_PTR(ary, 1); /* shift ptr */
ARY_INCREASE_LEN(ary, -1);
return top;
}
/*
* call-seq:
* array.shift -> obj or nil
* array.shift(n) -> array
*
* Returns the first element of self and removes it (shifting all
* other elements down by one). Returns nil if the array
* is empty.
*
* If a number _n_ is given, returns an array of the first n elements
* (or less) just like array.slice!(0, n) does.
*
* args = [ "-m", "-q", "filename" ]
* args.shift #=> "-m"
* args #=> ["-q", "filename"]
*
* args = [ "-m", "-q", "filename" ]
* args.shift(2) #=> ["-m", "-q"]
* args #=> ["filename"]
*/
static VALUE
rb_ary_shift_m(int argc, VALUE *argv, VALUE ary)
{
VALUE result;
long n;
if (argc == 0) {
return rb_ary_shift(ary);
}
rb_ary_modify_check(ary);
result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
n = RARRAY_LEN(result);
if (ARY_SHARED_P(ary)) {
ARY_INCREASE_PTR(ary, n);
}
else {
MEMMOVE(RARRAY_PTR(ary), RARRAY_PTR(ary)+n, VALUE, RARRAY_LEN(ary)-n);
}
ARY_INCREASE_LEN(ary, -n);
return result;
}
/*
* call-seq:
* array.unshift(obj, ...) -> array
*
* Prepends objects to the front of array.
* other elements up one.
*
* a = [ "b", "c", "d" ]
* a.unshift("a") #=> ["a", "b", "c", "d"]
* a.unshift(1, 2) #=> [ 1, 2, "a", "b", "c", "d"]
*/
static VALUE
rb_ary_unshift_m(int argc, VALUE *argv, VALUE ary)
{
long len;
if (argc == 0) return ary;
rb_ary_modify(ary);
if (ARY_CAPA(ary) <= (len = RARRAY_LEN(ary)) + argc) {
ary_resize_capa(ary, len + argc + ARY_DEFAULT_SIZE);
}
/* sliding items */
MEMMOVE(RARRAY_PTR(ary) + argc, RARRAY_PTR(ary), VALUE, len);
MEMCPY(RARRAY_PTR(ary), argv, VALUE, argc);
ARY_INCREASE_LEN(ary, argc);
return ary;
}
VALUE
rb_ary_unshift(VALUE ary, VALUE item)
{
return rb_ary_unshift_m(1,&item,ary);
}
/* faster version - use this if you don't need to treat negative offset */
static inline VALUE
rb_ary_elt(VALUE ary, long offset)
{
if (RARRAY_LEN(ary) == 0) return Qnil;
if (offset < 0 || RARRAY_LEN(ary) <= offset) {
return Qnil;
}
return RARRAY_PTR(ary)[offset];
}
VALUE
rb_ary_entry(VALUE ary, long offset)
{
if (offset < 0) {
offset += RARRAY_LEN(ary);
}
return rb_ary_elt(ary, offset);
}
VALUE
rb_ary_subseq(VALUE ary, long beg, long len)
{
VALUE klass;
if (beg > RARRAY_LEN(ary)) return Qnil;
if (beg < 0 || len < 0) return Qnil;
if (RARRAY_LEN(ary) < len || RARRAY_LEN(ary) < beg + len) {
len = RARRAY_LEN(ary) - beg;
}
klass = rb_obj_class(ary);
if (len == 0) return ary_new(klass, 0);
return ary_make_partial(ary, klass, beg, len);
}
/*
* call-seq:
* array[index] -> obj or nil
* array[start, length] -> an_array or nil
* array[range] -> an_array or nil
* array.slice(index) -> obj or nil
* array.slice(start, length) -> an_array or nil
* array.slice(range) -> an_array or nil
*
* Element Reference---Returns the element at _index_,
* or returns a subarray starting at _start_ and
* continuing for _length_ elements, or returns a subarray
* specified by _range_.
* Negative indices count backward from the end of the
* array (-1 is the last element). Returns nil if the index
* (or starting index) are out of range.
*
* a = [ "a", "b", "c", "d", "e" ]
* a[2] + a[0] + a[1] #=> "cab"
* a[6] #=> nil
* a[1, 2] #=> [ "b", "c" ]
* a[1..3] #=> [ "b", "c", "d" ]
* a[4..7] #=> [ "e" ]
* a[6..10] #=> nil
* a[-3, 3] #=> [ "c", "d", "e" ]
* # special cases
* a[5] #=> nil
* a[5, 1] #=> []
* a[5..10] #=> []
*
*/
VALUE
rb_ary_aref(int argc, VALUE *argv, VALUE ary)
{
VALUE arg;
long beg, len;
if (argc == 2) {
beg = NUM2LONG(argv[0]);
len = NUM2LONG(argv[1]);
if (beg < 0) {
beg += RARRAY_LEN(ary);
}
return rb_ary_subseq(ary, beg, len);
}
if (argc != 1) {
rb_scan_args(argc, argv, "11", 0, 0);
}
arg = argv[0];
/* special case - speeding up */
if (FIXNUM_P(arg)) {
return rb_ary_entry(ary, FIX2LONG(arg));
}
/* check if idx is Range */
switch (rb_range_beg_len(arg, &beg, &len, RARRAY_LEN(ary), 0)) {
case Qfalse:
break;
case Qnil:
return Qnil;
default:
return rb_ary_subseq(ary, beg, len);
}
return rb_ary_entry(ary, NUM2LONG(arg));
}
/*
* call-seq:
* array.at(index) -> obj or nil
*
* Returns the element at _index_. A
* negative index counts from the end of _self_. Returns +nil+
* if the index is out of range. See also Array#[].
*
* a = [ "a", "b", "c", "d", "e" ]
* a.at(0) #=> "a"
* a.at(-1) #=> "e"
*/
static VALUE
rb_ary_at(VALUE ary, VALUE pos)
{
return rb_ary_entry(ary, NUM2LONG(pos));
}
/*
* call-seq:
* array.first -> obj or nil
* array.first(n) -> an_array
*
* Returns the first element, or the first +n+ elements, of the array.
* If the array is empty, the first form returns nil, and the
* second form returns an empty array.
*
* a = [ "q", "r", "s", "t" ]
* a.first #=> "q"
* a.first(2) #=> ["q", "r"]
*/
static VALUE
rb_ary_first(int argc, VALUE *argv, VALUE ary)
{
if (argc == 0) {
if (RARRAY_LEN(ary) == 0) return Qnil;
return RARRAY_PTR(ary)[0];
}
else {
return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
}
}
/*
* call-seq:
* array.last -> obj or nil
* array.last(n) -> an_array
*
* Returns the last element(s) of self. If the array is empty,
* the first form returns nil.
*
* a = [ "w", "x", "y", "z" ]
* a.last #=> "z"
* a.last(2) #=> ["y", "z"]
*/
VALUE
rb_ary_last(int argc, VALUE *argv, VALUE ary)
{
if (argc == 0) {
if (RARRAY_LEN(ary) == 0) return Qnil;
return RARRAY_PTR(ary)[RARRAY_LEN(ary)-1];
}
else {
return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
}
}
/*
* call-seq:
* array.fetch(index) -> obj
* array.fetch(index, default ) -> obj
* array.fetch(index) {|index| block } -> obj
*
* Tries to return the element at position index. If the index
* lies outside the array, the first form throws an
* IndexError exception, the second form returns
* default, and the third form returns the value of invoking
* the block, passing in the index. Negative values of index
* count from the end of the array.
*
* a = [ 11, 22, 33, 44 ]
* a.fetch(1) #=> 22
* a.fetch(-1) #=> 44
* a.fetch(4, 'cat') #=> "cat"
* a.fetch(4) { |i| i*i } #=> 16
*/
static VALUE
rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
{
VALUE pos, ifnone;
long block_given;
long idx;
rb_scan_args(argc, argv, "11", &pos, &ifnone);
block_given = rb_block_given_p();
if (block_given && argc == 2) {
rb_warn("block supersedes default value argument");
}
idx = NUM2LONG(pos);
if (idx < 0) {
idx += RARRAY_LEN(ary);
}
if (idx < 0 || RARRAY_LEN(ary) <= idx) {
if (block_given) return rb_yield(pos);
if (argc == 1) {
rb_raise(rb_eIndexError, "index %ld out of array", idx);
}
return ifnone;
}
return RARRAY_PTR(ary)[idx];
}
/*
* call-seq:
* array.index(obj) -> int or nil
* array.index {|item| block} -> int or nil
*
* Returns the index of the first object in self such that is
* == to obj. If a block is given instead of an
* argument, returns first object for which block is true.
* Returns nil if no match is found.
*
* a = [ "a", "b", "c" ]
* a.index("b") #=> 1
* a.index("z") #=> nil
* a.index{|x|x=="b"} #=> 1
*
* This is an alias of #find_index.
*/
static VALUE
rb_ary_index(int argc, VALUE *argv, VALUE ary)
{
VALUE val;
long i;
if (argc == 0) {
RETURN_ENUMERATOR(ary, 0, 0);
for (i=0; i int or nil
*
* Returns the index of the last object in array
* == to obj. If a block is given instead of an
* argument, returns first object for which block is
* true. Returns nil if no match is found.
*
* a = [ "a", "b", "b", "b", "c" ]
* a.rindex("b") #=> 3
* a.rindex("z") #=> nil
* a.rindex{|x|x=="b"} #=> 3
*/
static VALUE
rb_ary_rindex(int argc, VALUE *argv, VALUE ary)
{
VALUE val;
long i = RARRAY_LEN(ary);
if (argc == 0) {
RETURN_ENUMERATOR(ary, 0, 0);
while (i--) {
if (RTEST(rb_yield(RARRAY_PTR(ary)[i])))
return LONG2NUM(i);
if (i > RARRAY_LEN(ary)) {
i = RARRAY_LEN(ary);
}
}
return Qnil;
}
rb_scan_args(argc, argv, "01", &val);
while (i--) {
if (rb_equal(RARRAY_PTR(ary)[i], val))
return LONG2NUM(i);
if (i > RARRAY_LEN(ary)) {
i = RARRAY_LEN(ary);
}
}
return Qnil;
}
VALUE
rb_ary_to_ary(VALUE obj)
{
if (TYPE(obj) == T_ARRAY) {
return obj;
}
if (rb_respond_to(obj, rb_intern("to_ary"))) {
return to_ary(obj);
}
return rb_ary_new3(1, obj);
}
static void
rb_ary_splice(VALUE ary, long beg, long len, VALUE rpl)
{
long rlen;
if (len < 0) rb_raise(rb_eIndexError, "negative length (%ld)", len);
if (beg < 0) {
beg += RARRAY_LEN(ary);
if (beg < 0) {
beg -= RARRAY_LEN(ary);
rb_raise(rb_eIndexError, "index %ld out of array", beg);
}
}
if (RARRAY_LEN(ary) < len || RARRAY_LEN(ary) < beg + len) {
len = RARRAY_LEN(ary) - beg;
}
if (rpl == Qundef) {
rlen = 0;
}
else {
rpl = rb_ary_to_ary(rpl);
rlen = RARRAY_LEN(rpl);
}
rb_ary_modify(ary);
if (beg >= RARRAY_LEN(ary)) {
if (beg > ARY_MAX_SIZE - rlen) {
rb_raise(rb_eIndexError, "index %ld too big", beg);
}
len = beg + rlen;
if (len >= ARY_CAPA(ary)) {
ary_resize_capa(ary, len);
}
rb_mem_clear(RARRAY_PTR(ary) + RARRAY_LEN(ary), beg - RARRAY_LEN(ary));
if (rlen > 0) {
MEMCPY(RARRAY_PTR(ary) + beg, RARRAY_PTR(rpl), VALUE, rlen);
}
ARY_SET_LEN(ary, len);
}
else {
long alen;
alen = RARRAY_LEN(ary) + rlen - len;
if (alen >= ARY_CAPA(ary)) {
ary_resize_capa(ary, alen);
}
if (len != rlen) {
MEMMOVE(RARRAY_PTR(ary) + beg + rlen, RARRAY_PTR(ary) + beg + len,
VALUE, RARRAY_LEN(ary) - (beg + len));
ARY_SET_LEN(ary, alen);
}
if (rlen > 0) {
MEMMOVE(RARRAY_PTR(ary) + beg, RARRAY_PTR(rpl), VALUE, rlen);
}
}
}
/*
* call-seq:
* array[index] = obj -> obj
* array[start, length] = obj or an_array or nil -> obj or an_array or nil
* array[range] = obj or an_array or nil -> obj or an_array or nil
*
* Element Assignment---Sets the element at _index_,
* or replaces a subarray starting at _start_ and
* continuing for _length_ elements, or replaces a subarray
* specified by _range_. If indices are greater than
* the current capacity of the array, the array grows
* automatically. A negative indices will count backward
* from the end of the array. Inserts elements if _length_ is
* zero. An +IndexError+ is raised if a negative index points
* past the beginning of the array. See also
* Array#push, and Array#unshift.
*
* a = Array.new
* a[4] = "4"; #=> [nil, nil, nil, nil, "4"]
* a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
* a[1..2] = [ 1, 2 ] #=> ["a", 1, 2, nil, "4"]
* a[0, 2] = "?" #=> ["?", 2, nil, "4"]
* a[0..2] = "A" #=> ["A", "4"]
* a[-1] = "Z" #=> ["A", "Z"]
* a[1..-1] = nil #=> ["A", nil]
* a[1..-1] = [] #=> ["A"]
*/
static VALUE
rb_ary_aset(int argc, VALUE *argv, VALUE ary)
{
long offset, beg, len;
if (argc == 3) {
beg = NUM2LONG(argv[0]);
len = NUM2LONG(argv[1]);
rb_ary_splice(ary, beg, len, argv[2]);
return argv[2];
}
if (argc != 2) {
rb_raise(rb_eArgError, "wrong number of arguments (%d for 2)", argc);
}
if (FIXNUM_P(argv[0])) {
offset = FIX2LONG(argv[0]);
goto fixnum;
}
if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) {
/* check if idx is Range */
rb_ary_splice(ary, beg, len, argv[1]);
return argv[1];
}
offset = NUM2LONG(argv[0]);
fixnum:
rb_ary_store(ary, offset, argv[1]);
return argv[1];
}
/*
* call-seq:
* array.insert(index, obj...) -> array
*
* Inserts the given values before the element with the given index
* (which may be negative).
*
* a = %w{ a b c d }
* a.insert(2, 99) #=> ["a", "b", 99, "c", "d"]
* a.insert(-2, 1, 2, 3) #=> ["a", "b", 99, "c", 1, 2, 3, "d"]
*/
static VALUE
rb_ary_insert(int argc, VALUE *argv, VALUE ary)
{
long pos;
if (argc == 1) return ary;
if (argc < 1) {
rb_raise(rb_eArgError, "wrong number of arguments (at least 1)");
}
pos = NUM2LONG(argv[0]);
if (pos == -1) {
pos = RARRAY_LEN(ary);
}
if (pos < 0) {
pos++;
}
rb_ary_splice(ary, pos, 0, rb_ary_new4(argc - 1, argv + 1));
return ary;
}
/*
* call-seq:
* array.each {|item| block } -> array
*
* Calls block once for each element in self, passing that
* element as a parameter.
*
* a = [ "a", "b", "c" ]
* a.each {|x| print x, " -- " }
*
* produces:
*
* a -- b -- c --
*/
VALUE
rb_ary_each(VALUE ary)
{
long i;
RETURN_ENUMERATOR(ary, 0, 0);
for (i=0; i array
*
* Same as Array#each, but passes the index of the element
* instead of the element itself.
*
* a = [ "a", "b", "c" ]
* a.each_index {|x| print x, " -- " }
*
* produces:
*
* 0 -- 1 -- 2 --
*/
static VALUE
rb_ary_each_index(VALUE ary)
{
long i;
RETURN_ENUMERATOR(ary, 0, 0);
for (i=0; iArray#each , but traverses self in reverse
* order.
*
* a = [ "a", "b", "c" ]
* a.reverse_each {|x| print x, " " }
*
* produces:
*
* c b a
*/
static VALUE
rb_ary_reverse_each(VALUE ary)
{
long len;
RETURN_ENUMERATOR(ary, 0, 0);
len = RARRAY_LEN(ary);
while (len--) {
rb_yield(RARRAY_PTR(ary)[len]);
if (RARRAY_LEN(ary) < len) {
len = RARRAY_LEN(ary);
}
}
return ary;
}
/*
* call-seq:
* array.length -> int
*
* Returns the number of elements in self. May be zero.
*
* [ 1, 2, 3, 4, 5 ].length #=> 5
*/
static VALUE
rb_ary_length(VALUE ary)
{
long len = RARRAY_LEN(ary);
return LONG2NUM(len);
}
/*
* call-seq:
* array.empty? -> true or false
*
* Returns true if self array contains no elements.
*
* [].empty? #=> true
*/
static VALUE
rb_ary_empty_p(VALUE ary)
{
if (RARRAY_LEN(ary) == 0)
return Qtrue;
return Qfalse;
}
VALUE
rb_ary_dup(VALUE ary)
{
VALUE dup = rb_ary_new2(RARRAY_LEN(ary));
int is_embed = ARY_EMBED_P(dup);
DUPSETUP(dup, ary);
if (is_embed) FL_SET_EMBED(dup);
MEMCPY(RARRAY_PTR(dup), RARRAY_PTR(ary), VALUE, RARRAY_LEN(ary));
ARY_SET_LEN(dup, RARRAY_LEN(ary));
return dup;
}
extern VALUE rb_output_fs;
static VALUE
recursive_join(VALUE ary, VALUE argp, int recur)
{
VALUE *arg = (VALUE *)argp;
if (recur) {
return rb_usascii_str_new2("[...]");
}
return rb_ary_join(arg[0], arg[1]);
}
VALUE
rb_ary_join(VALUE ary, VALUE sep)
{
long len = 1, i;
int taint = Qfalse;
int untrust = Qfalse;
VALUE result, tmp;
if (RARRAY_LEN(ary) == 0) return rb_str_new(0, 0);
if (OBJ_TAINTED(ary) || OBJ_TAINTED(sep)) taint = Qtrue;
if (OBJ_UNTRUSTED(ary) || OBJ_UNTRUSTED(sep)) untrust = Qtrue;
for (i=0; i 0 && !NIL_P(sep))
rb_str_buf_append(result, sep);
rb_str_buf_append(result, tmp);
if (OBJ_TAINTED(tmp)) taint = Qtrue;
if (OBJ_UNTRUSTED(tmp)) untrust = Qtrue;
}
if (taint) OBJ_TAINT(result);
if (untrust) OBJ_UNTRUST(result);
return result;
}
/*
* call-seq:
* array.join(sep=$,) -> str
*
* Returns a string created by converting each element of the array to
* a string, separated by sep.
*
* [ "a", "b", "c" ].join #=> "abc"
* [ "a", "b", "c" ].join("-") #=> "a-b-c"
*/
static VALUE
rb_ary_join_m(int argc, VALUE *argv, VALUE ary)
{
VALUE sep;
rb_scan_args(argc, argv, "01", &sep);
if (NIL_P(sep)) sep = rb_output_fs;
return rb_ary_join(ary, sep);
}
static VALUE
inspect_ary(VALUE ary, VALUE dummy, int recur)
{
int tainted = OBJ_TAINTED(ary);
int untrust = OBJ_UNTRUSTED(ary);
long i;
VALUE s, str;
if (recur) return rb_tainted_str_new2("[...]");
str = rb_str_buf_new2("[");
for (i=0; i 0) rb_str_buf_cat2(str, ", ");
rb_str_buf_append(str, s);
}
rb_str_buf_cat2(str, "]");
if (tainted) OBJ_TAINT(str);
if (untrust) OBJ_UNTRUST(str);
return str;
}
/*
* call-seq:
* array.to_s -> string
* array.inspect -> string
*
* Create a printable version of array.
*/
static VALUE
rb_ary_inspect(VALUE ary)
{
if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]");
return rb_exec_recursive(inspect_ary, ary, 0);
}
VALUE
rb_ary_to_s(VALUE ary)
{
return rb_ary_inspect(ary);
}
/*
* call-seq:
* array.to_a -> array
*
* Returns _self_. If called on a subclass of Array, converts
* the receiver to an Array object.
*/
static VALUE
rb_ary_to_a(VALUE ary)
{
if (rb_obj_class(ary) != rb_cArray) {
VALUE dup = rb_ary_new2(RARRAY_LEN(ary));
rb_ary_replace(dup, ary);
return dup;
}
return ary;
}
/*
* call-seq:
* array.to_ary -> array
*
* Returns _self_.
*/
static VALUE
rb_ary_to_ary_m(VALUE ary)
{
return ary;
}
VALUE
rb_ary_reverse(VALUE ary)
{
VALUE *p1, *p2;
VALUE tmp;
rb_ary_modify(ary);
if (RARRAY_LEN(ary) > 1) {
p1 = RARRAY_PTR(ary);
p2 = p1 + RARRAY_LEN(ary) - 1; /* points last item */
while (p1 < p2) {
tmp = *p1;
*p1++ = *p2;
*p2-- = tmp;
}
}
return ary;
}
/*
* call-seq:
* array.reverse! -> array
*
* Reverses _self_ in place.
*
* a = [ "a", "b", "c" ]
* a.reverse! #=> ["c", "b", "a"]
* a #=> ["c", "b", "a"]
*/
static VALUE
rb_ary_reverse_bang(VALUE ary)
{
return rb_ary_reverse(ary);
}
/*
* call-seq:
* array.reverse -> an_array
*
* Returns a new array containing self's elements in reverse order.
*
* [ "a", "b", "c" ].reverse #=> ["c", "b", "a"]
* [ 1 ].reverse #=> [1]
*/
static VALUE
rb_ary_reverse_m(VALUE ary)
{
return rb_ary_reverse(rb_ary_dup(ary));
}
struct ary_sort_data {
VALUE ary;
int opt_methods;
int opt_inited;
};
enum {
sort_opt_Fixnum,
sort_opt_String,
sort_optimizable_count
};
#define STRING_P(s) (TYPE(s) == T_STRING && CLASS_OF(s) == rb_cString)
#define SORT_OPTIMIZABLE_BIT(type) (1U << TOKEN_PASTE(sort_opt_,type))
#define SORT_OPTIMIZABLE(data, type) \
((data->opt_inited & SORT_OPTIMIZABLE_BIT(type)) ? \
(data->opt_methods & SORT_OPTIMIZABLE_BIT(type)) : \
((data->opt_inited |= SORT_OPTIMIZABLE_BIT(type)), \
rb_method_basic_definition_p(TOKEN_PASTE(rb_c,type), id_cmp) && \
(data->opt_methods |= SORT_OPTIMIZABLE_BIT(type))))
static VALUE
sort_reentered(VALUE ary)
{
if (RBASIC(ary)->klass) {
rb_raise(rb_eRuntimeError, "sort reentered");
}
return Qnil;
}
static int
sort_1(const void *ap, const void *bp, void *dummy)
{
struct ary_sort_data *data = dummy;
VALUE retval = sort_reentered(data->ary);
VALUE a = *(const VALUE *)ap, b = *(const VALUE *)bp;
int n;
retval = rb_yield_values(2, a, b);
n = rb_cmpint(retval, a, b);
sort_reentered(data->ary);
return n;
}
static int
sort_2(const void *ap, const void *bp, void *dummy)
{
struct ary_sort_data *data = dummy;
VALUE retval = sort_reentered(data->ary);
VALUE a = *(const VALUE *)ap, b = *(const VALUE *)bp;
int n;
if (FIXNUM_P(a) && FIXNUM_P(b) && SORT_OPTIMIZABLE(data, Fixnum)) {
if ((long)a > (long)b) return 1;
if ((long)a < (long)b) return -1;
return 0;
}
if (STRING_P(a) && STRING_P(b) && SORT_OPTIMIZABLE(data, String)) {
return rb_str_cmp(a, b);
}
retval = rb_funcall(a, id_cmp, 1, b);
n = rb_cmpint(retval, a, b);
sort_reentered(data->ary);
return n;
}
/*
* call-seq:
* array.sort! -> array
* array.sort! {| a,b | block } -> array
*
* Sorts _self_. Comparisons for
* the sort will be done using the <=> operator or using
* an optional code block. The block implements a comparison between
* a and b, returning -1, 0, or +1. See also
* Enumerable#sort_by.
*
* a = [ "d", "a", "e", "c", "b" ]
* a.sort #=> ["a", "b", "c", "d", "e"]
* a.sort {|x,y| y <=> x } #=> ["e", "d", "c", "b", "a"]
*/
VALUE
rb_ary_sort_bang(VALUE ary)
{
rb_ary_modify(ary);
assert(!ARY_SHARED_P(ary));
if (RARRAY_LEN(ary) > 1) {
VALUE tmp = ary_make_substitution(ary); /* only ary refers tmp */
struct ary_sort_data data;
RBASIC(tmp)->klass = 0;
data.ary = tmp;
data.opt_methods = 0;
data.opt_inited = 0;
ruby_qsort(RARRAY_PTR(tmp), RARRAY_LEN(tmp), sizeof(VALUE),
rb_block_given_p()?sort_1:sort_2, &data);
if (ARY_EMBED_P(tmp)) {
assert(ARY_EMBED_P(tmp));
if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */
rb_ary_unshare(ary);
}
FL_SET_EMBED(ary);
MEMCPY(RARRAY_PTR(ary), ARY_EMBED_PTR(tmp), VALUE, ARY_EMBED_LEN(tmp));
ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp));
}
else {
assert(!ARY_EMBED_P(tmp));
if (ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) {
assert(!ARY_EMBED_P(ary));
FL_UNSET_SHARED(ary);
ARY_SET_CAPA(ary, ARY_CAPA(tmp));
}
else {
assert(!ARY_SHARED_P(tmp));
if (ARY_EMBED_P(ary)) {
FL_UNSET_EMBED(ary);
}
else if (ARY_SHARED_P(ary)) {
/* ary might be destructively operated in the given block */
rb_ary_unshare(ary);
}
else {
xfree(ARY_HEAP_PTR(ary));
}
ARY_SET_PTR(ary, RARRAY_PTR(tmp));
ARY_SET_HEAP_LEN(ary, RARRAY_LEN(tmp));
ARY_SET_CAPA(ary, ARY_CAPA(tmp));
}
/* tmp was lost ownership for the ptr */
FL_UNSET(tmp, FL_FREEZE);
FL_SET_EMBED(tmp);
ARY_SET_EMBED_LEN(tmp, 0);
FL_SET(tmp, FL_FREEZE);
}
/* tmp will be GC'ed. */
RBASIC(tmp)->klass = rb_cArray;
}
return ary;
}
/*
* call-seq:
* array.sort -> an_array
* array.sort {| a,b | block } -> an_array
*
* Returns a new array created by sorting self. Comparisons for
* the sort will be done using the <=> operator or using
* an optional code block. The block implements a comparison between
* a and b, returning -1, 0, or +1. See also
* Enumerable#sort_by.
*
* a = [ "d", "a", "e", "c", "b" ]
* a.sort #=> ["a", "b", "c", "d", "e"]
* a.sort {|x,y| y <=> x } #=> ["e", "d", "c", "b", "a"]
*/
VALUE
rb_ary_sort(VALUE ary)
{
ary = rb_ary_dup(ary);
rb_ary_sort_bang(ary);
return ary;
}
/*
* call-seq:
* array.collect {|item| block } -> an_array
* array.map {|item| block } -> an_array
*
* Invokes block once for each element of self. Creates a
* new array containing the values returned by the block.
* See also Enumerable#collect.
*
* a = [ "a", "b", "c", "d" ]
* a.collect {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"]
* a #=> ["a", "b", "c", "d"]
*/
static VALUE
rb_ary_collect(VALUE ary)
{
long i;
VALUE collect;
RETURN_ENUMERATOR(ary, 0, 0);
collect = rb_ary_new2(RARRAY_LEN(ary));
for (i = 0; i < RARRAY_LEN(ary); i++) {
rb_ary_push(collect, rb_yield(RARRAY_PTR(ary)[i]));
}
return collect;
}
/*
* call-seq:
* array.collect! {|item| block } -> array
* array.map! {|item| block } -> array
*
* Invokes the block once for each element of _self_, replacing the
* element with the value returned by _block_.
* See also Enumerable#collect.
*
* a = [ "a", "b", "c", "d" ]
* a.collect! {|x| x + "!" }
* a #=> [ "a!", "b!", "c!", "d!" ]
*/
static VALUE
rb_ary_collect_bang(VALUE ary)
{
long i;
RETURN_ENUMERATOR(ary, 0, 0);
rb_ary_modify(ary);
for (i = 0; i < RARRAY_LEN(ary); i++) {
rb_ary_store(ary, i, rb_yield(RARRAY_PTR(ary)[i]));
}
return ary;
}
VALUE
rb_get_values_at(VALUE obj, long olen, int argc, VALUE *argv, VALUE (*func) (VALUE, long))
{
VALUE result = rb_ary_new2(argc);
long beg, len, i, j;
for (i=0; i an_array
*
* Returns an array containing the elements in
* _self_ corresponding to the given selector(s). The selectors
* may be either integer indices or ranges.
* See also Array#select.
*
* a = %w{ a b c d e f }
* a.values_at(1, 3, 5)
* a.values_at(1, 3, 5, 7)
* a.values_at(-1, -3, -5, -7)
* a.values_at(1..3, 2...5)
*/
static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
return rb_get_values_at(ary, RARRAY_LEN(ary), argc, argv, rb_ary_entry);
}
/*
* call-seq:
* array.select {|item| block } -> an_array
*
* Invokes the block passing in successive elements from array,
* returning an array containing those elements for which the block
* returns a true value (equivalent to Enumerable#select).
*
* a = %w{ a b c d e f }
* a.select {|v| v =~ /[aeiou]/} #=> ["a", "e"]
*/
static VALUE
rb_ary_select(VALUE ary)
{
VALUE result;
long i;
RETURN_ENUMERATOR(ary, 0, 0);
result = rb_ary_new2(RARRAY_LEN(ary));
for (i = 0; i < RARRAY_LEN(ary); i++) {
if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
rb_ary_push(result, rb_ary_elt(ary, i));
}
}
return result;
}
/*
* call-seq:
* array.delete(obj) -> obj or nil
* array.delete(obj) { block } -> obj or nil
*
* Deletes items from self that are equal to obj. If
* the item is not found, returns nil. If the optional
* code block is given, returns the result of block if the item
* is not found.
*
* a = [ "a", "b", "b", "b", "c" ]
* a.delete("b") #=> "b"
* a #=> ["a", "c"]
* a.delete("z") #=> nil
* a.delete("z") { "not found" } #=> "not found"
*/
VALUE
rb_ary_delete(VALUE ary, VALUE item)
{
VALUE v = item;
long i1, i2;
for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
VALUE e = RARRAY_PTR(ary)[i1];
if (rb_equal(e, item)) {
v = e;
continue;
}
if (i1 != i2) {
rb_ary_store(ary, i2, e);
}
i2++;
}
if (RARRAY_LEN(ary) == i2) {
if (rb_block_given_p()) {
return rb_yield(item);
}
return Qnil;
}
rb_ary_modify(ary);
if (RARRAY_LEN(ary) > i2) {
ARY_SET_LEN(ary, i2);
if (i2 * 2 < ARY_CAPA(ary) &&
ARY_CAPA(ary) > ARY_DEFAULT_SIZE) {
ary_resize_capa(ary, i2*2);
}
}
return v;
}
VALUE
rb_ary_delete_at(VALUE ary, long pos)
{
long len = RARRAY_LEN(ary);
VALUE del;
if (pos >= len) return Qnil;
if (pos < 0) {
pos += len;
if (pos < 0) return Qnil;
}
rb_ary_modify(ary);
del = RARRAY_PTR(ary)[pos];
MEMMOVE(RARRAY_PTR(ary)+pos, RARRAY_PTR(ary)+pos+1, VALUE,
RARRAY_LEN(ary)-pos-1);
ARY_INCREASE_LEN(ary, -1);
return del;
}
/*
* call-seq:
* array.delete_at(index) -> obj or nil
*
* Deletes the element at the specified index, returning that element,
* or nil if the index is out of range. See also
* Array#slice!.
*
* a = %w( ant bat cat dog )
* a.delete_at(2) #=> "cat"
* a #=> ["ant", "bat", "dog"]
* a.delete_at(99) #=> nil
*/
static VALUE
rb_ary_delete_at_m(VALUE ary, VALUE pos)
{
return rb_ary_delete_at(ary, NUM2LONG(pos));
}
/*
* call-seq:
* array.slice!(index) -> obj or nil
* array.slice!(start, length) -> sub_array or nil
* array.slice!(range) -> sub_array or nil
*
* Deletes the element(s) given by an index (optionally with a length)
* or by a range. Returns the deleted object, subarray, or
* nil if the index is out of range.
*
* a = [ "a", "b", "c" ]
* a.slice!(1) #=> "b"
* a #=> ["a", "c"]
* a.slice!(-1) #=> "c"
* a #=> ["a"]
* a.slice!(100) #=> nil
* a #=> ["a"]
*/
static VALUE
rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary)
{
VALUE arg1, arg2;
long pos, len, orig_len;
rb_ary_modify_check(ary);
if (rb_scan_args(argc, argv, "11", &arg1, &arg2) == 2) {
pos = NUM2LONG(arg1);
len = NUM2LONG(arg2);
delete_pos_len:
if (len < 0) return Qnil;
orig_len = RARRAY_LEN(ary);
if (pos < 0) {
pos += orig_len;
if (pos < 0) return Qnil;
}
else if (orig_len < pos) return Qnil;
if (orig_len < pos + len) {
len = orig_len - pos;
}
if (len == 0) return rb_ary_new2(0);
arg2 = rb_ary_new4(len, RARRAY_PTR(ary)+pos);
RBASIC(arg2)->klass = rb_obj_class(ary);
rb_ary_splice(ary, pos, len, Qundef);
return arg2;
}
if (!FIXNUM_P(arg1)) {
switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) {
case Qtrue:
/* valid range */
goto delete_pos_len;
case Qnil:
/* invalid range */
return Qnil;
default:
/* not a range */
break;
}
}
return rb_ary_delete_at(ary, NUM2LONG(arg1));
}
/*
* call-seq:
* array.reject! {|item| block } -> array or nil
*
* Equivalent to Array#delete_if, deleting elements from
* _self_ for which the block evaluates to true, but returns
* nil if no changes were made. Also see
* Enumerable#reject.
*/
static VALUE
rb_ary_reject_bang(VALUE ary)
{
long i1, i2;
RETURN_ENUMERATOR(ary, 0, 0);
rb_ary_modify(ary);
for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
VALUE v = RARRAY_PTR(ary)[i1];
if (RTEST(rb_yield(v))) continue;
if (i1 != i2) {
rb_ary_store(ary, i2, v);
}
i2++;
}
if (RARRAY_LEN(ary) == i2) return Qnil;
if (i2 < RARRAY_LEN(ary))
ARY_SET_LEN(ary, i2);
return ary;
}
/*
* call-seq:
* array.reject {|item| block } -> an_array
*
* Returns a new array containing the items in _self_
* for which the block is not true.
*/
static VALUE
rb_ary_reject(VALUE ary)
{
RETURN_ENUMERATOR(ary, 0, 0);
ary = rb_ary_dup(ary);
rb_ary_reject_bang(ary);
return ary;
}
/*
* call-seq:
* array.delete_if {|item| block } -> array
*
* Deletes every element of self for which block evaluates
* to true.
*
* a = [ "a", "b", "c" ]
* a.delete_if {|x| x >= "b" } #=> ["a"]
*/
static VALUE
rb_ary_delete_if(VALUE ary)
{
RETURN_ENUMERATOR(ary, 0, 0);
rb_ary_reject_bang(ary);
return ary;
}
static VALUE
take_i(VALUE val, VALUE *args, int argc, VALUE *argv)
{
if (args[1]-- == 0) rb_iter_break();
if (argc > 1) val = rb_ary_new4(argc, argv);
rb_ary_push(args[0], val);
return Qnil;
}
static VALUE
take_items(VALUE obj, long n)
{
VALUE result = rb_check_array_type(obj);
VALUE args[2];
if (!NIL_P(result)) return rb_ary_subseq(result, 0, n);
result = rb_ary_new2(n);
args[0] = result; args[1] = (VALUE)n;
rb_block_call(obj, rb_intern("each"), 0, 0, take_i, (VALUE)args);
return result;
}
/*
* call-seq:
* array.zip(arg, ...) -> an_array
* array.zip(arg, ...) {| arr | block } -> nil
*
* Converts any arguments to arrays, then merges elements of
* self with corresponding elements from each argument. This
* generates a sequence of self.size n-element
* arrays, where n is one more that the count of arguments. If
* the size of any argument is less than enumObj.size,
* nil values are supplied. If a block given, it is
* invoked for each output array, otherwise an array of arrays is
* returned.
*
* a = [ 4, 5, 6 ]
* b = [ 7, 8, 9 ]
* [1,2,3].zip(a, b) #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
* [1,2].zip(a,b) #=> [[1, 4, 7], [2, 5, 8]]
* a.zip([1,2],[8]) #=> [[4,1,8], [5,2,nil], [6,nil,nil]]
*/
static VALUE
rb_ary_zip(int argc, VALUE *argv, VALUE ary)
{
int i, j;
long len;
VALUE result = Qnil;
len = RARRAY_LEN(ary);
for (i=0; i an_array
*
* Assumes that self is an array of arrays and transposes the
* rows and columns.
*
* a = [[1,2], [3,4], [5,6]]
* a.transpose #=> [[1, 3, 5], [2, 4, 6]]
*/
static VALUE
rb_ary_transpose(VALUE ary)
{
long elen = -1, alen, i, j;
VALUE tmp, result = 0;
alen = RARRAY_LEN(ary);
if (alen == 0) return rb_ary_dup(ary);
for (i=0; i array
*
* Replaces the contents of self with the contents of
* other_array, truncating or expanding if necessary.
*
* a = [ "a", "b", "c", "d", "e" ]
* a.replace([ "x", "y", "z" ]) #=> ["x", "y", "z"]
* a #=> ["x", "y", "z"]
*/
VALUE
rb_ary_replace(VALUE copy, VALUE orig)
{
orig = to_ary(orig);
rb_ary_modify_check(copy);
if (copy == orig) return copy;
if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) {
VALUE *ptr;
VALUE shared = 0;
if (ARY_OWNS_HEAP_P(copy)) {
xfree(RARRAY_PTR(copy));
}
else if (ARY_SHARED_P(copy)) {
shared = ARY_SHARED(copy);
FL_UNSET_SHARED(copy);
}
FL_SET_EMBED(copy);
ptr = RARRAY_PTR(orig);
MEMCPY(RARRAY_PTR(copy), ptr, VALUE, RARRAY_LEN(orig));
if (shared) {
rb_ary_decrement_share(shared);
}
ARY_SET_LEN(copy, RARRAY_LEN(orig));
}
else {
VALUE shared = ary_make_shared(orig);
if (ARY_OWNS_HEAP_P(copy)) {
xfree(RARRAY_PTR(copy));
} else {
rb_ary_unshare_safe(copy);
}
FL_UNSET_EMBED(copy);
ARY_SET_PTR(copy, RARRAY_PTR(orig));
ARY_SET_LEN(copy, RARRAY_LEN(orig));
rb_ary_set_shared(copy, shared);
}
return copy;
}
/*
* call-seq:
* array.clear -> array
*
* Removes all elements from _self_.
*
* a = [ "a", "b", "c", "d", "e" ]
* a.clear #=> [ ]
*/
VALUE
rb_ary_clear(VALUE ary)
{
rb_ary_modify(ary);
ARY_SET_LEN(ary, 0);
if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2);
}
return ary;
}
/*
* call-seq:
* array.fill(obj) -> array
* array.fill(obj, start [, length]) -> array
* array.fill(obj, range ) -> array
* array.fill {|index| block } -> array
* array.fill(start [, length] ) {|index| block } -> array
* array.fill(range) {|index| block } -> array
*
* The first three forms set the selected elements of self (which
* may be the entire array) to obj. A start of
* nil is equivalent to zero. A length of
* nil is equivalent to self.length. The last three
* forms fill the array with the value of the block. The block is
* passed the absolute index of each element to be filled.
*
* a = [ "a", "b", "c", "d" ]
* a.fill("x") #=> ["x", "x", "x", "x"]
* a.fill("z", 2, 2) #=> ["x", "x", "z", "z"]
* a.fill("y", 0..1) #=> ["y", "y", "z", "z"]
* a.fill {|i| i*i} #=> [0, 1, 4, 9]
* a.fill(-2) {|i| i*i*i} #=> [0, 1, 8, 27]
*/
static VALUE
rb_ary_fill(int argc, VALUE *argv, VALUE ary)
{
VALUE item, arg1, arg2;
long beg = 0, end = 0, len = 0;
VALUE *p, *pend;
int block_p = Qfalse;
if (rb_block_given_p()) {
block_p = Qtrue;
rb_scan_args(argc, argv, "02", &arg1, &arg2);
argc += 1; /* hackish */
}
else {
rb_scan_args(argc, argv, "12", &item, &arg1, &arg2);
}
switch (argc) {
case 1:
beg = 0;
len = RARRAY_LEN(ary);
break;
case 2:
if (rb_range_beg_len(arg1, &beg, &len, RARRAY_LEN(ary), 1)) {
break;
}
/* fall through */
case 3:
beg = NIL_P(arg1) ? 0 : NUM2LONG(arg1);
if (beg < 0) {
beg = RARRAY_LEN(ary) + beg;
if (beg < 0) beg = 0;
}
len = NIL_P(arg2) ? RARRAY_LEN(ary) - beg : NUM2LONG(arg2);
break;
}
rb_ary_modify(ary);
if (len < 0) {
return ary;
}
if (beg >= ARY_MAX_SIZE || len > ARY_MAX_SIZE - beg) {
rb_raise(rb_eArgError, "argument too big");
}
end = beg + len;
if (RARRAY_LEN(ary) < end) {
if (end >= ARY_CAPA(ary)) {
ary_resize_capa(ary, end);
}
rb_mem_clear(RARRAY_PTR(ary) + RARRAY_LEN(ary), end - RARRAY_LEN(ary));
ARY_SET_LEN(ary, end);
}
if (block_p) {
VALUE v;
long i;
for (i=beg; i=RARRAY_LEN(ary)) break;
RARRAY_PTR(ary)[i] = v;
}
}
else {
p = RARRAY_PTR(ary) + beg;
pend = p + len;
while (p < pend) {
*p++ = item;
}
}
return ary;
}
/*
* call-seq:
* array + other_array -> an_array
*
* Concatenation---Returns a new array built by concatenating the
* two arrays together to produce a third array.
*
* [ 1, 2, 3 ] + [ 4, 5 ] #=> [ 1, 2, 3, 4, 5 ]
*/
VALUE
rb_ary_plus(VALUE x, VALUE y)
{
VALUE z;
long len;
y = to_ary(y);
len = RARRAY_LEN(x) + RARRAY_LEN(y);
z = rb_ary_new2(len);
MEMCPY(RARRAY_PTR(z), RARRAY_PTR(x), VALUE, RARRAY_LEN(x));
MEMCPY(RARRAY_PTR(z) + RARRAY_LEN(x), RARRAY_PTR(y), VALUE, RARRAY_LEN(y));
ARY_SET_LEN(z, len);
return z;
}
/*
* call-seq:
* array.concat(other_array) -> array
*
* Appends the elements in other_array to _self_.
*
* [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
*/
VALUE
rb_ary_concat(VALUE x, VALUE y)
{
y = to_ary(y);
if (RARRAY_LEN(y) > 0) {
rb_ary_splice(x, RARRAY_LEN(x), 0, y);
}
return x;
}
/*
* call-seq:
* array * int -> an_array
* array * str -> a_string
*
* Repetition---With a String argument, equivalent to
* self.join(str). Otherwise, returns a new array
* built by concatenating the _int_ copies of _self_.
*
*
* [ 1, 2, 3 ] * 3 #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
* [ 1, 2, 3 ] * "," #=> "1,2,3"
*
*/
static VALUE
rb_ary_times(VALUE ary, VALUE times)
{
VALUE ary2, tmp;
long i, len;
tmp = rb_check_string_type(times);
if (!NIL_P(tmp)) {
return rb_ary_join(ary, tmp);
}
len = NUM2LONG(times);
if (len == 0) {
ary2 = ary_new(rb_obj_class(ary), 0);
goto out;
}
if (len < 0) {
rb_raise(rb_eArgError, "negative argument");
}
if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) {
rb_raise(rb_eArgError, "argument too big");
}
len *= RARRAY_LEN(ary);
ary2 = ary_new(rb_obj_class(ary), len);
ARY_SET_LEN(ary2, len);
for (i=0; i an_array or nil
*
* Searches through an array whose elements are also arrays
* comparing _obj_ with the first element of each contained array
* using obj.==.
* Returns the first contained array that matches (that
* is, the first associated array),
* or +nil+ if no match is found.
* See also Array#rassoc.
*
* s1 = [ "colors", "red", "blue", "green" ]
* s2 = [ "letters", "a", "b", "c" ]
* s3 = "foo"
* a = [ s1, s2, s3 ]
* a.assoc("letters") #=> [ "letters", "a", "b", "c" ]
* a.assoc("foo") #=> nil
*/
VALUE
rb_ary_assoc(VALUE ary, VALUE key)
{
long i;
VALUE v;
for (i = 0; i < RARRAY_LEN(ary); ++i) {
v = rb_check_array_type(RARRAY_PTR(ary)[i]);
if (!NIL_P(v) && RARRAY_LEN(v) > 0 &&
rb_equal(RARRAY_PTR(v)[0], key))
return v;
}
return Qnil;
}
/*
* call-seq:
* array.rassoc(obj) -> an_array or nil
*
* Searches through the array whose elements are also arrays. Compares
* _obj_ with the second element of each contained array using
* ==. Returns the first contained array that matches. See
* also Array#assoc.
*
* a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
* a.rassoc("two") #=> [2, "two"]
* a.rassoc("four") #=> nil
*/
VALUE
rb_ary_rassoc(VALUE ary, VALUE value)
{
long i;
VALUE v;
for (i = 0; i < RARRAY_LEN(ary); ++i) {
v = RARRAY_PTR(ary)[i];
if (TYPE(v) == T_ARRAY &&
RARRAY_LEN(v) > 1 &&
rb_equal(RARRAY_PTR(v)[1], value))
return v;
}
return Qnil;
}
static VALUE
recursive_equal(VALUE ary1, VALUE ary2, int recur)
{
long i;
if (recur) return Qtrue; /* Subtle! */
for (i=0; i bool
*
* Equality---Two arrays are equal if they contain the same number
* of elements and if each element is equal to (according to
* Object.==) the corresponding element in the other array.
*
* [ "a", "c" ] == [ "a", "c", 7 ] #=> false
* [ "a", "c", 7 ] == [ "a", "c", 7 ] #=> true
* [ "a", "c", 7 ] == [ "a", "d", "f" ] #=> false
*
*/
static VALUE
rb_ary_equal(VALUE ary1, VALUE ary2)
{
if (ary1 == ary2) return Qtrue;
if (TYPE(ary2) != T_ARRAY) {
if (!rb_respond_to(ary2, rb_intern("to_ary"))) {
return Qfalse;
}
return rb_equal(ary2, ary1);
}
if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);
}
static VALUE
recursive_eql(VALUE ary1, VALUE ary2, int recur)
{
long i;
if (recur) return Qtrue; /* Subtle! */
for (i=0; i true or false
*
* Returns true if _array_ and _other_ are the same object,
* or are both arrays with the same content.
*/
static VALUE
rb_ary_eql(VALUE ary1, VALUE ary2)
{
if (ary1 == ary2) return Qtrue;
if (TYPE(ary2) != T_ARRAY) return Qfalse;
if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2);
}
static VALUE
recursive_hash(VALUE ary, VALUE dummy, int recur)
{
long i, h;
VALUE n;
if (recur) {
return LONG2FIX(0);
}
h = RARRAY_LEN(ary);
for (i=0; i fixnum
*
* Compute a hash-code for this array. Two arrays with the same content
* will have the same hash code (and will compare using eql?).
*/
static VALUE
rb_ary_hash(VALUE ary)
{
return rb_exec_recursive(recursive_hash, ary, 0);
}
/*
* call-seq:
* array.include?(obj) -> true or false
*
* Returns true if the given object is present in
* self (that is, if any object == anObject),
* false otherwise.
*
* a = [ "a", "b", "c" ]
* a.include?("b") #=> true
* a.include?("z") #=> false
*/
VALUE
rb_ary_includes(VALUE ary, VALUE item)
{
long i;
for (i=0; i RARRAY_LEN(ary2)) {
len = RARRAY_LEN(ary2);
}
for (i=0; i other_array -> -1, 0, +1
*
* Comparison---Returns an integer (-1, 0,
* or +1) if this array is less than, equal to, or greater than
* other_array. Each object in each array is compared
* (using <=>). If any value isn't
* equal, then that inequality is the return value. If all the
* values found are equal, then the return is based on a
* comparison of the array lengths. Thus, two arrays are
* ``equal'' according to Array#<=> if and only if they have
* the same length and the value of each element is equal to the
* value of the corresponding element in the other array.
*
* [ "a", "a", "c" ] <=> [ "a", "b", "c" ] #=> -1
* [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ] #=> +1
*
*/
VALUE
rb_ary_cmp(VALUE ary1, VALUE ary2)
{
long len;
VALUE v;
ary2 = to_ary(ary2);
if (ary1 == ary2) return INT2FIX(0);
v = rb_exec_recursive_paired(recursive_cmp, ary1, ary2, ary2);
if (v != Qundef) return v;
len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2);
if (len == 0) return INT2FIX(0);
if (len > 0) return INT2FIX(1);
return INT2FIX(-1);
}
static VALUE
ary_make_hash(VALUE ary1, VALUE ary2)
{
VALUE hash = rb_hash_new();
long i;
for (i=0; i an_array
*
* Array Difference---Returns a new array that is a copy of
* the original array, removing any items that also appear in
* other_array. (If you need set-like behavior, see the
* library class Set.)
*
* [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ] #=> [ 3, 3, 5 ]
*/
static VALUE
rb_ary_diff(VALUE ary1, VALUE ary2)
{
VALUE ary3;
volatile VALUE hash;
long i;
hash = ary_make_hash(to_ary(ary2), 0);
ary3 = rb_ary_new();
for (i=0; i [ 1, 3 ]
*/
static VALUE
rb_ary_and(VALUE ary1, VALUE ary2)
{
VALUE hash, ary3, v, vv;
long i;
ary2 = to_ary(ary2);
ary3 = rb_ary_new2(RARRAY_LEN(ary1) < RARRAY_LEN(ary2) ?
RARRAY_LEN(ary1) : RARRAY_LEN(ary2));
hash = ary_make_hash(ary2, 0);
if (RHASH_EMPTY_P(hash))
return ary3;
for (i=0; i an_array
*
* Set Union---Returns a new array by joining this array with
* other_array, removing duplicates.
*
* [ "a", "b", "c" ] | [ "c", "d", "a" ]
* #=> [ "a", "b", "c", "d" ]
*/
static VALUE
rb_ary_or(VALUE ary1, VALUE ary2)
{
VALUE hash, ary3;
VALUE v, vv;
long i;
ary2 = to_ary(ary2);
ary3 = rb_ary_new2(RARRAY_LEN(ary1)+RARRAY_LEN(ary2));
hash = ary_make_hash(ary1, ary2);
for (i=0; i array or nil
*
* Removes duplicate elements from _self_.
* Returns nil if no changes are made (that is, no
* duplicates are found).
*
* a = [ "a", "a", "b", "b", "c" ]
* a.uniq! #=> ["a", "b", "c"]
* b = [ "a", "b", "c" ]
* b.uniq! #=> nil
*/
static VALUE
rb_ary_uniq_bang(VALUE ary)
{
VALUE hash, v, vv;
long i, j;
hash = ary_make_hash(ary, 0);
if (RARRAY_LEN(ary) == RHASH_SIZE(hash)) {
return Qnil;
}
for (i=j=0; i an_array
*
* Returns a new array by removing duplicate values in self.
*
* a = [ "a", "a", "b", "b", "c" ]
* a.uniq #=> ["a", "b", "c"]
*/
static VALUE
rb_ary_uniq(VALUE ary)
{
ary = rb_ary_dup(ary);
rb_ary_uniq_bang(ary);
return ary;
}
/*
* call-seq:
* array.compact! -> array or nil
*
* Removes +nil+ elements from array.
* Returns +nil+ if no changes were made.
*
* [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
* [ "a", "b", "c" ].compact! #=> nil
*/
static VALUE
rb_ary_compact_bang(VALUE ary)
{
VALUE *p, *t, *end;
long n;
rb_ary_modify(ary);
p = t = RARRAY_PTR(ary);
end = p + RARRAY_LEN(ary);
while (t < end) {
if (NIL_P(*t)) t++;
else *p++ = *t++;
}
n = p - RARRAY_PTR(ary);
if (RARRAY_LEN(ary) == n) {
return Qnil;
}
ARY_SET_LEN(ary, n);
if (n * 2 < ARY_CAPA(ary) && ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
ary_resize_capa(ary, n * 2);
}
return ary;
}
/*
* call-seq:
* array.compact -> an_array
*
* Returns a copy of _self_ with all +nil+ elements removed.
*
* [ "a", nil, "b", nil, "c", nil ].compact
* #=> [ "a", "b", "c" ]
*/
static VALUE
rb_ary_compact(VALUE ary)
{
ary = rb_ary_dup(ary);
rb_ary_compact_bang(ary);
return ary;
}
/*
* call-seq:
* array.count -> int
* array.count(obj) -> int
* array.count { |item| block } -> int
*
* Returns the number of elements. If an argument is given, counts
* the number of elements which equals to obj. If a block is
* given, counts the number of elements yielding a true value.
*
* ary = [1, 2, 4, 2]
* ary.count # => 4
* ary.count(2) # => 2
* ary.count{|x|x%2==0} # => 3
*
*/
static VALUE
rb_ary_count(int argc, VALUE *argv, VALUE ary)
{
long n = 0;
if (argc == 0) {
VALUE *p, *pend;
if (!rb_block_given_p())
return LONG2NUM(RARRAY_LEN(ary));
for (p = RARRAY_PTR(ary), pend = p + RARRAY_LEN(ary); p < pend; p++) {
if (RTEST(rb_yield(*p))) n++;
}
}
else {
VALUE obj, *p, *pend;
rb_scan_args(argc, argv, "1", &obj);
if (rb_block_given_p()) {
rb_warn("given block not used");
}
for (p = RARRAY_PTR(ary), pend = p + RARRAY_LEN(ary); p < pend; p++) {
if (rb_equal(*p, obj)) n++;
}
}
return LONG2NUM(n);
}
static VALUE
flatten(VALUE ary, int level, int *modified)
{
long i = 0;
VALUE stack, result, tmp, elt;
st_table *memo;
st_data_t id;
stack = ary_new(0, ARY_DEFAULT_SIZE);
result = ary_new(0, RARRAY_LEN(ary));
memo = st_init_numtable();
st_insert(memo, (st_data_t)ary, (st_data_t)Qtrue);
*modified = 0;
while (1) {
while (i < RARRAY_LEN(ary)) {
elt = RARRAY_PTR(ary)[i++];
tmp = rb_check_array_type(elt);
if (RBASIC(result)->klass) {
rb_raise(rb_eRuntimeError, "flatten reentered");
}
if (NIL_P(tmp) || (level >= 0 && RARRAY_LEN(stack) / 2 >= level)) {
rb_ary_push(result, elt);
}
else {
*modified = 1;
id = (st_data_t)tmp;
if (st_lookup(memo, id, 0)) {
st_free_table(memo);
rb_raise(rb_eArgError, "tried to flatten recursive array");
}
st_insert(memo, id, (st_data_t)Qtrue);
rb_ary_push(stack, ary);
rb_ary_push(stack, LONG2NUM(i));
ary = tmp;
i = 0;
}
}
if (RARRAY_LEN(stack) == 0) {
break;
}
id = (st_data_t)ary;
st_delete(memo, &id, 0);
tmp = rb_ary_pop(stack);
i = NUM2LONG(tmp);
ary = rb_ary_pop(stack);
}
st_free_table(memo);
RBASIC(result)->klass = rb_class_of(ary);
return result;
}
/*
* call-seq:
* array.flatten! -> array or nil
* array.flatten!(level) -> array or nil
*
* Flattens _self_ in place.
* Returns nil if no modifications were made (i.e.,
* array contains no subarrays.) If the optional level
* argument determines the level of recursion to flatten.
*
* a = [ 1, 2, [3, [4, 5] ] ]
* a.flatten! #=> [1, 2, 3, 4, 5]
* a.flatten! #=> nil
* a #=> [1, 2, 3, 4, 5]
* a = [ 1, 2, [3, [4, 5] ] ]
* a.flatten!(1) #=> [1, 2, 3, [4, 5]]
*/
static VALUE
rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
{
int mod = 0, level = -1;
VALUE result, lv;
rb_scan_args(argc, argv, "01", &lv);
if (!NIL_P(lv)) level = NUM2INT(lv);
if (level == 0) return Qnil;
result = flatten(ary, level, &mod);
if (mod == 0) return Qnil;
rb_ary_replace(ary, result);
return ary;
}
/*
* call-seq:
* array.flatten -> an_array
* array.flatten(level) -> an_array
*
* Returns a new array that is a one-dimensional flattening of this
* array (recursively). That is, for every element that is an array,
* extract its elements into the new array. If the optional
* level argument determines the level of recursion to flatten.
*
* s = [ 1, 2, 3 ] #=> [1, 2, 3]
* t = [ 4, 5, 6, [7, 8] ] #=> [4, 5, 6, [7, 8]]
* a = [ s, t, 9, 10 ] #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
* a.flatten #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
* a = [ 1, 2, [3, [4, 5] ] ]
* a.flatten(1) #=> [1, 2, 3, [4, 5]]
*/
static VALUE
rb_ary_flatten(int argc, VALUE *argv, VALUE ary)
{
int mod = 0, level = -1;
VALUE result, lv;
rb_scan_args(argc, argv, "01", &lv);
if (!NIL_P(lv)) level = NUM2INT(lv);
if (level == 0) return ary_make_shared_copy(ary);
result = flatten(ary, level, &mod);
OBJ_INFECT(result, ary);
return result;
}
/*
* call-seq:
* array.shuffle! -> array
*
* Shuffles elements in _self_ in place.
*/
static VALUE
rb_ary_shuffle_bang(VALUE ary)
{
long i = RARRAY_LEN(ary);
rb_ary_modify(ary);
while (i) {
long j = rb_genrand_real()*i;
VALUE tmp = RARRAY_PTR(ary)[--i];
RARRAY_PTR(ary)[i] = RARRAY_PTR(ary)[j];
RARRAY_PTR(ary)[j] = tmp;
}
return ary;
}
/*
* call-seq:
* array.shuffle -> an_array
*
* Returns a new array with elements of this array shuffled.
*
* a = [ 1, 2, 3 ] #=> [1, 2, 3]
* a.shuffle #=> [2, 3, 1]
*/
static VALUE
rb_ary_shuffle(VALUE ary)
{
ary = rb_ary_dup(ary);
rb_ary_shuffle_bang(ary);
return ary;
}
/*
* call-seq:
* array.sample -> obj
* array.sample(n) -> an_array
*
* Choose a random element, or the random +n+ elements, from the array.
* If the array is empty, the first form returns nil, and the
* second form returns an empty array.
*
*/
static VALUE
rb_ary_sample(int argc, VALUE *argv, VALUE ary)
{
VALUE nv, result, *ptr;
long n, len, i, j, k, idx[10];
len = RARRAY_LEN(ary);
if (argc == 0) {
if (len == 0) return Qnil;
i = len == 1 ? 0 : rb_genrand_real()*len;
return RARRAY_PTR(ary)[i];
}
rb_scan_args(argc, argv, "1", &nv);
n = NUM2LONG(nv);
if (n < 0) rb_raise(rb_eArgError, "negative sample number");
ptr = RARRAY_PTR(ary);
len = RARRAY_LEN(ary);
if (n > len) n = len;
switch (n) {
case 0: return rb_ary_new2(0);
case 1:
return rb_ary_new4(1, &ptr[(long)(rb_genrand_real()*len)]);
case 2:
i = rb_genrand_real()*len;
j = rb_genrand_real()*(len-1);
if (j >= i) j++;
return rb_ary_new3(2, ptr[i], ptr[j]);
case 3:
i = rb_genrand_real()*len;
j = rb_genrand_real()*(len-1);
k = rb_genrand_real()*(len-2);
{
long l = j, g = i;
if (j >= i) l = i, g = ++j;
if (k >= l && (++k >= g)) ++k;
}
return rb_ary_new3(3, ptr[i], ptr[j], ptr[k]);
}
if (n < sizeof(idx)/sizeof(idx[0])) {
long sorted[sizeof(idx)/sizeof(idx[0])];
sorted[0] = idx[0] = rb_genrand_real()*len;
for (i=1; iblock for each element repeatedly _n_ times or
* forever if none or nil is given. If a non-positive number is
* given or the array is empty, does nothing. Returns nil if the
* loop has finished without getting interrupted.
*
* a = ["a", "b", "c"]
* a.cycle {|x| puts x } # print, a, b, c, a, b, c,.. forever.
* a.cycle(2) {|x| puts x } # print, a, b, c, a, b, c.
*
*/
static VALUE
rb_ary_cycle(int argc, VALUE *argv, VALUE ary)
{
long n, i;
VALUE nv = Qnil;
rb_scan_args(argc, argv, "01", &nv);
RETURN_ENUMERATOR(ary, argc, argv);
if (NIL_P(nv)) {
n = -1;
}
else {
n = NUM2LONG(nv);
if (n <= 0) return Qnil;
}
while (RARRAY_LEN(ary) > 0 && (n < 0 || 0 < n--)) {
for (i=0; i array
* ary.permutation -> enumerator
* ary.permutation(n) { |p| block } -> array
* ary.permutation(n) -> enumerator
*
* When invoked with a block, yield all permutations of length n
* of the elements of ary, then return the array itself.
* If n is not specified, yield all permutations of all elements.
* The implementation makes no guarantees about the order in which
* the permutations are yielded.
*
* When invoked without a block, return an enumerator object instead.
*
* Examples:
*
* a = [1, 2, 3]
* a.permutation.to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
* a.permutation(1).to_a #=> [[1],[2],[3]]
* a.permutation(2).to_a #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
* a.permutation(3).to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
* a.permutation(0).to_a #=> [[]] # one permutation of length 0
* a.permutation(4).to_a #=> [] # no permutations of length 4
*/
static VALUE
rb_ary_permutation(int argc, VALUE *argv, VALUE ary)
{
VALUE num;
long r, n, i;
n = RARRAY_LEN(ary); /* Array length */
RETURN_ENUMERATOR(ary, argc, argv); /* Return enumerator if no block */
rb_scan_args(argc, argv, "01", &num);
r = NIL_P(num) ? n : NUM2LONG(num); /* Permutation size from argument */
if (r < 0 || n < r) {
/* no permutations: yield nothing */
}
else if (r == 0) { /* exactly one permutation: the zero-length array */
rb_yield(rb_ary_new2(0));
}
else if (r == 1) { /* this is a special, easy case */
for (i = 0; i < RARRAY_LEN(ary); i++) {
rb_yield(rb_ary_new3(1, RARRAY_PTR(ary)[i]));
}
}
else { /* this is the general case */
volatile VALUE t0 = tmpbuf(n,sizeof(long));
long *p = (long*)RSTRING_PTR(t0);
volatile VALUE t1 = tmpbuf(n,sizeof(int));
int *used = (int*)RSTRING_PTR(t1);
VALUE ary0 = ary_make_substitution(ary); /* private defensive copy of ary */
RBASIC(ary0)->klass = 0;
for (i = 0; i < n; i++) used[i] = 0; /* initialize array */
permute0(n, r, p, 0, used, ary0); /* compute and yield permutations */
RB_GC_GUARD(t0);
RB_GC_GUARD(t1);
RBASIC(ary0)->klass = rb_cArray;
}
return ary;
}
static long
combi_len(long n, long k)
{
long i, val = 1;
if (k*2 > n) k = n-k;
if (k == 0) return 1;
if (k < 0) return 0;
val = 1;
for (i=1; i <= k; i++,n--) {
long m = val;
val *= n;
if (val < m) {
rb_raise(rb_eRangeError, "too big for combination");
}
val /= i;
}
return val;
}
/*
* call-seq:
* ary.combination(n) { |c| block } -> ary
* ary.combination(n) -> enumerator
*
* When invoked with a block, yields all combinations of length n
* of elements from ary and then returns ary itself.
* The implementation makes no guarantees about the order in which
* the combinations are yielded.
*
* When invoked without a block, returns an enumerator object instead.
*
* Examples:
*
* a = [1, 2, 3, 4]
* a.combination(1).to_a #=> [[1],[2],[3],[4]]
* a.combination(2).to_a #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
* a.combination(3).to_a #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
* a.combination(4).to_a #=> [[1,2,3,4]]
* a.combination(0).to_a #=> [[]] # one combination of length 0
* a.combination(5).to_a #=> [] # no combinations of length 5
*
*/
static VALUE
rb_ary_combination(VALUE ary, VALUE num)
{
long n, i, len;
n = NUM2LONG(num);
RETURN_ENUMERATOR(ary, 1, &num);
len = RARRAY_LEN(ary);
if (n < 0 || len < n) {
/* yield nothing */
}
else if (n == 0) {
rb_yield(rb_ary_new2(0));
}
else if (n == 1) {
for (i = 0; i < len; i++) {
rb_yield(rb_ary_new3(1, RARRAY_PTR(ary)[i]));
}
}
else {
volatile VALUE t0 = tmpbuf(n+1, sizeof(long));
long *stack = (long*)RSTRING_PTR(t0);
long nlen = combi_len(len, n);
volatile VALUE cc = rb_ary_new2(n);
VALUE *chosen = RARRAY_PTR(cc);
long lev = 0;
RBASIC(cc)->klass = 0;
MEMZERO(stack, long, n);
stack[0] = -1;
for (i = 0; i < nlen; i++) {
chosen[lev] = RARRAY_PTR(ary)[stack[lev+1]];
for (lev++; lev < n; lev++) {
chosen[lev] = RARRAY_PTR(ary)[stack[lev+1] = stack[lev]+1];
}
rb_yield(rb_ary_new4(n, chosen));
do {
stack[lev--]++;
} while (lev && (stack[lev+1]+n == len+lev+1));
}
}
return ary;
}
/*
* call-seq:
* ary.product(other_ary, ...)
*
* Returns an array of all combinations of elements from all arrays.
* The length of the returned array is the product of the length
* of ary and the argument arrays
*
* [1,2,3].product([4,5]) # => [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
* [1,2].product([1,2]) # => [[1,1],[1,2],[2,1],[2,2]]
* [1,2].product([3,4],[5,6]) # => [[1,3,5],[1,3,6],[1,4,5],[1,4,6],
* # [2,3,5],[2,3,6],[2,4,5],[2,4,6]]
* [1,2].product() # => [[1],[2]]
* [1,2].product([]) # => []
*/
static VALUE
rb_ary_product(int argc, VALUE *argv, VALUE ary)
{
int n = argc+1; /* How many arrays we're operating on */
volatile VALUE t0 = tmpbuf(n, sizeof(VALUE));
volatile VALUE t1 = tmpbuf(n, sizeof(int));
VALUE *arrays = (VALUE*)RSTRING_PTR(t0); /* The arrays we're computing the product of */
int *counters = (int*)RSTRING_PTR(t1); /* The current position in each one */
VALUE result; /* The array we'll be returning */
long i,j;
long resultlen = 1;
RBASIC(t0)->klass = 0;
RBASIC(t1)->klass = 0;
/* initialize the arrays of arrays */
arrays[0] = ary;
for (i = 1; i < n; i++) arrays[i] = to_ary(argv[i-1]);
/* initialize the counters for the arrays */
for (i = 0; i < n; i++) counters[i] = 0;
/* Compute the length of the result array; return [] if any is empty */
for (i = 0; i < n; i++) {
long k = RARRAY_LEN(arrays[i]), l = resultlen;
if (k == 0) return rb_ary_new2(0);
resultlen *= k;
if (resultlen < k || resultlen < l || resultlen / k != l) {
rb_raise(rb_eRangeError, "too big to product");
}
}
/* Otherwise, allocate and fill in an array of results */
result = rb_ary_new2(resultlen);
for (i = 0; i < resultlen; i++) {
int m;
/* fill in one subarray */
VALUE subarray = rb_ary_new2(n);
for (j = 0; j < n; j++) {
rb_ary_push(subarray, rb_ary_entry(arrays[j], counters[j]));
}
/* put it on the result array */
rb_ary_push(result, subarray);
/*
* Increment the last counter. If it overflows, reset to 0
* and increment the one before it.
*/
m = n-1;
counters[m]++;
while (m > 0 && counters[m] == RARRAY_LEN(arrays[m])) {
counters[m] = 0;
m--;
counters[m]++;
}
}
return result;
}
/*
* call-seq:
* ary.take(n) => array
*
* Returns first n elements from ary.
*
* a = [1, 2, 3, 4, 5, 0]
* a.take(3) # => [1, 2, 3]
*
*/
static VALUE
rb_ary_take(VALUE obj, VALUE n)
{
long len = NUM2LONG(n);
if (len < 0) {
rb_raise(rb_eArgError, "attempt to take negative size");
}
return rb_ary_subseq(obj, 0, len);
}
/*
* call-seq:
* ary.take_while {|arr| block } => array
*
* Passes elements to the block until the block returns nil or false,
* then stops iterating and returns an array of all prior elements.
*
* a = [1, 2, 3, 4, 5, 0]
* a.take_while {|i| i < 3 } # => [1, 2]
*
*/
static VALUE
rb_ary_take_while(VALUE ary)
{
long i;
RETURN_ENUMERATOR(ary, 0, 0);
for (i = 0; i < RARRAY_LEN(ary); i++) {
if (!RTEST(rb_yield(RARRAY_PTR(ary)[i]))) break;
}
return rb_ary_take(ary, LONG2FIX(i));
}
/*
* call-seq:
* ary.drop(n) => array
*
* Drops first n elements from ary, and returns rest elements
* in an array.
*
* a = [1, 2, 3, 4, 5, 0]
* a.drop(3) # => [4, 5, 0]
*
*/
static VALUE
rb_ary_drop(VALUE ary, VALUE n)
{
VALUE result;
long pos = NUM2LONG(n);
if (pos < 0) {
rb_raise(rb_eArgError, "attempt to drop negative size");
}
result = rb_ary_subseq(ary, pos, RARRAY_LEN(ary));
if (result == Qnil) result = rb_ary_new();
return result;
}
/*
* call-seq:
* ary.drop_while {|arr| block } => array
*
* Drops elements up to, but not including, the first element for
* which the block returns nil or false and returns an array
* containing the remaining elements.
*
* a = [1, 2, 3, 4, 5, 0]
* a.drop_while {|i| i < 3 } # => [3, 4, 5, 0]
*
*/
static VALUE
rb_ary_drop_while(VALUE ary)
{
long i;
RETURN_ENUMERATOR(ary, 0, 0);
for (i = 0; i < RARRAY_LEN(ary); i++) {
if (!RTEST(rb_yield(RARRAY_PTR(ary)[i]))) break;
}
return rb_ary_drop(ary, LONG2FIX(i));
}
/* Arrays are ordered, integer-indexed collections of any object.
* Array indexing starts at 0, as in C or Java. A negative index is
* assumed to be relative to the end of the array---that is, an index of -1
* indicates the last element of the array, -2 is the next to last
* element in the array, and so on.
*/
void
Init_Array(void)
{
#undef rb_intern
#define rb_intern(str) rb_intern_const(str)
rb_cArray = rb_define_class("Array", rb_cObject);
rb_include_module(rb_cArray, rb_mEnumerable);
rb_define_alloc_func(rb_cArray, ary_alloc);
rb_define_singleton_method(rb_cArray, "[]", rb_ary_s_create, -1);
rb_define_singleton_method(rb_cArray, "try_convert", rb_ary_s_try_convert, 1);
rb_define_method(rb_cArray, "initialize", rb_ary_initialize, -1);
rb_define_method(rb_cArray, "initialize_copy", rb_ary_replace, 1);
rb_define_method(rb_cArray, "to_s", rb_ary_inspect, 0);
rb_define_method(rb_cArray, "inspect", rb_ary_inspect, 0);
rb_define_method(rb_cArray, "to_a", rb_ary_to_a, 0);
rb_define_method(rb_cArray, "to_ary", rb_ary_to_ary_m, 0);
rb_define_method(rb_cArray, "frozen?", rb_ary_frozen_p, 0);
rb_define_method(rb_cArray, "==", rb_ary_equal, 1);
rb_define_method(rb_cArray, "eql?", rb_ary_eql, 1);
rb_define_method(rb_cArray, "hash", rb_ary_hash, 0);
rb_define_method(rb_cArray, "[]", rb_ary_aref, -1);
rb_define_method(rb_cArray, "[]=", rb_ary_aset, -1);
rb_define_method(rb_cArray, "at", rb_ary_at, 1);
rb_define_method(rb_cArray, "fetch", rb_ary_fetch, -1);
rb_define_method(rb_cArray, "first", rb_ary_first, -1);
rb_define_method(rb_cArray, "last", rb_ary_last, -1);
rb_define_method(rb_cArray, "concat", rb_ary_concat, 1);
rb_define_method(rb_cArray, "<<", rb_ary_push, 1);
rb_define_method(rb_cArray, "push", rb_ary_push_m, -1);
rb_define_method(rb_cArray, "pop", rb_ary_pop_m, -1);
rb_define_method(rb_cArray, "shift", rb_ary_shift_m, -1);
rb_define_method(rb_cArray, "unshift", rb_ary_unshift_m, -1);
rb_define_method(rb_cArray, "insert", rb_ary_insert, -1);
rb_define_method(rb_cArray, "each", rb_ary_each, 0);
rb_define_method(rb_cArray, "each_index", rb_ary_each_index, 0);
rb_define_method(rb_cArray, "reverse_each", rb_ary_reverse_each, 0);
rb_define_method(rb_cArray, "length", rb_ary_length, 0);
rb_define_alias(rb_cArray, "size", "length");
rb_define_method(rb_cArray, "empty?", rb_ary_empty_p, 0);
rb_define_method(rb_cArray, "find_index", rb_ary_index, -1);
rb_define_method(rb_cArray, "index", rb_ary_index, -1);
rb_define_method(rb_cArray, "rindex", rb_ary_rindex, -1);
rb_define_method(rb_cArray, "join", rb_ary_join_m, -1);
rb_define_method(rb_cArray, "reverse", rb_ary_reverse_m, 0);
rb_define_method(rb_cArray, "reverse!", rb_ary_reverse_bang, 0);
rb_define_method(rb_cArray, "sort", rb_ary_sort, 0);
rb_define_method(rb_cArray, "sort!", rb_ary_sort_bang, 0);
rb_define_method(rb_cArray, "collect", rb_ary_collect, 0);
rb_define_method(rb_cArray, "collect!", rb_ary_collect_bang, 0);
rb_define_method(rb_cArray, "map", rb_ary_collect, 0);
rb_define_method(rb_cArray, "map!", rb_ary_collect_bang, 0);
rb_define_method(rb_cArray, "select", rb_ary_select, 0);
rb_define_method(rb_cArray, "values_at", rb_ary_values_at, -1);
rb_define_method(rb_cArray, "delete", rb_ary_delete, 1);
rb_define_method(rb_cArray, "delete_at", rb_ary_delete_at_m, 1);
rb_define_method(rb_cArray, "delete_if", rb_ary_delete_if, 0);
rb_define_method(rb_cArray, "reject", rb_ary_reject, 0);
rb_define_method(rb_cArray, "reject!", rb_ary_reject_bang, 0);
rb_define_method(rb_cArray, "zip", rb_ary_zip, -1);
rb_define_method(rb_cArray, "transpose", rb_ary_transpose, 0);
rb_define_method(rb_cArray, "replace", rb_ary_replace, 1);
rb_define_method(rb_cArray, "clear", rb_ary_clear, 0);
rb_define_method(rb_cArray, "fill", rb_ary_fill, -1);
rb_define_method(rb_cArray, "include?", rb_ary_includes, 1);
rb_define_method(rb_cArray, "<=>", rb_ary_cmp, 1);
rb_define_method(rb_cArray, "slice", rb_ary_aref, -1);
rb_define_method(rb_cArray, "slice!", rb_ary_slice_bang, -1);
rb_define_method(rb_cArray, "assoc", rb_ary_assoc, 1);
rb_define_method(rb_cArray, "rassoc", rb_ary_rassoc, 1);
rb_define_method(rb_cArray, "+", rb_ary_plus, 1);
rb_define_method(rb_cArray, "*", rb_ary_times, 1);
rb_define_method(rb_cArray, "-", rb_ary_diff, 1);
rb_define_method(rb_cArray, "&", rb_ary_and, 1);
rb_define_method(rb_cArray, "|", rb_ary_or, 1);
rb_define_method(rb_cArray, "uniq", rb_ary_uniq, 0);
rb_define_method(rb_cArray, "uniq!", rb_ary_uniq_bang, 0);
rb_define_method(rb_cArray, "compact", rb_ary_compact, 0);
rb_define_method(rb_cArray, "compact!", rb_ary_compact_bang, 0);
rb_define_method(rb_cArray, "flatten", rb_ary_flatten, -1);
rb_define_method(rb_cArray, "flatten!", rb_ary_flatten_bang, -1);
rb_define_method(rb_cArray, "count", rb_ary_count, -1);
rb_define_method(rb_cArray, "shuffle!", rb_ary_shuffle_bang, 0);
rb_define_method(rb_cArray, "shuffle", rb_ary_shuffle, 0);
rb_define_method(rb_cArray, "sample", rb_ary_sample, -1);
rb_define_method(rb_cArray, "cycle", rb_ary_cycle, -1);
rb_define_method(rb_cArray, "permutation", rb_ary_permutation, -1);
rb_define_method(rb_cArray, "combination", rb_ary_combination, 1);
rb_define_method(rb_cArray, "product", rb_ary_product, -1);
rb_define_method(rb_cArray, "take", rb_ary_take, 1);
rb_define_method(rb_cArray, "take_while", rb_ary_take_while, 0);
rb_define_method(rb_cArray, "drop", rb_ary_drop, 1);
rb_define_method(rb_cArray, "drop_while", rb_ary_drop_while, 0);
id_cmp = rb_intern("<=>");
}
yard-0.9.7/spec/parser/examples/override.c.txt 0000644 0000041 0000041 00000025111 13035234564 021370 0 ustar www-data www-data #include
#include
#include
/*
* Document-class: GMP::Z
*
* GMP Multiple Precision Integer.
*
* Instances of this class can store variables of the type mpz_t. This class
* also contains many methods that act as the functions for mpz_t variables,
* as well as a few methods that attempt to make this library more Ruby-ish.
*/
/**********************************************************************
* Macros *
**********************************************************************/
/*
* DEFUN_INT2INT defines two functions. The first takes a GMP::Z as
* self, calls mpz_fname on the contained mpz_t, whose arguments are
* exactly (0) the return argument and (1) self. The second is the same
* destructive method.
*/
#define DEFUN_INT2INT(fname,mpz_fname) \
static VALUE r_gmpz_##fname(VALUE self) \
{ \
MP_INT *self_val, *res_val; \
VALUE res; \
mpz_get_struct(self, self_val); \
mpz_make_struct_init(res, res_val); \
mpz_fname(res_val, self_val); \
return res; \
} \
\
static VALUE r_gmpz_##fname##_self(VALUE self) \
{ \
MP_INT *self_val; \
mpz_get_struct(self, self_val); \
mpz_fname(self_val, self_val); \
return self; \
}
/**********************************************************************
* Integer Arithmetic *
**********************************************************************/
/*
* call-seq:
* a + b
*
* Adds _a_ to _b_. _b_ must be an instance of one of:
* * GMP::Z
* * Fixnum
* * GMP::Q
* * GMP::F
* * Bignum
*/
VALUE r_gmpz_add(VALUE self, VALUE arg)
{
MP_INT *self_val, *arg_val, *res_val;
VALUE res;
mpz_get_struct(self,self_val);
if (GMPZ_P(arg)) {
mpz_get_struct(arg,arg_val);
mpz_make_struct_init(res, res_val);
mpz_add(res_val, self_val, arg_val);
} else if (FIXNUM_P(arg)) {
mpz_make_struct_init(res, res_val);
if (FIX2NUM(arg) > 0)
mpz_add_ui(res_val, self_val, FIX2NUM(arg));
else
mpz_sub_ui(res_val, self_val, -FIX2NUM(arg));
} else if (GMPQ_P(arg)) {
return r_gmpq_add(arg, self);
} else if (GMPF_P(arg)) {
#ifndef MPFR
return r_gmpf_add(arg, self);
#else
return rb_funcall(arg, rb_intern("+"), 1, self);
#endif
} else if (BIGNUM_P(arg)) {
mpz_make_struct_init(res, res_val);
mpz_init(res_val);
mpz_set_bignum(res_val, arg);
mpz_add(res_val, res_val, self_val);
} else {
typeerror(ZQFXB);
}
return res;
}
/*
* call-seq:
* a.add!(_b_)
*
* Adds _a_ to _b_ in-place, setting _a_ to the sum. _b_ must be an instance of one of:
* * GMP::Z
* * Fixnum
* * GMP::Q
* * GMP::F
* * Bignum
*/
VALUE r_gmpz_add_self(VALUE self, VALUE arg)
{
MP_INT *self_val, *arg_val;
mpz_get_struct(self,self_val);
if (GMPZ_P(arg)) {
mpz_get_struct(arg,arg_val);
mpz_add(self_val, self_val, arg_val);
} else if (FIXNUM_P(arg)) {
if (FIX2NUM(arg) > 0)
mpz_add_ui(self_val, self_val, FIX2NUM(arg));
else
mpz_sub_ui(self_val, self_val, -FIX2NUM(arg));
} else if (BIGNUM_P(arg)) {
mpz_temp_from_bignum(arg_val, arg);
mpz_add(self_val, self_val, arg_val);
mpz_temp_free(arg_val);
} else {
typeerror(ZXB);
}
return Qnil;
}
/*
* call-seq:
* a - b
*
* Subtracts _b_ from _a_. _b_ must be an instance of one of:
* * GMP::Z
* * Fixnum
* * GMP::Q
* * GMP::F
* * Bignum
*/
VALUE r_gmpz_sub(VALUE self, VALUE arg)
{
MP_RAT *res_val_q, *arg_val_q;
MP_INT *self_val, *arg_val, *res_val;
MP_FLOAT *arg_val_f, *res_val_f;
VALUE res;
unsigned long prec;
mpz_get_struct(self,self_val);
if (GMPZ_P(arg)) {
mpz_make_struct_init(res, res_val);
mpz_get_struct(arg,arg_val);
mpz_sub (res_val, self_val, arg_val);
} else if (FIXNUM_P(arg)) {
mpz_make_struct_init(res, res_val);
if (FIX2NUM(arg) > 0)
mpz_sub_ui (res_val, self_val, FIX2NUM(arg));
else
mpz_add_ui (res_val, self_val, -FIX2NUM(arg));
} else if (GMPQ_P(arg)) {
mpq_make_struct_init(res, res_val_q);
mpq_get_struct(arg,arg_val_q);
mpz_set (mpq_denref(res_val_q), mpq_denref(arg_val_q));
mpz_mul (mpq_numref(res_val_q), mpq_denref(arg_val_q), self_val);
mpz_sub (mpq_numref(res_val_q), mpq_numref(res_val_q), mpq_numref(arg_val_q));
} else if (GMPF_P(arg)) {
mpf_get_struct_prec (arg, arg_val_f, prec);
mpf_make_struct_init(res, res_val_f, prec);
mpf_set_z (res_val_f, self_val);
mpf_sub (res_val_f, res_val_f, arg_val_f);
} else if (BIGNUM_P(arg)) {
mpz_make_struct_init(res, res_val);
mpz_set_bignum (res_val, arg);
mpz_sub (res_val, self_val, res_val);
} else {
typeerror (ZQFXB);
}
return res;
}
/*
* call-seq:
* a.sub!(b)
*
* Subtracts _b_ from _a_ in-place, setting _a_ to the difference. _b_ must be an
* instance of one of:
* * GMP::Z
* * Fixnum
* * GMP::Q
* * GMP::F
* * Bignum
*/
VALUE r_gmpz_sub_self(VALUE self, VALUE arg)
{
MP_INT *self_val, *arg_val;
mpz_get_struct(self,self_val);
if (GMPZ_P(arg)) {
mpz_get_struct(arg, arg_val);
mpz_sub (self_val, self_val, arg_val);
} else if (FIXNUM_P(arg)) {
if (FIX2NUM(arg) > 0)
mpz_sub_ui (self_val, self_val, FIX2NUM(arg));
else
mpz_add_ui (self_val, self_val, -FIX2NUM(arg));
} else if (BIGNUM_P(arg)) {
mpz_temp_from_bignum(arg_val, arg);
mpz_sub (self_val, self_val, arg_val);
mpz_temp_free (arg_val);
} else {
typeerror (ZXB);
}
return Qnil;
}
/*
* call-seq:
* a * b
*
* Multiplies _a_ with _b_. _a_ must be an instance of one of
* * GMP::Z
* * Fixnum
* * GMP::Q
* * GMP::F
* * Bignum
*/
VALUE r_gmpz_mul(VALUE self, VALUE arg)
{
MP_INT *self_val, *arg_val, *res_val;
VALUE res;
mpz_get_struct(self,self_val);
if (GMPZ_P(arg)) {
mpz_make_struct_init(res, res_val);
mpz_get_struct(arg,arg_val);
mpz_mul(res_val, self_val, arg_val);
} else if (FIXNUM_P(arg)) {
mpz_make_struct_init(res, res_val);
mpz_mul_si(res_val, self_val, FIX2NUM(arg));
} else if (GMPQ_P(arg)) {
return r_gmpq_mul(arg, self);
} else if (GMPF_P(arg)) {
#ifndef MPFR
return r_gmpf_mul(arg, self);
#else
return rb_funcall(arg, rb_intern("*"), 1, self);
#endif
} else if (BIGNUM_P(arg)) {
mpz_make_struct_init(res, res_val);
mpz_set_bignum(res_val, arg);
mpz_mul(res_val, res_val, self_val);
} else {
typeerror(ZQFXB);
}
return res;
}
/*
* call-seq:
* a.addmul!(b, c)
*
* @since 0.4.17
*
* Sets _a_ to _a_ plus _b_ times _c_. _b_ and _c_ must each be an instance of one of
* * GMP::Z
* * Fixnum
* * Bignum
*/
VALUE r_gmpz_addmul_self(VALUE self, VALUE b, VALUE c)
{
MP_INT *self_val, *b_val, *c_val;
int free_b_val = 0;
if (GMPZ_P(b)) {
mpz_get_struct(b, b_val);
} else if (FIXNUM_P(b)) {
mpz_temp_alloc(b_val);
mpz_init_set_si(b_val, FIX2NUM(b));
free_b_val = 1;
} else if (BIGNUM_P(b)) {
mpz_temp_from_bignum(b_val, b);
free_b_val = 1;
} else {
typeerror_as(ZXB, "addend");
}
mpz_get_struct(self, self_val);
if (GMPZ_P(c)) {
mpz_get_struct(c, c_val);
mpz_addmul(self_val, b_val, c_val);
} else if (FIXNUM_P(c)) {
if (FIX2NUM(c) < 0)
{
if (free_b_val) { mpz_temp_free(b_val); }
rb_raise(rb_eRangeError, "multiplicand (Fixnum) must be nonnegative");
}
mpz_addmul_ui(self_val, b_val, FIX2NUM(c));
} else if (BIGNUM_P(c)) {
mpz_temp_from_bignum(c_val, c);
mpz_addmul(self_val, b_val, c_val);
mpz_temp_free(c_val);
} else {
if (free_b_val)
mpz_temp_free(b_val);
typeerror_as(ZXB, "multiplicand");
}
if (free_b_val)
mpz_temp_free(b_val);
return self;
}
/*
* Document-method: neg
*
* call-seq:
* a.neg
* -a
*
* Returns -_a_.
*/
/*
* Document-method: neg!
*
* call-seq:
* a.neg!
*
* Sets _a_ to -_a_.
*/
DEFUN_INT2INT(neg, mpz_neg)
/*
* Document-method: abs
*
* call-seq:
* a.abs
*
* Returns the absolute value of _a_.
*/
/*
* Document-method: abs!
*
* call-seq:
* a.abs!
*
* Sets _a_ to its absolute value.
*/
DEFUN_INT2INT(abs, mpz_abs)
/**********************************************************************
* Integer Roots *
**********************************************************************/
/*
* Document-method: sqrt
*
* call-seq:
* a.sqrt
*
* Returns the truncated integer part of the square root of _a_.
*/
/*
* Document-method: sqrt!
*
* call-seq:
* a.sqrt!
*
* Sets _a_ to the truncated integer part of its square root.
*/
DEFUN_INT2INT(sqrt, mpz_sqrt)
/*
* call-seq:
* a.sqrtrem #=> s, r
*
* Returns the truncated integer part of the square root of _a_ as _s_ and the remainder
* a - s * s as _r_, which will be zero if _a_ is a perfect square.
*/
static VALUE r_gmpz_sqrtrem(VALUE self)
{
MP_INT *self_val, *sqrt_val, *rem_val;
VALUE sqrt, rem;
mpz_get_struct(self, self_val);
mpz_make_struct_init(sqrt, sqrt_val);
mpz_make_struct_init(rem, rem_val);
mpz_sqrtrem(sqrt_val, rem_val, self_val);
return rb_assoc_new(sqrt, rem);
}
/**********************************************************************
* Init function *
**********************************************************************/
void init_gmpz()
{
mGMP = rb_define_module("GMP");
rb_define_module_function(mGMP, "Z", r_gmpmod_z, -1);
cGMP_Z = rb_define_class_under(mGMP, "Z", rb_cInteger);
// Integer Arithmetic
rb_define_method(cGMP_Z, "+", r_gmpz_add, 1);
rb_define_method(cGMP_Z, "add!", r_gmpz_add_self, 1);
rb_define_method(cGMP_Z, "-", r_gmpz_sub, 1);
rb_define_method(cGMP_Z, "sub!", r_gmpz_sub_self, 1);
rb_define_method(cGMP_Z, "*", r_gmpz_mul, 1);
rb_define_method(cGMP_Z, "addmul!", r_gmpz_addmul_self, 2);
rb_define_method(cGMP_Z, "neg", r_gmpz_neg, 0);
rb_define_method(cGMP_Z, "neg!", r_gmpz_neg_self, 0);
rb_define_method(cGMP_Z, "-@", r_gmpz_neg, 0);
rb_define_method(cGMP_Z, "abs", r_gmpz_abs, 0);
rb_define_method(cGMP_Z, "abs!", r_gmpz_abs_self, 0);
// Integer Roots
rb_define_method(cGMP_Z, "root", r_gmpz_root, 1);
rb_define_method(cGMP_Z, "sqrt", r_gmpz_sqrt, 0);
rb_define_method(cGMP_Z, "sqrt!", r_gmpz_sqrt_self, 0);
rb_define_method(cGMP_Z, "sqrtrem", r_gmpz_sqrtrem, 0);
}
yard-0.9.7/spec/parser/examples/parse_in_order_002.rb.txt 0000644 0000041 0000041 00000000023 13035234564 023301 0 ustar www-data www-data module MyModule
end yard-0.9.7/spec/parser/tag_parsing_spec.rb 0000644 0000041 0000041 00000000730 13035234564 020606 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Parser, "tag handling" do
before { parse_file :tag_handler_001, __FILE__ }
it "knows the list of all available tags" do
expect(P("Foo#foo").tags).to include(P("Foo#foo").tag(:api))
end
it "knows the text of tags on a method" do
expect(P("Foo#foo").tag(:api).text).to eq "public"
end
it "returns true when asked whether a tag exists" do
expect(P("Foo#foo").has_tag?(:api)).to be true
end
end
yard-0.9.7/spec/parser/source_parser_spec.rb 0000644 0000041 0000041 00000060672 13035234564 021177 0 ustar www-data www-data # frozen_string_literal: true
class MyParser < Parser::Base; end
RSpec.shared_examples_for "parser type registration" do
after do
Parser::SourceParser.parser_types.delete(:my_parser)
Parser::SourceParser.parser_type_extensions.delete(:my_parser)
end
end
RSpec.describe YARD::Parser::SourceParser do
before do
Registry.clear
end
def parse_list(*list)
files = list.map do |v|
filename, source = *v
allow(File).to receive(:read_binary).with(filename).and_return(source)
filename
end
Parser::SourceParser.send(:parse_in_order, *files)
end
def before_list(&block)
Parser::SourceParser.before_parse_list(&block)
end
def after_list(&block)
Parser::SourceParser.after_parse_list(&block)
end
def before_file(&block)
Parser::SourceParser.before_parse_file(&block)
end
def after_file(&block)
Parser::SourceParser.after_parse_file(&block)
end
describe ".before_parse_list" do
before do
Parser::SourceParser.before_parse_list_callbacks.clear
Parser::SourceParser.after_parse_list_callbacks.clear
end
it "handles basic callback support" do
before_list do |files, globals|
expect(files).to eq ['foo.rb', 'bar.rb']
expect(globals).to eq OpenStruct.new
end
parse_list ['foo.rb', 'foo!'], ['bar.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
end
it "supports multiple callbacks" do
checks = []
before_list { checks << :one }
before_list { checks << :two }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :two]
end
it "cancels parsing if it returns false" do
checks = []
before_list { checks << :one }
before_list { false }
before_list { checks << :three }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).to be nil
expect(checks).to eq [:one]
end
it "does not cancel on nil" do
checks = []
before_list { checks << :one }
before_list { nil }
before_list { checks << :two }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :two]
end
it "passes in globals" do
before_list {|_f, g| g.x = 1 }
before_list {|_f, g| g.x += 1 }
before_list {|_f, g| g.x += 1 }
after_list {|_f, g| expect(g.x).to eq 3 }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
end
end
describe ".after_parse_list" do
before do
Parser::SourceParser.before_parse_list_callbacks.clear
Parser::SourceParser.after_parse_list_callbacks.clear
end
it "handles basic callback support and maintain files/globals" do
before_list {|_f, g| g.foo = :bar }
after_list do |files, globals|
expect(files).to eq ['foo.rb', 'bar.rb']
expect(globals.foo).to eq :bar
end
parse_list ['foo.rb', 'foo!'], ['bar.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
end
it "supports multiple callbacks" do
checks = []
after_list { checks << :one }
after_list { checks << :two }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :two]
end
it "does not cancel parsing if it returns false" do
checks = []
after_list { checks << :one }
after_list { false }
after_list { checks << :three }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :three]
end
end
describe ".before_parse_file" do
before do
Parser::SourceParser.before_parse_file_callbacks.clear
Parser::SourceParser.after_parse_file_callbacks.clear
end
it "handles basic callback support" do
before_file do |parser|
expect(parser.contents).to eq 'class Foo; end'
expect(parser.file).to match(/(foo|bar)\.rb/)
end
parse_list ['foo.rb', 'class Foo; end'], ['bar.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
end
it "supports multiple callbacks" do
checks = []
before_file { checks << :one }
before_file { checks << :two }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :two, :one, :two, :one, :two]
end
it "cancels parsing if it returns false" do
checks = []
before_file { checks << :one }
before_file { false }
before_file { checks << :three }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).to be nil
expect(checks).to eq [:one, :one, :one]
end
it "does not cancel on nil" do
checks = []
before_file { checks << :one }
before_file { nil }
before_file { checks << :two }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :two, :one, :two, :one, :two]
end
end
describe ".after_parse_file" do
before do
Parser::SourceParser.before_parse_file_callbacks.clear
Parser::SourceParser.after_parse_file_callbacks.clear
end
it "handles basic callback support" do
after_file do |parser|
expect(parser.contents).to eq 'class Foo; end'
expect(parser.file).to match(/(foo|bar)\.rb/)
end
parse_list ['foo.rb', 'class Foo; end'], ['bar.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
end
it "supports multiple callbacks" do
checks = []
after_file { checks << :one }
after_file { checks << :two }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :two, :one, :two, :one, :two]
end
it "does not cancel parsing if it returns false" do
checks = []
after_file { checks << :one }
after_file { false }
after_file { checks << :three }
parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
expect(Registry.at('Foo')).not_to be nil
expect(checks).to eq [:one, :three, :one, :three, :one, :three]
end
end
describe ".register_parser_type" do
it_should_behave_like "parser type registration"
it "registers a subclass of Parser::Base" do
parser = double(:parser)
expect(parser).to receive(:parse)
expect(MyParser).to receive(:new).with('content', '(stdin)').and_return(parser)
Parser::SourceParser.register_parser_type(:my_parser, MyParser, 'myparser')
Parser::SourceParser.parse_string('content', :my_parser)
end
it "requires class to be a subclass of Parser::Base" do
expect { Parser::SourceParser.register_parser_type(:my_parser, String) }.to raise_error(ArgumentError)
expect { Parser::SourceParser.register_parser_type(:my_parser, Parser::Base) }.to raise_error(ArgumentError)
end
end
describe ".parser_type_for_extension" do
it_should_behave_like "parser type registration"
it "finds an extension in a registered array of extensions" do
Parser::SourceParser.register_parser_type(:my_parser, MyParser, ['a', 'b', 'd'])
expect(Parser::SourceParser.parser_type_for_extension('a')).to eq :my_parser
expect(Parser::SourceParser.parser_type_for_extension('b')).to eq :my_parser
expect(Parser::SourceParser.parser_type_for_extension('d')).to eq :my_parser
expect(Parser::SourceParser.parser_type_for_extension('c')).not_to eq :my_parser
end
it "finds an extension in a Regexp" do
Parser::SourceParser.register_parser_type(:my_parser, MyParser, /abc$/)
expect(Parser::SourceParser.parser_type_for_extension('dabc')).to eq :my_parser
expect(Parser::SourceParser.parser_type_for_extension('dabcd')).not_to eq :my_parser
end
it "finds an extension in a list of Regexps" do
Parser::SourceParser.register_parser_type(:my_parser, MyParser, [/ab$/, /abc$/])
expect(Parser::SourceParser.parser_type_for_extension('dabc')).to eq :my_parser
expect(Parser::SourceParser.parser_type_for_extension('dabcd')).not_to eq :my_parser
end
it "finds an extension in a String" do
Parser::SourceParser.register_parser_type(:my_parser, MyParser, "abc")
expect(Parser::SourceParser.parser_type_for_extension('abc')).to eq :my_parser
expect(Parser::SourceParser.parser_type_for_extension('abcd')).not_to eq :my_parser
end
end
describe "#parse_string" do
it "parses basic Ruby code" do
YARD.parse_string(<<-eof)
module Hello
class Hi
# Docstring
# Docstring2
def me; "VALUE" end
end
end
eof
expect(Registry.at(:Hello)).not_to eq nil
expect(Registry.at("Hello::Hi#me")).not_to eq nil
expect(Registry.at("Hello::Hi#me").docstring).to eq "Docstring\nDocstring2"
expect(Registry.at("Hello::Hi#me").docstring.line_range).to eq(3..4)
end
it "parses Ruby code with metaclasses" do
YARD.parse_string(<<-eof)
module Hello
class Hi
class < false, '##' => true}.each do |hash, expected|
YARD.parse_string "#{hash}\n# Foo bar\nclass Foo; end"
expect(Registry.at(:Foo).docstring.hash_flag).to eq expected
end
end
it "removes shebang from initial file comments" do
YARD.parse_string "#!/bin/ruby\n# this is a comment\nclass Foo; end"
expect(Registry.at(:Foo).docstring).to eq "this is a comment"
end
it "removes encoding line from initial file comments" do
YARD.parse_string "# encoding: utf-8\n# this is a comment\nclass Foo; end"
expect(Registry.at(:Foo).docstring).to eq "this is a comment"
end
it "adds macros on any object" do
YARD.parse_string <<-eof
# @!macro [new] foo
# This is a macro
# @return [String] the string
class Foo
# @!macro foo
def foo; end
end
eof
macro = CodeObjects::MacroObject.find('foo')
expect(macro.macro_data).to eq "This is a macro\n@return [String] the string"
expect(Registry.at('Foo').docstring.to_raw).to eq macro.macro_data
expect(Registry.at('Foo#foo').docstring.to_raw).to eq macro.macro_data
end
it "allows directives parsed on lone comments" do
YARD.parse_string(<<-eof)
class Foo
# @!method foo(a = "hello")
# @!scope class
# @!visibility private
# @param [String] a the name of the foo
# @return [Symbol] the symbolized foo
# @!method bar(value)
end
eof
foo = Registry.at('Foo.foo')
bar = Registry.at('Foo#bar')
expect(foo).not_to be nil
expect(foo.visibility).to eq :private
expect(foo.tag(:param).name).to eq 'a'
expect(foo.tag(:return).types).to eq ['Symbol']
expect(bar).not_to be nil
expect(bar.signature).to eq 'def bar(value)'
end
it "parses lone comments at end of blocks" do
YARD.parse_string(<<-eof)
class Foo
none
# @!method foo(a = "hello")
end
eof
foo = Registry.at('Foo#foo')
expect(foo).not_to be nil
expect(foo.signature).to eq 'def foo(a = "hello")'
end
it "handles lone comment with no code" do
YARD.parse_string '# @!method foo(a = "hello")'
foo = Registry.at('#foo')
expect(foo).not_to be nil
expect(foo.signature).to eq 'def foo(a = "hello")'
end
it "handles non-ASCII encoding in heredoc" do
YARD.parse_string <<-eof
# encoding: utf-8
heredoc <<-ending
foo\u{ffe2} bar.
ending
# Hello \u{ffe2} world
class Foo < Bar
attr_accessor :foo
end
eof
expect(Registry.at('Foo').superclass).to eq P('Bar')
end
end
describe "#parse" do
it "parses a basic Ruby file" do
parse_file :example1, __FILE__
expect(Registry.at(:Hello)).not_to eq nil
expect(Registry.at("Hello::Hi#me")).not_to eq nil
expect(Registry.at("Hello::Hi#me").docstring).to eq "Docstring"
end
it "parses a set of file globs" do
expect(Dir).to receive(:[]).with('lib/**/*.rb').and_return([])
YARD.parse('lib/**/*.rb')
end
it "parses a set of absolute paths" do
expect(Dir).not_to receive(:[])
expect(File).to receive(:file?).with('/path/to/file').and_return(true)
expect(File).to receive(:read_binary).with('/path/to/file').and_return("")
YARD.parse('/path/to/file')
end
it "cleans paths before parsing" do
expect(File).to receive(:open).and_return("")
parser = Parser::SourceParser.new(:ruby, true)
parser.parse('a//b//c')
expect(parser.file).to eq 'a/b/c'
end
it "parses files with '*' in them as globs and others as absolute paths" do
expect(Dir).to receive(:[]).with('*.rb').and_return(['a.rb', 'b.rb'])
expect(File).to receive(:file?).with('/path/to/file').and_return(true)
expect(File).to receive(:file?).with('a.rb').and_return(true)
expect(File).to receive(:file?).with('b.rb').and_return(true)
expect(File).to receive(:read_binary).with('/path/to/file').and_return("")
expect(File).to receive(:read_binary).with('a.rb').and_return("")
expect(File).to receive(:read_binary).with('b.rb').and_return("")
YARD.parse ['/path/to/file', '*.rb']
end
it "converts directories into globs" do
expect(Dir).to receive(:[]).with('foo/**/*.{rb,c,cc,cxx,cpp}').and_return(['foo/a.rb', 'foo/bar/b.rb'])
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/a.rb').and_return(true)
expect(File).to receive(:file?).with('foo/bar/b.rb').and_return(true)
expect(File).to receive(:read_binary).with('foo/a.rb').and_return("")
expect(File).to receive(:read_binary).with('foo/bar/b.rb').and_return("")
YARD.parse ['foo']
end
it "uses Registry.checksums cache if file is cached" do
data = 'DATA'
hash = Registry.checksum_for(data)
cmock = double(:cmock)
expect(cmock).to receive(:[]).with('foo/bar').and_return(hash)
expect(Registry).to receive(:checksums).and_return(cmock)
expect(File).to receive(:file?).with('foo/bar').and_return(true)
expect(File).to receive(:read_binary).with('foo/bar').and_return(data)
YARD.parse('foo/bar')
end
it "supports excluded paths" do
expect(File).to receive(:file?).with('foo/bar').and_return(true)
expect(File).to receive(:file?).with('foo/baz').and_return(true)
expect(File).not_to receive(:read_binary)
YARD.parse(["foo/bar", "foo/baz"], ["foo", /baz$/])
end
it "converts file contents to proper encoding if coding line is present" do
valid = []
valid << "# encoding: sjis"
valid << "# encoding: utf-8"
valid << "# xxxxxencoding: sjis"
valid << "# xxxxxencoding: sjis xxxxxx"
valid << "# ENCODING: sjis"
valid << "#coDiNG: sjis"
valid << "# -*- coding: sjis -*-"
valid << "# -*- coding: utf-8; indent-tabs-mode: nil"
valid << "### coding: sjis"
valid << "# encoding=sjis"
valid << "# encoding:sjis"
valid << "# encoding = sjis"
valid << "# encoding == sjis"
valid << "# encoding : sjis"
valid << "# encoding :: sjis"
valid << "#!/bin/shebang\n# encoding: sjis"
valid << "#!/bin/shebang\r\n# coding: sjis"
invalid = []
invalid << "#\n# encoding: sjis"
invalid << "#!/bin/shebang\n#\n# encoding: sjis"
invalid << "# !/bin/shebang\n# encoding: sjis"
{:to => valid, :not_to => invalid}.each do |msg, list|
list.each do |src|
Registry.clear
parser = Parser::SourceParser.new
expect(File).to receive(:read_binary).with('tmpfile').and_return(src)
result = parser.parse("tmpfile")
if HAVE_RIPPER && YARD.ruby19?
if msg == :not_to
default_encoding = 'UTF-8'
expect(result.enumerator[0].source.encoding.to_s).to eq(default_encoding)
else
expect(['Shift_JIS', 'Windows-31J', 'UTF-8']).send(msg,
include(result.enumerator[0].source.encoding.to_s))
end
end
expect(result.encoding_line).send(msg, eq(src.split("\n").last))
end
end
end
it "converts C file contents to proper encoding if coding line is present" do
valid = []
valid << "/* coding: utf-8 */"
valid << "/* -*- coding: utf-8; c-file-style: \"ruby\" -*- */"
valid << "// coding: utf-8"
valid << "// -*- coding: utf-8; c-file-style: \"ruby\" -*-"
invalid = []
{:to => valid, :not_to => invalid}.each do |msg, list|
list.each do |src|
Registry.clear
parser = Parser::SourceParser.new
expect(File).to receive(:read_binary).with('tmpfile.c').and_return(src)
result = parser.parse("tmpfile.c")
content = result.instance_variable_get("@content")
expect(['UTF-8']).send(msg, include(content.encoding.to_s))
end
end
end if YARD.ruby19?
Parser::SourceParser::ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
it "understands #{encoding.upcase} BOM" do
parser = Parser::SourceParser.new
src = bom + String.new("class FooBar; end").force_encoding('binary')
src.force_encoding('binary')
expect(File).to receive(:read_binary).with('tmpfile').and_return(src)
result = parser.parse('tmpfile')
expect(Registry.all(:class).first.path).to eq "FooBar"
expect(result.enumerator[0].source.encoding.to_s.downcase).to eq encoding
end
end if HAVE_RIPPER && YARD.ruby19?
end
describe "#parse_in_order" do
def in_order_parse(*files)
paths = files.map {|f| File.join(File.dirname(__FILE__), 'examples', f.to_s + '.rb.txt') }
YARD::Parser::SourceParser.parse(paths, [], Logger::DEBUG)
end
it "attempts to parse files in order" do
log.enter_level(Logger::DEBUG) do
msgs = []
expect(log).to receive(:debug) {|m| msgs << m }.at_least(:once)
allow(log).to receive(:<<)
in_order_parse 'parse_in_order_001', 'parse_in_order_002'
expect(msgs[1]).to match(/Parsing .+parse_in_order_001.+/)
expect(msgs[2]).to match(/Missing object MyModule/)
expect(msgs[3]).to match(/Parsing .+parse_in_order_002.+/)
expect(msgs[4]).to match(/Re-processing .+parse_in_order_001.+/)
end
end
it "attempts to order files by length for globs (process toplevel files first)" do
files = %w(a a/b a/b/c)
files.each do |file|
expect(File).to receive(:file?).with(file).and_return(true)
expect(File).to receive(:read_binary).with(file).ordered.and_return('')
end
expect(Dir).to receive(:[]).with('a/**/*').and_return(files.reverse)
YARD.parse 'a/**/*'
end
it "allows overriding of length sorting when single file is presented" do
files = %w(a/b/c a a/b)
files.each do |file|
expect(File).to receive(:file?).with(file).at_least(1).times.and_return(true)
expect(File).to receive(:read_binary).with(file).ordered.and_return('')
end
expect(Dir).to receive(:[]).with('a/**/*').and_return(files.reverse)
YARD.parse ['a/b/c', 'a/**/*']
end
end
describe "#parse_statements" do
before do
Registry.clear
end
it "displays a warning for invalid parser type" do
expect(log).to receive(:warn).with(/unrecognized file/)
expect(log).to receive(:backtrace)
YARD::Parser::SourceParser.parse_string("int main() { }", :d)
end
if HAVE_RIPPER
it "displays a warning for a syntax error (with new parser)" do
expect(log).to receive(:warn).with(/Syntax error in/)
expect(log).to receive(:backtrace)
YARD::Parser::SourceParser.parse_string("%!!!", :ruby)
end
end
it "handles groups" do
YARD.parse_string <<-eof
class A
# @group Group Name
def foo; end
def foo2; end
# @endgroup
def bar; end
# @group Group 2
def baz; end
end
eof
expect(Registry.at('A').groups).to eq ['Group Name', 'Group 2']
expect(Registry.at('A#bar').group).to be nil
expect(Registry.at('A#foo').group).to eq "Group Name"
expect(Registry.at('A#foo2').group).to eq "Group Name"
expect(Registry.at('A#baz').group).to eq "Group 2"
end
it "handles multi-line class/module references" do
YARD.parse_string <<-eof
class A::
B::C; end
eof
expect(Registry.all).to eq [P('A::B::C')]
end
it "handles sclass definitions of multi-line class/module references" do
YARD.parse_string <<-eof
class << A::
B::C
def foo; end
end
eof
expect(Registry.all.size).to eq 2
expect(Registry.at('A::B::C')).not_to be nil
expect(Registry.at('A::B::C.foo')).not_to be nil
end
it "handles lone comment blocks at the end of a namespace" do
YARD.parse_string <<-eof
module A
class B
def c; end
# @!method d
end
end
eof
expect(Registry.at('A#d')).to be nil
expect(Registry.at('A::B#d')).not_to be nil
end
if YARD.ruby2?
it "supports named arguments with default values" do
YARD.parse_string 'def foo(a, b = 1, *c, d, e: 3, **f, &g) end'
args = [['a', nil], ['b', '1'], ['*c', nil], ['d', nil], ['e:', '3'], ['**f', nil], ['&g', nil]]
expect(Registry.at('#foo').parameters).to eq(args)
end
end
if NAMED_OPTIONAL_ARGUMENTS && !LEGACY_PARSER
it "supports named arguments without default values" do
YARD.parse_string 'def foo(a, b = 1, *c, d, e: 3, f:, **g, &h) end'
args = [['a', nil], ['b', '1'], ['*c', nil], ['d', nil], ['e:', '3'], ['f:', nil], ['**g', nil], ['&h', nil]]
expect(Registry.at('#foo').parameters).to eq(args)
end
end
end
end
yard-0.9.7/spec/parser/c_parser_spec.rb 0000644 0000041 0000041 00000013553 13035234564 020115 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Parser::C::CParser do
describe "#parse" do
def parse(contents)
Registry.clear
YARD.parse_string(contents, :c)
end
describe "Array class" do
before(:all) do
file = File.join(File.dirname(__FILE__), 'examples', 'array.c.txt')
parse(File.read(file))
end
it "parses Array class" do
obj = YARD::Registry.at('Array')
expect(obj).not_to be nil
expect(obj.docstring).not_to be_blank
end
it "parses method" do
obj = YARD::Registry.at('Array#initialize')
expect(obj.docstring).not_to be_blank
expect(obj.tags(:overload).size).to be > 1
end
end
describe "Source located in extra files" do
before(:all) do
@multifile = File.join(File.dirname(__FILE__), 'examples', 'multifile.c.txt')
@extrafile = File.join(File.dirname(__FILE__), 'examples', 'extrafile.c.txt')
@contents = File.read(@multifile)
end
it "looks for methods in extra files (if 'in' comment is found)" do
extra_contents = File.read(@extrafile)
expect(File).to receive(:read).with('extra.c').and_return(extra_contents)
parse(@contents)
expect(Registry.at('Multifile#extra').docstring).to eq 'foo'
end
it "stops searching for extra source file gracefully if file is not found" do
expect(File).to receive(:read).with('extra.c').and_raise(Errno::ENOENT)
expect(log).to receive(:warn).with("Missing source file `extra.c' when parsing Multifile#extra")
parse(@contents)
expect(Registry.at('Multifile#extra').docstring).to eq ''
end
it "differentiates between a struct and a pointer to a struct retval" do
parse(@contents)
expect(Registry.at('Multifile#hello_mars').docstring).to eq 'Hello Mars'
end
end
describe "Foo class" do
it "does not include comments in docstring source" do
parse <<-eof
/*
* Hello world
*/
VALUE foo(VALUE x) {
int value = x;
}
void Init_Foo() {
rb_define_method(rb_cFoo, "foo", foo, 1);
}
eof
expect(Registry.at('Foo#foo').source.gsub(/\s\s+/, ' ')).to eq(
"VALUE foo(VALUE x) { int value = x;\n}"
)
end
end
describe "Constant" do
it "does not truncate docstring" do
parse <<-eof
#define MSK_DEADBEEF 0xdeadbeef
void
Init_Mask(void)
{
rb_cMask = rb_define_class("Mask", rb_cObject);
/* 0xdeadbeef: This constant is frequently used to indicate a
* software crash or deadlock in embedded systems. */
rb_define_const(rb_cMask, "DEADBEEF", INT2FIX(MSK_DEADBEEF));
}
eof
constant = Registry.at('Mask::DEADBEEF')
expect(constant.value).to eq '0xdeadbeef'
expect(constant.docstring).to eq "This constant is frequently used to indicate a\nsoftware crash or deadlock in embedded systems."
end
end
describe "Macros" do
it "handles param## inside of macros" do
thr = Thread.new do
parse <<-eof
void
Init_gobject_gparamspecs(void)
{
VALUE cParamSpec = GTYPE2CLASS(G_TYPE_PARAM);
VALUE c;
#define DEF_NUMERIC_PSPEC_METHODS(c, typename) \
G_STMT_START {\
rbg_define_method(c, "initialize", typename##_initialize, 7); \
rbg_define_method(c, "minimum", typename##_minimum, 0); \
rbg_define_method(c, "maximum", typename##_maximum, 0); \
rbg_define_method(c, "range", typename##_range, 0); \
} G_STMT_END
#if 0
rbg_define_method(c, "default_value", typename##_default_value, 0); \
rb_define_alias(c, "default", "default_value"); \
#endif
c = G_DEF_CLASS(G_TYPE_PARAM_CHAR, "Char", cParamSpec);
DEF_NUMERIC_PSPEC_METHODS(c, char);
eof
end
thr.join(5)
if thr.alive?
thr.kill
raise "Did not parse in time"
end
end
end
describe "C macros in declaration" do
it "handles C macros in method declaration" do
Registry.clear
parse <<-eof
// docstring
FOOBAR VALUE func() { }
void
Init_mod(void)
{
rb_define_method(rb_cFoo, "func", func, 0); \
}
eof
expect(Registry.at('Foo#func').docstring).to eq "docstring"
end
end
end
describe "Override comments" do
before(:all) do
Registry.clear
override_file = File.join(File.dirname(__FILE__), 'examples', 'override.c.txt')
@override_parser = YARD.parse_string(File.read(override_file), :c)
end
it "parses GMP::Z class" do
z = YARD::Registry.at('GMP::Z')
expect(z).not_to be nil
expect(z.docstring).not_to be_blank
end
it "parses GMP::Z methods w/ bodies" do
add = YARD::Registry.at('GMP::Z#+')
expect(add.docstring).not_to be_blank
expect(add.source).not_to be nil
expect(add.source).not_to be_empty
add_self = YARD::Registry.at('GMP::Z#+')
expect(add_self.docstring).not_to be_blank
expect(add_self.source).not_to be nil
expect(add_self.source).not_to be_empty
sqrtrem = YARD::Registry.at('GMP::Z#+')
expect(sqrtrem.docstring).not_to be_blank
expect(sqrtrem.source).not_to be nil
expect(sqrtrem.source).not_to be_empty
end
it "parses GMP::Z methods w/o bodies" do
neg = YARD::Registry.at('GMP::Z#neg')
expect(neg.docstring).not_to be_blank
expect(neg.source).to be nil
neg_self = YARD::Registry.at('GMP::Z#neg')
expect(neg_self.docstring).not_to be_blank
expect(neg_self.source).to be nil
end
end
end
yard-0.9.7/spec/parser/base_spec.rb 0000644 0000041 0000041 00000001407 13035234564 017224 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Parser::Base do
describe "#initialize" do
class MyParser < Parser::Base; def initialize(a, b) end end
it "takes 2 arguments" do
expect { YARD::Parser::Base.new }.to raise_error(ArgumentError,
/wrong (number|#) of arguments|given 0, expected 2/)
end
it "raises NotImplementedError on #initialize" do
expect { YARD::Parser::Base.new('a', 'b') }.to raise_error(NotImplementedError)
end
it "raises NotImplementedError on #parse" do
expect { MyParser.new('a', 'b').parse }.to raise_error(NotImplementedError)
end
it "raises NotImplementedError on #tokenize" do
expect { MyParser.new('a', 'b').tokenize }.to raise_error(NotImplementedError)
end
end
end
yard-0.9.7/spec/parser/ruby/ 0000755 0000041 0000041 00000000000 13035234564 015732 5 ustar www-data www-data yard-0.9.7/spec/parser/ruby/ruby_parser_spec.rb 0000644 0000041 0000041 00000031730 13035234564 021632 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Parser::Ruby::RubyParser do
def stmt(stmt)
YARD::Parser::Ruby::RubyParser.new(stmt, nil).parse.root.first
end
def stmts(stmts)
YARD::Parser::Ruby::RubyParser.new(stmts, nil).parse.root
end
def tokenize(stmt)
YARD::Parser::Ruby::RubyParser.new(stmt, nil).parse.tokens
end
describe "#parse" do
it "gets comment line numbers" do
s = stmt <<-eof
# comment
# comment
# comment
def method; end
eof
expect(s.comments).to eq "comment\ncomment\ncomment"
expect(s.comments_range).to eq(1..3)
s = stmt <<-eof
# comment
# comment
def method; end
eof
expect(s.comments).to eq "comment\ncomment"
expect(s.comments_range).to eq(2..3)
s = stmt <<-eof
# comment
# comment
def method; end
eof
expect(s.comments).to eq "comment\ncomment"
expect(s.comments_range).to eq(1..2)
s = stmt <<-eof
# comment
def method; end
eof
expect(s.comments).to eq "comment"
expect(s.comments_range).to eq(1..1)
s = stmt <<-eof
def method; end # comment
eof
expect(s.comments).to eq "comment"
expect(s.comments_range).to eq(1..1)
end
it "only looks up to two lines back for comments" do
s = stmts <<-eof
# comments
# comments
def method; end
eof
expect(s[1].comments).to eq "comments"
s = stmts <<-eof
# comments
def method; end
eof
expect(s[1].comments).to eq nil
ss = stmts <<-eof
# comments
def method; end
# hello
def method2; end
eof
expect(ss[1].comments).to eq nil
expect(ss[2].comments).to eq 'hello'
end
it "handles block comment followed by line comment" do
ss = stmts <<-eof
# comments1
=begin
comments2
=end
# comments3
def hello; end
eof
expect(ss.last.comments).to eq "comments3"
end
it "handles block comment followed by block comment" do
ss = stmts <<-eof
=begin
comments1
=end
=begin
comments2
=end
def hello; end
eof
expect(ss.last.comments.strip).to eq "comments2"
end
it "handles 1.9 lambda syntax with args" do
src = "->(a,b,c=1,*args,&block) { hello_world }"
expect(stmt(src).source).to eq src
end
it "handles 1.9 lambda syntax" do
src = "-> { hello_world }"
expect(stmt(src).source).to eq src
end
it "handles standard lambda syntax" do
src = "lambda { hello_world }"
expect(stmt(src).source).to eq src
end
it "throws a ParserSyntaxError on invalid code" do
expect { stmt("Foo, bar.") }.to raise_error(YARD::Parser::ParserSyntaxError)
end
it "handles bare hashes as method parameters" do
src = "command :a => 1, :b => 2, :c => 3"
expect(stmt(src).jump(:command)[1].source).to eq ":a => 1, :b => 2, :c => 3"
src = "command a: 1, b: 2, c: 3"
expect(stmt(src).jump(:command)[1].source).to eq "a: 1, b: 2, c: 3"
end
it "handles source for hash syntax" do
src = "{ :a => 1, :b => 2, :c => 3 }"
expect(stmt(src).jump(:hash).source).to eq "{ :a => 1, :b => 2, :c => 3 }"
end
it "handles an empty hash" do
expect(stmt("{}").jump(:hash).source).to eq "{}"
end
it "new hash label syntax should show label without colon" do
ast = stmt("{ a: 1 }").jump(:label)
expect(ast[0]).to eq "a"
expect(ast.source).to eq "a:"
end
it "handles begin/rescue blocks" do
ast = stmt("begin; X; rescue => e; Y end").jump(:rescue)
expect(ast.source).to eq "rescue => e; Y end"
ast = stmt("begin; X; rescue A => e; Y end").jump(:rescue)
expect(ast.source).to eq "rescue A => e; Y end"
ast = stmt("begin; X; rescue A, B => e; Y end").jump(:rescue)
expect(ast.source).to eq "rescue A, B => e; Y end"
end
it "handles method rescue blocks" do
ast = stmt("def x; A; rescue Y; B end")
expect(ast.source).to eq "def x; A; rescue Y; B end"
expect(ast.jump(:rescue).source).to eq "rescue Y; B end"
end
it "handles defs with keywords as method name" do
ast = stmt("# docstring\nclass A;\ndef class; end\nend")
expect(ast.jump(:class).docstring).to eq "docstring"
expect(ast.jump(:class).line_range).to eq(2..4)
end
it "handles defs with unnamed argument with default values" do
ast = stmt('def hello(one, two = 2, three = 3) end').jump(:params)
expect(ast.source).to eq 'one, two = 2, three = 3'
end
it "handles defs with splats" do
ast = stmt('def hello(one, *two) end').jump(:params)
expect(ast.source).to eq 'one, *two'
end
if YARD.ruby2?
it "handles defs with named arguments with default values" do
ast = stmt('def hello(one, two: 2, three: 3) end').jump(:params)
expect(ast.source).to eq 'one, two: 2, three: 3'
end
end
if NAMED_OPTIONAL_ARGUMENTS
it "handles defs with named arguments without default values" do
ast = stmt('def hello(one, two:, three:) end').jump(:params)
expect(ast.source).to eq 'one, two:, three:'
end
it "handles defs with double splats" do
ast = stmt('def hello(one, **two) end').jump(:params)
expect(ast.source).to eq 'one, **two'
end
end
it "ends source properly on array reference" do
ast = stmt("AS[0, 1 ] ")
expect(ast.source).to eq 'AS[0, 1 ]'
ast = stmt('def x(a = S[1]) end').jump(:params)
expect(ast.source).to eq 'a = S[1]'
end
it "ends source properly on if/unless mod" do
%w(if unless while).each do |mod|
expect(stmt("A=1 #{mod} true").source).to eq "A=1 #{mod} true"
end
end
it "shows proper source for assignment" do
expect(stmt("A=1").jump(:assign).source).to eq "A=1"
end
it "shows proper source for a top_const_ref" do
s = stmt("::\nFoo::Bar")
expect(s.jump(:top_const_ref).source).to eq "::\nFoo"
expect(s).to be_ref
expect(s.jump(:top_const_ref)).to be_ref
expect(s.source).to eq "::\nFoo::Bar"
expect(s.line_range.to_a).to eq [1, 2]
end
it "shows proper source for inline heredoc" do
src = "def foo\n foo(<<-XML, 1, 2)\n bar\n\n XML\nend"
s = stmt(src)
t = tokenize(src)
expect(s.source).to eq src
expect(t.map {|x| x[1] }.join).to eq src
end
it "shows proper source for regular heredoc" do
src = "def foo\n x = <<-XML\n Hello \#{name}!\n Bye!\n XML\nend"
s = stmt(src)
t = tokenize(src)
expect(s.source).to eq src
expect(t.map {|x| x[1] }.join).to eq src
end
it "shows proper source for heredoc with comment" do
src = "def foo\n x = <<-XML # HI!\n Hello \#{name}!\n Bye!\n XML\nend"
s = stmt(src)
t = tokenize(src)
expect(s.source).to eq src
expect(t.map {|x| x[1] }.join).to eq src
end
it "shows proper source for string" do
["'", '"'].each do |q|
src = "#{q}hello\n\nworld#{q}"
s = stmt(src)
expect(s.jump(:string_content).source).to eq "hello\n\nworld"
expect(s.source).to eq src
end
src = '("this is a string")'
expect(stmt(src).jump(:string_literal).source).to eq '"this is a string"'
end
%w(w W i I).each do |tok|
it "shows proper source for %#{tok}() array" do
src = "%#{tok}(\na b c\n d e f\n)"
expect(stmt(src).source).to eq src
end
it "shows proper source for %#{tok}{} array" do
src = "%#{tok}{\na b c\n d e f\n}"
expect(stmt(src).source).to eq src
end
end
{'i' => :qsymbols_literal, 'I' => :symbols_literal,
'w' => :qwords_literal, 'W' => :words_literal}.each do |id, sym|
it "parses %#{id}(...) literals" do
[
"TEST = %#{id}(A B C)",
"TEST = %#{id}( A B C )",
"TEST = %#{id}( \nA \nB \nC \n)",
"TEST = %#{id}(\n\nAD\n\nB\n\nC\n\n)",
"TEST = %#{id}(\n A\n B\n C\n )"
].each do |str|
node = stmt(str).jump(sym)
expect(node.source).to eq(str[/(\%#{id}\(.+\))/m, 1])
end
end
end
it "parses %w() array in constant declaration" do
s = stmt(<<-eof)
class Foo
FOO = %w( foo bar )
end
eof
expect(s.jump(:qwords_literal).source).to eq '%w( foo bar )'
if RUBY_VERSION >= '1.9.3' # ripper fix: array node encapsulates qwords
expect(s.jump(:array).source).to eq '%w( foo bar )'
end
end
it "parses %w() array source in object[] parsed context" do
s = stmts(<<-eof)
{}[:key]
FOO = %w( foo bar )
eof
expect(s[1].jump(:array).source).to eq '%w( foo bar )'
end
it "parses %w() array source in object[]= parsed context" do
s = stmts(<<-eof)
{}[:key] = :value
FOO = %w( foo bar )
eof
expect(s[1].jump(:array).source).to eq '%w( foo bar )'
end
it "parses [] as array" do
s = stmt(<<-eof)
class Foo
FOO = ['foo', 'bar']
end
eof
expect(s.jump(:array).source).to eq "['foo', 'bar']"
end
it "shows source for unary minus" do
expect(stmt("X = - 1").jump(:unary).source).to eq '- 1'
end
it "shows source for unary exclamation" do
expect(stmt("X = !1").jump(:unary).source).to eq '!1'
end
it "has the correct line range for class/modules" do
s = stmt(<<-eof)
class Foo
def foo; end
# Ending comment
end
eof
expect(s.jump(:class).line_range).to eq(1..7)
end
it "has the correct line range for blocks" do
Registry.clear
ast = YARD.parse_string(<<-eof).enumerator
module A
some_method
end
eof
expect(ast.first.block.source.strip).to eq "some_method"
end
it "finds lone comments" do
Registry.clear
ast = YARD.parse_string(<<-eof).enumerator
class Foo
##
# comment here
def foo; end
# end comment
end
eof
comment = ast.first.last.jump(:comment)
expect(comment.type).to eq :comment
expect(comment.docstring_hash_flag).to be true
expect(comment.docstring.strip).to eq "comment here"
expect(ast.first.last.last.type).to eq :comment
expect(ast.first.last.last.docstring).to eq "end comment"
end
it "does not group comments if they don't begin the line" do
Registry.clear
YARD.parse_string(<<-eof).enumerator
class Foo
CONST1 = 1 # Comment here
CONST2 = 2 # Another comment here
end
eof
expect(Registry.at("Foo::CONST1").docstring).to eq "Comment here"
expect(Registry.at("Foo::CONST2").docstring).to eq "Another comment here"
end
%w(if unless).each do |type|
it "does not get confused by modifier '#{type}' statements" do
Registry.clear
YARD.parse_string(<<-eof).enumerator
module Foo
#{type} test?
# Docstring
class Bar
# Docstring2
def foo
x #{type} true
end
end
end
end
eof
expect(Registry.at("Foo::Bar").docstring).to eq "Docstring"
expect(Registry.at("Foo::Bar#foo").docstring).to eq "Docstring2"
end
it "supports #{type} statements at start of source" do
Registry.clear
YARD.parse_string <<-eof
#{type} condition?
class Foo; def bar; #{type} true; end end end
end
eof
expect(log.io.string).to eq ""
expect(Registry.at('Foo#bar')).not_to eq nil
end
it "can handle complex non-modifier '#{type}' statements" do
Registry.clear
YARD.parse_string <<-eof
class Foo
def initialize(data, options = Hash.new)
#{type} true; raise "error" end
@x = ( #{type} 1; true end ) # This line should not blow up
end
end
eof
expect(log.io.string).to eq ""
expect(Registry.at('Foo#initialize')).not_to eq nil
end
it "does not add comment blocks to #{type}_mod nodes" do
Registry.clear
YARD.parse_string(<<-eof).enumerator
class Foo
# Docstring
def bar; end if true
end
eof
expect(Registry.at("Foo#bar").docstring).to eq "Docstring"
end
end
it "removes frozen string line from initial file comments" do
YARD.parse_string "# frozen_string_literal: true\n# this is a comment\nclass Foo; end"
YARD.parse_string "# Frozen-string-literal: true\n# this is a comment\nclass Bar; end"
expect(Registry.at(:Foo).docstring).to eq "this is a comment"
expect(Registry.at(:Bar).docstring).to eq "this is a comment"
end
it "handles compile errors" do
expect { stmt(":~$ Do not clobber") }.to raise_error(Parser::ParserSyntaxError)
end
end
end if HAVE_RIPPER
yard-0.9.7/spec/parser/ruby/legacy/ 0000755 0000041 0000041 00000000000 13035234564 017176 5 ustar www-data www-data yard-0.9.7/spec/parser/ruby/legacy/token_list_spec.rb 0000644 0000041 0000041 00000004503 13035234564 022712 0 ustar www-data www-data # frozen_string_literal: true
include YARD::Parser::Ruby::Legacy
include YARD::Parser::Ruby::Legacy::RubyToken
RSpec.describe YARD::Parser::Ruby::Legacy::TokenList do
describe "#initialize / #push" do
it "accepts a tokenlist (via constructor or push)" do
expect { TokenList.new(TokenList.new) }.not_to raise_error
expect(TokenList.new.push(TokenList.new("x = 2")).size).to eq 6
end
it "accept a token (via constructor or push)" do
expect { TokenList.new(Token.new(0, 0)) }.not_to raise_error
expect(TokenList.new.push(Token.new(0, 0), Token.new(1, 1)).size).to eq 2
end
it "accepts a string and parse it as code (via constructor or push)" do
expect { TokenList.new("x = 2") }.not_to raise_error
x = TokenList.new
x.push("x", "=", "2")
expect(x.size).to eq 6
expect(x.to_s).to eq "x\n=\n2\n"
end
it "does not accept any other input" do
expect { TokenList.new(:notcode) }.to raise_error(ArgumentError)
end
it "does not interpolate string data" do
x = TokenList.new('x = "hello #{world}"')
expect(x.size).to eq 6
expect(x[4].class).to eq TkDSTRING
expect(x.to_s).to eq 'x = "hello #{world}"' + "\n"
end
it "handles label syntax" do
x = TokenList.new('a:1,b:2')
expect(x[0].class).to eq TkLABEL
expect(x[0].text).to eq 'a:'
expect(x[3].class).to eq TkLABEL
expect(x[3].text).to eq 'b:'
end
end
describe "#to_s" do
before do
@t = TokenList.new
@t << TkDEF.new(1, 1, "def")
@t << TkSPACE.new(1, 1)
@t << TkIDENTIFIER.new(1, 1, "x")
@t << TkStatementEnd.new(1, 1)
@t << TkSEMICOLON.new(1, 1) << TkSPACE.new(1, 1)
@t << TkBlockContents.new(1, 1)
@t << TkSPACE.new(1, 1) << TkEND.new(1, 1, "end")
@t[0].set_text "def"
@t[1].set_text " "
@t[2].set_text "x"
@t[4].set_text ";"
@t[5].set_text " "
@t[7].set_text " "
@t[8].set_text "end"
end
it "only shows the statement portion of the tokens by default" do
expect(@t.to_s).to eq "def x"
end
it "shows ... for the block token if all of the tokens are shown" do
expect(@t.to_s(true)).to eq "def x; ... end"
end
it "ignores ... if show_block = false" do
expect(@t.to_s(true, false)).to eq "def x; end"
end
end
end
yard-0.9.7/spec/parser/ruby/legacy/statement_list_spec.rb 0000644 0000041 0000041 00000017443 13035234564 023605 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Parser::Ruby::Legacy::StatementList do
def stmts(code) YARD::Parser::Ruby::Legacy::StatementList.new(code) end
def stmt(code) stmts(code).first end
it "parses dangling block expressions" do
s = stmt <<-eof
if
foo
puts 'hi'
end
eof
expect(s.tokens.to_s(true)).to eq "if\n foo\n ...\n end"
expect(s.tokens.to_s).to eq "if\n foo"
expect(s.block.to_s).to eq "puts 'hi'"
s = stmt <<-eof
if foo ||
bar
puts 'hi'
end
eof
expect(s.tokens.to_s(true)).to eq "if foo ||\n bar\n ...\n end"
expect(s.tokens.to_s).to eq "if foo ||\n bar"
expect(s.block.to_s).to eq "puts 'hi'"
end
it "allows semicolons within parentheses" do
s = stmt "(foo; bar)"
expect(s.tokens.to_s(true)).to eq "(foo; bar)"
expect(s.block).to be nil
end
it "allows for non-block statements" do
s = stmt "hello_world(1, 2, 3)"
expect(s.tokens.to_s).to eq "hello_world(1, 2, 3)"
expect(s.block).to be nil
end
it "allows block statements to be used as part of other block statements" do
s = stmt "while (foo; bar); foo = 12; end; while"
expect(s.tokens.to_s(true)).to eq "while (foo; bar); ... end"
expect(s.tokens.to_s).to eq "while (foo; bar)"
expect(s.block.to_s).to eq "foo = 12"
end
it "allows continued processing after a block" do
s = stmt "if foo; end.stuff"
expect(s.tokens.to_s(true)).to eq "if foo; end.stuff"
expect(s.block.to_s).to eq ""
s = stmt "if foo; end[stuff]"
expect(s.tokens.to_s(true)).to eq "if foo; end[stuff]"
expect(s.block.to_s).to eq ""
s = stmt "if foo; hi end.map do; 123; end"
expect(s.tokens.to_s(true)).to eq "if foo; ... end.map do; 123; end"
expect(s.block.to_s).to eq "hi"
end
it "parses default arguments" do
s = stmt "def foo(bar, baz = 1, bang = 2); bar; end"
expect(s.tokens.to_s(true)).to eq "def foo(bar, baz = 1, bang = 2) ... end"
expect(s.block.to_s).to eq "bar"
s = stmt "def foo bar, baz = 1, bang = 2; bar; end"
expect(s.tokens.to_s(true)).to eq "def foo bar, baz = 1, bang = 2; ... end"
expect(s.block.to_s).to eq "bar"
s = stmt "def foo bar , baz = 1 , bang = 2; bar; end"
expect(s.tokens.to_s(true)).to eq "def foo bar , baz = 1 , bang = 2; ... end"
expect(s.block.to_s).to eq "bar"
end
it "parses complex default arguments" do
s = stmt "def foo(bar, baz = File.new(1, 2), bang = 3); bar; end"
expect(s.tokens.to_s(true)).to eq "def foo(bar, baz = File.new(1, 2), bang = 3) ... end"
expect(s.block.to_s).to eq "bar"
s = stmt "def foo bar, baz = File.new(1, 2), bang = 3; bar; end"
expect(s.tokens.to_s(true)).to eq "def foo bar, baz = File.new(1, 2), bang = 3; ... end"
expect(s.block.to_s).to eq "bar"
s = stmt "def foo bar , baz = File.new(1, 2) , bang = 3; bar; end"
expect(s.tokens.to_s(true)).to eq "def foo bar , baz = File.new(1, 2) , bang = 3; ... end"
expect(s.block.to_s).to eq "bar"
end
it "parses blocks with do/end" do
s = stmt <<-eof
foo do
puts 'hi'
end
eof
expect(s.tokens.to_s(true)).to eq "foo do\n ...\n end"
expect(s.block.to_s).to eq "puts 'hi'"
end
it "parses blocks with {}" do
s = stmt "x { y }"
expect(s.tokens.to_s(true)).to eq "x { ... }"
expect(s.block.to_s).to eq "y"
s = stmt "x() { y }"
expect(s.tokens.to_s(true)).to eq "x() { ... }"
expect(s.block.to_s).to eq "y"
end
it "parses blocks with begin/end" do
s = stmt "begin xyz end"
expect(s.tokens.to_s(true)).to eq "begin ... end"
expect(s.block.to_s).to eq "xyz"
end
it "parses nested blocks" do
s = stmt "foo(:x) { baz(:y) { skippy } }"
expect(s.tokens.to_s(true)).to eq "foo(:x) { ... }"
expect(s.block.to_s).to eq "baz(:y) { skippy }"
end
it "does not parse hashes as blocks" do
s = stmt "x({})"
expect(s.tokens.to_s(true)).to eq "x({})"
expect(s.block.to_s).to eq ""
s = stmt "x = {}"
expect(s.tokens.to_s(true)).to eq "x = {}"
expect(s.block.to_s).to eq ""
s = stmt "x(y, {})"
expect(s.tokens.to_s(true)).to eq "x(y, {})"
expect(s.block.to_s).to eq ""
end
it "parses hashes in blocks with {}" do
s = stmt "x {x = {}}"
expect(s.tokens.to_s(true)).to eq "x {...}"
expect(s.block.to_s).to eq "x = {}"
end
it "parses blocks with {} in hashes" do
s = stmt "[:foo, x {}]"
expect(s.tokens.to_s(true)).to eq "[:foo, x {}]"
expect(s.block.to_s).to eq ""
end
it "handles multiple methods" do
s = stmt <<-eof
def %; end
def b; end
eof
expect(s.to_s).to eq "def %; end"
end
it "handles nested methods" do
s = stmt <<-eof
def *(o) def +@; end
def ~@
end end
eof
expect(s.tokens.to_s(true)).to eq "def *(o) ... end"
expect(s.block.to_s).to eq "def +@; end\n def ~@\n end"
s = stmts(<<-eof)
def /(other) 'hi' end
def method1
def dynamic; end
end
eof
expect(s[1].to_s).to eq "def method1\n def dynamic; end\n end"
end
it "gets comment line numbers" do
s = stmt <<-eof
# comment
# comment
# comment
def method; end
eof
expect(s.comments).to eq ["comment", "comment", "comment"]
expect(s.comments_range).to eq(1..3)
s = stmt <<-eof
# comment
# comment
def method; end
eof
expect(s.comments).to eq ["comment", "comment"]
expect(s.comments_range).to eq(2..3)
s = stmt <<-eof
# comment
# comment
def method; end
eof
expect(s.comments).to eq ["comment", "comment"]
expect(s.comments_range).to eq(1..2)
s = stmt <<-eof
# comment
def method; end
eof
expect(s.comments).to eq ["comment"]
expect(s.comments_range).to eq(1..1)
s = stmt <<-eof
def method; end # comment
eof
expect(s.comments).to eq ["comment"]
expect(s.comments_range).to eq(1..1)
end
it "only looks up to two lines back for comments" do
s = stmt <<-eof
# comments
# comments
def method; end
eof
expect(s.comments).to eq ["comments"]
s = stmt <<-eof
# comments
def method; end
eof
expect(s.comments).to eq nil
ss = stmts <<-eof
# comments
def method; end
# hello
def method2; end
eof
expect(ss[0].comments).to eq nil
expect(ss[1].comments).to eq ['hello']
end
it "handles CRLF (Windows) newlines" do
s = stmts("require 'foo'\r\n\r\n# Test Test\r\n# \r\n# Example:\r\n# example code\r\ndef test\r\nend\r\n")
expect(s[1].comments).to eq ['Test Test', '', 'Example:', ' example code']
end
it "handles elsif blocks" do
s = stmts(stmt("if 0\n foo\nelsif 2\n bar\nend\nbaz").block)
expect(s.size).to eq 2
expect(s[1].tokens.to_s).to eq "elsif 2"
expect(s[1].block.to_s).to eq "bar"
end
it "handles else blocks" do
s = stmts(stmt("if 0\n foo\nelse\n bar\nend\nbaz").block)
expect(s.size).to eq 2
expect(s[1].tokens.to_s).to eq "else"
expect(s[1].block.to_s).to eq "bar"
end
it "allows aliasing keywords" do
['do x', 'x do', 'end begin', 'begin end'].each do |a|
s = stmt("alias #{a}\ndef foo; end")
expect(s.tokens.to_s).to eq "alias #{a}"
expect(s.block).to be nil
end
s = stmt("alias do x if 2 ==\n 2")
expect(s.tokens.to_s).to eq "alias do x if 2 ==\n 2"
end
it "does not open a block on an aliased keyword block opener" do
s = stmts(<<-eof)
class A; alias x do end
class B; end
eof
expect(s[0].block.to_s).to eq 'alias x do'
expect(s.size).to be > 1
end
it "converts heredoc to string" do
src = "<<-XML\n foo\n\nXML"
s = stmt(src)
expect(s.source).to eq '"foo\n\n"'
end
end
yard-0.9.7/spec/parser/ruby/ast_node_spec.rb 0000644 0000041 0000041 00000002232 13035234564 021064 0 ustar www-data www-data # frozen_string_literal: true
require 'pp'
require 'stringio'
include YARD::Parser::Ruby
RSpec.describe YARD::Parser::Ruby::AstNode do
describe "#jump" do
it "jumps to the first specific inner node if found" do
ast = s(:paren, s(:paren, s(:params, s(s(:ident, "hi"), s(:ident, "bye")))))
expect(ast.jump(:params)[0][0].type).to equal(:ident)
end
it "returns the original ast if no inner node is found" do
ast = s(:paren, s(:list, s(:list, s(s(:ident, "hi"), s(:ident, "bye")))))
expect(ast.jump(:params).object_id).to eq ast.object_id
end
end
describe "#pretty_print" do
it "shows a list of nodes" do
obj = YARD::Parser::Ruby::RubyParser.parse("# x\nbye", "x").ast
out = StringIO.new
PP.pp(obj, out)
vcall = RUBY_VERSION >= '1.9.3' ? 'vcall' : 'var_ref'
expect(out.string).to eq "s(s(:#{vcall},\n" \
" s(:ident, \"bye\", line: 2..2, source: 4..6),\n" \
" docstring: \"x\",\n" \
" line: 2..2,\n" \
" source: 4..6))\n"
end
end
end if HAVE_RIPPER
yard-0.9.7/spec/parser/ruby/token_resolver_spec.rb 0000644 0000041 0000041 00000010063 13035234564 022332 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Parser::Ruby::TokenResolver do
before(:all) do
YARD.parse_string <<-eof
module A
def nomatch; end
module B
class C
def initialize; end
# @return [A::B::C]
def self.foo; end
# @return [self]
def self.foo2; end
def bar; end
# @return [nil, D]
def baz; end
# @return [nil]
# @return [D]
def baz2; end
# @overload qux(a)
# @return [nil]
# @overload qux(b)
# @return [D]
def qux; end
end
class SubC < C
end
end
end
module D
def baz; end
end
class Q
def method; end
# @return [Q]
def self.q; end
end
eof
end
def tokens_match
expect(@resolved.map {|t| t.first.last }.join).to eq @src
end
def objs_match(*objects)
other_objs = @resolved.reject {|_, o| !o }.map {|_, o| o.path }
expect(other_objs).to eq objects.flatten
tokens_match
end
def tokenize(src, object = nil)
@src = src
@resolver = YARD::Parser::Ruby::TokenResolver.new(src, object)
@resolved = @resolver.map {|t, o| [t[0, 2], o] }
end
it "returns regular tokens" do
str = "def foo; Z::X::Y end"
tokenize(str)
tokens_match
end
it "resolves objects in compound constant paths" do
tokenize "A::B::C"
objs_match "A", "A::B", "A::B::C"
end
it "ignores full constant path if it breaks at beginning" do
tokenize "E::A::B::C"
objs_match []
end
it "ignores rest of constant path if sub-objects don't match" do
tokenize "D::A::B::C"
objs_match "D"
end
it "resets parsing at non-op tokens" do
tokenize "A::B::C < Q"
objs_match "A", "A::B", "A::B::C", "Q"
end
it "does not restart constant path" do
tokenize "A::B::D::A"
objs_match "A", "A::B"
end
it "resolves objects from base namespace" do
tokenize "A::B::C C", Registry.at("A::B")
objs_match "A", "A::B", "A::B::C", "A::B::C"
end
it "resolves methods" do
tokenize "A::B::C.foo"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo"
end
it "supports 'new' constructor method" do
tokenize "A::B::C.new"
objs_match "A", "A::B", "A::B::C", "A::B::C#initialize"
end
it "skips constructor method if not found but continues resolving" do
tokenize "Q.new.method"
objs_match "Q", "Q#method"
end
it "resolves methods in inheritance tree" do
tokenize "A::B::SubC.new"
objs_match "A", "A::B", "A::B::SubC", "A::B::C#initialize"
end
it "parses compound method call chains based on return type" do
tokenize "A::B::C.foo.baz"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#baz"
end
it "stops resolving if return types not found" do
tokenize "A::B::C.foo.bar.baz.baz"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#bar"
end
it "handles multiple return types (returns first valid type match)" do
tokenize "A::B::C.foo.baz.baz"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#baz", "D#baz"
end
it "doesn't perform lexical matching on methods" do
tokenize "A::B::C.nomatch"
objs_match "A", "A::B", "A::B::C"
end
it "handles multiple return tags (returns first valid type match)" do
tokenize "A::B::C.foo.baz2.baz"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#baz2", "D#baz"
end
it "handles self as return type" do
tokenize "A::B::C.foo2.baz"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo2", "A::B::C#baz"
end
it "handles multiple return tags inside overload tags" do
tokenize "A::B::C.foo.qux.baz"
objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#qux", "D#baz"
end
it "resolves method calls with arguments" do
tokenize "Q.q(A::B, A::B::C.foo().bar).q.q"
objs_match "Q", "Q.q", "A", "A::B", "A", "A::B", "A::B::C",
"A::B::C.foo", "A::B::C#bar", "Q.q", "Q.q"
end
end if HAVE_RIPPER
yard-0.9.7/spec/i18n/ 0000755 0000041 0000041 00000000000 13035234564 014234 5 ustar www-data www-data yard-0.9.7/spec/i18n/pot_generator_spec.rb 0000644 0000041 0000041 00000020440 13035234564 020443 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::I18n::PotGenerator do
def create_messages(messages)
yard_messages = YARD::I18n::Messages.new
add_messages(yard_messages, messages)
yard_messages
end
def add_messages(yard_messages, messages)
messages.each do |id, properties|
yard_message = yard_messages.register(id)
(properties[:locations] || []).each do |path, line|
yard_message.add_location(path, line)
end
(properties[:comments] || []).each do |comment|
yard_message.add_comment(comment)
end
end
end
before do
@generator = YARD::I18n::PotGenerator.new("..")
end
describe "Generate" do
it "generates the default header" do
current_time = Time.parse("2011-11-20 22:17+0900")
allow(@generator).to receive(:current_time).and_return(current_time)
pot_creation_date = current_time.strftime("%Y-%m-%d %H:%M%z")
expect(@generator.generate).to eq <<-eoh
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR , YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\\n"
"Report-Msgid-Bugs-To: \\n"
"POT-Creation-Date: #{pot_creation_date}\\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
"Last-Translator: FULL NAME \\n"
"Language-Team: LANGUAGE \\n"
"Language: \\n"
"MIME-Version: 1.0\\n"
"Content-Type: text/plain; charset=UTF-8\\n"
"Content-Transfer-Encoding: 8bit\\n"
eoh
end
it "generates messages in location order" do
allow(@generator).to receive(:header).and_return("HEADER\n\n")
messages = {
"tag|see|Parser::SourceParser.parse" => {
:locations => [["yard.rb", 14]],
:comments => ["@see"]
},
"Parses a path or set of paths" => {
:locations => [["yard.rb", 12], ["yard/parser/source_parser.rb", 83]],
:comments => ["YARD.parse", "YARD::Parser::SourceParser.parse"]
}
}
add_messages(@generator.messages, messages)
expect(@generator.generate).to eq <<-'eoh'
HEADER
# YARD.parse
# YARD::Parser::SourceParser.parse
#: ../yard.rb:12
#: ../yard/parser/source_parser.rb:83
msgid "Parses a path or set of paths"
msgstr ""
# @see
#: ../yard.rb:14
msgid "tag|see|Parser::SourceParser.parse"
msgstr ""
eoh
end
end
describe "Escape" do
def generate_message_pot(message_id)
pot = String.new("")
message = YARD::I18n::Message.new(message_id)
@generator.send(:generate_message, pot, message)
pot
end
it "escapes <\\>" do
expect(generate_message_pot("hello \\ world")).to eq <<-'eop'
msgid "hello \\ world"
msgstr ""
eop
end
it "escapes <\">" do
expect(generate_message_pot("hello \" world")).to eq <<-'eop'
msgid "hello \" world"
msgstr ""
eop
end
it "escapes <\\n>" do
expect(generate_message_pot("hello \n world")).to eq <<-'eop'
msgid "hello \n"
" world"
msgstr ""
eop
end
end
describe "Object" do
before do
Registry.clear
@yard = YARD::CodeObjects::ModuleObject.new(:root, :YARD)
end
it "extracts at docstring" do
object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
o.docstring = "An alias to {Parser::SourceParser}'s parsing method"
end
@generator.parse_objects([object])
expect(@generator.messages).to eq create_messages(
"An alias to {Parser::SourceParser}'s parsing method" => {
:locations => [],
:comments => ["YARD.parse"]
}
)
end
it "extracts at location" do
object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
o.docstring = "An alias to {Parser::SourceParser}'s parsing method"
o.files = [["yard.rb", 12]]
end
@generator.parse_objects([object])
expect(@generator.messages).to eq create_messages(
"An alias to {Parser::SourceParser}'s parsing method" => {
:locations => [["yard.rb", 13]],
:comments => ["YARD.parse"]
}
)
end
it "extracts at tag name" do
object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
o.docstring = "@see Parser::SourceParser.parse"
o.files = [["yard.rb", 12]]
end
@generator.parse_objects([object])
expect(@generator.messages).to eq create_messages(
"tag|see|Parser::SourceParser.parse" => {
:locations => [["yard.rb", 12]],
:comments => ["@see"]
}
)
end
it "extracts at tag text" do
object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
o.docstring = <<-eod
@example Parse a glob of files
YARD.parse('lib/**/*.rb')
eod
o.files = [["yard.rb", 12]]
end
@generator.parse_objects([object])
expect(@generator.messages).to eq create_messages(
"tag|example|Parse a glob of files" => {
:locations => [["yard.rb", 12]],
:comments => ["@example"]
},
"YARD.parse('lib/**/*.rb')" => {
:locations => [["yard.rb", 12]],
:comments => ["@example Parse a glob of files"]
}
)
end
it "extracts at tag types" do
object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
o.docstring = <<-eod
@param [String, Array] paths a path, glob, or list of paths to
parse
eod
o.files = [["yard.rb", 12]]
end
@generator.parse_objects([object])
expect(@generator.messages).to eq create_messages(
"tag|param|paths" => {
:locations => [["yard.rb", 12]],
:comments => ["@param [String, Array]"]
},
"a path, glob, or list of paths to\nparse" => {
:locations => [["yard.rb", 12]],
:comments => ["@param [String, Array] paths"]
}
)
end
it "extracts at overload tag recursively" do
object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
o.docstring = <<-eod
@overload foo(i)
docstring foo(i)
@param [Integer] i integer parameter
eod
end
@generator.parse_objects([object])
expect(@generator.messages).to eq create_messages(
"tag|overload|foo" => {
:locations => [],
:comments => ["@overload"]
},
"docstring foo(i)" => {
:locations => [],
:comments => ["YARD.parse"]
},
"tag|param|i" => {
:locations => [],
:comments => ["@param [Integer]"]
},
"integer parameter" => {
:locations => [],
:comments => ["@param [Integer] i"]
}
)
end
end
describe "File" do
it "extracts at attribute" do
path = "GettingStarted.md"
text = <<-eor
# @title Getting Started Guide
# Getting Started with YARD
eor
allow(File).to receive(:open).with(path).and_yield(StringIO.new(text))
allow(File).to receive(:read).with(path).and_return(text)
file = YARD::CodeObjects::ExtraFileObject.new(path)
@generator.parse_files([file])
expect(@generator.messages).to eq create_messages(
"Getting Started Guide" => {
:locations => [[path, 1]],
:comments => ["title"]
},
"# Getting Started with YARD" => {
:locations => [[path, 3]],
:comments => []
}
)
end
it "extracts at paragraphs" do
path = "README.md"
paragraph1 = <<-eop.strip
Note that class methods must not be referred to with the "::" namespace
separator. Only modules, classes and constants should use "::".
eop
paragraph2 = <<-eop.strip
You can also do lookups on any installed gems. Just make sure to build the
.yardoc databases for installed gems with:
eop
text = <<-eot
#{paragraph1}
#{paragraph2}
eot
allow(File).to receive(:open).with(path).and_yield(StringIO.new(text))
allow(File).to receive(:read).with(path).and_return(text)
file = YARD::CodeObjects::ExtraFileObject.new(path)
@generator.parse_files([file])
expect(@generator.messages).to eq create_messages(
paragraph1 => {
:locations => [[path, 1]],
:comments => []
},
paragraph2 => {
:locations => [[path, 4]],
:comments => []
}
)
end
end
end
yard-0.9.7/spec/i18n/text_spec.rb 0000644 0000041 0000041 00000007543 13035234564 016570 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::I18n::Text do
describe "#extract_messages" do
def extract_messages(input, options = {})
text = YARD::I18n::Text.new(StringIO.new(input), options)
messages = []
text.extract_messages do |*message|
messages << message
end
messages
end
describe "Header" do
it "extracts at attribute" do
text = <<-eot
# @title Getting Started Guide
# Getting Started with YARD
eot
expect(extract_messages(text, :have_header => true)).to eq(
[[:attribute, "title", "Getting Started Guide", 1],
[:paragraph, "# Getting Started with YARD", 3]]
)
end
it "ignores markup line" do
text = <<-eot
#!markdown
# @title Getting Started Guide
# Getting Started with YARD
eot
expect(extract_messages(text, :have_header => true)).to eq(
[[:attribute, "title", "Getting Started Guide", 2],
[:paragraph, "# Getting Started with YARD", 4]]
)
end
it "terminates header block by markup line not at the first line" do
text = <<-eot
# @title Getting Started Guide
#!markdown
# Getting Started with YARD
eot
expect(extract_messages(text, :have_header => true)).to eq(
[[:attribute, "title", "Getting Started Guide", 1],
[:paragraph, "#!markdown", 2],
[:paragraph, "# Getting Started with YARD", 4]]
)
end
end
describe "Body" do
it "splits to paragraphs" do
paragraph1 = <<-eop.strip
Note that class methods must not be referred to with the "::" namespace
separator. Only modules, classes and constants should use "::".
eop
paragraph2 = <<-eop.strip
You can also do lookups on any installed gems. Just make sure to build the
.yardoc databases for installed gems with:
eop
text = <<-eot
#{paragraph1}
#{paragraph2}
eot
expect(extract_messages(text)).to eq(
[[:paragraph, paragraph1, 1],
[:paragraph, paragraph2, 4]]
)
end
end
end
describe "#translate" do
def locale
locale = YARD::I18n::Locale.new("fr")
messages = locale.instance_variable_get(:@messages)
messages["markdown"] = "markdown (markdown in fr)"
messages["Hello"] = "Bonjour (Hello in fr)"
messages["Paragraph 1."] = "Paragraphe 1."
messages["Paragraph 2."] = "Paragraphe 2."
locale
end
def translate(input, options = {})
text = YARD::I18n::Text.new(StringIO.new(input), options)
text.translate(locale)
end
describe "Header" do
it "extracts at attribute" do
text = <<-eot
# @title Hello
# Getting Started with YARD
Paragraph.
eot
expect(translate(text, :have_header => true)).to eq <<-eot
# @title Bonjour (Hello in fr)
# Getting Started with YARD
Paragraph.
eot
end
it "ignores markup line" do
text = <<-eot
#!markdown
# @title Hello
# Getting Started with YARD
Paragraph.
eot
expect(translate(text, :have_header => true)).to eq <<-eot
#!markdown
# @title Bonjour (Hello in fr)
# Getting Started with YARD
Paragraph.
eot
end
end
describe "Body" do
it "splits to paragraphs" do
paragraph1 = <<-eop.strip
Paragraph 1.
eop
paragraph2 = <<-eop.strip
Paragraph 2.
eop
text = <<-eot
#{paragraph1}
#{paragraph2}
eot
expect(translate(text)).to eq <<-eot
Paragraphe 1.
Paragraphe 2.
eot
end
it "does not modify non-translated message" do
nonexistent_paragraph = <<-eop.strip
Nonexsitent paragraph.
eop
text = <<-eot
#{nonexistent_paragraph}
eot
expect(translate(text)).to eq <<-eot
#{nonexistent_paragraph}
eot
end
it "keeps empty lines" do
text = <<-eot
Paragraph 1.
Paragraph 2.
eot
expect(translate(text)).to eq <<-eot
Paragraphe 1.
Paragraphe 2.
eot
end
end
end
end
yard-0.9.7/spec/i18n/locale_spec.rb 0000644 0000041 0000041 00000003714 13035234564 017037 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::I18n::Locale do
def locale(name)
YARD::I18n::Locale.new(name)
end
before do
@locale = locale("fr")
end
describe "#name" do
it "returns name" do
expect(locale("fr").name).to eq "fr"
end
end
describe "#load" do
it "returns false for nonexistent PO" do
expect(File).to receive(:exist?).with('foo/fr.po').and_return(false)
expect(@locale.load('foo')).to be false
end
have_gettext_gem = true
if RUBY_VERSION < "1.9"
begin
require "gettext/tools/poparser"
rescue LoadError
have_gettext_gem = false
end
else
begin
require "gettext/po_parser"
rescue LoadError
begin
require "gettext/tools/poparser"
rescue LoadError
have_gettext_gem = false
end
end
end
it "returns true for existent PO", :if => have_gettext_gem do
data = <<-eop
msgid ""
msgstr ""
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
msgid "Hello"
msgstr "Bonjour"
eop
parser = GetText::POParser.new
expect(File).to receive(:exist?).with('foo/fr.po').and_return(true)
expect(GetText::POParser).to receive(:new).and_return(parser)
expect(parser).to receive(:parse_file) do |file, hash|
expect(file).to eq 'foo/fr.po'
parser.parse(String.new(data), hash)
end
expect(@locale.load('foo')).to be true
expect(@locale.translate('Hello')).to eq "Bonjour"
end
end
describe "#translate" do
before do
messages = @locale.instance_variable_get(:@messages)
messages["Hello"] = "Bonjour"
end
it "returns translated string for existent string" do
expect(@locale.translate("Hello")) == "Bonjour"
end
it "returns original string for nonexistent string" do
expect(@locale.translate("nonexistent")) == "nonexistent"
end
end
end
yard-0.9.7/spec/i18n/messages_spec.rb 0000644 0000041 0000041 00000003306 13035234564 017404 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::I18n::Messages do
def message(id)
YARD::I18n::Message.new(id)
end
def messages
YARD::I18n::Messages.new
end
before do
@messages = messages
end
describe "#each" do
it "enumerates messages" do
@messages.register("Hello World!")
@messages.register("Title")
enumerated_messages = []
@messages.each do |message|
enumerated_messages << message
end
enumerated_messages = enumerated_messages.sort_by(&:id)
expect(enumerated_messages).to eq [message("Hello World!"), message("Title")]
end
it "does not yield any message if there are none" do
enumerated_messages = []
@messages.each do |message|
enumerated_messages << message
end
expect(enumerated_messages).to eq []
end
end
describe "#[]" do
it "returns registered message" do
@messages.register("Hello World!")
expect(@messages["Hello World!"]).to eq message("Hello World!")
end
it "returns nil for nonexistent message ID" do
expect(@messages["Hello World!"]).to eq nil
end
end
describe "#register" do
it "returns registered message" do
expect(@messages.register("Hello World!")).to eq message("Hello World!")
end
it "returns existent message" do
message = @messages.register("Hello World!")
expect(@messages.register("Hello World!").object_id).to eq message.object_id
end
end
describe "#==" do
it "returns true for same value messages" do
@messages.register("Hello World!")
other_messages = messages
other_messages.register("Hello World!")
expect(@messages).to eq other_messages
end
end
end
yard-0.9.7/spec/i18n/message_spec.rb 0000644 0000041 0000041 00000002467 13035234564 017230 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::I18n::Message do
def message(id)
YARD::I18n::Message.new(id)
end
before do
@message = message("Hello World!")
end
describe "#id" do
it "returns ID" do
expect(message("Hello World!").id).to eq "Hello World!"
end
end
describe "#add_location" do
it "adds some locations" do
@message.add_location("hello.rb", 10)
@message.add_location("message.rb", 5)
expect(@message.locations).to eq Set.new([["hello.rb", 10], ["message.rb", 5]])
end
end
describe "#add_comment" do
it "adds some comments" do
@message.add_comment("YARD.title")
@message.add_comment("Hello#message")
expect(@message.comments).to eq Set.new(["YARD.title", "Hello#message"])
end
end
describe "#==" do
it "returns true for same value messages" do
locations = [["hello.rb", 10], ["message.rb", 5]]
comments = ["YARD.title", "Hello#message"]
other_message = message(@message.id)
locations.each do |path, line|
@message.add_location(path, line)
other_message.add_location(path, line)
end
comments.each do |comment|
@message.add_comment(comment)
other_message.add_comment(comment)
end
expect(@message).to eq other_message
end
end
end
yard-0.9.7/spec/serializers/ 0000755 0000041 0000041 00000000000 13035234564 016011 5 ustar www-data www-data yard-0.9.7/spec/serializers/data/ 0000755 0000041 0000041 00000000000 13035234564 016722 5 ustar www-data www-data yard-0.9.7/spec/serializers/data/serialized_yardoc/ 0000755 0000041 0000041 00000000000 13035234564 022416 5 ustar www-data www-data yard-0.9.7/spec/serializers/data/serialized_yardoc/checksums 0000644 0000041 0000041 00000000061 13035234564 024323 0 ustar www-data www-data test.rb 80e5834ff1e98223761615c0917ff9b77b7ae057
yard-0.9.7/spec/serializers/data/serialized_yardoc/objects/ 0000755 0000041 0000041 00000000000 13035234564 024047 5 ustar www-data www-data yard-0.9.7/spec/serializers/data/serialized_yardoc/objects/Foo/ 0000755 0000041 0000041 00000000000 13035234564 024572 5 ustar www-data www-data yard-0.9.7/spec/serializers/data/serialized_yardoc/objects/Foo/baz_i.dat 0000644 0000041 0000041 00000000623 13035234564 026351 0 ustar www-data www-data o:$YARD::CodeObjects::MethodObject: @scope:
instance:@visibility: public:@parameters[ : @files[[I" test.rb:ETi[@ i: @current_file_has_commentsF:
@name:baz:@source_type: ruby:
@tags[ :@docstringIC:YARD::Docstring" ; F: @objectIu:YARD::StubProxy Foo#baz; F:
@summary0:@ref_tags[ ;[ : @all0:@line_range0:@namespaceIu;Foo; F: @sourceI"def bar; end; F:@signatureI"def bar( ); F yard-0.9.7/spec/serializers/data/serialized_yardoc/objects/Foo/bar_i.dat 0000644 0000041 0000041 00000000637 13035234564 026346 0 ustar www-data www-data o:$YARD::CodeObjects::MethodObject: @scope:
instance:@visibility: public:@parameters[ : @files[[I" test.rb:ETi: @current_file_has_commentsF:
@name:bar:@source_type: ruby:
@tags[ :@docstringIC:YARD::Docstring" ; F: @objectIu:YARD::StubProxy Foo#bar; F:
@summary0:@ref_tags[ ;[ : @allI" ; F:@line_range0:@namespaceIu;Foo; F: @sourceI"def bar; end; F:@signatureI"def bar( ); F:@explicitT yard-0.9.7/spec/serializers/data/serialized_yardoc/objects/root.dat 0000644 0000041 0000041 00000000750 13035234564 025526 0 ustar www-data www-data o:"YARD::CodeObjects::RootObject:@childrenIC:&YARD::CodeObjects::CodeObjectList[Iu:YARD::StubProxyFoo:EF: @ownerIu; ; F:@class_mixinsIC;[ ;
Iu; ; F:@instance_mixinsIC;[ ;
Iu; ; F:@attributesIC:SymbolHash{:
classIC;{ :@symbolize_valueT:
instanceIC;{ ;T;T:
@aliases{ : @files[ : @current_file_has_commentsF:
@name: root:@source_type: ruby:
@tags[ :@docstringIC:YARD::Docstring" ; F: @objectIu; ; F:
@summary0:@ref_tags[ ;[ : @allI" ; F:@namespace0 yard-0.9.7/spec/serializers/data/serialized_yardoc/objects/Foo.dat 0000644 0000041 0000041 00000001262 13035234564 025265 0 ustar www-data www-data o:#YARD::CodeObjects::ClassObject:@childrenIC:&YARD::CodeObjects::CodeObjectList[Iu:YARD::StubProxy Foo#bar:EFIu; Foo#baz; F: @ownerIu;Foo; F:@class_mixinsIC;[ ;
Iu;Foo; F:@instance_mixinsIC;[ ;
Iu;Foo; F:@attributesIC:SymbolHash{:
classIC;{ :@symbolize_valueT:
instanceIC;{ ;T;T:
@aliases{Iu; Foo#baz; F:bar: @files[[I" test.rb; Ti: @current_file_has_commentsF:
@name:Foo:@source_type: ruby:
@tags[ :@docstringIC:YARD::Docstring" ; F: @objectIu;Foo; F:
@summary0:@ref_tags[ ;[ : @allI" ; F:@line_range0:@namespaceIu; ; F:@superclasso: YARD::CodeObjects::Proxy :
@imethod0:@origname0:@orignamespace0;: Object;"Iu; ; F: @obj0 yard-0.9.7/spec/serializers/data/serialized_yardoc/proxy_types 0000644 0000041 0000041 00000000031 13035234564 024740 0 ustar www-data www-data {I" Object:EF:
class yard-0.9.7/spec/serializers/spec_helper.rb 0000644 0000041 0000041 00000000053 13035234564 020625 0 ustar www-data www-data # frozen_string_literal: true
include YARD
yard-0.9.7/spec/serializers/yardoc_serializer_spec.rb 0000644 0000041 0000041 00000005400 13035234564 023061 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"
instance_eval do
class YARD::Serializers::YardocSerializer
public :dump
public :internal_dump
end
end
RSpec.describe YARD::Serializers::YardocSerializer do
before do
@serializer = YARD::Serializers::YardocSerializer.new('.yardoc')
Registry.clear
@foo = CodeObjects::ClassObject.new(:root, :Foo)
@bar = CodeObjects::MethodObject.new(@foo, :bar)
end
describe "#dump" do
it "maintains object equality when loading a dumped object" do
newfoo = @serializer.internal_dump(@foo)
expect(newfoo).to equal(@foo)
expect(newfoo).to eq @foo
expect(@foo).to equal(newfoo)
expect(@foo).to eq newfoo
expect(newfoo.hash).to eq @foo.hash
end
it "maintains hash key equality when loading a dumped object" do
newfoo = @serializer.internal_dump(@foo)
expect(@foo => 1).to have_key(newfoo)
expect(newfoo => 1).to have_key(@foo)
end
end
describe "#serialize" do
it "accepts a hash of codeobjects (and write to root)" do
data = {:root => Registry.root}
marshaldata = Marshal.dump(data)
filemock = double(:file)
expect(filemock).to receive(:write).with(marshaldata)
expect(File).to receive(:open!).with('.yardoc/objects/root.dat', 'wb').and_yield(filemock)
@serializer.serialize(data)
end
end
describe "#lock_for_writing" do
it "creates a lock file during writing and cleans up" do
expect(File).to receive(:open!).with(@serializer.processing_path, 'w')
expect(File).to receive(:exist?).with(@serializer.processing_path).exactly(2).times.and_return(true)
expect(File).to receive(:unlink).with(@serializer.processing_path)
@serializer.lock_for_writing do
expect(@serializer.locked_for_writing?).to eq true
end
end
end
describe "#complete?" do
it "returns false if complete file does not exist" do
allow(File).to receive(:exist?).with(@serializer.complete_lock_path).and_return(false)
allow(File).to receive(:exist?).with(@serializer.processing_path).and_return(false)
expect(@serializer.complete?).to eq false
end
it "returns false if processing file exists" do
allow(File).to receive(:exist?).with(@serializer.complete_lock_path).and_return(true)
allow(File).to receive(:exist?).with(@serializer.processing_path).and_return(true)
expect(@serializer.complete?).to eq false
end
it "returns true if complete file exists with no processing file" do
allow(File).to receive(:exist?).with(@serializer.complete_lock_path).and_return(true)
allow(File).to receive(:exist?).with(@serializer.processing_path).and_return(false)
expect(@serializer.complete?).to eq true
end
end
end
yard-0.9.7/spec/serializers/file_system_serializer_spec.rb 0000644 0000041 0000041 00000011374 13035234564 024132 0 ustar www-data www-data # frozen_string_literal: true
require File.join(File.dirname(__FILE__), "spec_helper")
require 'stringio'
RSpec.describe YARD::Serializers::FileSystemSerializer do
before do
allow(FileUtils).to receive(:mkdir_p)
allow(File).to receive(:open)
end
describe "#basepath" do
it "defaults the base path to the 'doc/'" do
obj = Serializers::FileSystemSerializer.new
expect(obj.basepath).to eq 'doc'
end
end
describe "#extension" do
it "defaults the file extension to .html" do
obj = Serializers::FileSystemSerializer.new
expect(obj.extension).to eq "html"
end
end
describe "#serialized_path" do
it "allows no extension to be used" do
obj = Serializers::FileSystemSerializer.new :extension => nil
yard = CodeObjects::ClassObject.new(nil, :FooBar)
expect(obj.serialized_path(yard)).to eq 'FooBar'
end
it "serializes to top-level-namespace for root" do
obj = Serializers::FileSystemSerializer.new :extension => nil
expect(obj.serialized_path(Registry.root)).to eq "top-level-namespace"
end
it "returns serialized_path for a String" do
s = Serializers::FileSystemSerializer.new(:basepath => 'foo', :extension => 'txt')
expect(s.serialized_path('test.txt')).to eq 'test.txt'
end
it "removes special chars from path" do
m = CodeObjects::MethodObject.new(nil, 'a')
s = Serializers::FileSystemSerializer.new
{:gsub! => 'gsub_21_i.html',
:ask? => 'ask_3F_i.html',
:=== => '_3D_3D_3D_i.html',
:+ => '_2B_i.html',
:- => '-_i.html',
:[]= => '_5B_5D_3D_i.html',
:<< => '_3C_3C_i.html',
:>= => '_3E_3D_i.html',
:` => '_60_i.html',
:& => '_26_i.html',
:* => '_2A_i.html',
:| => '_7C_i.html',
:/ => '_2F_i.html',
:=~ => '_3D_7E_i.html'}.each do |meth, value|
allow(m).to receive(:name).and_return(meth)
expect(s.serialized_path(m)).to eq value
end
end
it "handles ExtraFileObject's" do
s = Serializers::FileSystemSerializer.new
e = CodeObjects::ExtraFileObject.new('filename.txt', '')
expect(s.serialized_path(e)).to eq 'file.filename.html'
end
it "differentiates instance and class methods from serialized path" do
s = Serializers::FileSystemSerializer.new
m1 = CodeObjects::MethodObject.new(nil, 'meth')
m2 = CodeObjects::MethodObject.new(nil, 'meth', :class)
expect(s.serialized_path(m1)).not_to eq s.serialized_path(m2)
end
it "serializes path from overload tag" do
YARD.parse_string <<-'eof'
class Foo
# @overload bar
def bar; end
end
eof
serializer = Serializers::FileSystemSerializer.new
object = Registry.at('Foo#bar').tag(:overload)
expect(serializer.serialized_path(object)).to eq "Foo/bar_i.html"
end
it "maps matching case sensitive object names to different files on disk" do
Registry.clear
o1 = CodeObjects::ClassObject.new(:root, "AB")
o2 = CodeObjects::ClassObject.new(:root, "Ab")
s = Serializers::FileSystemSerializer.new
expect([["AB_.html", "Ab.html"], ["AB.html", "Ab_.html"]]).to include(
[s.serialized_path(o1), s.serialized_path(o2)]
)
end
it "handles case sensitivity of nested paths for objects with matching names" do
Registry.clear
YARD.parse_string <<-eof
class Abc; class D; end end
class ABC; class D; end end
eof
s = Serializers::FileSystemSerializer.new
expect(s.serialized_path(Registry.at('ABC::D'))).to eq "ABC/D.html"
expect(s.serialized_path(Registry.at('Abc::D'))).to eq "Abc/D.html"
end
end
describe "#serialize" do
it "serializes to the correct path" do
yard = CodeObjects::ClassObject.new(nil, :FooBar)
meth = CodeObjects::MethodObject.new(yard, :baz, :class)
meth2 = CodeObjects::MethodObject.new(yard, :baz)
{'foo/FooBar/baz_c.txt' => meth,
'foo/FooBar/baz_i.txt' => meth2,
'foo/FooBar.txt' => yard}.each do |path, obj|
io = StringIO.new
expect(File).to receive(:open).with(path, 'wb').and_yield(io)
expect(io).to receive(:write).with("data")
s = Serializers::FileSystemSerializer.new(:basepath => 'foo', :extension => 'txt')
s.serialize(obj, "data")
end
end
it "guarantees the directory exists" do
o1 = CodeObjects::ClassObject.new(nil, :Really)
o2 = CodeObjects::ClassObject.new(o1, :Long)
o3 = CodeObjects::ClassObject.new(o2, :PathName)
obj = CodeObjects::MethodObject.new(o3, :foo)
expect(FileUtils).to receive(:mkdir_p).once.with('doc/Really/Long/PathName')
s = Serializers::FileSystemSerializer.new
s.serialize(obj, "data")
end
end
end
yard-0.9.7/spec/code_objects/ 0000755 0000041 0000041 00000000000 13035234564 016100 5 ustar www-data www-data yard-0.9.7/spec/code_objects/proxy_spec.rb 0000644 0000041 0000041 00000010347 13035234564 020625 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::Proxy do
before { Registry.clear }
it "returns the object if it's in the Registry" do
ModuleObject.new(:root, :YARD)
proxyobj = P(:root, :YARD)
expect(proxyobj.type).to eq :module
expect(Proxy === proxyobj).to be false
end
it "handles complex string namespaces" do
ModuleObject.new(:root, :A)
ModuleObject.new(P(nil, :A), :B)
expect(P(:root, "A::B")).to be_instance_of(ModuleObject)
end
it "does not return true to Proxy === obj if obj is a Proxy class holding a resolved object" do
expect(Proxy === P(:root, 'a')).to be true
expect(Proxy === P(:root)).to be false
MethodObject.new(:root, 'a')
expect(Proxy === P(:root, 'a')).to be false
x = Proxy.new(:root, 'a')
expect(Proxy === x).to be false
end
it "returns the object if it's an included Module" do
yardobj = ModuleObject.new(:root, :YARD)
pathobj = ClassObject.new(:root, :TestClass)
pathobj.instance_mixins << yardobj
expect(P(P(nil, :TestClass), :YARD)).to be_instance_of(ModuleObject)
end
it "responds to respond_to?" do
ClassObject.new(:root, :Object)
ModuleObject.new(:root, :YARD)
expect(P(:YARD).respond_to?(:children)).to be true
expect(P(:NOTYARD).respond_to?(:children)).to be false
expect(P(:YARD).respond_to?(:initialize)).to be false
expect(P(:YARD).respond_to?(:initialize, true)).to be true
expect(P(:NOTYARD).respond_to?(:initialize)).to be false
expect(P(:NOTYARD).respond_to?(:initialize, true)).to be true
end
it "makes itself obvious that it's a proxy" do
pathobj = P(:root, :YARD)
expect(pathobj.class).to eq Proxy
expect(Proxy === pathobj).to be true
end
it "pretends it's the object's type if it can resolve" do
ModuleObject.new(:root, :YARD)
proxyobj = P(:root, :YARD)
expect(proxyobj).to be_instance_of(ModuleObject)
end
it "handles instance method names" do
obj = P(nil, '#test')
expect(obj.name).to eq :test
expect(obj.path).to eq "#test"
expect(obj.namespace).to eq Registry.root
end
it "handles instance method names under a namespace" do
pathobj = ModuleObject.new(:root, :YARD)
obj = P(pathobj, "A::B#test")
expect(obj.name).to eq :test
expect(obj.path).to eq "A::B#test"
end
it "allows type to be changed" do
obj = P("InvalidClass")
expect(obj.type).to eq :proxy
expect(Proxy === obj).to be true
obj.type = :class
expect(obj.type).to eq :class
end
it "does NOT retain a type change between Proxy objects" do
P("InvalidClass").type = :class
expect(P("InvalidClass").type).to eq :proxy
end
it "uses type to ensure resolved object is of intended type" do
YARD.parse_string <<-eof
module Foo
class Bar; end
def self.Bar; end
end
eof
proxy = Proxy.new(P('Foo'), 'Bar')
proxy.type = :method
expect(proxy.path).to eq 'Foo.Bar'
end
it "allows type in initializer" do
expect(Proxy.new(Registry.root, 'Foo', :method).type).to eq :method
expect(P(Registry.root, 'Foo', :method).type).to eq :method
end
it "never equals Registry.root" do
expect(P("MYPROXY")).not_to eq Registry.root
expect(P("X::A")).not_to eq Registry.root
end
it "resets namespace and name when object is resolved" do
obj1 = ModuleObject.new(:root, :YARD)
obj2 = ModuleObject.new(:root, :NOTYARD)
resolved = Proxy.new(obj2, :YARD)
expect(resolved).to eq obj1
expect(resolved.namespace).to eq Registry.root
expect(resolved.name).to eq :YARD
end
it "ensures that the correct object was resolved" do
foo = ModuleObject.new(:root, :Foo)
foobar = ModuleObject.new(foo, :Bar)
ClassObject.new(foo, :Baz)
# Remember, we're looking for Qux::Bar, not just 'Bar'
proxy = Proxy.new(foobar, 'Foo::Qux::Bar')
expect(proxy.type).to eq :proxy
qux = ModuleObject.new(foo, :Qux)
ModuleObject.new(qux, :Bar)
# Now it should resolve
expect(proxy.type).to eq :module
end
it "handles constant names in namespaces" do
YARD.parse_string <<-eof
module A; end; B = A
module B::C; def foo; end end
eof
expect(Proxy.new(:root, 'B::C')).to eq Registry.at('A::C')
end
end
yard-0.9.7/spec/code_objects/extra_file_object_spec.rb 0000644 0000041 0000041 00000013112 13035234564 023105 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::ExtraFileObject do
describe "#initialize" do
it "attempts to read contents from filesystem if contents=nil" do
expect(File).to receive(:read).with('file.txt').and_return('')
ExtraFileObject.new('file.txt')
end
it "raises Errno::ENOENT if contents=nil and file does not exist" do
expect { ExtraFileObject.new('file.txt') }.to raise_error(Errno::ENOENT)
end
it "does not attempt to read from disk if contents are provided" do
# TODO: no assertions here!
ExtraFileObject.new('file.txt', 'CONTENTS')
end
it "sets filename to filename" do
file = ExtraFileObject.new('a/b/c/file.txt', 'CONTENTS')
expect(file.filename).to eq "a/b/c/file.txt"
end
it "parses out attributes at top of the file" do
file = ExtraFileObject.new('file.txt', "# @title X\n# @some_attribute Y\nFOO BAR")
expect(file.attributes[:title]).to eq "X"
expect(file.attributes[:some_attribute]).to eq "Y"
expect(file.contents).to eq "FOO BAR"
end
it "allows whitespace prior to '#' marker when parsing attributes" do
file = ExtraFileObject.new('file.txt', " \t # @title X\nFOO BAR")
expect(file.attributes[:title]).to eq "X"
expect(file.contents).to eq "FOO BAR"
end
it "allows the attributes section to be wrapped in an HTML comment" do
file = ExtraFileObject.new('file.txt', "\nFOO BAR")
expect(file.attributes[:title]).to eq "X"
expect(file.contents).to eq "FOO BAR"
end
it "allows whitespace around ignored HTML comment" do
file = ExtraFileObject.new('file.txt', " \t \nFOO BAR")
expect(file.attributes[:title]).to eq "X"
expect(file.contents).to eq "FOO BAR"
end
it "parses out old-style #!markup shebang format" do
file = ExtraFileObject.new('file.txt', "#!foobar\nHello")
expect(file.attributes[:markup]).to eq "foobar"
end
it "does not parse old-style #!markup if any whitespace is found" do
file = ExtraFileObject.new('file.txt', " #!foobar\nHello")
expect(file.attributes[:markup]).to be nil
expect(file.contents).to eq " #!foobar\nHello"
end
it "does not parse out attributes if there are newlines prior to attributes" do
file = ExtraFileObject.new('file.txt', "\n# @title\nFOO BAR")
expect(file.attributes).to be_empty
expect(file.contents).to eq "\n# @title\nFOO BAR"
end
it "sets contents to data after attributes" do
file = ExtraFileObject.new('file.txt', "# @title\nFOO BAR")
expect(file.contents).to eq "FOO BAR"
end
it "preserves newlines" do
file = ExtraFileObject.new('file.txt', "FOO\r\nBAR\nBAZ")
expect(file.contents).to eq "FOO\r\nBAR\nBAZ"
end
it "does not include newlines in attribute data" do
file = ExtraFileObject.new('file.txt', "# @title FooBar\r\nHello world")
expect(file.attributes[:title]).to eq "FooBar"
end
it "forces encoding to @encoding attribute if present" do
expect(log).not_to receive(:warn)
data = String.new("# @encoding sjis\nFOO")
data.force_encoding('binary')
file = ExtraFileObject.new('file.txt', data)
expect(['Shift_JIS', 'Windows-31J']).to include(file.contents.encoding.to_s)
end if YARD.ruby19?
it "warns if @encoding is invalid" do
expect(log).to receive(:warn).with("Invalid encoding `INVALID' in file.txt")
data = String.new("# @encoding INVALID\nFOO")
encoding = data.encoding
file = ExtraFileObject.new('file.txt', data)
expect(file.contents.encoding).to eq encoding
end if YARD.ruby19?
it "ignores encoding in 1.8.x (or encoding-unaware platforms)" do
expect(log).not_to receive(:warn)
ExtraFileObject.new('file.txt', "# @encoding INVALID\nFOO")
end if YARD.ruby18?
it "attempts to re-parse data as 8-bit ascii if parsing fails" do
expect(log).not_to receive(:warn)
str, out = *([String.new("\xB0")] * 2)
if str.respond_to?(:force_encoding)
str.force_encoding('utf-8')
out.force_encoding('binary')
end
file = ExtraFileObject.new('file.txt', str)
expect(file.contents).to eq out
end
end
describe "#name" do
it "returns basename (not extension) of filename" do
file = ExtraFileObject.new('file.txt', '')
expect(file.name).to eq 'file'
end
end
describe "#title" do
it "returns @title attribute if present" do
file = ExtraFileObject.new('file.txt', '# @title FOO')
expect(file.title).to eq 'FOO'
end
it "returns #name if no @title attribute exists" do
file = ExtraFileObject.new('file.txt', '')
expect(file.title).to eq 'file'
end
end
describe "#locale=" do
it "translates contents" do
file = ExtraFileObject.new('file.txt', 'Hello')
file.locale = 'fr'
fr_locale = I18n::Locale.new('fr')
fr_messages = fr_locale.instance_variable_get(:@messages)
fr_messages["Hello"] = 'Bonjour'
expect(Registry).to receive(:locale).with('fr').and_return(fr_locale)
expect(file.contents).to eq 'Bonjour'
end
end
describe "#==" do
it "defines equality based on filename alone" do
file1 = ExtraFileObject.new('file.txt', 'A')
file2 = ExtraFileObject.new('file.txt', 'B')
expect(file1).to eq file2
expect(file1).to eql file2
expect(file1).to equal file2
# Another way to test the equality interface
a = [file1]
a |= [file2]
expect(a.size).to eq 1
end
end
end
yard-0.9.7/spec/code_objects/class_object_spec.rb 0000644 0000041 0000041 00000015432 13035234564 022077 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::ClassObject do
describe "#inheritance_tree" do
before(:all) do
Registry.clear
@mixin = ModuleObject.new(:root, :SomeMixin)
@mixin2 = ModuleObject.new(:root, :SomeMixin2)
@mixin2.instance_mixins << @mixin
@mixin3 = ModuleObject.new(:root, :SomeMixin3)
@mixin4 = ModuleObject.new(:root, :SomeMixin4)
@mixin2.instance_mixins << @mixin3
@superyard = ClassObject.new(:root, :SuperYard)
@superyard.superclass = P("String")
@superyard.instance_mixins << @mixin2
@superyard.class_mixins << @mixin4
@yard = ClassObject.new(:root, :YARD)
@yard.superclass = @superyard
@yard.instance_mixins << @mixin
end
it "shows the proper inheritance tree" do
expect(@yard.inheritance_tree).to eq [@yard, @superyard, P(:String)]
end
it "shows proper inheritance tree when mixins are included" do
expect(@yard.inheritance_tree(true)).to eq [@yard, @mixin, @superyard, @mixin4, @mixin2, @mixin3, P(:String)]
end
it "does not modify the object's mixin list when mixins are included" do
@class1 = ClassObject.new(:root, :A)
@class2 = ClassObject.new(:root, :B)
@class2.superclass = @class1
@class2.inheritance_tree(true)
expect(@class2.mixins).to eq []
end
it "lists class mixins in inheritance tree" do
mod = ModuleObject.new(:root, :ClassMethods)
klass = ClassObject.new(:root, :ReceivingClass)
klass.class_mixins << mod
expect(klass.inheritance_tree(true)).to eq [klass, mod]
end
end
describe "#meths / #inherited_meths" do
before(:all) do
Registry.clear
YARD.parse_string <<-eof
class SuperYard < String
def foo; end
def foo2; end
def bar; end
def middle; end
protected :foo2
private
def self.bar; end
end
class MiddleYard < SuperYard
def middle; end
end
class YARD < MiddleYard
def mymethod; end
def bar; end
end
module IncludedYard
def foo; end
end
class FinalYard < SuperYard
include IncludedYard
end
eof
end
it "shows inherited methods by default" do
meths = P(:YARD).meths
expect(meths).to include(P("YARD#mymethod"))
expect(meths).to include(P("SuperYard#foo"))
expect(meths).to include(P("SuperYard#foo2"))
expect(meths).to include(P("SuperYard.bar"))
end
it "allows :inherited to be set to false" do
meths = P(:YARD).meths(:inherited => false)
expect(meths).to include(P("YARD#mymethod"))
expect(meths).not_to include(P("SuperYard#foo"))
expect(meths).not_to include(P("SuperYard#foo2"))
expect(meths).not_to include(P("SuperYard.bar"))
end
it "does not show overridden methods" do
meths = P(:YARD).meths
expect(meths).to include(P("YARD#bar"))
expect(meths).not_to include(P("SuperYard#bar"))
meths = P(:YARD).inherited_meths
expect(meths).not_to include(P("YARD#bar"))
expect(meths).not_to include(P("YARD#mymethod"))
expect(meths).to include(P("SuperYard#foo"))
expect(meths).to include(P("SuperYard#foo2"))
expect(meths).to include(P("SuperYard.bar"))
end
it "does not show inherited methods overridden by other subclasses" do
meths = P(:YARD).inherited_meths
expect(meths).to include(P('MiddleYard#middle'))
expect(meths).not_to include(P('SuperYard#middle'))
end
it "shows mixed in methods before superclass method" do
meths = P(:FinalYard).meths
expect(meths).to include(P('IncludedYard#foo'))
expect(meths).not_to include(P('SuperYard#foo'))
end
end
describe "#constants / #inherited_constants" do
before(:all) do
Registry.clear
Parser::SourceParser.parse_string <<-eof
class YARD
CONST1 = 1
CONST2 = "hello"
CONST4 = 0
end
class SUPERYARD < YARD
CONST4 = 5
end
class SubYard < SUPERYARD
CONST2 = "hi"
CONST3 = "foo"
end
eof
end
it "lists inherited constants by default" do
consts = P(:SubYard).constants
expect(consts).to include(P("YARD::CONST1"))
expect(consts).to include(P("SubYard::CONST3"))
consts = P(:SubYard).inherited_constants
expect(consts).to include(P("YARD::CONST1"))
expect(consts).not_to include(P("YARD::CONST2"))
expect(consts).not_to include(P("SubYard::CONST2"))
expect(consts).not_to include(P("SubYard::CONST3"))
end
it "does not list inherited constants if turned off" do
consts = P(:SubYard).constants(:inherited => false)
expect(consts).not_to include(P("YARD::CONST1"))
expect(consts).to include(P("SubYard::CONST3"))
end
it "does not include an inherited constant if it is overridden by the object" do
consts = P(:SubYard).constants
expect(consts).to include(P("SubYard::CONST2"))
expect(consts).not_to include(P("YARD::CONST2"))
end
it "does not include an inherited constant if it is overridden by another subclass" do
consts = P(:SubYard).inherited_constants
expect(consts).to include(P("SUPERYARD::CONST4"))
expect(consts).not_to include(P("YARD::CONST4"))
end
it "does not set a superclass on BasicObject class" do
o = ClassObject.new(:root, :BasicObject)
expect(o.superclass).to be nil
end
it "sets superclass of Object to BasicObject" do
o = ClassObject.new(:root, :Object)
expect(o.superclass).to eq P(:BasicObject)
end
it "raises ArgumentError if superclass == self" do
expect do
ClassObject.new(:root, :Object) do |o|
o.superclass = :Object
end
end.to raise_error(ArgumentError)
end
it "tells the world if it is an exception class" do
o = ClassObject.new(:root, :MyClass)
o2 = ClassObject.new(:root, :OtherClass)
o2.superclass = :SystemCallError
o3 = ClassObject.new(:root, :StandardError)
o3.superclass = :Object
ClassObject.new(:root, :Object)
o.superclass = :Object
expect(o.is_exception?).to be false
o.superclass = :Exception
expect(o.is_exception?).to be true
o.superclass = :NoMethodError
expect(o.is_exception?).to be true
o.superclass = o2
expect(o.is_exception?).to be true
o.superclass = o3
expect(o.is_exception?).to be true
end
it "does not raise ArgumentError if superclass is proxy in different namespace" do
expect do
ClassObject.new(:root, :X) do |o|
o.superclass = P('OTHER::X')
end
end.not_to raise_error
end
end
end
yard-0.9.7/spec/code_objects/spec_helper.rb 0000644 0000041 0000041 00000000063 13035234564 020715 0 ustar www-data www-data # frozen_string_literal: true
include CodeObjects
yard-0.9.7/spec/code_objects/constants_spec.rb 0000644 0000041 0000041 00000006355 13035234564 021464 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects do
describe :CONSTANTMATCH do
it "matches a constant" do
expect("Constant"[CodeObjects::CONSTANTMATCH]).to eq "Constant"
expect("identifier"[CodeObjects::CONSTANTMATCH]).to be nil
expect("File.new"[CodeObjects::CONSTANTMATCH]).to eq "File"
end
end
describe :CONSTANTSTART do
it "matches a constant" do
expect("Constant"[CodeObjects::CONSTANTSTART]).to eq "C"
expect("identifier"[CodeObjects::CONSTANTSTART]).to be nil
expect("File.new"[CodeObjects::CONSTANTSTART]).to eq "F"
end
end
describe :NAMESPACEMATCH do
it "matches a namespace (multiple constants with ::)" do
expect("Constant"[CodeObjects::NAMESPACEMATCH]).to eq "Constant"
expect("A::B::C.new"[CodeObjects::NAMESPACEMATCH]).to eq "A::B::C"
end
end
describe :METHODNAMEMATCH do
it "matches a method name" do
expect("method"[CodeObjects::METHODNAMEMATCH]).to eq "method"
expect("[]()"[CodeObjects::METHODNAMEMATCH]).to eq "[]"
expect("-@"[CodeObjects::METHODNAMEMATCH]).to eq "-@"
expect("method?"[CodeObjects::METHODNAMEMATCH]).to eq "method?"
expect("method!!"[CodeObjects::METHODNAMEMATCH]).to eq "method!"
end
end
describe :METHODMATCH do
it "matches a full class method path" do
expect("method"[CodeObjects::METHODMATCH]).to eq "method"
expect("A::B::C.method?"[CodeObjects::METHODMATCH]).to eq "A::B::C.method?"
expect("A::B::C :: method"[CodeObjects::METHODMATCH]).to eq "A::B::C :: method"
expect("SomeClass . method"[CodeObjects::METHODMATCH]).to eq "SomeClass . method"
end
it "matches self.method" do
expect("self :: method!"[CodeObjects::METHODMATCH]).to eq "self :: method!"
expect("self.is_a?"[CodeObjects::METHODMATCH]).to eq "self.is_a?"
end
end
describe :BUILTIN_EXCEPTIONS do
it "includes all base exceptions" do
bad_names = []
YARD::CodeObjects::BUILTIN_EXCEPTIONS.each do |name|
begin
bad_names << name unless eval(name) <= Exception
rescue NameError
nil # noop
end
end
expect(bad_names).to be_empty
end
end
describe :BUILTIN_CLASSES do
it "includes all base classes" do
bad_names = []
YARD::CodeObjects::BUILTIN_CLASSES.each do |name|
begin
bad_names << name unless eval(name).is_a?(Class)
rescue NameError
nil # noop
end
end
expect(bad_names).to be_empty
end
it "includes all exceptions" do
YARD::CodeObjects::BUILTIN_EXCEPTIONS.each do |name|
expect(YARD::CodeObjects::BUILTIN_CLASSES).to include(name)
end
end
end
describe :BUILTIN_ALL do
it "includes classes, modules, and exceptions" do
a = YARD::CodeObjects::BUILTIN_ALL
b = YARD::CodeObjects::BUILTIN_CLASSES
c = YARD::CodeObjects::BUILTIN_MODULES
expect(a).to eq b + c
end
end
describe :BUILTIN_MODULES do
it "includes all base modules" do
YARD::CodeObjects::BUILTIN_MODULES.each do |name|
next if YARD.ruby19? && ["Precision"].include?(name)
expect(eval(name)).to be_instance_of(Module)
end
end
end
end
yard-0.9.7/spec/code_objects/module_object_spec.rb 0000644 0000041 0000041 00000011347 13035234564 022260 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::ModuleObject do
describe "#meths" do
before do
Registry.clear
# setup the object space:
#
# YARD:module
# YARD#foo:method
# YARD#foo2:method
# YARD#xyz:method
# YARD.bar:method
# SomeMod#mixmethod
# SomeMod#xyz:method
#
@yard = ModuleObject.new(:root, :YARD)
MethodObject.new(@yard, :foo)
MethodObject.new(@yard, :xyz)
MethodObject.new(@yard, :foo2) do |o|
o.visibility = :protected
end
MethodObject.new(@yard, :bar, :class) do |o|
o.visibility = :private
end
@other = ModuleObject.new(:root, :SomeMod)
MethodObject.new(@other, :mixmethod)
MethodObject.new(@other, :xyz)
MethodObject.new(@other, :baz, :class)
@another = ModuleObject.new(:root, :AnotherMod)
MethodObject.new(@another, :fizz)
MethodObject.new(@another, :bar)
MethodObject.new(@another, :fazz, :class)
@yard.instance_mixins << @other
@yard.class_mixins << @another
end
it "lists all methods (including mixin methods) via #meths" do
meths = @yard.meths
expect(meths).to include(P("YARD#foo"))
expect(meths).to include(P("YARD#foo2"))
expect(meths).to include(P("YARD.bar"))
expect(meths).to include(P("SomeMod#mixmethod"))
expect(meths).to include(P("AnotherMod#fizz"))
end
it "allows :visibility to be set" do
meths = @yard.meths(:visibility => :public)
expect(meths).not_to include(P("YARD.bar"))
meths = @yard.meths(:visibility => [:public, :private])
expect(meths).to include(P("YARD#foo"))
expect(meths).to include(P("YARD.bar"))
expect(meths).not_to include(P("YARD#foo2"))
end
it "only displays class methods for :scope => :class" do
meths = @yard.meths(:scope => :class)
expect(meths).not_to include(P("YARD#foo"))
expect(meths).not_to include(P("YARD#foo2"))
expect(meths).not_to include(P("SomeMod#mixmethod"))
expect(meths).not_to include(P("SomeMod.baz"))
expect(meths).not_to include(P("AnotherMod#fazz"))
expect(meths).to include(P("YARD.bar"))
expect(meths).to include(P("AnotherMod#fizz"))
end
it "only displays instance methods for :scope => :class" do
meths = @yard.meths(:scope => :instance)
expect(meths).to include(P("YARD#foo"))
expect(meths).to include(P("YARD#foo2"))
expect(meths).to include(P("SomeMod#mixmethod"))
expect(meths).not_to include(P("YARD.bar"))
expect(meths).not_to include(P("AnotherMod#fizz"))
end
it "allows :included to be set" do
meths = @yard.meths(:included => false)
expect(meths).not_to include(P("SomeMod#mixmethod"))
expect(meths).not_to include(P("AnotherMod#fizz"))
expect(meths).to include(P("YARD#foo"))
expect(meths).to include(P("YARD#foo2"))
expect(meths).to include(P("YARD.bar"))
end
it "chooses the method defined in the class over an included module" do
meths = @yard.meths
expect(meths).not_to include(P("SomeMod#xyz"))
expect(meths).to include(P("YARD#xyz"))
expect(meths).not_to include(P("AnotherMod#bar"))
expect(meths).to include(P("YARD.bar"))
meths = @other.meths
expect(meths).to include(P("SomeMod#xyz"))
meths = @another.meths
expect(meths).to include(P("AnotherMod#bar"))
end
end
describe "#inheritance_tree" do
before do
Registry.clear
@mod1 = ModuleObject.new(:root, :Mod1)
@mod2 = ModuleObject.new(:root, :Mod2)
@mod3 = ModuleObject.new(:root, :Mod3)
@mod4 = ModuleObject.new(:root, :Mod4)
@mod5 = ModuleObject.new(:root, :Mod5)
@mod1.instance_mixins << @mod2
@mod2.instance_mixins << @mod3
@mod3.instance_mixins << @mod4
@mod1.instance_mixins << @mod4
@proxy = P(:SomeProxyClass)
@mod5.instance_mixins << @proxy
end
it "shows only itself for an inheritance tree without included modules" do
expect(@mod1.inheritance_tree).to eq [@mod1]
end
it "shows proper inheritance tree when modules are included" do
expect(@mod1.inheritance_tree(true)).to eq [@mod1, @mod2, @mod3, @mod4]
end
it "does not list inheritance tree of proxy objects in inheritance tree" do
expect(@proxy).not_to receive(:inheritance_tree)
expect(@mod5.instance_mixins).to eq [@proxy]
end
it "lists class mixins in inheritance tree" do
mod = ModuleObject.new(:root, :ClassMethods)
recvmod = ModuleObject.new(:root, :ReceivingModule)
recvmod.class_mixins << mod
expect(recvmod.inheritance_tree(true)).to eq [recvmod, mod]
end
end
end
yard-0.9.7/spec/code_objects/method_object_spec.rb 0000644 0000041 0000041 00000013572 13035234564 022255 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::MethodObject do
before do
Registry.clear
@yard = ModuleObject.new(:root, :YARD)
end
context "for an instance method in the root" do
it "has a path of testing" do
meth = MethodObject.new(:root, :testing)
expect(meth.path).to eq "#testing"
end
end
context "for an instance method in YARD" do
it "has a path of YARD#testing" do
meth = MethodObject.new(@yard, :testing)
expect(meth.path).to eq "YARD#testing"
end
end
context "for a class method in YARD" do
it "has a path of YARD.testing" do
meth = MethodObject.new(@yard, :testing, :class)
expect(meth.path).to eq "YARD.testing"
end
end
context "for a class method added to root namespace" do
it "has a path of ::testing (note the ::)" do
meth = MethodObject.new(:root, :testing, :class)
expect(meth.path).to eq "::testing"
end
end
it "exists in the registry after successful creation" do
MethodObject.new(@yard, :something, :class)
expect(Registry.at("YARD.something")).not_to be nil
expect(Registry.at("YARD#something")).to be nil
expect(Registry.at("YARD::something")).to be nil
MethodObject.new(@yard, :somethingelse)
expect(Registry.at("YARD#somethingelse")).not_to be nil
end
it "allows #scope to be changed after creation" do
obj = MethodObject.new(@yard, :something, :class)
expect(Registry.at("YARD.something")).not_to be nil
obj.scope = :instance
expect(Registry.at("YARD.something")).to be nil
expect(Registry.at("YARD#something")).not_to be nil
end
it "creates object in :class scope if scope is :module" do
obj = MethodObject.new(@yard, :module_func, :module)
expect(obj.scope).to eq :class
expect(obj.visibility).to eq :public
expect(Registry.at('YARD.module_func')).not_to be nil
end
it "creates second private instance method if scope is :module" do
MethodObject.new(@yard, :module_func, :module)
obj = Registry.at('YARD#module_func')
expect(obj).not_to be nil
expect(obj.visibility).to eq :private
expect(obj.scope).to eq :instance
end
it "yields block to second method if scope is :module" do
MethodObject.new(@yard, :module_func, :module) do |o|
o.docstring = 'foo'
end
expect(Registry.at('YARD.module_func').docstring).to eq 'foo'
expect(Registry.at('YARD#module_func').docstring).to eq 'foo'
end
describe "#name" do
it "shows a prefix for an instance method when prefix=true" do
obj = MethodObject.new(nil, :something)
expect(obj.name(true)).to eq "#something"
end
it "never shows a prefix for a class method" do
obj = MethodObject.new(nil, :something, :class)
expect(obj.name).to eq :something
expect(obj.name(true)).to eq "something"
end
end
describe "#is_attribute?" do
it "only returns true if attribute is set in namespace for read/write" do
obj = MethodObject.new(@yard, :foo)
@yard.attributes[:instance][:foo] = {:read => obj, :write => nil}
expect(obj.is_attribute?).to be true
expect(MethodObject.new(@yard, :foo=).is_attribute?).to be false
end
end
describe "#attr_info" do
it "returns attribute info if namespace is available" do
obj = MethodObject.new(@yard, :foo)
@yard.attributes[:instance][:foo] = {:read => obj, :write => nil}
expect(obj.attr_info).to eq @yard.attributes[:instance][:foo]
end
it "returns nil if namespace is proxy" do
MethodObject.new(P(:ProxyClass), :foo)
expect(MethodObject.new(@yard, :foo).attr_info).to eq nil
end
it "returns nil if meth is not an attribute" do
expect(MethodObject.new(@yard, :notanattribute).attr_info).to eq nil
end
end
describe "#writer?" do
it "returns true if method is a writer attribute" do
obj = MethodObject.new(@yard, :foo=)
@yard.attributes[:instance][:foo] = {:read => nil, :write => obj}
expect(obj.writer?).to be true
expect(MethodObject.new(@yard, :NOTfoo=).writer?).to be false
end
end
describe "#reader?" do
it "returns true if method is a reader attribute" do
obj = MethodObject.new(@yard, :foo)
@yard.attributes[:instance][:foo] = {:read => obj, :write => nil}
expect(obj.reader?).to be true
expect(MethodObject.new(@yard, :NOTfoo).reader?).to be false
end
end
describe "#constructor?" do
before { @class = ClassObject.new(:root, :MyClass) }
it "marks the #initialize method as constructor" do
MethodObject.new(@class, :initialize)
end
it "does not mark Klass.initialize as constructor" do
expect(MethodObject.new(@class, :initialize, :class).constructor?).to be false
end
it "does not mark module method #initialize as constructor" do
expect(MethodObject.new(@yard, :initialize).constructor?).to be false
end
end
describe "#overridden_method" do
before { Registry.clear }
it "returns overridden method from mixin first" do
YARD.parse_string(<<-eof)
module C; def foo; end end
class A; def foo; end end
class B < A; include C; def foo; end end
eof
expect(Registry.at('B#foo').overridden_method).to eq Registry.at('C#foo')
end
it "returns overridden method from superclass" do
YARD.parse_string(<<-eof)
class A; def foo; end end
class B < A; def foo; end end
eof
expect(Registry.at('B#foo').overridden_method).to eq Registry.at('A#foo')
end
it "returns nil if none is found" do
YARD.parse_string(<<-eof)
class A; end
class B < A; def foo; end end
eof
expect(Registry.at('B#foo').overridden_method).to be nil
end
it "returns nil if namespace is a proxy" do
YARD.parse_string "def ARGV.foo; end"
expect(Registry.at('ARGV.foo').overridden_method).to be nil
end
end
end
yard-0.9.7/spec/code_objects/code_object_list_spec.rb 0000644 0000041 0000041 00000001630 13035234564 022732 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::CodeObjectList do
before { Registry.clear }
describe "#push" do
it "only allows CodeObjects::Base, String or Symbol" do
list = CodeObjectList.new(nil)
expect { list.push(:hash => 1) }.to raise_error(ArgumentError)
list << "Test"
list << :Test2
list << ModuleObject.new(nil, :YARD)
expect(list.size).to eq 3
end
end
it "added value should be a proxy if parameter was String or Symbol" do
list = CodeObjectList.new(nil)
list << "Test"
expect(list.first.class).to eq Proxy
end
it "contains a unique list of objects" do
obj = ModuleObject.new(nil, :YARD)
list = CodeObjectList.new(nil)
list << P(:YARD)
list << obj
expect(list.size).to eq 1
list << :Test
list << "Test"
expect(list.size).to eq 2
end
end
yard-0.9.7/spec/code_objects/base_spec.rb 0000644 0000041 0000041 00000036153 13035234564 020361 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::Base do
before { Registry.clear }
it "does not allow empty object name" do
expect { Base.new(:root, '') }.to raise_error(ArgumentError)
end
it "returns a unique instance of any registered object" do
obj = ClassObject.new(:root, :Me)
obj2 = ClassObject.new(:root, :Me)
expect(obj.object_id).to eq obj2.object_id
obj3 = ModuleObject.new(obj, :Too)
obj4 = CodeObjects::Base.new(obj3, :Hello)
obj4.parent = obj
obj5 = CodeObjects::Base.new(obj3, :hello)
expect(obj4.object_id).not_to eq obj5.object_id
end
it "creates a new object if cached object is not of the same class" do
expect(ConstantObject.new(:root, "MYMODULE")).to be_instance_of(ConstantObject)
expect(ModuleObject.new(:root, "MYMODULE")).to be_instance_of(ModuleObject)
expect(ClassObject.new(:root, "MYMODULE")).to be_instance_of(ClassObject)
expect(YARD::Registry.at("MYMODULE")).to be_instance_of(ClassObject)
end
it "simplifies complex namespace paths" do
obj = ClassObject.new(:root, "A::B::C::D")
expect(obj.name).to eq :D
expect(obj.path).to eq "A::B::C::D"
expect(obj.namespace).to eq P("A::B::C")
end
# @bug gh-552
it "simplifies complex namespace paths when path starts with ::" do
obj = ClassObject.new(:root, "::A::B::C::D")
expect(obj.name).to eq :D
expect(obj.path).to eq "A::B::C::D"
expect(obj.namespace).to eq P("A::B::C")
end
it "calls the block again if #new is called on an existing object" do
o1 = ClassObject.new(:root, :Me) do |o|
o.docstring = "DOCSTRING"
end
o2 = ClassObject.new(:root, :Me) do |o|
o.docstring = "NOT_DOCSTRING"
end
expect(o1.object_id).to eq o2.object_id
expect(o1.docstring).to eq "NOT_DOCSTRING"
expect(o2.docstring).to eq "NOT_DOCSTRING"
end
it "allows complex name and converts it to namespace" do
obj = CodeObjects::Base.new(nil, "A::B")
expect(obj.namespace.path).to eq "A"
expect(obj.name).to eq :B
end
it "allows namespace to be nil and not register in the Registry" do
obj = CodeObjects::Base.new(nil, :Me)
expect(obj.namespace).to eq nil
expect(Registry.at(:Me)).to eq nil
end
it "allows namespace to be a NamespaceObject" do
ns = ModuleObject.new(:root, :Name)
obj = CodeObjects::Base.new(ns, :Me)
expect(obj.namespace).to eq ns
end
it "allows :root to be the shorthand namespace of `Registry.root`" do
obj = CodeObjects::Base.new(:root, :Me)
expect(obj.namespace).to eq Registry.root
end
it "does not allow any other types as namespace" do
expect { CodeObjects::Base.new("ROOT!", :Me) }.to raise_error(ArgumentError)
end
it "registers itself in the registry if namespace is supplied" do
obj = ModuleObject.new(:root, :Me)
expect(Registry.at(:Me)).to eq obj
obj2 = ModuleObject.new(obj, :Too)
expect(Registry.at(:"Me::Too")).to eq obj2
end
describe "#[]=" do
it "sets any attribute" do
obj = ModuleObject.new(:root, :YARD)
obj[:some_attr] = "hello"
expect(obj[:some_attr]).to eq "hello"
end
it "uses the accessor method if available" do
obj = CodeObjects::Base.new(:root, :YARD)
obj[:source] = "hello"
expect(obj.source).to eq "hello"
obj.source = "unhello"
expect(obj[:source]).to eq "unhello"
end
end
it "sets attributes via attr= through method_missing" do
obj = CodeObjects::Base.new(:root, :YARD)
obj.something = 2
expect(obj.something).to eq 2
expect(obj[:something]).to eq 2
end
it "exists in the parent's #children after creation" do
obj = ModuleObject.new(:root, :YARD)
obj2 = MethodObject.new(obj, :testing)
expect(obj.children).to include(obj2)
end
it "properly re-indents source starting from 0 indentation" do
obj = CodeObjects::Base.new(nil, :test)
obj.source = <<-eof
def mymethod
if x == 2 &&
5 == 5
3
else
1
end
end
eof
expect(obj.source).to eq "def mymethod\n if x == 2 &&\n 5 == 5\n 3\n else\n 1\n end\nend"
Registry.clear
Parser::SourceParser.parse_string <<-eof
def key?(key)
super(key)
end
eof
expect(Registry.at('#key?').source).to eq "def key?(key)\n super(key)\nend"
Registry.clear
Parser::SourceParser.parse_string <<-eof
def key?(key)
if x == 2
puts key
else
exit
end
end
eof
expect(Registry.at('#key?').source).to eq "def key?(key)\n if x == 2\n puts key\n else\n exit\n end\nend"
end
it "does not add newlines to source when parsing sub blocks" do
Parser::SourceParser.parse_string <<-eof
module XYZ
module ZYX
class ABC
def msg
hello_world
end
end
end
end
eof
expect(Registry.at('XYZ::ZYX::ABC#msg').source).to eq "def msg\n hello_world\nend"
end
it "handles source for 'def x; end'" do
Registry.clear
Parser::SourceParser.parse_string "def x; 2 end"
expect(Registry.at('#x').source).to eq "def x; 2 end"
end
it "sets file and line information" do
Parser::SourceParser.parse_string <<-eof
class X; end
eof
expect(Registry.at(:X).file).to eq '(stdin)'
expect(Registry.at(:X).line).to eq 1
end
it "maintains all file associations when objects are defined multiple times in one file" do
Parser::SourceParser.parse_string <<-eof
class X; end
class X; end
class X; end
eof
expect(Registry.at(:X).file).to eq '(stdin)'
expect(Registry.at(:X).line).to eq 1
expect(Registry.at(:X).files).to eq [['(stdin)', 1], ['(stdin)', 2], ['(stdin)', 3]]
end
it "maintains all file associations when objects are defined multiple times in multiple files" do
3.times do |i|
allow(File).to receive(:read_binary).and_return("class X; end")
Parser::SourceParser.new.parse("file#{i + 1}.rb")
end
expect(Registry.at(:X).file).to eq 'file1.rb'
expect(Registry.at(:X).line).to eq 1
expect(Registry.at(:X).files).to eq [['file1.rb', 1], ['file2.rb', 1], ['file3.rb', 1]]
end
it "prioritizes the definition with a docstring when returning #file" do
Parser::SourceParser.parse_string <<-eof
class X; end
class X; end
# docstring
class X; end
eof
expect(Registry.at(:X).file).to eq '(stdin)'
expect(Registry.at(:X).line).to eq 4
expect(Registry.at(:X).files).to eq [['(stdin)', 4], ['(stdin)', 1], ['(stdin)', 2]]
end
describe "#format" do
it "sends object to Templates.render" do
object = MethodObject.new(:root, :method)
expect(Templates::Engine).to receive(:render).with(:x => 1, :object => object, :type => object.type)
object.format :x => 1
end
it "does not change options object class" do
opts = YARD::Templates::TemplateOptions.new
opts.type = "test"
object = MethodObject.new(:root, :method)
expect(Templates::Engine).to receive(:render).with kind_of(YARD::Templates::TemplateOptions)
object.format(opts)
end
end
describe "#source_type" do
it "defaults to :ruby" do
object = MethodObject.new(:root, :method)
expect(object.source_type).to eq :ruby
end
end
describe "#relative_path" do
it "accepts a string" do
YARD.parse_string "module A; class B; end; class C; end; end"
expect(Registry.at('A::B').relative_path(Registry.at('A::C'))).to eq(
Registry.at('A::B').relative_path('A::C')
)
end
it "returns full class name when objects share a common class prefix" do
YARD.parse_string "module User; end; module UserManager; end"
expect(Registry.at('User').relative_path('UserManager')).to eq 'UserManager'
expect(Registry.at('User').relative_path(Registry.at('UserManager'))).to eq 'UserManager'
end
it "returns the relative path when they share a common namespace" do
YARD.parse_string "module A; class B; end; class C; end; end"
expect(Registry.at('A::B').relative_path(Registry.at('A::C'))).to eq 'C'
YARD.parse_string "module Foo; module A; end; module B; def foo; end end end"
expect(Registry.at('Foo::A').relative_path(Registry.at('Foo::B#foo'))).to eq 'B#foo'
end
it "returns the full path if they don't have a common namespace" do
YARD.parse_string "module A; class B; end; end; module D; class C; end; end"
expect(Registry.at('A::B').relative_path('D::C')).to eq 'D::C'
YARD.parse_string 'module C::B::C; module Apple; end; module Ant; end end'
expect(Registry.at('C::B::C::Apple').relative_path('C::B::C::Ant')).to eq 'Ant'
YARD.parse_string 'module OMG::ABC; end; class Object; end'
expect(Registry.at('OMG::ABC').relative_path('Object')).to eq "Object"
YARD.parse_string("class YARD::Config; MYCONST = 1; end")
expect(Registry.at('YARD::Config').relative_path('YARD::Config::MYCONST')).to eq "MYCONST"
end
it "returns a relative path for class methods" do
YARD.parse_string "module A; def self.b; end; def self.c; end; end"
expect(Registry.at('A.b').relative_path('A.c')).to eq 'c'
expect(Registry.at('A').relative_path('A.c')).to eq 'c'
end
it "returns a relative path for instance methods" do
YARD.parse_string "module A; def b; end; def c; end; end"
expect(Registry.at('A#b').relative_path('A#c')).to eq '#c'
expect(Registry.at('A').relative_path('A#c')).to eq '#c'
end
it "returns full path if relative path is to parent namespace" do
YARD.parse_string "module A; module B; end end"
expect(Registry.at('A::B').relative_path('A')).to eq 'A'
end
it "only returns name for relative path to self" do
YARD.parse_string("class A::B::C; def foo; end end")
expect(Registry.at('A::B::C').relative_path('A::B::C')).to eq 'C'
expect(Registry.at('A::B::C#foo').relative_path('A::B::C#foo')).to eq '#foo'
end
end
describe "#docstring=" do
it "converts string into Docstring when #docstring= is set" do
o = ClassObject.new(:root, :Me)
o.docstring = "DOCSTRING"
expect(o.docstring).to be_instance_of(Docstring)
end
it "sets docstring to docstring of other object if docstring is '(see Path)'" do
ClassObject.new(:root, :AnotherObject) {|x| x.docstring = "FOO" }
o = ClassObject.new(:root, :Me)
o.docstring = '(see AnotherObject)'
expect(o.docstring).to eq "FOO"
end
it "does not copy docstring mid-docstring" do
doc = "Hello.\n(see file.rb)\nmore documentation"
o = ClassObject.new(:root, :Me)
o.docstring = doc
expect(o.docstring).to eq doc
end
it "allows extra docstring after (see Path)" do
ClassObject.new(:root, :AnotherObject) {|x| x.docstring = "FOO" }
o = ClassObject.new(:root, :Me)
o.docstring = Docstring.new("(see AnotherObject)\n\nEXTRA\n@api private", o)
expect(o.docstring).to eq "FOO\n\nEXTRA"
expect(o.docstring).to have_tag(:api)
end
end
describe "#docstring" do
it "returns an empty string if docstring was '(see Path)' and Path is not resolved" do
o = ClassObject.new(:root, :Me)
o.docstring = '(see AnotherObject)'
expect(o.docstring).to eq ""
end
it "returns docstring when object is resolved" do
o = ClassObject.new(:root, :Me)
o.docstring = '(see AnotherObject)'
expect(o.docstring).to eq ""
ClassObject.new(:root, :AnotherObject) {|x| x.docstring = "FOO" }
expect(o.docstring).to eq "FOO"
end
describe "localization" do
it "returns localized docstring" do
fr_locale = YARD::I18n::Locale.new('fr')
allow(fr_locale).to receive(:translate).with('Hello').and_return('Bonjour')
o = ClassObject.new(:root, :Me)
o.docstring = 'Hello'
expect(o.docstring).to eq 'Hello'
allow(Registry).to receive(:locale).with('fr').and_return(fr_locale)
expect(o.docstring('fr')).to eq "Bonjour"
end
it "returns updated localized docstring" do
fr_locale = YARD::I18n::Locale.new('fr')
allow(Registry).to receive(:locale).with('fr').and_return(fr_locale)
o = ClassObject.new(:root, :Me)
o.docstring = 'Hello'
expect(o.docstring).to eq 'Hello'
allow(fr_locale).to receive(:translate).with('Hello').and_return('Bonjour')
expect(o.docstring('fr')).to eq "Bonjour"
o.docstring = 'World'
allow(fr_locale).to receive(:translate).with('World').and_return('Monde')
expect(o.docstring('fr')).to eq "Monde"
expect(o.docstring).to eq 'World'
end
end
end
describe "#add_file" do
it "only adds a file/line combination once" do
o = ClassObject.new(:root, :Me)
o.add_file('filename', 12)
expect(o.files).to eq [['filename', 12]]
o.add_file('filename', 12)
expect(o.files).to eq [['filename', 12]]
o.add_file('filename', 40) # different line
expect(o.files).to eq [['filename', 12], ['filename', 40]]
end
end
describe "#copy_to" do
it "copies all data to new object" do
YARD.parse_string <<-eof
private
# A docstring
# @return [String] a tag
def foo(a, b, c)
source_code_here
end
eof
foo_c = MethodObject.new(:root, :foo, :class)
Registry.at('#foo').copy_to(foo_c)
expect(foo_c.scope).to eq :class
expect(foo_c.visibility).to eq :private
expect(foo_c.type).to eq :method
expect(foo_c.class).to eq MethodObject
expect(foo_c.path).to eq '::foo'
expect(foo_c.docstring).to eq "A docstring"
expect(foo_c.tag(:return).types).to eq ['String']
expect(foo_c.file).to eq '(stdin)'
expect(foo_c.line).to eq 4
expect(foo_c.source).to match(/source_code_here/)
expect(foo_c.signature).to eq 'def foo(a, b, c)'
expect(foo_c.parameters).to eq [['a', nil], ['b', nil], ['c', nil]]
end
it "returns the copied object" do
YARD.parse_string 'def foo; end'
foo_c = MethodObject.new(:root, :foo, :class)
expect(Registry.at('#foo').copy_to(foo_c)).to eq foo_c
end
it "copies docstring and rewrite tags to new object" do
YARD.parse_string <<-eof
# @return [String] a tag
def foo; end
eof
foo_c = MethodObject.new(:root, :foo, :class)
foo_i = Registry.at('#foo')
foo_i.copy_to(foo_c)
expect(foo_i.tags).not_to eq foo_c.tags
expect(foo_c.tags.first.object).to eq foo_c
end
it "only copies #copyable_attributes" do
foo = MethodObject.new(:root, :foo)
expect(foo).to receive(:copyable_attributes).and_return %w(a b c)
expect(foo).to receive(:instance_variable_get).with('@a').and_return(1)
expect(foo).to receive(:instance_variable_get).with('@b').and_return(2)
expect(foo).to receive(:instance_variable_get).with('@c').and_return(3)
bar = MethodObject.new(:root, :bar)
expect(bar).to receive(:instance_variable_set).with('@a', 1)
expect(bar).to receive(:instance_variable_set).with('@b', 2)
expect(bar).to receive(:instance_variable_set).with('@c', 3)
foo.copy_to(bar)
end
end
end
yard-0.9.7/spec/code_objects/macro_object_spec.rb 0000644 0000041 0000041 00000010252 13035234564 022066 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::MacroObject do
before do
Registry.clear
end
describe ".create" do
def create(*args) MacroObject.create(*args) end
it "creates an object" do
create('foo', '')
obj = Registry.at('.macro.foo')
expect(obj).not_to be nil
end
it "uses identity map" do
obj1 = create('foo', '')
obj2 = create('foo', '')
expect(obj1.object_id).to eq obj2.object_id
end
it "allows specifying of macro data" do
obj = create('foo', 'MACRODATA')
expect(obj.macro_data).to eq 'MACRODATA'
end
context "if a method object is provided" do
it "attaches it" do
obj = create('foo', 'MACRODATA', P('Foo.property'))
expect(obj.method_object).to eq P('Foo.property')
expect(obj).to be_attached
end
end
end
describe ".find" do
before { MacroObject.create('foo', 'DATA') }
it "searches for an object by name" do
expect(MacroObject.find('foo').macro_data).to eq 'DATA'
end
it "accepts Symbol" do
expect(MacroObject.find(:foo).macro_data).to eq 'DATA'
end
end
describe ".find_or_create" do
it "looks up name if @!macro is present and find object" do
macro1 = MacroObject.create('foo', 'FOO')
macro2 = MacroObject.find_or_create('foo', "a b c")
expect(macro1).to eq macro2
end
it "creates new macro if macro by that name does not exist" do
MacroObject.find_or_create('foo', "@!method $1")
expect(MacroObject.find('foo').macro_data).to eq "@!method $1"
end
end
describe ".apply" do
let(:args) { %w(foo a b c) }
def apply(comments)
MacroObject.apply(comments, args)
end
it "only expands macros if @macro is present" do
expect(apply("$1$2$3")).to eq "$1$2$3"
end
it "handles macro text inside block" do
expect(apply("@!macro\n foo$1$2$3\nfoobaz")).to eq "fooabc\nfoobaz"
end
it "appends docstring to existing macro" do
MacroObject.create('name', '$3$2$1')
result = MacroObject.apply("@!macro name\nfoobar", args)
expect(result).to eq "cba\nfoobar"
end
it "uses only non-macro data if docstring is an existing macro" do
data = "@!macro name\n $3$2$1\nEXTRA"
result = MacroObject.apply(data, args, 'SOURCE')
expect(result).to eq "cba\nEXTRA"
expect(MacroObject.apply("@!macro name\nFOO", args)).to eq "cba\nFOO"
end
it "creates macros if they don't exist" do
result = MacroObject.apply("@!macro name\n foo!$1", args, 'SOURCE')
expect(result).to eq "foo!a"
expect(MacroObject.find('name').macro_data).to eq 'foo!$1'
end
it "keeps other tags" do
expect(apply("@!macro\n foo$1$2$3\n@param name foo\nfoo")).to eq(
"fooabc\nfoo\n@param name\n foo"
)
end
end
describe ".expand" do
def expand(comments)
args = %w(foo a b c)
full_line = 'foo :bar, :baz'
MacroObject.expand(comments, args, full_line)
end
it "allows escaping of macro syntax" do
expect(expand("$1\\$2$3")).to eq "a$2c"
end
it "replaces $* with the whole statement" do
expect(expand("$* ${*}")).to eq "foo :bar, :baz foo :bar, :baz"
end
it "replaces $0 with method name" do
expect(expand("$0 ${0}")).to eq "foo foo"
end
it "replaces all $N values with the Nth argument in the method call" do
expect(expand("$1$2$3${3}\nfoobar")).to eq "abcc\nfoobar"
end
it "replaces ${N-M} ranges with N-M arguments (incl. commas)" do
expect(expand("${1-2}x")).to eq "a, bx"
end
it "handles open ended ranges (${N-})" do
expect(expand("${2-}")).to eq "b, c"
end
it "handles negative indexes ($-N)" do
expect(expand("$-1 ${-2-} ${-2--2}")).to eq "c b, c b"
end
it "accepts Docstring objects" do
expect(expand(Docstring.new("$1\n@param name foo"))).to eq "a\n@param name foo"
end
end
describe "#expand" do
it "expands a macro given its data" do
macro = MacroObject.create_docstring('foo', '$1 $2 THREE!')
expect(macro.expand(['NAME', 'ONE', 'TWO'])).to eq "ONE TWO THREE!"
end
end
end
yard-0.9.7/spec/code_objects/namespace_object_spec.rb 0000644 0000041 0000041 00000012726 13035234564 022731 0 ustar www-data www-data # frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
RSpec.describe YARD::CodeObjects::NamespaceObject do
before { Registry.clear }
describe "#child" do
it "returns the object matching the name passed in if argument is a Symbol" do
obj = NamespaceObject.new(nil, :YARD)
other = NamespaceObject.new(obj, :Other)
expect(obj.child(:Other)).to eq other
expect(obj.child('Other')).to eq other
end
it "looks for attributes matching the object if the argument is a Hash" do
obj = NamespaceObject.new(nil, :YARD)
NamespaceObject.new(obj, :NotOther)
other = NamespaceObject.new(obj, :Other)
other.somevalue = 2
expect(obj.child(:somevalue => 2)).to eq other
end
end
describe "#meths" do
it "returns #meths even if parent is a Proxy" do
obj = NamespaceObject.new(P(:String), :YARD)
expect(obj.meths).to be_empty
end
it "does not list included methods that are already defined in the namespace using #meths" do
a = ModuleObject.new(nil, :Mod1)
ameth = MethodObject.new(a, :testing)
b = ModuleObject.new(nil, :Mod2)
bmeth = MethodObject.new(b, :foo)
c = NamespaceObject.new(nil, :YARD)
cmeth = MethodObject.new(c, :testing)
cmeth2 = MethodObject.new(c, :foo)
c.instance_mixins << a
c.class_mixins << b
meths = c.meths
expect(meths).to include(bmeth)
expect(meths).to include(cmeth)
expect(meths).to include(cmeth2)
expect(meths).not_to include(ameth)
meths = c.included_meths
expect(meths).to include(bmeth)
expect(meths).not_to include(ameth)
expect(meths).not_to include(cmeth)
expect(meths).not_to include(cmeth2)
end
end
describe "#included_meths" do
it "lists methods mixed into the class scope as class methods" do
b = ModuleObject.new(nil, :Mod2)
bmeth = MethodObject.new(b, :foo)
bmeth2 = MethodObject.new(b, :foo2)
c = NamespaceObject.new(nil, :YARD)
c.class_mixins << b
[bmeth, bmeth2].each {|o| expect(o.scope).to eq :instance }
meths = c.included_meths(:scope => :class)
meths.each {|o| expect(o.scope).to eq :class }
end
it "does not list methods overridden by another included module" do
a = ModuleObject.new(nil, :Mod)
ameth = MethodObject.new(a, :testing)
b = ModuleObject.new(nil, :Mod2)
bmeth = MethodObject.new(b, :testing)
c = NamespaceObject.new(nil, :YARD)
c.instance_mixins.unshift a
c.instance_mixins.unshift b
c.class_mixins.unshift b
c.class_mixins.unshift a
meths = c.included_meths(:scope => :instance)
expect(meths).not_to include(ameth)
expect(meths).to include(bmeth)
meths = c.included_meths(:scope => :class)
expect(meths).to include(ameth)
expect(meths).not_to include(bmeth)
end
end
describe "#class_attributes" do
it "lists class attributes" do
a = NamespaceObject.new(nil, :Mod)
a.attributes[:instance][:a] = {:read => MethodObject.new(a, :a), :write => nil}
a.attributes[:instance][:b] = {:read => MethodObject.new(a, :b), :write => nil}
a.attributes[:class][:a] = {:read => MethodObject.new(a, :a, :class), :write => nil}
expect(a.class_attributes.keys).to include(:a)
expect(a.class_attributes.keys).not_to include(:b)
end
end
describe "#instance_attributes" do
it "lists instance attributes" do
a = NamespaceObject.new(nil, :Mod)
a.attributes[:instance][:a] = {:read => MethodObject.new(a, :a), :write => nil}
a.attributes[:instance][:b] = {:read => MethodObject.new(a, :b), :write => nil}
a.attributes[:class][:a] = {:read => MethodObject.new(a, :a, :class), :write => nil}
expect(a.instance_attributes.keys).to include(:a)
expect(a.instance_attributes.keys).to include(:b)
end
end
describe "#constants/#included_constants" do
before do
Registry.clear
YARD.parse_string <<-eof
module A
CONST1 = 1
CONST2 = 2
end
module B
CONST2 = -2
CONST3 = -3
end
class C
CONST3 = 3
CONST4 = 4
include A
include B
end
eof
end
it "lists all included constants by default" do
consts = P(:C).constants
expect(consts).to include(P('A::CONST1'))
expect(consts).to include(P('C::CONST4'))
end
it "allows :included to be set to false to ignore included constants" do
consts = P(:C).constants(:included => false)
expect(consts).not_to include(P('A::CONST1'))
expect(consts).to include(P('C::CONST4'))
end
it "does not list an included constant if it is defined in the object" do
consts = P(:C).constants
expect(consts).to include(P('C::CONST3'))
expect(consts).not_to include(P('B::CONST3'))
end
it "does not list an included constant if it is shadowed by another included constant" do
consts = P(:C).included_constants
expect(consts).to include(P('B::CONST2'))
expect(consts).not_to include(P('A::CONST2'))
end
end
describe "#included_meths" do
it "returns all included methods with :all = true" do
YARD.parse_string <<-eof
module B; def foo; end end
module C; def bar; end end
class A; include B; include C; def foo; end; def bar; end end
eof
expect(Registry.at('A').included_meths(:all => true)).to eq [P('C#bar'), P('B#foo')]
end
end
end
yard-0.9.7/spec/registry_store_spec.rb 0000644 0000041 0000041 00000030551 13035234564 020104 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::RegistryStore do
before do
FileUtils.rm_rf("foo")
@store = RegistryStore.new
@serializer = Serializers::YardocSerializer.new('foo')
@foo = CodeObjects::MethodObject.new(nil, :foo)
@bar = CodeObjects::ClassObject.new(nil, :Bar)
allow(Serializers::YardocSerializer).to receive(:new).and_return(@serializer)
end
describe "#load" do
it "loads root.dat as full object list if it is a Hash" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(@serializer).to receive(:deserialize).with('root').and_return(:root => @foo, :A => @bar)
expect(@store.load('foo')).to be true
expect(@store.root).to eq @foo
expect(@store.get('A')).to eq @bar
end
it "loads old yardoc format if .yardoc is a file" do
expect(File).to receive(:directory?).with('foo').and_return(false)
expect(File).to receive(:file?).with('foo').and_return(true)
expect(File).to receive(:read_binary).with('foo').and_return('FOO')
expect(Marshal).to receive(:load).with('FOO')
@store.load('foo')
end
it "loads new yardoc format if .yardoc is a directory" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
expect(@store.load('foo')).to be true
end
it "returns true if .yardoc is loaded (file)" do
expect(File).to receive(:directory?).with('myyardoc').and_return(false)
expect(File).to receive(:file?).with('myyardoc').and_return(true)
expect(File).to receive(:read_binary).with('myyardoc').and_return(Marshal.dump(''))
expect(@store.load('myyardoc')).to be true
end
it "returns true if .yardoc is loaded (directory)" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
expect(@store.load('foo')).to be true
end
it "returns false if .yardoc does not exist" do
expect(@store.load('NONEXIST')).to be false
end
it "returns false if there is no file to load" do
expect(@store.load(nil)).to be false
end
it "loads checksums if they exist" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(true)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(File).to receive(:readlines).with('foo/checksums').and_return([
'file1 CHECKSUM1', ' file2 CHECKSUM2 '
])
expect(@store.load('foo')).to be true
expect(@store.checksums).to eq('file1' => 'CHECKSUM1', 'file2' => 'CHECKSUM2')
end
it "loads proxy_types if they exist" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(true)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
expect(File).to receive(:read_binary).with('foo/proxy_types').and_return(Marshal.dump('a' => 'b'))
expect(@store.load('foo')).to be true
expect(@store.proxy_types).to eq('a' => 'b')
end
it "loads root object if it exists" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(true)
expect(File).to receive(:read_binary).with('foo/objects/root.dat').and_return(Marshal.dump(@foo))
expect(@store.load('foo')).to be true
expect(@store.root).to eq @foo
end
end
describe "#save" do
before do
allow(@store).to receive(:write_proxy_types)
allow(@store).to receive(:write_checksums)
allow(@store).to receive(:destroy)
end
after do
Registry.single_object_db = nil
end
def saves_to_singledb
expect(@serializer).to receive(:serialize).once.with(instance_of(Hash))
@store.save(true, 'foo')
end
def add_items(n)
n.times {|i| @store[i.to_s] = @foo }
end
def saves_to_multidb
times = @store.keys.size
expect(@serializer).to receive(:serialize).exactly(times).times
@store.save(true, 'foo')
@last = times
end
it "saves as single object db if single_object_db is nil and there are less than 3000 objects" do
Registry.single_object_db = nil
add_items(100)
saves_to_singledb
expect(@serializer.complete?).to eq true
end
it "saves as single object db if single_object_db is nil and there are more than 3000 objects" do
Registry.single_object_db = nil
add_items(5000)
saves_to_singledb
end
it "saves as single object db if single_object_db is true (and any amount of objects)" do
Registry.single_object_db = true
add_items(100)
saves_to_singledb
add_items(5000)
saves_to_singledb
end
it "never saves as single object db if single_object_db is false" do
Registry.single_object_db = false
add_items(100)
saves_to_multidb
add_items(5000)
saves_to_multidb
end
end
describe "#put" do
it "assigns values" do
@store.put(:YARD, @foo)
expect(@store.get(:YARD)).to eq @foo
end
it "treats '' as root" do
@store.put('', @foo)
expect(@store.get(:root)).to eq @foo
end
end
describe "#get" do
it "hits cache if object exists" do
@store.put(:YARD, @foo)
expect(@store.get(:YARD)).to eq @foo
end
it "hits backstore on cache miss and cache is not fully loaded" do
serializer = double(:serializer)
expect(serializer).to receive(:deserialize).once.with(:YARD).and_return(@foo)
@store.load('foo')
@store.instance_variable_set("@loaded_objects", 0)
@store.instance_variable_set("@available_objects", 100)
@store.instance_variable_set("@serializer", serializer)
expect(@store.get(:YARD)).to eq @foo
expect(@store.get(:YARD)).to eq @foo
expect(@store.instance_variable_get("@loaded_objects")).to eq 1
end
end
[:keys, :values].each do |item|
describe "##{item}" do
it "loads entire database if reload=true" do
expect(File).to receive(:directory?).with('foo').and_return(true)
@store.load('foo')
expect(@store).to receive(:load_all)
@store.send(item, true)
end
it "does not load entire database if reload=false" do
expect(File).to receive(:directory?).with('foo').and_return(true)
@store.load('foo')
expect(@store).not_to receive(:load_all)
@store.send(item, false)
end
end
end
describe "#paths_for_type" do
after { Registry.clear }
it "sets all object types if not set by object_types" do
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(@serializer).to receive(:deserialize).with('root').and_return(:'A#foo' => @foo, :A => @bar)
@store.load('foo')
expect(@store.paths_for_type(:method)).to eq ['#foo']
expect(@store.paths_for_type(:class)).to eq ['Bar']
end
it "keeps track of types when assigning values" do
@store.put(:abc, @foo)
expect(@store.paths_for_type(@foo.type)).to eq ['abc']
end
it "reassigns path if type changes" do
foo = CodeObjects::ClassObject.new(:root, :Foo)
@store.put('Foo', foo)
expect(@store.get('Foo').type).to eq :class
expect(@store.paths_for_type(:class)).to eq ["Foo"]
foo = CodeObjects::ModuleObject.new(:root, :Foo)
@store.put('Foo', foo)
expect(@store.get('Foo').type).to eq :module
expect(@store.paths_for_type(:class)).to eq []
expect(@store.paths_for_type(:module)).to eq ["Foo"]
end
end
describe "#values_for_type" do
it "returns all objects with type" do
@store.put(:abc, @foo)
expect(@store.values_for_type(@foo.type)).to eq [@foo]
end
end
describe "#load_all" do
it "loads the entire database" do
foomock = double(:Foo)
barmock = double(:Bar)
allow(foomock).to receive(:type).and_return(:class)
allow(barmock).to receive(:type).and_return(:class)
expect(foomock).to receive(:path).and_return('Foo')
expect(barmock).to receive(:path).and_return('Bar')
expect(File).to receive(:directory?).with('foo').and_return(true)
expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
expect(File).to receive(:file?).with('foo/object_types').and_return(false)
expect(File).to receive(:file?).with('foo/checksums').and_return(false)
expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
expect(@store).to receive(:all_disk_objects).at_least(1).times.and_return(['foo/objects/foo', 'foo/objects/bar'])
@store.load('foo')
serializer = @store.instance_variable_get("@serializer")
expect(serializer).to receive(:deserialize).with('foo/objects/foo', true).and_return(foomock)
expect(serializer).to receive(:deserialize).with('foo/objects/bar', true).and_return(barmock)
@store.send(:load_all)
expect(@store.instance_variable_get("@available_objects")).to eq 2
expect(@store.instance_variable_get("@loaded_objects")).to eq 2
expect(@store[:Foo]).to eq foomock
expect(@store[:Bar]).to eq barmock
end
end
describe "#destroy" do
it "destroys file ending in .yardoc when force=false" do
expect(File).to receive(:file?).with('foo.yardoc').and_return(true)
expect(File).to receive(:unlink).with('foo.yardoc')
@store.instance_variable_set("@file", 'foo.yardoc')
expect(@store.destroy).to be true
end
it "destroys dir ending in .yardoc when force=false" do
expect(File).to receive(:directory?).with('foo.yardoc').and_return(true)
expect(FileUtils).to receive(:rm_rf).with('foo.yardoc')
@store.instance_variable_set("@file", 'foo.yardoc')
expect(@store.destroy).to be true
end
it "does not destroy file/dir not ending in .yardoc when force=false" do
expect(File).not_to receive(:file?).with('foo')
expect(File).not_to receive(:directory?).with('foo')
expect(File).not_to receive(:unlink).with('foo')
expect(FileUtils).not_to receive(:rm_rf).with('foo')
@store.instance_variable_set("@file", 'foo')
expect(@store.destroy).to be false
end
it "destroys any file/dir when force=true" do
expect(File).to receive(:file?).with('foo').and_return(true)
expect(File).to receive(:unlink).with('foo')
@store.instance_variable_set("@file", 'foo')
expect(@store.destroy(true)).to be true
end
end
describe "#locale" do
it "loads ./po/LOCALE_NAME.po" do
fr_locale = I18n::Locale.new("fr")
expect(I18n::Locale).to receive(:new).with("fr").and_return(fr_locale)
expect(Registry).to receive(:po_dir).and_return("po")
expect(fr_locale).to receive(:load).with("po")
expect(@store.locale("fr")).to eq fr_locale
end
end
end
yard-0.9.7/spec/registry_spec.rb 0000644 0000041 0000041 00000042164 13035234564 016673 0 ustar www-data www-data # frozen_string_literal: true
include CodeObjects
require "thread"
RSpec.describe YARD::Registry do
before { Registry.clear }
describe ".yardoc_file_for_gem" do
before do
@gem = double('gem')
allow(@gem).to receive(:name).and_return('foo')
allow(@gem).to receive(:full_name).and_return('foo-1.0')
allow(@gem).to receive(:full_gem_path).and_return('/path/to/foo')
allow(@gem).to receive(:doc_dir).and_return('/path/to/foo/doc')
allow(@gem).to receive(:doc_dir).with('.yardoc').and_return('/path/to/foo/doc/.yardoc')
end
it "returns nil if gem isn't found" do
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([])
expect(Registry.yardoc_file_for_gem('foo')).to eq nil
end
it "allows version to be specified" do
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '= 2').and_return([])
expect(Registry.yardoc_file_for_gem('foo', '= 2')).to eq nil
end
it "returns existing .yardoc path for gem when for_writing=false" do
allow(File).to receive(:exist?).twice.and_return(false)
allow(File).to receive(:exist?).with('/path/to/foo/.yardoc').and_return(true)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo')).to eq '/path/to/foo/.yardoc'
end
it "returns new existing .yardoc path for gem when for_writing=false" do
allow(File).to receive(:exist?).and_return(false)
allow(File).to receive(:exist?).with('/path/to/foo/doc/.yardoc').and_return(true)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo')).to eq '/path/to/foo/doc/.yardoc'
end
it "returns nil if no .yardoc path exists in gem when for_writing=false" do
allow(File).to receive(:exist?).twice.and_return(false)
allow(File).to receive(:exist?).with('/path/to/foo/.yardoc').and_return(false)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo')).to eq nil
end
it "searches local gem path first if for_writing=false" do
allow(File).to receive(:exist?).and_return(true)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo')).to match %r{/.yard/gem_index/foo-1.0.yardoc$}
end
it "returns global .yardoc path for gem if for_writing=true and dir is writable" do
allow(File).to receive(:exist?).and_return(false)
allow(File).to receive(:directory?).with(@gem.doc_dir).and_return(true)
allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
allow(File).to receive(:writable?).with(@gem.full_gem_path).and_return(true)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/.yardoc'
end
it "returns new global .yardoc path for gem if for_writing=true and dir is writable" do
allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(true)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/doc/.yardoc'
end
it "returns new global .yardoc path for gem if for_writing=true and parent dir is writable (but dir does not exist)" do
allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
allow(File).to receive(:directory?).with(@gem.doc_dir).and_return(false)
allow(File).to receive(:writable?).with(File.dirname(@gem.doc_dir)).and_return(true)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/doc/.yardoc'
end
it "returns local .yardoc path for gem if for_writing=true and dir is not writable" do
allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
allow(File).to receive(:writable?).with(@gem.full_gem_path).and_return(false)
allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to match %r{/.yard/gem_index/foo-1.0.yardoc$}
end
it "returns gem path if gem starts with yard-doc- and for_writing=false" do
allow(@gem).to receive(:name).and_return('yard-doc-core')
allow(@gem).to receive(:full_name).and_return('yard-doc-core-1.0')
allow(@gem).to receive(:full_gem_path).and_return('/path/to/yard-doc-core')
allow(YARD::GemIndex).to receive(:find_all_by_name).with('yard-doc-core', '>= 0').and_return([@gem])
allow(File).to receive(:exist?).with('/path/to/yard-doc-core/.yardoc').and_return(true)
expect(Registry.yardoc_file_for_gem('yard-doc-core')).to eq '/path/to/yard-doc-core/.yardoc'
end
it "returns nil if gem starts with yard-doc- and for_writing=true" do
allow(@gem).to receive(:name).and_return('yard-doc-core')
allow(@gem).to receive(:full_name).and_return('yard-doc-core-1.0')
allow(@gem).to receive(:full_gem_path).and_return('/path/to/yard-doc-core')
allow(YARD::GemIndex).to receive(:find_all_by_name).with('yard-doc-core', '>= 0').and_return([@gem])
allow(File).to receive(:exist?).with('/path/to/yard-doc-core/.yardoc').and_return(true)
expect(Registry.yardoc_file_for_gem('yard-doc-core', '>= 0', true)).to eq nil
end
end
describe ".root" do
it "has an empty path for root" do
expect(Registry.root.path).to eq ""
end
end
describe ".locale" do
it "loads locale object" do
fr_locale = I18n::Locale.new("fr")
store = Registry.send(:thread_local_store)
expect(store).to receive(:locale).with("fr").and_return(fr_locale)
expect(Registry.locale("fr")).to eq fr_locale
end
end
describe ".resolve" do
it "resolves any existing namespace" do
o1 = ModuleObject.new(:root, :A)
o2 = ModuleObject.new(o1, :B)
o3 = ModuleObject.new(o2, :C)
expect(Registry.resolve(o1, "B::C")).to eq o3
Registry.resolve(:root, "A::B::C")
end
it "resolves an object in the root namespace when prefixed with ::" do
o1 = ModuleObject.new(:root, :A)
o2 = ModuleObject.new(o1, :B)
o3 = ModuleObject.new(o2, :C)
expect(Registry.resolve(o3, "::A")).to eq o1
expect(Registry.resolve(o3, "::String", false, true)).to eq P(:String)
end
it "resolves instance methods with # prefix" do
o1 = ModuleObject.new(:root, :A)
o2 = ModuleObject.new(o1, :B)
o3 = ModuleObject.new(o2, :C)
o4 = MethodObject.new(o3, :methname)
expect(Registry.resolve(o1, "B::C#methname")).to eq o4
expect(Registry.resolve(o2, "C#methname")).to eq o4
expect(Registry.resolve(o3, "#methname")).to eq o4
end
it "resolves instance methods in the root without # prefix" do
o = MethodObject.new(:root, :methname)
expect(Registry.resolve(:root, 'methname')).to eq o
end
it "does lexical lookup on the initial namespace" do
YARD.parse_string <<-eof
module A
module B; module C; end end
module D; module E; end end
end
eof
d = Registry.at('A::B::C')
expect(Registry.resolve(d, 'D::E')).to eq Registry.at('A::D::E')
end
it "resolves superclass methods when inheritance = true" do
superyard = ClassObject.new(:root, :SuperYard)
yard = ClassObject.new(:root, :YARD)
yard.superclass = superyard
imeth = MethodObject.new(superyard, :hello)
cmeth = MethodObject.new(superyard, :class_hello, :class)
expect(Registry.resolve(yard, "#hello", false)).to be nil
expect(Registry.resolve(yard, "#hello", true)).to eq imeth
expect(Registry.resolve(yard, "class_hello", false)).to be nil
expect(Registry.resolve(yard, "class_hello", true)).to eq cmeth
end
it "does not look at superclass proxies when inheritance = true" do
YARD.parse_string "class A::B; end"
expect(Registry.resolve(Registry.at('A::B'), "#bar", true)).to eq nil
end
it "resolves mixin methods when inheritance = true" do
yard = ClassObject.new(:root, :YARD)
mixin = ModuleObject.new(:root, :Mixin)
yard.mixins(:instance) << mixin
imeth = MethodObject.new(mixin, :hello)
cmeth = MethodObject.new(mixin, :class_hello, :class)
expect(Registry.resolve(yard, "#hello", false)).to be nil
expect(Registry.resolve(yard, "#hello", true)).to eq imeth
expect(Registry.resolve(yard, "class_hello", false)).to be nil
expect(Registry.resolve(yard, "class_hello", true)).to eq cmeth
end
it "resolves methods in Object when inheritance = true" do
YARD.parse_string <<-eof
class Object; def foo; end end
class A; end
class MyObject < A; end
eof
expect(Registry.resolve(P('MyObject'), '#foo', true)).to eq P('Object#foo')
end
it "resolves methods in BasicObject when inheritance = true" do
YARD.parse_string <<-eof
class BasicObject; def foo; end end
class A; end
class MyObject < A; end
eof
expect(Registry.resolve(P('MyObject'), '#foo', true)).to eq P('BasicObject#foo')
end
it "does not perform lexical lookup to resolve a method object by more than one namespace" do
YARD.parse_string <<-eof
module A
def foo; end
def self.bar; end
module B; module C; end end
end
eof
expect(Registry.resolve(P('A::B::C'), '#foo', true)).to be nil
expect(Registry.resolve(P('A::B::C'), '.bar', true)).to be nil
expect(Registry.resolve(P('A::B'), '#foo', true)).not_to be nil
expect(Registry.resolve(P('A::B'), '.bar', true)).not_to be nil
end
it "does not resolve methods in Object if inheriting BasicObject when inheritance = true" do
YARD.parse_string <<-eof
class Object; def foo; end end
class MyObject < BasicObject; end
eof
expect(Registry.resolve(P('MyObject'), '#foo', true)).to be nil
end
it "performs lookups on each individual namespace when inheritance = true" do
YARD.parse_string <<-eof
module A
module B; include A::D end
module C; extend A::D end
module D; def bar; end end
end
eof
r = Registry.root
expect(Registry.resolve(r, 'A::B#bar', true)).to eq Registry.at('A::D#bar')
expect(Registry.resolve(r, 'A::C.bar', true)).to eq Registry.at('A::D#bar')
end
it "allows type=:typename to ensure resolved object is of a certain type" do
YARD.parse_string "class Foo; end"
expect(Registry.resolve(Registry.root, 'Foo')).to eq Registry.at('Foo')
expect(Registry.resolve(Registry.root, 'Foo', false, false, :method)).to be nil
end
it "allows keep trying to find obj where type equals object type" do
YARD.parse_string <<-eof
module Foo
class Bar; end
def self.Bar; end
end
eof
expect(Registry.resolve(P('Foo'), 'Bar', false, false, :class)).to eq Registry.at('Foo::Bar')
expect(Registry.resolve(P('Foo'), 'Bar', false, false, :method)).to eq(
Registry.at('Foo.Bar')
)
end
it "returns proxy fallback with given type if supplied" do
YARD.parse_string "module Foo; end"
proxy = Registry.resolve(P('Foo'), 'Bar', false, true, :method)
expect(proxy.type).to eq :method
proxy = Registry.resolve(P('Qux'), 'Bar', false, true, :method)
expect(proxy.type).to eq :method
end
it "does not return proxy on original namespace if path is anchored to root" do
YARD.parse_string "module Foo; class Bar; def baz; end end end"
proxy = Registry.resolve(P('Foo::Bar#baz'), '::Bar', true, true)
expect(proxy.path).to eq('Bar')
expect(proxy.namespace).to equal(Registry.root)
expect(proxy.type).to eq(:proxy)
end
it "only checks 'Path' in lookup on root namespace" do
expect(Registry).to receive(:at).once.with('Test').and_return(true)
Registry.resolve(Registry.root, "Test")
end
it "does not perform lookup by joining namespace and name without separator" do
yard = ClassObject.new(:root, :YARD)
expect(Registry).not_to receive(:at).with('YARDB')
Registry.resolve(yard, 'B')
end
end
describe ".all" do
it "returns objects of types specified by arguments" do
ModuleObject.new(:root, :A)
o1 = ClassObject.new(:root, :B)
o2 = MethodObject.new(:root, :testing)
r = Registry.all(:method, :class)
expect(r).to include(o1, o2)
end
it "returns code objects" do
o1 = ModuleObject.new(:root, :A)
o2 = ClassObject.new(:root, :B)
MethodObject.new(:root, :testing)
r = Registry.all.select {|t| NamespaceObject === t }
expect(r).to include(o1, o2)
end
it "allows .all to omit list" do
o1 = ModuleObject.new(:root, :A)
o2 = ClassObject.new(:root, :B)
r = Registry.all
expect(r).to include(o1, o2)
end
end
describe ".paths" do
it "returns all object paths" do
ModuleObject.new(:root, :A)
ClassObject.new(:root, :B)
expect(Registry.paths).to include('A', 'B')
end
end
describe ".load_yardoc" do
it "delegates load to RegistryStore" do
store = RegistryStore.new
expect(store).to receive(:load).with('foo')
expect(RegistryStore).to receive(:new).and_return(store)
Registry.yardoc_file = 'foo'
Registry.load_yardoc
end
it "returns itself" do
expect(Registry.load_yardoc).to eq Registry
end
it "maintains hash key equality on loaded objects" do
Registry.clear
Registry.load!(File.dirname(__FILE__) + '/serializers/data/serialized_yardoc')
baz = Registry.at('Foo#baz')
expect(Registry.at('Foo').aliases.keys).to include(baz)
expect(Registry.at('Foo').aliases.key?(baz)).to be true
end
end
['load', 'load_all', 'load!'].each do |meth|
describe('.' + meth) do
it "returns itself" do
expect(Registry.send(meth)).to eq Registry
end
end
end
describe ".each" do
before do
YARD.parse_string "def a; end; def b; end; def c; end"
end
after { Registry.clear }
it "iterates over .all" do
items = []
Registry.each {|x| items << x.path }
expect(items.sort).to eq ['#a', '#b', '#c']
end
it "includes Enumerable and allow for find, select" do
expect(Registry.find {|x| x.path == "#a" }).to be_a(CodeObjects::MethodObject)
end
end
describe ".instance" do
it "returns itself" do
expect(Registry.instance).to eq Registry
end
end
describe ".single_object_db" do
it "defaults to nil" do
expect(Registry.single_object_db).to eq nil
Thread.new { expect(Registry.single_object_db).to eq nil }.join
end
end
describe "Thread local" do
it "maintains two Registries in separate threads" do
barrier = 0
mutex = Mutex.new
threads = []
threads << Thread.new do
Registry.clear
YARD.parse_string "# docstring 1\nclass Foo; end"
mutex.synchronize { barrier += 1 }
"barrier < 2, spinning" while barrier < 2
expect(Registry.at('Foo').docstring).to eq "docstring 1"
end
threads << Thread.new do
Registry.clear
YARD.parse_string "# docstring 2\nclass Foo; end"
mutex.synchronize { barrier += 1 }
"barrier < 2, spinning" while barrier < 2
expect(Registry.at('Foo').docstring).to eq "docstring 2"
end
threads.each(&:join)
end
it "allows setting of yardoc_file in separate threads" do
barrier = 0
mutex = Mutex.new
threads = []
threads << Thread.new do
expect(Registry.yardoc_file).to eq '.yardoc'
Registry.yardoc_file = 'foo'
mutex.synchronize { barrier += 1 }
"barrier = 1, spinning" while barrier == 1
expect(Registry.yardoc_file).to eq 'foo'
end
threads << Thread.new do
"barrier = 0, spinning" while barrier == 0
expect(Registry.yardoc_file).to eq '.yardoc'
mutex.synchronize { barrier += 1 }
Registry.yardoc_file = 'foo2'
end
threads.each(&:join)
Registry.yardoc_file = Registry::DEFAULT_YARDOC_FILE
end
it "automatically clears in new threads" do
Thread.new { expect(Registry.all).to be_empty }.join
end
it "allows setting of po_dir in separate threads" do
barrier = 0
mutex = Mutex.new
threads = []
threads << Thread.new do
expect(Registry.po_dir).to eq 'po'
Registry.po_dir = 'locale'
mutex.synchronize { barrier += 1 }
"barrier = 1, spinning" while barrier == 1
expect(Registry.po_dir).to eq 'locale'
end
threads << Thread.new do
"barrier = 0, spinning" while barrier == 0
expect(Registry.po_dir).to eq 'po'
mutex.synchronize { barrier += 1 }
Registry.po_dir = '.'
end
threads.each(&:join)
Registry.po_dir = Registry::DEFAULT_PO_DIR
end
end
end
yard-0.9.7/spec/verifier_spec.rb 0000644 0000041 0000041 00000006064 13035234564 016635 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::Verifier do
describe "#parse_expressions" do
it "creates #__execute method" do
v = Verifier.new("expr1")
expect(v).to respond_to(:__execute)
end
it "parses @tagname into tag('tagname')" do
obj = double(:object)
expect(obj).to receive(:tag).with('return')
Verifier.new('@return').call(obj)
end
it "parses @@tagname into object.tags('tagname')" do
obj = double(:object)
expect(obj).to receive(:tags).with('return')
Verifier.new('@@return').call(obj)
end
it "allows namespaced tag using @{} syntax" do
obj = double(:object)
expect(obj).to receive(:tag).with('yard.return')
Verifier.new('@{yard.return}').call(obj)
end
it "allows namespaced tags using @{} syntax" do
obj = double(:object)
expect(obj).to receive(:tags).with('yard.return')
Verifier.new('@@{yard.return}').call(obj)
end
it "calls methods on tag object" do
obj = double(:object)
obj2 = double(:tag)
expect(obj).to receive(:tag).with('return').and_return obj2
expect(obj2).to receive(:foo)
Verifier.new('@return.foo').call(obj)
end
it "sends any missing methods to object" do
obj = double(:object)
expect(obj).to receive(:has_tag?).with('return')
Verifier.new('has_tag?("return")').call(obj)
end
it "allows multiple expressions" do
obj = double(:object)
expect(obj).to receive(:tag).with('return').and_return(true)
expect(obj).to receive(:tag).with('param').and_return(false)
expect(Verifier.new('@return', '@param').call(obj)).to be false
end
end
describe "#o" do
it "aliases object to o" do
obj = double(:object)
expect(obj).to receive(:a).ordered
Verifier.new('o.a').call(obj)
end
end
describe "#call" do
it "doubles a nonexistent tag so that exceptions are not raised" do
obj = double(:object)
expect(obj).to receive(:tag).and_return(nil)
expect(Verifier.new('@return.text').call(obj)).to be false
end
it "does not fail if no expressions were added" do
expect { Verifier.new.call(nil) }.not_to raise_error
end
it "always ignores proxy objects and return true" do
v = Verifier.new('tag(:x)')
expect { expect(v.call(P('foo'))).to be true }.not_to raise_error
end
end
describe "#expressions" do
it "maintains a list of all unparsed expressions" do
expect(Verifier.new('@return.text', '@private').expressions).to eq ['@return.text', '@private']
end
end
describe "#expressions=" do
it "recompiles expressions when attribute is modified" do
obj = double(:object)
expect(obj).to receive(:tag).with('return')
v = Verifier.new
v.expressions = ['@return']
v.call(obj)
end
end
describe "#add_expressions" do
it "adds new expressions and recompile" do
obj = double(:object)
expect(obj).to receive(:tag).with('return')
v = Verifier.new
v.add_expressions '@return'
v.call(obj)
end
end
end
yard-0.9.7/spec/cli/ 0000755 0000041 0000041 00000000000 13035234564 014224 5 ustar www-data www-data yard-0.9.7/spec/cli/command_parser_spec.rb 0000644 0000041 0000041 00000002352 13035234564 020557 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::CommandParser do
describe "#run" do
before do
@cmd = CLI::CommandParser.new
end
it "shows help if --help is provided" do
command = double(:command)
expect(command).to receive(:run).with('--help')
CLI::CommandParser.commands[:foo] = command
@cmd.class.default_command = :foo
@cmd.run(*%w(foo --help))
end
it "uses default command if first argument is a switch" do
command = double(:command)
expect(command).to receive(:run).with('--a', 'b', 'c')
CLI::CommandParser.commands[:foo] = command
@cmd.class.default_command = :foo
@cmd.run(*%w(--a b c))
end
it "uses default command if no arguments are provided" do
command = double(:command)
expect(command).to receive(:run)
CLI::CommandParser.commands[:foo] = command
@cmd.class.default_command = :foo
@cmd.run
end
it "lists commands if command is not found" do
expect(@cmd).to receive(:list_commands)
@cmd.run(*%w(unknown_command --args))
end
it "lists commands if --help is provided as sole argument" do
expect(@cmd).to receive(:list_commands)
@cmd.run(*%w(--help))
end
end
end
yard-0.9.7/spec/cli/server_spec.rb 0000644 0000041 0000041 00000024754 13035234564 017105 0 ustar www-data www-data # frozen_string_literal: true
class Server::WebrickAdapter; def start; end end
RSpec.describe YARD::CLI::Server do
before do
allow(CLI::Yardoc).to receive(:run)
@no_verify_libraries = false
@set_libraries = true
@no_adapter_mock = false
@libraries = {}
@options = {:single_library => true, :caching => false}
@server_options = {:Port => 8808}
@adapter = double(:adapter, :setup => nil)
new_cli
end
after(:all) do
Server::Adapter.shutdown
end
def new_cli
@cli = subject
end
def rack_required
require 'rack'
rescue LoadError
pending "rack required for this test"
end
def bundler_required
require 'bundler'
rescue LoadError
pending "bundler required for this test"
end
def unstub_adapter
@no_adapter_mock = true
end
def run(*args)
if @set_libraries && @libraries.empty?
library = Server::LibraryVersion.new(
File.basename(Dir.pwd), nil, File.expand_path('.yardoc')
)
@libraries = {library.name => [library]}
end
unless @no_verify_libraries
@libraries.values.each do |libs|
libs.each do |lib|
yfile = File.expand_path(lib.yardoc_file)
allow(File).to receive(:exist?).with(yfile).and_return(true)
end
end
end
unless @no_adapter_mock
allow(@cli).to receive(:adapter).and_return(@adapter)
expect(@adapter).to receive(:new).
with(@libraries, @options, @server_options).and_return(@adapter)
expect(@adapter).to receive(:start)
end
@cli.run(*args.flatten)
assert_libraries @libraries, @cli.libraries
end
def assert_libraries(expected_libs, actual_libs)
expect(actual_libs).to eq expected_libs
expected_libs.each do |name, libs|
libs.each_with_index do |expected, i|
actual = actual_libs[name][i]
[:source, :source_path, :yardoc_file].each do |m|
expect(actual.send(m)).to eq expected.send(m)
end
end
end
end
# Mocks the existence of a file.
def mock_file(filename, content = nil)
allow(File).to receive(:exist?).with(filename).and_return(true)
allow(File).to receive(:read_binary).with(filename).and_return(content) if content
filename_e = File.expand_path(filename)
mock_file(filename_e) unless filename_e == filename
end
context 'when .yardopts file exists' do
before :each do
Registry.yardoc_file = Registry::DEFAULT_YARDOC_FILE
allow(File).to receive(:exist?).with(%r{\.yardoc/complete$}).and_return(false)
allow(Dir).to receive(:pwd).and_return('/path/to/bar')
allow(Dir).to receive(:chdir).and_yield
@name = 'bar'
end
it "uses .yardoc as the yardoc db if .yardopts doesn't specify an alternate path" do
mock_file '/path/to/bar/.yardopts', '--protected'
@libraries[@name] = [Server::LibraryVersion.new(@name, nil, File.expand_path('/path/to/bar/.yardoc'))]
@libraries.values[0][0].source_path = File.expand_path('/path/to/bar')
run
end
it "uses the yardoc db location specified by .yardopts" do
allow(File).to receive(:exist?).with(%r{/foo/complete$}).and_return(false)
mock_file '/path/to/bar/.yardopts', '--db foo'
@libraries[@name] = [Server::LibraryVersion.new(@name, nil, File.expand_path('/path/to/bar/foo'))]
@libraries.values[0][0].source_path = File.expand_path('/path/to/bar')
run
end
it "parses .yardopts when the library list is odd" do
mock_file '/path/to/bar/.yardopts', '--db foo'
@libraries['a'] = [Server::LibraryVersion.new('a', nil, File.expand_path('/path/to/bar/foo'))]
@libraries.values[0][0].source_path = File.expand_path('/path/to/bar')
run 'a'
end
end
context "when .yardopts file doesn't exist" do
before :each do
allow(File).to receive(:exist?).with(%r{\.yardoc/complete$}).and_return(false)
allow(File).to receive(:exist?).with(%r{^(.*[\\/])?\.yardopts$}).and_return(false)
end
it "defaults to .yardoc if no library is specified" do
allow(Dir).to receive(:chdir).and_yield
expect(Dir).to receive(:pwd).at_least(:once).and_return(File.expand_path('/path/to/foo'))
@libraries['foo'] = [Server::LibraryVersion.new('foo', nil, File.expand_path('/path/to/foo/.yardoc'))]
run
end
it "uses .yardoc as yardoc file if library list is odd" do
@libraries['a'] = [Server::LibraryVersion.new('a', nil, File.expand_path('.yardoc'))]
run 'a'
end
it "forces multi library if more than one library is listed" do
allow(File).to receive(:exist?).with('b').and_return(true)
@options[:single_library] = false
@libraries['a'] = [Server::LibraryVersion.new('a', nil, File.expand_path('b'))]
@libraries['c'] = [Server::LibraryVersion.new('c', nil, File.expand_path('.yardoc'))]
run %w(a b c)
end
it "fails if specified directory does not exist" do
@set_libraries = false
allow(File).to receive(:exist?).with('b').and_return(false)
expect(log).to receive(:warn).with(/Cannot find yardoc db for a: "b"/)
run %w(a b)
end
end
describe "General options" do
before do
allow(File).to receive(:exist?).with(%r{\.yardoc/complete$}).and_return(false)
allow(File).to receive(:exist?).with(/\.yardopts$/).and_return(false)
end
it "accepts -m, --multi-library" do
@options[:single_library] = false
run '-m'
run '--multi-library'
end
it "accepts -c, --cache" do
@options[:caching] = true
run '-c'
run '--cache'
end
it "accepts -r, --reload" do
@options[:incremental] = true
run '-r'
run '--reload'
end
it "accepts -d, --daemon" do
@server_options[:daemonize] = true
run '-d'
run '--daemon'
end
it "accepts -B, --bind" do
@server_options[:Host] = 'example.com'
run '-B', 'example.com'
run '--bind', 'example.com'
end
it "binds address with WebRick adapter" do
@server_options[:Host] = 'example.com'
run '-B', 'example.com', '-a', 'webrick'
run '--bind', 'example.com', '-a', 'webrick'
end
it "binds address with Rack adapter" do
@server_options[:Host] = 'example.com'
run '-B', 'example.com', '-a', 'rack'
run '--bind', 'example.com', '-a', 'rack'
end
it "accepts -p, --port" do
@server_options[:Port] = 10
run '-p', '10'
run '--port', '10'
end
it "accepts --docroot" do
@server_options[:DocumentRoot] = Dir.pwd + '/__foo/bar'
run '--docroot', '__foo/bar'
end
it "accepts -a webrick to create WEBrick adapter" do
expect(@cli).to receive(:adapter=).with(YARD::Server::WebrickAdapter)
run '-a', 'webrick'
end
it "accepts -a rack to create Rack adapter" do
rack_required
expect(@cli).to receive(:adapter=).with(YARD::Server::RackAdapter)
run '-a', 'rack'
end
it "defaults to Rack adapter if exists on system" do
rack_required
expect(@cli).to receive(:require).with('rubygems').and_return(false)
expect(@cli).to receive(:require).with('rack').and_return(true)
expect(@cli).to receive(:adapter=).with(YARD::Server::RackAdapter)
@cli.send(:select_adapter)
end
it "falls back to WEBrick adapter if Rack is not on system" do
expect(@cli).to receive(:require).with('rubygems').and_return(false)
expect(@cli).to receive(:require).with('rack').and_raise(LoadError)
expect(@cli).to receive(:adapter=).with(YARD::Server::WebrickAdapter)
@cli.send(:select_adapter)
end
it "accepts -s, --server" do
@server_options[:server] = 'thin'
run '-s', 'thin'
run '--server', 'thin'
end
it "accepts -g, --gems" do
@no_verify_libraries = true
@options[:single_library] = false
@libraries['gem1'] = [Server::LibraryVersion.new('gem1', '1.0.0', nil, :gem)]
@libraries['gem2'] = [Server::LibraryVersion.new('gem2', '1.0.0', nil, :gem)]
gem1 = double(:gem1, :name => 'gem1', :version => '1.0.0', :full_gem_path => '/path/to/foo')
gem2 = double(:gem2, :name => 'gem2', :version => '1.0.0', :full_gem_path => '/path/to/bar')
specs = {'gem1' => gem1, 'gem2' => gem2}
allow(YARD::GemIndex).to receive(:find_all_by_name) do |k, _ver|
k == '' ? specs.values : specs.grep(k).map {|name| specs[name] }
end
run '-g'
run '--gems'
end
it "accepts -G, --gemfile" do
bundler_required
@no_verify_libraries = true
@options[:single_library] = false
@libraries['gem1'] = [Server::LibraryVersion.new('gem1', '1.0.0', nil, :gem)]
@libraries['gem2'] = [Server::LibraryVersion.new('gem2', '1.0.0', nil, :gem)]
gem1 = double(:gem1, :name => 'gem1', :version => '1.0.0', :full_gem_path => '/path/to/foo')
gem2 = double(:gem2, :name => 'gem2', :version => '1.0.0', :full_gem_path => '/path/to/bar')
lockfile_parser = double(:new, :specs => [gem1, gem2])
allow(Bundler::LockfileParser).to receive(:new).and_return(lockfile_parser)
expect(File).to receive(:exist?).at_least(2).times.with("Gemfile.lock").and_return(true)
allow(File).to receive(:read)
run '-G'
run '--gemfile'
expect(File).to receive(:exist?).with("different_name.lock").and_return(true)
run '--gemfile', 'different_name'
end
it "warns if lockfile is not found (with -G)" do
bundler_required
expect(File).to receive(:exist?).with(/\.yardopts$/).at_least(:once).and_return(false)
expect(File).to receive(:exist?).with('somefile.lock').and_return(false)
expect(log).to receive(:warn).with(/Cannot find somefile.lock/)
run '-G', 'somefile'
end
it "displays an error if Bundler not available (with -G)" do
expect(@cli).to receive(:require).with('bundler').and_raise(LoadError)
expect(log).to receive(:error).with(/Bundler not available/)
run '-G'
end
it "loads template paths after adapter template paths" do
unstub_adapter
@cli.adapter = Server::WebrickAdapter
run '-t', 'foo'
expect(Templates::Engine.template_paths.last).to eq 'foo'
end
it "loads ruby code (-e) after adapter" do
unstub_adapter
@cli.adapter = Server::WebrickAdapter
path = File.dirname(__FILE__) + '/tmp.adapterscript.rb'
begin
File.open(path, 'w') do |f|
f.puts "YARD::Templates::Engine.register_template_path 'foo'"
f.flush
run '-e', f.path
expect(Templates::Engine.template_paths.last).to eq 'foo'
end
ensure
File.unlink(path)
end
end
end
end
yard-0.9.7/spec/cli/help_spec.rb 0000644 0000041 0000041 00000001141 13035234564 016510 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::Help do
describe "#run" do
it "accepts help command" do
expect(CLI::Yardoc).to receive(:run).with('--help')
CLI::Help.run('doc')
end
it "accepts no arguments (and lists all commands)" do
expect(CLI::CommandParser).to receive(:run).with('--help')
CLI::Help.run
end
it "shows all commands if command isn't found" do
expect(CLI::CommandParser).to receive(:run).with('--help')
help = CLI::Help.new
expect(log).to receive(:puts).with(/not found/)
help.run('unknown')
end
end
end
yard-0.9.7/spec/cli/gems_spec.rb 0000644 0000041 0000041 00000006450 13035234564 016523 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
require 'rubygems'
RSpec.describe YARD::CLI::Gems do
before do
@rebuild = false
@gem1 = build_mock('gem1')
@gem2 = build_mock('gem2')
@gem3 = build_mock('gem3')
end
def build_mock(name, version = '1.0')
OpenStruct.new :name => name,
:version => version,
:full_gem_path => "/path/to/gems/#{name}-#{version}",
:yardoc_file => "/path/to/yardoc/#{name}-#{version}"
end
def build_specs(*specs)
specs.each do |themock|
allow(Registry).to receive(:yardoc_file_for_gem).with(themock.name, "= #{themock.version}").and_return(themock.yardoc_file)
allow(File).to receive(:directory?).with(themock.yardoc_file).and_return(@rebuild)
allow(File).to receive(:directory?).with(themock.full_gem_path).and_return(true)
allow(Registry).to receive(:yardoc_file_for_gem).with(themock.name, "= #{themock.version}", true).and_return(themock.yardoc_file)
expect(Dir).to receive(:chdir).with(themock.full_gem_path).and_yield
end
expect(Registry).to receive(:clear).exactly(specs.size).times
expect(CLI::Yardoc).to receive(:run).exactly(specs.size).times
end
describe "#run" do
it "builds all gem indexes if no gem is specified" do
build_specs(@gem1, @gem2)
expect(YARD::GemIndex).to receive(:find_all_by_name).with('').and_return([@gem1, @gem2])
CLI::Gems.run
end
it "allows gem to be specified" do
build_specs(@gem1)
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 0').and_return([@gem1])
CLI::Gems.run(@gem1.name)
end
it "allows multiple gems to be specified for building" do
build_specs(@gem1, @gem2)
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, @gem1.version).and_return([@gem1])
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem2.name, '>= 0').and_return([@gem2])
CLI::Gems.run(@gem1.name, @gem1.version, @gem2.name)
end
it "allows version to be specified with gem" do
build_specs(@gem1)
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 1.0').and_return([@gem1])
CLI::Gems.run(@gem1.name, '>= 1.0')
end
it "warns if one of the gems is not found, but it should process others" do
build_specs(@gem2)
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 2.0').and_return([])
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem2.name, '>= 0').and_return([@gem2])
expect(log).to receive(:warn).with(/#{@gem1.name} >= 2.0 could not be found/)
CLI::Gems.run(@gem1.name, '>= 2.0', @gem2.name)
end
it "fails if specified gem(s) is/are not found" do
expect(CLI::Yardoc).not_to receive(:run)
expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 2.0').and_return([])
expect(log).to receive(:warn).with(/#{@gem1.name} >= 2.0 could not be found/)
expect(log).to receive(:error).with(/No specified gems could be found/)
CLI::Gems.run(@gem1.name, '>= 2.0')
end
it "accepts --rebuild" do
@rebuild = true
build_specs(@gem1)
expect(YARD::GemIndex).to receive(:find_all_by_name).with('').and_return([@gem1])
CLI::Gems.run('--rebuild')
end
end
end
yard-0.9.7/spec/cli/config_spec.rb 0000644 0000041 0000041 00000010606 13035234564 017033 0 ustar www-data www-data # frozen_string_literal: true
require 'yaml'
RSpec.describe YARD::CLI::Config do
before do
@config = YARD::CLI::Config.new
YARD::Config.options = YARD::Config::DEFAULT_CONFIG_OPTIONS.dup
allow(YARD::Config).to receive(:save)
end
def run(*args)
@config.run(*args)
end
describe "Listing configuration" do
it "accepts --list" do
opts = YARD::Config.options
expect(YAML).to receive(:dump).twice.and_return("--- foo\nbar\nbaz")
expect(log).to receive(:puts).twice.with("bar\nbaz")
run
run('--list')
expect(YARD::Config.options).to eq opts
end
end
describe "Viewing an item" do
it "views item if no value is given" do
YARD::Config.options[:foo] = 'bar'
expect(log).to receive(:puts).with('"bar"')
run 'foo'
expect(YARD::Config.options[:foo]).to eq 'bar'
end
end
describe "Modifying an item" do
it "accepts --reset to set value" do
YARD::Config.options[:load_plugins] = 'foo'
run('--reset', 'load_plugins')
expect(YARD::Config.options[:load_plugins]).to be false
end
it "accepts --as-list to force single item as list" do
run('--as-list', 'foo', 'bar')
expect(YARD::Config.options[:foo]).to eq ['bar']
end
it "accepts --append to append values to existing key" do
YARD::Config.options[:foo] = ['bar']
run('--append', 'foo', 'baz', 'quux')
expect(YARD::Config.options[:foo]).to eq ['bar', 'baz', 'quux']
run('-a', 'foo', 'last')
expect(YARD::Config.options[:foo]).to eq ['bar', 'baz', 'quux', 'last']
end
it "turns key into list if --append is used on single item" do
YARD::Config.options[:foo] = 'bar'
run('-a', 'foo', 'baz')
expect(YARD::Config.options[:foo]).to eq ['bar', 'baz']
end
it "modifies item if value is given" do
run('foo', 'xxx')
expect(YARD::Config.options[:foo]).to eq 'xxx'
end
it "turns list of values into array of values" do
run('foo', 'a', 'b', '1', 'true', 'false')
expect(YARD::Config.options[:foo]).to eq ['a', 'b', 1, true, false]
end
it "turns number into numeric Ruby type" do
run('foo', '1')
expect(YARD::Config.options[:foo]).to eq 1
end
it "turns true into TrueClass" do
run('foo', 'true')
expect(YARD::Config.options[:foo]).to be true
end
it "turns false into FalseClass" do
run('foo', 'false')
expect(YARD::Config.options[:foo]).to be false
end
it "saves on modification" do
expect(YARD::Config).to receive(:save)
run('foo', 'true')
end
end
describe "RubyGems hooks" do
require 'rubygems'
class FakeGemConfig < Hash
attr_accessor :written
def write; @written = true end
def path; nil end
end
before do
allow(Gem).to receive(:configuration).and_return(FakeGemConfig.new)
end
it "accepts --gem-install-yri" do
@config.send(:optparse, '--gem-install-yri')
expect(@config.gem_install_cmd).to eq 'yri'
end
it "accepts --gem-install-yard" do
@config.send(:optparse, '--gem-install-yard')
expect(@config.gem_install_cmd).to eq 'yard'
end
it "does not change back to yri if yard was specified" do
@config.send(:optparse, '--gem-install-yard', '--gem-install-yri')
expect(@config.gem_install_cmd).to eq 'yard'
end
it "ignores actual config options" do
run('--gem-install-yri', 'foo', 'true')
expect(YARD::Config).not_to receive(:save)
end
it "updates configuration as :gem if no configuration exists" do
run('--gem-install-yri')
expect(Gem.configuration[:gem]).to eq "--document=yri"
expect(Gem.configuration.written).to eq true
end
[:install, "install", :gem, "gem"].each do |type|
it "finds existing config in #{type.inspect} and updates that line without changing anything else" do
Gem.configuration[type] = "--opts x"
run('--gem-install-yri')
expect(Gem.configuration[type]).to eq "--opts x --document=yri"
([:install, "install", :gem, "gem"] - [type]).each do |other|
expect(Gem.configuration[other]).to eq nil
end
end
end
it "scrubs --document values from existing config" do
Gem.configuration["gem"] = "--document=yri,ri --no-document --opts x"
run('--gem-install-yri')
expect(Gem.configuration["gem"]).to eq "--opts x --document=yri"
end
end
end
yard-0.9.7/spec/cli/yri_spec.rb 0000644 0000041 0000041 00000007264 13035234564 016377 0 ustar www-data www-data # frozen_string_literal: true
class TestYRI < YARD::CLI::YRI
public :optparse, :find_object, :cache_object
def test_stub; end
def print_object(*args) test_stub; super end
end
RSpec.describe YARD::CLI::YRI do
before do
@yri = TestYRI.new
allow(Registry).to receive(:load)
end
describe "#find_object" do
it "uses cache if available" do
allow(@yri).to receive(:cache_object)
expect(File).to receive(:exist?).with('.yardoc').and_return(false)
expect(File).to receive(:exist?).with('bar.yardoc').and_return(true)
expect(Registry).to receive(:load).with('bar.yardoc')
expect(Registry).to receive(:at).ordered.with('Foo').and_return(nil)
expect(Registry).to receive(:at).ordered.with('Foo').and_return('OBJ')
@yri.instance_variable_set("@cache", 'Foo' => 'bar.yardoc')
expect(@yri.find_object('Foo')).to eq 'OBJ'
end
it "never uses cache ahead of current directory's .yardoc" do
allow(@yri).to receive(:cache_object)
expect(File).to receive(:exist?).with('.yardoc').and_return(true)
expect(Registry).to receive(:load).with('.yardoc')
expect(Registry).to receive(:at).ordered.with('Foo').and_return(nil)
expect(Registry).to receive(:at).ordered.with('Foo').and_return('OBJ')
@yri.instance_variable_set("@cache", 'Foo' => 'bar.yardoc')
expect(@yri.find_object('Foo')).to eq 'OBJ'
expect(@yri.instance_variable_get("@search_paths")[0]).to eq '.yardoc'
end
end
describe "#cache_object" do
it "skips caching for Registry.yardoc_file" do
expect(File).not_to receive(:open).with(CLI::YRI::CACHE_FILE, 'w')
@yri.cache_object('Foo', Registry.yardoc_file)
end
end
describe "#initialize" do
it "loads search paths" do
path = %r{/\.yard/yri_search_paths$}
expect(File).to receive(:file?).with(%r{/\.yard/yri_cache$}).and_return(false)
expect(File).to receive(:file?).with(path).and_return(true)
expect(File).to receive(:readlines).with(path).and_return(%w(line1 line2))
@yri = YARD::CLI::YRI.new
spaths = @yri.instance_variable_get("@search_paths")
expect(spaths).to include('line1')
expect(spaths).to include('line2')
end
it "uses DEFAULT_SEARCH_PATHS prior to other paths" do
YARD::CLI::YRI::DEFAULT_SEARCH_PATHS.push('foo', 'bar')
path = %r{/\.yard/yri_search_paths$}
expect(File).to receive(:file?).with(%r{/\.yard/yri_cache$}).and_return(false)
expect(File).to receive(:file?).with(path).and_return(true)
expect(File).to receive(:readlines).with(path).and_return(%w(line1 line2))
@yri = YARD::CLI::YRI.new
spaths = @yri.instance_variable_get("@search_paths")
expect(spaths[0, 4]).to eq %w(foo bar line1 line2)
YARD::CLI::YRI::DEFAULT_SEARCH_PATHS.replace([])
end
end
describe "#run" do
it "searches for objects and print their documentation" do
obj = YARD::CodeObjects::ClassObject.new(:root, 'Foo')
expect(@yri).to receive(:print_object).with(obj)
@yri.run('Foo')
Registry.clear
end
it "prints usage if no object is provided" do
expect(@yri).to receive(:print_usage)
expect(@yri).to receive(:exit).with(1)
@yri.run('')
end
it "prints 'no documentation exists for object' if object is not found" do
expect(STDERR).to receive(:puts).with("No documentation for `Foo'")
expect(@yri).to receive(:exit).with(1)
@yri.run('Foo')
end
it "ensures output is serialized" do
YARD::CodeObjects::ClassObject.new(:root, 'Foo')
allow(@yri).to receive(:test_stub) do
expect(@yri.instance_variable_get(:@serializer)).to receive(:serialize).once
end
@yri.run('Foo')
end
end
end
yard-0.9.7/spec/cli/stats_spec.rb 0000644 0000041 0000041 00000005352 13035234564 016726 0 ustar www-data www-data # frozen_string_literal: true
require 'stringio'
RSpec.describe YARD::CLI::Stats do
before do
Registry.clear
YARD.parse_string <<-eof
class A
CONST = 1
def foo; end
attr_reader :fooattr
# Documented
def bar; end
end
module B; end
eof
@main_stats =
"Files: 1\n" \
"Modules: 1 ( 1 undocumented)\n" \
"Classes: 1 ( 1 undocumented)\n" \
"Constants: 1 ( 1 undocumented)\n" \
"Attributes: 1 ( 0 undocumented)\n" \
"Methods: 2 ( 1 undocumented)\n" \
" 33.33% documented\n"
@output = StringIO.new
@stats = CLI::Stats.new(false)
allow(@stats).to receive(:support_rdoc_document_file!).and_return([])
allow(@stats).to receive(:yardopts).and_return([])
allow(log).to receive(:puts) {|*args| @output << args.join("\n") << "\n" }
end
it "lists undocumented objects with --list-undoc when there are undocumented objects" do
@stats.run('--list-undoc')
expect(@output.string).to eq <<-eof
#{@main_stats}
Undocumented Objects:
(in file: (stdin))
B
A
A::CONST
A#foo
eof
end
it "lists no undocumented objects with --list-undoc when there is nothing undocumented" do
Registry.clear
YARD.parse_string <<-eof
# documentation
def foo; end
eof
@stats.run('--list-undoc')
expect(@output.string).to eq "Files: 1\n" \
"Modules: 0 ( 0 undocumented)\n" \
"Classes: 0 ( 0 undocumented)\n" \
"Constants: 0 ( 0 undocumented)\n" \
"Attributes: 0 ( 0 undocumented)\n" \
"Methods: 1 ( 0 undocumented)\n" \
" 100.00% documented\n"
end
it "lists undocumented objects in compact mode with --list-undoc --compact" do
@stats.run('--list-undoc', '--compact')
expect(@output.string).to eq <<-eof
#{@main_stats}
Undocumented Objects:
B ((stdin):11)
A ((stdin):1)
A::CONST ((stdin):2)
A#foo ((stdin):4)
eof
end
it "still lists stats with --quiet" do
@stats.run('--quiet')
expect(@output.string).to eq @main_stats
end
it "ignores everything with --no-public" do
@stats.run('--no-public')
expect(@output.string).to eq(
"Files: 0\n" \
"Modules: 0 ( 0 undocumented)\n" \
"Classes: 0 ( 0 undocumented)\n" \
"Constants: 0 ( 0 undocumented)\n" \
"Attributes: 0 ( 0 undocumented)\n" \
"Methods: 0 ( 0 undocumented)\n" \
" 100.00% documented\n"
)
end
end
yard-0.9.7/spec/cli/diff_spec.rb 0000644 0000041 0000041 00000017252 13035234564 016502 0 ustar www-data www-data # frozen_string_literal: true
require 'stringio'
require 'open-uri'
RSpec.describe YARD::CLI::Diff do
before do
allow(CLI::Yardoc).to receive(:run)
allow(CLI::Gems).to receive(:run)
@diff = CLI::Diff.new
end
describe "Argument handling" do
it "exits if there is only one gem name" do
expect(@diff).to receive(:exit)
expect(log).to receive(:puts).with(/Usage/)
@diff.run
end
end
describe "Diffing" do
before do
@objects1 = nil
@objects2 = nil
end
def run(*args)
@all_call = -1
@data = StringIO.new
@objects1 ||= %w(C#fooey C#baz D.bar)
@objects2 ||= %w(A A::B A::B::C A.foo A#foo B C.foo C.bar C#baz)
@objects = [@objects1, @objects2]
expect(@diff).to receive(:load_gem_data).ordered.with('gem1') do
Registry.clear
YARD.parse_string <<-eof
class C
def fooey; end
def baz; FOO end
end
class D
def self.bar; end
end
eof
end
expect(@diff).to receive(:load_gem_data).ordered.with('gem2') do
Registry.clear
YARD.parse_string <<-eof
module A
module B
class C; end
end
def self.foo; end
def foo; end
end
class C
def self.foo; end
def self.bar; end
def baz; BAR end
end
eof
end
allow(log).to receive(:print) {|data| @data << data }
allow(log).to receive(:puts) {|*pargs| @data << pargs.join("\n"); @data << "\n" }
@diff.run(*(args + ['gem1', 'gem2']))
end
it "shows differences between objects" do
run
expect(@data.string).to eq <<-eof
Added objects:
A ((stdin):1) (...)
A::B::C ((stdin):3)
C.bar ((stdin):10)
C.foo ((stdin):9)
Modified objects:
C#baz ((stdin):3)
Removed objects:
C#fooey ((stdin):2)
D ((stdin):5) (...)
eof
end
it "accepts --compact" do
run('--compact')
expect(@data.string).to eq <<-eof
A A ((stdin):1) (...)
A A::B::C ((stdin):3)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
M C#baz ((stdin):3)
D C#fooey ((stdin):2)
D D ((stdin):5) (...)
eof
end
it "accepts -a/--all" do
['-a', '--all'].each do |opt|
run(opt)
expect(@data.string).to eq <<-eof
Added objects:
A ((stdin):1)
A#foo ((stdin):6)
A.foo ((stdin):5)
A::B ((stdin):2)
A::B::C ((stdin):3)
C.bar ((stdin):10)
C.foo ((stdin):9)
Modified objects:
C#baz ((stdin):3)
Removed objects:
C#fooey ((stdin):2)
D ((stdin):5)
D.bar ((stdin):6)
eof
end
end
it "accepts --compact and --all" do
run('--compact', '--all')
expect(@data.string).to eq <<-eof
A A ((stdin):1)
A A#foo ((stdin):6)
A A.foo ((stdin):5)
A A::B ((stdin):2)
A A::B::C ((stdin):3)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
M C#baz ((stdin):3)
D C#fooey ((stdin):2)
D D ((stdin):5)
D D.bar ((stdin):6)
eof
end
it "accepts --no-modified" do
run('--compact', '--no-modified')
expect(@data.string).to eq <<-eof
A A ((stdin):1) (...)
A A::B::C ((stdin):3)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
D C#fooey ((stdin):2)
D D ((stdin):5) (...)
eof
end
it "accepts --query" do
run('--compact', '--query', 'o.type == :method')
expect(@data.string).to eq <<-eof
A A#foo ((stdin):6)
A A.foo ((stdin):5)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
M C#baz ((stdin):3)
D C#fooey ((stdin):2)
D D.bar ((stdin):6)
eof
end
end
describe "File searching" do
before do
allow(@diff).to receive(:generate_yardoc)
end
it "searches for gem/.yardoc" do
expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(true)
expect(File).to receive(:directory?).with('gem2/.yardoc').and_return(true)
expect(Registry).to receive(:load_yardoc).with('gem1/.yardoc')
expect(Registry).to receive(:load_yardoc).with('gem2/.yardoc')
@diff.run('gem1', 'gem2')
end
it "searches for argument as yardoc" do
expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem2/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem1').and_return(true)
expect(File).to receive(:directory?).with('gem2').and_return(true)
expect(Registry).to receive(:load_yardoc).with('gem1')
expect(Registry).to receive(:load_yardoc).with('gem2')
@diff.run('gem1', 'gem2')
end
it "searches for installed gem" do
expect(File).to receive(:directory?).with('gem1-1.0.0.gem/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem2-1.0.0/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem1-1.0.0.gem').and_return(false)
expect(File).to receive(:directory?).with('gem2-1.0.0').and_return(false)
spec1 = double(:spec)
spec2 = double(:spec)
expect(YARD::GemIndex).to receive(:find_all_by_name).at_least(1).times.and_return([spec1, spec2])
allow(spec1).to receive(:full_name).and_return('gem1-1.0.0')
allow(spec1).to receive(:name).and_return('gem1')
allow(spec1).to receive(:version).and_return('1.0.0')
allow(spec2).to receive(:full_name).and_return('gem2-1.0.0')
allow(spec2).to receive(:name).and_return('gem2')
allow(spec2).to receive(:version).and_return('1.0.0')
expect(Registry).to receive(:yardoc_file_for_gem).with('gem1', '= 1.0.0').and_return('/path/to/file')
expect(Registry).to receive(:yardoc_file_for_gem).with('gem2', '= 1.0.0').and_return(nil)
expect(Registry).to receive(:load_yardoc).with('/path/to/file')
expect(CLI::Gems).to receive(:run).with('gem2', '1.0.0').and_return(nil)
allow(Dir).to receive(:chdir)
@diff.run('gem1-1.0.0.gem', 'gem2-1.0.0')
end
it "searches for .gem file" do
expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem2.gem/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem1').and_return(false)
expect(File).to receive(:directory?).with('gem2.gem').and_return(false)
expect(File).to receive(:exist?).with('gem1.gem').and_return(true)
expect(File).to receive(:exist?).with('gem2.gem').and_return(true)
expect(File).to receive(:open).with('gem1.gem', 'rb')
expect(File).to receive(:open).with('gem2.gem', 'rb')
allow(FileUtils).to receive(:mkdir_p)
allow(Gem::Package).to receive(:open)
allow(FileUtils).to receive(:rm_rf)
@diff.run('gem1', 'gem2.gem')
end
it "searches for .gem file on rubygems.org" do
expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem2.gem/.yardoc').and_return(false)
expect(File).to receive(:directory?).with('gem1').and_return(false)
expect(File).to receive(:directory?).with('gem2.gem').and_return(false)
expect(File).to receive(:exist?).with('gem1.gem').and_return(false)
expect(File).to receive(:exist?).with('gem2.gem').and_return(false)
expect(@diff).to receive(:open).with('http://rubygems.org/downloads/gem1.gem')
expect(@diff).to receive(:open).with('http://rubygems.org/downloads/gem2.gem')
allow(FileUtils).to receive(:mkdir_p)
allow(Gem::Package).to receive(:open)
allow(FileUtils).to receive(:rm_rf)
@diff.run('gem1', 'gem2.gem')
end
it "raises an error if gem is not found" do
expect(log).to receive(:error).with("Cannot find gem gem1")
expect(log).to receive(:error).with("Cannot find gem gem2.gem")
allow(@diff).to receive(:load_gem_data).and_return(false)
@diff.run('gem1', 'gem2.gem')
end
end
end
yard-0.9.7/spec/cli/i18n_spec.rb 0000644 0000041 0000041 00000006445 13035234564 016353 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::I18n do
before do
@i18n = YARD::CLI::I18n.new
@i18n.use_document_file = false
@i18n.use_yardopts_file = false
output_path = File.expand_path(@i18n.options.serializer.basepath)
allow(File).to receive(:open!).with(output_path, "wb")
allow(YARD).to receive(:parse)
end
describe "Defaults" do
before do
@i18n = YARD::CLI::I18n.new
allow(@i18n).to receive(:yardopts).and_return([])
allow(@i18n).to receive(:support_rdoc_document_file!).and_return([])
@i18n.parse_arguments
end
it "reads .yardopts by default" do
expect(@i18n.use_yardopts_file).to be true
end
it "only shows public visibility by default" do
expect(@i18n.visibilities).to eq [:public]
end
end
describe "General options" do
def self.should_accept(*args, &block)
@counter ||= 0
@counter += 1
counter = @counter
args.each do |arg|
define_method("test_options_#{@counter}", &block)
it("accepts #{arg}") { send("test_options_#{counter}", arg) }
end
end
should_accept('--yardopts') do |arg|
@i18n = YARD::CLI::I18n.new
@i18n.use_document_file = false
expect(@i18n).to receive(:yardopts).at_least(1).times.and_return([])
@i18n.parse_arguments(arg)
expect(@i18n.use_yardopts_file).to be true
@i18n.parse_arguments('--no-yardopts', arg)
expect(@i18n.use_yardopts_file).to be true
end
should_accept('--yardopts with filename') do |_arg|
@i18n = YARD::CLI::I18n.new
expect(File).to receive(:read_binary).with('.yardopts_i18n').and_return('')
@i18n.use_document_file = false
@i18n.parse_arguments('--yardopts', '.yardopts_i18n')
expect(@i18n.use_yardopts_file).to be true
expect(@i18n.options_file).to eq '.yardopts_i18n'
end
should_accept('--no-yardopts') do |arg|
@i18n = YARD::CLI::I18n.new
@i18n.use_document_file = false
expect(@i18n).not_to receive(:yardopts)
@i18n.parse_arguments(arg)
expect(@i18n.use_yardopts_file).to be false
@i18n.parse_arguments('--yardopts', arg)
expect(@i18n.use_yardopts_file).to be false
end
should_accept('--exclude') do |arg|
expect(YARD).to receive(:parse).with(['a'], ['nota', 'b'])
@i18n.run(arg, 'nota', arg, 'b', 'a')
end
end
describe ".yardopts handling" do
before do
@i18n.use_yardopts_file = true
end
it "searches for and uses yardopts file specified by #options_file" do
expect(File).to receive(:read_binary).with("test").and_return("-o \n\nMYPATH\nFILE1 FILE2")
@i18n.use_document_file = false
@i18n.options_file = "test"
expect(File).to receive(:open!).with(File.expand_path("MYPATH"), "wb")
@i18n.run
expect(@i18n.files).to eq ["FILE1", "FILE2"]
end
end
describe "#run" do
it "calls parse_arguments if run() is called" do
expect(@i18n).to receive(:parse_arguments)
@i18n.run
end
it "calls parse_arguments if run(arg1, arg2, ...) is called" do
expect(@i18n).to receive(:parse_arguments)
@i18n.run('--private', '-p', 'foo')
end
it "doesn't call parse_arguments if run(nil) is called" do
expect(@i18n).not_to receive(:parse_arguments)
@i18n.run(nil)
end
end
end
yard-0.9.7/spec/cli/graph_spec.rb 0000644 0000041 0000041 00000001127 13035234564 016665 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::Graph do
it "serializes output" do
allow(Registry).to receive(:load).at_least(1).times
allow(subject).to receive(:yardopts) { [] }
expect(subject.options.serializer).to receive(:serialize).once
subject.run
end
it "reads yardoc file from .yardopts" do
allow(Registry).to receive(:load).at_least(1).times
allow(subject).to receive(:yardopts) { %w(--db /path/to/db) }
expect(subject.options.serializer).to receive(:serialize).once
subject.run
expect(Registry.yardoc_file).to eq '/path/to/db'
end
end
yard-0.9.7/spec/cli/markup_types_spec.rb 0000644 0000041 0000041 00000001211 13035234564 020301 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::MarkupTypes do
it "lists all available markup types" do
YARD::CLI::MarkupTypes.run
data = log.io.string
exts = YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS
YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS.each do |name, providers|
expect(data).to match(/\b#{name}\b/)
# Match all extensions
exts[name].each do |ext|
expect(data).to include(".#{ext}")
end if exts[name]
# Match all provider libs
providers.each do |provider|
expect(data).to match(/\b#{provider[:lib]}\b/)
end
end
end
end
yard-0.9.7/spec/cli/yardoc_spec.rb 0000644 0000041 0000041 00000071674 13035234564 017063 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::Yardoc do
before do
@yardoc = YARD::CLI::Yardoc.new
@yardoc.statistics = false
@yardoc.use_document_file = false
@yardoc.use_yardopts_file = false
@yardoc.generate = false
allow(Templates::Engine).to receive(:render)
allow(Templates::Engine).to receive(:generate)
allow(YARD).to receive(:parse)
allow(Registry).to receive(:load)
allow(Registry).to receive(:save)
allow(File).to receive(:open!)
end
describe "Defaults" do
before do
@yardoc = CLI::Yardoc.new
allow(@yardoc).to receive(:yardopts).and_return([])
allow(@yardoc).to receive(:support_rdoc_document_file!).and_return([])
@yardoc.parse_arguments
end
it "does not use cache by default" do
expect(@yardoc.use_cache).to be false
end
it "prints statistics by default" do
expect(@yardoc.statistics).to be true
end
it "generates output by default" do
expect(@yardoc.generate).to be true
end
it "reads .yardopts by default" do
expect(@yardoc.use_yardopts_file).to be true
end
it "reads .document by default" do
expect(@yardoc.use_document_file).to be true
end
it "uses lib, app, and ext as default file glob paths" do
expect(@yardoc.files).to eq Parser::SourceParser::DEFAULT_PATH_GLOB
end
it "uses rdoc as default markup type (but falls back on none)" do
expect(@yardoc.options.markup).to eq :rdoc
end
it "uses default as default template" do
expect(@yardoc.options.template).to eq :default
end
it "uses HTML as default format" do
expect(@yardoc.options.format).to eq :html
end
it "uses 'Object' as default return type" do
expect(@yardoc.options.default_return).to eq 'Object'
end
it "does not hide void return types by default" do
expect(@yardoc.options.hide_void_return).to be false
end
it "only shows public visibility by default" do
expect(@yardoc.visibilities).to eq [:public]
end
it "does not list objects by default" do
expect(@yardoc.list).to be false
end
it "does not embed mixins by default" do
expect(@yardoc.options.embed_mixins).to be_empty
end
it "does not set any locale by default" do
expect(@yardoc.options.locale).to be nil
end
end
describe "General options" do
def self.should_accept(*args, &block)
@counter ||= 0
@counter += 1
counter = @counter
define_method("test_options_#{@counter}", &block)
args.each do |arg|
it("accepts #{arg}") { send("test_options_#{counter}", arg) }
end
end
should_accept('--single-db') do |arg|
@yardoc.parse_arguments(arg)
expect(Registry.single_object_db).to be true
Registry.single_object_db = nil
end
should_accept('--no-single-db') do |arg|
@yardoc.parse_arguments(arg)
expect(Registry.single_object_db).to be false
Registry.single_object_db = nil
end
should_accept('-c', '--use-cache') do |arg|
@yardoc.parse_arguments(arg)
expect(@yardoc.use_cache).to be true
end
should_accept('--no-cache') do |arg|
@yardoc.parse_arguments(arg)
expect(@yardoc.use_cache).to be false
end
should_accept('--yardopts') do |arg|
@yardoc = CLI::Yardoc.new
@yardoc.use_document_file = false
expect(@yardoc).to receive(:yardopts).at_least(1).times.and_return([])
@yardoc.parse_arguments(arg)
expect(@yardoc.use_yardopts_file).to be true
@yardoc.parse_arguments('--no-yardopts', arg)
expect(@yardoc.use_yardopts_file).to be true
end
should_accept('--yardopts with filename') do |_arg|
@yardoc = CLI::Yardoc.new
expect(File).to receive(:read_binary).with('.foobar').and_return('')
@yardoc.use_document_file = false
@yardoc.parse_arguments('--yardopts', '.foobar')
expect(@yardoc.use_yardopts_file).to be true
expect(@yardoc.options_file).to eq '.foobar'
end
should_accept('--no-yardopts') do |arg|
@yardoc = CLI::Yardoc.new
@yardoc.use_document_file = false
expect(@yardoc).not_to receive(:yardopts)
@yardoc.parse_arguments(arg)
expect(@yardoc.use_yardopts_file).to be false
@yardoc.parse_arguments('--yardopts', arg)
expect(@yardoc.use_yardopts_file).to be false
end
should_accept('--document') do |arg|
@yardoc = CLI::Yardoc.new
@yardoc.use_yardopts_file = false
expect(@yardoc).to receive(:support_rdoc_document_file!).and_return([])
@yardoc.parse_arguments('--no-document', arg)
expect(@yardoc.use_document_file).to be true
end
should_accept('--no-document') do |arg|
@yardoc = CLI::Yardoc.new
@yardoc.use_yardopts_file = false
expect(@yardoc).not_to receive(:support_rdoc_document_file!)
@yardoc.parse_arguments('--document', arg)
expect(@yardoc.use_document_file).to be false
end
should_accept('-b', '--db') do |arg|
@yardoc.parse_arguments(arg, 'test')
expect(Registry.yardoc_file).to eq 'test'
Registry.yardoc_file = '.yardoc'
end
should_accept('-n', '--no-output') do |arg|
expect(Templates::Engine).not_to receive(:generate)
@yardoc.run(arg)
end
should_accept('--exclude') do |arg|
expect(YARD).to receive(:parse).with(['a'], ['nota', 'b'])
@yardoc.run(arg, 'nota', arg, 'b', 'a')
end
should_accept('--no-save') do |arg|
expect(YARD).to receive(:parse)
expect(Registry).not_to receive(:save)
@yardoc.run(arg)
end
end
describe "Output options" do
it "accepts --title" do
@yardoc.parse_arguments('--title', 'hello world')
expect(@yardoc.options.title).to eq 'hello world'
end
it "allows --title to have multiple spaces in .yardopts" do
expect(File).to receive(:read_binary).with("test").and_return("--title \"Foo Bar\"")
@yardoc.options_file = "test"
@yardoc.use_yardopts_file = true
@yardoc.run
expect(@yardoc.options.title).to eq "Foo Bar"
end
it "aliases --main to the --readme flag" do
readme = File.join(File.dirname(__FILE__), '..', '..', 'README.md')
@yardoc.parse_arguments('--main', readme)
expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new(readme, '')
end
it "selects a markup provider when --markup-provider or -mp is set" do
@yardoc.parse_arguments("-M", "test")
expect(@yardoc.options.markup_provider).to eq :test
@yardoc.parse_arguments("--markup-provider", "test2")
expect(@yardoc.options.markup_provider).to eq :test2
end
it "selects a markup format when -m is set" do
expect(@yardoc).to receive(:verify_markup_options).and_return(true)
@yardoc.generate = true
@yardoc.parse_arguments('-m', 'markdown')
expect(@yardoc.options.markup).to eq :markdown
end
it "accepts --default-return" do
@yardoc.parse_arguments(*%w(--default-return XYZ))
expect(@yardoc.options.default_return).to eq "XYZ"
end
it "allows --hide-void-return to be set" do
@yardoc.parse_arguments(*%w(--hide-void-return))
expect(@yardoc.options.hide_void_return).to be true
end
it "accepts --embed-mixins" do
@yardoc.parse_arguments(*%w(--embed-mixins))
expect(@yardoc.options.embed_mixins).to eq ['*']
end
it "accepts --embed-mixin MODULE" do
@yardoc.parse_arguments(*%w(--embed-mixin MyModule))
expect(@yardoc.options.embed_mixins).to eq ['MyModule']
end
it "generates all objects with --use-cache" do
expect(YARD).to receive(:parse)
expect(Registry).to receive(:load)
expect(Registry).to receive(:load_all)
allow(@yardoc).to receive(:generate).and_return(true)
@yardoc.run(*%w(--use-cache))
end
it "does not print statistics with --no-stats" do
allow(@yardoc).to receive(:statistics).and_return(false)
expect(CLI::Stats).not_to receive(:new)
@yardoc.run(*%w(--no-stats))
end
it "disables progress bar with --no-progress" do
old = log.show_progress
log.show_progress = true
@yardoc.run(*%w(--no-progress))
expect(log.show_progress).to eq false
log.show_progress = old
end
describe "--asset" do
before do
@yardoc.generate = true
allow(@yardoc).to receive(:run_generate)
end
it "copies assets to output directory" do
expect(FileUtils).to receive(:cp_r).with('a', 'doc/a')
@yardoc.run(*%w(--asset a))
expect(@yardoc.assets).to eq('a' => 'a')
end
it "allows multiple --asset options" do
expect(FileUtils).to receive(:cp_r).with('a', 'doc/a')
expect(FileUtils).to receive(:cp_r).with('b', 'doc/b')
@yardoc.run(*%w(--asset a --asset b))
expect(@yardoc.assets).to eq('a' => 'a', 'b' => 'b')
end
it "does not allow from or to to refer to a path above current path" do
expect(log).to receive(:warn).exactly(4).times.with(/invalid/i)
@yardoc.run(*%w(--asset ../../../etc/passwd))
expect(@yardoc.assets).to be_empty
@yardoc.run(*%w(--asset a/b/c/d/../../../../../../etc/passwd))
expect(@yardoc.assets).to be_empty
@yardoc.run(*%w(--asset /etc/passwd))
expect(@yardoc.assets).to be_empty
@yardoc.run(*%w(--asset normal:/etc/passwd))
expect(@yardoc.assets).to be_empty
end
it "allows from:to syntax" do
expect(FileUtils).to receive(:cp_r).with('foo', 'doc/bar')
@yardoc.run(*%w(--asset foo:bar))
expect(@yardoc.assets).to eq('foo' => 'bar')
end
it "does not put from inside of to/ if from is a directory" do
begin
from = 'tmp_foo'
to = 'tmp_bar'
full_to = File.join(File.dirname(__FILE__), to)
FileUtils.mkdir_p(from)
@yardoc.options.serializer.basepath = File.dirname(__FILE__)
@yardoc.run("--asset", "#{from}:#{to}")
@yardoc.run("--asset", "#{from}:#{to}")
expect(File.directory?(full_to)).to be true
expect(File.directory?(File.join(full_to, 'tmp_foo'))).to be false
ensure
FileUtils.rm_rf(from)
FileUtils.rm_rf(full_to)
end
end
end
describe "--locale" do
it "applies specified locale to all extra file objects" do
allow(File).to receive(:read).with('extra_file1').and_return('')
allow(File).to receive(:read).with('extra_file2').and_return('')
extra_file_object1 = CodeObjects::ExtraFileObject.new('extra_file1')
extra_file_object2 = CodeObjects::ExtraFileObject.new('extra_file2')
expect(extra_file_object1).to receive(:locale=).with('fr')
expect(extra_file_object2).to receive(:locale=).with('fr')
allow(CodeObjects::ExtraFileObject).to receive(:new).with('extra_file1').and_return(extra_file_object1)
allow(CodeObjects::ExtraFileObject).to receive(:new).with('extra_file2').and_return(extra_file_object2)
allow(Dir).to receive(:glob).with('README{,*[^~]}').and_return([])
allow(File).to receive(:file?).with('extra_file1').and_return(true)
allow(File).to receive(:file?).with('extra_file2').and_return(true)
@yardoc.run('--locale=fr', '-', 'extra_file1', 'extra_file2')
end
end
describe "--po-dir" do
it "sets Registry.po_dir" do
expect(Registry).to receive(:po_dir=).with("locale")
@yardoc.run('--po-dir=locale')
end
end
end
describe "--[no-]api" do
before { Registry.clear }
it "allows --api name" do
YARD.parse_string <<-eof
# @api private
class Foo; end
# @api public
class Bar; end
class Baz; end
eof
@yardoc.run('--api', 'private')
expect(@yardoc.options.verifier.run(Registry.all)).to eq [P('Foo')]
end
it "allows multiple --api's to all be shown" do
YARD.parse_string <<-eof
# @api private
class Foo; end
# @api public
class Bar; end
class Baz; end
eof
@yardoc.run('--api', 'private', '--api', 'public')
expect(@yardoc.options.verifier.run(Registry.all).
sort_by(&:path)).to eq [P('Bar'), P('Foo')]
end
it "allows --no-api to specify objects with no @api tag" do
YARD.parse_string <<-eof
# @api private
class Foo; end
# @api public
class Bar; end
class Baz; end
eof
@yardoc.run('--api', '')
expect(@yardoc.options.verifier.run(Registry.all)).to eq [P('Baz')]
@yardoc.options.verifier = Verifier.new
@yardoc.run('--no-api')
expect(@yardoc.options.verifier.run(Registry.all)).to eq [P('Baz')]
end
it "allows --no-api to work with other --api switches" do
YARD.parse_string <<-eof
# @api private
class Foo; end
# @api public
class Bar; end
class Baz; end
eof
@yardoc.run('--no-api', '--api', 'public')
expect(@yardoc.options.verifier.run(Registry.all).
sort_by(&:path)).to eq [P('Bar'), P('Baz')]
end
it "ensures Ruby code cannot be used" do
[':symbol', '42', '"; exit'].each do |ruby|
@yardoc.options.verifier.expressions = []
@yardoc.run('--api', ruby)
expect(@yardoc.options.verifier.expressions[1]).to include(ruby.inspect)
end
end
end
describe "--hide-api option" do
it "allows --hide-api to hide objects with api tags" do
YARD.parse_string <<-eof
# @api private
class Foo; end
class Bar; end
class Baz; end
eof
@yardoc.run('--hide-api', 'private')
expect(@yardoc.options.verifier.run(Registry.all).
sort_by(&:path)).to eq [P('Bar'), P('Baz')]
end
it "allows --hide-api to work with --api" do
YARD.parse_string <<-eof
# @api private
class Foo; end
# @api public
class Bar; end
class Baz; end
eof
@yardoc.run('--api', 'public', '--hide-api', 'private')
expect(@yardoc.options.verifier.run(Registry.all).
sort_by(&:path)).to eq [P('Bar')]
end
end
describe "--no-private option" do
it "accepts --no-private" do
obj = double(:object)
expect(obj).to receive(:tag).ordered.with(:private).and_return(true)
@yardoc.parse_arguments(*%w(--no-private))
expect(@yardoc.options.verifier.call(obj)).to be false
end
it "hides object if namespace is @private with --no-private" do
ns = double(:namespace, :type => :module)
expect(ns).to receive(:tag).with(:private).and_return(true)
obj = double(:object, :namespace => ns)
expect(obj).to receive(:tag).with(:private).and_return(false)
@yardoc.parse_arguments(*%w(--no-private))
expect(@yardoc.options.verifier.call(obj)).to be false
end
it "does not call #tag on namespace if namespace is proxy with --no-private" do
ns = double(:namespace)
expect(ns).to receive(:is_a?).with(CodeObjects::Proxy).and_return(true)
expect(ns).not_to receive(:tag)
obj = double(:object, :type => :class, :namespace => ns, :visibility => :public)
expect(obj).to receive(:tag).ordered.with(:private).and_return(false)
@yardoc.parse_arguments(*%w(--no-private))
expect(@yardoc.options.verifier.call(obj)).to be true
end
# @bug gh-197
it "does not call #tag on namespace if namespace is proxy with --no-private" do
Registry.clear
YARD.parse_string "module Qux; class Foo::Bar; end; end"
foobar = Registry.at('Foo::Bar')
foobar.namespace.type = :module
@yardoc.parse_arguments(*%w(--no-private))
expect(@yardoc.options.verifier.call(foobar)).to be true
end
it "does not call #tag on proxy object" do # @bug gh-197
@yardoc.parse_arguments(*%w(--no-private))
expect(@yardoc.options.verifier.call(P('ProxyClass'))).to be true
end
it "hides methods inside a 'private' class/module with --no-private" do
Registry.clear
YARD.parse_string <<-eof
# @private
class ABC
def foo; end
end
eof
@yardoc.parse_arguments(*%w(--no-private))
expect(@yardoc.options.verifier.call(Registry.at('ABC'))).to be false
expect(@yardoc.options.verifier.call(Registry.at('ABC#foo'))).to be false
end
end
describe ".yardopts and .document handling" do
before do
@yardoc.use_yardopts_file = true
end
it "searches for and uses yardopts file specified by #options_file" do
expect(File).to receive(:read_binary).with("test").and_return("-o \n\nMYPATH\nFILE1 FILE2")
@yardoc.use_document_file = false
@yardoc.options_file = "test"
@yardoc.run
expect(@yardoc.options.serializer.options[:basepath]).to eq "MYPATH"
expect(@yardoc.files).to eq ["FILE1", "FILE2"]
end
it "uses String#shell_split to split .yardopts tokens" do
optsdata = String.new("foo bar")
expect(optsdata).to receive(:shell_split)
expect(File).to receive(:read_binary).with("test").and_return(optsdata)
@yardoc.options_file = "test"
@yardoc.run
end
it "allows opts specified in command line to override yardopts file" do
expect(File).to receive(:read_binary).with(".yardopts").and_return("-o NOTMYPATH")
@yardoc.run("-o", "MYPATH", "FILE")
expect(@yardoc.options.serializer.options[:basepath]).to eq "MYPATH"
expect(@yardoc.files).to eq ["FILE"]
end
it "loads the RDoc .document file if found" do
expect(File).to receive(:read_binary).with(".yardopts").and_return("-o NOTMYPATH")
@yardoc.use_document_file = true
allow(@yardoc).to receive(:support_rdoc_document_file!).and_return(["FILE2", "FILE3"])
@yardoc.run("-o", "MYPATH", "FILE1")
expect(@yardoc.options.serializer.options[:basepath]).to eq "MYPATH"
expect(@yardoc.files).to eq ["FILE2", "FILE3", "FILE1"]
end
end
describe "Query options" do
after { Registry.clear }
it "hides private constants in with default visibilities" do
classobj = CodeObjects::ClassObject.new(:root, :Foo) {|o| o.visibility = :private }
@yardoc.run
expect(@yardoc.options.verifier.run([classobj])).to eq []
end
it "sets up visibility rules as verifier" do
methobj = CodeObjects::MethodObject.new(:root, :test) {|o| o.visibility = :private }
expect(File).to receive(:read_binary).with("test").and_return("--private")
@yardoc.use_yardopts_file = true
@yardoc.options_file = "test"
@yardoc.run
expect(@yardoc.options.verifier.call(methobj)).to be true
end
it "accepts a --query" do
@yardoc.parse_arguments(*%w(--query @return))
expect(@yardoc.options.verifier).to be_a(Verifier)
end
it "accepts multiple --query arguments" do
obj = double(:object)
expect(obj).to receive(:tag).ordered.with('return').and_return(true)
expect(obj).to receive(:tag).ordered.with('tag').and_return(false)
@yardoc.parse_arguments(*%w(--query @return --query @tag))
expect(@yardoc.options.verifier).to be_a(Verifier)
expect(@yardoc.options.verifier.call(obj)).to be false
end
end
describe "Extra file arguments" do
it "accepts extra files if specified after '-' with source files" do
expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return([])
expect(File).to receive(:file?).with('extra_file1').and_return(true)
expect(File).to receive(:file?).with('extra_file2').and_return(true)
expect(File).to receive(:read).with('extra_file1').and_return('')
expect(File).to receive(:read).with('extra_file2').and_return('')
@yardoc.parse_arguments(*%w(file1 file2 - extra_file1 extra_file2))
expect(@yardoc.files).to eq %w(file1 file2)
expect(@yardoc.options.files).to eq(
[CodeObjects::ExtraFileObject.new('extra_file1', ''),
CodeObjects::ExtraFileObject.new('extra_file2', '')]
)
end
it "accepts files section only containing extra files" do
expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return([])
@yardoc.parse_arguments(*%w(- LICENSE))
expect(@yardoc.files).to eq Parser::SourceParser::DEFAULT_PATH_GLOB
expect(@yardoc.options.files).to eq [CodeObjects::ExtraFileObject.new('LICENSE', '')]
end
it "accepts globs as extra files" do
expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
expect(Dir).to receive(:glob).with('*.txt').and_return ['a.txt', 'b.txt']
expect(File).to receive(:read).with('a.txt').and_return('')
expect(File).to receive(:read).with('b.txt').and_return('')
expect(File).to receive(:file?).with('a.txt').and_return(true)
expect(File).to receive(:file?).with('b.txt').and_return(true)
@yardoc.parse_arguments(*%w(file1 file2 - *.txt))
expect(@yardoc.files).to eq %w(file1 file2)
expect(@yardoc.options.files).to eq(
[CodeObjects::ExtraFileObject.new('a.txt', ''),
CodeObjects::ExtraFileObject.new('b.txt', '')]
)
end
it "warns if extra file is not found" do
expect(log).to receive(:warn).with(/Could not find extra file: UNKNOWN/)
@yardoc.parse_arguments(*%w(- UNKNOWN))
end
it "warns if readme file is not found" do
expect(log).to receive(:warn).with(/Could not find readme file: UNKNOWN/)
@yardoc.parse_arguments(*%w(-r UNKNOWN))
end
it "uses first file as readme if no readme is specified when using --one-file" do
expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
expect(Dir).to receive(:glob).with('lib/*.rb').and_return(['lib/foo.rb'])
expect(File).to receive(:read).with('lib/foo.rb').and_return('')
@yardoc.parse_arguments(*%w(--one-file lib/*.rb))
expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('lib/foo.rb', '')
end
it "uses readme it exists when using --one-file" do
expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README']
expect(File).to receive(:read).with('README').and_return('')
@yardoc.parse_arguments(*%w(--one-file lib/*.rb))
expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
end
it "does not allow US-ASCII charset when using --one-file" do
ienc = Encoding.default_internal
eenc = Encoding.default_external
expect(log).to receive(:warn).with(/not compatible with US-ASCII.*using ASCII-8BIT/)
@yardoc.parse_arguments(*%w(--one-file --charset us-ascii))
expect(Encoding.default_internal.name).to eq 'ASCII-8BIT'
expect(Encoding.default_external.name).to eq 'ASCII-8BIT'
Encoding.default_internal = ienc
Encoding.default_external = eenc
end if defined?(::Encoding)
end
describe "Source file arguments" do
it "accepts no params and parse {lib,app}/**/*.rb ext/**/*.c" do
@yardoc.parse_arguments
expect(@yardoc.files).to eq Parser::SourceParser::DEFAULT_PATH_GLOB
end
end
describe "Tags options" do
def tag_created(switch, factory_method)
visible_tags = double(:visible_tags)
expect(visible_tags).to receive(:|).ordered.with([:foo])
expect(visible_tags).to receive(:-).ordered.with([]).and_return(visible_tags)
expect(Tags::Library).to receive(:define_tag).with('Foo', :foo, factory_method)
allow(Tags::Library).to receive(:visible_tags=)
expect(Tags::Library).to receive(:visible_tags).at_least(1).times.and_return(visible_tags)
@yardoc.parse_arguments("--#{switch}-tag", 'foo')
end
def tag_hidden(tag)
visible_tags = double(:visible_tags)
expect(visible_tags).to receive(:|).ordered.with([tag])
expect(visible_tags).to receive(:-).ordered.with([tag]).and_return([])
expect(Tags::Library).to receive(:define_tag).with(tag.to_s.capitalize, tag, nil)
allow(Tags::Library).to receive(:visible_tags=)
expect(Tags::Library).to receive(:visible_tags).at_least(1).times.and_return(visible_tags)
end
it "accepts --tag" do
expect(Tags::Library).to receive(:define_tag).with('Title of Foo', :foo, nil)
@yardoc.parse_arguments('--tag', 'foo:Title of Foo')
end
it "accepts --tag without title (and default to captialized tag name)" do
expect(Tags::Library).to receive(:define_tag).with('Foo', :foo, nil)
@yardoc.parse_arguments('--tag', 'foo')
end
it "only lists tag once if declared twice" do
visible_tags = []
allow(Tags::Library).to receive(:define_tag)
allow(Tags::Library).to receive(:visible_tags).and_return([:foo])
allow(Tags::Library).to receive(:visible_tags=) {|value| visible_tags = value }
@yardoc.parse_arguments('--tag', 'foo', '--tag', 'foo')
expect(visible_tags).to eq [:foo]
end
it "accepts --type-tag" do
tag_created 'type', :with_types
end
it "accepts --type-name-tag" do
tag_created 'type-name', :with_types_and_name
end
it "accepts --name-tag" do
tag_created 'name', :with_name
end
it "accepts --title-tag" do
tag_created 'title', :with_title_and_text
end
it "accepts --hide-tag before tag is listed" do
tag_hidden(:anewfoo)
@yardoc.parse_arguments('--hide-tag', 'anewfoo', '--tag', 'anewfoo')
end
it "accepts --hide-tag after tag is listed" do
tag_hidden(:anewfoo2)
@yardoc.parse_arguments('--tag', 'anewfoo2', '--hide-tag', 'anewfoo2')
end
it "accepts --transitive-tag" do
@yardoc.parse_arguments('--transitive-tag', 'foo')
expect(Tags::Library.transitive_tags).to include(:foo)
end
it "accepts --non-transitive-tag" do
Tags::Library.transitive_tags |= [:foo]
@yardoc.parse_arguments('--non-transitive-tag', 'foo')
expect(Tags::Library.transitive_tags).not_to include(:foo)
end
end
describe "Safe mode" do
before do
allow(YARD::Config).to receive(:options).and_return(:safe_mode => true)
end
it "does not allow --load or -e in safe mode" do
expect(@yardoc).not_to receive(:require)
@yardoc.run('--load', 'foo')
@yardoc.run('-e', 'foo')
end
it "does not allow --query in safe mode" do
@yardoc.run('--query', 'foo')
expect(@yardoc.options.verifier.expressions).not_to include("foo")
end
it "does not allow modifying the template paths" do
expect(YARD::Templates::Engine).not_to receive(:register_template_path)
@yardoc.run('-p', 'foo')
@yardoc.run('--template-path', 'foo')
end
end
describe "Markup Loading" do
it "loads rdoc markup if no markup is provided" do
@yardoc.generate = true
@yardoc.run
expect(@yardoc.options.markup).to eq :rdoc
end
it "loads rdoc markup even when no output is specified" do
@yardoc.parse_arguments('--no-output')
expect(@yardoc.options.markup).to eq :rdoc
end
it "warns if rdoc cannot be loaded and fallback to :none" do
mod = YARD::Templates::Helpers::MarkupHelper
mod.clear_markup_cache
expect(mod.const_get(:MARKUP_PROVIDERS)).to receive(:[]).with(:rdoc).and_return([{:lib => 'INVALID'}])
expect(log).to receive(:warn).with(/Could not load default RDoc formatter/)
allow(@yardoc).to receive(:generate) { @yardoc.options.files = []; true }
@yardoc.run
expect(@yardoc.options.markup).to eq :none
mod.clear_markup_cache
end
it "returns an error immediately if markup for any files are missing" do
mod = YARD::Templates::Helpers::MarkupHelper
mod.clear_markup_cache
expect(mod.const_get(:MARKUP_PROVIDERS)).to receive(:[]).with(:markdown).and_return([{:lib => 'INVALID'}])
expect(log).to receive(:error).with(/Missing 'INVALID' gem for Markdown formatting/)
files = [CodeObjects::ExtraFileObject.new('test.md', '')]
allow(@yardoc).to receive(:generate) { @yardoc.options.files = files; true }
@yardoc.run
mod.clear_markup_cache
end
it "returns an error immediately if markup for any files are missing (file markup specified in attributes)" do
mod = YARD::Templates::Helpers::MarkupHelper
mod.clear_markup_cache
expect(mod.const_get(:MARKUP_PROVIDERS)).to receive(:[]).with(:markdown).and_return([{:lib => 'INVALID'}])
expect(log).to receive(:error).with(/Missing 'INVALID' gem for Markdown formatting/)
files = [CodeObjects::ExtraFileObject.new('test', '# @markup markdown')]
allow(@yardoc).to receive(:generate) { @yardoc.options.files = files; true }
@yardoc.run
mod.clear_markup_cache
end
end
describe "#run" do
it "parses arguments if run() is called" do
expect(@yardoc).to receive(:parse_arguments)
@yardoc.run
end
it "parses arguments if run(arg1, arg2, ...) is called" do
expect(@yardoc).to receive(:parse_arguments)
@yardoc.run('--private', '-p', 'foo')
end
it "does not parse arguments if run(nil) is called" do
expect(@yardoc).not_to receive(:parse_arguments)
@yardoc.run(nil)
end
it "creates processing lock if saving" do
expect(Registry).to receive(:lock_for_writing).and_yield
@yardoc.run
end
it "does not create processing lock if not saving" do
expect(Registry).not_to receive(:lock_for_writing)
@yardoc.run('--no-save')
end
end
end
yard-0.9.7/spec/cli/display_spec.rb 0000644 0000041 0000041 00000001776 13035234564 017243 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::Display do
before do
allow(Registry).to receive(:load)
@object = CodeObjects::ClassObject.new(:root, :Foo)
@object.docstring = 'Foo bar'
end
it "displays an object" do
YARD::CLI::Display.run('-f', 'text', 'Foo')
expect(log.io.string.strip).to eq(@object.format.strip)
end
it "wraps output with -l (defaulting to layout)" do
YARD::CLI::Display.run('-l', '-f', 'html', 'Foo')
formatted_output = @object.format(:format => :html).strip
actual_output = log.io.string.strip
expect(actual_output).not_to eq(formatted_output)
expect(actual_output).to include(formatted_output)
end
it "wraps output with --layout onefile" do
YARD::CLI::Display.run('--layout', 'onefile', '-f', 'html', 'Foo')
formatted_output = @object.format(:format => :html).strip
actual_output = log.io.string.strip
expect(actual_output).not_to eq(formatted_output)
expect(actual_output).to include(formatted_output)
end
end
yard-0.9.7/spec/cli/list_spec.rb 0000644 0000041 0000041 00000000354 13035234564 016540 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::CLI::List do
it "passes command off to Yardoc with --list" do
expect(YARD::CLI::Yardoc).to receive(:run).with('-c', '--list', '--foo')
YARD::CLI::List.run('--foo')
end
end
yard-0.9.7/spec/cli/command_spec.rb 0000644 0000041 0000041 00000002075 13035234564 017205 0 ustar www-data www-data # frozen_string_literal: true
require 'optparse'
RSpec.describe YARD::CLI::Command do
describe "#parse_options" do
before do
@options = OptionParser.new
@saw_foo = false
@options.on('--foo') { @saw_foo = true }
end
def parse(*args)
CLI::Command.new.send(:parse_options, @options, args)
args
end
it "skips unrecognized options but continue to next option" do
expect(log).to receive(:warn).with(/Unrecognized.*--list/)
expect(log).to receive(:warn).with(/Unrecognized.*--list2/)
parse('--list', '--list2', '--foo')
expect(@saw_foo).to be true
end
it "skips unrecognized options and any extra non-option arg that follows" do
expect(log).to receive(:warn).with(/Unrecognized.*--list/)
parse('--list', 'foo', '--foo')
expect(@saw_foo).to be true
end
it "stops retrying to parse at non-switch argument" do
expect(log).to receive(:warn).with(/Unrecognized.*--list/)
args = parse('--list', 'foo', 'foo', 'foo')
expect(args).to eq %w(foo foo)
end
end
end
yard-0.9.7/spec/docstring_parser_spec.rb 0000644 0000041 0000041 00000016113 13035234564 020366 0 ustar www-data www-data # frozen_string_literal: true
RSpec.describe YARD::DocstringParser do
after(:all) do
YARD::Registry.clear
end
def parse(content, object = nil, handler = nil)
@library ||= Tags::Library.instance
@parser = DocstringParser.new(@library)
@parser.parse(content, object, handler)
@parser
end
def docstring(content, object = nil, handler = nil)
parse(content, object, handler).to_docstring
end
describe "#parse" do
it "parses comments into tags" do
doc = docstring(<<-eof)
@param name Hello world
how are you?
@param name2
this is a new line
@param name3 and this
is a new paragraph:
right here.
eof
tags = doc.tags(:param)
expect(tags[0].name).to eq "name"
expect(tags[0].text).to eq "Hello world\nhow are you?"
expect(tags[1].name).to eq "name2"
expect(tags[1].text).to eq "this is a new line"
expect(tags[2].name).to eq "name3"
expect(tags[2].text).to eq "and this\nis a new paragraph:\n\nright here."
end
it "ends parsing a tag on de-dent" do
doc = docstring(<<-eof)
@note test
one two three
rest of docstring
eof
expect(doc.tag(:note).text).to eq "test\none two three"
expect(doc).to eq "rest of docstring"
end
it "parses examples embedded in doc" do
doc = docstring(<<-eof)
test string here
@example code
def foo(x, y, z)
end
class A; end
more stuff
eof
expect(doc).to eq "test string here\nmore stuff"
expect(doc.tag(:example).text).to eq "\ndef foo(x, y, z)\nend\n\nclass A; end"
end
it "removes only original indentation from beginning of line in tags" do
doc = docstring(<<-eof)
@param name
some value
foo bar
baz
eof
expect(doc.tag(:param).text).to eq "some value\nfoo bar\n baz"
end
it "allows numbers in tags" do
Tags::Library.define_tag(nil, :foo1)
Tags::Library.define_tag(nil, :foo2)
Tags::Library.define_tag(nil, :foo3)
doc = docstring(<<-eof)
@foo1 bar1
@foo2 bar2
@foo3 bar3
eof
expect(doc.tag(:foo1).text).to eq "bar1"
expect(doc.tag(:foo2).text).to eq "bar2"
end
it "ends tag on newline if next line is not indented" do
doc = docstring(<<-eof)
@author bar1
@api bar2
Hello world
eof
expect(doc.tag(:author).text).to eq "bar1"
expect(doc.tag(:api).text).to eq "bar2"
end
it "warns about unknown tag" do
expect(log).to receive(:warn).with(/Unknown tag @hello$/)
docstring("@hello world")
end
it "does not add trailing whitespace to freeform tags" do
doc = docstring("@api private \t ")
expect(doc.tag(:api).text).to eq "private"
end
end
describe "#parse with custom tag library" do
class TestLibrary < Tags::Library; end
before { @library = TestLibrary.new }
it "accepts valid tags" do
valid = %w(testing valid is_a is_A __)
valid.each do |tag|
TestLibrary.define_tag("Tag", tag)
doc = docstring('@' + tag + ' foo bar')
expect(doc.tag(tag).text).to eq 'foo bar'
end
end
it "does not parse invalid tag names" do
invalid = %w(@ @return@ @p,aram @x-y @.x.y.z)
invalid.each do |tag|
expect(docstring(tag + ' foo bar')).to eq tag + ' foo bar'
end
end
it "allows namespaced tags in the form @x.y.z" do
TestLibrary.define_tag("Tag", 'x.y.z')
doc = docstring("@x.y.z foo bar")
expect(doc.tag('x.y.z').text).to eq 'foo bar'
end
it "ignores new directives without @! prefix syntax" do
TestLibrary.define_directive('dir1', Tags::ScopeDirective)
expect(log).to receive(:warn).with(/@dir1/)
docstring("@dir1")
end
%w(attribute endgroup group macro method scope visibility).each do |tag|
it "handles non prefixed @#{tag} syntax as directive, not tag" do
TestLibrary.define_directive(tag, Tags::ScopeDirective)
parse("@#{tag}")
expect(@parser.directives.first).to be_a(Tags::ScopeDirective)
end
end
it "handles directives with @! prefix syntax" do
TestLibrary.define_directive('dir2', Tags::ScopeDirective)
docstring("@!dir2 class")
expect(@parser.state.scope).to eq :class
end
end
describe "#text" do
it "only returns text data" do
parse("Foo\n@param foo x y z\nBar")
expect(@parser.text).to eq "Foo\nBar"
end
end
describe "#raw_text" do
it "returns the entire original data" do
data = "Foo\n@param foo x y z\nBar"
parse(data)
expect(@parser.raw_text).to eq data
end
end
describe "#tags" do
it "returns the parsed tags" do
data = "Foo\n@param foo x y z\nBar"
parse(data)
expect(@parser.tags.size).to eq 1
expect(@parser.tags.first.tag_name).to eq 'param'
end
end
describe "#directives" do
it "groups all processed directives" do
data = "Foo\n@!scope class\n@!visibility private\nBar"
parse(data)
dirs = @parser.directives
expect(dirs[0]).to be_a(Tags::ScopeDirective)
expect(dirs[0].tag.text).to eq 'class'
expect(dirs[1]).to be_a(Tags::VisibilityDirective)
expect(dirs[1].tag.text).to eq 'private'
end
end
describe "#state" do
it "handles modified state" do
parse("@!scope class")
expect(@parser.state.scope).to eq :class
end
end
describe "after_parse (param)" do
it "allows specifying of callbacks" do
parser = DocstringParser.new
the_yielded_obj = nil
DocstringParser.after_parse {|obj| the_yielded_obj = obj }
parser.parse("Some text")
expect(the_yielded_obj).to eq parser
end
it "warns about invalid named parameters" do
expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
YARD.parse_string <<-eof
# @param notaparam foo
def foo(a) end
eof
end
it "warns about invalid named parameters on @!method directives" do
expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
YARD.parse_string <<-eof
# @!method foo(a)
# @param notaparam foo
test
eof
end
it "warns about duplicate named parameters" do
expect(log).to receive(:warn).with(/@param tag has duplicate parameter name: a/)
YARD.parse_string <<-eof
# @param a foo
# @param a foo
def foo(a) end
eof
end
it "does not warn on aliases" do
expect(log).to_not receive(:warn)
YARD.parse_string <<-eof
# @param a foo
def foo(a) end
alias bar foo
eof
end
end
describe "after_parse (see)" do
it "does not warn on valid see tag" do
expect(log).to_not receive(:warn)
YARD.parse_string "# @see valid\nclass Foo;end"
end
it "warns if {} wraps single name" do
expect(log).to receive(:warn).with(/@see tag \(#1\) should not be wrapped in \{\}/)
YARD.parse_string "# @see {invalid}\nclass Foo;end"
end
it "warns if {} wraps across name and text" do
expect(log).to receive(:warn).with(/@see tag \(#1\) should not be wrapped in \{\}/)
YARD.parse_string "# @see {invalid tag}\nclass Foo;end"
end
end
end
yard-0.9.7/lib/ 0000755 0000041 0000041 00000000000 13035234564 013271 5 ustar www-data www-data yard-0.9.7/lib/rubygems_plugin.rb 0000644 0000041 0000041 00000000605 13035234564 017032 0 ustar www-data www-data # frozen_string_literal: true
if defined?(Gem::VERSION) && Gem::VERSION >= "2.0."
require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/hook')
else
unless defined?(Gem::DocManager.load_yardoc)
require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/specification')
require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/doc_manager')
end
end
yard-0.9.7/lib/yard/ 0000755 0000041 0000041 00000000000 13035234564 014230 5 ustar www-data www-data yard-0.9.7/lib/yard/tags/ 0000755 0000041 0000041 00000000000 13035234564 015166 5 ustar www-data www-data yard-0.9.7/lib/yard/tags/types_explainer.rb 0000644 0000041 0000041 00000011346 13035234564 020733 0 ustar www-data www-data # frozen_string_literal: true
require 'strscan'
module YARD
module Tags
class TypesExplainer
# (see Tag#explain_types)
# @param types [Array] a list of types to parse and summarize
def self.explain(*types)
explain!(*types)
rescue SyntaxError
nil
end
# (see explain)
# @raise [SyntaxError] if the types are not parseable
def self.explain!(*types)
Parser.parse(types.join(", ")).join("; ")
end
class << self
private :new
end
# @private
class Type
attr_accessor :name
def initialize(name)
@name = name
end
def to_s(singular = true)
if name[0, 1] == "#"
singular ? "an object that responds to #{name}" : "objects that respond to #{name}"
elsif name[0, 1] =~ /[A-Z]/
singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
else
name
end
end
private
def list_join(list)
index = 0
list.inject(String.new) do |acc, el|
acc << el.to_s
acc << ", " if index < list.size - 2
acc << " or " if index == list.size - 2
index += 1
acc
end
end
end
# @private
class CollectionType < Type
attr_accessor :types
def initialize(name, types)
@name = name
@types = types
end
def to_s(_singular = true)
"a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} of (" + list_join(types.map {|t| t.to_s(false) }) + ")"
end
end
# @private
class FixedCollectionType < CollectionType
def to_s(_singular = true)
"a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} containing (" + types.map(&:to_s).join(" followed by ") + ")"
end
end
# @private
class HashCollectionType < Type
attr_accessor :key_types, :value_types
def initialize(name, key_types, value_types)
@name = name
@key_types = key_types
@value_types = value_types
end
def to_s(_singular = true)
"a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with keys made of (" +
list_join(key_types.map {|t| t.to_s(false) }) +
") and values of (" + list_join(value_types.map {|t| t.to_s(false) }) + ")"
end
end
# @private
class Parser
TOKENS = {
:collection_start => / />/,
:fixed_collection_start => /\(/,
:fixed_collection_end => /\)/,
:type_name => /#\w+|((::)?\w+)+/,
:type_next => /[,;]/,
:whitespace => /\s+/,
:hash_collection_start => /\{/,
:hash_collection_next => /=>/,
:hash_collection_end => /\}/,
:parse_end => nil
}
def self.parse(string)
new(string).parse
end
def initialize(string)
@scanner = StringScanner.new(string)
end
def parse
types = []
type = nil
name = nil
loop do
found = false
TOKENS.each do |token_type, match|
# TODO: cleanup this code.
# rubocop:disable Lint/AssignmentInCondition
next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
found = true
case token_type
when :type_name
raise SyntaxError, "expecting END, got name '#{token}'" if name
name = token
when :type_next
raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
type = Type.new(name) unless type
types << type
type = nil
name = nil
when :fixed_collection_start, :collection_start
name ||= "Array"
klass = token_type == :collection_start ? CollectionType : FixedCollectionType
type = klass.new(name, parse)
when :hash_collection_start
name ||= "Hash"
type = HashCollectionType.new(name, parse, parse)
when :hash_collection_next, :hash_collection_end, :fixed_collection_end, :collection_end, :parse_end
raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
type = Type.new(name) unless type
types << type
return types
end
end
raise SyntaxError, "invalid character at #{@scanner.peek(1)}" unless found
end
end
end
end
end
end
yard-0.9.7/lib/yard/tags/tag_format_error.rb 0000644 0000041 0000041 00000000162 13035234564 021046 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
class TagFormatError < RuntimeError
end
end
end
yard-0.9.7/lib/yard/tags/default_tag.rb 0000644 0000041 0000041 00000000442 13035234564 017772 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
class DefaultTag < Tag
attr_reader :defaults
def initialize(tag_name, text, types = nil, name = nil, defaults = nil)
super(tag_name, text, types, name)
@defaults = defaults
end
end
end
end
yard-0.9.7/lib/yard/tags/option_tag.rb 0000644 0000041 0000041 00000000361 13035234564 017656 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
class OptionTag < Tag
attr_accessor :pair
def initialize(tag_name, name, pair)
super(tag_name, nil, nil, name)
@pair = pair
end
end
end
end
yard-0.9.7/lib/yard/tags/directives.rb 0000644 0000041 0000041 00000052716 13035234564 017667 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
module YARD
module Tags
# The base directive class. Subclass this class to create a custom
# directive, registering it with {Library.define_directive}. Directive
# classes are executed via the {#call} method, which perform all directive
# processing on the object.
#
# If processing occurs within a handler, the {#handler} attribute is
# available to access more information about parsing context and state.
# Handlers are only available when parsing from {Parser::SourceParser},
# not when parsing directly from {DocstringParser}. If the docstring is
# attached to an object declaration, {#object} will be set and available
# to modify the generated code object directly. Note that both of these
# attributes may be nil, and directives should test their existence
# before attempting to use them.
#
# @abstract Subclasses should implement {#call}.
# @see Library.define_directive
# @since 0.8.0
class Directive
# @return [Tag] the meta-data tag containing data input to the directive
attr_accessor :tag
# Set this field to replace the directive definition inside of a docstring
# with arbitrary text. For instance, the {MacroDirective} uses this field
# to expand its macro data in place of the call to a +@!macro+.
#
# @return [String] the text to expand in the original docstring in place
# of this directive definition.
# @return [nil] if no expansion should take place for this directive
attr_accessor :expanded_text
# @return [DocstringParser] the parser that is parsing all tag
# information out of the docstring
attr_accessor :parser
# @!attribute [r] object
# @return [CodeObjects::Base, nil] the object the parent docstring is
# attached to. May be nil.
def object; parser.object end
# @!attribute [r] handler
# @return [Handlers::Base, nil] the handler object the docstring parser
# might be attached to. May be nil. Only available when parsing
# through {Parser::SourceParser}.
def handler; parser.handler end
# @!endgroup
# @param [Tag] tag the meta-data tag containing all input to the docstring
# @param [DocstringParser] parser the docstring parser object
def initialize(tag, parser)
self.tag = tag
self.parser = parser
self.expanded_text = nil
end
# @!group Parser callbacks
# Called when processing the directive. Subclasses should implement
# this method to perform all functionality of the directive.
#
# @abstract implement this method to perform all data processing for
# the directive.
# @return [void]
def call; raise NotImplementedError end
# Called after parsing all directives and tags in the docstring. Used
# to perform any cleanup after all directives perform their main task.
# @return [void]
def after_parse; end
protected :parser
end
# Ends a group listing definition. Group definition automatically end
# when class or module blocks are closed, and defining a new group overrides
# the last group definition, but occasionally you need to end the current
# group to return to the default listing. Use {tag:!group} to begin a
# group listing.
#
# @example
# class Controller
# # @!group Callbacks
#
# def before_filter; end
# def after_filter; end
#
# # @!endgroup
#
# def index; end
# end
# @see tag:!group
# @since 0.6.0
class EndGroupDirective < Directive
def call
return unless handler
handler.extra_state.group = nil
end
end
# Defines a group listing. All methods (and attributes) seen after this
# directive are placed into a group with the given description as the
# group name. The group listing is used by templates to organize methods
# and attributes into respective logical groups. To end a group listing
# use {tag:!endgroup}.
#
# @note A group definition only applies to the scope it is defined in.
# If a new class or module is opened after the directive, this directive
# will not apply to methods in that class or module.
# @example
# # @!group Callbacks
#
# def before_filter; end
# def after_filter; end
# @see tag:!endgroup
# @since 0.6.0
class GroupDirective < Directive
def call
return unless handler
handler.extra_state.group = tag.text
end
end
# Defines a block of text to be expanded whenever the macro is called by name
# in subsequent docstrings. The macro data can be any arbitrary text data, be
# it regular documentation, meta-data tags or directives.
#
# == Defining a Macro
#
# A macro must first be defined in order to be used. Note that a macro is also
# expanded upon definition if it defined on an object (the docstring of a
# method, class, module or constant object as opposed to a free standing
# comment). To define a macro, use the "new" or "attach" identifier in the
# types specifier list. A macro will also automatically be created if an
# indented macro data block is given, so the keywords are not strictly needed.
#
# === Anonymous Macros
#
# In addition to standard named macros, macros can be defined anonymously if
# no name is given. In this case, they can not be re-used in future docstrings,
# but they will expand in the first definition. This is useful when needing
# to take advantage of the macro expansion variables (described below).
#
# == Using a Macro
#
# To re-use a macro in another docstring after it is defined, simply use
# @!macro the_name with no indented block of macro data. The resulting
# data will be expanded in place.
#
# == Attaching a Macro to a DSL Method
#
# Macros can be defined to auto-expand on DSL-style class method calls. To
# define a macro to be auto expanded in this way, use the "attach" keyword
# in the type specifier list ("new" is implied).
#
# Attached macros can also be attached directly on the class method declaration
# that provides the DSL method to its subclasses. The syntax in either case
# is the same.
#
# == Macro Expansion Variables
#
# In the case of using macros on DSL-style method calls, a number of expansion
# variables can be used for interpolation inside of the macro data. The variables,
# similar in syntax to Ruby's global variables, are as follows:
#
# * $0 - the method name being called
# * $1, $2, $3, ... - the Nth argument in the method call
# * $& - the full source line
#
# The following example shows what the expansion variables might hold for a given
# DSL method call:
#
# property :foo, :a, :b, :c, String
# # $0 => "property"
# # $1 => "foo"
# # $2 => "a"
# # $& => "property :foo, :a, :b, :c, String"
#
# === Ranges
#
# Ranges are also acceptable with the syntax ${N-M}. Negative values
# on either N or M are valid, and refer to indexes from the end of the list.
# Consider a DSL method that creates a method using the first argument with
# argument names following, ending with the return type of the method. This
# could be documented as:
#
# # @!macro dsl_method
# # @!method $1(${2--2})
# # @return [${-1}] the return value of $0
# create_method_with_args :foo, :a, :b, :c, String
#
# As described, the method is using the signature foo(a, b, c) and the return
# type from the last argument, +String+. When using ranges, tokens are joined
# with commas. Note that this includes using $0:
#
# !!!plain
# $0-1 # => Interpolates to "create_method_with_args, foo"
#
# If you want to separate them with spaces, use $1 $2 $3 $4 .... Note that
# if the token cannot be expanded, it will return the empty string (not an error),
# so it would be safe to list $1 $2 ... $10, for example.
#
# === Escaping Interpolation
#
# Interpolation can be escaped by prefixing the +$+ with +\\\+, like so:
#
# # @!macro foo
# # I have \$2.00 USD.
#
# @example Defining a simple macro
# # @!macro [new] returnself
# # @return [self] returns itself
# @example Using a simple macro in multiple docstrings
# # Documentation for map
# # ...
# # @macro returnself
# def map; end
#
# # Documentation for filter
# # ...
# # @macro returnself
# def filter; end
# @example Attaching a macro to a class method (for DSL usage)
# class Resource
# # Defines a new property
# # @param [String] name the property name
# # @param [Class] type the property's type
# # @!macro [attach] property
# # @return [$2] the $1 property
# def self.property(name, type) end
# end
#
# class Post < Resource
# property :title, String
# property :view_count, Integer
# end
# @example Attaching a macro directly to a DSL method
# class Post < Resource
# # @!macro [attach] property
# # @return [$2] the $1 property
# property :title, String
#
# # Macro will expand on this definition too
# property :view_count, Integer
# end
# @since 0.7.0
class MacroDirective < Directive
def call
raise TagFormatError if tag.name.nil? && tag.text.to_s.empty?
macro_data = find_or_create
unless macro_data
warn
return
end
self.expanded_text = expand(macro_data)
end
private
def new?
(tag.types && tag.types.include?('new')) ||
(tag.text && !tag.text.strip.empty?)
end
def attach?
new? && # must have data or there is nothing to attach
class_method? || # always attach to class methods
(tag.types && tag.types.include?('attach'))
end
def class_method?
object && object.is_a?(CodeObjects::MethodObject) &&
object.scope == :class
end
def anonymous?
tag.name.nil? || tag.name.empty?
end
def expand(macro_data)
return if attach? && class_method?
return if !anonymous? && new? &&
(!handler || handler.statement.source.empty?)
call_params = []
caller_method = nil
full_source = ''
if handler
call_params = handler.call_params
caller_method = handler.caller_method
full_source = handler.statement.source
end
all_params = ([caller_method] + call_params).compact
CodeObjects::MacroObject.expand(macro_data, all_params, full_source)
end
def find_or_create
if new? || attach?
if handler && attach?
if object && object.is_a?(CodeObjects::NamespaceObject)
log.warn "Attaching macros to non-methods is unsupported, ignoring: " \
"#{object.path} (#{handler.parser.file}:#{handler.statement.line})"
obj = nil
else
obj = object ? object :
P("#{handler.namespace}.#{handler.caller_method}")
end
else
obj = nil
end
return tag.text || "" if anonymous? # anonymous macro
macro = CodeObjects::MacroObject.create(tag.name, tag.text, obj)
else
macro = CodeObjects::MacroObject.find(tag.name)
end
macro ? macro.macro_data : nil
end
def warn
if object && handler
log.warn "Invalid/missing macro name for " \
"#{object.path} (#{handler.parser.file}:#{handler.statement.line})"
end
end
end
# Defines a method object with a given method signature, using indented
# block data as the method's docstring. The signature is similar to the
# {tag:overload} tag. The comment containing this directive does not need
# to be attached to any source, but if it is, that source code will be
# used as the method's source.
#
# To define an attribute method, see {tag:!attribute}
#
# @note For backwards compatibility support, you do not need to indent
# the method's docstring text. If a +@!method+ directive is seen with
# no indented block, the entire docstring is used as the new method's
# docstring text.
# @example Defining a simple method
# # @!method quit(username, message = "Quit")
# # Sends a quit message to the server for a +username+.
# # @param [String] username the username to quit
# # @param [String] message the quit message
# quit_message_method
# @example Attaching multiple methods to the same source
# # @!method method1
# # @!method method2
# create_methods :method1, :method2
# @see tag:!attribute
# @since 0.7.0
class MethodDirective < Directive
SCOPE_MATCH = /\A\s*self\s*\.\s*/
def call; end
def after_parse
return unless handler
use_indented_text
create_object
end
protected
def method_name
sig = sanitized_tag_signature
if sig && sig =~ /^#{CodeObjects::METHODNAMEMATCH}(\s|\(|$)/
sig[/\A\s*([^\(; \t]+)/, 1]
else
handler.call_params.first
end
end
def method_signature
"def #{sanitized_tag_signature || method_name}"
end
def sanitized_tag_signature
if tag.name && tag.name =~ SCOPE_MATCH
parser.state.scope = :class
$'
else
tag.name
end
end
def use_indented_text
return if tag.text.empty?
handler = parser.handler
object = parser.object
self.parser = parser.class.new(parser.library)
parser.state.inside_directive = true
parser.parse(tag.text, object, handler)
parser.state.inside_directive = false
end
def create_object
name = method_name
scope = parser.state.scope || handler.scope
visibility = parser.state.visibility || handler.visibility
ns = CodeObjects::NamespaceObject === object ? object : handler.namespace
obj = CodeObjects::MethodObject.new(ns, name, scope)
handler.register_file_info(obj)
handler.register_source(obj)
handler.register_visibility(obj, visibility)
handler.register_group(obj)
obj.signature = method_signature
obj.parameters = OverloadTag.new(:overload, method_signature).parameters
obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
parser.raw_text, parser.reference)
handler.register_module_function(obj)
old_obj = parser.object
parser.object = obj
parser.post_process
parser.object = old_obj
obj
end
end
# Defines an attribute with a given name, using indented block data as the
# attribute's docstring. If the type specifier is supplied with "r", "w", or
# "rw", the attribute is made readonly, writeonly or readwrite respectively.
# A readwrite attribute is the default, if no type is specified. The comment
# containing this directive does not need to be attached to any source, but
# if it is, that source code will be used as the method's source.
#
# To define a regular method, see {tag:!method}
#
# @note For backwards compatibility support, you do not need to indent
# the attribute's docstring text. If an +@!attribute+ directive is seen with
# no indented block, the entire docstring is used as the new attribute's
# docstring text.
# @example Defining a simple readonly attribute
# # @!attribute [r] count
# # @return [Fixnum] the size of the list
# @example Defining a simple readwrite attribute
# # @!attribute name
# # @return [String] the name of the user
# @see tag:!method
# @since 0.7.0
class AttributeDirective < MethodDirective
def after_parse
return unless handler
use_indented_text
create_attribute_data(create_object)
end
protected
def method_name
name = sanitized_tag_signature || handler.call_params.first
name += '=' unless readable?
name
end
def method_signature
if readable?
"def #{method_name}"
else
"def #{method_name}(value)"
end
end
private
def create_attribute_data(object)
return unless object
clean_name = object.name.to_s.sub(/=$/, '')
attrs = object.namespace.attributes[object.scope]
attrs[clean_name] ||= SymbolHash[:read => nil, :write => nil]
attrs[clean_name][:read] = object if readable?
if writable?
if object.name.to_s[-1, 1] == '='
writer = object
writer.parameters = [['value', nil]]
else
writer = CodeObjects::MethodObject.new(object.namespace,
object.name.to_s + '=', object.scope)
writer.signature = "def #{object.name}=(value)"
writer.visibility = object.visibility
writer.dynamic = object.dynamic
writer.source = object.source
writer.group = object.group
writer.parameters = [['value', nil]]
writer.docstring = object.base_docstring
handler.register_file_info(writer)
end
attrs[clean_name][:write] = writer
end
end
def writable?
!tag.types || tag.types.join.include?('w')
end
def readable?
!tag.types || tag.types.join =~ /(?!w)r/
end
end
# Parses a block of code as if it were present in the source file at that
# location. This directive is useful if a class has dynamic meta-programmed
# behaviour that cannot be recognized by YARD.
#
# You can specify the language of the code block using the types
# specification list. By default, the code language is "ruby".
#
# @example Documenting dynamic module inclusion
# class User
# # includes "UserMixin" and extends "UserMixin::ClassMethods"
# # using the UserMixin.included callback.
# # @!parse include UserMixin
# # @!parse extend UserMixin::ClassMethods
# end
# @example Declaring a method as an attribute
# # This should really be an attribute
# # @!parse attr_reader :foo
# def object; @parent.object end
# @example Parsing C code
# # @!parse [c]
# # void Init_Foo() {
# # rb_define_method(rb_cFoo, "method", method, 0);
# # }
# @since 0.8.0
class ParseDirective < Directive
def call
lang = tag.types ? tag.types.first.to_sym :
(handler ? handler.parser.parser_type : :ruby)
if handler && lang == handler.parser.parser_type
pclass = Parser::SourceParser.parser_types[handler.parser.parser_type]
pobj = pclass.new(tag.text, handler.parser.file)
pobj.parse
handler.parser.process(pobj.enumerator)
else # initialize a new parse chain
src_parser = Parser::SourceParser.new(lang, handler ? handler.globals : nil)
src_parser.file = handler.parser.file if handler
src_parser.parse(StringIO.new(tag.text))
end
end
end
# Modifies the current parsing scope (class or instance). If this
# directive is defined on a docstring attached to an object definition,
# it is applied only to that object. Otherwise, it applies the scope
# to all future objects in the namespace.
#
# @example Modifying the scope of a DSL method
# # @!scope class
# cattr_accessor :subclasses
# @example Modifying the scope of a set of methods
# # @!scope class
#
# # Documentation for method1
# def method1; end
#
# # Documentation for method2
# def method2; end
# @since 0.7.0
class ScopeDirective < Directive
def call
if %w(class instance module).include?(tag.text)
if object.is_a?(CodeObjects::MethodObject)
object.scope = tag.text.to_sym
else
parser.state.scope = tag.text.to_sym
end
end
end
end
# Modifies the current parsing visibility (public, protected, or private).
# If this directive is defined on a docstring attached to an object
# definition, it is applied only to that object. Otherwise, it applies
# the visibility to all future objects in the namespace.
#
# @example Modifying the visibility of a DSL method
# # @!visibility private
# cattr_accessor :subclasses
# @example Modifying the visibility of a set of methods
# # Note that Ruby's "protected" is recommended over this directive
# # @!visibility protected
#
# # Documentation for method1
# def method1; end
#
# # Documentation for method2
# def method2; end
# @since 0.7.0
class VisibilityDirective < Directive
def call
if %w(public protected private).include?(tag.text)
if object.is_a?(CodeObjects::Base)
object.visibility = tag.text.to_sym
elsif handler && !parser.state.inside_directive
handler.visibility = tag.text.to_sym
else
parser.state.visibility = tag.text.to_sym
end
end
end
end
end
end
yard-0.9.7/lib/yard/tags/tag.rb 0000644 0000041 0000041 00000005110 13035234564 016263 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
# Represents a metadata tag value (+@tag+). Tags can have any combination of
# {#types}, {#name} and {#text}, or none of the above.
#
# @example Programmatic tag creation
# # The following docstring syntax:
# # @param [String, nil] arg an argument
# #
# # is equivalent to:
# Tag.new(:param, 'an argument', ['String', 'nil'], 'arg')
class Tag
# @return [String] the name of the tag
attr_accessor :tag_name
# @return [String] the tag text associated with the tag
# @return [nil] if no tag text is supplied
attr_accessor :text
# @return [Array] a list of types associated with the tag
# @return [nil] if no types are associated with the tag
attr_accessor :types
# @return [String] a name associated with the tag
attr_accessor :name
# @return [CodeObjects::Base] the associated object
attr_accessor :object
# Creates a new tag object with a tag name and text. Optionally, formally declared types
# and a key name can be specified.
#
# Types are mainly for meta tags that rely on type information, such as +param+, +return+, etc.
#
# Key names are for tags that declare meta data for a specific key or name, such as +param+,
# +raise+, etc.
#
# @param [#to_s] tag_name the tag name to create the tag for
# @param [String] text the descriptive text for this tag
# @param [Array] types optional type list of formally declared types
# for the tag
# @param [String] name optional key name which the tag refers to
def initialize(tag_name, text, types = nil, name = nil)
@tag_name = tag_name.to_s
@text = text
@name = name
@types = (types ? [types].flatten.compact : nil)
end
# Convenience method to access the first type specified. This should mainly
# be used for tags that only specify one type.
#
# @return [String] the first of the list of specified types
# @see #types
def type
types.first
end
# Provides a plain English summary of the type specification, or nil
# if no types are provided or parseable.
#
# @return [String] a plain English description of the associated types
# @return [nil] if no types are provided or not parseable
def explain_types
return nil if !types || types.empty?
TypesExplainer.explain(*types)
end
end
end
end
yard-0.9.7/lib/yard/tags/ref_tag.rb 0000644 0000041 0000041 00000000167 13035234564 017126 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
module RefTag
attr_accessor :owner
end
end
end
yard-0.9.7/lib/yard/tags/library.rb 0000644 0000041 0000041 00000062056 13035234564 017170 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
# Keeps track of all the registered meta-data tags and directives.
# Also allows for defining of custom tags and customizing the tag parsing
# syntax.
#
# == Defining Custom Meta-Data Tags
#
# To define a custom tag, use {define_tag}. You should pass the tag
# name and the factory method to use when creating the tag. If you do not
# provide a factory method to use, it will default to {DefaultFactory#parse_tag}
#
# You can also define tag objects manually by simply implementing a "tagname_tag"
# method that returns a {Tag} object, but they will not take advantage of tag factory
# parsing:
#
# def mytag_tag(text)
# Tag.new(:mytag, text)
# end
#
# == Defining Custom Directives
#
# Directives can be defined by calling the {define_directive} method, taking
# the directive name, an optional tag factory parser method (to parse the
# data in the directive into a temporary {Tag} object) and a {Directive} subclass
# that performs the directive processing. For more information on creating a
# Directive subclass, see the {Directive} class documentation.
#
# Similar to tags, Directives can also be defined manually, in this case using
# the method name "mydirective_directive" and returning a new {Directive} object:
#
# def mydirective_directive(tag, parser)
# MyDirective.new(tag, parser)
# end
#
# == Namespaced Tags
#
# In YARD 0.8.0+, tags can be namespaced using the '.' character. It is recommended
# to namespace project specific tags, like +@yard.tag_name+, so that tags do not
# collide with other plugins or new built-in tags.
#
# == Adding/Changing the Tag Syntax
#
# If you have specialized tag parsing needs you can substitute the {#factory}
# object with your own by setting {Library.default_factory= Library.default_factory}
# to a new class with its own parsing methods before running YARD. This is useful
# if you want to change the syntax of existing tags (@see, @since, etc.)
#
# @example Defining a custom tag
# define_tag "Parameter", :param, :with_types_and_name
# define_tag "Author", :author
# @example Defining a custom directive
# define_directive :method, :with_title_and_text, MethodDirective
# @see DefaultFactory
# @see define_tag
# @see define_directive
# @see Directive
class Library
class << self
# @return [SymbolHash{Symbol=>String}] the map of tag names and their
# respective display labels.
attr_reader :labels
# @!attribute instance
# @return [Library] the main Library instance object.
def instance
@instance ||= new
end
# @!attribute default_factory
# Replace the factory object responsible for parsing tags by setting
# this to an object (or class) that responds to +parse_TAGNAME+ methods
# where +TAGNAME+ is the name of the tag.
#
# You should set this value before performing any source parsing with
# YARD, otherwise your factory class will not be used.
#
# @example
# YARD::Tags::Library.default_factory = MyFactory
#
# @see DefaultFactory
def default_factory
@default_factory ||= DefaultFactory.new
end
def default_factory=(factory)
@default_factory = factory.is_a?(Class) ? factory.new : factory
end
# Returns the factory method used to parse the tag text for a specific tag
#
# @param [Symbol] tag the tag name
# @return [Symbol] the factory method name for the tag
# @return [Class,Symbol] the Tag class to use to parse the tag
# or the method to call on the factory class
# @return [nil] if the tag is freeform text
# @since 0.6.0
def factory_method_for(tag)
@factory_methods[tag]
end
# Returns the factory method used to parse the tag text for a specific
# directive
#
# @param [Symbol] directive the directive name
# @return [Symbol] the factory method name for the tag
# @return [Class,Symbol] the Tag class to use to parse the tag or
# the methods to call on the factory class
# @return [nil] if the tag is freeform text
# @since 0.8.0
def factory_method_for_directive(directive)
@directive_factory_classes[directive]
end
# Sets the list of tags to display when rendering templates. The order of
# tags in the list is also significant, as it represents the order that
# tags are displayed in templates.
#
# You can use the {Array#place} to insert new tags to be displayed in
# the templates at specific positions:
#
# Library.visible_tags.place(:mytag).before(:return)
#
# @return [Array] a list of ordered tags
# @since 0.6.0
attr_accessor :visible_tags
# Sets the list of tags that should apply to any children inside the
# namespace they are defined in. For instance, a "@since" tag should
# apply to all methods inside a module it is defined in. Transitive
# tags can be overridden by directly defining a tag on the child object.
#
# @return [Array] a list of transitive tags
# @since 0.6.0
attr_accessor :transitive_tags
# Sorts the labels lexically by their label name, often used when displaying
# the tags.
#
# @return [Array, String] the sorted labels as an array of the tag name and label
def sorted_labels
labels.sort_by {|a| a.last.downcase }
end
# Convenience method to define a new tag using one of {Tag}'s factory methods, or the
# regular {DefaultFactory#parse_tag} factory method if none is supplied.
#
# @!macro [attach] yard.tag
# @!method $2_tag
# @!visibility private
# @yard.tag $2 [$3] $1
# @param [#to_s] label the label used when displaying the tag in templates
# @param [#to_s] tag the tag name to create
# @param [#to_s, Class] meth the {Tag} factory method to call when
# creating the tag or the name of the class to directly create a tag for
def define_tag(label, tag, meth = nil)
tag_meth = tag_method_name(tag)
if meth.is_a?(Class) && Tag > meth
class_eval(<<-eof, __FILE__, __LINE__ + 1)
def #{tag_meth}(text)
#{meth}.new(#{tag.inspect}, text)
end
eof
else
class_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef #{tag_meth}; rescue NameError; end
def #{tag_meth}(text)
send_to_factory(#{tag.inspect}, #{meth.inspect}, text)
end
eof
end
@labels ||= SymbolHash.new(false)
@labels.update(tag => label)
@factory_methods ||= SymbolHash.new(false)
@factory_methods.update(tag => meth)
tag
end
# @macro [attach] yard.directive
# @!method $1_directive
# @!visibility private
# @yard.directive $1 [$2] $-1
# @overload define_directive(tag, tag_meth = nil, directive_class)
# Convenience method to define a new directive using a {Tag} factory
# method and {Directive} subclass that implements the directive
# callbacks.
#
# @param [#to_s] tag the tag name of the directive
# @param [#to_s] tag_meth the tag factory method to use when
# parsing tag information
# @param [Class] the directive class that implements the
# directive behaviour
# @see define_tag
def define_directive(tag, tag_meth = nil, directive_class = nil)
directive_meth = directive_method_name(tag)
if directive_class.nil?
directive_class = tag_meth
tag_meth = nil
end
class_eval <<-eof, __FILE__, __LINE__
def #{directive_meth}(tag, parser)
directive_call(tag, parser)
end
eof
@factory_methods ||= SymbolHash.new(false)
@factory_methods.update(tag => tag_meth)
@directive_factory_classes ||= SymbolHash.new(false)
@directive_factory_classes.update(tag => directive_class)
tag
end
def tag_method_name(tag_name)
tag_or_directive_method_name(tag_name)
end
def directive_method_name(tag_name)
tag_or_directive_method_name(tag_name, 'directive')
end
private
def tag_or_directive_method_name(tag_name, type = 'tag')
"#{tag_name.to_s.tr('.', '_')}_#{type}"
end
end
private
def send_to_factory(tag_name, meth, text)
meth = meth.to_s
send_name = "parse_tag" + (meth.empty? ? "" : "_" + meth)
if @factory.respond_to?(send_name)
@factory.send(send_name, tag_name, text)
else
raise NoMethodError, "Factory #{@factory.class_name} does not implement factory method :#{meth}."
end
end
# @return [Directive]
def directive_call(tag, parser)
meth = self.class.factory_method_for_directive(tag.tag_name)
if meth <= Directive
meth = meth.new(tag, parser)
meth.call
meth
else
meth.call(tag, parser)
end
end
public
# A factory class to handle parsing of tags, defaults to {default_factory}
attr_accessor :factory
def initialize(factory = Library.default_factory)
self.factory = factory
end
# @param [#to_s] tag_name the name of the tag to look for
# @return [Boolean] whether a tag by the given name is registered in
# the library.
def has_tag?(tag_name)
tag_name && respond_to?(self.class.tag_method_name(tag_name))
end
# Creates a new {Tag} object with a given tag name and data
# @return [Tag] the newly created tag object
def tag_create(tag_name, tag_buf)
send(self.class.tag_method_name(tag_name), tag_buf)
end
# @param [#to_s] tag_name the name of the tag to look for
# @return [Boolean] whether a directive by the given name is registered in
# the library.
def has_directive?(tag_name)
tag_name && respond_to?(self.class.directive_method_name(tag_name))
end
# Creates a new directive with tag information and a docstring parser
# object.
# @param [String] tag_name the name of the tag
# @param [String] tag_buf the tag data
# @param [DocstringParser] parser the parser object parsing the docstring
# @return [Directive] the newly created directive
def directive_create(tag_name, tag_buf, parser)
meth = self.class.factory_method_for(tag_name)
tag = send_to_factory(tag_name, meth, tag_buf)
meth = self.class.directive_method_name(tag_name)
send(meth, tag, parser)
end
# @!macro yard.tag.transitive
# @note This tag is *transitive*. If it is applied on a
# namespace (module or class), it will immediately be
# applied to all children objects of that namespace unless
# it is redefined on the child object.
# Marks a class/module/method as abstract with optional
# implementor information.
#
# @example
# # @abstract Subclass and override {#run} to implement
# # a custom Threadable class.
# class Runnable
# def run; raise NotImplementedError end
# end
define_tag "Abstract", :abstract
# Declares the API that the object belongs to. Does not display in
# output, but useful for performing queries (+yardoc --query+). Any text is
# allowable in this tag, and there are no predefined values.
#
# @!macro yard.tag.transitive
# @note The special name +@api private+ does display a notice in
# documentation if it is listed, letting users know that the
# method is not to be used by external components.
# @example
# class Post
# # @api private
# def reset_table!; table.flush end
# end
define_tag "API Visibility", :api
# Declares a readwrite attribute on a Struct or class.
#
# @note This attribute is only applicable on class docstrings
# @deprecated Use the more powerful {tag:!attribute} directive instead.
# @example
# # @attr [String] name the name of the structure
# # @attr [Fixnum] size the size of the structure
# class MyStruct < Struct; end
define_tag "Attribute", :attr, :with_types_and_name
# Declares a readonly attribute on a Struct or class.
#
# @note This attribute is only applicable on class docstrings
# @deprecated Use the more powerful {tag:!attribute} directive instead.
# @example
# # @attr_reader [String] name the name of the structure
# # @attr_reader [Fixnum] size the size of the structure
# class MyStruct < Struct; end
define_tag "Attribute Getter", :attr_reader, :with_types_and_name
# Declares a writeonly attribute on a Struct or class.
#
# @note This attribute is only applicable on class docstrings
# @deprecated Use the more powerful {tag:!attribute} directive instead.
# @example
# # @attr_reader [String] name the name of the structure
# # @attr_reader [Fixnum] size the size of the structure
# class MyStruct < Struct; end
define_tag "Attribute Setter", :attr_writer, :with_types_and_name
# List the author or authors of a class, module, or method.
#
# @example
# # @author Foo Bar
# class MyClass; end
define_tag "Author", :author
# Marks a method/class as deprecated with an optional description.
# The description should be used to inform users of the recommended
# migration path, and/or any useful information about why the object
# was marked as deprecated.
#
# @example Deprecate a method with a replacement API
# # @deprecated Use {#bar} instead.
# def foo; end
# @example Deprecate a method with no replacement
# class Thread
# # @deprecated Exiting a thread in this way is not reliable and
# # can cause a program crash.
# def kill; end
# end
define_tag "Deprecated", :deprecated
# Show an example snippet of code for an object. The first line
# is an optional title.
#
# @example
# # @example Reverse a String
# # "mystring".reverse #=> "gnirtsym"
# def reverse; end
# @yard.signature Optional title
# Code block
define_tag "Example", :example, :with_title_and_text
# Adds an emphasized note at the top of the docstring for the object
#
# @example
# # @note This method should only be used in outer space.
# def eject; end
# @see tag:todo
define_tag "Note", :note
# Describe an options hash in a method. The tag takes the
# name of the options parameter first, followed by optional types,
# the option key name, a default value for the key and a
# description of the option. The default value should be placed within
# parentheses and is optional (can be omitted).
#
# Note that a +@param+ tag need not be defined for the options
# hash itself, though it is useful to do so for completeness.
#
# @note For keyword parameters, use +@param+, not +@option+.
#
# @example
# # @param [Hash] opts the options to create a message with.
# # @option opts [String] :subject The subject
# # @option opts [String] :from ('nobody') From address
# # @option opts [String] :to Recipient email
# # @option opts [String] :body ('') The email's body
# def send_email(opts = {}) end
# @yard.signature name [Types] option_key (default_value) description
define_tag "Options Hash", :option, :with_options
# Describe that your method can be used in various
# contexts with various parameters or return types. The first
# line should declare the new method signature, and the following
# indented tag data will be a new documentation string with its
# own tags adding metadata for such an overload.
#
# @example
# # @overload set(key, value)
# # Sets a value on key
# # @param key [Symbol] describe key param
# # @param value [Object] describe value param
# # @overload set(value)
# # Sets a value on the default key +:foo+
# # @param value [Object] describe value param
# def set(*args) end
# @yard.signature method_signature(parameters)
# Indented docstring for overload method
define_tag "Overloads", :overload, OverloadTag
# Documents a single method parameter (either regular or keyword) with a given name, type
# and optional description.
#
# @example
# # @param url [String] the URL of the page to download
# # @param directory [String] the name of the directory to save to
# def load_page(url, directory: 'pages') end
define_tag "Parameters", :param, :with_types_and_name
# Declares that the _logical_ visibility of an object is private.
# In other words, it specifies that this method should be marked
# private but cannot due to Ruby's visibility restrictions. This
# exists for classes, modules and constants that do not obey Ruby's
# visibility rules. For instance, an inner class might be considered
# "private", though Ruby would make no such distinction.
#
# This tag is meant to be used in conjunction with the +--no-private+
# command-line option, and is required to actually remove these objects
# from documentation output. See {file:README.md} for more information on
# switches.
#
# If you simply want to set the API visibility of a method, you should
# look at the {tag:api} tag instead.
#
# @note This method is not recommended for hiding undocumented or
# "unimportant" methods. This tag should only be used to mark objects
# private when Ruby visibility rules cannot do so. In Ruby 1.9.3, you
# can use +private_constant+ to declare constants (like classes or
# modules) as private, and should be used instead of +@private+.
# @macro yard.tag.transitive
# @example
# # @private
# class InteralImplementation; end
# @see tag:api
# @yard.signature
define_tag "Private", :private
# Describes that a method may raise a given exception, with
# an optional description of what it may mean.
#
# @example
# # @raise [AccountBalanceError] if the account does not have
# # sufficient funds to perform the transaction
# def withdraw(amount) end
define_tag "Raises", :raise, :with_types
# Describes the return value (and type or types) of a method.
# You can list multiple return tags for a method in the case
# where a method has distinct return cases. In this case, each
# case should begin with "if ...".
#
# @example A regular return value
# # @return [Fixnum] the size of the file
# def size; @file.size end
# @example A method returns an Array or a single object
# # @return [String] if a single object was returned
# # from the database.
# # @return [Array] if multiple objects were
# # returned.
# def find(query) end
define_tag "Returns", :return, :with_types
# "See Also" references for an object. Accepts URLs or
# other code objects with an optional description at the end.
# Note that the URL or object will be automatically linked by
# YARD and does not need to be formatted with markup.
#
# @example
# # Synchronizes system time using NTP.
# # @see http://ntp.org/documentation.html NTP Documentation
# # @see NTPHelperMethods
# class NTPUpdater; end
define_tag "See Also", :see, :with_name
# Lists the version that the object was first added.
#
# @!macro yard.tag.transitive
# @example
# # @since 1.2.4
# def clear_routes; end
define_tag "Since", :since
# Marks a TODO note in the object being documented.
# For reference, objects with TODO items can be enumerated
# from the command line with a simple command:
#
# !!!sh
# mocker$ yard list --query '@todo'
# lib/mocker/mocker.rb:15: Mocker
# lib/mocker/report/html.rb:5: Mocker::Report::Html
#
# YARD can also be used to enumerate the TODO items from
# a short script:
#
# !!!ruby
# require 'yard'
# YARD::Registry.load!.all.each do |o|
# puts o.tag(:todo).text if o.tag(:todo)
# end
#
# @example
# # @todo Add support for Jabberwocky service.
# # There is an open source Jabberwocky library available
# # at http://jbrwcky.org that can be easily integrated.
# class Wonderlander; end
# @see tag:note
define_tag "Todo Item", :todo
# Lists the version of a class, module or method. This is
# similar to a library version, but at finer granularity.
# In some cases, version of specific modules, classes, methods
# or generalized components might change independently between
# releases. A version tag is used to infer the API compatibility
# of a specific object.
#
# @example
# # The public REST API for http://jbrwcky.org
# # @version 2.0
# class JabberwockyAPI; end
define_tag "Version", :version
# Describes what a method might yield to a given block.
# The types specifier list should not list types, but names
# of the parameters yielded to the block. If you define
# parameters with +@yieldparam+, you do not need to define
# the parameters in the type specification of +@yield+ as
# well.
#
# @example
# # For a block {|a,b,c| ... }
# # @yield [a, b, c] Gives 3 random numbers to the block
# def provide3values(&block) yield(42, 42, 42) end
# @see tag:yieldparam
# @see tag:yieldreturn
# @yard.signature [parameters] description
define_tag "Yields", :yield, :with_types
# Defines a parameter yielded by a block. If you define the
# parameters with +@yieldparam+, you do not need to define
# them via +@yield+ as well.
#
# @example
# # @yieldparam [String] name the name that is yielded
# def with_name(name) yield(name) end
define_tag "Yield Parameters", :yieldparam, :with_types_and_name
# Documents the value and type that the block is expected
# to return to the method.
#
# @example
# # @yieldreturn [Fixnum] the number to add 5 to.
# def add5_block(&block) 5 + yield end
# @see tag:return
define_tag "Yield Returns", :yieldreturn, :with_types
# @yard.signature [r | w | rw] attribute_name
# Indented attribute docstring
define_directive :attribute, :with_types_and_title, AttributeDirective
# @yard.signature
define_directive :endgroup, EndGroupDirective
define_directive :group, GroupDirective
# @yard.signature [attach | new] optional_name
# Optional macro expansion data
define_directive :macro, :with_types_and_title, MacroDirective
# @yard.signature method_signature(parameters)
# Indented method docstring
define_directive :method, :with_title_and_text, MethodDirective
# @yard.signature [language] code
define_directive :parse, :with_types, ParseDirective
# Sets the scope of a DSL method. Only applicable to DSL method
# calls. Acceptable values are 'class' or 'instance'
# @yard.signature class | instance
define_directive :scope, ScopeDirective
# Sets the visibility of a DSL method. Only applicable to
# DSL method calls. Acceptable values are public, protected, or private.
# @yard.signature public | protected | private
define_directive :visibility, VisibilityDirective
self.visible_tags = [:abstract, :deprecated, :note, :todo, :example, :overload,
:param, :option, :yield, :yieldparam, :yieldreturn, :return, :raise,
:see, :author, :since, :version]
self.transitive_tags = [:since, :api]
end
end
end
yard-0.9.7/lib/yard/tags/ref_tag_list.rb 0000644 0000041 0000041 00000001170 13035234564 020154 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
class RefTagList
attr_accessor :owner, :tag_name, :name
def initialize(tag_name, owner, name = nil)
@owner = CodeObjects::Proxy === owner ? owner : P(owner)
@tag_name = tag_name.to_s
@name = name
end
def tags
if owner.is_a?(CodeObjects::Base)
o = owner.tags(tag_name)
o = o.select {|t| t.name.to_s == name.to_s } if name
o.each do |t|
t.extend(RefTag)
t.owner = owner
end
o
else
[]
end
end
end
end
end
yard-0.9.7/lib/yard/tags/overload_tag.rb 0000644 0000041 0000041 00000003775 13035234564 020175 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
class OverloadTag < Tag
attr_reader :signature, :parameters, :docstring
def initialize(tag_name, text)
super(tag_name, nil)
parse_tag(text)
parse_signature
end
def tag(name) docstring.tag(name) end
def tags(name = nil) docstring.tags(name) end
def has_tag?(name) docstring.has_tag?(name) end
def object=(value)
super(value)
docstring.object = value
docstring.tags.each {|tag| tag.object = value }
end
def name(prefix = false)
return @name unless prefix
object.scope == :class ? @name.to_s : "#{object.send(:sep)}#{@name}"
end
def method_missing(*args, &block)
object.send(*args, &block)
end
def type
object.type
end
def is_a?(other)
object.is_a?(other) || self.class >= other.class || false
end
alias kind_of? is_a?
private
def parse_tag(text)
@signature, text = *text.split(/\r?\n/, 2)
@signature.strip!
text ||= String.new("")
numspaces = text[/\A(\s*)/, 1].length
text.gsub!(/^[ \t]{#{numspaces}}/, '')
text.strip!
@docstring = Docstring.new(text, nil)
end
def parse_signature
if signature =~ /^(?:def\s)?\s*(#{CodeObjects::METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
meth = $1
args = $2
meth.gsub!(/\s+/, '')
# FIXME: refactor this code to not make use of the Handlers::Base class (tokval_list should be moved)
toks = YARD::Parser::Ruby::Legacy::TokenList.new(args)
args = YARD::Handlers::Ruby::Legacy::Base.new(nil, nil).send(:tokval_list, toks, :all)
args = args.map do |a|
k, v = *a.split(/:|=/, 2)
[k.strip.to_s + (a[k.size, 1] == ':' ? ':' : ''), (v ? v.strip : nil)]
end if args
@name = meth.to_sym
@parameters = args
end
end
end
end
end
yard-0.9.7/lib/yard/tags/default_factory.rb 0000644 0000041 0000041 00000016164 13035234564 020676 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Tags
class DefaultFactory
TYPELIST_OPENING_CHARS = '[({<'
TYPELIST_CLOSING_CHARS = '>})]'
# Parses tag text and creates a new tag with descriptive text
#
# @param tag_name the name of the tag to parse
# @param [String] text the raw tag text
# @return [Tag] a tag object with the tag_name and text values filled
def parse_tag(tag_name, text)
Tag.new(tag_name, text.strip)
end
# Parses tag text and creates a new tag with a key name and descriptive text
#
# @param tag_name the name of the tag to parse
# @param [String] text the raw tag text
# @return [Tag] a tag object with the tag_name, name and text values filled
def parse_tag_with_name(tag_name, text)
name, text = *extract_name_from_text(text)
Tag.new(tag_name, text, nil, name)
end
# Parses tag text and creates a new tag with formally declared types and
# descriptive text
#
# @param tag_name the name of the tag to parse
# @param [String] text the raw tag text
# @return [Tag] a tag object with the tag_name, types and text values filled
def parse_tag_with_types(tag_name, text)
name, types, text = *extract_types_and_name_from_text(text)
raise TagFormatError, "cannot specify a name before type list for '@#{tag_name}'" if name
Tag.new(tag_name, text, types)
end
# Parses tag text and creates a new tag with formally declared types, a key
# name and descriptive text
#
# @param tag_name the name of the tag to parse
# @param [String] text the raw tag text
# @return [Tag] a tag object with the tag_name, name, types and text values filled
def parse_tag_with_types_and_name(tag_name, text)
name, types, text = *extract_types_and_name_from_text(text)
name, text = *extract_name_from_text(text) unless name
Tag.new(tag_name, text, types, name)
end
# Parses tag text and creates a new tag with formally declared types, a title
# on the first line and descriptive text
#
# @param tag_name the name of the tag to parse
# @param [String] text the raw tag text
# @return [Tag] a tag object with the tag_name, name, types and text values filled
def parse_tag_with_types_and_title(tag_name, text)
name, types, text = *extract_types_and_name_from_text_unstripped(text)
if name
title = name
desc = text
else
title, desc = *extract_title_and_desc_from_text(text)
end
Tag.new(tag_name, desc, types, title)
rescue TagFormatError
Tag.new(tag_name, '', types, nil)
end
def parse_tag_with_title_and_text(tag_name, text)
title, desc = *extract_title_and_desc_from_text(text)
Tag.new(tag_name, desc, nil, title)
end
def parse_tag_with_types_name_and_default(tag_name, text)
# Can't allow () in a default tag, otherwise the grammar is too ambiguous when types is omitted.
open = TYPELIST_OPENING_CHARS.delete('(')
close = TYPELIST_CLOSING_CHARS.delete(')')
name, types, text = *extract_types_and_name_from_text(text, open, close)
name, text = *extract_name_from_text(text) unless name
if text && text.start_with?('(')
_, default, text = *extract_types_and_name_from_text(text, '(', ')')
DefaultTag.new(tag_name, text, types, name, default)
else
DefaultTag.new(tag_name, text, types, name, nil)
end
end
def parse_tag_with_options(tag_name, text)
name, text = *extract_name_from_text(text)
OptionTag.new(tag_name, name, parse_tag_with_types_name_and_default(tag_name, text))
end
private
# Extracts the name from raw tag text returning the name and remaining value
#
# @param [String] text the raw tag text
# @return [Array] an array holding the name as the first element and the
# value as the second element
def extract_name_from_text(text)
text.strip.split(/\s+/, 2)
end
def extract_title_and_desc_from_text(text)
raise TagFormatError if text.nil? || text.empty?
title = nil
desc = nil
if text =~ /\A[ \t]\n/
desc = text
else
text = text.split(/\r?\n/)
title = text.shift.squeeze(' ').strip
desc = text.join("\n")
end
[title, desc]
end
# Parses a [], <>, {} or () block at the beginning of a line of text
# into a list of comma delimited values.
#
# @example
# obj.parse_types('[String, Array, nil]') # => [nil, ['String', 'Array', 'nil'], ""]
# obj.parse_types('b A string') # => ['b', ['String'], 'A string']
#
# @return [Array(String, Array, String)] the text before the type
# list (or nil), followed by the type list parsed into an array of
# strings, followed by the text following the type list.
def extract_types_and_name_from_text(text, opening_types = TYPELIST_OPENING_CHARS, closing_types = TYPELIST_CLOSING_CHARS)
before, list, text = *extract_types_and_name_from_text_unstripped(text, opening_types, closing_types)
if list.nil?
[nil, nil, text.strip]
else
[before ? before.strip : nil, list.map(&:strip), text.strip]
end
end
def extract_types_and_name_from_text_unstripped(text, opening_types = TYPELIST_OPENING_CHARS, closing_types = TYPELIST_CLOSING_CHARS)
e = 0
before = String.new("")
list = [String.new("")]
level = 0
seen_space = false
i = 0
last_seen = ''
while i < text.length
c = text[i, 1]
if (c == '"' || c == "'") && text[i..-1] =~ /#{c}.+?#{c}/
list.last << $&
i += $&.length
next
end
if level > 0 && c == '#' && text[i + 1..-1] =~ CodeObjects::METHODNAMEMATCH
list.last << c + $&
i += $&.length + 1
next
elsif opening_types.include?(c)
list.last << c if level > 0
level += 1
elsif closing_types.include?(c)
level -= 1 unless last_seen == '=' && c == '>'
break e = i if level == 0
list.last << c
elsif c == ',' && level == 1
list.push String.new("")
elsif c =~ /\S/ && level == 0
break e = i if seen_space && list == ['']
before << c
elsif c =~ /[ \t]/ && level == 0 && !before.empty?
seen_space = true
elsif level >= 1
list.last << c
elsif level == 0 && c == "\n"
break e = i
end
last_seen = c
i += 1
end
before = before.empty? ? nil : before
if list.size == 1 && list.first == ''
[nil, nil, text]
else
[before, list, text[(e + 1)..-1]]
end
end
end
end
end
yard-0.9.7/lib/yard/registry_resolver.rb 0000644 0000041 0000041 00000014130 13035234564 020345 0 ustar www-data www-data # frozen_string_literal: true
module YARD
# Handles all logic for complex lexical and inherited object resolution.
# Used by {Registry.resolve}, so there is no need to use this class
# directly.
#
# @see Registry.resolve
# @since 0.9.1
class RegistryResolver
include CodeObjects::NamespaceMapper
# Creates a new resolver object for a registry.
#
# @param registry [Registry] only set this if customizing the registry
# object
def initialize(registry = Registry)
@registry = registry
@default_sep = nil
end
# Performs a lookup on a given path in the registry. Resolution will occur
# in a similar way to standard Ruby identifier resolution, doing lexical
# lookup, as well as (optionally) through the inheritance chain. A proxy
# object can be returned if the lookup fails for future resolution. The
# proxy will be type hinted with the +type+ used in the original lookup.
#
# @option opts namespace [CodeObjects::Base, :root, nil] (nil) the namespace
# object to start searching from. If root or nil is provided, {Registry.root}
# is assumed.
# @option opts inheritance [Boolean] (false) whether to perform lookups through
# the inheritance chain (includes mixins)
# @option opts proxy_fallback [Boolean] (false) when true, a proxy is returned
# if no match is found
# @option opts type [Symbol] (nil) an optional type hint for the resolver
# to consider when performing a lookup. If a type is provided and the
# resolved object's type does not match the hint, the object is discarded.
# @return [CodeObjects::Base, CodeObjects::Proxy, nil] the first object
# that matches the path lookup. If proxy_fallback is provided, a proxy
# object will be returned in the event of no match, otherwise nil will
# be returned.
# @example A lookup from root
# resolver.lookup_by_path("A::B::C")
# @example A lookup from the A::B namespace
# resolver.lookup_by_path("C", namespace: P("A::B"))
# @example A lookup on a method through the inheritance tree
# resolver.lookup_by_math("A::B#foo", inheritance: true)
def lookup_by_path(path, opts = {})
path = path.to_s
namespace = opts[:namespace]
inheritance = opts[:inheritance] || false
proxy_fallback = opts[:proxy_fallback] || false
type = opts[:type]
if namespace.is_a?(CodeObjects::Proxy)
return proxy_fallback ? CodeObjects::Proxy.new(namespace, path, type) : nil
end
if namespace == :root || !namespace
namespace = @registry.root
else
namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
end
orignamespace = namespace
if path =~ /\A#{default_separator}/
path = $'
namespace = @registry.root
orignamespace = @registry.root
end
resolved = nil
lexical_lookup = 0
while namespace && !resolved
resolved = lookup_path_direct(namespace, path, type)
resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
break if resolved
namespace = namespace.parent
lexical_lookup += 1
end
# method objects cannot be resolved through lexical lookup by more than 1 ns
if lexical_lookup > 1 && resolved.is_a?(CodeObjects::MethodObject)
resolved = nil
end
if proxy_fallback
resolved ||= CodeObjects::Proxy.new(orignamespace, path, type)
end
resolved
end
private
# return [Boolean] if the obj's type matches the provided type.
def validate(obj, type)
!type || (obj && obj.type == type) ? obj : nil
end
# Performs a lexical lookup from a namespace for a path and a type hint.
def lookup_path_direct(namespace, path, type)
result = namespace.root? && validate(@registry.at(path), type)
return result if result
if path =~ /\A(#{separators_match})/
return validate(@registry.at(namespace.path + path), type)
end
separators.each do |sep|
result = validate(@registry.at(namespace.path + sep + path), type)
return result if result
end
nil
end
# Performs a lookup through the inheritance chain on a path with a type hint.
def lookup_path_inherited(namespace, path, type)
resolved = nil
last_obj = namespace
scopes = []
last_sep = nil
pos = 0
if path =~ /\A(#{separators_match})/
last_sep = $1
path = $'
end
path.scan(/(.+?)(#{separators_match}|$)/).each do |part, sep|
cur_obj = nil
pos += "#{part}#{sep}".length
parsed_end = pos == path.length
if !last_obj || (!parsed_end && !last_obj.is_a?(CodeObjects::NamespaceObject))
break # can't continue
end
collect_namespaces(last_obj).each do |ns|
next if ns.is_a?(CodeObjects::Proxy)
found = nil
search_seps = []
scopes.each do |scope|
search_seps += separators_for_type(scope)
end
if search_seps.empty?
search_seps =
if ns.type == :root
[""]
elsif last_sep.nil?
separators
else
[@default_sep]
end
end
([last_sep] | search_seps).compact.each do |search_sep|
found = @registry.at(ns.path + search_sep.to_s + part)
break if found
end
break cur_obj = found if found
end
last_sep = sep
scopes = types_for_separator(sep) || []
last_obj = cur_obj
resolved = cur_obj if parsed_end && cur_obj && (type.nil? || type == cur_obj.type)
end
resolved
end
# Collects and returns all inherited namespaces for a given object
def collect_namespaces(object)
return [] unless object.respond_to?(:inheritance_tree)
nss = object.inheritance_tree(true)
if object.respond_to?(:superclass)
nss |= [P('Object')] if object.superclass != P('BasicObject')
nss |= [P('BasicObject')]
end
nss
end
end
end
yard-0.9.7/lib/yard/registry_store.rb 0000644 0000041 0000041 00000023017 13035234564 017644 0 ustar www-data www-data # frozen_string_literal: true
require 'fileutils'
module YARD
# The data store for the {Registry}.
#
# @see Registry
# @see Serializers::YardocSerializer
class RegistryStore
# @deprecated The registry no longer tracks proxy types
attr_reader :proxy_types
attr_reader :file, :checksums
def initialize
@file = nil
@checksums = {}
@store = {}
@proxy_types = {}
@object_types = {:root => [:root]}
@notfound = {}
@loaded_objects = 0
@available_objects = 0
@locales = {}
@store[:root] = CodeObjects::RootObject.allocate
@store[:root].send(:initialize, nil, :root)
end
# Gets a {CodeObjects::Base} from the store
#
# @param [String, Symbol] key the path name of the object to look for.
# If it is empty or :root, returns the {#root} object.
# @return [CodeObjects::Base, nil] a code object or nil if none is found
def get(key)
key = :root if key == ''
key = key.to_sym
return @store[key] if @store[key]
return if @loaded_objects >= @available_objects
# check disk
return if @notfound[key]
obj = @serializer.deserialize(key)
if obj
@loaded_objects += 1
put(key, obj)
else
@notfound[key] = true
nil
end
end
# Associates an object with a path
# @param [String, Symbol] key the path name (:root or '' for root object)
# @param [CodeObjects::Base] value the object to store
# @return [CodeObjects::Base] returns +value+
def put(key, value)
if key == ''
@object_types[:root] = [:root]
@store[:root] = value
else
@notfound.delete(key.to_sym)
(@object_types[value.type] ||= []) << key.to_s
if @store[key.to_sym]
@object_types[@store[key.to_sym].type].delete(key.to_s)
end
@store[key.to_sym] = value
end
end
alias [] get
alias []= put
# Deletes an object at a given path
# @param [#to_sym] key the key to delete
# @return [void]
def delete(key) @store.delete(key.to_sym) end
# Gets all path names from the store. Loads the entire database
# if +reload+ is +true+
#
# @param [Boolean] reload if false, does not load the entire database
# before a lookup.
# @return [Array] the path names of all the code objects
def keys(reload = false) load_all if reload; @store.keys end
# Gets all code objects from the store. Loads the entire database
# if +reload+ is +true+
#
# @param [Boolean] reload if false, does not load the entire database
# before a lookup.
# @return [Array] all the code objects
def values(reload = false) load_all if reload; @store.values end
# @param [Symbol] type the type to look for
# @return [Array] a list of object paths with a given
# {CodeObjects::Base#type}
# @since 0.8.0
def paths_for_type(type, reload = false)
load_all if reload
@object_types[type] || []
end
# @param [Symbol] type the type to look for
# @return [Array] a list of objects with a given
# {CodeObjects::Base#type}
# @since 0.8.0
def values_for_type(type, reload = false)
load_all if reload
paths_for_type(type).map {|t| @store[t.to_sym] }
end
# @return [CodeObjects::RootObject] the root object
def root; @store[:root] end
# @param [String] name the locale name.
# @return [I18n::Locale] the locale object for +name+.
# @since 0.8.3
def locale(name)
@locales[name] ||= load_locale(name)
end
# @param [String, nil] file the name of the yardoc db to load
# @return [Boolean] whether the database was loaded
def load(file = nil)
@file = file
@store = {}
@proxy_types = {}
@object_types = {}
@notfound = {}
@serializer = Serializers::YardocSerializer.new(@file)
load_yardoc
end
# Loads the .yardoc file and loads all cached objects into memory
# automatically.
#
# @param [String, nil] file the name of the yardoc db to load
# @return [Boolean] whether the database was loaded
# @see #load_all
# @since 0.5.1
def load!(file = nil)
if load(file)
load_all
true
else
false
end
end
# Loads all cached objects into memory
# @return [void]
def load_all
return unless @file
return if @loaded_objects >= @available_objects
log.debug "Loading entire database: #{@file} ..."
objects = []
all_disk_objects.sort_by(&:size).each do |path|
obj = @serializer.deserialize(path, true)
objects << obj if obj
end
objects.each do |obj|
put(obj.path, obj)
end
@loaded_objects += objects.size
log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
end
# Saves the database to disk
# @param [Boolean] merge if true, merges the data in memory with the
# data on disk, otherwise the data on disk is deleted.
# @param [String, nil] file if supplied, the name of the file to save to
# @return [Boolean] whether the database was saved
def save(merge = true, file = nil)
if file && file != @file
@file = file
@serializer = Serializers::YardocSerializer.new(@file)
end
destroy unless merge
sdb = Registry.single_object_db
if sdb == true || sdb.nil?
@serializer.serialize(@store)
else
values(false).each do |object|
@serializer.serialize(object)
end
end
write_proxy_types
write_object_types
write_checksums
write_complete_lock
true
end
# (see Serializers::YardocSerializer#lock_for_writing)
# @param file [String] if supplied, the path to the database
def lock_for_writing(file = nil, &block)
Serializers::YardocSerializer.new(file || @file).lock_for_writing(&block)
end
# (see Serializers::YardocSerializer#locked_for_writing?)
# @param file [String] if supplied, the path to the database
def locked_for_writing?(file = nil)
Serializers::YardocSerializer.new(file || @file).locked_for_writing?
end
# Deletes the .yardoc database on disk
#
# @param [Boolean] force if force is not set to true, the file/directory
# will only be removed if it ends with .yardoc. This helps with
# cases where the directory might have been named incorrectly.
# @return [Boolean] true if the .yardoc database was deleted, false
# otherwise.
def destroy(force = false)
if (!force && file =~ /\.yardoc$/) || force
if File.file?(@file)
# Handle silent upgrade of old .yardoc format
File.unlink(@file)
elsif File.directory?(@file)
FileUtils.rm_rf(@file)
end
true
else
false
end
end
protected
def objects_path
@serializer.objects_path
end
# @deprecated The registry no longer tracks proxy types
def proxy_types_path
@serializer.proxy_types_path
end
def checksums_path
@serializer.checksums_path
end
def object_types_path
@serializer.object_types_path
end
def load_yardoc
return false unless @file
if File.directory?(@file) # new format
@loaded_objects = 0
@available_objects = all_disk_objects.size
load_proxy_types
load_checksums
load_root
load_object_types
true
elsif File.file?(@file) # old format
load_yardoc_old
true
else
false
end
end
private
def load_yardoc_old
@store, @proxy_types = *Marshal.load(File.read_binary(@file))
end
# @deprecated The registry no longer tracks proxy types
def load_proxy_types
return unless File.file?(proxy_types_path)
@proxy_types = Marshal.load(File.read_binary(proxy_types_path))
end
def load_object_types
if File.file?(object_types_path)
@object_types = Marshal.load(File.read_binary(object_types_path))
else # migrate db without object_types
values.each do |object|
(@object_types[object.type] ||= []) << object.path
end
end
end
def load_checksums
return unless File.file?(checksums_path)
lines = File.readlines(checksums_path).map do |line|
line.strip.split(/\s+/)
end
@checksums = Hash[lines]
end
def load_root
root = @serializer.deserialize('root')
return if root.nil?
@loaded_objects += 1
if root.is_a?(Hash) # single object db
log.debug "Loading single object DB from .yardoc"
@loaded_objects += (root.keys.size - 1)
@store = root
else # just the root object
@store[:root] = root
end
end
def load_locale(name)
locale = I18n::Locale.new(name)
locale.load(Registry.po_dir)
locale
end
def all_disk_objects
Dir.glob(File.join(objects_path, '**/*')).select {|f| File.file?(f) }
end
# @deprecated The registry no longer tracks proxy types
def write_proxy_types
File.open!(proxy_types_path, 'wb') {|f| f.write(Marshal.dump(@proxy_types)) }
end
def write_object_types
File.open!(object_types_path, 'wb') {|f| f.write(Marshal.dump(@object_types)) }
end
def write_checksums
File.open!(checksums_path, 'w') do |f|
@checksums.each {|k, v| f.puts("#{k} #{v}") }
end
end
def write_complete_lock
File.open!(@serializer.complete_lock_path, 'w') {}
end
end
end
yard-0.9.7/lib/yard/core_ext/ 0000755 0000041 0000041 00000000000 13035234564 016040 5 ustar www-data www-data yard-0.9.7/lib/yard/core_ext/string.rb 0000644 0000041 0000041 00000003136 13035234564 017676 0 ustar www-data www-data # frozen_string_literal: true
class String
# Splits text into tokens the way a shell would, handling quoted
# text as a single token. Use '\"' and "\'" to escape quotes and
# '\\' to escape a backslash.
#
# @return [Array] an array representing the tokens
def shell_split
out = [String.new("")]
state = :none
escape_next = false
quote = String.new("")
strip.split(//).each do |char|
case state
when :none, :space
case char
when /\s/
out << String.new("") unless state == :space
state = :space
escape_next = false
when "\\"
if escape_next
out.last << char
escape_next = false
else
escape_next = true
end
when '"', "'"
if escape_next
out.last << char
escape_next = false
else
state = char
quote = String.new("")
end
else
state = :none
out.last << char
escape_next = false
end
when '"', "'"
case char
when '"', "'"
if escape_next
quote << char
escape_next = false
elsif char == state
out.last << quote
state = :none
else
quote << char
end
when '\\'
if escape_next
quote << char
escape_next = false
else
escape_next = true
end
else
quote << char
escape_next = false
end
end
end
out
end
end
yard-0.9.7/lib/yard/core_ext/hash.rb 0000644 0000041 0000041 00000000524 13035234564 017311 0 ustar www-data www-data # frozen_string_literal: true
class Hash
class << self
def create(*args)
if args.first.is_a?(Array) && args.size == 1
obj = new
args.first.each {|k, v| obj[k] = v }
obj
else
create_186(*args)
end
end
alias create_186 []
alias [] create
end
end if RUBY_VERSION < "1.8.7"
yard-0.9.7/lib/yard/core_ext/module.rb 0000644 0000041 0000041 00000001030 13035234564 017644 0 ustar www-data www-data # frozen_string_literal: true
class Module
# Returns the class name of a full module namespace path
#
# @example
# module A::B::C; class_name end # => "C"
# @return [String] the last part of a module path
def class_name
name.split("::").last
end
# Returns the module namespace path minus the class/module name
#
# @example
# module A::B::C; namespace_name end # => "A::B"
# @return [String] the namespace minus the class/module name
def namespace_name
name.split("::")[0..-2].join("::")
end
end
yard-0.9.7/lib/yard/core_ext/file.rb 0000644 0000041 0000041 00000003632 13035234564 017310 0 ustar www-data www-data # frozen_string_literal: true
require 'fileutils'
class File
RELATIVE_PARENTDIR = '..'
RELATIVE_SAMEDIR = '.'
# @group Manipulating Paths
# Turns a path +to+ into a relative path from starting
# point +from+. The argument +from+ is assumed to be
# a filename. To treat it as a directory, make sure it
# ends in +File::SEPARATOR+ ('/' on UNIX filesystems).
#
# @param [String] from the starting filename
# (or directory with +from_isdir+ set to +true+).
# @param [String] to the final path that should be made relative.
# @return [String] the relative path from +from+ to +to+.
def self.relative_path(from, to)
from = expand_path(from).split(SEPARATOR)
to = expand_path(to).split(SEPARATOR)
from.length.times do
break if from[0] != to[0]
from.shift; to.shift
end
from.pop
join(*(from.map { RELATIVE_PARENTDIR } + to))
end
# Cleans a path by removing extraneous '..', '.' and '/' characters
#
# @example Clean a path
# File.cleanpath('a/b//./c/../e') # => "a/b/e"
# @param [String] path the path to clean
# @return [String] the sanitized path
def self.cleanpath(path)
path = path.split(SEPARATOR)
path = path.inject([]) do |acc, comp|
next acc if comp == RELATIVE_SAMEDIR
if comp == RELATIVE_PARENTDIR && !acc.empty? && acc.last != RELATIVE_PARENTDIR
acc.pop
next acc
end
acc << comp
end
File.join(*path)
end
# @group Reading Files
# Forces opening a file (for writing) by first creating the file's directory
# @param [String] file the filename to open
# @since 0.5.2
def self.open!(file, *args, &block)
dir = dirname(file)
FileUtils.mkdir_p(dir) unless directory?(dir)
open(file, *args, &block)
end
# Reads a file with binary encoding
# @return [String] the ascii-8bit encoded data
# @since 0.5.3
def self.read_binary(file)
File.open(file, 'rb', &:read)
end
end
yard-0.9.7/lib/yard/core_ext/insertion.rb 0000644 0000041 0000041 00000003757 13035234564 020413 0 ustar www-data www-data # frozen_string_literal: true
# The Insertion class inserts a value before or after another
# value in a list.
#
# @example
# Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]
class Insertion
# Creates an insertion object on a list with a value to be
# inserted. To finalize the insertion, call {#before} or
# {#after} on the object.
#
# @param [Array] list the list to perform the insertion on
# @param [Object] value the value to insert
def initialize(list, value)
@list = list
@values = (Array === value ? value : [value])
end
# Inserts the value before +val+
# @param [Object] val the object the value will be inserted before
# @param [Boolean] recursive look inside sublists
def before(val, recursive = false) insertion(val, 0, recursive) end
# Inserts the value after +val+.
#
# @example If subsections are ignored
# Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]
# @param [Object] val the object the value will be inserted after
# @param [Boolean] recursive look inside sublists
def after(val, recursive = false) insertion(val, 1, recursive) end
# Alias for {#before} with +recursive+ set to true
# @since 0.6.0
def before_any(val) insertion(val, 0, true) end
# Alias for {#after} with +recursive+ set to true
# @since 0.6.0
def after_any(val) insertion(val, 1, true) end
private
# This method performs the actual insertion
#
# @param [Object] val the value to insert
# @param [Fixnum] rel the relative index (0 or 1) of where the object
# should be placed
# @param [Boolean] recursive look inside sublists
# @param [Array] list the list to place objects into
def insertion(val, rel, recursive = false, list = @list)
if recursive
list.each do |item|
next unless item.is_a?(Array)
tmp = item.dup
insertion(val, rel, recursive, item)
return(list) unless item == tmp
end
end
index = list.index(val)
list[index + rel, 0] = @values if index
list
end
end
yard-0.9.7/lib/yard/core_ext/array.rb 0000644 0000041 0000041 00000001136 13035234564 017504 0 ustar www-data www-data # frozen_string_literal: true
class Array
# Places values before or after another object (by value) in
# an array. This is used in tandem with the before and after
# methods of the {Insertion} class.
#
# @example Places an item before another
# [1, 2, 3].place(4).before(3) # => [1, 2, 4, 3]
# @example Places an item after another
# [:a, :b, :c].place(:x).after(:a) # => [:a, :x, :b, :c]
# @param [Array] values value to insert
# @return [Insertion] an insertion object to
# @see Insertion#before
# @see Insertion#after
def place(*values) Insertion.new(self, values) end
end
yard-0.9.7/lib/yard/core_ext/symbol_hash.rb 0000644 0000041 0000041 00000004774 13035234564 020711 0 ustar www-data www-data # frozen_string_literal: true
# A subclass of Hash where all keys are converted into Symbols, and
# optionally, all String values are converted into Symbols.
class SymbolHash < Hash
# Creates a new SymbolHash object
#
# @param [Boolean] symbolize_value converts any String values into Symbols
# if this is set to +true+.
def initialize(symbolize_value = true)
@symbolize_value = symbolize_value
end
# @overload [](hash)
# Creates a SymbolHash object from an existing Hash
#
# @example
# SymbolHash['x' => 1, :y => 2] # => #
# @param [Hash] hash the hash object
# @return [SymbolHash] a new SymbolHash from a hash object
#
# @overload [](*list)
# Creates a SymbolHash from an even list of keys and values
#
# @example
# SymbolHash[key1, value1, key2, value2, ...]
# @param [Array] list an even list of key followed by value
# @return [SymbolHash] a new SymbolHash object
def self.[](*hsh)
obj = new
if hsh.size == 1 && hsh.first.is_a?(Hash)
hsh.first.each {|k, v| obj[k] = v }
else
0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n + 1] }
end
obj
end
# Assigns a value to a symbolized key
# @param [#to_sym] key the key
# @param [Object] value the value to be assigned. If this is a String and
# values are set to be symbolized, it will be converted into a Symbol.
def []=(key, value)
super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value)
end
# Accessed a symbolized key
# @param [#to_sym] key the key to access
# @return [Object] the value associated with the key
def [](key) super(key.to_sym) end
# Deleted a key and value associated with it
# @param [#to_sym] key the key to delete
# @return [void]
def delete(key) super(key.to_sym) end
# Tests if a symbolized key exists
# @param [#to_sym] key the key to test
# @return [Boolean] whether the key exists
def key?(key) super(key.to_sym) end
alias has_key? key?
# Updates the object with the contents of another Hash object.
# This method modifies the original SymbolHash object
#
# @param [Hash] hash the hash object to copy the values from
# @return [SymbolHash] self
def update(hash) hash.each {|k, v| self[k] = v }; self end
alias merge! update
# Merges the contents of another hash into a new SymbolHash object
#
# @param [Hash] hash the hash of objects to copy
# @return [SymbolHash] a new SymbolHash containing the merged data
def merge(hash) dup.merge!(hash) end
end
yard-0.9.7/lib/yard/handlers/ 0000755 0000041 0000041 00000000000 13035234564 016030 5 ustar www-data www-data yard-0.9.7/lib/yard/handlers/c/ 0000755 0000041 0000041 00000000000 13035234564 016252 5 ustar www-data www-data yard-0.9.7/lib/yard/handlers/c/path_handler.rb 0000644 0000041 0000041 00000000451 13035234564 021230 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::PathHandler < YARD::Handlers::C::Base
MATCH = /([\w\.]+)\s* = \s*rb_path2class\s*\(\s*"([\w:]+)"\)/mx
handles MATCH
process do
statement.source.scan(MATCH) do |var_name, path|
namespaces[var_name] = P(path)
end
end
end
yard-0.9.7/lib/yard/handlers/c/mixin_handler.rb 0000644 0000041 0000041 00000001146 13035234564 021422 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::MixinHandler < YARD::Handlers::C::Base
MATCH = /rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/
handles MATCH
statement_class BodyStatement
process do
statement.source.scan(MATCH) do |klass_var, mixin_var|
namespace = namespace_for_variable(klass_var)
ensure_loaded!(namespace)
var = namespace_for_variable(mixin_var)
if var
namespace.mixins(:instance) << var
else
raise YARD::Parser::UndocumentableError,
"CRuby mixin for unrecognized variable '#{mixin_var}'"
end
end
end
end
yard-0.9.7/lib/yard/handlers/c/attribute_handler.rb 0000644 0000041 0000041 00000000710 13035234564 022275 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::AttributeHandler < YARD::Handlers::C::Base
MATCH = /rb_define_attr\s*\(\s*([\w\.]+),\s*"([^"]+)",\s*(0|1)\s*,\s*(0|1)\s*\)/
handles MATCH
process do
return if ToplevelStatement == statement
return if Comment === statement && statement.type != :multi
statement.source.scan(MATCH) do |var_name, name, read, write|
handle_attribute(var_name, name, read, write)
end
end
end
yard-0.9.7/lib/yard/handlers/c/init_handler.rb 0000644 0000041 0000041 00000001105 13035234564 021234 0 ustar www-data www-data # frozen_string_literal: true
# Handles the Init_Libname() method
class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
MATCH = /\A\s*(?:\S+\s+)*void\s+(?:[Ii]nit_)?(\w+)\s*/
handles MATCH
statement_class ToplevelStatement
process do
parse_block
decl = statement.declaration[MATCH, 1]
if decl
ns = namespace_for_variable(decl)
if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
if statement.comments
register_docstring(ns, statement.comments.source, statement)
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/c/class_handler.rb 0000644 0000041 0000041 00000001462 13035234564 021404 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::ClassHandler < YARD::Handlers::C::Base
MATCH1 = /([\w\.]+)\s* = \s*(?:rb_define_class|boot_defclass)\s*
\(
\s*"([\w:]+)",
\s*(\w+|0)\s*
\)/mx
MATCH2 = /([\w\.]+)\s* = \s*rb_define_class_under\s*
\(
\s*(\w+),
\s*"(\w+)"(?:,
\s*([\w\*\s\(\)\.\->]+)\s*)? # for SWIG
\s*\)/mx
handles MATCH1
handles MATCH2
statement_class BodyStatement
process do
statement.source.scan(MATCH1) do |var_name, class_name, parent|
handle_class(var_name, class_name, parent)
end
statement.source.scan(MATCH2) do |var_name, in_module, class_name, parent|
handle_class(var_name, class_name, parent, in_module)
end
end
end
yard-0.9.7/lib/yard/handlers/c/method_handler.rb 0000644 0000041 0000041 00000002312 13035234564 021552 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
MATCH1 = /rb_define_
(
singleton_method |
method |
module_function |
private_method
)
\s*\(\s*([\w\.]+)\s*,
\s*"([^"]+)"\s*,
\s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?\s*,
\s*(-?\w+)\s*\)/xm
MATCH2 = /rb_define_global_function\s*\(
\s*"([^"]+)",
\s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
\s*(-?\w+)\s*\)/xm
handles MATCH1
handles MATCH2
statement_class BodyStatement
process do
statement.source.scan(MATCH1) do |type, var_name, name, func_name, _param_count|
break if var_name == "ruby_top_self"
break if var_name == "nstr"
break if var_name == "envtbl"
var_name = "rb_cObject" if var_name == "rb_mKernel"
handle_method(type, var_name, name, func_name)
end
statement.source.scan(MATCH2) do |name, func_name, _param_count|
handle_method("method", "rb_mKernel", name, func_name)
end
end
end
yard-0.9.7/lib/yard/handlers/c/struct_handler.rb 0000644 0000041 0000041 00000000624 13035234564 021622 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::StructHandler < YARD::Handlers::C::Base
MATCH = /([\w\.]+)\s*=\s*(?:rb_struct_define_without_accessor)\s*
\(\s*"([\w:]+)"\s*,\s*(\w+)\s*/mx
handles MATCH
statement_class BodyStatement
process do
statement.source.scan(MATCH) do |var_name, class_name, parent|
handle_class(var_name, class_name, parent)
end
end
end
yard-0.9.7/lib/yard/handlers/c/module_handler.rb 0000644 0000041 0000041 00000001115 13035234564 021557 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::ModuleHandler < YARD::Handlers::C::Base
MATCH1 = /([\w\.]+)\s* = \s*rb_define_module\s*\(\s*"([\w:]+)"\s*\)/mx
MATCH2 = /([\w\.]+)\s* = \s*rb_define_module_under\s*\(\s*(\w+),\s*"(\w+)"\s*\)/mx
handles MATCH1
handles MATCH2
statement_class BodyStatement
process do
statement.source.scan(MATCH1) do |var_name, module_name|
handle_module(var_name, module_name)
end
statement.source.scan(MATCH2) do |var_name, in_module, module_name|
handle_module(var_name, module_name, in_module)
end
end
end
yard-0.9.7/lib/yard/handlers/c/alias_handler.rb 0000644 0000041 0000041 00000000724 13035234564 021370 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::AliasHandler < YARD::Handlers::C::Base
MATCH = /rb_define_alias
\s*\(\s*([\w\.]+),
\s*"([^"]+)",
\s*"([^"]+)"\s*\)/xm
handles MATCH
statement_class BodyStatement
process do
statement.source.scan(MATCH) do |var_name, new_name, old_name|
var_name = "rb_cObject" if var_name == "rb_mKernel"
handle_alias(var_name, new_name, old_name)
end
end
end
yard-0.9.7/lib/yard/handlers/c/handler_methods.rb 0000644 0000041 0000041 00000020455 13035234564 021745 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module C
module HandlerMethods
include Parser::C
include CodeObjects
def handle_class(var_name, class_name, parent, in_module = nil)
parent = nil if parent == "0"
namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
if namespace.nil?
raise Parser::UndocumentableError,
"class #{class_name}. Cannot find definition for parent namespace."
end
register ClassObject.new(namespace, class_name) do |obj|
if parent
parent_class = namespace_for_variable(parent)
if parent_class.is_a?(Proxy)
obj.superclass = "::#{parent_class.path}"
obj.superclass.type = :class
else
obj.superclass = parent_class
end
end
namespaces[var_name] = obj
register_file_info(obj, statement.file, statement.line)
end
end
def handle_module(var_name, module_name, in_module = nil)
namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
if namespace.nil?
raise Parser::UndocumentableError,
"module #{module_name}. Cannot find definition for parent namespace."
end
register ModuleObject.new(namespace, module_name) do |obj|
namespaces[var_name] = obj
register_file_info(obj, statement.file, statement.line)
end
end
def handle_method(scope, var_name, name, func_name, _source_file = nil)
visibility = :public
case scope
when "singleton_method"; scope = :class
when "module_function"; scope = :module
when "private_method"; scope = :instance; visibility = :private
else; scope = :instance
end
namespace = namespace_for_variable(var_name)
# Is this method being defined on a core Ruby class or module?
if namespace.is_a?(Proxy)
if var_name =~ /^rb_c(\w+)/ && YARD::CodeObjects::BUILTIN_CLASSES.include?($1)
namespace = namespaces[var_name] = YARD::CodeObjects::ClassObject.new(:root, $1)
elsif var_name =~ /^rb_m(\w+)/ && YARD::CodeObjects::BUILTIN_MODULES.include?($1)
namespace = namespaces[var_name] = YARD::CodeObjects::ModuleObject.new(:root, $1)
end
end
return if namespace.nil? # XXX: raise UndocumentableError might be too noisy.
register MethodObject.new(namespace, name, scope) do |obj|
register_visibility(obj, visibility)
find_method_body(obj, func_name)
obj.explicit = true
obj.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
end
end
def handle_attribute(var_name, name, read, write)
values = {:read => read.to_i, :write => write.to_i}
{:read => name, :write => "#{name}="}.each do |type, meth_name|
next unless values[type] > 0
obj = handle_method(:instance, var_name, meth_name, nil)
register_file_info(obj, statement.file, statement.line)
obj.namespace.attributes[:instance][name] ||= SymbolHash[:read => nil, :write => nil]
obj.namespace.attributes[:instance][name][type] = obj
end
end
def handle_alias(var_name, new_name, old_name)
namespace = namespace_for_variable(var_name)
return if namespace.nil?
new_meth = new_name.to_sym
old_meth = old_name.to_sym
old_obj = namespace.child(:name => old_meth, :scope => :instance)
new_obj = register MethodObject.new(namespace, new_meth, :instance) do |o|
register_visibility(o, visibility)
register_file_info(o, statement.file, statement.line)
end
if old_obj
new_obj.signature = old_obj.signature
new_obj.source = old_obj.source
new_obj.docstring = old_obj.docstring
new_obj.docstring.object = new_obj
else
new_obj.signature = "def #{new_meth}" # this is all we know.
end
namespace.aliases[new_obj] = old_meth
end
def handle_constants(type, var_name, const_name, value)
return unless type =~ /^const$|^global_const$/
namespace = type == 'global_const' ?
:root : namespace_for_variable(var_name)
register ConstantObject.new(namespace, const_name) do |obj|
obj.source_type = :c
obj.value = value
register_file_info(obj, statement.file, statement.line)
find_constant_docstring(obj)
end
end
private
def find_constant_docstring(object)
comment = nil
# look inside overrides for declaration value
override_comments.each do |name, override_comment|
next unless override_comment.file == statement.file
just_const_name = name.gsub(/\A.+::/, '')
if object.path == name || object.name.to_s == just_const_name
comment = override_comment.source
break
end
end
# use any comments on this statement as a last resort
if comment.nil? && statement.comments && statement.comments.source =~ /\S/
comment = statement.comments.source
stmt = statement.comments
end
# In the case of rb_define_const, the definition and comment are in
# "/* definition: comment */" form. The literal ':' and '\' characters
# can be escaped with a backslash.
if comment
comment.scan(/\A\s*(.*?[^\s\\]):\s*(.+)/m) do |new_value, new_comment|
object.value = new_value.gsub(/\\:/, ':')
comment = new_comment
end
register_docstring(object, comment, stmt)
end
end
def find_method_body(object, symbol)
file = statement.file
in_file = false
if statement.comments && statement.comments.source =~ /\A\s*in (\S+)\Z/
file = $1
in_file = true
process_file(file, object)
end
src_stmt = symbols[symbol]
if src_stmt
register_file_info(object, src_stmt.file, src_stmt.line, true)
register_source(object, src_stmt)
record_parameters(object, symbol, src_stmt)
unless src_stmt.comments.nil? || src_stmt.comments.source.empty?
register_docstring(object, src_stmt.comments.source, src_stmt)
return # found docstring
end
end
# found source (possibly) but no docstring
# so look in overrides
return if override_comments.any? do |name, override_comment|
next unless override_comment.file == file
name = name.gsub(/::([^:\.#]+?)\Z/, '.\1')
# explicit namespace in override comment
path = (name =~ /\.|#/ ? object.path : object.name.to_s)
if path == name || path == name.sub(/new$/, 'initialize') || path == name.sub('.', '#')
register_docstring(object, override_comment.source, override_comment)
true
else
false
end
end
# use any comments on this statement as a last resort
if !in_file && statement.comments && statement.comments.source =~ /\S/
register_docstring(object, statement.comments.source, statement)
end
end
def record_parameters(object, symbol, src)
# use regex to extract comma-delimited list of parameters from cfunc definition
if src.source =~ /VALUE\s+#{symbol}\(([^)]*)\)\s*\{/m
params = $~[1].split(/\s*,\s*/) # rubocop:disable Style/SpecialGlobalVars
# cfunc for a "varargs" method has params "int argc, VALUE *argv"
if params[0] =~ /int\s+argc/ && params[1] =~ /VALUE\s*\*\s*argv/
object.parameters = [['*args', nil]]
else
# the first cfunc argument is the 'self' argument, we don't need that
object.parameters = params.drop(1).map {|s| [s[/VALUE\s+(\S+)/, 1], nil] }
end
end
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/c/override_comment_handler.rb 0000644 0000041 0000041 00000001557 13035234564 023645 0 ustar www-data www-data # frozen_string_literal: true
# Parses comments
class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
handles(/./)
statement_class Comment
process do
return if statement.overrides.empty?
statement.overrides.each do |type, name|
override_comments << [name, statement]
obj = nil
case type
when :class
name, superclass = *name.split(/\s*<\s*/)
obj = YARD::CodeObjects::ClassObject.new(:root, name)
obj.superclass = "::#{superclass}" if superclass
when :module
obj = YARD::CodeObjects::ModuleObject.new(:root, name)
end
register(obj)
end
end
def register_docstring(object, docstring = statement.source, stmt = statement)
super
end
def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
super
end
end
yard-0.9.7/lib/yard/handlers/c/constant_handler.rb 0000644 0000041 0000041 00000000670 13035234564 022130 0 ustar www-data www-data # frozen_string_literal: true
class YARD::Handlers::C::ConstantHandler < YARD::Handlers::C::Base
MATCH = /\brb_define_((?:readonly_)?variable|(?:global_)?const)
\s*\((?:\s*(\w+),)?\s*"(\w+)",\s*(.*?)\s*\)\s*;/xm
handles MATCH
statement_class BodyStatement
process do
statement.source.scan(MATCH) do |type, var_name, const_name, value|
handle_constants(type, var_name, const_name, value)
end
end
end
yard-0.9.7/lib/yard/handlers/c/base.rb 0000644 0000041 0000041 00000007100 13035234564 017507 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module C
class Base < Handlers::Base
include YARD::Parser::C
include HandlerMethods
# @return [Boolean] whether the handler handles this statement
def self.handles?(statement, processor)
processor.globals.cruby_processed_files ||= {}
processor.globals.cruby_processed_files[processor.file] = true
src = statement.respond_to?(:declaration) ?
statement.declaration : statement.source
handlers.any? do |a_handler|
statement_class >= statement.class &&
case a_handler
when String
src == a_handler
when Regexp
src =~ a_handler
end
end
end
def self.statement_class(type = nil)
if type
@statement_class = type
else
(defined?(@statement_class) && @statement_class) || Statement
end
end
# @group Registering objects
def register_docstring(object, docstring = nil, stmt = nil)
super(object, docstring, stmt) if docstring
end
def register_file_info(object, file = nil, line = nil, comments = nil)
super(object, file, line, comments) if file
end
def register_source(object, source = nil, type = nil)
super(object, source, type) if source
end
def register_visibility(object, visibility = nil)
super(object, visibility) if visibility
end
# @group Looking up Symbol and Var Values
def symbols
globals.cruby_symbols ||= {}
end
def override_comments
globals.cruby_override_comments ||= []
end
def namespace_for_variable(var)
return namespaces[var] if namespaces[var]
var = remove_var_prefix(var)
var.empty? ? nil : P(var)
end
def ensure_variable_defined!(var, max_retries = 1)
retries = 0
object = nil
loop do
object = namespace_for_variable(var)
break unless object.is_a?(Proxy)
raise NamespaceMissingError, object if retries > max_retries
log.debug "Missing namespace variable #{var} in file `#{parser.file}', moving it to the back of the line."
parser.parse_remaining_files
retries += 1
end
object
end
def namespaces
globals.cruby_namespaces ||= {}
end
def processed_files
globals.cruby_processed_files ||= {}
end
# @group Parsing an Inner Block
def parse_block(opts = {})
return if !statement.block || statement.block.empty?
push_state(opts) do
parser.process(statement.block)
end
end
# @group Processing other files
def process_file(file, object)
file = File.cleanpath(file)
return if processed_files[file]
processed_files[file] = file
begin
log.debug "Processing embedded call to C source #{file}..."
globals.ordered_parser.files.delete(file) if globals.ordered_parser
parser.process(Parser::C::CParser.new(File.read(file), file).parse)
rescue Errno::ENOENT
log.warn "Missing source file `#{file}' when parsing #{object}"
end
end
# @endgroup
private
def remove_var_prefix(var)
var.gsub(/^rb_[mc]|^[a-z_]+/, '')
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/c/symbol_handler.rb 0000644 0000041 0000041 00000000551 13035234564 021602 0 ustar www-data www-data # frozen_string_literal: true
# Keeps track of function bodies for symbol lookup during Ruby method declarations
class YARD::Handlers::C::SymbolHandler < YARD::Handlers::C::Base
MATCH = /\A\s*(?:(?:\w+)\s+)?(?:intern\s+)?VALUE\s+(\w+)\s*\(/
handles MATCH
statement_class ToplevelStatement
process { symbols[statement.source[MATCH, 1]] = statement }
end
yard-0.9.7/lib/yard/handlers/processor.rb 0000644 0000041 0000041 00000017265 13035234564 020407 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
module YARD
module Handlers
# Iterates over all statements in a file and delegates them to the
# {Handlers::Base} objects that are registered to handle the statement.
#
# This class is passed to each handler and keeps overall processing state.
# For example, if the {#visibility} is set in a handler, all following
# statements will have access to this state. This allows "public",
# "protected" and "private" statements to be handled in classes and modules.
# In addition, the {#namespace} can be set during parsing to control
# where objects are being created from. You can also access extra stateful
# properties that any handler can set during the duration of the post
# processing of a file from {#extra_state}. If you need to access state
# across different files, look at {#globals}.
#
# @see Handlers::Base
class Processor
class << self
# Registers a new namespace for handlers of the given type.
# @since 0.6.0
def register_handler_namespace(type, ns)
namespace_for_handler[type] = ns
end
# @return [Hash] a list of registered parser type extensions
# @private
# @since 0.6.0
attr_reader :namespace_for_handler
undef namespace_for_handler
def namespace_for_handler; @@parser_type_extensions ||= {} end
end
register_handler_namespace :ruby, Ruby
register_handler_namespace :ruby18, Ruby::Legacy
register_handler_namespace :c, C
# @return [String] the filename
attr_accessor :file
# @return [CodeObjects::NamespaceObject] the current namespace
attr_accessor :namespace
# @return [Symbol] the current visibility (public, private, protected)
attr_accessor :visibility
# @return [Symbol] the current scope (class, instance)
attr_accessor :scope
# @return [CodeObjects::Base, nil] unlike the namespace, the owner
# is a non-namespace object that should be stored between statements.
# For instance, when parsing a method body, the {CodeObjects::MethodObject}
# is set as the owner, in case any extra method information is processed.
attr_accessor :owner
# @return [Symbol] the parser type (:ruby, :ruby18, :c)
attr_accessor :parser_type
# Handlers can share state for the entire post processing stage through
# this attribute. Note that post processing stage spans multiple files.
# To share state only within a single file, use {#extra_state}
#
# @example Sharing state among two handlers
# class Handler1 < YARD::Handlers::Ruby::Base
# handles :class
# process { globals.foo = :bar }
# end
#
# class Handler2 < YARD::Handlers::Ruby::Base
# handles :method
# process { puts globals.foo }
# end
# @return [OpenStruct] global shared state for post-processing stage
# @see #extra_state
attr_accessor :globals
# Share state across different handlers inside of a file.
# This attribute is similar to {#visibility}, {#scope}, {#namespace}
# and {#owner}, in that they all maintain state across all handlers
# for the entire source file. Use this attribute to store any data
# your handler might need to save during the parsing of a file. If
# you need to save state across files, see {#globals}.
#
# @return [OpenStruct] an open structure that can store arbitrary data
# @see #globals
attr_accessor :extra_state
# Creates a new Processor for a +file+.
# @param [SourceParser] parser the parser used to initialize the processor
def initialize(parser)
@file = parser.file || "(stdin)"
@namespace = YARD::Registry.root
@visibility = :public
@scope = :instance
@owner = @namespace
@parser_type = parser.parser_type
@handlers_loaded = {}
@globals = parser.globals || OpenStruct.new
@extra_state = OpenStruct.new
load_handlers
end
# Processes a list of statements by finding handlers to process each
# one.
#
# @param [Array] statements a list of statements
# @return [void]
def process(statements)
statements.each_with_index do |stmt, _index|
find_handlers(stmt).each do |handler|
begin
handler.new(self, stmt).process
rescue HandlerAborted
log.debug "#{handler} cancelled from #{caller.last}"
log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
rescue NamespaceMissingError => missingerr
log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized.\n" \
"If this class/method is part of your source tree, this will affect your documentation results.\n" \
"You can correct this issue by loading the source file for this object before `#{file}'\n"
rescue Parser::UndocumentableError => undocerr
log.warn "in #{handler}: Undocumentable #{undocerr.message}\n" \
"\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
rescue => e
log.error "Unhandled exception in #{handler}:\n" \
" in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
log.backtrace(e)
end
end
end
end
# Continue parsing the remainder of the files in the +globals.ordered_parser+
# object. After the remainder of files are parsed, processing will continue
# on the current file.
#
# @return [void]
# @see Parser::OrderedParser
def parse_remaining_files
if globals.ordered_parser
globals.ordered_parser.parse
log.debug("Re-processing #{@file}...")
end
end
# Searches for all handlers in {Base.subclasses} that match the +statement+
#
# @param statement the statement object to match.
# @return [Array, CodeObjects::Base, Object]
# If this method returns a code object (or a list of them),
# they are passed to the +#register+ method which adds basic
# attributes. It is not necessary to return any objects and in
# some cases you may want to explicitly avoid the returning of
# any objects for post-processing by the register method.
#
# @see handles
# @see #register
#
def process
raise NotImplementedError, "#{self} did not implement a #process method for handling."
end
# Parses the semantic "block" contained in the statement node.
#
# @abstract Subclasses should call {Processor#process parser.process}
def parse_block(*)
raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
end
# @return [Processor] the processor object that manages all global state
# during handling.
attr_reader :parser
# @return [Object] the statement object currently being processed. Usually
# refers to one semantic language statement, though the strict definition
# depends on the parser used.
attr_reader :statement
# (see Processor#owner)
attr_accessor :owner
# (see Processor#namespace)
attr_accessor :namespace
# (see Processor#visibility)
attr_accessor :visibility
# (see Processor#scope)
attr_accessor :scope
# (see Processor#globals)
attr_reader :globals
# (see Processor#extra_state)
attr_reader :extra_state
undef owner, owner=, namespace, namespace=
undef visibility, visibility=, scope, scope=
undef globals, extra_state
def owner; parser.owner end
def owner=(v) parser.owner = v end
def namespace; parser.namespace end
def namespace=(v); parser.namespace = v end
def visibility; parser.visibility end
def visibility=(v); parser.visibility = v end
def scope; parser.scope end
def scope=(v); parser.scope = v end
def globals; parser.globals end
def extra_state; parser.extra_state end
# Aborts a handler by raising {Handlers::HandlerAborted}.
# An exception will only be logged in debugging mode for
# this kind of handler exit.
#
# @since 0.8.4
def abort!
raise Handlers::HandlerAborted
end
# Executes a given block with specific state values for {#owner},
# {#namespace} and {#scope}.
#
# @option opts [CodeObjects::NamespaceObject] :namespace (value of #namespace)
# the namespace object that {#namespace} will be equal to for the
# duration of the block.
# @option opts [Symbol] :scope (:instance)
# the scope for the duration of the block.
# @option opts [CodeObjects::Base] :owner (value of #owner)
# the owner object (method) for the duration of the block
# @yield a block to execute with the given state values.
def push_state(opts = {})
opts = {
:namespace => namespace,
:scope => :instance,
:owner => owner || namespace,
:visibility => nil
}.update(opts)
ns = namespace
vis = visibility
sc = scope
oo = owner
self.namespace = opts[:namespace]
self.visibility = opts[:visibility] || :public
self.scope = opts[:scope]
self.owner = opts[:owner]
yield
self.namespace = ns
self.visibility = vis
self.scope = sc
self.owner = oo
end
# Do some post processing on a list of code objects.
# Adds basic attributes to the list of objects like
# the filename, line number, {CodeObjects::Base#dynamic},
# source code and {CodeObjects::Base#docstring},
# but only if they don't exist.
#
# @param [Array] objects
# the list of objects to post-process.
#
# @return [CodeObjects::Base, Array]
# returns whatever is passed in, for chainability.
#
def register(*objects)
objects.flatten.each do |object|
next unless object.is_a?(CodeObjects::Base)
register_ensure_loaded(object)
yield(object) if block_given?
register_file_info(object)
register_source(object)
register_visibility(object)
register_docstring(object)
register_group(object)
register_dynamic(object)
register_module_function(object)
end
objects.size == 1 ? objects.first : objects
end
# Ensures that the object's namespace is loaded before attaching it
# to the namespace.
#
# @param [CodeObjects::Base] object the object to register
# @return [void]
# @since 0.8.0
def register_ensure_loaded(object)
ensure_loaded!(object.namespace)
object.namespace.children << object
rescue NamespaceMissingError
nil # noop
end
# Registers the file/line of the declaration with the object
#
# @param [CodeObjects::Base] object the object to register
# @return [void]
# @since 0.8.0
def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
object.add_file(file, line, comments)
end
# Registers any docstring found for the object and expands macros
#
# @param [CodeObjects::Base] object the object to register
# @return [void]
# @since 0.8.0
def register_docstring(object, docstring = statement.comments, stmt = statement)
docstring = docstring.join("\n") if Array === docstring
parser = Docstring.parser
parser.parse(docstring || "", object, self)
if object && docstring
object.docstring = parser.to_docstring
# Add hash_flag/line_range
if stmt
object.docstring.hash_flag = stmt.comments_hash_flag
object.docstring.line_range = stmt.comments_range
end
end
register_transitive_tags(object)
end
# Registers the object as being inside a specific group
#
# @param [CodeObjects::Base] object the object to register
# @return [void]
# @since 0.8.0
def register_group(object, group = extra_state.group)
if group
unless object.namespace.is_a?(Proxy)
object.namespace.groups |= [group]
end
object.group = group
end
end
# Registers any transitive tags from the namespace on the object
#
# @param [CodeObjects::Base, nil] object the object to register
# @return [void]
# @since 0.8.0
def register_transitive_tags(object)
return unless object && !object.namespace.is_a?(Proxy)
Tags::Library.transitive_tags.each do |tag|
next unless object.namespace.has_tag?(tag)
next if object.has_tag?(tag)
object.add_tag(*object.namespace.tags(tag))
end
end
# @param [CodeObjects::Base] object the object to register
# @return [void]
# @since 0.8.0
def register_source(object, source = statement, type = parser.parser_type)
return unless object.is_a?(MethodObject)
object.source ||= source
object.source_type = type
end
# Registers visibility on a method object. If the object does not
# respond to setting visibility, nothing is done.
#
# @param [#visibility=] object the object to register
# @param [Symbol] visibility the visibility to set on the object
# @since 0.8.0
def register_visibility(object, visibility = self.visibility)
return unless object.respond_to?(:visibility=)
return if object.is_a?(NamespaceObject)
object.visibility = visibility
end
# Registers the same method information on the module function, if
# the object was defined as a module function.
#
# @param [CodeObjects::Base] object the possible module function object
# to copy data for
# @since 0.8.0
def register_module_function(object)
return unless object.is_a?(MethodObject)
return unless object.module_function?
modobj = MethodObject.new(object.namespace, object.name)
object.copy_to(modobj)
modobj.visibility = :private # rubocop:disable Lint/UselessSetterCall
end
# Registers the object as dynamic if the object is defined inside
# a method or block (owner != namespace)
#
# @param [CodeObjects::Base] object the object to register
# @return [void]
# @since 0.8.0
def register_dynamic(object)
object.dynamic = true if owner != namespace
end
# Ensures that a specific +object+ has been parsed and loaded into the
# registry. This is necessary when adding data to a namespace, for instance,
# since the namespace may not have been processed yet (it can be located
# in a file that has not been handled).
#
# Calling this method defers the handler until all other files have been
# processed. If the object gets resolved, the rest of the handler continues,
# otherwise an exception is raised.
#
# @example Adding a mixin to the String class programmatically
# ensure_loaded! P('String')
# # "String" is now guaranteed to be loaded
# P('String').mixins << P('MyMixin')
#
# @param [Proxy, CodeObjects::Base] object the object to resolve.
# @param [Integer] max_retries the number of times to defer the handler
# before raising a +NamespaceMissingError+.
# @raise [NamespaceMissingError] if the object is not resolved within
# +max_retries+ attempts, this exception is raised and the handler
# finishes processing.
def ensure_loaded!(object, max_retries = 1)
return if object.root?
return object unless object.is_a?(Proxy)
retries = 0
while object.is_a?(Proxy)
raise NamespaceMissingError, object if retries > max_retries
log.debug "Missing object #{object} in file `#{parser.file}', moving it to the back of the line."
parser.parse_remaining_files
retries += 1
end
object
end
# @group Macro Support
# @abstract Implement this method to return the parameters in a method call
# statement. It should return an empty list if the statement is not a
# method call.
# @return [Array] a list of argument names
def call_params
raise NotImplementedError
end
# @abstract Implement this method to return the method being called in
# a method call. It should return nil if the statement is not a method
# call.
# @return [String] the method name being called
# @return [nil] if the statement is not a method call
def caller_method
raise NotImplementedError
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/ 0000755 0000041 0000041 00000000000 13035234564 017011 5 ustar www-data www-data yard-0.9.7/lib/yard/handlers/ruby/module_function_handler.rb 0000644 0000041 0000041 00000001573 13035234564 024233 0 ustar www-data www-data # frozen_string_literal: true
# Handles module_function calls to turn methods into public class methods.
# Also creates a private instance copy of the method.
class YARD::Handlers::Ruby::ModuleFunctionHandler < YARD::Handlers::Ruby::Base
handles method_call(:module_function)
namespace_only
process do
return if statement.jump(:ident) == statement
case statement.type
when :var_ref, :vcall
self.scope = :module
when :fcall, :command
statement[1].traverse do |node|
case node.type
when :symbol; name = node.first.source
when :string_content; name = node.source
else next
end
instance_method = MethodObject.new(namespace, name)
class_method = MethodObject.new(namespace, name, :module)
instance_method.copy_to(class_method)
class_method.visibility = :public
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/dsl_handler_methods.rb 0000644 0000041 0000041 00000005566 13035234564 023354 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module Ruby
module DSLHandlerMethods
include CodeObjects
include Parser
IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
attr_reader attr_writer extend include public private protected
private_constant).map {|n| [n, true] }.flatten]
def handle_comments
return if IGNORE_METHODS[caller_method]
@docstring = statement.comments || ""
@docstring = @docstring.join("\n") if @docstring.is_a?(Array)
attaching = false
if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
register_docstring(nil)
@docstring = ""
attaching = true
end
macro = find_attached_macro
if macro
txt = macro.expand([caller_method, *call_params], statement.source)
@docstring += "\n" + txt
# macro may have a directive
return register_docstring(nil) if !attaching && txt.match(/^\s*@!/)
elsif !statement.comments_hash_flag && !implicit_docstring?
return register_docstring(nil)
end
# ignore DSL definitions if @method/@attribute directive is used
if @docstring =~ /^@!?(method|attribute)\b/
return register_docstring(nil)
end
object = MethodObject.new(namespace, method_name, scope)
object.signature = method_signature
register(object)
end
def register_docstring(object, docstring = @docstring, stmt = statement)
super
end
private
def implicit_docstring?
tags = %w(method attribute overload visibility scope return)
tags.any? {|tag| @docstring =~ /^@!?#{tag}\b/ }
end
def method_name
name = call_params.first || ""
if name =~ /^#{CodeObjects::METHODNAMEMATCH}$/
name
else
raise UndocumentableError, "method, missing name"
end
end
def method_signature
"def #{method_name}"
end
def find_attached_macro
Registry.all(:macro).each do |macro|
next unless macro.method_object
next unless macro_name_matches(macro)
(namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
return macro if obj == macro.method_object.namespace
end
end
nil
end
# @return [Boolean] whether caller method matches a macro or
# its alias names.
def macro_name_matches(macro)
objs = [macro.method_object]
if objs.first.type != :proxy && objs.first.respond_to?(:aliases)
objs.concat(objs.first.aliases)
end
objs.any? {|obj| obj.name.to_s == caller_method.to_s }
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/decorator_handler_methods.rb 0000644 0000041 0000041 00000007740 13035234564 024550 0 ustar www-data www-data # frozen_string_literal: true
# Helper methods to assist with processing decorators.
module YARD::Handlers::Ruby::DecoratorHandlerMethods
# @overload process_decorator(*nodes, opts = {}, &block)
# Takes care of parsing method definitions passed to decorators
# as parameters, as well as parsing chained decorators.
#
# Use this in a handler's process block.
#
# @yieldparam method [YARD::CodeObjects::MethodObject] Method being decorated.
# @yieldparam node [YARD::Parser::Ruby::AstNode] AST node of the decorated method.
# @yieldparam name [Symbol] Name of the decorated method.
# @return [Array] Array of hashes containing :method, :node, :name.
# See yield params.
#
# @param nodes [YARD::Parser::Ruby::AstNode] AST nodes that refer to decorated
# methods, like indexes of statement.parameter. Defaults to all parameters.
# Pass nil to specify zero parameters.
#
# @option opts [:instance, :class] :scope (:instance) Scope to use for each
# MethodObject.
#
# @option opts [true, false] :transfer_docstring Set false to disable
# transferring the decorator docstring to method definitions passed to the
# decorator as parameters.
#
# @option opts [true, false] :transfer_source Set false to disable
# transferring the decorator source code string to method definitions
# passed to the decorator as parameters.
#
# @example Basic Usage
# # Simply pass the method docs through to the method definition.
# process do
# process_decorator
# end
#
# @example Setting a method's visibility to private.
# process do
# process_decorator :scope => :class do |method|
# method.visibility = :private if method.respond_to? :visibility
# end
# end
def process_decorator(*nodes, &block)
opts = nodes.last.is_a?(Hash) ? nodes.pop : {}
all_nodes = statement.parameters.select do |p|
p.is_a? YARD::Parser::Ruby::AstNode
end
# Parse decorator parameters (decorator chain).
all_nodes.each do |param|
parse_block param if param.call? || param.def?
end
selected_nodes =
if nodes.empty?
all_nodes
elsif nodes.count == 1 && nodes.first.nil?
[]
else
nodes
end
decorated_methods = selected_nodes.map do |param|
process_decorator_parameter param, opts, &block
end.flatten
# Store method nodes in decorator node.
statement.define_singleton_method :decorators do
decorated_methods.map {|h| h[:node] }
end
decorated_methods
end
private
def process_decorator_parameter(node, opts = {}, &block)
scope = opts.fetch :scope, :instance
transfer_docstring = opts.fetch :transfer_docstring, true
transfer_source = opts.fetch :transfer_source, true
name = nil
if node.call?
if node.respond_to? :decorators
return node.decorators.map do |n|
process_decorator_parameter n, opts, &block
end
end
elsif node.def?
name = node.jump(:def).method_name.source
else
name = node.jump(:ident, :string_content, :const).source
end
if name.nil?
raise YARD::Parser::UndocumentableError, 'statement, cannot determine method name'
end
method = YARD::CodeObjects::Proxy.new(
namespace,
(scope == :instance ? '#' : '.') + name.to_s,
:method
)
# Transfer source to methods passed to the helper as parameters.
method.source = statement.source if transfer_source && node.def?
# Transfer decorator docstring to methods passed to the helper as parameters.
if transfer_docstring && node.def? &&
statement.docstring && method.docstring.empty?
tags = method.tags if method.respond_to? :tags
tags ||= []
method.docstring = statement.docstring
tags.each {|t| method.add_tag t }
end
yield method, node, name.to_sym if block_given?
[{:method => method, :node => node, :name => name.to_sym}]
end
end
yard-0.9.7/lib/yard/handlers/ruby/mixin_handler.rb 0000644 0000041 0000041 00000002251 13035234564 022157 0 ustar www-data www-data # frozen_string_literal: true
# Handles the 'include' statement to mixin a module in the instance scope
class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
handles method_call(:include)
namespace_only
process do
errors = []
statement.parameters(false).reverse.each do |mixin|
begin
process_mixin(mixin)
rescue YARD::Parser::UndocumentableError => err
errors << err.message
end
end
unless errors.empty?
msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
raise YARD::Parser::UndocumentableError, "mixin#{msg} for class #{namespace.path}"
end
end
protected
def process_mixin(mixin)
raise YARD::Parser::UndocumentableError unless mixin.ref?
raise YARD::Parser::UndocumentableError if mixin.first.type == :ident
case obj = Proxy.new(namespace, mixin.source)
when ConstantObject # If a constant is included, use its value as the real object
obj = Proxy.new(namespace, obj.value, :module)
else
obj = Proxy.new(namespace, mixin.source, :module)
end
namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)
end
end
yard-0.9.7/lib/yard/handlers/ruby/extend_handler.rb 0000644 0000041 0000041 00000001057 13035234564 022325 0 ustar www-data www-data # frozen_string_literal: true
# Handles 'extend' call to include modules into the class scope of another
# @see MixinHandler
class YARD::Handlers::Ruby::ExtendHandler < YARD::Handlers::Ruby::MixinHandler
handles method_call(:extend)
namespace_only
def scope; :class end
private
def process_mixin(mixin)
if mixin == s(:var_ref, s(:kw, "self"))
if namespace.is_a?(ClassObject)
raise UndocumentableError, "extend(self) statement on class"
end
namespace.mixins(scope) << namespace
else
super
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/ 0000755 0000041 0000041 00000000000 13035234564 020255 5 ustar www-data www-data yard-0.9.7/lib/yard/handlers/ruby/legacy/module_function_handler.rb 0000644 0000041 0000041 00000001143 13035234564 025470 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ModuleFunctionHandler)
class YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\A(module_function)(\s|\(|$)/)
namespace_only
process do
if statement.tokens.size == 1
self.scope = :module
else
tokval_list(statement.tokens[2..-1], :attr).each do |name|
instance_method = MethodObject.new(namespace, name)
class_method = MethodObject.new(namespace, name, :module)
instance_method.copy_to(class_method)
class_method.visibility = :public
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/mixin_handler.rb 0000644 0000041 0000041 00000002220 13035234564 023417 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::MixinHandler)
class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\Ainclude(\s|\()/)
namespace_only
process do
errors = []
statement.tokens[1..-1].to_s.split(/\s*,\s*/).reverse.each do |mixin|
mixin = mixin.strip
begin
process_mixin(mixin)
rescue YARD::Parser::UndocumentableError => err
errors << err.message
end
end
unless errors.empty?
msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
raise YARD::Parser::UndocumentableError, "mixin#{msg} for class #{namespace.path}"
end
end
private
def process_mixin(mixin)
mixmatch = mixin[/\A(#{NAMESPACEMATCH})/, 1]
raise YARD::Parser::UndocumentableError unless mixmatch
case obj = Proxy.new(namespace, mixmatch)
when ConstantObject # If a constant is included, use its value as the real object
obj = Proxy.new(namespace, obj.value, :module)
else
obj = Proxy.new(namespace, mixmatch, :module)
end
namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/extend_handler.rb 0000644 0000041 0000041 00000000745 13035234564 023574 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ExtendHandler)
class YARD::Handlers::Ruby::Legacy::ExtendHandler < YARD::Handlers::Ruby::Legacy::MixinHandler
handles(/\Aextend(\s|\()/)
namespace_only
def scope; :class end
private
def process_mixin(mixin)
if mixin == "self"
if namespace.is_a?(ClassObject)
raise UndocumentableError, "extend(self) statement on class"
end
namespace.mixins(scope) << namespace
else
super
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/attribute_handler.rb 0000644 0000041 0000041 00000004176 13035234564 024312 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::AttributeHandler)
class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\Aattr(?:_(?:reader|writer|accessor))?(?:\s|\()/)
namespace_only
process do
begin
attr_type = statement.tokens.first.text.to_sym
symbols = tokval_list statement.tokens[2..-1], :attr, TkTRUE, TkFALSE
read = true
write = false
rescue SyntaxError
raise YARD::Parser::UndocumentableError, attr_type
end
# Change read/write based on attr_reader/writer/accessor
case attr_type
when :attr
# In the case of 'attr', the second parameter (if given) isn't a symbol.
write = symbols.pop if symbols.size == 2
when :attr_accessor
write = true
when :attr_reader
# change nothing
when :attr_writer
read = false
write = true
end
# Add all attributes
symbols.each do |name|
namespace.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]
# Show their methods as well
{:read => name, :write => "#{name}="}.each do |type, meth|
if type == :read ? read : write
o = MethodObject.new(namespace, meth, scope)
if type == :write
o.parameters = [['value', nil]]
src = "def #{meth}(value)"
full_src = "#{src}\n @#{name} = value\nend"
doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
else
src = "def #{meth}"
full_src = "#{src}\n @#{name}\nend"
doc = "Returns the value of attribute #{name}"
end
o.source ||= full_src
o.signature ||= src
register(o)
o.docstring = doc if o.docstring.blank?(false)
# Regsiter the object explicitly
namespace.attributes[scope][name][type] = o
else
obj = namespace.children.find {|other| other.name == meth.to_sym && other.scope == scope }
# register an existing method as attribute
namespace.attributes[scope][name][type] = obj if obj
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/class_handler.rb 0000644 0000041 0000041 00000007413 13035234564 023411 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ClassHandler)
class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy::Base
include YARD::Handlers::Ruby::StructHandlerMethods
handles TkCLASS
namespace_only
process do
if statement.tokens.to_s =~ /^class\s+(#{NAMESPACEMATCH})\s*(?:<\s*(.+)|\Z)/m
classname = $1
superclass_def = $2
superclass = parse_superclass($2)
classname = classname.gsub(/\s/, '')
if superclass == "Struct"
is_a_struct = true
superclass = struct_superclass_name(superclass_def)
create_struct_superclass(superclass, superclass_def)
end
undocsuper = superclass_def && superclass.nil?
klass = register ClassObject.new(namespace, classname) do |o|
o.superclass = superclass if superclass
o.superclass.type = :class if o.superclass.is_a?(Proxy)
end
if is_a_struct
parse_struct_subclass(klass, superclass_def)
elsif klass
create_attributes(klass, members_from_tags(klass))
end
parse_block(:namespace => klass)
if undocsuper
raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
end
elsif statement.tokens.to_s =~ /^class\s*<<\s*([\w\:\s]+)/
classname = $1.gsub(/\s/, '')
proxy = Proxy.new(namespace, classname)
# Allow constants to reference class names
if ConstantObject === proxy
if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
proxy = Proxy.new(namespace, proxy.value)
else
raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
end
end
if classname == "self"
parse_block(:namespace => namespace, :scope => :class)
elsif classname[0, 1] =~ /[A-Z]/
register ClassObject.new(namespace, classname) if Proxy === proxy
parse_block(:namespace => proxy, :scope => :class)
else
raise YARD::Parser::UndocumentableError, "class '#{classname}'"
end
else
raise YARD::Parser::UndocumentableError, "class: #{statement.tokens}"
end
end
private
# Extracts the parameter list from the Struct.new declaration and returns it
# formatted as a list of member names. Expects the user will have used symbols
# to define the struct member names
#
# @param [String] superstring the string declaring the superclass
# @return [Array] a list of member names
def extract_parameters(superstring)
paramstring = superstring.match(/\A(O?Struct)\.new\((.*?)\)/)[2]
paramstring.split(",").select {|x| x.strip[0, 1] == ":" }.map {|x| x.strip[1..-1] } # the 1..-1 chops the leading :
end
def create_struct_superclass(superclass, superclass_def)
return if superclass == "Struct"
the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
o.superclass = "Struct"
end
parse_struct_subclass(the_super, superclass_def)
the_super
end
def struct_superclass_name(superclass)
match = superclass.match(/\A(Struct)\.new\((.*?)\)/)
if match
paramstring = match[2].split(",")
first = paramstring.first.strip
if first[0, 1] =~ /['"]/ && first[-1, 1] =~ /['"]/ && first !~ /\#\{/
return "Struct::#{first[1..-2]}"
end
end
"Struct"
end
def parse_struct_subclass(klass, superclass_def)
# Bounce if there's no parens
return unless superclass_def =~ /O?Struct\.new\((.*?)\)/
members = extract_parameters(superclass_def)
create_attributes(klass, members)
end
def parse_superclass(superclass)
case superclass
when /\A(#{NAMESPACEMATCH})(?:\s|\Z)/,
/\A(Struct|OStruct)\.new/,
/\ADelegateClass\((.+?)\)\s*\Z/,
/\A(#{NAMESPACEMATCH})\(/
$1
when "self"
namespace.path
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/visibility_handler.rb 0000644 0000041 0000041 00000001000 13035234564 024455 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::VisibilityHandler)
class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\A(protected|private|public)(\s|\(|$)/)
namespace_only
process do
vis = statement.tokens.first.text
if statement.tokens.size == 1
self.visibility = vis
else
tokval_list(statement.tokens[2..-1], :attr).each do |name|
MethodObject.new(namespace, name, scope) {|o| o.visibility = vis }
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/class_condition_handler.rb 0000644 0000041 0000041 00000004407 13035234564 025457 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ClassConditionHandler)
# @since 0.5.4
class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby::Legacy::Base
namespace_only
handles TkIF, TkELSIF, TkUNLESS
process do
condition = parse_condition
if condition.nil?
# Parse both blocks if we're unsure of the condition
parse_then_block
parse_else_block
elsif condition
parse_then_block
else
parse_else_block
end
end
protected
# Parses the condition part of the if/unless statement
#
# @return [true, false, nil] true if the condition can be definitely
# parsed to true, false if not, and nil if the condition cannot be
# parsed with certainty (it's dynamic)
# @since 0.5.5
def parse_condition
condition = nil
# Right now we can handle very simple unary conditions like:
# if true
# if false
# if 0
# if 100 (not 0)
# if defined? SOME_CONSTANT
#
# The last case will do a lookup in the registry and then one
# in the Ruby world (using eval).
case statement.tokens[1..-1].to_s.strip
when /^(\d+)$/
condition = $1 != "0"
when /^defined\?\s*\(?(.+?)\)?$/
# defined? keyword used, let's see if we can look up the name
# in the registry, then we'll try using Ruby's powers. eval() is not
# *too* dangerous here since code is not actually executed.
name = $1
obj = YARD::Registry.resolve(namespace, name, true)
begin
condition = true if obj || Object.instance_eval("defined? #{name}")
rescue SyntaxError, NameError
condition = false
end
when "true"
condition = true
when "false"
condition = false
end
if TkUNLESS === statement.tokens.first
condition = !condition unless condition.nil?
end
condition
end
# @since 0.5.5
def parse_then_block
parse_block(:visibility => visibility)
end
# @since 0.5.5
def parse_else_block
return unless statement.block
stmtlist = YARD::Parser::Ruby::Legacy::StatementList
stmtlist.new(statement.block).each do |stmt|
next unless TkELSE === stmt.tokens.first
push_state(:visibility => visibility) do
parser.process(stmtlist.new(stmt.block))
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/method_handler.rb 0000644 0000041 0000041 00000005531 13035234564 023563 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::MethodHandler)
class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy::Base
handles TkDEF
process do
nobj = namespace
mscope = scope
if statement.tokens.to_s =~ /^def\s+(#{METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
meth = $1
args = $2
meth.gsub!(/\s+/, '')
args = tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(args), :all)
args.map! do |a|
k, v, r = *a.split(/(:)|=/, 2)
if r
k += v
v = r
end
[k.strip, (v ? v.strip : nil)]
end if args
else
raise YARD::Parser::UndocumentableError, "method: invalid name"
end
# Class method if prefixed by self(::|.) or Module(::|.)
if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
mscope = :class
meth = $1
prefix = $`
if prefix =~ /^[a-z]/ && prefix != "self"
raise YARD::Parser::UndocumentableError, 'method defined on object instance'
end
nobj = P(namespace, prefix) unless prefix == "self"
end
nobj = P(namespace, nobj.value) while nobj.type == :constant
obj = register MethodObject.new(nobj, meth, mscope) do |o|
o.explicit = true
o.parameters = args
end
# delete any aliases referencing old method
nobj.aliases.each do |aobj, name|
next unless name == obj.name
nobj.aliases.delete(aobj)
end if nobj.is_a?(NamespaceObject)
if mscope == :instance && meth == "initialize"
unless obj.has_tag?(:return)
obj.add_tag(YARD::Tags::Tag.new(:return,
"a new instance of #{namespace.name}", namespace.name.to_s))
end
elsif mscope == :class && obj.docstring.blank? && %w(inherited included
extended method_added method_removed method_undefined).include?(meth)
obj.add_tag(YARD::Tags::Tag.new(:private, nil))
elsif meth.to_s =~ /\?$/
if obj.tag(:return) && (obj.tag(:return).types || []).empty?
obj.tag(:return).types = ['Boolean']
elsif obj.tag(:return).nil?
unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
end
end
end
if obj.has_tag?(:option)
# create the options parameter if its missing
obj.tags(:option).each do |option|
expected_param = option.name
unless obj.tags(:param).find {|x| x.name == expected_param }
new_tag = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", expected_param)
obj.add_tag(new_tag)
end
end
end
info = obj.attr_info
if info
if meth.to_s =~ /=$/ # writer
info[:write] = obj if info[:read]
elsif info[:write]
info[:read] = obj
end
end
parse_block(:owner => obj) # mainly for yield/exceptions
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/module_handler.rb 0000644 0000041 0000041 00000000560 13035234564 023565 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ModuleHandler)
class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
handles TkMODULE
namespace_only
process do
modname = statement.tokens.to_s[/^module\s+(#{NAMESPACEMATCH})/, 1]
mod = register ModuleObject.new(namespace, modname)
parse_block(:namespace => mod)
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/class_variable_handler.rb 0000644 0000041 0000041 00000000675 13035234564 025261 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ClassVariableHandler)
class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby::Legacy::Base
HANDLER_MATCH = /\A@@\w+\s*=\s*/m
handles HANDLER_MATCH
namespace_only
process do
name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
register ClassVariableObject.new(namespace, name) do |o|
o.source = statement
o.value = value.strip
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/yield_handler.rb 0000644 0000041 0000041 00000002036 13035234564 023406 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::YieldHandler)
class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy::Base
handles TkYIELD
process do
return unless owner.is_a?(MethodObject) # Only methods yield
return if owner.has_tag? :yield # Don't override yield tags
return if owner.has_tag? :yieldparam # Same thing.
yieldtag = YARD::Tags::Tag.new(:yield, "", [])
tokval_list(statement.tokens[2..-1], Token).each do |item|
item = item.inspect unless item.is_a?(String)
if item == "self"
yieldtag.types << '_self'
owner.add_tag YARD::Tags::Tag.new(:yieldparam,
"the object that the method was called on", owner.namespace.path, '_self')
elsif item == "super"
yieldtag.types << '_super'
owner.add_tag YARD::Tags::Tag.new(:yieldparam,
"the result of the method from the superclass", nil, '_super')
else
yieldtag.types << item
end
end
owner.add_tag(yieldtag) unless yieldtag.types.empty?
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/alias_handler.rb 0000644 0000041 0000041 00000002614 13035234564 023373 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::AliasHandler)
class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\Aalias(_method)?(\s|\()/)
namespace_only
process do
if TkALIAS === statement.tokens.first
tokens = statement.tokens[2..-1].to_s.split(/\s+/)
names = [tokens[0], tokens[1]].map {|t| t.gsub(/^:(['"])?(.+?)\1?$|^(:)(.+)/, '\2') }
else
names = tokval_list(statement.tokens[2..-1], :attr)
end
raise YARD::Parser::UndocumentableError, statement.tokens.first.text if names.size != 2
names = names.map {|n| Symbol === n ? n.to_s.delete('"') : n }
new_meth = names[0].to_sym
old_meth = names[1].to_sym
old_obj = namespace.child(:name => old_meth, :scope => scope)
new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
o.add_file(parser.file, statement.tokens.first.line_no, statement.comments)
end
if old_obj
new_obj.signature = old_obj.signature
new_obj.source = old_obj.source
new_obj.docstring = old_obj.docstring + YARD::Docstring.new(statement.comments)
new_obj.docstring.line_range = statement.comments_range
new_obj.docstring.hash_flag = statement.comments_hash_flag
new_obj.docstring.object = new_obj
else
new_obj.signature = "def #{new_meth}" # this is all we know.
end
namespace.aliases[new_obj] = old_meth
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/dsl_handler.rb 0000644 0000041 0000041 00000000551 13035234564 023062 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module Ruby
module Legacy
# (see Ruby::DSLHandler)
class DSLHandler < Base
include CodeObjects
include DSLHandlerMethods
handles TkIDENTIFIER
namespace_only
process { handle_comments }
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/exception_handler.rb 0000644 0000041 0000041 00000000774 13035234564 024305 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ExceptionHandler)
class YARD::Handlers::Ruby::Legacy::ExceptionHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\Araise(\s|\(|\Z)/)
process do
return unless owner.is_a?(MethodObject) # Only methods yield
return if owner.has_tag?(:raise)
klass = statement.tokens.to_s[/^raise[\(\s]*(#{NAMESPACEMATCH})\s*(?:\)|,|\s(?:if|unless|until)|;|(?:(?:\.|\:\:)\s*)?new|$)/, 1]
owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/constant_handler.rb 0000644 0000041 0000041 00000001614 13035234564 024132 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::ConstantHandler)
class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Legacy::Base
include YARD::Handlers::Ruby::StructHandlerMethods
HANDLER_MATCH = /\A[A-Z]\w*\s*=[^=]\s*/m
handles HANDLER_MATCH
namespace_only
process do
name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
if value =~ /\A\s*Struct.new(?:\s*\(?|\b)/
process_structclass(name, $')
else
register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
end
end
private
def process_structclass(classname, parameters)
klass = create_class(classname, P(:Struct))
create_attributes(klass, extract_parameters(parameters))
end
def extract_parameters(parameters)
members = tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(parameters), TkSYMBOL)
members.map(&:to_s)
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/comment_handler.rb 0000644 0000041 0000041 00000000354 13035234564 023743 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::CommentHandler)
class YARD::Handlers::Ruby::Legacy::CommentHandler < YARD::Handlers::Ruby::Legacy::Base
handles TkCOMMENT
namespace_only
process do
register_docstring(nil)
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/base.rb 0000644 0000041 0000041 00000022305 13035234564 021516 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module Ruby::Legacy
# This is the base handler for the legacy parser. To implement a legacy
# handler, subclass this class.
#
# @abstract (see Ruby::Base)
class Base < Handlers::Base
# For tokens like TkDEF, TkCLASS, etc.
include YARD::Parser::Ruby::Legacy::RubyToken
# @return [Boolean] whether or not a {Parser::Ruby::Legacy::Statement} object should be handled
# by this handler.
def self.handles?(stmt)
handlers.any? do |a_handler|
case a_handler
when String
stmt.tokens.first.text == a_handler
when Regexp
stmt.tokens.to_s =~ a_handler
else
a_handler == stmt.tokens.first.class
end
end
end
# Parses a statement's block with a set of state values. If the
# statement has no block, nothing happens. A description of state
# values can be found at {Handlers::Base#push_state}
#
# @param [Hash] opts State options
# @option opts (see Handlers::Base#push_state)
# @see Handlers::Base#push_state #push_state
def parse_block(opts = {})
push_state(opts) do
if statement.block
blk = Parser::Ruby::Legacy::StatementList.new(statement.block)
parser.process(blk)
end
end
end
def call_params
if statement.tokens.first.is_a?(TkDEF)
extract_method_details.last.map(&:first)
else
tokens = statement.tokens[1..-1]
tokval_list(tokens, :attr, :identifier, TkId).map(&:to_s)
end
end
def caller_method
if statement.tokens.first.is_a?(TkIDENTIFIER)
statement.tokens.first.text
elsif statement.tokens.first.is_a?(TkDEF)
extract_method_details.first
end
end
private
# Extracts method information for macro expansion only
#
# @todo This is a duplicate implementation of {MethodHandler}. Refactor.
# @return [Array>>] the method name followed by method
# arguments (name and optional value)
def extract_method_details
if statement.tokens.to_s =~ /^def\s+(#{METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
meth = $1
args = $2
meth.gsub!(/\s+/, '')
args = tokval_list(Parser::Ruby::Legacy::TokenList.new(args), :all)
args.map! {|a| k, v = *a.split('=', 2); [k.strip, (v ? v.strip : nil)] } if args
meth = $` if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
[meth, args]
end
end
# The string value of a token. For example, the return value for the symbol :sym
# would be :sym. The return value for a string +"foo #{ bar}"+ would be the literal
# +"foo #{ bar}"+ without any interpolation. The return value of the identifier
# 'test' would be the same value: 'test'. Here is a list of common types and
# their return values:
#
# @example
# tokval(TokenList.new('"foo"').first) => "foo"
# tokval(TokenList.new(':foo').first) => :foo
# tokval(TokenList.new('CONSTANT').first, RubyToken::TkId) => "CONSTANT"
# tokval(TokenList.new('identifier').first, RubyToken::TkId) => "identifier"
# tokval(TokenList.new('3.25').first) => 3.25
# tokval(TokenList.new('/xyz/i').first) => /xyz/i
#
# @param [Token] token The token of the class
#
# @param [Array>, Symbol] accepted_types
# The allowed token types that this token can be. Defaults to [{TkVal}].
# A list of types would be, for example, [+TkSTRING+, +TkSYMBOL+], to return
# the token's value if it is either of those types. If +TkVal+ is accepted,
# +TkNode+ is also accepted.
#
# Certain symbol keys are allowed to specify multiple types in one fell swoop.
# These symbols are:
# :string => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+
# :attr => +TkSYMBOL+ and +TkSTRING+
# :identifier => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.
# :number => +TkFLOAT+, +TkINTEGER+
#
# @return [Object] if the token is one of the accepted types, in its real value form.
# It should be noted that identifiers and constants are kept in String form.
# @return [nil] if the token is not any of the specified accepted types
def tokval(token, *accepted_types)
accepted_types = [TkVal] if accepted_types.empty?
accepted_types.push(TkNode) if accepted_types.include? TkVal
if accepted_types.include?(:attr)
accepted_types.push(TkSTRING, TkSYMBOL)
end
if accepted_types.include?(:string)
accepted_types.push(TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING)
end
if accepted_types.include?(:identifier)
accepted_types.push(TkIDENTIFIER, TkFID, TkGVAR)
end
if accepted_types.include?(:number)
accepted_types.push(TkFLOAT, TkINTEGER)
end
return unless accepted_types.any? {|t| t === token }
case token
when TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING
token.text[1..-2]
when TkSYMBOL
token.text[1..-1].to_sym
when TkFLOAT
token.text.to_f
when TkINTEGER
token.text.to_i
when TkREGEXP
token.text =~ %r{\A/(.+)/([^/])\Z}
Regexp.new($1, $2)
when TkTRUE
true
when TkFALSE
false
when TkNIL
nil
else
token.text
end
end
# Returns a list of symbols or string values from a statement.
# The list must be a valid comma delimited list, and values
# will only be returned to the end of the list only.
#
# Example:
# attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']
# attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c']
#
# The tokval list of a {Parser::Ruby::Legacy::TokenList} of the above
# code would be the {#tokval} value of :a, 'b',
# :c and :d.
#
# It should also be noted that this function stops immediately at
# any ruby keyword encountered:
# "attr_accessor :a, :b, :c if x == 5" => ['a', 'b', 'c']
#
# @param [TokenList] tokenlist The list of tokens to process.
# @param [Array>] accepted_types passed to {#tokval}
# @return [Array] the list of tokvalues in the list.
# @return [Array] if there are no symbols or Strings in the list
# @see #tokval
def tokval_list(tokenlist, *accepted_types)
return [] unless tokenlist
out = [[]]
parencount = 0
beforeparen = 0
needcomma = false
seen_comma = true
tokenlist.each do |token|
tokval = accepted_types == [:all] ? token.text : tokval(token, *accepted_types)
parencond = !out.last.empty? && !tokval.nil?
# puts "#{seen_comma.inspect} #{parencount} #{token.class.class_name} #{out.inspect}"
case token
when TkCOMMA
if parencount == 0
out << [] unless out.last.empty?
needcomma = false
seen_comma = true
elsif parencond
out.last << token.text
end
when TkLPAREN
if seen_comma
beforeparen += 1
else
parencount += 1
out.last << token.text if parencond
end
when TkRPAREN
if beforeparen > 0
beforeparen -= 1
else
out.last << token.text if parencount > 0 && !tokval.nil?
parencount -= 1
end
when TkLBRACE, TkLBRACK, TkDO
parencount += 1
out.last << token.text unless tokval.nil?
when TkRBRACE, TkRBRACK, TkEND
out.last << token.text unless tokval.nil?
parencount -= 1
else
break if TkKW === token && ![TkTRUE, TkFALSE, TkSUPER, TkSELF, TkNIL].include?(token.class)
seen_comma = false unless TkWhitespace === token
if parencount == 0
next if needcomma
next if TkWhitespace === token
if !tokval.nil?
out.last << tokval
else
out.last.clear
needcomma = true
end
elsif parencond
needcomma = true
out.last << token.text
end
end
break if beforeparen == 0 && parencount < 0
end
# Flatten any single element lists
out.map {|e| e.empty? ? nil : (e.size == 1 ? e.pop : e.flatten.join) }.compact
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/private_constant_handler.rb 0000644 0000041 0000041 00000001161 13035234564 025661 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::PrivateConstantHandler)
class YARD::Handlers::Ruby::Legacy::PrivateConstantHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\Aprivate_constant(\s|\(|$)/)
namespace_only
process do
tokval_list(statement.tokens[2..-1], :attr, TkCONSTANT).each do |name|
privatize_constant name
end
end
private
def privatize_constant(name)
const = Proxy.new(namespace, name)
ensure_loaded!(const)
const.visibility = :private
rescue NamespaceMissingError
raise UndocumentableError, "private visibility set on unrecognized constant: #{name}"
end
end
yard-0.9.7/lib/yard/handlers/ruby/legacy/private_class_method_handler.rb 0000644 0000041 0000041 00000001210 13035234564 026470 0 ustar www-data www-data # frozen_string_literal: true
# (see Ruby::PrivateClassMethodHandler)
class YARD::Handlers::Ruby::Legacy::PrivateClassMethodHandler < YARD::Handlers::Ruby::Legacy::Base
handles(/\Aprivate_class_method(\s|\(|$)/)
namespace_only
process do
tokval_list(statement.tokens[2..-1], :attr).each do |name|
privatize_class_method name
end
end
private
def privatize_class_method(name)
method = Proxy.new(namespace, name)
ensure_loaded!(method)
method.visibility = :private
rescue YARD::Handlers::NamespaceMissingError
raise UndocumentableError, "private visibility set on unrecognized method: #{name}"
end
end
yard-0.9.7/lib/yard/handlers/ruby/method_condition_handler.rb 0000644 0000041 0000041 00000000404 13035234564 024357 0 ustar www-data www-data # frozen_string_literal: true
# Handles a conditional inside a method
class YARD::Handlers::Ruby::MethodConditionHandler < YARD::Handlers::Ruby::Base
handles :if_mod, :unless_mod
process do
parse_block(statement.then_block, :owner => owner)
end
end
yard-0.9.7/lib/yard/handlers/ruby/struct_handler_methods.rb 0000644 0000041 0000041 00000015344 13035234564 024111 0 ustar www-data www-data # frozen_string_literal: true
# Helper methods to parse @attr_* tags on a class.
#
# @deprecated The use of +@attr+ tags are deprecated since 0.8.0 in favour of
# the +@!attribute+ directive. This module should not be relied on.
# @since 0.5.6
module YARD::Handlers::Ruby::StructHandlerMethods
include YARD::CodeObjects
# Extracts the user's defined @member tag for a given class and its member. Returns
# nil if the user did not define a @member tag for this struct entry.
#
# @param [ClassObject] klass the class whose tags we're searching
# @param [String] member the name of the struct member we need
# @param [Symbol] type reader method, or writer method?
# @return [Tags::Tag, nil] the tag matching the request, or nil if not found
def member_tag_for_member(klass, member, type = :read)
specific_tag = type == :read ? :attr_reader : :attr_writer
(klass.tags(specific_tag) + klass.tags(:attr)).find {|tag| tag.name == member }
end
# Retrieves all members defined in @attr* tags
#
# @param [ClassObject] klass the class with the attributes
# @return [Array] the list of members defined as attributes on the class
def members_from_tags(klass)
tags = klass.tags(:attr) + klass.tags(:attr_reader) + klass.tags(:attr_writer)
tags.map(&:name).uniq
end
# Determines whether to create an attribute method based on the class's
# tags.
#
# @param [ClassObject] klass the class whose tags we're searching
# @param [String] member the name of the struct member we need
# @param [Symbol] type (:read) reader method, or writer method?
# @return [Boolean] should the attribute be created?
def create_member_method?(klass, member, type = :read)
return true if (klass.tags(:attr) + klass.tags(:attr_reader) + klass.tags(:attr_writer)).empty?
return true if member_tag_for_member(klass, member, type)
return !member_tag_for_member(klass, member, :write) if type == :read
!member_tag_for_member(klass, member, :read)
end
# Gets the return type for the member in a nicely formatted string. Used
# to be injected into auto-generated docstrings.
#
# @param [Tags::Tag] member_tag the tag object to check for types
# @return [String] the user-declared type of the struct member, or [Object] if
# the user did not define a type for this member.
def return_type_from_tag(member_tag)
member_tag && member_tag.types ? member_tag.types : "Object"
end
# Creates the auto-generated docstring for the getter method of a struct's
# member. This is used so the generated documentation will look just like that
# of an attribute defined using attr_accessor.
#
# @param [ClassObject] klass the class whose members we're working with
# @param [String] member the name of the member we're generating documentation for
# @return [String] a docstring to be attached to the getter method for this member
def add_reader_tags(klass, new_method, member)
member_tag = member_tag_for_member(klass, member, :read)
return_type = return_type_from_tag(member_tag)
getter_doc_text = member_tag ? member_tag.text : "Returns the value of attribute #{member}"
new_method.docstring.replace(getter_doc_text)
new_method.add_tag YARD::Tags::Tag.new(:return, "the current value of #{member}", return_type)
end
# Creates the auto-generated docstring for the setter method of a struct's
# member. This is used so the generated documentation will look just like that
# of an attribute defined using attr_accessor.
#
# @param [ClassObject] klass the class whose members we're working with
# @param [String] member the name of the member we're generating documentation for
# @return [String] a docstring to be attached to the setter method for this member
def add_writer_tags(klass, new_method, member)
member_tag = member_tag_for_member(klass, member, :write)
return_type = return_type_from_tag(member_tag)
setter_doc_text = member_tag ? member_tag.text : "Sets the attribute #{member}"
new_method.docstring.replace(setter_doc_text)
new_method.add_tag YARD::Tags::Tag.new(:param, "the value to set the attribute #{member} to.", return_type, "value")
new_method.add_tag YARD::Tags::Tag.new(:return, "the newly set value", return_type)
end
# Creates and registers a class object with the given name and superclass name.
# Returns it for further use.
#
# @param [String] classname the name of the class
# @param [String] superclass the name of the superclass
# @return [ClassObject] the class object for further processing/method attaching
def create_class(classname, superclass)
register ClassObject.new(namespace, classname) do |o|
o.superclass = superclass if superclass
o.superclass.type = :class if o.superclass.is_a?(Proxy)
end
end
# Creates the setter (writer) method and attaches it to the class as an attribute.
# Also sets up the docstring to prettify the documentation output.
#
# @param [ClassObject] klass the class to attach the method to
# @param [String] member the name of the member we're generating a method for
def create_writer(klass, member)
# We want to convert these members into attributes just like
# as if they were declared using attr_accessor.
new_meth = register MethodObject.new(klass, "#{member}=", :instance) do |o|
o.parameters = [['value', nil]]
o.signature ||= "def #{member}=(value)"
o.source ||= "#{o.signature}\n @#{member} = value\nend"
end
add_writer_tags(klass, new_meth, member)
klass.attributes[:instance][member][:write] = new_meth
end
# Creates the getter (reader) method and attaches it to the class as an attribute.
# Also sets up the docstring to prettify the documentation output.
#
# @param [ClassObject] klass the class to attach the method to
# @param [String] member the name of the member we're generating a method for
def create_reader(klass, member)
new_meth = register MethodObject.new(klass, member, :instance) do |o|
o.signature ||= "def #{member}"
o.source ||= "#{o.signature}\n @#{member}\nend"
end
add_reader_tags(klass, new_meth, member)
klass.attributes[:instance][member][:read] = new_meth
end
# Creates the given member methods and attaches them to the given ClassObject.
#
# @param [ClassObject] klass the class to generate attributes for
# @param [Array] members a list of member names
def create_attributes(klass, members)
# For each parameter, add reader and writers
members.each do |member|
next if klass.attributes[:instance][member]
klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
create_writer klass, member if create_member_method?(klass, member, :write)
create_reader klass, member if create_member_method?(klass, member, :read)
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/attribute_handler.rb 0000644 0000041 0000041 00000005467 13035234564 023052 0 ustar www-data www-data # frozen_string_literal: true
# Handles +attr_*+ statements in modules/classes
class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
handles method_call(:attr)
handles method_call(:attr_reader)
handles method_call(:attr_writer)
handles method_call(:attr_accessor)
namespace_only
process do
return if statement.type == :var_ref || statement.type == :vcall
read = true
write = false
params = statement.parameters(false).dup
# Change read/write based on attr_reader/writer/accessor
case statement.method_name(true)
when :attr
# In the case of 'attr', the second parameter (if given) isn't a symbol.
if params.size == 2
write = true if params.pop == s(:var_ref, s(:kw, "true"))
end
when :attr_accessor
write = true
when :attr_reader
# change nothing
when :attr_writer
read = false
write = true
end
# Add all attributes
validated_attribute_names(params).each do |name|
namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
# Show their methods as well
{:read => name, :write => "#{name}="}.each do |type, meth|
if type == :read ? read : write
o = MethodObject.new(namespace, meth, scope)
if type == :write
o.parameters = [['value', nil]]
src = "def #{meth}(value)"
full_src = "#{src}\n @#{name} = value\nend"
doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
else
src = "def #{meth}"
full_src = "#{src}\n @#{name}\nend"
doc = "Returns the value of attribute #{name}"
end
o.source ||= full_src
o.signature ||= src
register(o)
o.docstring = doc if o.docstring.blank?(false)
# Regsiter the object explicitly
namespace.attributes[scope][name][type] = o
else
obj = namespace.children.find {|other| other.name == meth.to_sym && other.scope == scope }
# register an existing method as attribute
namespace.attributes[scope][name][type] = obj if obj
end
end
end
end
protected
# Strips out any non-essential arguments from the attr statement.
#
# @param [Array] params a list of the parameters
# in the attr call.
# @return [Array] the validated attribute names
# @raise [Parser::UndocumentableError] if the arguments are not valid.
def validated_attribute_names(params)
params.map do |obj|
case obj.type
when :symbol_literal
obj.jump(:ident, :op, :kw, :const).source
when :string_literal
obj.jump(:string_content).source
else
raise YARD::Parser::UndocumentableError, obj.source
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/class_handler.rb 0000644 0000041 0000041 00000010172 13035234564 022141 0 ustar www-data www-data # frozen_string_literal: true
# Handles class declarations
class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
include YARD::Handlers::Ruby::StructHandlerMethods
handles :class, :sclass
namespace_only
process do
classname = statement[0].source.gsub(/\s/, '')
if statement.type == :class
superclass = parse_superclass(statement[1])
if superclass == "Struct"
is_a_struct = true
superclass = struct_superclass_name(statement[1]) # refine the superclass if possible
create_struct_superclass(superclass, statement[1])
end
undocsuper = statement[1] && superclass.nil?
klass = register ClassObject.new(namespace, classname) do |o|
o.superclass = superclass if superclass
o.superclass.type = :class if o.superclass.is_a?(Proxy)
end
if is_a_struct
parse_struct_superclass(klass, statement[1])
elsif klass
create_attributes(klass, members_from_tags(klass))
end
parse_block(statement[2], :namespace => klass)
if undocsuper
raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
end
elsif statement.type == :sclass
if statement[0] == s(:var_ref, s(:kw, "self"))
parse_block(statement[1], :namespace => namespace, :scope => :class)
else
proxy = Proxy.new(namespace, classname)
# Allow constants to reference class names
if ConstantObject === proxy
if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
proxy = Proxy.new(namespace, proxy.value)
else
raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
end
end
if classname[0, 1] =~ /[A-Z]/
register ClassObject.new(namespace, classname) if Proxy === proxy
parse_block(statement[1], :namespace => proxy, :scope => :class)
else
raise YARD::Parser::UndocumentableError, "class '#{classname}'"
end
end
else
sig_end = (statement[1] ? statement[1].source_end : statement[0].source_end) - statement.source_start
raise YARD::Parser::UndocumentableError, "class: #{statement.source[0..sig_end]}"
end
end
private
# Extract the parameters from the Struct.new AST node, returning them as a list
# of strings
#
# @param [MethodCallNode] superclass the AST node for the Struct.new call
# @return [Array] the member names to generate methods for
def extract_parameters(superclass)
members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
members.map! {|x| x.source.strip[1..-1] }
members
end
def create_struct_superclass(superclass, superclass_def)
return if superclass == "Struct"
the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
o.superclass = "Struct"
end
parse_struct_superclass(the_super, superclass_def)
the_super
end
def struct_superclass_name(superclass)
if superclass.call?
first = superclass.parameters.first
if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
return "Struct::#{first[0][0][0]}"
end
end
"Struct"
end
def parse_struct_superclass(klass, superclass)
return unless superclass.call? && superclass.parameters
members = extract_parameters(superclass)
create_attributes(klass, members)
end
def parse_superclass(superclass)
return nil unless superclass
case superclass.type
when :var_ref
return namespace.path if superclass.first == s(:kw, "self")
return superclass.source if superclass.first.type == :const
when :const, :const_ref, :const_path_ref, :top_const_ref
return superclass.source
when :fcall, :command
methname = superclass.method_name.source
return superclass.parameters.first.source if methname == "DelegateClass"
return methname if superclass.method_name.type == :const
when :call, :command_call
cname = superclass.namespace.source
if cname =~ /^O?Struct$/ && superclass.method_name(true) == :new
return cname
end
end
nil
end
end
yard-0.9.7/lib/yard/handlers/ruby/visibility_handler.rb 0000644 0000041 0000041 00000001226 13035234564 023223 0 ustar www-data www-data # frozen_string_literal: true
# Handles 'private', 'protected', and 'public' calls.
class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
include YARD::Handlers::Ruby::DecoratorHandlerMethods
handles method_call(:private)
handles method_call(:protected)
handles method_call(:public)
namespace_only
process do
return if (ident = statement.jump(:ident)) == statement
case statement.type
when :var_ref, :vcall
self.visibility = ident.first.to_sym
when :fcall, :command
process_decorator do |method|
method.visibility = ident.first if method.respond_to? :visibility=
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/class_condition_handler.rb 0000644 0000041 0000041 00000004624 13035234564 024214 0 ustar www-data www-data # frozen_string_literal: true
# Matches if/unless conditions inside classes and attempts to process only
# one branch (by evaluating the condition if possible).
#
# @example A simple class conditional
# class Foo
# if 0
# # This method is ignored
# def xyz; end
# end
# end
class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
handles meta_type(:condition)
namespace_only
process do
condition = parse_condition
if condition.nil?
# Parse both blocks if we're unsure of the condition
parse_then_block
parse_else_block
elsif condition
parse_then_block
else
parse_else_block
end
end
protected
# Parses the condition part of the if/unless statement
#
# @return [true, false, nil] true if the condition can be definitely
# parsed to true, false if not, and nil if the condition cannot be
# parsed with certainty (it's dynamic)
def parse_condition
condition = nil
# Right now we can handle very simple unary conditions like:
# if true
# if false
# if 0
# if 100 (not 0)
# if defined? SOME_CONSTANT
#
# The last case will do a lookup in the registry and then one
# in the Ruby world (using eval).
case statement.condition.type
when :int
condition = statement.condition[0] != "0"
when :defined
# defined? keyword used, let's see if we can look up the name
# in the registry, then we'll try using Ruby's powers. eval() is not
# *too* dangerous here since code is not actually executed.
name = statement.condition[0].source
obj = YARD::Registry.resolve(namespace, name, true)
begin
condition = true if obj || Object.instance_eval("defined? #{name}")
rescue SyntaxError, NameError
condition = false
end
when :var_ref
var = statement.condition[0]
if var == s(:kw, "true")
condition = true
elsif var == s(:kw, "false")
condition = false
end
end
# Invert an unless condition
if statement.type == :unless || statement.type == :unless_mod
condition = !condition unless condition.nil?
end
condition
end
def parse_then_block
parse_block(statement.then_block, :visibility => visibility)
end
def parse_else_block
if statement.else_block
parse_block(statement.else_block, :visibility => visibility)
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/method_handler.rb 0000644 0000041 0000041 00000006600 13035234564 022315 0 ustar www-data www-data # frozen_string_literal: true
# Handles a method definition
class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
handles :def, :defs
process do
meth = statement.method_name(true).to_s
args = format_args
blk = statement.block
nobj = namespace
mscope = scope
if statement.type == :defs
if statement[0][0].type == :ident
raise YARD::Parser::UndocumentableError, 'method defined on object instance'
end
nobj = P(namespace, statement[0].source) if statement[0][0].type == :const
mscope = :class
end
nobj = P(namespace, nobj.value) while nobj.type == :constant
obj = register MethodObject.new(nobj, meth, mscope) do |o|
o.signature = method_signature
o.explicit = true
o.parameters = args
end
# delete any aliases referencing old method
nobj.aliases.each do |aobj, name|
next unless name == obj.name
nobj.aliases.delete(aobj)
end if nobj.is_a?(NamespaceObject)
if obj.constructor?
unless obj.has_tag?(:return)
obj.add_tag(YARD::Tags::Tag.new(:return,
"a new instance of #{namespace.name}", namespace.name.to_s))
end
elsif mscope == :class && obj.docstring.blank? && %w(inherited included
extended method_added method_removed method_undefined).include?(meth)
obj.add_tag(YARD::Tags::Tag.new(:private, nil))
elsif meth.to_s =~ /\?$/
if obj.tag(:return) && (obj.tag(:return).types || []).empty?
obj.tag(:return).types = ['Boolean']
elsif obj.tag(:return).nil?
unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
end
end
end
if obj.has_tag?(:option)
# create the options parameter if its missing
obj.tags(:option).each do |option|
expected_param = option.name
unless obj.tags(:param).find {|x| x.name == expected_param }
new_tag = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", expected_param)
obj.add_tag(new_tag)
end
end
end
info = obj.attr_info
if info
if meth.to_s =~ /=$/ # writer
info[:write] = obj if info[:read]
elsif info[:write]
info[:read] = obj
end
end
parse_block(blk, :owner => obj) # mainly for yield/exceptions
end
def format_args
args = statement.parameters
params = []
if args.unnamed_required_params
params += args.unnamed_required_params.map {|a| [a.source, nil] }
end
if args.unnamed_optional_params
params += args.unnamed_optional_params.map do |a|
[a[0].source, a[1].source]
end
end
params << ['*' + args.splat_param.source, nil] if args.splat_param
if args.unnamed_end_params
params += args.unnamed_end_params.map {|a| [a.source, nil] }
end
if args.named_params
params += args.named_params.map do |a|
[a[0].source, a[1] ? a[1].source : nil]
end
end
if args.double_splat_param
params << ['**' + args.double_splat_param.source, nil]
end
params << ['&' + args.block_param.source, nil] if args.block_param
params
end
def method_signature
method_name = statement.method_name(true)
if statement.parameters.any? {|e| e }
"def #{method_name}(#{statement.parameters.source})"
else
"def #{method_name}"
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/module_handler.rb 0000644 0000041 0000041 00000000521 13035234564 022316 0 ustar www-data www-data # frozen_string_literal: true
# Handles the declaration of a module
class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base
handles :module
namespace_only
process do
modname = statement[0].source
mod = register ModuleObject.new(namespace, modname)
parse_block(statement[1], :namespace => mod)
end
end
yard-0.9.7/lib/yard/handlers/ruby/class_variable_handler.rb 0000644 0000041 0000041 00000000737 13035234564 024014 0 ustar www-data www-data # frozen_string_literal: true
# Handles a class variable (@@variable)
class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
handles :assign
namespace_only
process do
if statement[0].type == :var_field && statement[0][0].type == :cvar
name = statement[0][0][0]
value = statement[1].source
register ClassVariableObject.new(namespace, name) do |o|
o.source = statement
o.value = value
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/yield_handler.rb 0000644 0000041 0000041 00000002064 13035234564 022143 0 ustar www-data www-data # frozen_string_literal: true
# Handles 'yield' calls
class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
handles :yield, :yield0
process do
return unless owner.is_a?(MethodObject) # Only methods yield
return if owner.has_tag? :yield # Don't override yield tags
return if owner.has_tag? :yieldparam # Same thing.
yieldtag = YARD::Tags::Tag.new(:yield, "", [])
if statement.type == :yield
statement.jump(:list).children.each do |item|
if item == s(:var_ref, s(:kw, "self"))
yieldtag.types << '_self'
owner.add_tag YARD::Tags::Tag.new(:yieldparam,
"the object that the method was called on", owner.namespace.path, '_self')
elsif item == s(:zsuper)
yieldtag.types << '_super'
owner.add_tag YARD::Tags::Tag.new(:yieldparam,
"the result of the method from the superclass", nil, '_super')
else
yieldtag.types << item.source
end
end
end
owner.add_tag(yieldtag) unless yieldtag.types.empty?
end
end
yard-0.9.7/lib/yard/handlers/ruby/alias_handler.rb 0000644 0000041 0000041 00000003051 13035234564 022123 0 ustar www-data www-data # frozen_string_literal: true
# Handles alias and alias_method calls
class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
handles :alias, method_call(:alias_method)
namespace_only
process do
names = []
if statement.type == :alias
names = statement.map {|o| o.jump(:ident, :op, :kw, :const).source }
elsif statement.call?
statement.parameters(false).each do |obj|
case obj.type
when :symbol_literal, :dyna_symbol
names << obj.jump(:ident, :op, :kw, :const).source
when :string_literal
names << obj.jump(:string_content).source
end
end
end
raise YARD::Parser::UndocumentableError, "alias/alias_method" if names.size != 2
new_meth = names[0].to_sym
old_meth = names[1].to_sym
old_obj = namespace.child(:name => old_meth, :scope => scope)
new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
o.add_file(parser.file, statement.line)
end
namespace.aliases[new_obj] = old_meth
if old_obj
new_obj.signature = old_obj.signature
new_obj.source = old_obj.source
comments = [old_obj.docstring.to_raw, statement.comments].join("\n")
doc = YARD::Docstring.parser.parse(comments, new_obj, self)
new_obj.docstring = doc.to_docstring
new_obj.docstring.line_range = statement.comments_range
new_obj.docstring.hash_flag = statement.comments_hash_flag
new_obj.docstring.object = new_obj
else
new_obj.signature = "def #{new_meth}" # this is all we know.
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/public_class_method_handler.rb 0000644 0000041 0000041 00000000654 13035234564 025043 0 ustar www-data www-data # frozen_string_literal: true
# Sets visibility of a class method to public.
class YARD::Handlers::Ruby::PublicClassMethodHandler < YARD::Handlers::Ruby::Base
include YARD::Handlers::Ruby::DecoratorHandlerMethods
handles method_call(:public_class_method)
namespace_only
process do
process_decorator :scope => :class do |method|
method.visibility = :public if method.respond_to? :visibility
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/dsl_handler.rb 0000644 0000041 0000041 00000000524 13035234564 021616 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module Ruby
# Handles automatic detection of dsl-style methods
class DSLHandler < Base
include CodeObjects
include DSLHandlerMethods
handles method_call
namespace_only
process { handle_comments }
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/exception_handler.rb 0000644 0000041 0000041 00000001531 13035234564 023031 0 ustar www-data www-data # frozen_string_literal: true
# Handles 'raise' calls inside methods
class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
handles method_call(:raise)
process do
return unless owner.is_a?(MethodObject) # Only methods yield
return if [:command_call, :call].include? statement.type
return if owner.has_tag?(:raise)
klass = nil
if statement.call?
params = statement.parameters(false)
if params.size == 1
if params.first.ref? && params.first.first.type != :ident
klass = params.first.source
elsif params.first.call? && params.first.method_name(true) == :new
klass = params.first.namespace.source
end
elsif params.size > 1
klass = params.first.source
end
end
owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
end
end
yard-0.9.7/lib/yard/handlers/ruby/constant_handler.rb 0000644 0000041 0000041 00000003463 13035234564 022672 0 ustar www-data www-data # frozen_string_literal: true
# Handles any constant assignment
class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
include YARD::Handlers::Ruby::StructHandlerMethods
handles :assign
namespace_only
process do
if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
statement[1][2] == s(:ident, "new")
process_structclass(statement)
elsif statement[0].type == :var_field && statement[0][0].type == :const
process_constant(statement)
elsif statement[0].type == :const_path_field
process_constant(statement)
end
end
private
def process_constant(statement)
name = statement[0].source
value = statement[1].source
obj = P(namespace, name)
if obj.is_a?(NamespaceObject) && obj.namespace == namespace
raise YARD::Parser::UndocumentableError, "constant for existing #{obj.type} #{obj}"
else
ensure_loaded! obj.parent
register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
end
end
def process_structclass(statement)
lhs = statement[0][0]
if lhs.type == :const
klass = create_class(lhs[0], P(:Struct))
create_attributes(klass, extract_parameters(statement[1]))
else
raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
end
end
# Extract the parameters from the Struct.new AST node, returning them as a list
# of strings
#
# @param [MethodCallNode] superclass the AST node for the Struct.new call
# @return [Array] the member names to generate methods for
def extract_parameters(superclass)
return [] unless superclass.parameters
members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
members.map! {|x| x.source.strip[1..-1] }
members
end
end
yard-0.9.7/lib/yard/handlers/ruby/comment_handler.rb 0000644 0000041 0000041 00000000376 13035234564 022503 0 ustar www-data www-data # frozen_string_literal: true
# Handles any lone comment statement in a Ruby file
class YARD::Handlers::Ruby::CommentHandler < YARD::Handlers::Ruby::Base
handles :comment, :void_stmt
namespace_only
process do
register_docstring(nil)
end
end
yard-0.9.7/lib/yard/handlers/ruby/base.rb 0000644 0000041 0000041 00000013360 13035234564 020253 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module Ruby
# To implement a custom handler matcher, subclass this class and implement
# {#matches?} to return whether a node matches the handler.
#
# @example A Custom Handler Matcher Extension
# # Implements a handler that checks for a specific string
# # in the node's source.
# class MyExtension < HandlesExtension
# def matches?(node) node.source.include?(name) end
# end
#
# # This handler will handle any node where the source includes 'foo'
# class MyHandler < Handlers::Ruby::Base
# handles MyExtension.new('foo')
# end
class HandlesExtension
# Creates a new extension with a specific matcher value +name+
# @param [Object] name the matcher value to check against {#matches?}
def initialize(name) @name = name end
# Tests if the node matches the handler
# @param [Parser::Ruby::AstNode] node a Ruby node
# @return [Boolean] whether the +node+ matches the handler
def matches?(node) # rubocop:disable Lint/UnusedMethodArgument
raise NotImplementedError
end
protected
# @return [String] the extension matcher value
attr_reader :name
end
class MethodCallWrapper < HandlesExtension
def matches?(node)
case node.type
when :var_ref
if !node.parent || node.parent.type == :list
return true if node[0].type == :ident && (name.nil? || node[0][0] == name)
end
when :fcall, :command, :vcall
return true if name.nil? || node[0][0] == name
when :call, :command_call
return true if name.nil? || node[2][0] == name
end
false
end
end
class TestNodeWrapper < HandlesExtension
def matches?(node) !node.send(name).is_a?(FalseClass) end
end
# This is the base handler class for the new-style (1.9) Ruby parser.
# All handlers that subclass this base class will be used when the
# new-style parser is used. For implementing legacy handlers, see
# {Legacy::Base}.
#
# @abstract See {Handlers::Base} for subclassing information.
# @see Handlers::Base
# @see Legacy::Base
class Base < Handlers::Base
class << self
include Parser::Ruby
# @group Statement Matcher Extensions
# Matcher for handling any type of method call. Method calls can
# be expressed by many {AstNode} types depending on the syntax
# with which it is called, so YARD allows you to use this matcher
# to simplify matching a method call.
#
# @example Match the "describe" method call
# handles method_call(:describe)
#
# # The following will be matched:
# # describe(...)
# # object.describe(...)
# # describe "argument" do ... end
#
# @param [#to_s] name matches the method call of this name
# @return [void]
def method_call(name = nil)
MethodCallWrapper.new(name ? name.to_s : nil)
end
# Matcher for handling a node with a specific meta-type. An {AstNode}
# has a {AstNode#type} to define its type but can also be associated
# with a set of types. For instance, +:if+ and +:unless+ are both
# of the meta-type +:condition+.
#
# A meta-type is any method on the {AstNode} class ending in "?",
# though you should not include the "?" suffix in your declaration.
# Some examples are: "condition", "call", "literal", "kw", "token",
# "ref".
#
# @example Handling any conditional statement (if, unless)
# handles meta_type(:condition)
# @param [Symbol] type the meta-type to match. A meta-type can be
# any method name + "?" that {AstNode} responds to.
# @return [void]
def meta_type(type)
TestNodeWrapper.new(type.to_s + "?")
end
# @group Testing for a Handler
# @return [Boolean] whether or not an {AstNode} object should be
# handled by this handler
def handles?(node)
handlers.any? do |a_handler|
case a_handler
when Symbol
a_handler == node.type
when String
node.source == a_handler
when Regexp
node.source =~ a_handler
when Parser::Ruby::AstNode
a_handler == node
when HandlesExtension
a_handler.matches?(node)
end
end
end
end
include Parser::Ruby
# @group Parsing an Inner Block
def parse_block(inner_node, opts = {})
push_state(opts) do
nodes = inner_node.type == :list ? inner_node.children : [inner_node]
parser.process(nodes)
end
end
# @group Macro Handling
def call_params
return [] unless statement.respond_to?(:parameters)
statement.parameters(false).compact.map do |param|
if param.type == :list
param.map {|n| n.jump(:ident, :kw, :tstring_content).source }
else
param.jump(:ident, :kw, :tstring_content).source
end
end.flatten
end
def caller_method
if statement.call? || statement.def?
statement.method_name(true).to_s
elsif statement.type == :var_ref || statement.type == :vcall
statement[0].jump(:ident, :kw).source
end
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/private_constant_handler.rb 0000644 0000041 0000041 00000002602 13035234564 024416 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Handlers
module Ruby
# Sets visibility of a constant (class, module, const)
class PrivateConstantHandler < YARD::Handlers::Ruby::Base
handles method_call(:private_constant)
namespace_only
process do
errors = []
statement.parameters.each do |param|
next unless AstNode === param
begin
privatize_constant(param)
rescue UndocumentableError => err
errors << err.message
end
end
unless errors.empty?
msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
raise UndocumentableError, "private constant#{msg} for #{namespace.path}"
end
end
private
def privatize_constant(node)
if node.literal? || (node.type == :var_ref && node[0].type == :const)
node = node.jump(:tstring_content, :const)
const = Proxy.new(namespace, node[0])
ensure_loaded!(const)
const.visibility = :private
else
raise UndocumentableError, "invalid argument to private_constant: #{node.source}"
end
rescue NamespaceMissingError
raise UndocumentableError, "private visibility set on unrecognized constant: #{node[0]}"
end
end
end
end
end
yard-0.9.7/lib/yard/handlers/ruby/private_class_method_handler.rb 0000644 0000041 0000041 00000000661 13035234564 025235 0 ustar www-data www-data # frozen_string_literal: true
# Sets visibility of a class method to private.
class YARD::Handlers::Ruby::PrivateClassMethodHandler < YARD::Handlers::Ruby::Base
include YARD::Handlers::Ruby::DecoratorHandlerMethods
handles method_call(:private_class_method)
namespace_only
process do
process_decorator :scope => :class do |method|
method.visibility = :private if method.respond_to? :visibility=
end
end
end
yard-0.9.7/lib/yard/docstring.rb 0000644 0000041 0000041 00000032306 13035234564 016555 0 ustar www-data www-data # frozen_string_literal: true
module YARD
# A documentation string, or "docstring" for short, encapsulates the
# comments and metadata, or "tags", of an object. Meta-data is expressed
# in the form +@tag VALUE+, where VALUE can span over multiple lines as
# long as they are indented. The following +@example+ tag shows how tags
# can be indented:
#
# # @example My example
# # a = "hello world"
# # a.reverse
# # @version 1.0
#
# Tags can be nested in a documentation string, though the {Tags::Tag}
# itself is responsible for parsing the inner tags.
class Docstring < String
class << self
# @note Plugin developers should make sure to reset this value
# after parsing finishes. This can be done via the
# {Parser::SourceParser.after_parse_list} callback. This will
# ensure that YARD can properly parse multiple projects in
# the same process.
# @return [Class] the parser class used to parse
# text and optional meta-data from docstrings. Defaults to
# {DocstringParser}.
# @see DocstringParser
# @see Parser::SourceParser.after_parse_list
attr_accessor :default_parser
# Creates a parser object using the current {default_parser}.
# Equivalent to:
# Docstring.default_parser.new(*args)
# @param args arguments are passed to the {DocstringParser}
# class. See {DocstringParser#initialize} for details on
# arguments.
# @return [DocstringParser] the parser object used to parse a
# docstring.
def parser(*args) default_parser.new(*args) end
end
self.default_parser = DocstringParser
# @return [Array] the list of reference tags
attr_reader :ref_tags
# @return [CodeObjects::Base] the object that owns the docstring.
attr_accessor :object
# @return [Range] line range in the {#object}'s file where the docstring was parsed from
attr_accessor :line_range
# @return [String] the raw documentation (including raw tag text)
attr_reader :all
# @return [Boolean] whether the docstring was started with "##"
attr_reader :hash_flag
def hash_flag=(v) @hash_flag = v.nil? ? false : v end
# Matches a tag at the start of a comment line
# @deprecated Use {DocstringParser::META_MATCH}
META_MATCH = DocstringParser::META_MATCH
# @group Creating a Docstring Object
# Creates a new docstring without performing any parsing through
# a {DocstringParser}. This method is called by +DocstringParser+
# when creating the new docstring object.
#
# @param [String] text the textual portion of the docstring
# @param [Array] tags the list of tag objects in the docstring
# @param [CodeObjects::Base, nil] object the object associated with the
# docstring. May be nil.
# @param [String] raw_data the complete docstring, including all
# original formatting and any unparsed tags/directives.
# @param [CodeObjects::Base, nil] ref_object a reference object used for
# the base set of documentation / tag information.
def self.new!(text, tags = [], object = nil, raw_data = nil, ref_object = nil)
docstring = allocate
docstring.replace(text, false)
docstring.object = object
docstring.add_tag(*tags)
docstring.instance_variable_set("@unresolved_reference", ref_object)
docstring.instance_variable_set("@all", raw_data) if raw_data
docstring
end
# Creates a new docstring with the raw contents attached to an optional
# object. Parsing will be done by the {DocstringParser} class.
#
# @note To properly parse directives with proper parser context within
# handlers, you should not use this method to create a Docstring.
# Instead, use the {parser}, which takes a handler object that
# can pass parser state onto directives. If a Docstring is created
# with this method, directives do not have access to any parser
# state, and may not function as expected.
# @example
# Docstring.new("hello world\n@return Object return", someobj)
#
# @param [String] content the raw comments to be parsed into a docstring
# and associated meta-data.
# @param [CodeObjects::Base] object an object to associate the docstring
# with.
def initialize(content = '', object = nil)
@object = object
@summary = nil
@hash_flag = false
self.all = content
end
# Adds another {Docstring}, copying over tags.
#
# @param [Docstring, String] other the other docstring (or string) to
# add.
# @return [Docstring] a new docstring with both docstrings combines
def +(other)
case other
when Docstring
Docstring.new([all, other.all].join("\n"), object)
else
super
end
end
def to_s
resolve_reference
super
end
# Replaces the docstring with new raw content. Called by {#all=}.
# @param [String] content the raw comments to be parsed
def replace(content, parse = true)
content = content.join("\n") if content.is_a?(Array)
@tags = []
@ref_tags = []
if parse
super(parse_comments(content))
else
@all = content
@unresolved_reference = nil
super(content)
end
end
alias all= replace
# Deep-copies a docstring
#
# @note This method creates a new docstring with new tag lists, but does
# not create new individual tags. Modifying the tag objects will still
# affect the original tags.
# @return [Docstring] a new copied docstring
# @since 0.7.0
def dup
resolve_reference
obj = super
%w(all summary tags ref_tags).each do |name|
val = instance_variable_defined?("@#{name}") && instance_variable_get("@#{name}")
obj.instance_variable_set("@#{name}", val ? val.dup : nil)
end
obj
end
# @endgroup
# @return [Fixnum] the first line of the {#line_range}
# @return [nil] if there is no associated {#line_range}
def line
line_range ? line_range.first : nil
end
# Gets the first line of a docstring to the period or the first paragraph.
# @return [String] The first line or paragraph of the docstring; always ends with a period.
def summary
resolve_reference
return @summary if defined?(@summary) && @summary
stripped = gsub(/[\r\n](?![\r\n])/, ' ').strip
num_parens = 0
idx = length.times do |index|
case stripped[index, 1]
when "."
next_char = stripped[index + 1, 1].to_s
break index - 1 if num_parens <= 0 && next_char =~ /^\s*$/
when "\r", "\n"
next_char = stripped[index + 1, 1].to_s
if next_char =~ /^\s*$/
break stripped[index - 1, 1] == '.' ? index - 2 : index - 1
end
when "{", "(", "["
num_parens += 1
when "}", ")", "]"
num_parens -= 1
end
end
@summary = stripped[0..idx]
if !@summary.empty? && @summary !~ /\A\s*\{include:.+\}\s*\Z/
@summary += '.'
end
@summary
end
# Reformats and returns a raw representation of the tag data using the
# current tag and docstring data, not the original text.
#
# @return [String] the updated raw formatted docstring data
# @since 0.7.0
# @todo Add Tags::Tag#to_raw and refactor
def to_raw
tag_data = tags.sort_by(&:tag_name).map do |tag|
case tag
when Tags::OverloadTag
tag_text = "@#{tag.tag_name} #{tag.signature}\n"
unless tag.docstring.blank?
tag_text += "\n " + tag.docstring.all.gsub(/\r?\n/, "\n ")
end
when Tags::OptionTag
tag_text = "@#{tag.tag_name} #{tag.name}"
tag_text += ' [' + tag.pair.types.join(', ') + ']' if tag.pair.types
tag_text += ' ' + tag.pair.name.to_s if tag.pair.name
tag_text += "\n " if tag.name && tag.text
tag_text += ' (' + tag.pair.defaults.join(', ') + ')' if tag.pair.defaults
tag_text += " " + tag.pair.text.strip.gsub(/\n/, "\n ") if tag.pair.text
else
tag_text = '@' + tag.tag_name
tag_text += ' [' + tag.types.join(', ') + ']' if tag.types
tag_text += ' ' + tag.name.to_s if tag.name
tag_text += "\n " if tag.name && tag.text
tag_text += ' ' + tag.text.strip.gsub(/\n/, "\n ") if tag.text
end
tag_text
end
[strip, tag_data.join("\n")].reject(&:empty?).compact.join("\n")
end
# @group Creating and Accessing Meta-data
# Adds a tag or reftag object to the tag list. If you want to parse
# tag data based on the {Tags::DefaultFactory} tag factory, use
# {DocstringParser} instead.
#
# @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
# @return [void]
def add_tag(*tags)
tags.each_with_index do |tag, i|
case tag
when Tags::Tag
tag.object = object
@tags << tag
when Tags::RefTag, Tags::RefTagList
@ref_tags << tag
else
raise ArgumentError, "expected Tag or RefTag, got #{tag.class} (at index #{i})"
end
end
end
# Convenience method to return the first tag
# object in the list of tag objects of that name
#
# @example
# doc = Docstring.new("@return zero when nil")
# doc.tag(:return).text # => "zero when nil"
#
# @param [#to_s] name the tag name to return data for
# @return [Tags::Tag] the first tag in the list of {#tags}
def tag(name)
tags.find {|tag| tag.tag_name.to_s == name.to_s }
end
# Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
#
# @param [#to_s] name the tag name to return data for, or nil for all tags
# @return [Array] the list of tags by the specified tag name
def tags(name = nil)
list = @tags + convert_ref_tags
return list unless name
list.select {|tag| tag.tag_name.to_s == name.to_s }
end
# Returns true if at least one tag by the name +name+ was declared
#
# @param [String] name the tag name to search for
# @return [Boolean] whether or not the tag +name+ was declared
def has_tag?(name)
tags.any? {|tag| tag.tag_name.to_s == name.to_s }
end
# Delete all tags with +name+
# @param [String] name the tag name
# @return [void]
# @since 0.7.0
def delete_tags(name)
delete_tag_if {|tag| tag.tag_name.to_s == name.to_s }
end
# Deletes all tags where the block returns true
# @yieldparam [Tags::Tag] tag the tag that is being tested
# @yieldreturn [Boolean] true if the tag should be deleted
# @return [void]
# @since 0.7.0
def delete_tag_if(&block)
@tags.delete_if(&block)
@ref_tags.delete_if(&block)
end
# Returns true if the docstring has no content that is visible to a template.
#
# @param [Boolean] only_visible_tags whether only {Tags::Library.visible_tags}
# should be checked, or if all tags should be considered.
# @return [Boolean] whether or not the docstring has content
def blank?(only_visible_tags = true)
if only_visible_tags
empty? && !tags.any? {|tag| Tags::Library.visible_tags.include?(tag.tag_name.to_sym) }
else
empty? && @tags.empty? && @ref_tags.empty?
end
end
# @endgroup
# Resolves unresolved other docstring reference if there is
# unresolved reference. Does nothing if there is no unresolved
# reference.
#
# Normally, you don't need to call this method
# explicitly. Resolving unresolved reference is done implicitly.
#
# @return [void]
def resolve_reference
loop do
return if defined?(@unresolved_reference).nil? || @unresolved_reference.nil?
return if CodeObjects::Proxy === @unresolved_reference
reference = @unresolved_reference
@unresolved_reference = nil
self.all = [reference.docstring.all, @all].join("\n")
end
end
private
# Maps valid reference tags
#
# @return [Array] the list of valid reference tags
def convert_ref_tags
list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }
@ref_tag_recurse_count ||= 0
@ref_tag_recurse_count += 1
if @ref_tag_recurse_count > 2
log.error "#{@object.file}:#{@object.line}: Detected circular reference tag in " \
"`#{@object}', ignoring all reference tags for this object " \
"(#{@ref_tags.map {|t| "@#{t.tag_name}" }.join(", ")})."
@ref_tags = []
return @ref_tags
end
list = list.map(&:tags).flatten
@ref_tag_recurse_count -= 1
list
end
# Parses out comments split by newlines into a new code object
#
# @param [String] comments
# the newline delimited array of comments. If the comments
# are passed as a String, they will be split by newlines.
#
# @return [String] the non-metadata portion of the comments to
# be used as a docstring
def parse_comments(comments)
parser = self.class.parser
parser.parse(comments, object)
@all = parser.raw_text
@unresolved_reference = parser.reference
add_tag(*parser.tags)
parser.text
end
end
end
yard-0.9.7/lib/yard/templates/ 0000755 0000041 0000041 00000000000 13035234564 016226 5 ustar www-data www-data yard-0.9.7/lib/yard/templates/template_options.rb 0000644 0000041 0000041 00000007152 13035234564 022146 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
module YARD
module Templates
# An Options class containing default options for base template rendering. For
# options specific to generation of HTML output, see {CLI::YardocOptions}.
#
# @see CLI::YardocOptions
class TemplateOptions < YARD::Options
# @return [Symbol] the template output format
default_attr :format, :text
# @return [Symbol] the template name used to render output
default_attr :template, :default
# @return [Symbol] the markup format to use when parsing docstrings
default_attr :markup, :rdoc # default is :rdoc but falls back on :none
# @return [String] the default return type for a method with no return tags
default_attr :default_return, "Object"
# @return [Boolean] whether void methods should show "void" in their signature
default_attr :hide_void_return, false
# @return [Boolean] whether code blocks should be syntax highlighted
default_attr :highlight, true
# @return [Class] the markup provider class for the markup format
attr_accessor :markup_provider
# @return [OpenStruct] an open struct containing any global state across all
# generated objects in a template.
default_attr :globals, lambda { OpenStruct.new }
alias __globals globals
# @return [CodeObjects::Base] the main object being generated in the template
attr_accessor :object
# @return [CodeObjects::Base] the owner of the generated object
attr_accessor :owner
# @return [Symbol] the template type used to generate output
attr_accessor :type
# @return [Boolean] whether serialization should be performed
default_attr :serialize, true
# @return [Serializers::Base] the serializer used to generate links and serialize
# output. Serialization output only occurs if {#serialize} is +true+.
attr_accessor :serializer
# @deprecated use {#highlight} instead.
# @return [Boolean] whether highlighting should be ignored
attr_reader :no_highlight
undef no_highlight
def no_highlight; !highlight end
def no_highlight=(value) self.highlight = !value end
# @return [String] the title of a given page
attr_accessor :page_title
# @return [Boolean] whether the page is the "index"
attr_accessor :index
# @example A list of mixin path names (including wildcards)
# opts.embed_mixins #=> ['ClassMethods', '*Helper', 'YARD::*']
# @return [Array] an array of module name wildcards to embed into
# class documentation as if their methods were defined directly in the class.
# Useful for modules like ClassMethods. If the name contains '::', the module
# is matched against the full mixin path, otherwise only the module name is used.
default_attr :embed_mixins, lambda { [] }
# @param [CodeObjects::Base] mixin accepts any code object, but returns
# nil unless the object is a module.
# @return [Boolean] whether a mixin matches the embed_mixins list
# @return [nil] if the mixin is not a module object
def embed_mixins_match?(mixin)
return true if mixin == object # the method is not inherited
return nil unless mixin.is_a?(CodeObjects::ModuleObject)
embed_mixins.any? do |embed_mixin|
re = /\A#{Regexp.quote(embed_mixin).gsub('\*', '.*')}\Z/
matchstr = embed_mixin.include?("::") ? mixin.path : mixin.name
re.match(matchstr.to_s)
end
end
# @return [Verifier] the verifier object
attr_accessor :verifier
end
end
end
yard-0.9.7/lib/yard/templates/erb_cache.rb 0000644 0000041 0000041 00000001107 13035234564 020445 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates
# @since 0.5.4
module ErbCache
def self.method_for(filename)
@methods ||= {}
return @methods[filename] if @methods[filename]
@methods[filename] = name = "_erb_cache_#{@methods.size}"
erb = yield.src
encoding = erb[/\A(#coding[:=].*\r?\n)/, 1] || ''
module_eval "#{encoding}def #{name}; #{erb}; end", filename
name
end
def self.clear!
return unless defined?(@methods) && @methods
@methods.clear
end
end
end
end
yard-0.9.7/lib/yard/templates/section.rb 0000644 0000041 0000041 00000004524 13035234564 020224 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates
# Abstracts the structure for a section and its subsections into an ordered
# list of sections and subsections.
# @since 0.6.0
class Section < Array
attr_accessor :name
def initialize(name, *args)
self.name = name
replace(parse_sections(args))
end
def dup
obj = super
obj.name = name
obj
end
def [](*args)
if args.first.is_a?(Range) || args.size > 1
obj = super(*args)
obj.name = name
return obj
elsif args.first.is_a?(Integer)
return super(*args)
end
find {|o| o.name == args.first }
end
def eql?(other)
super(other) && name == other.name
end
def ==(other)
case other
when Section
eql?(other)
when Array
to_a == other
else
name == other
end
end
def push(*args)
super(*parse_sections(args))
end
alias << push
def unshift(*args)
super(*parse_sections(args))
end
def inspect
n = name.respond_to?(:path) ? "T('#{name.path}')" : name.inspect
subsects = empty? ? "" : ", subsections=#{super}"
"Section(#{n}#{subsects})"
end
def place(*args)
super(*parse_sections(args))
end
def to_a
list = [name]
unless empty?
subsects = []
each {|s| subsects += s.to_a }
list << subsects
end
list
end
def any(item)
find do |section|
return section if section == item
return section.any(item) unless section.empty?
end
nil
end
private
def parse_sections(args)
if args.size == 1 && args.first.is_a?(Array) && !args.first.is_a?(Section)
args = args.first
end
sections = []
args.each_with_index do |name, index|
case name
when Section; sections << name
when Array; next
else
subsections = args[index + 1].is_a?(Array) ? args[index + 1] : []
subsections = [] if subsections.is_a?(Section)
sections << Section.new(name, subsections)
end
end
sections
end
end
end
end
yard-0.9.7/lib/yard/templates/engine.rb 0000644 0000041 0000041 00000016552 13035234564 020031 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
module YARD
module Templates
# This module manages all creation, handling and rendering of {Template}
# objects.
#
# * To create a template object at a path, use {template}.
# * To render a template, call {render}.
# * To register a template path in the lookup paths, call {register_template_path}.
module Engine
class << self
# @return [Array] the list of registered template paths
attr_accessor :template_paths
# Registers a new template path in {template_paths}
#
# @param [String] path a new template path
# @return [void]
def register_template_path(path)
template_paths.push(path) unless template_paths.include?(path)
end
# Creates a template module representing the path. Searches on disk
# for the first directory named +path+ (joined by '/') within the
# template paths and builds a template module for. All other matching
# directories in other template paths will be included in the
# generated module as mixins (for overriding).
#
# @param [Array] path a list of path components
# @raise [ArgumentError] if the path does not exist within one of the
# {template_paths} on disk.
# @return [Template] the module representing the template
def template(*path)
from_template = nil
from_template = path.shift if path.first.is_a?(Template)
path = path.join('/')
full_paths = find_template_paths(from_template, path)
path = File.cleanpath(path).gsub('../', '')
raise ArgumentError, "No such template for #{path}" if full_paths.empty?
mod = template!(path, full_paths)
mod
end
# Forces creation of a template at +path+ within a +full_path+.
#
# @param [String] path the path name of the template
# @param [Array] full_paths the full path on disk of the template
# @return [Template] the template module representing the +path+
def template!(path, full_paths = nil)
full_paths ||= [path]
full_paths = [full_paths] unless full_paths.is_a?(Array)
name = template_module_name(full_paths.first)
begin; return const_get(name); rescue NameError; nil end
mod = const_set(name, Module.new)
mod.send(:include, Template)
mod.send(:initialize, path, full_paths)
mod
end
# Renders a template on a {CodeObjects::Base code object} using
# a set of default (overridable) options. Either the +:object+
# or +:type+ keys must be provided.
#
# If a +:serializer+ key is provided and +:serialize+ is not set to
# false, the rendered contents will be serialized through the {Serializers::Base}
# object. See {with_serializer}.
#
# @example Renders an object with html formatting
# Engine.render(:format => :html, :object => obj)
# @example Renders without an object
# Engine.render(:type => :fulldoc, :otheropts => somevalue)
# @param [Hash] options the options hash
# @option options [Symbol] :format (:text) the default format
# @option options [Symbol] :type (nil) the :object's type.
# @option options [Symbol] :template (:default) the default template
# @return [String] the rendered template
def render(options = {})
options = set_default_options(options)
mod = template(options.template, options.type, options.format)
if options.serializer && options.serialize != false
with_serializer(options.object, options.serializer) { mod.run(options) }
else
mod.run(options)
end
end
# Passes a set of objects to the +:fulldoc+ template for full documentation generation.
# This is called by {CLI::Yardoc} to most commonly perform HTML
# documentation generation.
#
# @param [Array] objects a list of {CodeObjects::Base}
# objects to pass to the template
# @param [Hash] options (see {render})
# @return [void]
def generate(objects, options = {})
options = set_default_options(options)
options.objects = objects
options.object = Registry.root
template(options.template, :fulldoc, options.format).run(options)
end
# Serializes the results of a block with a +serializer+ object.
#
# @param [CodeObjects::Base] object the code object to serialize
# @param [Serializers::Base] serializer the serializer object
# @yield a block whose result will be serialize
# @yieldreturn [String] the contents to serialize
# @see Serializers::Base
def with_serializer(object, serializer)
output = nil
filename = serializer.serialized_path(object)
if serializer.respond_to?(:basepath)
filename = File.join(serializer.basepath, filename)
end
log.capture("Generating #{filename}", nil) do
serializer.before_serialize if serializer
output = yield
if serializer
serializer.serialize(object, output)
serializer.after_serialize(output)
end
end
output
end
private
# Sets default options on the options hash
#
# @param [Hash] options the options hash
# @option options [Symbol] :format (:text) the default format
# @option options [Symbol] :type (nil) the :object's type, if provided
# @option options [Symbol] :template (:default) the default template
# @return [void]
def set_default_options(options = {})
if options.is_a?(Hash)
options = TemplateOptions.new.tap do |o|
o.reset_defaults
o.update(options)
end
end
options.type ||= options.object.type if options.object
options
end
# Searches through the registered {template_paths} and returns
# all full directories that have the +path+ within them on disk.
#
# @param [Template] from_template if provided, allows a relative
# path to be specified from this template's full path.
# @param [String] path the path component to search for in the
# {template_paths}
# @return [Array] a list of full paths that are existing
# candidates for a template module
def find_template_paths(from_template, path)
paths = template_paths.dup
paths = from_template.full_paths + paths if from_template
paths.inject([]) do |acc, tp|
full_path = File.cleanpath(File.join(tp, path))
acc.unshift(full_path) if File.directory?(full_path)
acc
end.uniq
end
# The name of the module that represents a +path+
#
# @param [String] path the path to generate a module name for
# @return [String] the module name
def template_module_name(path)
'Template_' + path.to_s.gsub(/[^a-z0-9]/i, '_')
end
end
self.template_paths = []
end
Engine.register_template_path(File.join(YARD::ROOT, '..', 'templates'))
end
end
yard-0.9.7/lib/yard/templates/helpers/ 0000755 0000041 0000041 00000000000 13035234564 017670 5 ustar www-data www-data yard-0.9.7/lib/yard/templates/helpers/markup/ 0000755 0000041 0000041 00000000000 13035234564 021167 5 ustar www-data www-data yard-0.9.7/lib/yard/templates/helpers/markup/rdoc_markdown.rb 0000644 0000041 0000041 00000001041 13035234564 024341 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates
module Helpers
module Markup
begin require 'rdoc'; rescue LoadError; nil end
begin
require 'rdoc/markdown'
rescue LoadError
raise NameError, "could not load RDoc Markdown support (rdoc is too old)"
end
class RDocMarkdown < RDocMarkup
def initialize(text)
super RDoc::Markdown.new.parse(text)
end
def fix_typewriter(html) html end
end
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/markup/rdoc_markup.rb 0000644 0000041 0000041 00000006252 13035234564 024027 0 ustar www-data www-data # frozen_string_literal: true
require 'thread'
module YARD
module Templates
module Helpers
module Markup
begin require 'rdoc'; rescue LoadError; nil end
begin
require 'rdoc/markup'
require 'rdoc/markup/to_html'
class RDocMarkup; MARKUP = RDoc::Markup end
class RDocMarkupToHtml < RDoc::Markup::ToHtml
if defined?(RDoc::VERSION) && RDoc::VERSION >= '4.0.0' &&
defined?(RDoc::Options)
def initialize
options = RDoc::Options.new
options.pipe = true
super(options)
end
end
end
rescue LoadError
begin
require 'rdoc/markup/simple_markup'
require 'rdoc/markup/simple_markup/to_html'
class RDocMarkup; MARKUP = SM::SimpleMarkup end
class RDocMarkupToHtml < SM::ToHtml; end
rescue LoadError
raise NameError, "could not load RDocMarkup (rdoc is not installed)"
end
end
class RDocMarkup
attr_accessor :from_path
@@formatter = nil
@@markup = nil
@@mutex = nil
def initialize(text)
@text = text
@@formatter ||= RDocMarkupToHtml.new
@@markup ||= MARKUP.new
@@mutex ||= Mutex.new
end
def to_html
html = nil
@@mutex.synchronize do
@@formatter.from_path = from_path
html = @@markup.convert(@text, @@formatter)
end
html = fix_dash_dash(html)
html = fix_typewriter(html)
html
end
private
# Fixes RDoc behaviour with ++ only supporting alphanumeric text.
#
# @todo Refactor into own SimpleMarkup subclass
def fix_typewriter(text)
code_tags = 0
text.gsub(%r{<(/)?(pre|code|tt)|(\s|^|>)\+(?! )([^\n\+]{1,900})(?! )\+}) do |str|
closed = $1
tag = $2
first_text = $3
type_text = $4
if tag
code_tags += (closed ? -1 : 1)
next str
end
next str unless code_tags == 0
first_text + '' + type_text + ''
end
end
# Don't allow -- to turn into — element. The chances of this being
# some --option is far more likely than the typographical meaning.
#
# @todo Refactor into own SimpleMarkup subclass
def fix_dash_dash(text)
text.gsub(/—(?=\S)/, '--')
end
end
class RDocMarkupToHtml
attr_accessor :from_path
# Disable auto-link of URLs
def handle_special_HYPERLINK(special) # rubocop:disable Style/MethodName
@hyperlink ? special.text : super
end
def accept_paragraph(*args)
par = args.last
text = par.respond_to?(:txt) ? par.txt : par.text
@hyperlink = text =~ /\{(https?:|mailto:|link:|www\.)/ ? true : false
super
end
end
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/html_syntax_highlight_helper.rb 0000644 0000041 0000041 00000005345 13035234564 026164 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates
module Helpers
# Helper methods for syntax highlighting.
module HtmlSyntaxHighlightHelper
include ModuleHelper
# Highlights Ruby source
# @param [String] source the Ruby source code
# @return [String] the highlighted Ruby source
def html_syntax_highlight_ruby(source)
if Parser::SourceParser.parser_type == :ruby
html_syntax_highlight_ruby_ripper(source)
else
html_syntax_highlight_ruby_legacy(source)
end
end
private
def html_syntax_highlight_ruby_ripper(source)
resolver = Parser::Ruby::TokenResolver.new(source, object)
output = String.new("")
resolver.each do |s, token_obj|
token_obj = clean_token_object(token_obj)
output << "" if [:tstring_beg, :regexp_beg].include?(s[0])
case s.first
when :nl, :ignored_nl, :sp
output << h(s[1])
when :ident, :const
klass = s.first == :ident ? "id identifier rubyid_#{h(s[1])}" : s.first
val = token_obj ? link_object(token_obj, s[1]) : h(s[1])
output << "#{val}"
else
output << "#{h(s[1])}"
end
output << "" if [:tstring_end, :regexp_end].include?(s[0])
end
output
rescue Parser::ParserSyntaxError
h(source)
end
def html_syntax_highlight_ruby_legacy(source)
tokenlist = Parser::Ruby::Legacy::TokenList.new(source)
tokenlist.map do |s|
prettyclass = s.class.class_name.sub(/^Tk/, '').downcase
prettysuper = s.class.superclass.class_name.sub(/^Tk/, '').downcase
case s
when Parser::Ruby::Legacy::RubyToken::TkWhitespace, Parser::Ruby::Legacy::RubyToken::TkUnknownChar
h s.text
when Parser::Ruby::Legacy::RubyToken::TkId
prettyval = h(s.text)
"#{prettyval}"
else
"#{h s.text}"
end
end.join
end
def clean_token_object(token_obj)
return unless token_obj
if token_obj == object
token_obj = nil
elsif token_obj.is_a?(CodeObjects::MethodObject)
token_obj = prune_method_listing([token_obj], false).first
else
token_obj = run_verifier([token_obj]).first
end
token_obj
end
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/base_helper.rb 0000644 0000041 0000041 00000015771 13035234564 022501 0 ustar www-data www-data # frozen_string_literal: true
module YARD::Templates::Helpers
# The base helper module included in all templates.
module BaseHelper
attr_accessor :object, :serializer
# @return [CodeObjects::Base] the object representing the current generated
# page. Might not be the current {#object} when inside sub-templates.
attr_reader :owner
undef owner
def owner; (defined?(@owner) && @owner) || object.namespace end
# @group Managing Global Template State
# An object that keeps track of global state throughout the entire template
# rendering process (including any sub-templates).
#
# @return [OpenStruct] a struct object that stores state
# @since 0.6.0
def globals; options.globals end
# @group Running the Verifier
# Runs a list of objects against the {Verifier} object passed into the
# template and returns the subset of verified objects.
#
# @param [Array] list a list of code objects
# @return [Array] a list of code objects that match
# the verifier. If no verifier is supplied, all objects are returned.
def run_verifier(list)
options.verifier ? options.verifier.run(list) : list
end
# @group Escaping Text
# Escapes text. This is used a lot by the HtmlHelper and there should
# be some helper to "clean up" text for whatever, this is it.
def h(text)
text
end
# @group Linking Objects and URLs
# Links objects or URLs. This method will delegate to the correct +link_+
# method depending on the arguments passed in.
#
# @example Linking a URL
# linkify('http://example.com')
# @example Including docstring contents of an object
# linkify('include:YARD::Docstring')
# @example Linking to an extra file
# linkify('file:README')
# @example Linking an object by path
# linkify('YARD::Docstring')
def linkify(*args)
if args.first.is_a?(String)
case args.first
when %r{://}, /^mailto:/
link_url(args[0], args[1], {:target => '_parent'}.merge(args[2] || {}))
when /^include:file:(\S+)/
file = $1
relpath = File.relative_path(Dir.pwd, File.expand_path(file))
if relpath =~ /^\.\./
log.warn "Cannot include file from path `#{file}'"
""
elsif File.file?(file)
link_include_file(file)
else
log.warn "Cannot find file at `#{file}' for inclusion"
""
end
when /^include:(\S+)/
path = $1
obj = YARD::Registry.resolve(object.namespace, path)
if obj
link_include_object(obj)
else
log.warn "Cannot find object at `#{path}' for inclusion"
""
end
when /^render:(\S+)/
path = $1
obj = YARD::Registry.resolve(object, path)
if obj
opts = options.dup
opts.delete(:serializer)
obj.format(opts)
else
''
end
when /^file:(\S+?)(?:#(\S+))?$/
link_file($1, args[1] ? args[1] : nil, $2)
else
link_object(*args)
end
else
link_object(*args)
end
end
# Includes an object's docstring into output.
# @since 0.6.0
# @param [CodeObjects::Base] obj the object to include
# @return [String] the object's docstring (no tags)
def link_include_object(obj)
obj.docstring
end
# Include a file as a docstring in output
# @since 0.7.0
# @param [String] file the filename to include
# @return [String] the file's contents
def link_include_file(file)
File.read(file)
end
# Links to an object with an optional title
#
# @param [CodeObjects::Base] obj the object to link to
# @param [String] title the title to use for the link
# @return [String] the linked object
def link_object(obj, title = nil)
return title if title
case obj
when YARD::CodeObjects::Base, YARD::CodeObjects::Proxy
obj.title
when String, Symbol
P(obj).title
else
obj
end
end
# Links to a URL
#
# @param [String] url the URL to link to
# @param [String] title the optional title to display the link as
# @param [Hash] params optional parameters for the link
# @return [String] the linked URL
def link_url(url, title = nil, params = nil) # rubocop:disable Lint/UnusedMethodArgument
url
end
# Links to an extra file
#
# @param [String] filename the filename to link to
# @param [String] title the title of the link
# @param [String] anchor optional anchor
# @return [String] the link to the file
# @since 0.5.5
def link_file(filename, title = nil, anchor = nil) # rubocop:disable Lint/UnusedMethodArgument
return filename.filename if CodeObjects::ExtraFileObject === filename
filename
end
# @group Formatting Object Attributes
# Formats a list of return types for output and links each type.
#
# @example Formatting types
# format_types(['String', 'Array']) #=> "(String, Array)"
# @example Formatting types without surrounding brackets
# format_types(['String', 'Array'], false) #=> "String, Array"
# @param [Array] list a list of types
# @param [Boolean] brackets whether to surround the types in brackets
# @return [String] the formatted list of Ruby types
def format_types(list, brackets = true)
list.nil? || list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
end
# @example Formatted type of an exception class
# o = ClassObject.new(:root, :MyError)
# o.superclass = P('RuntimeError')
# format_object_type(o) # => "Exception"
# @example Formatted type of a method
# o = MethodObject.new(:root, :to_s)
# format_object_type(o) # => "Method"
# @param [CodeObjects::Base] object the object to retrieve the type for
# @return [String] the human-readable formatted {CodeObjects::Base#type #type}
# for the object
def format_object_type(object)
case object
when YARD::CodeObjects::ClassObject
object.is_exception? ? "Exception" : "Class"
else
object.type.to_s.capitalize
end
end
# @example
# s = format_object_title ModuleObject.new(:root, :MyModuleName)
# s # => "Module: MyModuleName"
# @param [CodeObjects::Base] object the object to retrieve a title for
# @return [String] the page title name for a given object
def format_object_title(object)
case object
when YARD::CodeObjects::RootObject
"Top Level Namespace"
else
format_object_type(object) + ": " + object.title
end
end
# Indents and formats source code
#
# @param [String] value the input source code
# @return [String] formatted source code
def format_source(value)
sp = value.split("\n").last[/^(\s+)/, 1]
num = sp ? sp.size : 0
value.gsub(/^\s{#{num}}/, '')
end
end
end
yard-0.9.7/lib/yard/templates/helpers/html_helper.rb 0000644 0000041 0000041 00000053734 13035234564 022534 0 ustar www-data www-data # frozen_string_literal: true
require 'cgi'
module YARD
module Templates::Helpers
# The helper module for HTML templates.
module HtmlHelper
include MarkupHelper
include HtmlSyntaxHighlightHelper
# @private
URLMATCH = /[^\w\s~!\*'\(\):;@&=\$,\[\]<>-]/
# @group Escaping Template Data
# Escapes HTML entities
#
# @param [String] text the text to escape
# @return [String] the HTML with escaped entities
def h(text)
CGI.escapeHTML(text.to_s)
end
# Escapes a URL
#
# @param [String] text the URL
# @return [String] the escaped URL
def urlencode(text)
text = text.dup
enc = nil
if text.respond_to?(:force_encoding)
enc = text.encoding
text = text.force_encoding('binary')
end
text = text.gsub(/%[a-z0-9]{2}|#{URLMATCH}/i) do
$&.size > 1 ? $& : "%" + $&.ord.to_s(16).upcase
end.tr(' ', '+')
text = text.force_encoding(enc) if enc
text
end
module_function :urlencode
# @group Converting Markup to HTML
# Turns text into HTML using +markup+ style formatting.
#
# @param [String] text the text to format
# @param [Symbol] markup examples are +:markdown+, +:textile+, +:rdoc+.
# To add a custom markup type, see {MarkupHelper}
# @return [String] the HTML
def htmlify(text, markup = options.markup)
markup_meth = "html_markup_#{markup}"
return text unless respond_to?(markup_meth)
return "" unless text
return text unless markup
html = send(markup_meth, text).dup
if html.respond_to?(:encode)
html = html.force_encoding(text.encoding) # for libs that mess with encoding
html = html.encode(:invalid => :replace, :replace => '?')
end
html = resolve_links(html)
unless [:text, :none, :pre].include?(markup)
html = parse_codeblocks(html)
end
html
end
# Converts Markdown to HTML
# @param [String] text input Markdown text
# @return [String] output HTML
# @since 0.6.0
def html_markup_markdown(text)
# TODO: other libraries might be more complex
provider = markup_class(:markdown)
if provider.to_s == 'RDiscount'
provider.new(text, :autolink).to_html
elsif provider.to_s == 'RedcarpetCompat'
provider.new(text, :no_intraemphasis, :gh_blockcode,
:fenced_code, :autolink, :tables,
:lax_spacing).to_html
else
provider.new(text).to_html
end
end
# Converts Asciidoc to HTML
# @param [String] text input Asciidoc text
# @return [String] output HTML
def html_markup_asciidoc(text)
markup_class(:asciidoc).render(text)
end
# Converts Textile to HTML
# @param [String] text the input Textile text
# @return [String] output HTML
# @since 0.6.0
def html_markup_textile(text)
doc = markup_class(:textile).new(text)
doc.hard_breaks = false if doc.respond_to?(:hard_breaks=)
doc.to_html
end
# Converts plaintext to strict Textile (hard breaks)
# @param [String] text the input textile data
# @return [String] the output HTML
# @since 0.6.0
def html_markup_textile_strict(text)
markup_class(:textile).new(text).to_html
end
# Converts RDoc formatting (SimpleMarkup) to HTML
# @param [String] text the input RDoc formatted text
# @return [String] output HTML
# @since 0.6.0
def html_markup_rdoc(text)
doc = markup_class(:rdoc).new(text)
doc.from_path = url_for(object) if doc.respond_to?(:from_path=)
doc.to_html
end
# Converts plaintext to pre-formatted HTML
# @param [String] text the input text
# @return [String] the output HTML
# @since 0.6.0
def html_markup_pre(text)
"" + h(text) + "
"
end
# Converts plaintext to regular HTML
# @param [String] text the input text
# @return [String] the output HTML
# @since 0.6.0
def html_markup_text(text)
h(text).gsub(/\r?\n/, '
')
end
# @return [String] the same text with no markup
# @since 0.6.6
def html_markup_none(text)
h(text)
end
# Converts HTML to HTML
# @param [String] text input html
# @return [String] output HTML
# @since 0.6.0
def html_markup_html(text)
text
end
# Highlights Ruby source. Similar to {#html_syntax_highlight}, but
# this method is meant to be called from {#htmlify} when markup is
# set to "ruby".
#
# @param [String] source the Ruby source
# @return [String] the highlighted HTML
# @since 0.7.0
def html_markup_ruby(source)
'' + html_syntax_highlight(source, :ruby) + '
'
end
# @return [String] HTMLified text as a single line (paragraphs removed)
def htmlify_line(*args)
"" + htmlify(*args) + ""
end
# @group Syntax Highlighting Source Code
# Syntax highlights +source+ in language +type+.
#
# @note To support a specific language +type+, implement the method
# +html_syntax_highlight_TYPE+ in this class.
#
# @param [String] source the source code to highlight
# @param [Symbol, String] type the language type (:ruby, :plain, etc). Use
# :plain for no syntax highlighting.
# @return [String] the highlighted source
def html_syntax_highlight(source, type = nil)
return "" unless source
return h(source) unless options.highlight
new_type, source = parse_lang_for_codeblock(source)
type ||= new_type || :ruby
meth = "html_syntax_highlight_#{type}"
respond_to?(meth) ? send(meth, source) : h(source)
end
# @return [String] unhighlighted source
def html_syntax_highlight_plain(source)
h(source)
end
# @group Linking Objects and URLs
# Resolves any text in the form of +{Name}+ to the object specified by
# Name. Also supports link titles in the form +{Name title}+.
#
# @example Linking to an instance method
# resolve_links("{MyClass#method}") # => "MyClass#method"
# @example Linking to a class with a title
# resolve_links("{A::B::C the C class}") # => "the c class"
# @param [String] text the text to resolve links in
# @return [String] HTML with linkified references
def resolve_links(text)
code_tags = 0
text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+.*\s*(.*)\Z}
name = $1
title = $2
title = nil if title.empty?
end
name = CGI.unescapeHTML(name)
if object.is_a?(String)
object
else
link = linkify(name, title)
if (link == name || link == title) && (name + ' ' + link !~ /\A/)
match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text)
file = (defined?(@file) && @file ? @file.filename : object.file) || '(unknown)'
line = (defined?(@file) && @file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0)
log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".") +
"\n\t" + (match[1] ? '...' : '') + match[2].delete("\n") + (match[3] ? '...' : '') if match
end
link
end
end
end
# (see BaseHelper#link_file)
def link_file(filename, title = nil, anchor = nil)
if CodeObjects::ExtraFileObject === filename
file = filename
else
contents = File.file?(filename) ? nil : ''
file = CodeObjects::ExtraFileObject.new(filename, contents)
end
return title || file.title unless serializer
link_url(url_for_file(file, anchor), title || file.title)
end
# (see BaseHelper#link_include_file)
def link_include_file(file)
unless file.is_a?(CodeObjects::ExtraFileObject)
file = CodeObjects::ExtraFileObject.new(file)
end
file.attributes[:markup] ||= markup_for_file('', file.filename)
insert_include(file.contents, file.attributes[:markup] || options.markup)
end
# (see BaseHelper#link_include_object)
def link_include_object(obj)
insert_include(obj.docstring)
end
# Inserts an include link while respecting inlining
def insert_include(text, markup = options.markup)
htmlify(text, markup).gsub(%r{\A\s*|
\s*\Z}, '')
end
# (see BaseHelper#link_object)
def link_object(obj, title = nil, anchor = nil, relative = true)
return title if obj.nil?
obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String)
if title
title = title.to_s
elsif object.is_a?(CodeObjects::Base)
# Check if we're linking to a class method in the current
# object. If we are, create a title in the format of
# "CurrentClass.method_name"
if obj.is_a?(CodeObjects::MethodObject) && obj.scope == :class && obj.parent == object
title = h([object.name, obj.sep, obj.name].join)
elsif obj.title != obj.path
title = h(obj.title)
else
title = h(object.relative_path(obj))
end
else
title = h(obj.title)
end
return title unless serializer
return title if obj.is_a?(CodeObjects::Proxy)
link = url_for(obj, anchor, relative)
link = link ? link_url(link, title, :title => h("#{obj.title} (#{obj.type})")) : title
"" + link + ""
end
# (see BaseHelper#link_url)
def link_url(url, title = nil, params = {})
title ||= url
title = title.gsub(/[\r\n]/, ' ')
params = SymbolHash.new(false).update(
:href => url,
:title => h(title)
).update(params)
params[:target] ||= '_parent' if url =~ %r{^(\w+)://}
"#{title}".gsub(/[\r\n]/, ' ')
end
# @group URL Helpers
# @param [CodeObjects::Base] object the object to get an anchor for
# @return [String] the anchor for a specific object
def anchor_for(object)
case object
when CodeObjects::MethodObject
"#{object.name}-#{object.scope}_#{object.type}"
when CodeObjects::ClassVariableObject
"#{object.name.to_s.gsub('@@', '')}-#{object.type}"
when CodeObjects::Base
"#{object.name}-#{object.type}"
when CodeObjects::Proxy
object.path
else
object.to_s
end
end
# Returns the URL for an object.
#
# @param [String, CodeObjects::Base] obj the object (or object path) to link to
# @param [String] anchor the anchor to link to
# @param [Boolean] relative use a relative or absolute link
# @return [String] the URL location of the object
def url_for(obj, anchor = nil, relative = true)
link = nil
return link unless serializer
return link if obj.is_a?(CodeObjects::Base) && run_verifier([obj]).empty?
if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
# If the obj is not a namespace obj make it the anchor.
anchor = obj
obj = obj.namespace
end
objpath = serializer.serialized_path(obj)
return link unless objpath
relative = false if object == Registry.root
if relative
fromobj = object
if object.is_a?(CodeObjects::Base) &&
!object.is_a?(CodeObjects::NamespaceObject)
fromobj = owner
end
from = serializer.serialized_path(fromobj)
link = File.relative_path(from, objpath)
else
link = objpath
end
link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
end
alias mtime_url url_for
def mtime(_file) nil end
# Returns the URL for a specific file
#
# @param [String, CodeObjects::ExtraFileObject] filename the filename to link to
# @param [String] anchor optional anchor
# @return [String] the URL pointing to the file
def url_for_file(filename, anchor = nil)
return '' unless serializer
fromobj = object
if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
fromobj = fromobj.namespace
end
from = serializer.serialized_path(fromobj)
path = filename == options.readme ?
'index.html' : serializer.serialized_path(filename)
link = File.relative_path(from, path)
link += (anchor ? '#' + urlencode(anchor) : '')
link
end
# Returns the URL for a list type
#
# @param [String, Symbol] type the list type to generate a URL for
# @return [String] the URL pointing to the list
# @since 0.8.0
def url_for_list(type)
url_for_file("#{type}_list.html")
end
# Returns the URL for the frameset page
#
# @return [String] the URL pointing to the frames page
# @since 0.8.0
def url_for_frameset
url_for_file("frames.html")
end
# Returns the URL for the main page (README or alphabetic index)
#
# @return [String] the URL pointing to the first main page the
# user should see.
def url_for_main
url_for_file("index.html")
end
# Returns the URL for the alphabetic index page
#
# @return [String] the URL pointing to the first main page the
# user should see.
def url_for_index
url_for_file("_index.html")
end
# @group Formatting Objects and Attributes
# Formats a list of objects and links them
# @return [String] a formatted list of objects
def format_object_name_list(objects)
objects.sort_by {|o| o.name.to_s.downcase }.map do |o|
"" + linkify(o, o.name) + ""
end.join(", ")
end
# Formats a list of types from a tag.
#
# @param [Array, FalseClass] typelist
# the list of types to be formatted.
#
# @param [Boolean] brackets omits the surrounding
# brackets if +brackets+ is set to +false+.
#
# @return [String] the list of types formatted
# as [Type1, Type2, ...] with the types linked
# to their respective descriptions.
#
def format_types(typelist, brackets = true)
return unless typelist.is_a?(Array)
list = typelist.map do |type|
type = type.gsub(/([<>])/) { h($1) }
type = type.gsub(/([\w:]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) }
"" + type + ""
end
list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
end
# Get the return types for a method signature.
#
# @param [CodeObjects::MethodObject] meth the method object
# @param [Boolean] link whether to link the types
# @return [String] the signature types
# @since 0.5.3
def signature_types(meth, link = true)
meth = convert_method_to_overload(meth)
if meth.respond_to?(:object) && !meth.has_tag?(:return)
meth = meth.object
end
type = options.default_return || ""
if meth.tag(:return) && meth.tag(:return).types
types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
first = link ? h(types.first) : format_types([types.first], false)
if types.size == 2 && types.last == 'nil'
type = first + '?'
elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
type = first + '+'
elsif types.size > 2
type = [first, '...'].join(', ')
elsif types == ['void'] && options.hide_void_return
type = ""
else
type = link ? h(types.join(", ")) : format_types(types, false)
end
elsif !type.empty?
type = link ? h(type) : format_types([type], false)
end
type = "#{type} " unless type.empty?
type
end
# Formats the signature of method +meth+.
#
# @param [CodeObjects::MethodObject] meth the method object to list
# the signature of
# @param [Boolean] link whether to link the method signature to the details view
# @param [Boolean] show_extras whether to show extra meta-data (visibility, attribute info)
# @param [Boolean] full_attr_name whether to show the full attribute name
# ("name=" instead of "name")
# @return [String] the formatted method signature
def signature(meth, link = true, show_extras = true, full_attr_name = true)
meth = convert_method_to_overload(meth)
type = signature_types(meth, link)
type = "⇒ #{type}" if type && !type.empty?
scope = meth.scope == :class ? "." : "#"
name = full_attr_name ? meth.name : meth.name.to_s.gsub(/^(\w+)=$/, '\1')
blk = format_block(meth)
args = !full_attr_name && meth.writer? ? "" : format_args(meth)
extras = []
extras_text = ''
if show_extras
rw = meth.attr_info
if rw
attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
attname = attname.size == 1 ? attname.join('') + 'only' : nil
extras << attname if attname
end
extras << meth.visibility if meth.visibility != :public
extras_text = ' (' + extras.join(", ") + ')' unless extras.empty?
end
title = "%s%s%s %s %s" % [scope, h(name), args, blk, type]
if link
if meth.is_a?(YARD::CodeObjects::MethodObject)
link_title = "#{h meth.name(true)} (#{meth.scope} #{meth.type})"
else
link_title = "#{h name} (#{meth.type})"
end
obj = meth.respond_to?(:object) ? meth.object : meth
url = url_for(object, obj)
link_url(url, title, :title => link_title) + extras_text
else
title + extras_text
end
end
# @group Getting the Character Encoding
# Returns the current character set. The default value can be overridden
# by setting the +LANG+ environment variable or by overriding this
# method. In Ruby 1.9 you can also modify this value by setting
# +Encoding.default_external+.
#
# @return [String] the current character set
# @since 0.5.4
def charset
has_encoding = defined?(::Encoding)
if defined?(@file) && @file && has_encoding
lang = @file.contents.encoding.to_s
else
return 'utf-8' unless has_encoding || ENV['LANG']
lang =
if has_encoding
::Encoding.default_external.name.downcase
else
ENV['LANG'].downcase.split('.').last
end
end
case lang
when "ascii-8bit", "us-ascii", "ascii-7bit"; 'iso-8859-1'
when "utf8"; 'utf-8'
else; lang
end
end
# @endgroup
private
# Converts a set of hash options into HTML attributes for a tag
#
# @param [Hash{String => String}] opts the tag options
# @return [String] the tag attributes of an HTML tag
def tag_attrs(opts = {})
opts.sort_by {|k, _v| k.to_s }.map {|k, v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
end
# Converts a {CodeObjects::MethodObject} into an overload object
# @since 0.5.3
def convert_method_to_overload(meth)
# use first overload tag if it has a return type and method itself does not
if !meth.tag(:return) && meth.tags(:overload).size == 1 && meth.tag(:overload).tag(:return)
return meth.tag(:overload)
end
meth
end
# Parses !!!lang out of codeblock, returning the codeblock language
# followed by the source code.
#
# @param [String] source the source code whose language to determine
# @return [Array(String, String)] the language, if any, and the
# remaining source
# @since 0.7.5
def parse_lang_for_codeblock(source)
type = nil
if source =~ /\A(?:[ \t]*\r?\n)?[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/
type = $1
source = $'
end
[type, source]
end
# Parses code blocks out of html and performs syntax highlighting
# on code inside of the blocks.
#
# @param [String] html the html to search for code in
# @return [String] highlighted html
# @see #html_syntax_highlight
def parse_codeblocks(html)
html.gsub(%r{(?:\s*)?(.+?)(?:\s*)?}m) do
string = $3
# handle !!!LANG prefix to send to html_syntax_highlight_LANG
language, = parse_lang_for_codeblock(string)
language ||= $1 || $2 || object.source_type
if options.highlight
string = html_syntax_highlight(CGI.unescapeHTML(string), language)
end
classes = ['code', language].compact.join(' ')
%(#{string}
)
end
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/uml_helper.rb 0000644 0000041 0000041 00000002671 13035234564 022357 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates::Helpers
# Helpers for UML template format
module UMLHelper
# Official UML visibility prefix syntax for an object given its visibility
# @param [CodeObjects::Base] object the object to retrieve visibility for
# @return [String] the UML visibility prefix
def uml_visibility(object)
case object.visibility
when :public; '+'
when :protected; '#'
when :private; '-'
end
end
# Formats the path of an object for Graphviz syntax
# @param [CodeObjects::Base] object an object to format the path of
# @return [String] the encoded path
def format_path(object)
object.path.gsub('::', '_')
end
# Encodes text in escaped Graphviz syntax
# @param [String] text text to encode
# @return [String] the encoded text
def h(text)
text.to_s.gsub(/(\W)/, '\\\\\1')
end
# Tidies data by formatting and indenting text
# @param [String] data pre-formatted text
# @return [String] tidied text.
def tidy(data)
indent = 0
data.split(/\n/).map do |line|
line.gsub!(/^\s*/, '')
next if line.empty?
indent -= 1 if line =~ /^\s*\}\s*$/
line = (' ' * (indent * 2)) + line
indent += 1 if line =~ /\{\s*$/
line
end.compact.join("\n") + "\n"
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/markup_helper.rb 0000644 0000041 0000041 00000014454 13035234564 023063 0 ustar www-data www-data # frozen_string_literal: true
require 'rubygems'
module YARD
module Templates::Helpers
# Helper methods for loading and managing markup types.
module MarkupHelper
class << self
# Clears the markup provider cache information. Mainly used for testing.
# @return [void]
def clear_markup_cache
self.markup_cache = {}
end
# @return [Hash{Symbol=>{(:provider,:class)=>Object}}] the cached markup providers
# @private
# @since 0.6.4
attr_accessor :markup_cache
end
MarkupHelper.clear_markup_cache
# The default list of markup providers for each markup type
MARKUP_PROVIDERS = {
:markdown => [
{:lib => :redcarpet, :const => 'RedcarpetCompat'},
{:lib => :rdiscount, :const => 'RDiscount'},
{:lib => :kramdown, :const => 'Kramdown::Document'},
{:lib => :bluecloth, :const => 'BlueCloth'},
{:lib => :maruku, :const => 'Maruku'},
{:lib => :'rpeg-markdown', :const => 'PEGMarkdown'},
{:lib => :rdoc, :const => 'YARD::Templates::Helpers::Markup::RDocMarkdown'}
],
:textile => [
{:lib => :redcloth, :const => 'RedCloth'}
],
:textile_strict => [
{:lib => :redcloth, :const => 'RedCloth'}
],
:rdoc => [
{:lib => nil, :const => 'YARD::Templates::Helpers::Markup::RDocMarkup'}
],
:asciidoc => [
{:lib => :asciidoctor, :const => 'Asciidoctor'}
],
:ruby => [],
:text => [],
:pre => [],
:html => [],
:none => []
}
# Returns a list of extensions for various markup types. To register
# extensions for a type, add them to the array of extensions for the
# type.
# @since 0.6.0
MARKUP_EXTENSIONS = {
:html => ['htm', 'html', 'shtml'],
:text => ['txt'],
:textile => ['textile', 'txtile'],
:asciidoc => ['asciidoc', 'ad', 'adoc', 'asc'],
:markdown => ['markdown', 'md', 'mdown', 'mkd'],
:rdoc => ['rdoc'],
:ruby => ['rb', 'ru']
}
# Contains the Regexp object that matches the shebang line of extra
# files to detect the markup type.
MARKUP_FILE_SHEBANG = /\A#!(\S+)\s*$/
# Attempts to load the first valid markup provider in {MARKUP_PROVIDERS}.
# If a provider is specified, immediately try to load it.
#
# On success this sets `@markup_provider` and `@markup_class` to
# the provider name and library constant class/module respectively for
# the loaded provider.
#
# On failure this method will inform the user that no provider could be
# found and exit the program.
#
# @return [Boolean] whether the markup provider was successfully loaded.
def load_markup_provider(type = options.markup)
return true if MarkupHelper.markup_cache[type]
MarkupHelper.markup_cache[type] ||= {}
providers = MARKUP_PROVIDERS[type.to_sym]
return true if providers && providers.empty?
if providers && options.markup_provider
providers = providers.select {|p| p[:lib] == options.markup_provider }
end
if providers.nil? || providers.empty?
log.error "Invalid markup type '#{type}' or markup provider " \
"(#{options.markup_provider}) is not registered."
return false
end
# Search for provider, return the library class name as const if found
providers.each do |provider|
begin require provider[:lib].to_s; rescue LoadError; next end if provider[:lib]
begin klass = eval("::" + provider[:const]); rescue NameError; next end # rubocop:disable Lint/Eval
MarkupHelper.markup_cache[type][:provider] = provider[:lib] # Cache the provider
MarkupHelper.markup_cache[type][:class] = klass
return true
end
# Show error message telling user to install first potential provider
lib = providers.first[:lib] || type
log.error "Missing '#{lib}' gem for #{type.to_s.capitalize} formatting. Install it with `gem install #{lib}`"
false
end
# Checks for a shebang or looks at the file extension to determine
# the markup type for the file contents. File extensions are registered
# for a markup type in {MARKUP_EXTENSIONS}.
#
# A shebang should be on the first line of a file and be in the form:
#
# #!markup_type
#
# Standard markup types are text, html, rdoc, markdown, textile
#
# @param [String] contents Unused. Was necessary prior to 0.7.0.
# Newer versions of YARD use {CodeObjects::ExtraFileObject#contents}
# @return [Symbol] the markup type recognized for the file
# @see MARKUP_EXTENSIONS
# @since 0.6.0
def markup_for_file(contents, filename)
return $1.to_sym if contents && contents =~ MARKUP_FILE_SHEBANG # Shebang support
ext = (File.extname(filename)[1..-1] || '').downcase
MARKUP_EXTENSIONS.each do |type, exts|
return type if exts.include?(ext)
end
options.markup
end
# Strips any shebang lines on the file contents that pertain to
# markup or preprocessing data.
#
# @deprecated Use {CodeObjects::ExtraFileObject#contents} instead
# @return [String] the file contents minus any preprocessing tags
# @since 0.6.0
def markup_file_contents(contents)
contents =~ MARKUP_FILE_SHEBANG ? $' : contents
end
# Gets the markup provider class/module constant for a markup type
# Call {#load_markup_provider} before using this method.
#
# @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
# @return [Class] the markup class
def markup_class(type = options.markup)
load_markup_provider(type)
MarkupHelper.markup_cache[type][:class]
end
# Gets the markup provider name for a markup type
# Call {#load_markup_provider} before using this method.
#
# @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
# @return [Symbol] the markup provider name (usually the gem name of the library)
def markup_provider(type = options.markup)
MarkupHelper.markup_cache[type][:provider]
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/filter_helper.rb 0000644 0000041 0000041 00000001313 13035234564 023037 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates::Helpers
# Helpers for various object types
module FilterHelper
# @return [Boolean] whether an object is a method
def is_method?(object)
object.type == :method
end
# @return [Boolean] whether an object is a namespace
def is_namespace?(object)
object.is_a?(CodeObjects::NamespaceObject)
end
# @return [Boolean] whether an object is a class
def is_class?(object)
object.is_a?(CodeObjects::ClassObject)
end
# @return [Boolean] whether an object is a module
def is_module?(object)
object.is_a?(CodeObjects::ModuleObject)
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/text_helper.rb 0000644 0000041 0000041 00000007534 13035234564 022551 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates
module Helpers
# Helper methods for text template formats.
module TextHelper
# @return [String] escapes text
def h(text)
out = String.new("")
text = resolve_links(text)
text = text.split(/\n/)
text.each_with_index do |line, i|
out <<
case line
when /^\s*$/; "\n\n"
when /^\s+\S/, /^=/; line + "\n"
else; line + (text[i + 1] =~ /^\s+\S/ ? "\n" : " ")
end
end
out
end
# @return [String] wraps text at +col+ columns.
def wrap(text, col = 72)
text.gsub(/(.{1,#{col}})( +|$\n?)|(.{1,#{col}})/, "\\1\\3\n")
end
# @return [String] indents +text+ by +len+ characters.
def indent(text, len = 4)
text.gsub(/^/, ' ' * len)
end
# @return [String] aligns a title to the right
def title_align_right(text, col = 72)
align_right(text, '-', col)
end
# @return [String] aligns text to the right
def align_right(text, spacer = ' ', col = 72)
text = text[0, col - 4] + '...' if (col - 1 - text.length) < 0
spacer * (col - 1 - text.length) + " " + text
end
# @return [String] returns a horizontal rule for output
def hr(col = 72, sep = "-")
sep * col
end
# @return [String] the formatted signature for a method
def signature(meth)
# use first overload tag if it has a return type and method itself does not
if !meth.tag(:return) && meth.tag(:overload) && meth.tag(:overload).tag(:return)
meth = meth.tag(:overload)
end
type = options.default_return || ""
rmeth = meth
if !rmeth.has_tag?(:return) && rmeth.respond_to?(:object)
rmeth = meth.object
end
if rmeth.tag(:return) && rmeth.tag(:return).types
types = rmeth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
first = types.first
if types.size == 2 && types.last == 'nil'
type = first + '?'
elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
type = first + '+'
elsif types.size > 2
type = [first, '...'].join(', ')
elsif types == ['void'] && options.hide_void_return
type = ""
else
type = types.join(", ")
end
end
type = "(#{type})" if type.include?(',')
type = " -> #{type} " unless type.empty?
scope = meth.scope == :class ? "#{meth.namespace.name}." : "#{meth.namespace.name.to_s.downcase}."
name = meth.name
blk = format_block(meth)
args = format_args(meth)
extras = []
extras_text = ''
rw = meth.namespace.attributes[meth.scope][meth.name]
if rw
attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
attname = attname.size == 1 ? attname.join('') + 'only' : nil
extras << attname if attname
end
extras << meth.visibility if meth.visibility != :public
extras_text = '(' + extras.join(", ") + ')' unless extras.empty?
title = "%s%s%s %s%s%s" % [scope, name, args, blk, type, extras_text]
title.gsub(/\s+/, ' ')
end
private
def resolve_links(text)
text.gsub(/(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W]|$)/m) do |_str|
escape = $1
name = $2
title = $3
match = $&
next(match[1..-1]) if escape
next(match) if name[0, 1] == '|'
linkify(name, title)
end
end
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/module_helper.rb 0000644 0000041 0000041 00000001610 13035234564 023037 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates
module Helpers
# Helper methods for managing module objects.
module ModuleHelper
# Prunes the method listing by running the verifier and removing attributes/aliases
# @param [Array] list a list of methods
# @param [Boolean] hide_attributes whether to prune attribute methods from the list
# @return [Array] a pruned list of methods
def prune_method_listing(list, hide_attributes = true)
list = run_verifier(list)
list = list.reject {|o| run_verifier([o.parent]).empty? }
list = list.reject {|o| o.is_alias? unless CodeObjects::Proxy === o.namespace }
list = list.reject {|o| o.is_attribute? unless CodeObjects::Proxy === o.namespace } if hide_attributes
list
end
end
end
end
end
yard-0.9.7/lib/yard/templates/helpers/method_helper.rb 0000644 0000041 0000041 00000004711 13035234564 023037 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Templates::Helpers
# Helper methods for method objects.
module MethodHelper
# @return [String] formatted arguments for a method
def format_args(object)
return if object.parameters.nil?
params = object.parameters
if object.has_tag?(:yield) || object.has_tag?(:yieldparam)
params.reject! do |param|
param[0].to_s[0, 1] == "&" &&
!object.tags(:param).any? {|t| t.name == param[0][1..-1] }
end
end
if params.empty?
""
else
args = params.map do |n, v|
v ? "#{n}#{n[-1, 1] == ':' ? '' : ' ='} #{v}" : n.to_s
end.join(", ")
h("(#{args})")
end
end
# @return [String] formatted and linked return types for a method
def format_return_types(object)
return unless object.has_tag?(:return) && object.tag(:return).types
return if object.tag(:return).types.empty?
format_types [object.tag(:return).types.first], false
end
# @return [String] formatted block if one exists
def format_block(object)
if object.has_tag?(:yield) && object.tag(:yield).types
params = object.tag(:yield).types
elsif object.has_tag?(:yieldparam)
params = object.tags(:yieldparam).map(&:name)
elsif object.has_tag?(:yield)
return "{ ... }"
else
params = nil
end
params ? h("{|" + params.join(", ") + "| ... }") : ""
end
# @return [String] formats line numbers for source code of an object
def format_lines(object)
return "" if object.source.nil? || object.line.nil?
i = -1
object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
end
# @return [String] formats source of an object
def format_code(object, _show_lines = false)
i = -1
lines = object.source.split(/\n/)
longestline = (object.line + lines.size).to_s.length
lines.map do |line|
lineno = object.line + (i += 1)
(" " * (longestline - lineno.to_s.length)) + lineno.to_s + " " + line
end.join("\n")
end
# @return [String] formats source code of a constant value
def format_constant(value)
sp = value.split("\n").last[/^(\s+)/, 1]
num = sp ? sp.size : 0
html_syntax_highlight value.gsub(/^\s{#{num}}/, '')
end
end
end
end
yard-0.9.7/lib/yard/templates/template.rb 0000644 0000041 0000041 00000033454 13035234564 020377 0 ustar www-data www-data # frozen_string_literal: true
require 'erb'
module YARD
module Templates
module Template
attr_accessor :class, :section
attr_reader :options
class << self
# Extra includes are mixins that are included after a template is created. These
# mixins can be registered by plugins to operate on templates and override behaviour.
#
# Note that this array can be filled with modules or proc objects. If a proc object
# is given, the proc will be called with the {Template#options} hash containing
# relevant template information like the object, format, and more. The proc should
# return a module or nil if there is none.
#
# @example Adding in extra mixins to include on a template
# Template.extra_includes << MyHelper
# @example Conditionally including a mixin if the format is html
# Template.extra_includes << proc {|opts| MyHelper if opts.format == :html }
# @return [Array] a list of modules to be automatically included
# into any new template module
attr_accessor :extra_includes
# @!parse extend ClassMethods
# @private
def included(klass)
klass.extend(ClassMethods)
end
# Includes the {extra_includes} modules into the template object.
#
# @param [Template] template the template object to mixin the extra includes.
# @param [SymbolHash] options the options hash containing all template information
# @return [void]
def include_extra(template, options)
extra_includes.each do |mod|
mod = mod.call(options) if mod.is_a?(Proc)
next unless mod.is_a?(Module)
template.extend(mod)
end
end
end
self.extra_includes = [
proc do |options|
{:html => Helpers::HtmlHelper,
:text => Helpers::TextHelper,
:dot => Helpers::UMLHelper}[options.format]
end
]
include ErbCache
include Helpers::BaseHelper
include Helpers::MethodHelper
module ClassMethods
attr_accessor :path, :full_path
# @return [Array] a list of full paths
# @note This method caches path results. Paths should not be modified
# after this method is called; call {#reset_full_paths} to reset cache.
def full_paths
reset_full_paths unless defined? @cached_included_modules
return @full_paths if included_modules == @cached_included_modules
@cached_included_modules = included_modules
@full_paths = included_modules.inject([full_path]) do |paths, mod|
paths |= mod.full_paths if mod.respond_to?(:full_paths)
paths
end
end
# Resets cache for {#full_paths}
def reset_full_paths
@cached_included_modules = nil
end
def initialize(path, full_paths)
full_path = full_paths.shift
self.path = path
self.full_path = full_path
include_inherited(full_paths)
include_parent
load_setup_rb
end
# Searches for a file identified by +basename+ in the template's
# path as well as any mixed in template paths. Equivalent to calling
# {ClassMethods#find_nth_file} with index of 1.
#
# @param [String] basename the filename to search for
# @return [String] the full path of a file on disk with filename
# +basename+ in one of the template's paths.
# @see find_nth_file
def find_file(basename)
find_nth_file(basename)
end
# Searches for the nth file (where n = +index+) identified
# by basename in the template's path and any mixed in template paths.
#
# @param [String] basename the filename to search for
# @param [Fixnum] index the nth existing file to return
# @return [String] the full path of the nth file on disk with
# filename +basename+ in one of the template paths
def find_nth_file(basename, index = 1)
n = 1
full_paths.each do |path|
file = File.join(path, basename)
if File.file?(file)
return file if index == n
n += 1
end
end
nil
end
def is_a?(klass)
return true if klass == Template
super(klass)
end
# Creates a new template object to be rendered with {Template#run}
def new(*args)
obj = Object.new.extend(self)
obj.class = self
obj.send(:initialize, *args)
obj
end
def run(*args)
new(*args).run
end
# rubocop:disable Style/MethodName
# Alias for creating {Engine.template}.
def T(*path)
Engine.template(*path)
end
# Alias for creating a {Section} with arguments
# @see Section#initialize
# @since 0.6.0
def S(*args)
Section.new(*args)
end
# rubocop:enable Style/MethodName
private
def include_parent
pc = path.to_s.split('/')
if pc.size > 1
pc.pop
pc = pc.join('/')
begin
include Engine.template(pc)
rescue ArgumentError
include Engine.template!(pc, full_path.gsub(%r{/[^/]+$}, ''))
end
end
end
def include_inherited(full_paths)
full_paths.reverse.each do |full_path|
include Engine.template!(path, full_path)
end
end
def load_setup_rb
setup_file = File.join(full_path, 'setup.rb')
if File.file? setup_file
module_eval(File.read(setup_file).taint, setup_file, 1)
end
end
end
def initialize(opts = TemplateOptions.new)
opts_class = opts.class
opts_class = TemplateOptions if opts_class == Hash
@cache = {}
@cache_filename = {}
@sections = []
@options = opts_class.new
add_options(opts)
Template.include_extra(self, options)
init
end
# Loads a template specified by path. If +:template+ or +:format+ is
# specified in the {#options} hash, they are prepended and appended
# to the path respectively.
#
# @param [Array] path the path of the template
# @return [Template] the loaded template module
def T(*path) # rubocop:disable Style/MethodName
path.unshift(options.template) if options.template
path.push(options.format) if options.format
self.class.T(*path)
end
# Sets the sections (and subsections) to be rendered for the template
#
# @example Sets a set of erb sections
# sections :a, :b, :c # searches for a.erb, b.erb, c.erb
# @example Sets a set of method and erb sections
# sections :a, :b, :c # a is a method, the rest are erb files
# @example Sections with subsections
# sections :header, [:name, :children]
# # the above will call header.erb and only renders the subsections
# # if they are yielded by the template (see #yieldall)
# @param [Array] args the sections
# to use to render the template. For symbols and strings, the
# section will be executed as a method (if one exists), or rendered
# from the file "name.erb" where name is the section name. For
# templates, they will have {Template::ClassMethods#run} called on them.
# Any subsections can be yielded to using yield or {#yieldall}
def sections(*args)
@sections = Section.new(nil, *args) unless args.empty?
@sections
end
# Initialization called on the template. Override this in a 'setup.rb'
# file in the template's path to implement a template
#
# @example A default set of sections
# def init
# sections :section1, :section2, [:subsection1, :etc]
# end
# @see #sections
def init
end
# Runs a template on +sects+ using extra options. This method should
# not be called directly. Instead, call the class method {ClassMethods#run}
#
# @param [Hash, nil] opts any extra options to apply to sections
# @param [Section, Array] sects a section list of sections to render
# @param [Fixnum] start_at the index in the section list to start from
# @param [Boolean] break_first if true, renders only the first section
# @yield [opts] calls for the subsections to be rendered
# @yieldparam [Hash] opts any extra options to yield
# @return [String] the rendered sections joined together
def run(opts = nil, sects = sections, start_at = 0, break_first = false, &block)
out = String.new("")
return out if sects.nil?
sects = sects[start_at..-1] if start_at > 0
sects = Section.new(nil, sects) unless sects.is_a?(Section)
add_options(opts) do
sects.each do |s|
self.section = s
subsection_index = 0
value = render_section(section) do |*args|
value = with_section do
run(args.first, section, subsection_index, true, &block)
end
subsection_index += 1
value
end
out << (value || "")
break if break_first
end
end
out
end
# Yields all subsections with any extra options
#
# @param [Hash] opts extra options to be applied to subsections
def yieldall(opts = nil, &block)
with_section { run(opts, section, &block) }
end
# @param [String, Symbol] section the section name
# @yield calls subsections to be rendered
# @return [String] the contents of the ERB rendered section
def erb(section, &block)
method_name = ErbCache.method_for(cache_filename(section)) do
erb_with(cache(section), cache_filename(section))
end
send(method_name, &block)
end
# Returns the contents of a file. If +allow_inherited+ is set to +true+,
# use +{{{__super__}}}+ inside the file contents to insert the contents
# of the file from an inherited template. For instance, if +templates/b+
# inherits from +templates/a+ and file "test.css" exists in both directories,
# both file contents can be retrieved by having +templates/b/test.css+ look
# like:
#
# {{{__super__}}}
# ...
# body { css styles here }
# p.class { other styles }
#
# @param [String] basename the name of the file
# @param [Boolean] allow_inherited whether inherited templates can
# be inserted with +{{{__super__}}}+
# @return [String] the contents of a file identified by +basename+. All
# template paths (including any mixed in templates) are searched for
# the file
# @see ClassMethods#find_file
# @see ClassMethods#find_nth_file
def file(basename, allow_inherited = false)
file = self.class.find_file(basename)
raise ArgumentError, "no file for '#{basename}' in #{self.class.path}" unless file
data = IO.read(file)
if allow_inherited
superfile = self.class.find_nth_file(basename, 2)
data.gsub!('{{{__super__}}}', superfile ? IO.read(superfile) : "")
end
data
end
# Calls the ERB file from the last inherited template with {#section}.erb
#
# @param [Symbol, String] sect if provided, uses a specific section name
# @return [String] the rendered ERB file in any of the inherited template
# paths.
def superb(sect = section, &block)
filename = self.class.find_nth_file(erb_file_for(sect), 2)
return "" unless filename
method_name = ErbCache.method_for(filename) { erb_with(IO.read(filename), filename) }
send(method_name, &block)
end
def options=(value)
@options = value
set_ivars
end
def inspect
"Template(#{self.class.path}) [section=#{section.name}]"
end
protected
def erb_file_for(section)
"#{section}.erb"
end
def erb_with(content, filename = nil)
erb = ERB.new(content, nil, options.format == :text ? '<>' : nil)
erb.filename = filename if filename
erb
end
private
def render_section(section, &block)
section = section.name if section.is_a?(Section)
case section
when Section, String, Symbol
if respond_to?(section)
send(section, &block)
else
erb(section, &block)
end
when Module, Template
section.run(options, &block) if section.is_a?(Template)
end || ""
end
def cache(section)
content = @cache[section.to_sym]
return content if content
file = cache_filename(section)
@cache_filename[section.to_sym] = file
raise ArgumentError, "no template for section '#{section}' in #{self.class.path}" unless file
@cache[section.to_sym] = IO.read(file)
end
def cache_filename(section)
@cache_filename[section.to_sym] ||=
self.class.find_file(erb_file_for(section))
end
def set_ivars
options.each do |k, v|
instance_variable_set("@#{k}", v)
end
end
def add_options(opts = nil)
return(yield) if opts.nil? && block_given?
cur_opts = options if block_given?
self.options = options.merge(opts)
if block_given?
value = yield
self.options = cur_opts
value
end
end
def with_section
sect = section
value = yield
self.section = sect
value
end
end
end
end
yard-0.9.7/lib/yard/rubygems/ 0000755 0000041 0000041 00000000000 13035234564 016065 5 ustar www-data www-data yard-0.9.7/lib/yard/rubygems/hook.rb 0000644 0000041 0000041 00000010336 13035234564 017355 0 ustar www-data www-data # frozen_string_literal: true
require 'rubygems'
require 'rubygems/user_interaction'
require 'fileutils'
##
# Gem::YARDoc provides methods to generate YARDoc and yri data for installed gems
# upon gem installation.
#
# This file is automatically required by RubyGems 1.9 and newer.
module YARD
class RubygemsHook
include Gem::UserInteraction
extend Gem::UserInteraction
@yard_version = nil
##
# Force installation of documentation?
attr_accessor :force
##
# Generate yard?
attr_accessor :generate_yard
##
# Generate yri data?
attr_accessor :generate_yri
class << self
##
# Loaded version of YARD. Set by ::load_yard
attr_reader :yard_version
end
##
# Post installs hook that generates documentation for each specification in
# +specs+
def self.generation_hook(installer, specs)
start = Time.now
types = installer.document
generate_yard = types.include?('yardoc') || types.include?('yard')
generate_yri = types.include? 'yri'
specs.each do |spec|
gen_yard = generate_yard
gen_yri = generate_yri
gen_yri = false if gen_yard # never generate both, no need
unless types.empty? # --no-document is not in effect
# look at spec.metadata['yard.run'] for override
run_yard = spec.metadata['yard.run']
gen_yard = true if run_yard && run_yard != 'yri'
gen_yri = true if run_yard == 'yri'
end
new(spec, gen_yard, gen_yri).generate
end
return unless generate_yard || generate_yri
duration = (Time.now - start).to_i
names = specs.map(&:name).join ', '
say "Done installing documentation for #{names} after #{duration} seconds"
end
##
# Loads the YARD generator
def self.load_yard
return if @yard_version
require 'yard'
@yard_version = Gem::Version.new ::YARD::VERSION
end
def initialize(spec, generate_yard = false, generate_yri = true)
@doc_dir = spec.doc_dir
@force = false
@spec = spec
@generate_yard = generate_yard
@generate_yri = generate_yri
@yard_dir = spec.doc_dir('yard')
@yri_dir = spec.doc_dir('.yardoc')
end
def run_yardoc(*args)
args << '--quiet' unless Gem.configuration.really_verbose
args << '--backtrace' if Gem.configuration.backtrace
unless File.file?(File.join(@spec.full_gem_path, '.yardopts'))
args << @spec.require_paths
unless @spec.extra_rdoc_files.empty?
args << '-'
args += @spec.extra_rdoc_files
end
end
args = args.flatten.map(&:to_s)
Dir.chdir(@spec.full_gem_path) do
YARD::CLI::Yardoc.run(*args)
end
rescue Errno::EACCES => e
dirname = File.dirname e.message.split("-")[1].strip
raise Gem::FilePermissionError, dirname
rescue => ex
alert_error "While generating documentation for #{@spec.full_name}"
ui.errs.puts "... MESSAGE: #{ex}"
ui.errs.puts "... YARDOC args: #{args.join(' ')}"
ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
ui.errs.puts "(continuing with the rest of the installation)"
end
def install_yard
FileUtils.rm_rf @yard_dir
say "Installing YARD documentation for #{@spec.full_name}..."
run_yardoc '--no-progress', '--db', @yri_dir, '-o', @yard_dir
end
def install_yri
FileUtils.rm_rf @yri_dir
say "Building YARD (yri) index for #{@spec.full_name}..."
run_yardoc '--no-progress', '-c', '-n', '--db', @yri_dir
end
##
# Generates YARD and yri data
def generate
return if @spec.default_gem?
return unless @generate_yri || @generate_yard
setup
install_yri if @generate_yri && (@force || !File.exist?(@yri_dir))
install_yard if @generate_yard && (@force || !File.exist?(@yard_dir))
end
##
# Prepares the spec for documentation generation
def setup
self.class.load_yard
if File.exist?(@doc_dir)
raise Gem::FilePermissionError, @doc_dir unless File.writable?(@doc_dir)
else
FileUtils.mkdir_p @doc_dir
end
end
end
end
Gem.done_installing(&YARD::RubygemsHook.method(:generation_hook))
yard-0.9.7/lib/yard/rubygems/backports.rb 0000644 0000041 0000041 00000000415 13035234564 020402 0 ustar www-data www-data # frozen_string_literal: true
begin
require 'rubygems'
if defined?(Gem::VERSION) && Gem::VERSION >= '1.8.0'
require File.dirname(__FILE__) + '/backports/gem'
require File.dirname(__FILE__) + '/backports/source_index'
end
rescue LoadError
nil # noop
end
yard-0.9.7/lib/yard/rubygems/doc_manager.rb 0000644 0000041 0000041 00000004546 13035234564 020662 0 ustar www-data www-data # frozen_string_literal: true
begin
require 'rubygems/user_interaction'
require 'rubygems/doc_manager'
rescue LoadError
nil # noop
end
class Gem::DocManager
def self.load_yardoc
require File.expand_path(File.join(File.dirname(__FILE__), *%w(.. .. yard)))
end
def run_yardoc(*args)
args << '--quiet'
args << '--backtrace' if Gem.configuration.backtrace
unless File.file?(File.join(@spec.full_gem_path, '.yardopts'))
args << @spec.require_paths
unless @spec.extra_rdoc_files.empty?
args << '-'
args += @spec.extra_rdoc_files
end
end
args = args.flatten.map(&:to_s)
old_pwd = Dir.pwd
Dir.chdir(@spec.full_gem_path)
YARD::CLI::Yardoc.run(*args)
rescue Errno::EACCES => e
dirname = File.dirname e.message.split("-")[1].strip
raise Gem::FilePermissionError, dirname
rescue => ex
alert_error "While generating documentation for #{@spec.full_name}"
ui.errs.puts "... MESSAGE: #{ex}"
ui.errs.puts "... YARDOC args: #{args.join(' ')}"
ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
ui.errs.puts "(continuing with the rest of the installation)"
ensure
Dir.chdir(old_pwd)
end
begin undef setup_rdoc; rescue NameError; nil end
def setup_rdoc
if File.exist?(@doc_dir) && !File.writable?(@doc_dir)
raise Gem::FilePermissionError, @doc_dir
end
FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)
self.class.load_rdoc if @spec.has_rdoc?
self.class.load_yardoc if @spec.has_yardoc?
end
def install_yardoc
rdoc_dir = File.join(@doc_dir, 'rdoc')
FileUtils.rm_rf rdoc_dir
say "Installing YARD documentation for #{@spec.full_name}..."
run_yardoc '-o', rdoc_dir
end
def install_ri_yard
install_ri_yard_orig if @spec.has_rdoc?
return if @spec.has_rdoc? == false
return if @spec.has_yardoc?
self.class.load_yardoc
say "Building YARD (yri) index for #{@spec.full_name}..."
run_yardoc '-c', '-n'
end
begin
alias install_ri_yard_orig install_ri
alias install_ri install_ri_yard
rescue NameError; nil end
def install_rdoc_yard
if @spec.has_rdoc?
install_rdoc_yard_orig
elsif @spec.has_yardoc?
install_yardoc
end
end
begin
alias install_rdoc_yard_orig install_rdoc
alias install_rdoc install_rdoc_yard
rescue NameError; nil end
end
yard-0.9.7/lib/yard/rubygems/backports/ 0000755 0000041 0000041 00000000000 13035234564 020055 5 ustar www-data www-data yard-0.9.7/lib/yard/rubygems/backports/LICENSE.txt 0000644 0000041 0000041 00000004633 13035234564 021706 0 ustar www-data www-data RubyGems is copyrighted free software by Chad Fowler, Rich Kilmer, Jim
Weirich and others. You can redistribute it and/or modify it under
either the terms of the MIT license (see the file MIT.txt), or the
conditions below:
1. You may make and give away verbatim copies of the source form of the
software without restriction, provided that you duplicate all of the
original copyright notices and associated disclaimers.
2. You may modify your copy of the software in any way, provided that
you do at least ONE of the following:
a. place your modifications in the Public Domain or otherwise
make them Freely Available, such as by posting said
modifications to Usenet or an equivalent medium, or by allowing
the author to include your modifications in the software.
b. use the modified software only within your corporation or
organization.
c. give non-standard executables non-standard names, with
instructions on where to get the original software distribution.
d. make other distribution arrangements with the author.
3. You may distribute the software in object code or executable
form, provided that you do at least ONE of the following:
a. distribute the executables and library files of the software,
together with instructions (in the manual page or equivalent)
on where to get the original distribution.
b. accompany the distribution with the machine-readable source of
the software.
c. give non-standard executables non-standard names, with
instructions on where to get the original software distribution.
d. make other distribution arrangements with the author.
4. You may modify and include the part of the software into any other
software (possibly commercial). But some files in the distribution
are not written by the author, so that they are not under these terms.
For the list of those files and their copying conditions, see the
file LEGAL.
5. The scripts and library files supplied as input to or produced as
output from the software do not automatically fall under the
copyright of the software, but belong to whomever generated them,
and may be sold commercially, and may be aggregated with this
software.
6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.
yard-0.9.7/lib/yard/rubygems/backports/MIT.txt 0000644 0000041 0000041 00000002100 13035234564 021240 0 ustar www-data www-data Copyright (c) Chad Fowler, Rich Kilmer, Jim Weirich and others.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
yard-0.9.7/lib/yard/rubygems/backports/gem.rb 0000644 0000041 0000041 00000000440 13035234564 021150 0 ustar www-data www-data # frozen_string_literal: true
module Gem
class << self
undef source_index if method_defined?(:source_index)
# Returns the Gem::SourceIndex of specifications that are in the Gem.path
def source_index
@@source_index ||= SourceIndex.from_installed_gems
end
end
end
yard-0.9.7/lib/yard/rubygems/backports/source_index.rb 0000644 0000041 0000041 00000022366 13035234564 023102 0 ustar www-data www-data # frozen_string_literal: true
#--
# Copyright 2006 by Chad Fowler, Rich Kilmer, Jim Weirich and others.
# All rights reserved.
# See LICENSE.txt for permissions.
#++
require 'rubygems/specification'
##
# The SourceIndex object indexes all the gems available from a
# particular source (e.g. a list of gem directories, or a remote
# source). A SourceIndex maps a gem full name to a gem
# specification.
#
# NOTE:: The class used to be named Cache, but that became
# confusing when cached source fetchers where introduced. The
# constant Gem::Cache is an alias for this class to allow old
# YAMLized source index objects to load properly.
class Gem::SourceIndex
# Undef old methods
alias old_initialize initialize
undef old_initialize
%w(all_gems prerelease_gems load_gems_in latest_specs prerelease_specs
released_specs add_spec add_specs remove_spec each specification
index_signature gem_signature size length find_name search released_gems
refresh! outdated == dump gems spec_dirs spec_dirs=).each do |meth|
undef_method(meth) if method_defined?(meth)
end
include Enumerable
attr_reader :gems # :nodoc:
##
# Directories to use to refresh this SourceIndex when calling refresh!
attr_accessor :spec_dirs
class << self
# Undef old methods
%w(from_installed_gems installed_spec_directories
from_gems_in load_specification).each do |meth|
undef_method(meth) if instance_methods(true).find {|m| m.to_s == meth }
end
##
# Factory method to construct a source index instance for a given
# path.
#
# deprecated::
# If supplied, from_installed_gems will act just like
# +from_gems_in+. This argument is deprecated and is provided
# just for backwards compatibility, and should not generally
# be used.
#
# return::
# SourceIndex instance
def from_installed_gems(*deprecated)
if deprecated.empty?
from_gems_in(*installed_spec_directories)
else
from_gems_in(*deprecated) # HACK: warn
end
end
##
# Returns a list of directories from Gem.path that contain specifications.
def installed_spec_directories
Gem.path.collect {|dir| File.join(dir, "specifications") }
end
##
# Creates a new SourceIndex from the ruby format gem specifications in
# +spec_dirs+.
def from_gems_in(*spec_dirs)
source_index = new
source_index.spec_dirs = spec_dirs
source_index.refresh!
end
##
# Loads a ruby-format specification from +file_name+ and returns the
# loaded spec.
def load_specification(file_name)
Gem::Specification.load file_name
end
end
##
# Constructs a source index instance from the provided specifications, which
# is a Hash of gem full names and Gem::Specifications.
#--
# TODO merge @gems and @prerelease_gems and provide a separate method
# #prerelease_gems
def initialize(specifications = {})
@gems = {}
specifications.each {|_full_name, spec| add_spec spec }
@spec_dirs = nil
end
# TODO: remove method
def all_gems
@gems
end
def prerelease_gems
@gems.reject {|_name, gem| !gem.version.prerelease? }
end
def released_gems
@gems.reject {|_name, gem| gem.version.prerelease? }
end
##
# Reconstruct the source index from the specifications in +spec_dirs+.
def load_gems_in(*spec_dirs)
@gems.clear
spec_dirs.reverse_each do |spec_dir|
spec_files = Dir.glob File.join(spec_dir, '*.gemspec')
spec_files.each do |spec_file|
gemspec = Gem::Specification.load spec_file
add_spec gemspec if gemspec
end
end
self
end
##
# Returns an Array specifications for the latest released versions
# of each gem in this index.
def latest_specs(include_prerelease = false)
result = Hash.new {|h, k| h[k] = [] }
latest = {}
sort.each do |_, spec|
name = spec.name
curr_ver = spec.version
prev_ver = latest.key?(name) ? latest[name].version : nil
next if !include_prerelease && curr_ver.prerelease?
next unless prev_ver.nil? || curr_ver >= prev_ver ||
latest[name].platform != Gem::Platform::RUBY
if prev_ver.nil? ||
(curr_ver > prev_ver && spec.platform == Gem::Platform::RUBY)
result[name].clear
latest[name] = spec
end
if spec.platform != Gem::Platform::RUBY
result[name].delete_if do |result_spec|
result_spec.platform == spec.platform
end
end
result[name] << spec
end
# TODO: why is this a hash while @gems is an array? Seems like
# structural similarity would be good.
result.values.flatten
end
##
# An array including only the prerelease gemspecs
def prerelease_specs
prerelease_gems.values
end
##
# An array including only the released gemspecs
def released_specs
released_gems.values
end
##
# Add a gem specification to the source index.
def add_spec(gem_spec, name = gem_spec.full_name)
# No idea why, but the Indexer wants to insert them using original_name
# instead of full_name. So we make it an optional arg.
@gems[name] = gem_spec
end
##
# Add gem specifications to the source index.
def add_specs(*gem_specs)
gem_specs.each do |spec|
add_spec spec
end
end
##
# Remove a gem specification named +full_name+.
def remove_spec(full_name)
@gems.delete full_name
end
##
# Iterate over the specifications in the source index.
def each(&block) # :yields: gem.full_name, gem
@gems.each(&block)
end
##
# The gem specification given a full gem spec name.
def specification(full_name)
@gems[full_name]
end
##
# The signature for the source index. Changes in the signature indicate a
# change in the index.
def index_signature
require 'digest'
Digest::SHA256.new.hexdigest(@gems.keys.sort.join(',')).to_s
end
##
# The signature for the given gem specification.
def gem_signature(gem_full_name)
require 'digest'
Digest::SHA256.new.hexdigest(@gems[gem_full_name].to_yaml).to_s
end
def size
@gems.size
end
alias length size
##
# Find a gem by an exact match on the short name.
def find_name(gem_name, requirement = Gem::Requirement.default)
dep = Gem::Dependency.new gem_name, requirement
search dep
end
##
# Search for a gem by Gem::Dependency +gem_pattern+. If +only_platform+
# is true, only gems matching Gem::Platform.local will be returned. An
# Array of matching Gem::Specification objects is returned.
#
# For backwards compatibility, a String or Regexp pattern may be passed as
# +gem_pattern+, and a Gem::Requirement for +platform_only+. This
# behavior is deprecated and will be removed.
def search(gem_pattern, platform_only = false)
requirement = nil
only_platform = false
# TODO: Remove support and warning for legacy arguments after 2008/11
unless Gem::Dependency === gem_pattern
warn "#{Gem.location_of_caller.join ':'}:Warning: Gem::SourceIndex#search support for #{gem_pattern.class} patterns is deprecated, use #find_name"
end
case gem_pattern
when Regexp then
requirement = platform_only || Gem::Requirement.default
when Gem::Dependency then
only_platform = platform_only
requirement = gem_pattern.requirement
gem_pattern = if Regexp === gem_pattern.name
gem_pattern.name
elsif gem_pattern.name.empty?
//
else
/^#{Regexp.escape gem_pattern.name}$/
end
else
requirement = platform_only || Gem::Requirement.default
gem_pattern = /#{gem_pattern}/i
end
unless Gem::Requirement === requirement
requirement = Gem::Requirement.create requirement
end
specs = all_gems.values.select do |spec|
spec.name =~ gem_pattern &&
requirement.satisfied_by?(spec.version)
end
if only_platform
specs = specs.select do |spec|
Gem::Platform.match spec.platform
end
end
specs.sort_by(&:sort_obj)
end
##
# Replaces the gems in the source index from specifications in the
# directories this source index was created from. Raises an exception if
# this source index wasn't created from a directory (via from_gems_in or
# from_installed_gems, or having spec_dirs set).
def refresh!
raise 'source index not created from disk' if @spec_dirs.nil?
load_gems_in(*@spec_dirs)
end
##
# Returns an Array of Gem::Specifications that are not up to date.
def outdated
outdateds = []
latest_specs.each do |local|
dependency = Gem::Dependency.new local.name, ">= #{local.version}"
fetcher = Gem::SpecFetcher.fetcher
remotes = fetcher.find_matching dependency
remotes = remotes.map {|(_, version, _), _| version }
latest = remotes.sort.last
outdateds << local.name if latest && local.version < latest
end
outdateds
end
def ==(other) # :nodoc:
self.class === other && @gems == other.gems
end
def dump
Marshal.dump(self)
end
end
# :stopdoc:
module Gem
##
# Cache is an alias for SourceIndex to allow older YAMLized source index
# objects to load properly.
Cache = SourceIndex unless defined?(Cache)
end
# :startdoc:
yard-0.9.7/lib/yard/rubygems/specification.rb 0000644 0000041 0000041 00000002004 13035234564 021226 0 ustar www-data www-data # frozen_string_literal: true
require 'rubygems/specification'
class Gem::Specification
# @since 0.5.3
def has_yardoc=(value)
@has_rdoc = value ? 'yard' : false
end
def has_yardoc
@has_rdoc == 'yard'
end
undef has_rdoc?
def has_rdoc?
(@has_rdoc ||= true) && @has_rdoc != 'yard'
end
alias has_yardoc? has_yardoc
# has_rdoc should not be ignored!
if respond_to?(:overwrite_accessor)
overwrite_accessor(:has_rdoc) { @has_rdoc ||= true }
overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
else
attr_accessor :has_rdoc
end
if defined?(Gem::VERSION) && Gem::VERSION >= '1.7.'
def _dump_with_rdoc(limit)
dmp = _dump_without_rdoc(limit)
dmp[15] = @has_rdoc if dmp[15] == true
dmp
end
alias _dump_without_rdoc _dump
alias _dump _dump_with_rdoc
@@default_value[:has_rdoc] = true if defined?(@@default_value)
@@attributes << 'has_rdoc' if defined?(@@attributes)
@@nil_attributes << 'has_rdoc' if defined?(@@nil_attributes)
end
end
yard-0.9.7/lib/yard/options.rb 0000644 0000041 0000041 00000017626 13035234564 016264 0 ustar www-data www-data # frozen_string_literal: true
module YARD
# Generalized options class for passing around large amounts of options between objects.
#
# The options class exists for better visibility and documentability of options being
# passed through to other objects. Because YARD has parser and template architectures
# that are heavily reliant on options, it is necessary to make these option keys easily
# visible and understood by developers. Since the options class is more than just a
# basic Hash, the subclass can provide aliasing and convenience methods to simplify
# option property access, and, if needed, support backward-compatibility for deprecated
# key names.
#
# == Hash and OpenStruct-like Access
#
# Although the options class allows for Hash-like access (opts[:key]), the recommended
# mechanism for accessing an option key will be via standard method calls on attributes
#
# The options class can also act as an open ended key value storage structure (like a
# Hash or OpenStruct), and allows for setting and getting of unregistered option keys.
# This methodology is not recommended, however, and is only supported for backward
# compatibility inside YARD. Whenever possible, developers should define all keys used
# by an options class.
#
# == Declaring Default Values
#
# Note that the options class can contain default value definitions for certain options,
# but to initialize these defaults, {#reset_defaults} must be called manually after
# initialization; the options object is always created empty until defaults are applied.
#
# @abstract Subclasses should define (and document) custom attributes that are expected
# to be made available as option keys.
# @example Defining an Options class with custom option keys
# class TemplateOptions < YARD::Options
# # @return [Symbol] the output format to generate templates in
# attr_accessor :format
#
# # @return [Symbol] the template to use when generating output
# attr_accessor :template
# end
# @example Initializing default option values
# class TemplateOptions < YARD::Options
# def reset_defaults
# super
# self.format = :html
# self.template = :default
# self.highlight = true
# # ...
# end
# end
# @example Using +default_attr+ to create default attributes
# class TemplateOptions < YARD::Options
# default_attr :format, :html
# default_attr :template, :default
# default_attr :highlight, true
# end
# @example Deprecating an option while still supporting it
# class TemplateOptions < YARD::Options
# # @return [Boolean] if syntax highlighting should be performed on code blocks.
# # Defaults to true.
# attr_accessor :highlight
#
# # @deprecated Use {#highlight} instead.
# # @return [Boolean] if no syntax highlighting should be performs on code blocks.
# # Defaults to false.
# attr_accessor :no_highlight
# def no_highlight=(value) @highlight = !value end
# def no_highlight; !highlight end
# end
class Options
# @!macro [attach] yard.default_attr
# @!attribute $1
# Defines an attribute named +key+ and sets a default value for it
#
# @example Defining a default option key
# default_attr :name, 'Default Name'
# default_attr :time, lambda { Time.now }
# @param [Symbol] key the option key name
# @param [Object, Proc] default the default object value. If the default
# value is a proc, it is executed upon initialization.
def self.default_attr(key, default)
(@defaults ||= {})[key] = default
attr_accessor(key)
end
# Delegates calls with Hash syntax to actual method with key name
#
# @example Calling on an option key with Hash syntax
# options[:format] # equivalent to: options.format
# @param [Symbol, String] key the option name to access
# @return the value of the option named +key+
def [](key) send(key) end
# Delegates setter calls with Hash syntax to the attribute setter with the key name
#
# @example Setting an option with Hash syntax
# options[:format] = :html # equivalent to: options.format = :html
# @param [Symbol, String] key the optin to set
# @param [Object] value the value to set for the option
# @return [Object] the value being set
def []=(key, value) send("#{key}=", value) end
# Updates values from an options hash or options object on this object.
# All keys passed should be key names defined by attributes on the class.
#
# @example Updating a set of options on an Options object
# opts.update(:template => :guide, :type => :fulldoc)
# @param [Hash, Options] opts
# @return [self]
def update(opts)
opts = opts.to_hash if Options === opts
opts.each do |key, value|
self[key] = value
end
self
end
# Creates a new options object and sets options hash or object value
# onto that object.
#
# @param [Options, Hash] opts
# @return [Options] the newly created options object
# @see #update
def merge(opts)
dup.update(opts)
end
# @return [Hash] Converts options object to an options hash. All keys
# will be symbolized.
def to_hash
opts = {}
instance_variables.each do |ivar|
name = ivar.to_s.sub(/^@/, '')
opts[name.to_sym] = send(name)
end
opts
end
# Yields over every option key and value
# @yield [key, value] every option key and value
# @yieldparam [Symbol] key the option key
# @yieldparam [Object] value the option value
# @return [void]
def each
instance_variables.each do |ivar|
name = ivar.to_s.sub(/^@/, '')
yield(name.to_sym, send(name))
end
end
# Inspects the object
def inspect
"<#{self.class}: #{to_hash.inspect}>"
end
# @return [Boolean] whether another Options object equals the
# keys and values of this options object
def ==(other)
case other
when Options; to_hash == other.to_hash
when Hash; to_hash == other
else false
end
end
# Handles setting and accessing of unregistered keys similar
# to an OpenStruct object.
#
# @note It is not recommended to set and access unregistered keys on
# an Options object. Instead, register the attribute before using it.
def method_missing(meth, *args, &block)
if meth.to_s =~ /^(.+)=$/
log.debug "Attempting to set unregistered key #{$1} on #{self.class}"
instance_variable_set("@#{$1}", args.first)
elsif args.empty?
log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
instance_variable_defined?("@#{meth}") ? instance_variable_get("@#{meth}") : nil
else
super
end
end
# Resets all values to their defaults.
#
# @abstract Subclasses should override this method to perform custom
# value initialization if not using {default_attr}. Be sure to call
# +super+ so that default initialization can take place.
# @return [void]
def reset_defaults
names_set = {}
self.class.ancestors.each do |klass| # look at all ancestors
defaults =
klass.instance_variable_defined?("@defaults") &&
klass.instance_variable_get("@defaults")
next unless defaults
defaults.each do |key, value|
next if names_set[key]
names_set[key] = true
self[key] = Proc === value ? value.call : value
end
end
end
# Deletes an option value for +key+
#
# @param [Symbol, String] key the key to delete a value for
# @return [Object] the value that was deleted
def delete(key)
val = self[key]
if instance_variable_defined?("@#{key}")
remove_instance_variable("@#{key}")
end
val
end
def tap; yield(self); self end unless defined?(tap) # only for 1.8.6
end
end
yard-0.9.7/lib/yard/rake/ 0000755 0000041 0000041 00000000000 13035234564 015152 5 ustar www-data www-data yard-0.9.7/lib/yard/rake/yardoc_task.rb 0000644 0000041 0000041 00000005272 13035234564 020010 0 ustar www-data www-data # frozen_string_literal: true
require 'rake'
require 'rake/tasklib'
module YARD
module Rake
# The rake task to run {CLI::Yardoc} and generate documentation.
class YardocTask < ::Rake::TaskLib
# The name of the task
# @return [String] the task name
attr_accessor :name
# Options to pass to {CLI::Yardoc}
# @return [Array] the options passed to the commandline utility
attr_accessor :options
# Options to pass to {CLI::Stats}
# @return [Array] the options passed to the stats utility
attr_accessor :stats_options
# The Ruby source files (and any extra documentation files separated by '-')
# to process.
# @example Task files assignment
# YARD::Rake::YardocTask.new do |t|
# t.files = ['app/**/*.rb', 'lib/**/*.rb', '-', 'doc/FAQ.md', 'doc/Changes.md']
# end
# @return [Array] a list of files
attr_accessor :files
# Runs a +Proc+ before the task
# @return [Proc] a proc to call before running the task
attr_accessor :before
# Runs a +Proc+ after the task
# @return [Proc] a proc to call after running the task
attr_accessor :after
# @return [Verifier, Proc] an optional {Verifier} to run against all objects
# being generated. Any object that the verifier returns false for will be
# excluded from documentation. This attribute can also be a lambda.
# @see Verifier
attr_accessor :verifier
# Creates a new task with name +name+.
#
# @param [String, Symbol] name the name of the rake task
# @yield a block to allow any options to be modified on the task
# @yieldparam [YardocTask] _self the task object to allow any parameters
# to be changed.
def initialize(name = :yard)
@name = name
@options = []
@stats_options = []
@files = []
yield self if block_given?
self.options += ENV['OPTS'].split(/[ ,]/) if ENV['OPTS']
self.files += ENV['FILES'].split(/[ ,]/) if ENV['FILES']
self.options << '--no-stats' unless stats_options.empty?
define
end
protected
# Defines the rake task
# @return [void]
def define
desc "Generate YARD Documentation" unless ::Rake.application.last_description
task(name) do
before.call if before.is_a?(Proc)
yardoc = YARD::CLI::Yardoc.new
yardoc.options[:verifier] = verifier if verifier
yardoc.run(*(options + files))
YARD::CLI::Stats.run(*(stats_options + ['--use-cache'])) unless stats_options.empty?
after.call if after.is_a?(Proc)
end
end
end
end
end
yard-0.9.7/lib/yard/verifier.rb 0000644 0000041 0000041 00000011531 13035234564 016371 0 ustar www-data www-data # frozen_string_literal: true
module YARD
# Similar to a Proc, but runs a set of Ruby expressions using a small
# DSL to make tag lookups easier.
#
# The syntax is as follows:
# * All syntax is Ruby compatible
# * +object+ (+o+ for short) exist to access the object being verified
# * +@TAGNAME+ is translated into +object.tag('TAGNAME')+
# * +@@TAGNAME+ is translated into +object.tags('TAGNAME')+
# * +object+ can be omitted as target for method calls (it is implied)
#
# @example Create a verifier to check for objects that don't have @private tags
# verifier = Verifier.new('!@private')
# verifier.call(object) # => true (no @private tag)
# @example Create a verifier to find any return tag with an empty description
# Verifier.new('@return.text.empty?')
# # Equivalent to:
# Verifier.new('object.tag(:return).text.empty?')
# @example Check if there are any @param tags
# Verifier.new('@@param.empty?')
# # Equivalent to:
# Verifier.new('object.tags(:param).empty?')
# @example Using +object+ or +o+ to look up object attributes directly
# Verifier.new('object.docstring == "hello world"')
# # Equivalent to:
# Verifier.new('o.docstring == "hello world"')
# @example Without using +object+ or +o+
# Verifier.new('tag(:return).size == 1 || has_tag?(:author)')
# @example Specifying multiple expressions
# Verifier.new('@return', '@param', '@yield')
# # Equivalent to:
# Verifier.new('@return && @param && @yield')
class Verifier
# @return [Array] a list of all expressions the verifier checks for
# @since 0.5.6
attr_reader :expressions
def expressions=(value)
@expressions = value
create_method_from_expressions
end
# Creates a verifier from a set of expressions
#
# @param [Array] expressions a list of Ruby expressions to
# parse.
def initialize(*expressions)
@expressions = []
add_expressions(*expressions)
end
# Adds a set of expressions and recompiles the verifier
#
# @param [Array] expressions a list of expressions
# @return [void]
# @since 0.5.6
def add_expressions(*expressions)
self.expressions += expressions.flatten
end
# Passes any method calls to the object from the {#call}
def method_missing(sym, *args, &block)
if object.respond_to?(sym)
object.send(sym, *args, &block)
else
super
end
end
# Tests the expressions on the object.
#
# @note If the object is a {CodeObjects::Proxy} the result will always be true.
# @param [CodeObjects::Base] object the object to verify
# @return [Boolean] the result of the expressions
def call(object)
return true if object.is_a?(CodeObjects::Proxy)
modify_nilclass
@object = object
retval = __execute ? true : false
unmodify_nilclass
retval
end
# Runs a list of objects against the verifier and returns the subset
# of verified objects.
#
# @param [Array] list a list of code objects
# @return [Array] a list of code objects that match
# the verifier.
def run(list)
list.reject {|item| call(item).is_a?(FalseClass) }
end
protected
# @return [CodeObjects::Base] the current object being tested
attr_reader :object
alias o object
private
# @private
NILCLASS_METHODS = [:type, :method_missing]
# Modifies nil to not throw NoMethodErrors. This allows
# syntax like object.tag(:return).text to work if the #tag
# call returns nil, which means users don't need to perform
# stringent nil checking
#
# @return [void]
def modify_nilclass
NILCLASS_METHODS.each do |meth|
NilClass.send(:define_method, meth) {|*args| }
end
end
# Returns the state of NilClass back to normal
# @return [void]
def unmodify_nilclass
NILCLASS_METHODS.each do |meth|
next unless nil.respond_to?(meth)
NilClass.send(:remove_method, meth)
end
end
# Creates the +__execute+ method by evaluating the expressions
# as Ruby code
# @return [void]
def create_method_from_expressions
expr = expressions.map {|e| "(#{parse_expression(e)})" }.join(" && ")
instance_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef __execute; rescue NameError; end
def __execute; #{expr}; end
eof
end
# Parses a single expression, handling some of the DSL syntax.
#
# The syntax "@tag" should be turned into object.tag(:tag),
# and "@@tag" should be turned into object.tags(:tag)
#
# @return [String] the parsed expression
def parse_expression(expr)
expr = expr.gsub(/@@(?:(\w+)|\{([\w\.]+)\})/, 'object.tags("\1\2")')
expr = expr.gsub(/@(?:(\w+)|\{([\w\.]+)\})/, 'object.tag("\1\2")')
expr
end
end
end
yard-0.9.7/lib/yard/gem_index.rb 0000644 0000041 0000041 00000000637 13035234564 016522 0 ustar www-data www-data # frozen_string_literal: true
# Backward compatability for gem specification lookup
# @see Gem::SourceIndex
module YARD
module GemIndex
module_function
def find_all_by_name(*args)
if defined?(Gem::Specification) && Gem::Specification.respond_to?(:find_all_by_name)
Gem::Specification.find_all_by_name(*args)
else
Gem.source_index.find_name(*args)
end
end
end
end
yard-0.9.7/lib/yard/server/ 0000755 0000041 0000041 00000000000 13035234564 015536 5 ustar www-data www-data yard-0.9.7/lib/yard/server/doc_server_helper.rb 0000644 0000041 0000041 00000007114 13035234564 021560 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
# A module that is mixed into {Templates::Template} in order to customize
# certain template methods.
module DocServerHelper
# Modifies {Templates::Helpers::HtmlHelper#url_for} to return a URL instead
# of a disk location.
# @param (see Templates::Helpers::HtmlHelper#url_for)
# @return (see Templates::Helpers::HtmlHelper#url_for)
def url_for(obj, anchor = nil, relative = false) # rubocop:disable Lint/UnusedMethodArgument
return '' if obj.nil?
return url_for_index if obj == '_index.html'
return abs_url(base_path(router.static_prefix), obj) if String === obj
url = super(obj, anchor, false)
return unless url
abs_url(base_path(router.docs_prefix), url)
end
# Modifies {Templates::Helpers::HtmlHelper#url_for_file} to return a URL instead
# of a disk location.
# @param (see Templates::Helpers::HtmlHelper#url_for_file)
# @return (see Templates::Helpers::HtmlHelper#url_for_file)
def url_for_file(filename, anchor = nil)
if filename.is_a?(CodeObjects::ExtraFileObject)
filename = filename.filename
end
fname = filename.sub(%r{^#{@library.source_path.to_s}/}, '')
fname += "##{anchor}" if anchor && !anchor.empty?
abs_url(base_path(router.docs_prefix), 'file', fname)
end
# Modifies {Templates::Helpers::HtmlHelper#url_for_list} to return a URL
# based on the list prefix instead of a HTML filename.
# @param (see Templates::Helpers::HtmlHelper#url_for_list)
# @return (see Templates::Helpers::HtmlHelper#url_for_list)
def url_for_list(type)
abs_url(base_path(router.list_prefix), type.to_s)
end
# Returns the frames URL for the page
# @return (see Templates::Helpers::HtmlHelper#url_for_frameset)
def url_for_frameset
options.file ? url_for_file(options.file) : url_for(object)
end
# Returns the main URL, first checking a readme and then linking to the index
# @return (see Templates::Helpers::HtmlHelper#url_for_main)
def url_for_main
options.readme ? url_for_file(options.readme) : url_for_index
end
# Returns the URL for the alphabetic index page
# @return (see Templates::Helpers::HtmlHelper#url_for_index)
def url_for_index
abs_url(base_path(router.docs_prefix), 'index')
end
# @param path_components [Array] components of a URL
# @return [String] the absolute path from any mounted base URI.
def abs_url(*path_components)
File.join(router.request.script_name, *path_components)
end
# @example The base path for a library 'foo'
# base_path('docs') # => 'docs/foo'
# @param [String] path the path prefix for a base path URI
# @return [String] the base URI for a library with an extra +path+ prefix
def base_path(path)
libname = router.request.version_supplied ? @library.to_s : @library.name
path + (@single_library ? '' : "/#{libname}")
end
# @return [Router] convenience method for accessing the router
def router; @adapter.router end
# @return [String] a timestamp for a given file
def mtime(file)
file = YARD::Server::Commands::StaticFileHelpers.find_file(@adapter, file)
file ? File.mtime(file).to_i : nil
end
# @return [String] a URL for a file with a timestamp
def mtime_url(file)
url = url_for(file)
time = mtime(file)
url + (time ? "?#{time}" : "")
end
end
end
end
yard-0.9.7/lib/yard/server/static_caching.rb 0000644 0000041 0000041 00000003376 13035234564 021037 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
# Implements static caching for requests.
#
# @see Router Router documentation for "Caching"
module StaticCaching
# Called by a router to return the cached object. By default, this
# method performs disk-based caching. To perform other forms of caching,
# implement your own +#check_static_cache+ method and mix the module into
# the Router class.
#
# Note that caching does not occur here. This method simply checks for
# the existence of cached data. To actually cache a response, see
# {Commands::Base#cache}.
#
# @example Implementing In-Memory Cache Checking
# module MemoryCaching
# def check_static_cache
# # $memory_cache is filled by {Commands::Base#cache}
# cached_data = $memory_cache[request.path]
# if cached_data
# [200, {'Content-Type' => 'text/html'}, [cached_data]]
# else
# nil
# end
# end
# end
#
# class YARD::Server::Router; include MemoryCaching; end
# @return [Array(Numeric,Hash,Array)] the Rack-style response
# @return [nil] if no cache is available and routing should continue
# @see Commands::Base#cache
def check_static_cache
return nil unless adapter.document_root
cache_path = File.join(adapter.document_root, request.path.sub(/\.html$/, '') + '.html')
cache_path = cache_path.sub(%r{/\.html$}, '.html')
if File.file?(cache_path)
log.debug "Loading cache from disk: #{cache_path}"
return [200, {'Content-Type' => 'text/html'}, [File.read_binary(cache_path)]]
end
nil
end
end
end
end
yard-0.9.7/lib/yard/server/router.rb 0000644 0000041 0000041 00000015363 13035234564 017413 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
# A router class implements the logic used to recognize a request for a specific
# URL and run specific {Commands::Base commands}.
#
# == Subclassing Notes
# To create a custom router, subclass this class and pass it into the adapter
# options through {Adapter#initialize} or by directly modifying {Adapter#router}.
#
# The most general customization is to change the URL prefixes recognized by
# routing, which can be done by overriding {#docs_prefix}, {#list_prefix},
# {#static_prefix}, and {#search_prefix}.
#
# == Implementing Custom Caching
# By default, the Router class performs static disk-based caching on all
# requests through the +#check_static_cache+. To override this behaviour,
# or create your own caching mechanism, mixin your own custom module with
# this method implemented as per {StaticCaching#check_static_cache}.
#
# @example Creating a subclassed router
# # Adds 'my' to all routing prefixes
# class MyRouter < YARD::Server::Router
# def docs_prefix; 'mydocs' end
# def list_prefix; 'mylist' end
# def static_prefix; 'mystatic' end
# def search_prefix; 'mysearch' end
# end
#
# # Using it:
# WebrickAdapter.new(libraries, :router => MyRouter).start
class Router
include StaticCaching
include Commands
# @return [Adapter Dependent] the request data coming in with the routing
attr_accessor :request
# @return [Adapter] the adapter used by the router
attr_accessor :adapter
# Creates a new router for a specific adapter
#
# @param [Adapter] adapter the adapter to route requests to
def initialize(adapter)
self.adapter = adapter
end
# Perform routing on a specific request, serving the request as a static
# file through {Commands::RootRequestCommand} if no route is found.
#
# @param [Adapter Dependent] request the request object
# @return [Array(Numeric,Hash,Array)] the Rack-style server response data
def call(request)
self.request = request
result = check_static_cache || route
result ? result : RootRequestCommand.new(adapter.options).call(request)
end
# @group Route Prefixes
# @return [String] the URI prefix for all object documentation requests
def docs_prefix; 'docs' end
# @return [String] the URI prefix for all class/method/file list requests
def list_prefix; 'list' end
# @return [String] the URI prefix for all search requests
def search_prefix; 'search' end
# @return [String] the URI prefix for all static assets (templates)
def static_prefix; 'static' end
# @group Routing Methods
# @return [Array(LibraryVersion, Array)] the library followed
# by the rest of the path components in the request path. LibraryVersion
# will be nil if no matching library was found.
def parse_library_from_path(paths)
return [adapter.libraries.values.first.first, paths] if adapter.options[:single_library]
library = nil
paths = paths.dup
libs = adapter.libraries[paths.first]
if libs
paths.shift
library = libs.find {|l| l.version == paths.first }
if library
request.version_supplied = true if request
paths.shift
else # use the last lib in the list
request.version_supplied = false if request
library = libs.last
end
end
[library, paths]
end
protected
# Performs routing algorithm to find which prefix is called, first
# parsing out library name/version information.
#
# @return [Array(Numeric,Hash,Array)] the Rack-style response
# @return [nil] if no route is matched
def route(path = request.path_info)
path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
return route_index if path.empty? || path == docs_prefix
case path
when %r{^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_prefix})(/.*|$)}
prefix = $1
paths = $2.gsub(%r{^/|/$}, '').split('/')
library, paths = *parse_library_from_path(paths)
return unless library
return case prefix
when docs_prefix; route_docs(library, paths)
when list_prefix; route_list(library, paths)
when search_prefix; route_search(library, paths)
when static_prefix; route_static(library, paths)
end
end
nil
end
# Routes requests from {#docs_prefix} and calls the appropriate command
# @param [LibraryVersion] library the library to route for
# @param [Array] paths path components (split by '/')
# @return (see #route)
def route_docs(library, paths)
return route_index if library.nil?
case paths.first
when "frames"
paths.shift
cmd = DisplayObjectCommand
when "file"
paths.shift
cmd = DisplayFileCommand
else
cmd = DisplayObjectCommand
end
cmd = cmd.new(final_options(library, paths))
cmd.call(request)
end
# Routes for the index of a library / multiple libraries
# @return (see #route)
def route_index
if adapter.options[:single_library]
route_docs(adapter.libraries.values.first.first, [])
else
LibraryIndexCommand.new(adapter.options.merge(:path => '')).call(request)
end
end
# Routes requests from {#list_prefix} and calls the appropriate command
# @param (see #route_docs)
# @return (see #route_docs)
def route_list(library, paths)
return if paths.empty?
ListCommand.new(final_options(library, paths)).call(request)
end
# Routes requests from {#search_prefix} and calls the appropriate command
# @param (see #route_docs)
# @return (see #route_docs)
def route_search(library, paths)
return unless paths.empty?
SearchCommand.new(final_options(library, paths)).call(request)
end
def route_static(library, paths)
StaticFileCommand.new(final_options(library, paths)).call(request)
end
# @group Utility Methods
# Adds extra :library/:path option keys to the adapter options.
# Use this method when passing options to a command.
#
# @param (see #route_docs)
# @return [Hash] finalized options
def final_options(library, paths)
path = File.cleanpath(paths.join('/')).gsub(%r{^(\.\./)+}, '')
adapter.options.merge(:library => library, :path => path)
end
end
end
end
yard-0.9.7/lib/yard/server/doc_server_serializer.rb 0000644 0000041 0000041 00000002417 13035234564 022453 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
# A custom {Serializers::Base serializer} which returns resource URLs instead of
# static relative paths to files on disk.
class DocServerSerializer < Serializers::FileSystemSerializer
def initialize(_command = nil)
super(:basepath => '', :extension => '')
end
def serialized_path(object)
case object
when CodeObjects::RootObject
"toplevel"
when CodeObjects::ExtendedMethodObject
serialized_path(object.namespace) + ':' + urlencode(object.name.to_s)
when CodeObjects::MethodObject
serialized_path(object.namespace) +
(object.scope == :instance ? ":" : ".") + urlencode(object.name.to_s)
when CodeObjects::ConstantObject, CodeObjects::ClassVariableObject
serialized_path(object.namespace) + "##{object.name}-#{object.type}"
when CodeObjects::ExtraFileObject
super(object).gsub(/^file\./, 'file/')
else
super(object)
end
end
private
def urlencode(name)
if name.respond_to?(:force_encoding)
name = name.dup.force_encoding('binary')
end
Templates::Helpers::HtmlHelper.urlencode(name)
end
end
end
end
yard-0.9.7/lib/yard/server/commands/ 0000755 0000041 0000041 00000000000 13035234564 017337 5 ustar www-data www-data yard-0.9.7/lib/yard/server/commands/list_command.rb 0000644 0000041 0000041 00000001225 13035234564 022335 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Returns a list of objects of a specific type
class ListCommand < LibraryCommand
include Templates::Helpers::BaseHelper
def run
Registry.load_all
options.update(:objects => run_verifier(Registry.all(:class, :module)))
list_type = request.path.split('/').last
meth = "generate_#{list_type}_list"
tpl = fulldoc_template
if tpl.respond_to?(meth)
tpl.send(meth)
cache(tpl.contents)
else
not_found
end
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/display_object_command.rb 0000644 0000041 0000041 00000003252 13035234564 024357 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Displays documentation for a specific object identified by the path
class DisplayObjectCommand < LibraryCommand
include DocServerHelper
def run
if path.empty?
if options.readme
filename = options.readme.filename
opts = adapter.options.merge(
:index => true, :library => library,
:path => filename.sub(%r{^#{library.source_path.to_s}/}, '')
)
self.status, self.headers, self.body =
*DisplayFileCommand.new(opts).call(request)
cache(body)
return
else
self.path = 'index'
end
end
return index if path == 'index'
object = Registry.at(object_path)
if object
options.update(:type => :layout)
render(object)
else
not_found
end
end
def index
Registry.load_all
options.update(
:object => '_index.html',
:objects => Registry.all(:module, :class),
:type => :layout
)
render
end
def not_found
super
self.body = "Could not find object: #{object_path}"
end
private
def object_path
return @object_path if @object_path
if path == "toplevel"
@object_path = :root
else
@object_path = path.sub(':', '#').gsub('/', '::').sub(/^toplevel\b/, '').sub(/\.html$/, '')
end
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/root_request_command.rb 0000644 0000041 0000041 00000000474 13035234564 024122 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Serves requests from the root of the server
class RootRequestCommand < Base
include StaticFileHelpers
def run
static_template_file? || favicon? || not_found
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/frames_command.rb 0000644 0000041 0000041 00000000600 13035234564 022633 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Displays an object wrapped in frames
class FramesCommand < DisplayObjectCommand
def run
options.update(:frames => true, :type => :fulldoc)
tpl = fulldoc_template
tpl.generate_frameset
cache(tpl.contents)
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/library_index_command.rb 0000644 0000041 0000041 00000001316 13035234564 024216 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
class LibraryIndexOptions < CLI::YardocOptions
attr_accessor :adapter, :libraries
default_attr :template, :doc_server
default_attr :type, :library_list
default_attr :serialize, false
end
# Returns the index of libraries served by the server.
class LibraryIndexCommand < Base
attr_accessor :options
def run
return unless path.empty?
self.options = LibraryIndexOptions.new
options.adapter = adapter
options.libraries = adapter.libraries
options.reset_defaults
render
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/static_file_helpers.rb 0000644 0000041 0000041 00000003667 13035234564 023710 0 ustar www-data www-data # frozen_string_literal: true
require 'webrick/httputils'
module YARD
module Server
module Commands
# Include this module to get access to {#static_template_file?}
# and {favicon?} helpers.
module StaticFileHelpers
include WEBrick::HTTPUtils
# Serves an empty favicon.
# @raise [FinishRequest] finalizes an empty body if the path matches
# /favicon.ico so browsers don't complain.
def favicon?
return unless request.path == '/favicon.ico'
headers['Content-Type'] = 'image/png'
self.status = 200
self.body = ''
raise FinishRequest
end
# Attempts to route a path to a static template file.
#
# @raise [FinishRequest] if a file was found and served
# @return [void]
def static_template_file?
# this const was defined in StaticFileCommand originally
default_mime_types = StaticFileCommand::DefaultMimeTypes
file = find_file(adapter, path)
if file
ext = "." + (path[/\.(\w+)$/, 1] || "html")
headers['Content-Type'] = mime_type(ext, default_mime_types)
self.body = File.read(file)
raise FinishRequest
end
end
module_function
def find_file(adapter, url)
# this const was defined in StaticFileCommand originally
static_paths = StaticFileCommand::STATIC_PATHS
file = nil
([adapter.document_root] + static_paths.reverse).compact.each do |path_prefix|
file = File.join(path_prefix, url)
p file
break if File.exist?(file)
file = nil
end
# Search in default/fulldoc/html template if nothing in static asset paths
assets_template = Templates::Engine.template(:default, :fulldoc, :html)
file || assets_template.find_file(url)
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/static_file_command.rb 0000644 0000041 0000041 00000001274 13035234564 023654 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Serves static content when no other router matches a request
class StaticFileCommand < LibraryCommand
include StaticFileHelpers
DefaultMimeTypes['js'] = 'text/javascript'
# Defines the paths used to search for static assets. To define an
# extra path, use {YARD::Server.register_static_path} rather than
# modifying this constant directly. Also note that files in the
# document root will always take precedence over these paths.
STATIC_PATHS = []
def run
static_template_file? || not_found
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/display_file_command.rb 0000644 0000041 0000041 00000001722 13035234564 024030 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Displays a README or extra file.
#
# @todo Implement better support for detecting binary (image) filetypes
class DisplayFileCommand < LibraryCommand
attr_accessor :index
def run
filename = File.cleanpath(File.join(library.source_path, path))
raise NotFoundError unless File.file?(filename)
if filename =~ /\.(jpe?g|gif|png|bmp)$/i
headers['Content-Type'] = StaticFileCommand::DefaultMimeTypes[$1.downcase] || 'text/html'
render File.read_binary(filename)
else
file = CodeObjects::ExtraFileObject.new(filename)
options.update :object => Registry.root,
:type => :layout,
:file => file,
:index => index ? true : false
render
end
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/base.rb 0000644 0000041 0000041 00000016205 13035234564 020602 0 ustar www-data www-data # frozen_string_literal: true
require 'fileutils'
module YARD
module Server
module Commands
# This is the base command class used to implement custom commands for
# a server. A command will be routed to by the {Router} class and return
# a Rack-style response.
#
# == Attribute Initializers
# All attributes can be initialized via options passed into the {#initialize}
# method. When creating a custom command, the {Adapter#options} will
# automatically be mapped to attributes by the same name on your class.
#
# class MyCommand < Base
# attr_accessor :myattr
# end
#
# Adapter.new(libs, {:myattr => 'foo'}).start
#
# # when a request comes in, cmd.myattr == 'foo'
#
# == Subclassing Notes
# To implement a custom command, override the {#run} method, not {#call}.
# In your implementation, you should set the body and status for requests.
# See details in the +#run+ method documentation.
#
# Note that if your command deals directly with libraries, you should
# consider subclassing the more specific {LibraryCommand} class instead.
#
# @abstract
# @see #run
class Base
# @group Basic Command and Adapter Options
# @return [Hash] the options passed to the command's constructor
attr_accessor :command_options
# @return [Adapter] the server adapter
attr_accessor :adapter
# @return [Boolean] whether to cache
attr_accessor :caching
# @group Attributes Set Per Request
# @return [Request] request object
attr_accessor :request
# @return [String] the path after the command base URI
attr_accessor :path
# @return [Hash{String => String}] response headers
attr_accessor :headers
# @return [Numeric] status code. Defaults to 200 per request
attr_accessor :status
# @return [String] the response body. Defaults to empty string.
attr_accessor :body
# @group Instance Method Summary
# Creates a new command object, setting attributes named by keys
# in the options hash. After initialization, the options hash
# is saved in {#command_options} for further inspection.
#
# @example Creating a Command
# cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
# cmd.library # => mylib
# cmd.command_options # => {:caching => true, :library => mylib}
# @param [Hash] opts the options hash, saved to {#command_options}
# after initialization.
def initialize(opts = {})
opts.each do |key, value|
send("#{key}=", value) if respond_to?("#{key}=")
end
self.command_options = opts
end
# The main method called by a router with a request object.
#
# @note This command should not be overridden by subclasses. Implement
# the callback method {#run} instead.
# @param [Adapter Dependent] request the request object
# @return [Array(Numeric,Hash,Array)] a Rack-style response
# of status, headers, and body wrapped in an array.
def call(request)
self.request = request
self.path ||= request.path_info[1..-1]
self.headers = {'Content-Type' => 'text/html'}
self.body = ''
self.status = 200
add_cache_control
begin
run
rescue FinishRequest
nil # noop
rescue NotFoundError => e
self.body = e.message if e.message != e.class.to_s
not_found
end
# keep this to support commands setting status manually.
not_found if status == 404
[status, headers, body.is_a?(Array) ? body : [body]]
end
# @group Abstract Methods
# Subclass this method to implement a custom command. This method
# should set the {#status} and {#body}, and optionally modify the
# {#headers}. Note that +#status+ defaults to 200.
#
# @example A custom command
# class ErrorCommand < Base
# def run
# self.body = 'ERROR! The System is down!'
# self.status = 500
# self.headers['Conten-Type'] = 'text/plain'
# end
# end
#
# @abstract
# @return [void]
def run
raise NotImplementedError
end
protected
# @group Helper Methods
# Renders a specific object if provided, or a regular template rendering
# if object is not provided.
#
# @todo This method is dependent on +#options+, it should be in {LibraryCommand}.
# @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if
# an object is provided, or {Templates::Engine.render} if object is nil. Both
# receive +#options+ as an argument.
# @return [String] the resulting output to display
def render(object = nil)
case object
when CodeObjects::Base
cache object.format(options)
when nil
cache Templates::Engine.render(options)
else
cache object
end
end
# Override this method to implement custom caching mechanisms for
#
# @example Caching to memory
# $memory_cache = {}
# def cache(data)
# $memory_cache[path] = data
# end
# @param [String] data the data to cache
# @return [String] the same cached data (for chaining)
# @see StaticCaching
def cache(data)
if caching && adapter.document_root
path = File.join(adapter.document_root, request.path_info.sub(/\.html$/, '') + '.html')
path = path.sub(%r{/\.html$}, '.html')
FileUtils.mkdir_p(File.dirname(path))
log.debug "Caching data to #{path}"
File.open(path, 'wb') {|f| f.write(data) }
end
self.body = data
end
# Sets the body and headers for a 404 response. Does not modify the
# body if already set.
#
# @return [void]
def not_found
self.status = 404
return unless body.empty?
self.body = "Not found: #{request.path}"
headers['Content-Type'] = 'text/plain'
headers['X-Cascade'] = 'pass'
headers.delete('Cache-Control')
end
# Sets the headers and status code for a redirection to a given URL
# @param [String] url the URL to redirect to
# @raise [FinishRequest] causes the request to terminate.
def redirect(url)
headers['Location'] = url
self.status = 302
raise FinishRequest
end
private
# Add a conservative cache control policy to reduce load on
# requests served with "?1234567890" style timestamp query strings.
def add_cache_control
return if request.query_string.to_i == 0
headers['Cache-Control'] = 'private, max-age=300'
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/library_command.rb 0000644 0000041 0000041 00000013361 13035234564 023032 0 ustar www-data www-data # frozen_string_literal: true
require 'thread'
module YARD
module Server
module Commands
class LibraryOptions < CLI::YardocOptions
def adapter; @command.adapter end
def library; @command.library end
def single_library; @command.single_library end
def serializer; @command.serializer end
def serialize; false end
attr_accessor :command
attr_accessor :frames
def each(&block)
super(&block)
yield(:adapter, adapter)
yield(:library, library)
yield(:single_library, single_library)
yield(:serializer, serializer)
end
end
# This is the base command for all commands that deal directly with libraries.
# Some commands do not, but most (like {DisplayObjectCommand}) do. If your
# command deals with libraries directly, subclass this class instead.
# See {Base} for notes on how to subclass a command.
#
# @abstract
class LibraryCommand < Base
begin
Process.fork { exit 0 }
CAN_FORK = true
rescue Exception # rubocop:disable Lint/RescueException
CAN_FORK = false
end
# @return [LibraryVersion] the object containing library information
attr_accessor :library
# @return [LibraryOptions] default options for the library
attr_accessor :options
# @return [Serializers::Base] the serializer used to perform file linking
attr_accessor :serializer
# @return [Boolean] whether router should route for multiple libraries
attr_accessor :single_library
# @return [Boolean] whether to reparse data
attr_accessor :incremental
# @return [Boolean] whether or not this adapter calls +fork+ when serving
# library requests. Defaults to false.
attr_accessor :use_fork
# Needed to synchronize threads in {#setup_yardopts}
# @private
@@library_chdir_lock = Mutex.new
def initialize(opts = {})
super
self.serializer = DocServerSerializer.new
end
def call(request)
if can_fork?
call_with_fork(request) { super }
else
begin
save_default_template_info
call_without_fork(request) { super }
ensure
restore_template_info
end
end
end
private
def call_without_fork(request)
self.request = request
self.options = LibraryOptions.new
options.reset_defaults
options.command = self
setup_library
options.title = "Documentation for #{library.name} " +
(library.version ? '(' + library.version + ')' : '')
yield
rescue LibraryNotPreparedError
not_prepared
end
def call_with_fork(request, &block)
reader, writer = IO.pipe
fork do
log.debug "[pid=#{Process.pid}] fork serving: #{request.path}"
reader.close
writer.print(Marshal.dump(call_without_fork(request, &block)))
end
writer.close
Marshal.load(reader.read)
end
def can_fork?
CAN_FORK && use_fork
end
def save_default_template_info
@old_template_paths = Templates::Engine.template_paths.dup
@old_extra_includes = Templates::Template.extra_includes.dup
end
def restore_template_info
Templates::Engine.template_paths = @old_template_paths
Templates::Template.extra_includes = @old_extra_includes
end
def setup_library
library.prepare! if request.xhr? && request.query['process']
load_yardoc
setup_yardopts
true
end
def setup_yardopts
@@library_chdir_lock.synchronize do
Dir.chdir(library.source_path) do
yardoc = CLI::Yardoc.new
if incremental
yardoc.run('-c', '-n', '--no-stats')
else
yardoc.parse_arguments
end
yardoc.send(:verify_markup_options)
yardoc.options.delete(:serializer)
yardoc.options.delete(:serialize)
options.update(yardoc.options.to_hash)
end
end
end
def load_yardoc
raise LibraryNotPreparedError unless library.ready?
if Thread.current[:__yard_last_yardoc__] == library.yardoc_file
log.debug "Reusing yardoc file: #{library.yardoc_file}"
return
end
Registry.clear
Templates::ErbCache.clear!
Registry.load_yardoc(library.yardoc_file)
Thread.current[:__yard_last_yardoc__] = library.yardoc_file
end
def not_prepared
options.update(:template => :doc_server, :type => :processing)
self.caching = false
self.status = 202
self.body = render
self.headers = {'Content-Type' => 'text/html'}
[status, headers, [body]]
end
# Hack to load a custom fulldoc template object that does
# not do any rendering/generation. We need this to access the
# generate_*_list methods.
def fulldoc_template
tplopts = [options.template, :fulldoc, options.format]
tplclass = Templates::Engine.template(*tplopts)
obj = Object.new.extend(tplclass)
class << obj; define_method(:init) {} end
obj.class = tplclass
obj.send(:initialize, options)
class << obj
attr_reader :contents
define_method(:asset) {|_, contents| @contents = contents }
end
obj
end
end
end
end
end
yard-0.9.7/lib/yard/server/commands/search_command.rb 0000644 0000041 0000041 00000004574 13035234564 022641 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
module Commands
# Performs a search over the objects inside of a library and returns
# the results as HTML or plaintext
class SearchCommand < LibraryCommand
include Templates::Helpers::BaseHelper
include Templates::Helpers::ModuleHelper
include DocServerHelper
attr_accessor :results, :query
def run
Registry.load_all
self.query = request.query['q']
redirect(abs_url(adapter.router.docs_prefix, single_library ? library : '')) if query.nil? || query =~ /\A\s*\Z/
found = Registry.at(query)
redirect(url_for(found)) if found
search_for_object
request.xhr? ? serve_xhr : serve_normal
end
def visible_results
results[0, 10]
end
private
def url_for(object)
abs_url(base_path(router.docs_prefix),
serializer.serialized_path(object))
end
def serve_xhr
headers['Content-Type'] = 'text/plain'
self.body = visible_results.map {|o|
[(o.type == :method ? o.name(true) : o.name).to_s,
o.path,
o.namespace.root? ? '' : o.namespace.path,
url_for(o)].join(",")
}.join("\n")
end
def serve_normal
options.update(
:visible_results => visible_results,
:query => query,
:results => results,
:template => :doc_server,
:type => :search
)
self.body = Templates::Engine.render(options)
end
def search_for_object
# rubocop:disable Style/MultilineBlockChain
self.results = run_verifier(Registry.all).select do |o|
o.path.downcase.include?(query.downcase)
end.reject do |o|
name = (o.type == :method ? o.name(true) : o.name).to_s.downcase
!name.include?(query.downcase) ||
case o.type
when :method
!(query =~ /[#.]/) && query.include?("::")
when :class, :module, :constant, :class_variable
query =~ /[#.]/
end
end.sort_by do |o|
name = (o.type == :method ? o.name(true) : o.name).to_s
name.length.to_f / query.length.to_f
end
end
end
end
end
end
yard-0.9.7/lib/yard/server/templates/ 0000755 0000041 0000041 00000000000 13035234564 017534 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/ 0000755 0000041 0000041 00000000000 13035234564 021160 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/method_details/ 0000755 0000041 0000041 00000000000 13035234564 024145 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/method_details/html/ 0000755 0000041 0000041 00000000000 13035234564 025111 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/method_details/html/permalink.erb 0000644 0000041 0000041 00000000345 13035234564 027567 0 ustar www-data www-data
yard-0.9.7/lib/yard/server/templates/default/method_details/html/setup.rb 0000644 0000041 0000041 00000000155 13035234564 026577 0 ustar www-data www-data # frozen_string_literal: true
def init
super
sections.place(:permalink).after_any(:method_signature)
end
yard-0.9.7/lib/yard/server/templates/default/layout/ 0000755 0000041 0000041 00000000000 13035234564 022475 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/layout/html/ 0000755 0000041 0000041 00000000000 13035234564 023441 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/layout/html/script_setup.erb 0000644 0000041 0000041 00000000475 13035234564 026665 0 ustar www-data www-data
yard-0.9.7/lib/yard/server/templates/default/layout/html/setup.rb 0000644 0000041 0000041 00000000205 13035234564 025123 0 ustar www-data www-data # frozen_string_literal: true
def javascripts
super + %w(js/autocomplete.js)
end
def stylesheets
super + %w(css/custom.css)
end
yard-0.9.7/lib/yard/server/templates/default/layout/html/breadcrumb.erb 0000644 0000041 0000041 00000003413 13035234564 026242 0 ustar www-data www-data
yard-0.9.7/lib/yard/server/templates/default/fulldoc/ 0000755 0000041 0000041 00000000000 13035234564 022610 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/ 0000755 0000041 0000041 00000000000 13035234564 023554 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/js/ 0000755 0000041 0000041 00000000000 13035234564 024170 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/js/autocomplete.js 0000644 0000041 0000041 00000017503 13035234564 027235 0 ustar www-data www-data /*
* jQuery Autocomplete plugin 1.1
*
* Copyright (c) 2009 Jörn Zaefferer
*
* Dual licensed under the MIT and GPL licenses:
* http://www.opensource.org/licenses/mit-license.php
* http://www.gnu.org/licenses/gpl.html
*
* Revision: $Id: jquery.autocomplete.js 15 2009-08-22 10:30:27Z joern.zaefferer $
*/
eval(function(p,a,c,k,e,r){e=function(c){return(c35?String.fromCharCode(c+29):c.toString(36))};if(!''.replace(/^/,String)){while(c--)r[e(c)]=k[c]||e(c);k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}(';(3($){$.2e.1u({19:3(b,d){5 c=W b=="1B";d=$.1u({},$.M.1T,{Y:c?b:P,y:c?P:b,1J:c?$.M.1T.1J:10,X:d&&!d.1D?10:48},d);d.1y=d.1y||3(a){6 a};d.1v=d.1v||d.1R;6 A.I(3(){1M $.M(A,d)})},L:3(a){6 A.11("L",a)},1k:3(a){6 A.14("1k",[a])},2b:3(){6 A.14("2b")},28:3(a){6 A.14("28",[a])},24:3(){6 A.14("24")}});$.M=3(o,r){5 t={2Y:38,2S:40,2N:46,2I:9,2E:13,2B:27,2x:3I,2v:33,2p:34,2n:8};5 u=$(o).3r("19","3o").Q(r.2Q);5 p;5 m="";5 n=$.M.3c(r);5 s=0;5 k;5 h={1F:C};5 l=$.M.32(r,o,1Z,h);5 j;$.1Y.2X&&$(o.2U).11("45.19",3(){4(j){j=C;6 C}});u.11(($.1Y.2X?"43":"42")+".19",3(a){s=1;k=a.2M;3V(a.2M){O t.2Y:a.1d();4(l.N()){l.30()}w{12(0,D)}R;O t.2S:a.1d();4(l.N()){l.2D()}w{12(0,D)}R;O t.2v:a.1d();4(l.N()){l.2C()}w{12(0,D)}R;O t.2p:a.1d();4(l.N()){l.2A()}w{12(0,D)}R;O r.17&&$.1c(r.S)==","&&t.2x:O t.2I:O t.2E:4(1Z()){a.1d();j=D;6 C}R;O t.2B:l.Z();R;3J:1P(p);p=1O(12,r.1J);R}}).2t(3(){s++}).3E(3(){s=0;4(!h.1F){2r()}}).2q(3(){4(s++>1&&!l.N()){12(0,D)}}).11("1k",3(){5 c=(1r.7>1)?1r[1]:P;3 1N(q,a){5 b;4(a&&a.7){16(5 i=0;i1){5 f=r.S.7;5 c=$(o).18().1I;5 d,1H=0;$.I(b,3(i,a){1H+=a.7;4(c<=1H){d=i;6 C}1H+=f});b[d]=v;v=b.3f(r.S)}v+=r.S}u.K(v);1l();u.14("L",[e.y,e.F]);6 D}3 12(b,c){4(k==t.2N){l.Z();6}5 a=u.K();4(!c&&a==m)6;m=a;a=1m(a);4(a.7>=r.29){u.Q(r.26);4(!r.1s)a=a.J();21(a,3a,1l)}w{1q();l.Z()}};3 15(b){4(!b)6[""];4(!r.17)6[$.1c(b)];6 $.4h(b.23(r.S),3(a){6 $.1c(b).7?$.1c(a):P})}3 1m(a){4(!r.17)6 a;5 c=15(a);4(c.7==1)6 c[0];5 b=$(o).18().1I;4(b==a.7){c=15(a)}w{c=15(a.22(a.37(b),""))}6 c[c.7-1]}3 1G(q,a){4(r.1G&&(1m(u.K()).J()==q.J())&&k!=t.2n){u.K(u.K()+a.37(1m(m).7));$(o).18(m.7,m.7+a.7)}};3 2r(){1P(p);p=1O(1l,4g)};3 1l(){5 c=l.N();l.Z();1P(p);1q();4(r.36){u.1k(3(a){4(!a){4(r.17){5 b=15(u.K()).1n(0,-1);u.K(b.3f(r.S)+(b.7?r.S:""))}w{u.K("");u.14("L",P)}}})}};3 3a(q,a){4(a&&a.7&&s){1q();l.35(a,q);1G(q,a[0].F);l.20()}w{1l()}};3 21(f,d,g){4(!r.1s)f=f.J();5 e=n.31(f);4(e&&e.7){d(f,e)}w 4((W r.Y=="1B")&&(r.Y.7>0)){5 c={4f:+1M 4e()};$.I(r.2Z,3(a,b){c[a]=W b=="3"?b():b});$.4d({4c:"4b",4a:"19"+o.49,2V:r.2V,Y:r.Y,y:$.1u({q:1m(f),47:r.X},c),44:3(a){5 b=r.1A&&r.1A(a)||1A(a);n.1i(f,b);d(f,b)}})}w{l.2T();g(f)}};3 1A(c){5 d=[];5 b=c.23("\\n");16(5 i=0;i]*)("+a.22(/([\\^\\$\\(\\)\\[\\]\\{\\}\\*\\.\\+\\?\\|\\\\])/2K,"\\\\$1")+")(?![^<>]*>)(?![^&;]+;)","2K"),"<2J>$1")},1D:D,1E:3S};$.M.3c=3(g){5 h={};5 j=0;3 1f(s,a){4(!g.1s)s=s.J();5 i=s.2H(a);4(g.1w=="3R"){i=s.J().1k("\\\\b"+a.J())}4(i==-1)6 C;6 i==0||g.1w};3 1i(q,a){4(j>g.1g){1o()}4(!h[q]){j++}h[q]=a}3 1e(){4(!g.y)6 C;5 f={},2G=0;4(!g.Y)g.1g=1;f[""]=[];16(5 i=0,2F=g.y.7;i<2F;i++){5 c=g.y[i];c=(W c=="1B")?[c]:c;5 d=g.1v(c,i+1,g.y.7);4(d===C)1V;5 e=d.3Q(0).J();4(!f[e])f[e]=[];5 b={F:d,y:c,L:g.1z&&g.1z(c)||d};f[e].1U(b);4(2G++0){5 c=h[k];$.I(c,3(i,x){4(1f(x.F,q)){a.1U(x)}})}}6 a}w 4(h[q]){6 h[q]}w 4(g.1f){16(5 i=q.7-1;i>=g.29;i--){5 c=h[q.3O(0,i)];4(c){5 a=[];$.I(c,3(i,x){4(1f(x.F,q)){a[a.7]=x}});6 a}}}6 P}}};$.M.32=3(e,g,f,k){5 h={H:"3N"};5 j,z=-1,y,1t="",1S=D,G,B;3 2y(){4(!1S)6;G=$("<3M/>").Z().Q(e.2P).T("3L","3K").1Q(1K.2w);B=$("<3H/>").1Q(G).3G(3(a){4(U(a).2u&&U(a).2u.3F()==\'2s\'){z=$("1L",B).1h(h.H).3D(U(a));$(U(a)).Q(h.H)}}).2q(3(a){$(U(a)).Q(h.H);f();g.2t();6 C}).3C(3(){k.1F=D}).3B(3(){k.1F=C});4(e.E>0)G.T("E",e.E);1S=C}3 U(a){5 b=a.U;3A(b&&b.3z!="2s")b=b.3y;4(!b)6[];6 b}3 V(b){j.1n(z,z+1).1h(h.H);2o(b);5 a=j.1n(z,z+1).Q(h.H);4(e.1D){5 c=0;j.1n(0,z).I(3(){c+=A.1a});4((c+a[0].1a-B.1b())>B[0].3x){B.1b(c+a[0].1a-B.3w())}w 4(c=j.1j()){z=0}}3 2m(a){6 e.X&&e.X").3v(e.1y(a,1t)).Q(i%2==0?"3u":"3P").1Q(B)[0];$.y(c,"2k",y[i])}j=B.3t("1L");4(e.1X){j.1n(0,1).Q(h.H);z=0}4($.2e.2W)B.2W()}6{35:3(d,q){2y();y=d;1t=q;2l()},2D:3(){V(1)},30:3(){V(-1)},2C:3(){4(z!=0&&z-8<0){V(-z)}w{V(-8)}},2A:3(){4(z!=j.1j()-1&&z+8>j.1j()){V(j.1j()-1-z)}w{V(8)}},Z:3(){G&&G.Z();j&&j.1h(h.H);z=-1},N:3(){6 G&&G.3s(":N")},3q:3(){6 A.N()&&(j.2j("."+h.H)[0]||e.1X&&j[0])},20:3(){5 a=$(g).3p();G.T({E:W e.E=="1B"||e.E>0?e.E:$(g).E(),2i:a.2i+g.1a,1W:a.1W}).20();4(e.1D){B.1b(0);B.T({2L:e.1E,3n:\'3X\'});4($.1Y.3m&&W 1K.2w.3l.2L==="1x"){5 c=0;j.I(3(){c+=A.1a});5 b=c>e.1E;B.T(\'3k\',b?e.1E:c);4(!b){j.E(B.E()-2R(j.T("2O-1W"))-2R(j.T("2O-3j")))}}}},2g:3(){5 a=j&&j.2j("."+h.H).1h(h.H);6 a&&a.7&&$.y(a[0],"2k")},2T:3(){B&&B.2z()},1p:3(){G&&G.3i()}}};$.2e.18=3(b,f){4(b!==1x){6 A.I(3(){4(A.2d){5 a=A.2d();4(f===1x||b==f){a.4n("2c",b);a.3h()}w{a.4m(D);a.4l("2c",b);a.4k("2c",f);a.3h()}}w 4(A.3g){A.3g(b,f)}w 4(A.1C){A.1C=b;A.3e=f}})}5 c=A[0];4(c.2d){5 e=1K.18.4j(),3d=c.F,2a="<->",2f=e.3b.7;e.3b=2a;5 d=c.F.2H(2a);c.F=3d;A.18(d,d+2f);6{1I:d,39:d+2f}}w 4(c.1C!==1x){6{1I:c.1C,39:c.3e}}}})(4i);',62,272,'|||function|if|var|return|length|||||||||||||||||||||||||else||data|active|this|list|false|true|width|value|element|ACTIVE|each|toLowerCase|val|result|Autocompleter|visible|case|null|addClass|break|multipleSeparator|css|target|moveSelect|typeof|max|url|hide||bind|onChange||trigger|trimWords|for|multiple|selection|autocomplete|offsetHeight|scrollTop|trim|preventDefault|populate|matchSubset|cacheLength|removeClass|add|size|search|hideResultsNow|lastWord|slice|flush|unbind|stopLoading|arguments|matchCase|term|extend|formatMatch|matchContains|undefined|highlight|formatResult|parse|string|selectionStart|scroll|scrollHeight|mouseDownOnSelect|autoFill|progress|start|delay|document|li|new|findValueCallback|setTimeout|clearTimeout|appendTo|formatItem|needsInit|defaults|push|continue|left|selectFirst|browser|selectCurrent|show|request|replace|split|unautocomplete||loadingClass||setOptions|minChars|teststring|flushCache|character|createTextRange|fn|textLength|selected|in|top|filter|ac_data|fillList|limitNumberOfItems|BACKSPACE|movePosition|PAGEDOWN|click|hideResults|LI|focus|nodeName|PAGEUP|body|COMMA|init|empty|pageDown|ESC|pageUp|next|RETURN|ol|nullData|indexOf|TAB|strong|gi|maxHeight|keyCode|DEL|padding|resultsClass|inputClass|parseInt|DOWN|emptyList|form|dataType|bgiframe|opera|UP|extraParams|prev|load|Select|||display|mustMatch|substring||end|receiveData|text|Cache|orig|selectionEnd|join|setSelectionRange|select|remove|right|height|style|msie|overflow|off|offset|current|attr|is|find|ac_even|html|innerHeight|clientHeight|parentNode|tagName|while|mouseup|mousedown|index|blur|toUpperCase|mouseover|ul|188|default|absolute|position|div|ac_over|substr|ac_odd|charAt|word|180|RegExp|100|switch|400|auto|ac_loading|ac_results||ac_input|keydown|keypress|success|submit||limit|150|name|port|abort|mode|ajax|Date|timestamp|200|map|jQuery|createRange|moveEnd|moveStart|collapse|move'.split('|'),0,{})) yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/images/ 0000755 0000041 0000041 00000000000 13035234564 025021 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/images/processing.gif 0000644 0000041 0000041 00000002343 13035234564 027666 0 ustar www-data www-data GIF89a õ øøøèèèÒÒÒ¼¼¼®®®¢¢¢ÜÜܸ¸¸šššäääØØتªª °°°ÌÌÌööö¨¨¨ÔÔÔÿÿÿ666&&&PPPÄÄÄppp’’’VVVúúúhhhFFFÆÆÆHHH222æææ !ÿ NETSCAPE2.0 !ù
ÿ , ÿ@‰pH „‚dR¹ Ĩth8 ®W e»Ý4 Sib€-k¹ÜK'²…£\ Øí¡ån¯1|!! B‹
C| Gv s A !ù
! , W@‰p(| ŽÇ‘˜@ ˡÉD…
ªà¡"Q„zˆv$^QSàPÐH«$`Ád(ø÷q‘æÿx
C€ K†x ‰†gŽy
WWCA !ù
, M "Jdž¨”Hb+Q\¡¥g!ìHíT†YÉ#áh´p8žr—;º>KeÓ‰`,I¢ˆ‘$H¤ÖñŒ ˆlÑx lvœ}1Èè—b ׃6"h8¤ƒ’€`@(„ !ù
! , YÀpñC …r\–Kc
n¨NÇ¥BlFzR1Â
Ö"œ`Ǹ°€¨× B‚½žöB€
!€B€ !ŠBvG ur
GA !ù
! , V@‰pHt .• qhl(PèRÒ¹D¯Ë…çŠ%~¸]‰‚!G…‰QŽf0–€p°^—9
ÑP¯S§} S‚S‚
‹t}‚ ‚A ; yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/css/ 0000755 0000041 0000041 00000000000 13035234564 024344 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/default/fulldoc/html/css/custom.css 0000644 0000041 0000041 00000005750 13035234564 026377 0 ustar www-data www-data #search_results h1 { margin-bottom: 0; }
#search_results p { margin-top: 0; margin-bottom: 25px; }
#search_results ul { list-style-position: inside; padding-left: 0; list-style: none; }
#search_results ul li { padding: 7px 15px; font-size: 1.1em; }
form.search {
z-index: 8000;
position: absolute;
color: #fff;
border: 1px solid #99f; width: 210px; background: #05a;
border-radius: 4px; border-top-left-radius: 0; border-top-right-radius: 0;
}
form.search input {
height: 25px;
padding: 0;
padding-left: 4px;
margin: 4px;
margin-right: 0;
width: 202px;
border: 1px solid #99f;
border-radius: 3px;
font-size: 1.1em;
box-sizing: border-box;
-webkit-appearance: none;
}
@media (max-width: 920px) {
form.search {
position: absolute;
color: #fff;
width: 100%;
margin-top: 0;
background: #05a;
border-radius: 0;
border: 0;
margin-bottom: 10px;
left: 0;
top: 0;
}
form.search input {
margin-top: 9px;
margin-bottom: 11px;
margin-left: 12px;
padding-left: 6px;
border: 1px solid #eaf0ff;
}
#menu { margin-top: 41px; }
#search a {
border-top-left-radius: 3px; border-top-right-radius: 3px;
background: none;
border: 0;
box-shadow: none;
margin-top: 4px;
padding-bottom: 5px;
color: #eaf0ff; fill: #eaf0ff;
}
#search a.active {
background: #048; border: 0;
}
}
@media (min-width: 920px) {
form.search { right: 12px; top: 0; }
}
#menu { padding-top: 5px; }
#content h1 { margin-top: 15px; border-top: 0; }
#content.error { font-size: 1.2em; }
#content.error p tt { font-size: 1.2em; }
#content.error .note { padding: 12px; }
.signature .permalink { float: right; font-size: 0.9em; }
/* autocomplete */
.ac_results {
padding: 0px;
border: 1px solid black;
width: 500px;
overflow: hidden;
z-index: 99999;
}
.ac_results ul {
width: 100%;
list-style-position: outside;
list-style: none;
padding: 0;
margin: 0;
}
.ac_results li {
cursor: pointer;
margin: 0px;
padding: 3px;
display: block;
font-family: sans-serif;
font-size: 12px;
line-height: 16px;
overflow: hidden;
}
.ac_loading {
background: white url('/images/processing.gif') right center no-repeat;
}
.ac_even {
background: #fafafa; border: 1px dotted #fafafa; border-left-width: 0; border-right-width: 0;
}
.ac_odd {
background: #f0f0f0; border: 1px dotted #f0f0f0; border-left-width: 0; border-right-width: 0;
}
.ac_over {
background: #ddd; cursor: pointer; border: 1px dotted #fff; border-left-width: 0; border-right-width: 0;
}
#fade { display: none; position: absolute; top: 0px; left: 0; background: #eee; z-index: -1; width: 100%; height: 100%; border-top: 1px solid #e0e0e0; }
#processing {
position: absolute; width: 400px; height: 200px; margin: auto; background: #fff; padding: 10px 30px; z-index: 20;
-webkit-box-shadow: 0px 0px 20px #444; -moz-box-shadow: 0px 0px 20px #444;
-webkit-border-radius: 4px;
display: none;
}
#processing img { display: block; position: absolute; bottom: 30px; left: 44%; }
yard-0.9.7/lib/yard/server/templates/doc_server/ 0000755 0000041 0000041 00000000000 13035234564 021667 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/library_list/ 0000755 0000041 0000041 00000000000 13035234564 024366 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/library_list/html/ 0000755 0000041 0000041 00000000000 13035234564 025332 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/library_list/html/headers.erb 0000644 0000041 0000041 00000001140 13035234564 027433 0 ustar www-data www-data
YARD Documentation Server <%= YARD::VERSION %> - Library Listing
yard-0.9.7/lib/yard/server/templates/doc_server/library_list/html/title.erb 0000644 0000041 0000041 00000000121 13035234564 027137 0 ustar www-data www-data YARD Documentation Server <%= YARD::VERSION %>
Library Listing
yard-0.9.7/lib/yard/server/templates/doc_server/library_list/html/setup.rb 0000644 0000041 0000041 00000000203 13035234564 027012 0 ustar www-data www-data # frozen_string_literal: true
include T('default/layout/html')
def init
sections :library_list, [:title, :listing, :footer]
end
yard-0.9.7/lib/yard/server/templates/doc_server/library_list/html/listing.erb 0000644 0000041 0000041 00000001174 13035234564 027500 0 ustar www-data www-data
<% @libraries.sort_by {|name, y| name.downcase }.each do |name, library_versions| %>
-
<% library_versions = library_versions.dup %>
<% first_lib = library_versions.pop %>
<%= name %>
<% if first_lib.version %>
(<%= first_lib.version %><% if library_versions.size > 0 %>,
<%= library_versions.reverse.map {|lib| "#{lib.version}" }.join(', ') %><% end %>)
<% end %>
<% end %>
yard-0.9.7/lib/yard/server/templates/doc_server/library_list/html/library_list.erb 0000644 0000041 0000041 00000000544 13035234564 030526 0 ustar www-data www-data
<%= erb(:headers) %>
<%= yieldall %>
yard-0.9.7/lib/yard/server/templates/doc_server/search/ 0000755 0000041 0000041 00000000000 13035234564 023134 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/search/html/ 0000755 0000041 0000041 00000000000 13035234564 024100 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/search/html/search.erb 0000644 0000041 0000041 00000001303 13035234564 026034 0 ustar www-data www-data
Search Results (for '<%= h @query %>')
Showing <%= @visible_results.size %> of <%= @results.size %> results
<% n = 1 %>
<% @visible_results.each do |result| %>
<% name = result.type == :method ? result.name(true).to_s : result.name.to_s %>
<% path = name.gsub(/(#{Regexp.quote @query})/i, '\1') %>
-
<%= path %>
<% if !result.namespace.root? %>
(<%= result.namespace.path %>)
<% end %>
<% n = n == 2 ? 1 : 2 %>
<% end %>
yard-0.9.7/lib/yard/server/templates/doc_server/search/html/setup.rb 0000644 0000041 0000041 00000000306 13035234564 025564 0 ustar www-data www-data # frozen_string_literal: true
def init
sections :search, [T('../default/layout')]
end
def search
options.breadcrumb_title = h("Search for '#{@query}'")
yieldall :contents => erb(:search)
end
yard-0.9.7/lib/yard/server/templates/doc_server/processing/ 0000755 0000041 0000041 00000000000 13035234564 024043 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/processing/html/ 0000755 0000041 0000041 00000000000 13035234564 025007 5 ustar www-data www-data yard-0.9.7/lib/yard/server/templates/doc_server/processing/html/processing.erb 0000644 0000041 0000041 00000004711 13035234564 027660 0 ustar www-data www-data
Processing <%= @library.to_s(false) %>
Processing <%= @library.name %>
<%= @library.name %> <% if @library.version %>(<%= @library.version %>)<% end %> is being processed.
You'll be redirected when the pages are built, it shouldn't take much longer.
 %>?<%= mtime('images/processing.gif') %>)
yard-0.9.7/lib/yard/server/templates/doc_server/processing/html/setup.rb 0000644 0000041 0000041 00000000102 13035234564 026465 0 ustar www-data www-data # frozen_string_literal: true
def init
sections :processing
end
yard-0.9.7/lib/yard/server/webrick_adapter.rb 0000644 0000041 0000041 00000002533 13035234564 021214 0 ustar www-data www-data # frozen_string_literal: true
require 'webrick'
module YARD
module Server
# The main adapter to initialize a WEBrick server.
class WebrickAdapter < Adapter
# Initializes a WEBrick server. If {Adapter#server_options} contains a
# +:daemonize+ key set to true, the server will be daemonized.
def start
server_options[:ServerType] = WEBrick::Daemon if server_options[:daemonize]
server = WEBrick::HTTPServer.new(server_options)
server.mount('/', WebrickServlet, self)
trap("INT") { server.shutdown }
server.start
end
end
# The main WEBrick servlet implementation, accepting only GET requests.
class WebrickServlet < WEBrick::HTTPServlet::AbstractServlet
attr_accessor :adapter
def initialize(server, adapter)
super
self.adapter = adapter
end
# @private
def do_GET(request, response) # rubocop:disable Style/MethodName
status, headers, body = *adapter.router.call(request)
response.status = status
response.body = body.is_a?(Array) ? body[0] : body
headers.each do |key, value|
response[key] = value
end
end
end
end
end
# @private
class WEBrick::HTTPRequest
attr_accessor :version_supplied
def xhr?; (self['X-Requested-With'] || "").casecmp('xmlhttprequest') == 0 end
end
yard-0.9.7/lib/yard/server/library_version.rb 0000644 0000041 0000041 00000026267 13035234564 021311 0 ustar www-data www-data # frozen_string_literal: true
require 'fileutils'
require 'thread'
module YARD
module Server
# This exception is raised when {LibraryVersion#prepare!} fails, or discovers
# that the library is not "prepared" to be served by
class LibraryNotPreparedError < RuntimeError; end
# A library version encapsulates a library's documentation at a specific version.
# Although the version is optional, this allows for creating multiple documentation
# points for a specific library, each representing a unique version. The term
# "library" used in other parts of the YARD::Server documentation refers to
# objects of this class unless otherwise noted.
#
# A library points to a location where a {#yardoc_file} is located so that
# its documentation may be loaded and served. Optionally, a {#source_path} is
# given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts})
# should be loaded from. Both of these methods may not be known immediately,
# since the yardoc file may not be built until later. Resolving the yardoc
# file and source path are dependent on the specific library "source type" used.
# Source types (known as "library source") are discussed in detail below.
#
# == Using with Adapters
# A list of libraries need to be passed into adapters upon creation. In
# most cases, you will never do this manually, but if you use a {RackMiddleware},
# you will need to pass in this list yourself. To build this list of libraries,
# you should create a hash of library names mapped to an *Array* of LibraryVersion
# objects. For example:
#
# {'mylib' => [LibraryVersion.new('mylib', '1.0', ...),
# LibraryVersion.new('mylib', '2.0', ...)]}
#
# Note that you can also use {Adapter#add_library} for convenience.
#
# The "array" part is required, even for just one library version.
#
# == Library Sources
# The {#source} method represents the library source type, ie. where the
# library "comes from". It might come from "disk", or it might come from a
# "gem" (technically the disk, but a separate type nonetheless). In these
# two cases, the yardoc file sits somewhere on your filesystem, though
# it may also be built dynamically if it does not yet exist. This behaviour
# is controlled through the {#prepare!} method, which prepares the yardoc file
# given a specific library source. We will see how this works in detail in
# the following section.
#
# == Implementing a Custom Library Source
# YARD can be extended to support custom library sources in order to
# build or retrieve a yardoc file at runtime from many different locations.
#
# To implement this behaviour, 3 methods can be added to the +LibraryVersion+
# class, +#load_yardoc_from_SOURCE+, +#yardoc_file_for_SOURCE+, and
# +#source_path_for_SOURCE+. In all cases, "SOURCE" represents the source
# type used in {#source} when creating the library object. The
# +#yardoc_file_for_SOURCE+ and +#source_path_for_SOURCE+ methods are called upon
# creation and should return the location where the source code for the library
# lives. The load method is called from {#prepare!} if there is no yardoc file
# and should set {#yardoc_file}. Below is a full example for
# implementing a custom library source, +:http+, which reads packaged .yardoc
# databases from zipped archives off of an HTTP server.
#
# Note that only +#load_yardoc_from_SOURCE+ is required. The other two
# methods are optional and can be set manually (via {#source_path=} and
# {#yardoc_file=}) on the object at any time.
#
# @example Implementing a Custom Library Source
# # Adds the source type "http" for .yardoc files zipped on HTTP servers
# class LibraryVersion
# def load_yardoc_from_http
# Thread.new do
# # zip/unzip method implementations are not shown
# download_zip_file("http://mysite.com/yardocs/#{self}.zip")
# unzip_file_to("/path/to/yardocs/#{self}")
# end
#
# # tell the server it's not ready yet (but it might be next time)
# raise LibraryNotPreparedError
# end
#
# def yardoc_file_for_http
# "/path/to/yardocs/#{self}/.yardoc"
# end
#
# def source_path_for_http
# File.dirname(yardoc_file)
# end
# end
#
# # Creating a library of this source type:
# LibraryVersion.new('name', '1.0', nil, :http)
#
class LibraryVersion
# @return [String] the name of the library
attr_accessor :name
# @return [String] the version of the specific library
attr_accessor :version
# @return [String] the location of the yardoc file used to load the object
# information from.
# @return [nil] if no yardoc file exists yet. In this case, {#prepare!} will
# be called on this library to build the yardoc file.
# @note To implement a custom yardoc file getter, implement
def yardoc_file
@yardoc_file ||= load_yardoc_file
end
attr_writer :yardoc_file
# @return [Symbol] the source type representing where the yardoc should be
# loaded from. Defaults are +:disk+ and +:gem+, though custom sources
# may be implemented. This value is used to inform {#prepare!} about how
# to load the necessary data in order to display documentation for an object.
# @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
attr_accessor :source
# @return [String] the location of the source code for a library. This
# value is filled by calling +#source_path_for_SOURCE+ on this class.
# @return [nil] if there is no source code
# @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
def source_path
@source_path ||= load_source_path
end
attr_writer :source_path
# @param [String] name the name of the library
# @param [String] version the specific (usually, but not always, numeric) library
# version
# @param [String] yardoc the location of the yardoc file, or nil if it is
# generated later
# @param [Symbol] source the location of the files used to build the yardoc.
# Builtin source types are +:disk+ or +:gem+.
def initialize(name, version = nil, yardoc = nil, source = :disk)
self.name = name
self.yardoc_file = yardoc
self.version = version
self.source = source
end
# @param [Boolean] url_format if true, returns the string in a URI-compatible
# format (for appending to a URL). Otherwise, it is given in a more human
# readable format.
# @return [String] the string representation of the library.
def to_s(url_format = true)
version ? "#{name}#{url_format ? '/' : '-'}#{version}" : name.to_s
end
# @return [Fixnum] used for Hash mapping.
def hash; to_s.hash end
# @return [Boolean] whether another LibraryVersion is equal to this one
def eql?(other)
other.is_a?(LibraryVersion) && other.name == name &&
other.version == version && other.yardoc_file == yardoc_file
end
alias == eql?
alias equal? eql?
# @return [Boolean] whether the library has been completely processed
# and is ready to be served
def ready?
return false if yardoc_file.nil?
serializer.complete?
end
# @note You should not directly override this method. Instead, implement
# +load_yardoc_from_SOURCENAME+ when implementing loading for a specific
# source type. See the {LibraryVersion} documentation for "Implementing
# a Custom Library Source"
#
# Prepares a library to be displayed by the server. This callback is
# performed before each request on a library to ensure that it is loaded
# and ready to be viewed. If any steps need to be performed prior to loading,
# they are performed through this method (though they should be implemented
# through the +load_yardoc_from_SOURCE+ method).
#
# @raise [LibraryNotPreparedError] if the library is not ready to be
# displayed. Usually when raising this error, you would simultaneously
# begin preparing the library for subsequent requests, although this
# is not necessary.
def prepare!
return if ready?
meth = "load_yardoc_from_#{source}"
send(meth) if respond_to?(meth, true)
end
# @return [Gem::Specification] a gemspec object for a given library. Used
# for :gem source types.
# @return [nil] if there is no installed gem for the library
def gemspec
ver = version ? "= #{version}" : ">= 0"
YARD::GemIndex.find_all_by_name(name, ver).last
end
protected
@@chdir_mutex = Mutex.new
# Called when a library of source type "disk" is to be prepared. In this
# case, the {#yardoc_file} should already be set, but the library may not
# be prepared. Run preparation if not done.
#
# @raise [LibraryNotPreparedError] if the yardoc file has not been
# prepared.
def load_yardoc_from_disk
return if ready?
@@chdir_mutex.synchronize do
Dir.chdir(source_path_for_disk) do
Thread.new do
CLI::Yardoc.run('--no-stats', '-n', '-b', yardoc_file)
end
end
end
raise LibraryNotPreparedError
end
# Called when a library of source type "gem" is to be prepared. In this
# case, the {#yardoc_file} needs to point to the correct location for
# the installed gem. The yardoc file is built if it has not been done.
#
# @raise [LibraryNotPreparedError] if the gem does not have an existing
# yardoc file.
def load_yardoc_from_gem
return if ready?
ver = version ? "= #{version}" : ">= 0"
@@chdir_mutex.synchronize do
Thread.new do
# Build gem docs on demand
log.debug "Building gem docs for #{to_s(false)}"
CLI::Gems.run(name, ver)
log.debug "Done building gem docs for #{to_s(false)}"
end
end
raise LibraryNotPreparedError
end
# @return [String] the source path for a disk source
def source_path_for_disk
File.dirname(yardoc_file) if yardoc_file
end
# @return [String] the source path for a gem source
def source_path_for_gem
gemspec.full_gem_path if gemspec
end
# @return [String] the yardoc file for a gem source
def yardoc_file_for_gem
require 'rubygems'
ver = version ? "= #{version}" : ">= 0"
Registry.yardoc_file_for_gem(name, ver)
end
private
def load_source_path
meth = "source_path_for_#{source}"
send(meth) if respond_to?(meth, true)
end
def load_yardoc_file
meth = "yardoc_file_for_#{source}"
send(meth) if respond_to?(meth, true)
end
def serializer
return if yardoc_file.nil?
Serializers::YardocSerializer.new(yardoc_file)
end
end
end
end
yard-0.9.7/lib/yard/server/rack_adapter.rb 0000644 0000041 0000041 00000006400 13035234564 020503 0 ustar www-data www-data # frozen_string_literal: true
require 'rack'
require 'webrick/httputils'
module YARD
module Server
# This class wraps the {RackAdapter} into a Rack-compatible middleware.
# See {#initialize} for a list of options to pass via Rack's +#use+ method.
#
# @note You must pass a +:libraries+ option to the RackMiddleware via +#use+. To
# read about how to return a list of libraries, see {LibraryVersion} or look
# at the example below.
# @example Using the RackMiddleware in a Rack application
# libraries = {:mylib => [YARD::Server::LibraryVersion.new('mylib', nil, '/path/to/.yardoc')]}
# use YARD::Server::RackMiddleware, :libraries => libraries
#
class RackMiddleware
# Creates a new Rack-based middleware for serving YARD documentation.
#
# @param app the next Rack middleware in the stack
# @option opts [Hash{String=>Array}] :libraries ({})
# the map of libraries to serve through the adapter. This option is *required*.
# @option opts [Hash] :options ({}) a list of options to pass to the adapter.
# See {Adapter#options} for a list.
# @option opts [Hash] :server_options ({}) a list of options to pass to the server.
# See {Adapter#server_options} for a list.
def initialize(app, opts = {})
args = [opts[:libraries] || {}, opts[:options] || {}, opts[:server_options] || {}]
@app = app
@adapter = RackAdapter.new(*args)
end
def call(env)
status, headers, body = *@adapter.call(env)
if status == 404
@app.call(env)
else
[status, headers, body]
end
end
end
# A server adapter to respond to requests using the Rack server infrastructure.
class RackAdapter < Adapter
include WEBrick::HTTPUtils
# Responds to Rack requests and builds a response with the {Router}.
# @return [Array(Numeric,Hash,Array)] the Rack-style response
def call(env)
request = Rack::Request.new(env)
request.path_info = unescape(request.path_info) # unescape things like %3F
router.call(request)
rescue StandardError => ex
log.backtrace(ex)
[500, {'Content-Type' => 'text/plain'},
[ex.message + "\n" + ex.backtrace.join("\n")]]
end
# Starts the +Rack::Server+. This method will pass control to the server and
# block.
# @return [void]
def start
server = Rack::Server.new(server_options)
server.instance_variable_set("@app", self)
print_start_message(server)
server.start
end
private
def print_start_message(server)
opts = server.default_options.merge(server.options)
log.puts ">> YARD #{YARD::VERSION} documentation server at http://#{opts[:Host]}:#{opts[:Port]}"
# Only happens for Mongrel
return unless server.server.to_s == "Rack::Handler::Mongrel"
log.puts ">> #{server.server.class_name} web server (running on Rack)"
log.puts ">> Listening on #{opts[:Host]}:#{opts[:Port]}, CTRL+C to stop"
end
end
end
end
# @private
class Rack::Request
attr_accessor :version_supplied
alias query params
def xhr?; (env['HTTP_X_REQUESTED_WITH'] || "").casecmp("xmlhttprequest") == 0 end
end
yard-0.9.7/lib/yard/server/adapter.rb 0000644 0000041 0000041 00000010334 13035234564 017504 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Server
# Short circuits a request by raising an error. This exception is caught
# by {Commands::Base#call} to immediately end a request and return a response.
class FinishRequest < RuntimeError; end
# Raises an error if a resource is not found. This exception is caught by
# {Commands::Base#call} to immediately end a request and return a 404 response
# code. If a message is provided, the body is set to the exception message.
class NotFoundError < RuntimeError; end
# This class implements the bridge between the {Router} and the server
# backend for a specific server type. YARD implements concrete adapters
# for WEBrick and Rack respectively, though other adapters can be made
# for other server architectures.
#
# == Subclassing Notes
# To create a concrete adapter class, implement the {#start} method to
# initiate the server backend.
#
# @abstract
class Adapter
# @return [String] the location where static files are located, if any.
# To set this field on initialization, pass +:DocumentRoot+ to the
# +server_opts+ argument in {#initialize}
attr_accessor :document_root
# @return [Hash{String=>Array}] a map of libraries.
# @see LibraryVersion LibraryVersion for information on building a list of libraries
# @see #add_library
attr_accessor :libraries
# @return [Hash] options passed and processed by adapters. The actual
# options mostly depend on the adapters themselves.
attr_accessor :options
# @return [Hash] a set of options to pass to the server backend. Note
# that +:DocumentRoot+ also sets the {#document_root}.
attr_accessor :server_options
# @return [Router] the router object used to route URLs to commands
attr_accessor :router
# Performs any global initialization for the adapter.
# @note If you subclass this method, make sure to call +super+.
# @return [void]
def self.setup
Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
end
# Performs any global shutdown procedures for the adapter.
# @note If you subclass this method, make sure to call +super+.
# @return [void]
def self.shutdown
Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
end
# Creates a new adapter object
#
# @param [Hash{String=>Array}] libs a list of libraries,
# see {#libraries} for formulating this list.
# @param [Hash] opts extra options to pass to the adapter
# @option opts [Class] :router (Router) the router class to initialize as the
# adapter's router.
# @option opts [Boolean] :caching (false) whether or not caching is enabled
# @option opts [Boolean] :single_library (false) whether to server documentation
# for a single or multiple libraries (changes URL structure)
def initialize(libs, opts = {}, server_opts = {})
self.class.setup
self.libraries = libs
self.options = opts
self.server_options = server_opts
self.document_root = server_options[:DocumentRoot]
self.router = (options[:router] || Router).new(self)
options[:adapter] = self
log.debug "Serving libraries using #{self.class}: #{libraries.keys.join(', ')}"
log.debug "Caching on" if options[:caching]
log.debug "Document root: #{document_root}" if document_root
end
# Adds a library to the {#libraries} mapping for a given library object.
# @example Adding a new library to an adapter
# adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')
# @param [LibraryVersion] library a library to add
def add_library(library)
libraries[library.name] ||= []
libraries[library.name] |= [library]
end
# Implement this method to connect your adapter to your server.
# @abstract
def start
raise NotImplementedError
end
end
end
end
yard-0.9.7/lib/yard/parser/ 0000755 0000041 0000041 00000000000 13035234564 015524 5 ustar www-data www-data yard-0.9.7/lib/yard/parser/c/ 0000755 0000041 0000041 00000000000 13035234564 015746 5 ustar www-data www-data yard-0.9.7/lib/yard/parser/c/c_parser.rb 0000644 0000041 0000041 00000014745 13035234564 020104 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
module C
class CParser < Base
def initialize(source, file = '(stdin)')
@file = file
@namespaces = {}
@content = source
@index = 0
@line = 1
@state = nil
@newline = true
@statements = []
@last_comment = nil
@last_statement = nil
end
def parse
parse_toplevel
enumerator
end
def enumerator
@statements
end
def tokenize
raise NotImplementedError, "no tokenization support for C/C++ files"
end
private
def parse_toplevel
advance_loop do
case char
when /['"]/; consume_quote(char)
when '#'; consume_directive
when '/'; consume_comment
when /\s/; consume_whitespace
else consume_toplevel_statement
end
end
end
def consume_quote(type = '"')
advance
advance_loop do
case char
when "\n"; advance; nextline
when '\\'; advance(2)
when type; advance; return
else advance
end
end
end
def consume_directive
return(advance) unless @newline
@last_comment = nil
@last_statement = nil
advance_loop do
if char == '\\' && nextchar =~ /[\r\n]/
advance_loop { advance; break(nextline) if char == "\n" }
elsif char == "\n"
return
end
advance
end
end
def consume_toplevel_statement
@newline = false
start = @index
line = @line
decl = consume_until(/[{;]/)
return nil if decl =~ /\A\s*\Z/
statement = ToplevelStatement.new(nil, @file, line)
@statements << statement
attach_comment(statement)
stmts = nil
if prevchar == '{'
stmts = consume_body_statements
if decl =~ /\A(typedef|enum|class|#{struct}|union)/
consume_until(';')
end
end
statement.source = @content[start..@index]
statement.block = stmts
statement.declaration = decl # rubocop:disable Lint/UselessSetterCall
end
def consume_body_statements
stmts = []
brace_level = 1
loop do
strip_non_statement_data
start = @index
line = @line
consume_until(/[{};]/)
brace_level += 1 if prevchar == '{'
brace_level -= 1 if prevchar == '}'
break if prevchar.empty? || (brace_level <= 0 && prevchar == '}')
src = @content[start...@index]
next unless src && src !~ /\A\s*\Z|\A\}\Z/
stmt = BodyStatement.new(src, @file, line)
attach_comment(stmt)
stmts << stmt
end
stmts
end
def strip_non_statement_data
start = @index
loop do
start = @index
case char
when /\s/; consume_whitespace
when '#'; consume_directive
when '/'; consume_comment
end
break if start == @index
end
end
def consume_whitespace
advance_loop { nextline if char == "\n"; break if char =~ /\S/; advance }
end
def consume_comment(add_comment = true)
return(advance) unless nextchar == '*' || nextchar == '/'
line = @line
type = nextchar == '*' ? :multi : :line
advance(2)
comment = String.new("")
advance_loop do
comment << char
if type == :multi
nextline if char == "\n"
if char(2) == '*/'
if add_comment
comment << '/'
stmt = Comment.new(comment, @file, line)
stmt.type = type
attach_comment(stmt)
@statements << stmt
end
return advance(2)
end
elsif char == "\n"
if add_comment
stmt = Comment.new(comment[0...-1], @file, line)
stmt.type = type
attach_comment(stmt)
@statements << stmt
end
return
end
advance
end
end
def consume_until(end_char, bracket_level = 0, brace_level = 0, add_comment = true)
end_char = /#{end_char}/ if end_char.is_a?(String)
start = @index
advance_loop do
chr = char
case chr
when /\s/; consume_whitespace
when /['"]/; consume_quote(char)
when '#'; consume_directive
when '/'; consume_comment(add_comment)
when '{'; advance; brace_level += 1
when '}'; advance; brace_level -= 1
when '('; advance; bracket_level += 1
when ')'; advance; bracket_level -= 1
else advance
end
@newline = false if chr !~ /\s/
if chr =~ end_char
break if chr == '{' || chr == '('
break if bracket_level <= 0 && brace_level <= 0
end
end
@content[start...@index]
end
def attach_comment(statement)
if Comment === statement
if @last_statement && @last_statement.line == statement.line
@last_statement.comments = statement
statement.statement = @last_statement
end
@last_comment = statement
@last_statement = nil
else
if @last_comment
statement.comments = @last_comment
@last_comment.statement = statement
end
@last_statement = statement
@last_comment = nil
end
end
def advance(num = 1) @index += num end
def back(num = 1) @index -= num end
def advance_loop
yield while @index <= @content.size
end
def nextline
@line += 1
@newline = true
end
def char(num = 1) @content[@index, num] end
def prevchar(num = 1) @content[@index - 1, num] end
def nextchar(num = 1) @content[@index + 1, num] end
def struct
/struct\s[a-zA-Z0-9]+\s\{/
end
end
end
end
end
yard-0.9.7/lib/yard/parser/c/statement.rb 0000644 0000041 0000041 00000002513 13035234564 020300 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
module C
class Statement
attr_accessor :source
attr_accessor :line
attr_accessor :file
# @deprecated Groups are now defined by directives
# @see Tags::GroupDirective
attr_accessor :group
attr_accessor :comments_hash_flag
def initialize(source, file = nil, line = nil)
@source = source
@file = file
@line = line
end
def line_range
line...(line + source.count("\n"))
end
def comments_range
comments.line_range
end
def first_line
source.split(/\n/).first
end
def show
"\t#{line}: #{first_line}"
end
end
class BodyStatement < Statement
attr_accessor :comments
end
class ToplevelStatement < Statement
attr_accessor :block
attr_accessor :declaration
attr_accessor :comments
end
class Comment < Statement
include CommentParser
attr_accessor :type
attr_accessor :overrides
attr_accessor :statement
def initialize(source, file = nil, line = nil)
super(parse_comments(source), file, line)
end
def comments; self end
end
end
end
end
yard-0.9.7/lib/yard/parser/c/comment_parser.rb 0000644 0000041 0000041 00000011147 13035234564 021315 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
module C
module CommentParser
protected
def parse_comments(comments)
@overrides = []
spaces = nil
comments = remove_private_comments(comments)
comments = comments.split(/\r?\n/).map do |line|
line.gsub!(%r{^\s*/?\*/?}, '')
line.gsub!(%r{\*/\s*$}, '')
if line =~ /^\s*$/
next if spaces.nil?
next ""
end
spaces = (line[/^(\s+)/, 1] || "").size if spaces.nil?
line.gsub(/^\s{0,#{spaces}}/, '').rstrip
end.compact
comments = parse_overrides(comments)
comments = parse_callseq(comments)
comments.join("\n")
end
private
def parse_overrides(comments)
comments.map do |line|
type, name = *line.scan(/^\s*Document-(class|module|method|attr|const):\s*(\S.*)\s*$/).first
if type
@overrides << [type.to_sym, name]
nil
else
line
end
end.compact
end
def parse_callseq(comments)
return comments unless comments[0] =~ /\Acall-seq:\s*(\S.+)?/
if $1
comments[0] = " #{$1}"
else
comments.shift
end
overloads = []
seen_data = false
while comments.first =~ /^\s+(\S.+)/ || comments.first =~ /^\s*$/
line = comments.shift.strip
break if line.empty? && seen_data
next if line.empty?
seen_data = true
line.sub!(/^\w+[\.#]/, '')
signature, types = *line.split(/ [-=]> /)
types = parse_types(types)
if signature.sub!(/\[?\s*(\{(?:\s*\|(.+?)\|)?.*\})\s*\]?\s*$/, '') && $1
blk = $1
blkparams = $2
else
blk = nil
blkparams = nil
end
case signature
when /^(\w+)\s*=\s+(\w+)/
signature = "#{$1}=(#{$2})"
when /^\w+\s+\S/
signature = signature.split(/\s+/)
signature = "#{signature[1]}#{signature[2] ? '(' + signature[2..-1].join(' ') + ')' : ''}"
when /^\w+\[(.+?)\]\s*(=)?/
signature = "[]#{$2}(#{$1})"
when /^\w+\s+(#{CodeObjects::METHODMATCH})\s+(\w+)/
signature = "#{$1}(#{$2})"
end
break unless signature =~ /^#{CodeObjects::METHODNAMEMATCH}/
signature = signature.rstrip
overloads << "@overload #{signature}"
overloads << " @yield [#{blkparams}]" if blk
overloads << " @return [#{types.join(', ')}]" unless types.empty?
end
comments + [""] + overloads
end
def parse_types(types)
if types =~ /true or false/
["Boolean"]
else
(types || "").split(/,| or /).map do |t|
case t.strip.gsub(/^an?_/, '')
when "class"; "Class"
when "obj", "object", "anObject"; "Object"
when "arr", "array", "anArray", /^\[/; "Array"
when /^char\s*\*/, "char", "str", "string", "new_str"; "String"
when "enum", "anEnumerator"; "Enumerator"
when "exc", "exception"; "Exception"
when "proc", "proc_obj", "prc"; "Proc"
when "binding"; "Binding"
when "hsh", "hash", "aHash"; "Hash"
when "ios", "io"; "IO"
when "file"; "File"
when "float"; "Float"
when "time", "new_time"; "Time"
when "dir", "aDir"; "Dir"
when "regexp", "new_regexp"; "Regexp"
when "matchdata"; "MatchData"
when "encoding"; "Encoding"
when "fixnum", "fix"; "Fixnum"
when /^(?:un)?signed$/, /^(?:(?:un)?signed\s*)?(?:short|int|long|long\s+long)$/, "integer", "Integer"; "Integer"
when "num", "numeric", "Numeric", "number"; "Numeric"
when "aBignum"; "Bignum"
when "nil"; "nil"
when "true"; "true"
when "false"; "false"
when "bool", "boolean", "Boolean"; "Boolean"
when "self"; "self"
when /^[-+]?\d/; t
when /[A-Z][_a-z0-9]+/; t
end
end.compact
end
end
def remove_private_comments(comment)
comment = comment.gsub(%r{/?\*--\n(.*?)/?\*\+\+}m, '')
comment = comment.sub(%r{/?\*--\n.*}m, '')
comment
end
end
end
end
end
yard-0.9.7/lib/yard/parser/source_parser.rb 0000644 0000041 0000041 00000046637 13035234564 020745 0 ustar www-data www-data # frozen_string_literal: true
require 'stringio'
require 'ostruct'
module YARD
module Parser
# Raised when an object is recognized but cannot be documented. This
# generally occurs when the Ruby syntax used to declare an object is
# too dynamic in nature.
class UndocumentableError < RuntimeError; end
# Raised when the parser sees a Ruby syntax error
class ParserSyntaxError < UndocumentableError; end
# Responsible for parsing a list of files in order. The
# {#parse} method of this class can be called from the
# {SourceParser#globals} globals state list to re-enter
# parsing for the remainder of files in the list recursively.
#
# @see Processor#parse_remaining_files
class OrderedParser
# @return [Array] the list of remaining files to parse
attr_accessor :files
# Creates a new OrderedParser with the global state and a list
# of files to parse.
#
# @note OrderedParser sets itself as the +ordered_parser+ key on
# global_state for later use in {Handlers::Processor}.
# @param [OpenStruct] global_state a structure containing all global
# state during parsing
# @param [Array] files the list of files to parse
def initialize(global_state, files)
@global_state = global_state
@files = files.dup
@global_state.ordered_parser = self
end
# Parses the remainder of the {#files} list.
#
# @see Processor#parse_remaining_files
def parse
until files.empty?
file = files.shift
log.capture("Parsing #{file}") do
SourceParser.new(SourceParser.parser_type, @global_state).parse(file)
end
end
end
end
# Responsible for parsing a source file into the namespace. Parsing
# also invokes handlers to process the parsed statements and generate
# any code objects that may be recognized.
#
# == Custom Parsers
# SourceParser allows custom parsers to be registered and called when
# a certain filetype is recognized. To register a parser and hook it
# up to a set of file extensions, call {register_parser_type}
#
# @see register_parser_type
# @see Handlers::Base
# @see CodeObjects::Base
class SourceParser
SHEBANG_LINE = /\A\s*#!\S+/
ENCODING_LINE = %r{\A(?:\s*#*!.*\r?\n)?\s*(?:#+|/\*+|//+).*coding\s*[:=]{1,2}\s*([a-z\d_\-]+)}i
FROZEN_STRING_LINE = /frozen(-|_)string(-|_)literal: true/i
# The default glob of files to be parsed.
# @since 0.9.0
DEFAULT_PATH_GLOB = ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp}"]
# Byte order marks for various encodings
# @since 0.7.0
ENCODING_BYTE_ORDER_MARKS = {
'utf-8' => String.new("\xEF\xBB\xBF"),
# Not yet supported
# 'utf-16be' => "\xFE\xFF",
# 'utf-16le' => "\xFF\xFE",
# 'utf-32be' => "\x00\x00\xFF\xFE",
# 'utf-32le' => "\xFF\xFE",
}
class << self
# @return [Symbol] the default parser type (defaults to :ruby)
attr_reader :parser_type
def parser_type=(value)
@parser_type = validated_parser_type(value)
end
# Parses a path or set of paths
#
# @param [String, Array] paths a path, glob, or list of paths to
# parse
# @param [Array] excluded a list of excluded path matchers
# @param [Fixnum] level the logger level to use during parsing. See
# {YARD::Logger}
# @return [void]
def parse(paths = DEFAULT_PATH_GLOB, excluded = [], level = log.level)
log.debug("Parsing #{paths.inspect} with `#{parser_type}` parser")
excluded = excluded.map do |path|
case path
when Regexp; path
else Regexp.new(path.to_s, Regexp::IGNORECASE)
end
end
files = [paths].flatten.
map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
map {|p| p.include?("*") ? Dir[p].sort_by {|d| [d.length, d] } : p }.flatten.
reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }
log.enter_level(level) do
parse_in_order(*files.uniq)
end
end
# Parses a string +content+
#
# @param [String] content the block of code to parse
# @param [Symbol] ptype the parser type to use. See {parser_type}.
# @return the parser object that was used to parse +content+
def parse_string(content, ptype = parser_type)
new(ptype).parse(StringIO.new(content))
end
# Tokenizes but does not parse the block of code
#
# @param [String] content the block of code to tokenize
# @param [Symbol] ptype the parser type to use. See {parser_type}.
# @return [Array] a list of tokens
def tokenize(content, ptype = parser_type)
new(ptype).tokenize(content)
end
# Registers a new parser type.
#
# @example Registering a parser for "java" files
# SourceParser.register_parser_type :java, JavaParser, 'java'
# @param [Symbol] type a symbolic name for the parser type
# @param [Base] parser_klass a class that implements parsing and tokenization
# @param [Array, String, Regexp] extensions a list of extensions or a
# regex to match against the file extension
# @return [void]
# @see Parser::Base
def register_parser_type(type, parser_klass, extensions = nil)
unless Base > parser_klass
raise ArgumentError, "expecting parser_klass to be a subclass of YARD::Parser::Base"
end
parser_type_extensions[type.to_sym] = extensions if extensions
parser_types[type.to_sym] = parser_klass
end
# @return [Hash{Symbol=>Object}] a list of registered parser types
# @private
# @since 0.5.6
def parser_types; @@parser_types ||= {} end
def parser_types=(value) @@parser_types = value end
# @return [Hash] a list of registered parser type extensions
# @private
# @since 0.5.6
def parser_type_extensions; @@parser_type_extensions ||= {} end
def parser_type_extensions=(value) @@parser_type_extensions = value end
# Finds a parser type that is registered for the extension. If no
# type is found, the default Ruby type is returned.
#
# @return [Symbol] the parser type to be used for the extension
# @since 0.5.6
def parser_type_for_extension(extension)
type = parser_type_extensions.find do |_t, exts|
[exts].flatten.any? {|ext| ext === extension }
end
validated_parser_type(type ? type.first : :ruby)
end
# Returns the validated parser type. Basically, enforces that :ruby
# type is never set if the Ripper library is not available
#
# @param [Symbol] type the parser type to set
# @return [Symbol] the validated parser type
# @private
def validated_parser_type(type)
!defined?(::Ripper) && type == :ruby ? :ruby18 : type
end
# @group Parser Callbacks
# Registers a callback to be called before a list of files is parsed
# via {parse}. The block passed to this method will be called on
# subsequent parse calls.
#
# @example Installing a simple callback
# SourceParser.before_parse_list do |files, globals|
# puts "Starting to parse..."
# end
# YARD.parse('lib/**/*.rb')
# # prints "Starting to parse..."
#
# @example Setting global state
# SourceParser.before_parse_list do |files, globals|
# globals.method_count = 0
# end
# SourceParser.after_parse_list do |files, globals|
# puts "Found #{globals.method_count} methods"
# end
# class MyCountHandler < Handlers::Ruby::Base
# handles :def, :defs
# process { globals.method_count += 1 }
# end
# YARD.parse
# # Prints: "Found 37 methods"
#
# @example Using a global callback to cancel parsing
# SourceParser.before_parse_list do |files, globals|
# return false if files.include?('foo.rb')
# end
#
# YARD.parse(['foo.rb', 'bar.rb']) # callback cancels this method
# YARD.parse('bar.rb') # parses normally
#
# @yield [files, globals] the yielded block is called once before
# parsing all files
# @yieldparam [Array] files the list of files that will be parsed.
# @yieldparam [OpenStruct] globals a global structure to store arbitrary
# state for post processing (see {Handlers::Processor#globals})
# @yieldreturn [Boolean] if the block returns +false+, parsing is
# cancelled.
# @return [Proc] the yielded block
# @see after_parse_list
# @see before_parse_file
# @since 0.7.0
def before_parse_list(&block)
before_parse_list_callbacks << block
end
# Registers a callback to be called after a list of files is parsed
# via {parse}. The block passed to this method will be called on
# subsequent parse calls.
#
# @example Printing results after parsing occurs
# SourceParser.after_parse_list do
# puts "Finished parsing!"
# end
# YARD.parse
# # Prints "Finished parsing!" after parsing files
# @yield [files, globals] the yielded block is called once before
# parsing all files
# @yieldparam [Array] files the list of files that will be parsed.
# @yieldparam [OpenStruct] globals a global structure to store arbitrary
# state for post processing (see {Handlers::Processor#globals})
# @yieldreturn [void] the return value for the block is ignored.
# @return [Proc] the yielded block
# @see before_parse_list
# @see before_parse_file
# @since 0.7.0
def after_parse_list(&block)
after_parse_list_callbacks << block
end
# Registers a callback to be called before an individual file is parsed.
# The block passed to this method will be called on subsequent parse
# calls.
#
# To register a callback that is called before the entire list of files
# is processed, see {before_parse_list}.
#
# @example Installing a simple callback
# SourceParser.before_parse_file do |parser|
# puts "I'm parsing #{parser.file}"
# end
# YARD.parse('lib/**/*.rb')
# # prints:
# "I'm parsing lib/foo.rb"
# "I'm parsing lib/foo_bar.rb"
# "I'm parsing lib/last_file.rb"
#
# @example Cancel parsing of any test_*.rb files
# SourceParser.before_parse_file do |parser|
# return false if parser.file =~ /^test_.+\.rb$/
# end
#
# @yield [parser] the yielded block is called once before each
# file that is parsed. This might happen many times for a single
# codebase.
# @yieldparam [SourceParser] parser the parser object that will {#parse}
# the file.
# @yieldreturn [Boolean] if the block returns +false+, parsing for
# the file is cancelled.
# @return [Proc] the yielded block
# @see after_parse_file
# @see before_parse_list
# @since 0.7.0
def before_parse_file(&block)
before_parse_file_callbacks << block
end
# Registers a callback to be called after an individual file is parsed.
# The block passed to this method will be called on subsequent parse
# calls.
#
# To register a callback that is called after the entire list of files
# is processed, see {after_parse_list}.
#
# @example Printing the length of each file after it is parsed
# SourceParser.after_parse_file do |parser|
# puts "#{parser.file} is #{parser.contents.size} characters"
# end
# YARD.parse('lib/**/*.rb')
# # prints:
# "lib/foo.rb is 1240 characters"
# "lib/foo_bar.rb is 248 characters"
#
# @yield [parser] the yielded block is called once after each file
# that is parsed. This might happen many times for a single codebase.
# @yieldparam [SourceParser] parser the parser object that parsed
# the file.
# @yieldreturn [void] the return value for the block is ignored.
# @return [Proc] the yielded block
# @see before_parse_file
# @see after_parse_list
# @since 0.7.0
def after_parse_file(&block)
after_parse_file_callbacks << block
end
# @return [Array] the list of callbacks to be called before
# parsing a list of files. Should only be used for testing.
# @since 0.7.0
def before_parse_list_callbacks
@before_parse_list_callbacks ||= []
end
# @return [Array] the list of callbacks to be called after
# parsing a list of files. Should only be used for testing.
# @since 0.7.0
def after_parse_list_callbacks
@after_parse_list_callbacks ||= []
end
# @return [Array] the list of callbacks to be called before
# parsing a file. Should only be used for testing.
# @since 0.7.0
def before_parse_file_callbacks
@before_parse_file_callbacks ||= []
end
# @return [Array] the list of callbacks to be called after
# parsing a file. Should only be used for testing.
# @since 0.7.0
def after_parse_file_callbacks
@after_parse_file_callbacks ||= []
end
# @endgroup
private
# Parses a list of files in a queue.
#
# @param [Array] files a list of files to queue for parsing
# @return [void]
def parse_in_order(*files)
global_state = OpenStruct.new
return if before_parse_list_callbacks.any? do |cb|
cb.call(files, global_state) == false
end
OrderedParser.new(global_state, files).parse
after_parse_list_callbacks.each do |cb|
cb.call(files, global_state)
end
end
end
register_parser_type :ruby, Ruby::RubyParser
register_parser_type :ruby18, Ruby::Legacy::RubyParser
register_parser_type :c, C::CParser, ['c', 'cc', 'cxx', 'cpp']
self.parser_type = :ruby
# @return [String] the filename being parsed by the parser.
attr_accessor :file
# @return [Symbol] the parser type associated with the parser instance.
# This should be set by the {#initialize constructor}.
attr_reader :parser_type
# @return [OpenStruct] an open struct containing arbitrary global state
# shared between files and handlers.
# @since 0.7.0
attr_reader :globals
# @return [String] the contents of the file to be parsed
# @since 0.7.0
attr_reader :contents
# @overload initialize(parser_type = SourceParser.parser_type, globals = nil)
# Creates a new parser object for code parsing with a specific parser type.
#
# @param [Symbol] parser_type the parser type to use
# @param [OpenStruct] globals global state to be re-used across separate source files
def initialize(parser_type = SourceParser.parser_type, globals1 = nil, globals2 = nil)
globals = [true, false].include?(globals1) ? globals2 : globals1
@file = '(stdin)'
@globals = globals || OpenStruct.new
self.parser_type = parser_type
end
# The main parser method. This should not be called directly. Instead,
# use the class methods {parse} and {parse_string}.
#
# @param [String, #read, Object] content the source file to parse
# @return [Object, nil] the parser object used to parse the source
def parse(content = __FILE__)
case content
when String
@file = File.cleanpath(content)
content = convert_encoding(String.new(File.read_binary(file)))
checksum = Registry.checksum_for(content)
return if Registry.checksums[file] == checksum
if Registry.checksums.key?(file)
log.info "File '#{file}' was modified, re-processing..."
end
Registry.checksums[@file] = checksum
self.parser_type = parser_type_for_filename(file)
else
content = content.read if content.respond_to? :read
end
@contents = content
@parser = parser_class.new(content, file)
self.class.before_parse_file_callbacks.each do |cb|
return @parser if cb.call(self) == false
end
@parser.parse
post_process
self.class.after_parse_file_callbacks.each do |cb|
cb.call(self)
end
@parser
rescue ArgumentError, NotImplementedError => e
log.warn("Cannot parse `#{file}': #{e.message}")
log.backtrace(e, :warn)
rescue ParserSyntaxError => e
log.warn(e.message.capitalize)
log.backtrace(e, :warn)
end
# Tokenizes but does not parse the block of code using the current {#parser_type}
#
# @param [String] content the block of code to tokenize
# @return [Array] a list of tokens
def tokenize(content)
@parser = parser_class.new(content, file)
@parser.tokenize
end
private
# Searches for encoding line and forces encoding
# @since 0.5.3
def convert_encoding(content)
return content unless content.respond_to?(:force_encoding)
if content =~ ENCODING_LINE
content.force_encoding($1)
else
content.force_encoding('binary')
ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
bom.force_encoding('binary')
if content[0, bom.size] == bom
content.force_encoding(encoding)
return content
end
end
content.force_encoding('utf-8') # UTF-8 is default encoding
content
end
end
# Runs a {Handlers::Processor} object to post process the parsed statements.
# @return [void]
def post_process
return unless @parser.respond_to?(:enumerator)
enumerator = @parser.enumerator
if enumerator
post = Handlers::Processor.new(self)
post.process(enumerator)
end
end
def parser_type=(value)
@parser_type = self.class.validated_parser_type(value)
end
# Guesses the parser type to use depending on the file extension.
#
# @param [String] filename the filename to use to guess the parser type
# @return [Symbol] a parser type that matches the filename
def parser_type_for_filename(filename)
ext = (File.extname(filename)[1..-1] || "").downcase
type = self.class.parser_type_for_extension(ext)
parser_type == :ruby18 && type == :ruby ? :ruby18 : type
end
# @since 0.5.6
def parser_class
klass = self.class.parser_types[parser_type]
unless klass
raise ArgumentError, "invalid parser type '#{parser_type}' or unrecognized file", caller[1..-1]
end
klass
end
end
end
end
yard-0.9.7/lib/yard/parser/base.rb 0000644 0000041 0000041 00000003703 13035234564 016766 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
# Represents the abstract base parser class that parses source code in
# a specific way. A parser should implement {#parse}, {#tokenize} and
# {#enumerator}.
#
# == Registering a Custom Parser
# To register a parser, see {SourceParser.register_parser_type}
#
# @abstract
# @see #parse
# @see #tokenize
# @see #enumerator
# @since 0.5.6
class Base
# Convenience method to create a new parser and {#parse}
def self.parse(source, filename = nil)
new(source, filename).parse
end
# This default constructor does nothing. The subclass is responsible for
# storing the source contents and filename if they are required.
# @param [String] source the source contents
# @param [String] filename the name of the file if from disk
def initialize(source, filename) # rubocop:disable Lint/UnusedMethodArgument
raise NotImplementedError, "invalid parser implementation"
end
# This method should be implemented to parse the source and return itself.
# @abstract
# @return [Base] this method should return itself
def parse
raise NotImplementedError, "#{self.class} must implement #parse"
end
# This method should be implemented to tokenize given source
# @abstract
# @return [Array] a list/tree of lexical tokens
def tokenize
raise NotImplementedError, "#{self.class} does not support tokenization"
end
# This method should be implemented to return a list of semantic tokens
# representing the source code to be post-processed. Otherwise the method
# should return nil.
#
# @abstract
# @return [Array] a list of semantic tokens representing the source code
# to be post-processed
# @return [nil] if no post-processing should be done
def enumerator
nil
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/ 0000755 0000041 0000041 00000000000 13035234564 016505 5 ustar www-data www-data yard-0.9.7/lib/yard/parser/ruby/ruby_parser.rb 0000644 0000041 0000041 00000055201 13035234564 021372 0 ustar www-data www-data # frozen_string_literal: true
begin require 'ripper'; rescue LoadError; nil end
module YARD
module Parser
module Ruby
# Ruby 1.9 parser
# @!attribute [r] encoding_line
# @!attribute [r] frozen_string_line
# @!attribute [r] shebang_line
# @!attribute [r] enumerator
class RubyParser < Parser::Base
def initialize(source, filename)
@parser = RipperParser.new(source, filename)
end
def parse; @parser.parse end
def tokenize; @parser.tokens end
def enumerator; @parser.enumerator end
def shebang_line; @parser.shebang_line end
def encoding_line; @parser.encoding_line end
def frozen_string_line; @parser.frozen_string_line end
end
# Internal parser class
# @since 0.5.6
class RipperParser < Ripper
attr_reader :ast, :charno, :comments, :file, :tokens
attr_reader :shebang_line, :encoding_line, :frozen_string_line
alias root ast
def initialize(source, filename, *args)
super
@last_ns_token = nil
@file = filename
@source = source
@tokens = []
@comments = {}
@comments_range = {}
@comments_flags = {}
@heredoc_tokens = nil
@heredoc_state = nil
@map = {}
@ns_charno = 0
@list = []
@charno = 0
@shebang_line = nil
@encoding_line = nil
@frozen_string_line = nil
@file_encoding = nil
@newline = true
@percent_ary = nil
end
def parse
@ast = super
@ast.full_source = @source
@ast.file = @file
freeze_tree
insert_comments
self
end
def enumerator
ast.children
end
def file_encoding
return nil unless defined?(::Encoding)
return @file_encoding if @file_encoding
return Encoding.default_internal unless @encoding_line
match = @encoding_line.match(SourceParser::ENCODING_LINE)
@file_encoding = match.captures.last if match
end
private
MAPPINGS = {
:BEGIN => "BEGIN",
:END => "END",
:alias => "alias",
:array => :lbracket,
:arg_paren => :lparen,
:begin => "begin",
:blockarg => "&",
:brace_block => :lbrace,
:break => "break",
:case => "case",
:class => "class",
:def => "def",
:defined => "defined?",
:defs => "def",
:do_block => "do",
:else => "else",
:elsif => "elsif",
:ensure => "ensure",
:for => "for",
:hash => :lbrace,
:if => "if",
:lambda => [:tlambda, "lambda"],
:module => "module",
:next => "next",
:paren => :lparen,
:qwords_literal => :qwords_beg,
:words_literal => :words_beg,
:qsymbols_literal => :qsymbols_beg,
:symbols_literal => :symbols_beg,
:redo => "redo",
:regexp_literal => :regexp_beg,
:rescue => "rescue",
:rest_param => "*",
:retry => "retry",
:return => "return",
:return0 => "return",
:sclass => "class",
:string_embexpr => :embexpr_beg,
:string_literal => [:tstring_beg, :heredoc_beg],
:super => "super",
:symbol => :symbeg,
:top_const_ref => "::",
:undef => "undef",
:unless => "unless",
:until => "until",
:when => "when",
:while => "while",
:xstring_literal => :backtick,
:yield => "yield",
:yield0 => "yield",
:zsuper => "super"
}
REV_MAPPINGS = {}
AST_TOKENS = [:CHAR, :backref, :const, :cvar, :gvar, :heredoc_end, :ident,
:int, :float, :ivar, :label, :period, :regexp_end, :tstring_content, :backtick]
MAPPINGS.each do |k, v|
if Array === v
v.each {|vv| (REV_MAPPINGS[vv] ||= []) << k }
else
(REV_MAPPINGS[v] ||= []) << k
end
end
PARSER_EVENT_TABLE.each do |event, arity|
node_class = AstNode.node_class_for(event)
if /_new\z/ =~ event.to_s && arity == 0
module_eval(<<-eof, __FILE__, __LINE__ + 1)
def on_#{event}(*args)
#{node_class}.new(:list, args, :listchar => charno...charno, :listline => lineno..lineno)
end
eof
elsif /_add(_.+)?\z/ =~ event.to_s
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(list, item)
list.push(item)
list
end
eof
elsif MAPPINGS.key?(event)
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(*args)
visit_event #{node_class}.new(:#{event}, args)
end
eof
else
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(*args)
#{node_class}.new(:#{event}, args, :listline => lineno..lineno, :listchar => charno...charno)
end
eof
end
end
SCANNER_EVENTS.each do |event|
ast_token = AST_TOKENS.include?(event)
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(tok)
visit_ns_token(:#{event}, tok, #{ast_token.inspect})
end
eof
end
REV_MAPPINGS.select {|k, _v| k.is_a?(Symbol) }.each do |pair|
event = pair.first
ast_token = AST_TOKENS.include?(event)
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(tok)
(@map[:#{event}] ||= []) << [lineno, charno]
visit_ns_token(:#{event}, tok, #{ast_token.inspect})
end
eof
end
[:kw, :op].each do |event|
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(tok)
unless @last_ns_token == [:kw, "def"] ||
(@tokens.last && @tokens.last[0] == :symbeg) ||
(!@newline && %w(if while until unless).include?(tok))
(@map[tok] ||= []) << [lineno, charno]
end
visit_ns_token(:#{event}, tok, true)
end
eof
end
[:nl, :ignored_nl].each do |event|
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{event}; rescue NameError; end
def on_#{event}(tok)
add_token(:#{event}, tok)
@newline = true
@charno += tok ? tok.length : 1
end
eof
end
undef on_sp
def on_sp(tok)
add_token(:sp, tok)
@charno += tok.length
end
def visit_event(node)
map = @map[MAPPINGS[node.type]]
lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
node.source_range = Range.new(sstart, @ns_charno - 1)
node.line_range = Range.new(lstart, lineno)
if node.respond_to?(:block)
sr = node.block.source_range
lr = node.block.line_range
node.block.source_range = Range.new(sr.first, @tokens.last[2][1] - 1)
node.block.line_range = Range.new(lr.first, @tokens.last[2][0])
end
node
end
def visit_event_arr(node)
mapping = MAPPINGS[node.type].find {|k| @map[k] && !@map[k].empty? }
lstart, sstart = *@map[mapping].pop
node.source_range = Range.new(sstart, @ns_charno - 1)
node.line_range = Range.new(lstart, lineno)
node
end
def visit_ns_token(token, data, ast_token = false)
add_token(token, data)
ch = charno
@last_ns_token = [token, data]
@charno += data.length
@ns_charno = charno
@newline = [:semicolon, :comment, :kw, :op, :lparen, :lbrace].include?(token)
if ast_token
AstNode.new(token, [data], :line => lineno..lineno, :char => ch..charno - 1, :token => true)
end
end
def add_token(token, data)
if @percent_ary
if token == :words_sep && data !~ /\s\z/
rng = @percent_ary.source_range
rng = Range.new(rng.first, rng.last + data.length)
@percent_ary.source_range = rng
@tokens << [token, data, [lineno, charno]]
@percent_ary = nil
elsif token == :tstring_end && data =~ /\A\s/
rng = @percent_ary.source_range
rng = Range.new(rng.first, rng.last + data.length)
@percent_ary.source_range = rng
@tokens << [token, data, [lineno, charno]]
@percent_ary = nil
end
elsif @tokens.last && @tokens.last[0] == :symbeg
@tokens[-1] = [:symbol, ":" + data, @tokens.last[2]]
elsif @heredoc_state == :started
@heredoc_tokens << [token, data, [lineno, charno]]
# fix ripper encoding of heredoc bug
# (see http://bugs.ruby-lang.org/issues/6200)
data.force_encoding(file_encoding) if file_encoding
@heredoc_state = :ended if token == :heredoc_end
elsif (token == :nl || token == :comment) && @heredoc_state == :ended
@heredoc_tokens.unshift([token, data, [lineno, charno]])
@tokens += @heredoc_tokens
@heredoc_tokens = nil
@heredoc_state = nil
else
@tokens << [token, data, [lineno, charno]]
if token == :heredoc_beg
@heredoc_state = :started
@heredoc_tokens = []
end
end
end
undef on_program
undef on_assoc_new
undef on_array
undef on_hash
undef on_bare_assoc_hash
undef on_assoclist_from_args
undef on_aref
undef on_aref_field
undef on_lbracket
undef on_rbracket
undef on_string_literal
undef on_lambda
undef on_unary
undef on_string_content
undef on_rescue
undef on_void_stmt
undef on_params
undef on_label
undef on_comment
undef on_embdoc_beg
undef on_embdoc
undef on_embdoc_end
undef on_parse_error
undef on_bodystmt
undef on_top_const_ref
undef on_const_path_ref
def on_program(*args)
args.first
end
def on_body_stmt(*args)
args.compact.size == 1 ? args.first : AstNode.new(:list, args)
end
alias on_bodystmt on_body_stmt
def on_assoc_new(*args)
AstNode.new(:assoc, args)
end
def on_hash(*args)
visit_event AstNode.new(:hash, args.first || [])
end
def on_bare_assoc_hash(*args)
AstNode.new(:list, args.first)
end
def on_assoclist_from_args(*args)
args.first
end
def on_unary(op, val)
map = @map[op.to_s[0, 1]]
lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
node = AstNode.node_class_for(:unary).new(:unary, [op, val])
node.source_range = Range.new(sstart, @ns_charno - 1)
node.line_range = Range.new(lstart, lineno)
node
end
def on_aref(*args)
@map[:lbracket].pop
ll, lc = *@map[:aref].pop
sr = args.first.source_range.first..lc
lr = args.first.line_range.first..ll
AstNode.new(:aref, args, :char => sr, :line => lr)
end
def on_aref_field(*args)
@map[:lbracket].pop
AstNode.new(:aref_field, args,
:listline => lineno..lineno, :listchar => charno...charno)
end
def on_array(other)
node = AstNode.node_class_for(:array).new(:array, [other])
map = @map[MAPPINGS[node.type]]
if map && !map.empty?
lstart, sstart = *map.pop
node.source_range = Range.new(sstart, @ns_charno - 1)
node.line_range = Range.new(lstart, lineno)
else
sstart = other.source_range.begin
lstart = other.line_range.begin
node.source_range = Range.new(sstart, @ns_charno - 1)
node.line_range = Range.new(lstart, lineno)
node.source_range = other.source_range
node.line_range = other.line_range
end
node
end
def on_lbracket(tok)
(@map[:lbracket] ||= []) << [lineno, charno]
visit_ns_token(:lbracket, tok, false)
end
def on_rbracket(tok)
(@map[:aref] ||= []) << [lineno, charno]
visit_ns_token(:rbracket, tok, false)
end
def on_top_const_ref(*args)
type = :top_const_ref
node = AstNode.node_class_for(type).new(type, args)
mapping = @map[MAPPINGS[type]]
extra_op = mapping.last[1] + 2 == charno ? mapping.pop : nil
lstart, sstart = *mapping.pop
node.source_range = Range.new(sstart, args.last.source_range.last)
node.line_range = Range.new(lstart, args.last.line_range.last)
mapping.push(extra_op) if extra_op
node
end
def on_const_path_ref(*args)
ReferenceNode.new(:const_path_ref, args, :listline => lineno..lineno, :listchar => charno..charno)
end
[:if_mod, :unless_mod, :while_mod, :until_mod].each do |kw|
node_class = AstNode.node_class_for(kw)
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{kw}; rescue NameError; end
def on_#{kw}(*args)
sr = args.last.source_range.first..args.first.source_range.last
lr = args.last.line_range.first..args.first.line_range.last
#{node_class}.new(:#{kw}, args, :line => lr, :char => sr)
end
eof
end
%w(symbols qsymbols words qwords).each do |kw|
module_eval(<<-eof, __FILE__, __LINE__ + 1)
begin; undef on_#{kw}_new; rescue NameError; end
def on_#{kw}_new(*args)
node = LiteralNode.new(:#{kw}_literal, args)
@percent_ary = node
if @map[:#{kw}_beg]
lstart, sstart = *@map[:#{kw}_beg].pop
node.source_range = Range.new(sstart, @ns_charno-1)
node.line_range = Range.new(lstart, lineno)
end
node
end
begin; undef on_#{kw}_add; rescue NameError; end
def on_#{kw}_add(list, item)
last = @source[@ns_charno,1] == "\n" ? @ns_charno - 1 : @ns_charno
list.source_range = (list.source_range.first..last)
list.line_range = (list.line_range.first..lineno)
list.push(item)
list
end
eof
end
def on_string_literal(*args)
node = visit_event_arr(LiteralNode.new(:string_literal, args))
if args.size == 1
r = args[0].source_range
if node.source_range != Range.new(r.first - 1, r.last + 1)
klass = AstNode.node_class_for(node[0].type)
r = Range.new(node.source_range.first + 1, node.source_range.last - 1)
node[0] = klass.new(node[0].type, [@source[r]], :line => node.line_range, :char => r)
end
end
node
end
def on_lambda(*args)
visit_event_arr AstNode.new(:lambda, args)
end
def on_string_content(*args)
AstNode.new(:string_content, args, :listline => lineno..lineno, :listchar => charno..charno)
end
def on_rescue(exc, *args)
exc = AstNode.new(:list, exc) if exc
visit_event AstNode.new(:rescue, [exc, *args])
end
def on_void_stmt
AstNode.new(:void_stmt, [], :line => lineno..lineno, :char => charno...charno)
end
def on_params(*args)
args.map! do |arg|
next arg unless arg.class == Array
if arg.first.class == Array
arg.map! do |sub_arg|
next sub_arg unless sub_arg.class == Array
type = sub_arg[0].type == :label ?
:named_arg : :unnamed_optional_arg
AstNode.new(type, sub_arg, :listline => lineno..lineno, :listchar => charno..charno)
end
end
AstNode.new(:list, arg, :listline => lineno..lineno, :listchar => charno..charno)
end
ParameterNode.new(:params, args, :listline => lineno..lineno, :listchar => charno..charno)
end
def on_label(data)
add_token(:label, data)
ch = charno
@charno += data.length
@ns_charno = charno
AstNode.new(:label, [data[0...-1]], :line => lineno..lineno, :char => ch..charno - 1, :token => true)
end
def on_comment(comment)
not_comment = false
if @last_ns_token.nil? || @last_ns_token.empty?
if comment =~ SourceParser::SHEBANG_LINE && !@encoding_line
@shebang_line = comment
not_comment = true
elsif comment =~ SourceParser::ENCODING_LINE
@encoding_line = comment
not_comment = true
elsif comment =~ SourceParser::FROZEN_STRING_LINE
@frozen_string_line = comment
not_comment = true
end
end
ch = charno
visit_ns_token(:comment, comment)
if not_comment
@last_ns_token = nil
return
end
source_range = ch..(charno - 1)
comment = comment.gsub(/^(\#+)\s{0,1}/, '').chomp
append_comment = @comments[lineno - 1]
hash_flag = $1 == '##' ? true : false
if append_comment && @comments_last_column &&
@comments_last_column == column && comment_starts_line?(ch)
@comments.delete(lineno - 1)
@comments_flags[lineno] = @comments_flags[lineno - 1]
@comments_flags.delete(lineno - 1)
range = @comments_range.delete(lineno - 1)
source_range = range.first..source_range.last
comment = append_comment + "\n" + comment
end
@comments[lineno] = comment
@comments_range[lineno] = source_range
@comments_flags[lineno] = hash_flag unless append_comment
@comments_last_column = column
end
def on_embdoc_beg(text)
visit_ns_token(:embdoc_beg, text)
@embdoc_start = charno - text.length
@embdoc = String.new("")
end
def on_embdoc(text)
visit_ns_token(:embdoc, text)
@embdoc << text
end
def on_embdoc_end(text)
visit_ns_token(:embdoc_end, text)
@comments_last_column = nil
@comments[lineno] = @embdoc
@comments_range[lineno] = @embdoc_start...charno
@embdoc_start = nil
@embdoc = nil
end
def on_parse_error(msg)
raise ParserSyntaxError, "syntax error in `#{file}`:(#{lineno},#{column}): #{msg}"
end
alias compile_error on_parse_error
def comment_starts_line?(charno)
(charno - 1).downto(0) do |i|
ch = @source[i]
break if ch == "\n"
return false if ch != " " && ch != "\t"
end
true
end
def insert_comments
root.traverse do |node|
next if node.type == :comment || node.type == :list || node.parent.type != :list
# never attach comments to if/unless mod nodes
if node.type == :if_mod || node.type == :unless_mod
node = node.then_block
end
# check upwards from line before node; check node's line at the end
((node.line - 1).downto(node.line - 2).to_a + [node.line]).each do |line|
comment = @comments[line]
if comment && !comment.empty?
add_comment(line, node)
break
end
end
@comments.keys.each do |line|
add_comment(line, nil, node) if node.line > line
end
end
# insert any lone unadded comments before node
root.traverse do |node|
next if node.type == :list || node.parent.type != :list
@comments.keys.each do |line|
next unless node.line_range.include?(line)
pick = nil
node.traverse do |subnode|
next unless subnode.type == :list
pick ||= subnode
next unless subnode.line_range.include?(line)
pick = subnode
end
add_comment(line, nil, pick, true) if pick
end
end unless @comments.empty?
# insert all remaining comments
@comments.each do |line, _comment|
add_comment(line, nil, root, true)
end
@comments = {}
end
def add_comment(line, node = nil, before_node = nil, into = false)
comment = @comments[line]
source_range = @comments_range[line]
line_range = ((line - comment.count("\n"))..line)
if node.nil?
node = CommentNode.new(:comment, [comment], :line => line_range, :char => source_range)
if into
before_node.push(node)
before_node.unfreeze
node.parent = before_node
elsif before_node
parent_node = before_node.parent
idx = parent_node.index(before_node)
parent_node.insert(idx, node)
parent_node.unfreeze
node.parent = parent_node
end
end
node.docstring = comment
node.docstring_hash_flag = @comments_flags[line]
node.docstring_range = line_range
@comments.delete(line)
@comments_range.delete(line)
@comments_flags.delete(line)
end
def freeze_tree(node = nil)
nodes = [node || root]
until nodes.empty?
p_node = nodes.shift
p_node.children.each do |child|
child.parent = p_node
nodes << child
end
end
end
end if defined?(::Ripper)
end
end
end
yard-0.9.7/lib/yard/parser/ruby/token_resolver.rb 0000644 0000041 0000041 00000011540 13035234564 022074 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
module Ruby
# Supports {#each} enumeration over a source's tokens, yielding
# the token and a possible {CodeObjects::Base} associated with the
# constant or identifier token.
class TokenResolver
include Enumerable
# Creates a token resolver for given source.
#
# @param source [String] the source code to tokenize
# @param namespace [CodeObjects::Base] the object/namespace to resolve from
def initialize(source, namespace = Registry.root)
@tokens = RubyParser.parse(source, '(tokenize)').tokens
raise ParserSyntaxError if @tokens.empty? && !source.empty?
@default_namespace = namespace
end
# Iterates over each token, yielding the token and a possible code
# object that is associated with the token.
#
# @yieldparam token [Array(Symbol,String,Array(Integer,Integer))] the
# current token object being iterated
# @yieldparam object [CodeObjects::Base, nil] the fully qualified code
# object associated with the current token, or nil if there is no object
# for the yielded token.
# @example Yielding code objects
# r = TokenResolver.new("A::B::C")
# r.each do |tok, obj|
# if obj
# puts "#{tok[0]} -> #{obj.path.inspect}"
# else
# puts "No object: #{tok.inspect}"
# end
# end
#
# # Prints:
# # :const -> "A"
# # No object: [:op, "::"]
# # :const -> "A::B"
# # No object: [:op, "::"]
# # :const -> "A::B::C"
def each
@states = []
push_state
@tokens.each do |token|
yield_obj = false
if skip_group && [:const, :ident, :op, :period].include?(token[0])
yield token, nil
next
else
self.skip_group = false
end
case token[0]
when :const
lookup(token[0], token[1])
yield_obj = true
self.last_sep = nil
when :ident
lookup(token[0], token[1])
yield_obj = true
self.last_sep = nil
when :op, :period
self.last_sep = token[1]
unless CodeObjects.types_for_separator(token[1])
self.object = nil
self.last_sep = nil
end
when :lparen
push_state
when :rparen
pop_state
else
self.object = nil
end
yield token, (yield_obj ? object : nil)
if next_object
self.object = next_object
self.next_object = nil
end
self.skip_group = true if yield_obj && object.nil?
end
end
def self.state_attr(*attrs)
attrs.each do |attr|
define_method(attr) { @states.last[attr.to_sym] }
define_method("#{attr}=") {|v| @states.last[attr.to_sym] = v }
protected attr, :"#{attr}="
end
end
private
def push_state
@states.push :object => nil, :skip_group => false, :last_sep => nil
end
def pop_state
@states.pop
end
state_attr :object, :next_object, :skip_group, :last_sep
def lookup(toktype, name)
types = object_resolved_types
return self.object = nil if types.empty?
if toktype == :const
types.any? do |type|
prefix = (type ? type.path : "") + last_sep.to_s
self.object = Registry.resolve(@default_namespace, "#{prefix}#{name}", true)
end
else # ident
types.any? do |type|
obj = Registry.resolve(type, name, true)
if obj.nil? && name == "new"
obj = Registry.resolve(object, "#initialize", true)
self.next_object = object if obj.nil?
end
self.object = obj
end
end
end
def object_resolved_types(obj = object)
return [obj] unless obj.is_a?(CodeObjects::MethodObject)
resolved_types = []
tags = obj.tags(:return)
tags += obj.tags(:overload).map {|o| o.tags(:return) }.flatten
tags.each do |tag|
next if tag.types.nil?
tag.types.each do |type|
type = type.sub(/<.+>/, '')
if type == "self"
resolved_types << obj.parent
else
type_obj = Registry.resolve(obj, type, true)
resolved_types << type_obj if type_obj
end
end
end
resolved_types
end
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/legacy/ 0000755 0000041 0000041 00000000000 13035234564 017751 5 ustar www-data www-data yard-0.9.7/lib/yard/parser/ruby/legacy/ruby_parser.rb 0000644 0000041 0000041 00000001234 13035234564 022633 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
module Ruby
module Legacy
# Legacy Ruby parser
# @since 0.5.6
class RubyParser < Parser::Base
def initialize(source, _filename)
@source = source
end
def parse
@parse ||= StatementList.new(@source)
self
end
def tokenize
@tokenize ||= TokenList.new(@source)
end
def enumerator
@parse
end
def encoding_line; @parse.encoding_line end
def shebang_line; @parse.shebang_line end
end
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/legacy/statement_list.rb 0000644 0000041 0000041 00000031736 13035234564 023347 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser::Ruby::Legacy
class StatementList < Array
include RubyToken
attr_accessor :shebang_line, :encoding_line
# The following list of tokens will require a block to be opened
# if used at the beginning of a statement.
OPEN_BLOCK_TOKENS = [TkCLASS, TkDEF, TkMODULE, TkUNTIL,
TkIF, TkELSIF, TkUNLESS, TkWHILE, TkFOR, TkCASE]
# Creates a new statement list
#
# @param [TokenList, String] content the tokens to create the list from
def initialize(content)
@shebang_line = nil
@encoding_line = nil
@comments_last_line = nil
if content.is_a? TokenList
@tokens = content.dup
elsif content.is_a? String
@tokens = TokenList.new(content.delete("\r"))
else
raise ArgumentError, "Invalid content for StatementList: #{content.inspect}:#{content.class}"
end
parse_statements
end
private
def parse_statements
loop do
stmt = next_statement
break if stmt.nil?
self << stmt
end
end
# Returns the next statement in the token stream
#
# @return [Statement] the next statement
def next_statement
@state = :first_statement
@statement_stack = []
@level = 0
@block_num = 0
@done = false
@current_block = nil
@comments_line = nil
@comments_hash_flag = nil
@statement = TokenList.new
@block = nil
@comments = nil
@last_tk = nil
@last_ns_tk = nil
@before_last_tk = nil
@before_last_ns_tk = nil
@first_line = nil
until @done
tk = @tokens.shift
break if tk.nil?
process_token(tk)
@before_last_tk = @last_tk
@last_tk = tk # Save last token
unless [TkSPACE, TkNL, TkEND_OF_SCRIPT].include? tk.class
@before_last_ns_tk = @last_ns_tk
@last_ns_tk = tk
end
end
# Return the code block with starting token and initial comments
# If there is no code in the block, return nil
@comments = @comments.compact if @comments
if @block || !@statement.empty?
sanitize_statement_end
sanitize_block
@statement.pop if [TkNL, TkSPACE, TkSEMICOLON].include?(@statement.last.class)
stmt = Statement.new(@statement, @block, @comments)
if @comments && @comments_line
stmt.comments_range = (@comments_line..(@comments_line + @comments.size - 1))
stmt.comments_hash_flag = @comments_hash_flag
end
stmt
elsif @comments
@statement << TkCOMMENT.new(@comments_line, 0)
@statement.first.set_text("# " + @comments.join("\n# "))
Statement.new(@statement, nil, @comments)
end
end
def sanitize_statement_end
extra = []
(@statement.size - 1).downto(0) do |index|
token = @statement[index]
next unless TkStatementEnd === token
while [TkNL, TkSPACE, TkSEMICOLON].include?(@statement[index - 1].class)
extra.unshift(@statement.delete_at(index - 1))
index -= 1
end
@statement.insert(index + 1, *extra)
break
end
end
def sanitize_block
return unless @block
extra = []
while [TkSPACE, TkNL, TkSEMICOLON].include?(@block.last.class)
next(@block.pop) if TkSEMICOLON === @block.last
extra.unshift(@block.pop)
end
@statement.each_with_index do |token, index|
if TkBlockContents === token
@statement[index, 1] = [token, *extra]
break
end
end
end
# Processes a single token
#
# @param [RubyToken::Token] tk the token to process
def process_token(tk)
# p tk.class, tk.text, @state, @level, @current_block, "
"
case @state
when :first_statement
return if process_initial_comment(tk)
return if @statement.empty? && [TkSPACE, TkNL, TkCOMMENT].include?(tk.class)
@comments_last_line = nil
if @statement.empty? && tk.class == TkALIAS
@state = :alias_statement
@alias_values = []
push_token(tk)
return
end
return if process_simple_block_opener(tk)
push_token(tk)
return if process_complex_block_opener(tk)
if balances?(tk)
process_statement_end(tk)
else
@state = :balance
end
when :alias_statement
push_token(tk)
@alias_values << tk unless [TkSPACE, TkNL, TkCOMMENT].include?(tk.class)
if @alias_values.size == 2
@state = :first_statement
if [NilClass, TkNL, TkEND_OF_SCRIPT, TkSEMICOLON].include?(peek_no_space.class)
@done = true
end
end
when :balance
@statement << tk
return unless balances?(tk)
@state = :first_statement
process_statement_end(tk)
when :block_statement
push_token(tk)
return unless balances?(tk)
process_statement_end(tk)
when :pre_block
@current_block = nil
process_block_token(tk) unless tk.class == TkSEMICOLON
@state = :block
when :block
process_block_token(tk)
when :post_block
if tk.class == TkSPACE
@statement << tk
return
end
process_statement_end(tk)
@state = :block
end
if @first_line == tk.line_no && !@statement.empty? && TkCOMMENT === tk
process_initial_comment(tk)
end
end
# Processes a token in a block
#
# @param [RubyToken::Token] tk the token to process
def process_block_token(tk)
if balances?(tk)
@statement << tk
@state = :first_statement
process_statement_end(tk)
elsif @block_num > 1 || (@block.empty? && [TkSPACE, TkNL].include?(tk.class))
@statement << tk
else
if @block.empty?
@statement << TkBlockContents.new(tk.line_no, tk.char_no)
end
@block << tk
end
end
# Processes a comment token that comes before a statement
#
# @param [RubyToken::Token] tk the token to process
# @return [Boolean] whether or not +tk+ was processed as an initial comment
def process_initial_comment(tk)
if @statement.empty? && (@comments_last_line || 0) < tk.line_no - 2
@comments = nil
end
return unless tk.class == TkCOMMENT
case tk.text
when Parser::SourceParser::SHEBANG_LINE
if !@last_ns_tk && !@encoding_line
@shebang_line = tk.text
return
end
when Parser::SourceParser::ENCODING_LINE
if (@last_ns_tk.class == TkCOMMENT && @last_ns_tk.text == @shebang_line) ||
!@last_ns_tk
@encoding_line = tk.text
return
end
end
return if !@statement.empty? && @comments
return if @first_line && tk.line_no > @first_line
if @comments_last_line && @comments_last_line < tk.line_no - 1
if @comments && @statement.empty?
@tokens.unshift(tk)
return @done = true
end
@comments = nil
end
@comments_line = tk.line_no unless @comments
# Remove the "#" and up to 1 space before the text
# Since, of course, the convention is to have "# text"
# and not "#text", which I deem ugly (you heard it here first)
@comments ||= []
if tk.text.start_with?('=begin')
lines = tk.text.count("\n")
@comments += tk.text.gsub(/\A=begin.*\r?\n|\r?\n=end.*\r?\n?\Z/, '').split(/\r?\n/)
@comments_last_line = tk.line_no + lines
else
@comments << tk.text.gsub(/^(#+)\s{0,1}/, '')
@comments_hash_flag = $1 == '##' if @comments_hash_flag.nil?
@comments_last_line = tk.line_no
end
@comments.pop if @comments.size == 1 && @comments.first =~ /^\s*$/
true
end
# Processes a simple block-opening token;
# that is, a block opener such as +begin+ or +do+
# that isn't followed by an expression
#
# @param [RubyToken::Token] tk the token to process
def process_simple_block_opener(tk)
return unless [TkLBRACE, TkDO, TkBEGIN, TkELSE].include?(tk.class) &&
# Make sure hashes are parsed as hashes, not as blocks
(@last_ns_tk.nil? || @last_ns_tk.lex_state != EXPR_BEG)
@level += 1
@state = :block
@block_num += 1
if @block.nil?
@block = TokenList.new
tokens = [tk, TkStatementEnd.new(tk.line_no, tk.char_no)]
tokens = tokens.reverse if TkBEGIN === tk.class
@statement.concat(tokens)
else
@statement << tk
end
true
end
# Processes a complex block-opening token;
# that is, a block opener such as +while+ or +for+
# that is followed by an expression
#
# @param [RubyToken::Token] tk the token to process
def process_complex_block_opener(tk)
return unless OPEN_BLOCK_TOKENS.include?(tk.class)
@current_block = tk.class
@state = :block_statement
true
end
# Processes a token that closes a statement
#
# @param [RubyToken::Token] tk the token to process
def process_statement_end(tk)
# Whitespace means that we keep the same value of @new_statement as last token
return if tk.class == TkSPACE
return unless
# We might be coming after a statement-ending token...
(@last_tk && [TkSEMICOLON, TkNL, TkEND_OF_SCRIPT].include?(tk.class)) ||
# Or we might be at the beginning of an argument list
(@current_block == TkDEF && tk.class == TkRPAREN)
# Continue line ending on . or ::
return if @last_tk && [EXPR_DOT].include?(@last_tk.lex_state)
# Continue a possible existing new statement unless we just finished an expression...
return unless (@last_tk && [EXPR_END, EXPR_ARG].include?(@last_tk.lex_state)) ||
# Or we've opened a block and are ready to move into the body
(@current_block && [TkNL, TkSEMICOLON].include?(tk.class) &&
# Handle the case where the block statement's expression is on the next line
#
# while
# foo
# end
@last_ns_tk.class != @current_block &&
# And the case where part of the expression is on the next line
#
# while foo ||
# bar
# end
@last_tk.lex_state != EXPR_BEG)
# Continue with the statement if we've hit a comma in a def
return if @current_block == TkDEF && peek_no_space.class == TkCOMMA
if [TkEND_OF_SCRIPT, TkNL, TkSEMICOLON].include?(tk.class) && @state == :block_statement &&
[TkRBRACE, TkEND].include?(@last_ns_tk.class) && @level == 0
@current_block = nil
end
unless @current_block
@done = true
return
end
@state = :pre_block
@level += 1
@block_num += 1
unless @block
@block = TokenList.new
@statement << TkStatementEnd.new(tk.line_no, tk.char_no)
end
end
# Handles the balancing of parentheses and blocks
#
# @param [RubyToken::Token] tk the token to process
# @return [Boolean] whether or not the current statement's parentheses and blocks
# are balanced after +tk+
def balances?(tk)
unless [TkALIAS, TkDEF].include?(@last_ns_tk.class) || @before_last_ns_tk.class == TkALIAS
if [TkLPAREN, TkLBRACK, TkLBRACE, TkDO, TkBEGIN].include?(tk.class)
@level += 1
elsif OPEN_BLOCK_TOKENS.include?(tk.class)
@level += 1 unless tk.class == TkELSIF
elsif [TkRPAREN, TkRBRACK, TkRBRACE, TkEND].include?(tk.class) && @level > 0
@level -= 1
end
end
@level == 0
end
# Adds a token to the current statement,
# unless it's a newline, semicolon, or comment
#
# @param [RubyToken::Token] tk the token to process
def push_token(tk)
@first_line = tk.line_no if @statement.empty?
@statement << tk unless @level == 0 && [TkCOMMENT].include?(tk.class)
end
# Returns the next token in the stream that's not a space
#
# @return [RubyToken::Token] the next non-space token
def peek_no_space
return @tokens.first unless @tokens.first.class == TkSPACE
@tokens[1]
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/legacy/token_list.rb 0000644 0000041 0000041 00000003772 13035234564 022462 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser::Ruby::Legacy
class TokenList < Array
include RubyToken
def initialize(content = nil)
self << content if content
end
def to_s(full_statement = false, show_block = true)
inject([]) do |acc, token|
break acc if !full_statement && TkStatementEnd === token
acc << (!show_block && TkBlockContents === token ? "" : token.text)
end.join
end
# @param [TokenList, Token, String] tokens
# A list of tokens. If the token is a string, it
# is parsed with {RubyLex}.
def push(*tokens)
tokens.each do |tok|
if tok.is_a?(TokenList) || tok.is_a?(Array)
concat tok
elsif tok.is_a?(Token)
super tok
elsif tok.is_a?(String)
parse_content(tok)
else
raise ArgumentError, "Expecting token, list of tokens or string of code to be tokenized. Got #{tok.class}"
end
end
self
end
alias << push
def squeeze(type = TkSPACE)
last = nil
TokenList.new(map {|t| x = t.is_a?(type) && last.is_a?(type) ? nil : t; last = t; x })
end
private
def parse_content(content)
lex = RubyLex.new(content)
loop do
tk = lex.token
break if tk.nil?
self << convert_token(lex, tk)
end
end
def convert_token(lex, tk)
if TkIDENTIFIER === tk && lex.peek == ':'
next_tk = lex.token
sym = TkLABEL.new(tk.line_no, tk.char_no, nil)
sym.lex_state = lex.lex_state
sym.set_text(tk.text + next_tk.text)
elsif TkSYMBEG === tk
next_tk = lex.token
if next_tk
sym = TkSYMBOL.new(tk.line_no, tk.char_no, nil)
sym.lex_state = lex.lex_state
sym.set_text(tk.text + next_tk.text)
else
tk
end
else
tk
end
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/legacy/statement.rb 0000644 0000041 0000041 00000003044 13035234564 022303 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser::Ruby::Legacy
class Statement
attr_reader :tokens, :comments, :block
attr_accessor :comments_range
# @deprecated Groups are now defined by directives
# @see Tags::GroupDirective
attr_accessor :group
attr_accessor :comments_hash_flag
def initialize(tokens, block = nil, comments = nil)
@tokens = tokens
@block = block
@comments = comments
@comments_hash_flag = false
end
def first_line
to_s.split(/\n/)[0]
end
def to_s(include_block = true)
tokens.map do |token|
RubyToken::TkBlockContents === token ? (include_block ? block.to_s : '') : token.text
end.join
end
alias source to_s
def inspect
l = line - 1
to_s(false).split(/\n/).map do |text|
"\t#{l += 1}: #{text}"
end.join("\n")
end
def show
"\t#{line}: #{first_line}"
end
# @return [Fixnum] the first line of Ruby source
def line
tokens.first.line_no
end
# @return [Range] the first to last lines of Ruby source
# @since 0.5.4
def line_range
tokens.first.line_no..tokens.last.line_no
end
private
def clean_tokens(tokens)
last_tk = nil
tokens.reject do |tk|
tk.is_a?(RubyToken::TkNL) ||
(last_tk.is_a?(RubyToken::TkSPACE) &&
last_tk.class == tk.class) && last_tk = tk
end
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/legacy/ruby_lex.rb 0000644 0000041 0000041 00000106272 13035234564 022137 0 ustar www-data www-data require "e2mmap"
require "irb/slex"
module YARD
module Parser::Ruby::Legacy
# Legacy lexical tokenizer module.
module RubyToken
EXPR_BEG = :EXPR_BEG
EXPR_MID = :EXPR_MID
EXPR_END = :EXPR_END
EXPR_ARG = :EXPR_ARG
EXPR_FNAME = :EXPR_FNAME
EXPR_DOT = :EXPR_DOT
EXPR_CLASS = :EXPR_CLASS
# Represents a token in the Ruby lexer
class Token
# @return [Integer] the line number in the file/stream the token is
# located.
attr_reader :line_no
# @return [Integer] the character number in the file/stream the token
# is located.
attr_reader :char_no
# @return [String] the token text value
attr_reader :text
# @return [Symbol] the lexical state at the token
attr_accessor :lex_state
# @private
NO_TEXT = "??".freeze
# Creates a new Token object
# @param [Integer] line_no the line number to initialize the token to
# @param [Integer] char_no the char number to initialize the token to
def initialize(line_no, char_no)
@line_no = line_no
@char_no = char_no
@text = NO_TEXT
end
# Chainable way to sets the text attribute
#
# @param [String] text the new text
# @return [Token] this token object
def set_text(text)
@text = text
self
end
end
# Represents a block
class TkBlockContents < Token
def text; '...' end
end
# Represents an end statement
class TkStatementEnd < Token
def text; '' end
end
class TkNode < Token
attr :node
end
# Represents whitespace
class TkWhitespace < Token
end
# Represents a Ruby identifier
class TkId < Token
def initialize(line_no, char_no, name)
super(line_no, char_no)
@name = name
end
attr :name
end
# Represents a Ruby keyword
class TkKW < TkId
end
# Represents a Ruby value
class TkVal < Token
def initialize(line_no, char_no, value = nil)
super(line_no, char_no)
set_text(value)
end
end
class TkOp < Token
def name
self.class.op_name
end
end
class TkOPASGN < TkOp
def initialize(line_no, char_no, op)
super(line_no, char_no)
op = TkReading2Token[op] unless op.is_a?(Symbol)
@op = op
end
attr :op
end
class TkUnknownChar < Token
def initialize(line_no, char_no, _id)
super(line_no, char_no)
@name = char_no > 255 ? '?' : char_no.chr
end
attr :name
end
class TkError < Token
end
# @private
def set_token_position(line, char)
@prev_line_no = line
@prev_char_no = char
end
# @private
def Token(token, value = nil) # rubocop:disable Style/MethodName
tk = nil
case token
when String, Symbol
source = token.is_a?(String) ? TkReading2Token : TkSymbol2Token
if (tk = source[token]).nil?
IRB.fail TkReading2TokenNoKey, token
end
tk = Token(tk[0], value)
else
if token
tk = if (token.ancestors & [TkId, TkVal, TkOPASGN, TkUnknownChar]).empty?
token.new(@prev_line_no, @prev_char_no)
else
token.new(@prev_line_no, @prev_char_no, value)
end
end
end
tk
end
# @private
TokenDefinitions = [
[:TkCLASS, TkKW, "class", EXPR_CLASS],
[:TkMODULE, TkKW, "module", EXPR_BEG],
[:TkDEF, TkKW, "def", EXPR_FNAME],
[:TkUNDEF, TkKW, "undef", EXPR_FNAME],
[:TkBEGIN, TkKW, "begin", EXPR_BEG],
[:TkRESCUE, TkKW, "rescue", EXPR_MID],
[:TkENSURE, TkKW, "ensure", EXPR_BEG],
[:TkEND, TkKW, "end", EXPR_END],
[:TkIF, TkKW, "if", EXPR_BEG, :TkIF_MOD],
[:TkUNLESS, TkKW, "unless", EXPR_BEG, :TkUNLESS_MOD],
[:TkTHEN, TkKW, "then", EXPR_BEG],
[:TkELSIF, TkKW, "elsif", EXPR_BEG],
[:TkELSE, TkKW, "else", EXPR_BEG],
[:TkCASE, TkKW, "case", EXPR_BEG],
[:TkWHEN, TkKW, "when", EXPR_BEG],
[:TkWHILE, TkKW, "while", EXPR_BEG, :TkWHILE_MOD],
[:TkUNTIL, TkKW, "until", EXPR_BEG, :TkUNTIL_MOD],
[:TkFOR, TkKW, "for", EXPR_BEG],
[:TkBREAK, TkKW, "break", EXPR_END],
[:TkNEXT, TkKW, "next", EXPR_END],
[:TkREDO, TkKW, "redo", EXPR_END],
[:TkRETRY, TkKW, "retry", EXPR_END],
[:TkIN, TkKW, "in", EXPR_BEG],
[:TkDO, TkKW, "do", EXPR_BEG],
[:TkRETURN, TkKW, "return", EXPR_MID],
[:TkYIELD, TkKW, "yield", EXPR_END],
[:TkSUPER, TkKW, "super", EXPR_END],
[:TkSELF, TkKW, "self", EXPR_END],
[:TkNIL, TkKW, "nil", EXPR_END],
[:TkTRUE, TkKW, "true", EXPR_END],
[:TkFALSE, TkKW, "false", EXPR_END],
[:TkAND, TkKW, "and", EXPR_BEG],
[:TkOR, TkKW, "or", EXPR_BEG],
[:TkNOT, TkKW, "not", EXPR_BEG],
[:TkIF_MOD, TkKW],
[:TkUNLESS_MOD, TkKW],
[:TkWHILE_MOD, TkKW],
[:TkUNTIL_MOD, TkKW],
[:TkALIAS, TkKW, "alias", EXPR_FNAME],
[:TkDEFINED, TkKW, "defined?", EXPR_END],
[:TklBEGIN, TkKW, "BEGIN", EXPR_END],
[:TklEND, TkKW, "END", EXPR_END],
[:Tk__LINE__, TkKW, "__LINE__", EXPR_END],
[:Tk__FILE__, TkKW, "__FILE__", EXPR_END],
[:TkIDENTIFIER, TkId],
[:TkFID, TkId],
[:TkGVAR, TkId],
[:TkIVAR, TkId],
[:TkCONSTANT, TkId],
[:TkINTEGER, TkVal],
[:TkFLOAT, TkVal],
[:TkSYMBOL, TkVal],
[:TkLABEL, TkVal],
[:TkSTRING, TkVal],
[:TkXSTRING, TkVal],
[:TkREGEXP, TkVal],
[:TkCOMMENT, TkVal],
[:TkDSTRING, TkNode],
[:TkDXSTRING, TkNode],
[:TkDREGEXP, TkNode],
[:TkNTH_REF, TkId],
[:TkBACK_REF, TkId],
[:TkUPLUS, TkOp, "+@"],
[:TkUMINUS, TkOp, "-@"],
[:TkPOW, TkOp, "**"],
[:TkCMP, TkOp, "<=>"],
[:TkEQ, TkOp, "=="],
[:TkEQQ, TkOp, "==="],
[:TkNEQ, TkOp, "!="],
[:TkGEQ, TkOp, ">="],
[:TkLEQ, TkOp, "<="],
[:TkANDOP, TkOp, "&&"],
[:TkOROP, TkOp, "||"],
[:TkMATCH, TkOp, "=~"],
[:TkNMATCH, TkOp, "!~"],
[:TkDOT2, TkOp, ".."],
[:TkDOT3, TkOp, "..."],
[:TkAREF, TkOp, "[]"],
[:TkASET, TkOp, "[]="],
[:TkLSHFT, TkOp, "<<"],
[:TkRSHFT, TkOp, ">>"],
[:TkCOLON2, TkOp],
[:TkCOLON3, TkOp],
[:OPASGN, TkOp], # +=, -= etc. #
[:TkASSOC, TkOp, "=>"],
[:TkQUESTION, TkOp, "?"], #?
[:TkCOLON, TkOp, ":"], #:
[:TkSTAR], # *arg
[:TkAMPER], # &arg #
[:TkSYMBEG, TkId],
[:TkGT, TkOp, ">"],
[:TkLT, TkOp, "<"],
[:TkPLUS, TkOp, "+"],
[:TkMINUS, TkOp, "-"],
[:TkMULT, TkOp, "*"],
[:TkDIV, TkOp, "/"],
[:TkMOD, TkOp, "%"],
[:TkBITOR, TkOp, "|"],
[:TkBITXOR, TkOp, "^"],
[:TkBITAND, TkOp, "&"],
[:TkBITNOT, TkOp, "~"],
[:TkNOTOP, TkOp, "!"],
[:TkBACKQUOTE, TkOp, "`"],
[:TkASSIGN, Token, "="],
[:TkDOT, Token, "."],
[:TkLPAREN, Token, "("], # (exp)
[:TkLBRACK, Token, "["], # [arry]
[:TkLBRACE, Token, "{"], # {hash}
[:TkRPAREN, Token, ")"],
[:TkRBRACK, Token, "]"],
[:TkRBRACE, Token, "}"],
[:TkCOMMA, Token, ","],
[:TkSEMICOLON, Token, ";"],
[:TkSPACE, TkWhitespace],
[:TkNL, TkWhitespace],
[:TkEND_OF_SCRIPT, TkWhitespace],
[:TkBACKSLASH, TkUnknownChar, "\\"],
[:TkAT, TkUnknownChar, "@"],
[:TkDOLLAR, TkUnknownChar, "\$"]
]
# { reading => token_class }
# { reading => [token_class, *opt] }
TkReading2Token = {}
TkSymbol2Token = {}
# @private
def self.def_token(token_n, super_token = Token, reading = nil, *opts)
token_n = token_n.id2name unless token_n.is_a?(String)
if RubyToken.const_defined?(token_n)
# IRB.fail AlreadyDefinedToken, token_n
end
token_c = Class.new super_token
RubyToken.const_set token_n, token_c
# token_c.inspect
if reading
if TkReading2Token[reading]
IRB.fail TkReading2TokenDuplicateError, token_n, reading
end
if opts.empty?
TkReading2Token[reading] = [token_c]
else
TkReading2Token[reading] = [token_c].concat(opts)
end
end
TkSymbol2Token[token_n.intern] = token_c
if token_c <= TkOp
token_c.class_eval %{
def self.op_name; "#{reading}"; end
}
end
end
for defs in TokenDefinitions
def_token(*defs)
end
NEWLINE_TOKEN = TkNL.new(0, 0)
NEWLINE_TOKEN.set_text("\n")
end
# Lexical analyzer for Ruby source
# @private
class RubyLex
# Read an input stream character by character. We allow for unlimited
# ungetting of characters just read.
#
# We simplify the implementation greatly by reading the entire input
# into a buffer initially, and then simply traversing it using
# pointers.
#
# We also have to allow for the here document diversion. This
# little gem comes about when the lexer encounters a here
# document. At this point we effectively need to split the input
# stream into two parts: one to read the body of the here document,
# the other to read the rest of the input line where the here
# document was initially encountered. For example, we might have
#
# do_something(<<-A, <<-B)
# stuff
# for
# A
# stuff
# for
# B
#
# When the lexer encounters the <= @size
ch = @content[@offset, 1]
@offset += 1
@hwm = @offset if @hwm < @offset
if @newline_pending
@line_num += 1
@last_newline = @offset - 1
@newline_pending = false
end
if ch == "\n"
@newline_pending = true
end
ch
end
def getc_already_read
getc
end
def ungetc(_ch)
raise "unget past beginning of file" if @offset <= 0
@offset -= 1
if @content[@offset] == ?\n
@newline_pending = false
end
end
def get_read
res = @content[@read_back_offset...@offset]
@read_back_offset = @offset
res
end
def peek(at)
pos = @offset + at
if pos >= @size
nil
else
@content[pos, 1]
end
end
def peek_equal(str)
@content[@offset, str.length] == str
end
def divert_read_from(reserve)
@content[@offset, 0] = reserve
@size = @content.size
end
end
# end of nested class BufferedReader
extend Exception2MessageMapper
def_exception(:AlreadyDefinedToken, "Already defined token(%s)")
def_exception(:TkReading2TokenNoKey, "key nothing(key='%s')")
def_exception(:TkSymbol2TokenNoKey, "key nothing(key='%s')")
def_exception(:TkReading2TokenDuplicateError,
"key duplicate(token_n='%s', key='%s')")
def_exception(:SyntaxError, "%s")
include RubyToken
include IRB
attr_reader :continue
attr_reader :lex_state
def self.debug?
false
end
def initialize(content)
lex_init
@reader = BufferedReader.new(content)
@exp_line_no = @line_no = 1
@base_char_no = 0
@indent = 0
@ltype = nil
@quoted = nil
@lex_state = EXPR_BEG
@space_seen = false
@continue = false
@line = ""
@skip_space = false
@read_auto_clean_up = false
@exception_on_syntax_error = true
@colonblock_seen = false
end
attr_accessor :skip_space
attr_accessor :read_auto_clean_up
attr_accessor :exception_on_syntax_error
attr :indent
# io functions
def line_no
@reader.line_num
end
def char_no
@reader.column
end
def get_read
@reader.get_read
end
def getc
@reader.getc
end
def getc_of_rests
@reader.getc_already_read
end
def gets
(c = getc) || return
l = ""
begin
l.concat c unless c == "\r"
break if c == "\n"
end while c = getc # rubocop:disable Lint/Loop
l
end
def ungetc(c = nil)
@reader.ungetc(c)
end
def peek_equal?(str)
@reader.peek_equal(str)
end
def peek(i = 0)
@reader.peek(i)
end
def lex
catch(:eof) do
until ((tk = token).is_a?(TkNL) || tk.is_a?(TkEND_OF_SCRIPT)) &&
!@continue ||
tk.nil?
end
line = get_read
if line == "" && tk.is_a?(TkEND_OF_SCRIPT) || tk.nil?
nil
else
line
end
end
end
def token
set_token_position(line_no, char_no)
catch(:eof) do
begin
begin
tk = @OP.match(self)
@space_seen = tk.is_a?(TkSPACE)
rescue SyntaxError
abort if @exception_on_syntax_error
tk = TkError.new(line_no, char_no)
end
end while @skip_space && tk.is_a?(TkSPACE)
if @read_auto_clean_up
get_read
end
# throw :eof unless tk
p tk if $DEBUG
tk.lex_state = lex_state if tk
tk
end
end
ENINDENT_CLAUSE = [
"case", "class", "def", "do", "for", "if",
"module", "unless", "until", "while", "begin"
] #, "when"
ACCEPTS_COLON = ["if", "for", "unless", "until", "while"]
DEINDENT_CLAUSE = ["end"] #, "when"
PERCENT_LTYPE = {
"q" => "\'",
"Q" => "\"",
"x" => "\`",
"r" => "/",
"w" => "]",
"W" => "]"
}
PERCENT_PAREN = {
"{" => "}",
"[" => "]",
"<" => ">",
"(" => ")"
}
Ltype2Token = {
"\'" => TkSTRING,
"\"" => TkSTRING,
"\`" => TkXSTRING,
"/" => TkREGEXP,
"]" => TkDSTRING
}
Ltype2Token.default = TkSTRING
DLtype2Token = {
"\"" => TkDSTRING,
"\`" => TkDXSTRING,
"/" => TkDREGEXP
}
def lex_init()
@OP = SLex.new
@OP.def_rules("\0", "\004", "\032") do |chars, _io|
Token(TkEND_OF_SCRIPT).set_text(chars)
end
@OP.def_rules(" ", "\t", "\f", "\r", "\13") do |chars, _io|
@space_seen = TRUE
while (ch = getc) =~ /[ \t\f\r\13]/
chars << ch
end
ungetc
Token(TkSPACE).set_text(chars)
end
@OP.def_rule("#") do |_op, _io|
identify_comment
end
@OP.def_rule("=begin", proc { @prev_char_no == 0 && peek(0) =~ /\s/ }) do |op, _io|
str = String.new(op)
@ltype = "="
begin
line = String.new
begin
ch = getc
line << ch
end until ch == "\n"
str << line
end until line =~ /^=end/
ungetc
@ltype = nil
if str =~ /\A=begin\s+rdoc/i
str.sub!(/\A=begin.*\n/, '')
str.sub!(/^=end.*/m, '')
Token(TkCOMMENT).set_text(str)
else
Token(TkCOMMENT).set_text(str)
end
end
@OP.def_rule("\n") do
print "\\n\n" if RubyLex.debug?
@colonblock_seen = false
case @lex_state
when EXPR_BEG, EXPR_FNAME, EXPR_DOT
@continue = TRUE
else
@continue = FALSE
@lex_state = EXPR_BEG
end
Token(TkNL).set_text("\n")
end
@OP.def_rules("*", "**",
"!", "!=", "!~",
"=", "==", "===",
"=~", "<=>",
"<", "<=",
">", ">=", ">>") do |op, _io|
@lex_state = EXPR_BEG
Token(op).set_text(op)
end
@OP.def_rules("<<") do |op, _io|
tk = nil
if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
(@lex_state != EXPR_ARG || @space_seen)
c = peek(0)
tk = identify_here_document if /[-\w\"\'\`]/ =~ c
end
if !tk
@lex_state = EXPR_BEG
tk = Token(op).set_text(op)
end
tk
end
@OP.def_rules("'", '"') do |op, _io|
identify_string(op)
end
@OP.def_rules("`") do |op, _io|
if @lex_state == EXPR_FNAME
Token(op).set_text(op)
else
identify_string(op)
end
end
@OP.def_rules('?') do |op, _io|
if @lex_state == EXPR_END
@lex_state = EXPR_BEG
Token(TkQUESTION).set_text(op)
else
ch = getc
if @lex_state == EXPR_ARG && ch !~ /\s/
ungetc
@lex_state = EXPR_BEG
Token(TkQUESTION).set_text(op)
else
str = String.new(op)
str << ch
if ch == '\\' #'
str << read_escape
end
@lex_state = EXPR_END
Token(TkINTEGER).set_text(str)
end
end
end
@OP.def_rules("&", "&&", "|", "||") do |op, _io|
@lex_state = EXPR_BEG
Token(op).set_text(op)
end
@OP.def_rules("+=", "-=", "*=", "**=",
"&=", "|=", "^=", "<<=", ">>=", "||=", "&&=") do |op, _io|
@lex_state = EXPR_BEG
op =~ /^(.*)=$/
Token(TkOPASGN, $1).set_text(op)
end
@OP.def_rule("+@", proc { @lex_state == EXPR_FNAME }) do |op, _io|
Token(TkUPLUS).set_text(op)
end
@OP.def_rule("-@", proc { @lex_state == EXPR_FNAME }) do |op, _io|
Token(TkUMINUS).set_text(op)
end
@OP.def_rules("+", "-") do |op, _io|
catch(:RET) do
if @lex_state == EXPR_ARG
if @space_seen && peek(0) =~ /[0-9]/
throw :RET, identify_number(op)
else
@lex_state = EXPR_BEG
end
elsif @lex_state != EXPR_END && peek(0) =~ /[0-9]/
throw :RET, identify_number(op)
else
@lex_state = EXPR_BEG
end
Token(op).set_text(op)
end
end
@OP.def_rule(".") do
@lex_state = EXPR_BEG
if peek(0) =~ /[0-9]/
ungetc
identify_number("")
else
# for obj.if
@lex_state = EXPR_DOT
Token(TkDOT).set_text(".")
end
end
@OP.def_rules("..", "...") do |op, _io|
@lex_state = EXPR_BEG
Token(op).set_text(op)
end
lex_int2
end
def lex_int2
@OP.def_rules("]", "}", ")") do |op, _io|
@lex_state = EXPR_END
@indent -= 1
Token(op).set_text(op)
end
@OP.def_rule(":") do
if (@colonblock_seen && @lex_state != EXPR_BEG) || peek(0) =~ /\s/
@lex_state = EXPR_BEG
tk = Token(TkCOLON)
else
@lex_state = EXPR_FNAME
tk = Token(TkSYMBEG)
end
tk.set_text(":")
end
@OP.def_rule("::") do
# p @lex_state.id2name, @space_seen
if @lex_state == EXPR_BEG || @lex_state == EXPR_ARG && @space_seen
@lex_state = EXPR_BEG
tk = Token(TkCOLON3)
else
@lex_state = EXPR_DOT
tk = Token(TkCOLON2)
end
tk.set_text("::")
end
@OP.def_rule("/") do |op, _io|
if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
identify_string(op)
elsif peek(0) == '='
getc
@lex_state = EXPR_BEG
Token(TkOPASGN, :/).set_text("/=") #")
elsif @lex_state == EXPR_ARG && @space_seen && peek(0) !~ /\s/
identify_string(op)
else
@lex_state = EXPR_BEG
Token("/").set_text(op)
end
end
@OP.def_rules("^") do
@lex_state = EXPR_BEG
Token("^").set_text("^")
end
# @OP.def_rules("^=") do
# @lex_state = EXPR_BEG
# Token(TkOPASGN, :^)
# end
@OP.def_rules(",", ";") do |op, _io|
@colonblock_seen = false
@lex_state = EXPR_BEG
Token(op).set_text(op)
end
@OP.def_rule("~") do
@lex_state = EXPR_BEG
Token("~").set_text("~")
end
@OP.def_rule("~@", proc { @lex_state = EXPR_FNAME }) do
@lex_state = EXPR_BEG
Token("~").set_text("~@")
end
@OP.def_rule("(") do
@indent += 1
# if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
# @lex_state = EXPR_BEG
# tk = Token(TkfLPAREN)
# else
@lex_state = EXPR_BEG
tk = Token(TkLPAREN)
# end
tk.set_text("(")
end
@OP.def_rule("[]", proc { @lex_state == EXPR_FNAME }) do
Token("[]").set_text("[]")
end
@OP.def_rule("[]=", proc { @lex_state == EXPR_FNAME }) do
Token("[]=").set_text("[]=")
end
@OP.def_rule("[") do
@indent += 1
# if @lex_state == EXPR_FNAME
# t = Token(TkfLBRACK)
# else
# if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
# t = Token(TkLBRACK)
# elsif @lex_state == EXPR_ARG && @space_seen
# else
# t = Token(TkfLBRACK)
# end
# end
t = Token(TkLBRACK)
@lex_state = EXPR_BEG
t.set_text("[")
end
@OP.def_rule("{") do
@indent += 1
# if @lex_state != EXPR_END && @lex_state != EXPR_ARG
# t = Token(TkLBRACE)
# else
# t = Token(TkfLBRACE)
# end
t = Token(TkLBRACE)
@lex_state = EXPR_BEG
t.set_text("{")
end
@OP.def_rule('\\') do #'
if getc == "\n"
@space_seen = true
@continue = true
Token(TkSPACE).set_text("\\\n")
else
ungetc
Token("\\").set_text("\\") #"
end
end
@OP.def_rule('%') do |_op, _io|
if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
identify_quotation('%')
elsif peek(0) == '='
getc
Token(TkOPASGN, "%").set_text("%=")
elsif @lex_state == EXPR_ARG && @space_seen && peek(0) !~ /\s/
identify_quotation('%')
else
@lex_state = EXPR_BEG
Token("%").set_text("%")
end
end
@OP.def_rule('$') do #'
identify_gvar
end
@OP.def_rule('@') do
if peek(0) =~ /[@\w]/
ungetc
identify_identifier
else
Token("@").set_text("@")
end
end
# @OP.def_rule("def", proc{|op, io| /\s/ =~ io.peek(0)}) do
# |op, io|
# @indent += 1
# @lex_state = EXPR_FNAME
# # @lex_state = EXPR_END
# # until @rests[0] == "\n" or @rests[0] == ";"
# # rests.shift
# # end
# end
@OP.def_rule("__END__", proc { @prev_char_no == 0 && peek(0) =~ /[\r\n]/ }) do
throw :eof
end
@OP.def_rule("") do |op, io|
printf "MATCH: start %s: %s\n", op, io.inspect if RubyLex.debug?
if peek(0) =~ /[0-9]/
t = identify_number("")
elsif peek(0) =~ /[\w]/
t = identify_identifier
end
printf "MATCH: end %s: %s\n", op, io.inspect if RubyLex.debug?
t
end
p @OP if RubyLex.debug?
end
def identify_gvar
@lex_state = EXPR_END
str = String.new("$")
tk = case ch = getc
when %r{[~_*$?!@/\\;,=:<>".]}
str << ch
Token(TkGVAR, str)
when "-"
str << "-" << getc
Token(TkGVAR, str)
when "&", "`", "'", "+"
str << ch
Token(TkBACK_REF, str)
when /[1-9]/
str << ch
while (ch = getc) =~ /[0-9]/
str << ch
end
ungetc
Token(TkNTH_REF)
when /\w/
ungetc
ungetc
return identify_identifier
else
ungetc
Token("$")
end
tk.set_text(str)
end
def identify_identifier
token = ""
token.concat getc if peek(0) =~ /[$@]/
token.concat getc if peek(0) == "@"
while (ch = getc) =~ /\w|_/
print ":", ch, ":" if RubyLex.debug?
token.concat ch
end
ungetc
if ch == "!" || ch == "?"
token.concat getc
end
# fix token
# $stderr.puts "identifier - #{token}, state = #@lex_state"
case token
when /^\$/
return Token(TkGVAR, token).set_text(token)
when /^\@/
@lex_state = EXPR_END
return Token(TkIVAR, token).set_text(token)
end
if @lex_state != EXPR_DOT
print token, "\n" if RubyLex.debug?
token_c, *trans = TkReading2Token[token]
if token_c
# reserved word?
if @lex_state != EXPR_BEG &&
@lex_state != EXPR_FNAME &&
trans[1]
# modifiers
token_c = TkSymbol2Token[trans[1]]
@lex_state = trans[0]
else
if @lex_state != EXPR_FNAME
if ENINDENT_CLAUSE.include?(token)
@indent += 1
if ACCEPTS_COLON.include?(token)
@colonblock_seen = true
else
@colonblock_seen = false
end
elsif DEINDENT_CLAUSE.include?(token)
@indent -= 1
@colonblock_seen = false
end
@lex_state = trans[0]
else
@lex_state = EXPR_END
end
end
return Token(token_c, token).set_text(token)
end
end
if @lex_state == EXPR_FNAME
@lex_state = EXPR_END
if peek(0) == '='
token.concat getc
end
elsif @lex_state == EXPR_BEG || @lex_state == EXPR_DOT
@lex_state = EXPR_ARG
else
@lex_state = EXPR_END
end
if token[0, 1] =~ /[A-Z]/
return Token(TkCONSTANT, token).set_text(token)
elsif token[token.size - 1, 1] =~ /[!?]/
return Token(TkFID, token).set_text(token)
else
return Token(TkIDENTIFIER, token).set_text(token)
end
end
def identify_here_document
ch = getc
if ch == "-"
ch = getc
indent = true
end
if /['"`]/ =~ ch # '
lt = ch
quoted = ""
while (c = getc) && c != lt
quoted.concat c
end
else
lt = '"'
quoted = ch.dup
while (c = getc) && c =~ /\w/
quoted.concat c
end
ungetc
end
ltback, @ltype = @ltype, lt
reserve = String.new
while ch = getc
reserve << ch
if ch == "\\" #"
ch = getc
reserve << ch
elsif ch == "\n"
break
end
end
str = String.new
while (l = gets)
l.chomp!
l.strip! if indent
break if l == quoted
str << l.chomp << "\n"
end
@reader.divert_read_from(reserve)
@ltype = ltback
@lex_state = EXPR_END
Token(Ltype2Token[lt], str).set_text(str.dump)
end
def identify_quotation(initial_char)
ch = getc
if lt = PERCENT_LTYPE[ch]
initial_char += ch
ch = getc
elsif ch =~ /\W/
lt = "\""
else
# RubyLex.fail SyntaxError, "unknown type of %string ('#{ch}')"
end
# if ch !~ /\W/
# ungetc
# next
# end
# @ltype = lt
@quoted = ch unless @quoted = PERCENT_PAREN[ch]
identify_string(lt, @quoted, ch, initial_char) if lt
end
def identify_number(start)
str = start.dup
if start == "+" || start == "-" || start == ""
start = getc
str << start
end
@lex_state = EXPR_END
if start == "0"
if peek(0) == "x"
ch = getc
str << ch
match = /[0-9a-f_]/
else
match = /[0-7_]/
end
while ch = getc
if ch !~ match
ungetc
break
else
str << ch
end
end
return Token(TkINTEGER).set_text(str)
end
type = TkINTEGER
allow_point = TRUE
allow_e = TRUE
while ch = getc
case ch
when /[0-9_]/
str << ch
when allow_point && "."
type = TkFLOAT
if peek(0) !~ /[0-9]/
ungetc
break
end
str << ch
allow_point = false
when allow_e && "e", allow_e && "E"
str << ch
type = TkFLOAT
if peek(0) =~ /[+-]/
str << getc
end
allow_e = false
allow_point = false
else
ungetc
break
end
end
Token(type).set_text(str)
end
def identify_string(ltype, quoted = ltype, opener = nil, initial_char = nil)
@ltype = ltype
@quoted = quoted
subtype = nil
str = String.new
str << initial_char if initial_char
str << (opener || quoted)
nest = 0
begin
while ch = getc
str << ch
if @quoted == ch
if nest == 0
break
else
nest -= 1
end
elsif opener == ch
nest += 1
elsif @ltype != "'" && @ltype != "]" && ch == "#"
ch = getc
if ch == "{"
subtype = true
str << ch << skip_inner_expression
else
ungetc(ch)
end
elsif ch == '\\' #'
str << read_escape
end
end
if @ltype == "/"
if peek(0) =~ /i|o|n|e|s/
str << getc
end
end
if subtype
Token(DLtype2Token[ltype], str)
else
Token(Ltype2Token[ltype], str)
end.set_text(str)
ensure
@ltype = nil
@quoted = nil
@lex_state = EXPR_END
end
end
def skip_inner_expression
res = String.new
nest = 0
while (ch = getc)
res << ch
if ch == '}'
break if nest == 0
nest -= 1
elsif ch == '{'
nest += 1
end
end
res
end
def identify_comment
@ltype = "#"
comment = String.new("#")
while ch = getc
if ch == "\\"
ch = getc
if ch == "\n"
ch = " "
else
comment << "\\"
end
else
if ch == "\n"
@ltype = nil
ungetc
break
end
end
comment << ch
end
Token(TkCOMMENT).set_text(comment)
end
def read_escape
res = String.new
case ch = getc
when /[0-7]/
ungetc ch
3.times do
case ch = getc
when /[0-7]/
when nil
break
else
ungetc
break
end
res << ch
end
when "x"
res << ch
2.times do
case ch = getc
when /[0-9a-fA-F]/
when nil
break
else
ungetc
break
end
res << ch
end
when "M"
res << ch
if (ch = getc) != '-'
ungetc
else
res << ch
if (ch = getc) == "\\" #"
res << ch
res << read_escape
else
res << ch
end
end
when "C", "c" #, "^"
res << ch
if ch == "C" && (ch = getc) != "-"
ungetc
else
res << ch
if (ch = getc) == "\\" #"
res << ch
res << read_escape
else
res << ch
end
end
else
res << ch
end
res
end
end
end
end
yard-0.9.7/lib/yard/parser/ruby/ast_node.rb 0000644 0000041 0000041 00000040001 13035234564 020621 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Parser
module Ruby
# Builds and s-expression by creating {AstNode} objects with
# the type provided by the first argument.
#
# @example An implicit list of keywords
# ast = s(s(:kw, "if"), s(:kw, "else"))
# ast.type # => :list
# @example A method call
# s(:command, s(:var_ref, "mymethod"))
#
# @overload s(*nodes, opts = {})
# @param [Array] nodes a list of nodes.
# @param [Hash] opts any extra options (docstring, file, source) to
# set on the object
# @return [AstNode] an implicit node where node.type == +:list+
# @overload s(type, *children, opts = {})
# @param [Symbol] type the node type
# @param [Array] children any child nodes inside this one
# @param [Hash] opts any extra options to set on the object
# @return [AstNode] a node of type +type+.
# @see AstNode#initialize
def s(*args)
type = Symbol === args.first ? args.shift : :list
opts = Hash === args.last ? args.pop : {}
AstNode.node_class_for(type).new(type, args, opts)
end
# An AST node is characterized by a type and a list of children. It
# is most easily represented by the s-expression {#s} such as:
# # AST for "if true; 5 end":
# s(s(:if, s(:var_ref, s(:kw, "true")), s(s(:int, "5")), nil))
#
# The node type is not considered part of the list, only its children.
# So +ast[0]+ does not refer to the type, but rather the first child
# (or object). Items that are not +AstNode+ objects can be part of the
# list, like Strings or Symbols representing names. To return only
# the AstNode children of the node, use {#children}.
class AstNode < Array
attr_accessor :docstring_hash_flag
attr_accessor :docstring, :docstring_range, :source
# @deprecated Groups are now defined by directives
# @see Tags::GroupDirective
attr_accessor :group
attr_writer :source_range, :line_range, :file, :full_source
alias comments docstring
alias comments_range docstring_range
alias comments_hash_flag docstring_hash_flag
alias to_s source
# @return [Symbol] the node's unique symbolic type
attr_accessor :type
# @return [AstNode, nil] the node's parent or nil if it is a root node.
attr_accessor :parent
# @return [Range] the character range in {#full_source} represented
# by the node
def source_range
reset_line_info unless @source_range
@source_range
end
# @return [Range] the line range in {#full_source} represented
# by the node
def line_range
reset_line_info unless @line_range
@line_range
end
# @return [String] the filename the node was parsed from
def file
return parent.file if parent
@file
end
# @return [String] the full source that the node was parsed from
def full_source
return parent.full_source if parent
return @full_source if @full_source
return IO.read(@file) if file && File.exist?(file)
end
# @return [String] the parse of {#full_source} that the node represents
def source
return parent.full_source[source_range] if parent
full_source
end
# List of all known keywords
# @return [Hash]
KEYWORDS = {:class => true, :alias => true, :lambda => true, :do_block => true,
:def => true, :defs => true, :begin => true, :rescue => true, :rescue_mod => true,
:if => true, :if_mod => true, :else => true, :elsif => true, :case => true,
:when => true, :next => true, :break => true, :retry => true, :redo => true,
:return => true, :throw => true, :catch => true, :until => true, :until_mod => true,
:while => true, :while_mod => true, :yield => true, :yield0 => true, :zsuper => true,
:unless => true, :unless_mod => true, :for => true, :super => true, :return0 => true}
# @group Creating an AstNode
# Finds the node subclass that should be instantiated for a specific
# node type
#
# @param [Symbol] type the node type to find a subclass for
# @return [Class] a subclass of AstNode to instantiate the node with.
def self.node_class_for(type)
case type
when :params
ParameterNode
when :call, :fcall, :vcall, :command, :command_call
MethodCallNode
when :if, :elsif, :if_mod, :unless, :unless_mod
ConditionalNode
when :for, :while, :while_mod, :until, :until_mod
LoopNode
when :def, :defs
MethodDefinitionNode
when :class, :sclass
ClassNode
when :module
ModuleNode
else
if type.to_s =~ /_ref\Z/
ReferenceNode
elsif type.to_s =~ /_literal\Z/
LiteralNode
elsif KEYWORDS.key?(type)
KeywordNode
else
AstNode
end
end
end
# Creates a new AST node
#
# @param [Symbol] type the type of node being created
# @param [Array] arr the child nodes
# @param [Hash] opts any extra line options
# @option opts [Fixnum] :line (nil) the line the node starts on in source
# @option opts [String] :char (nil) the character number the node starts on
# in source
# @option opts [Fixnum] :listline (nil) a special key like :line but for
# list nodes
# @option opts [Fixnum] :listchar (nil) a special key like :char but for
# list nodes
# @option opts [Boolean] :token (nil) whether the node represents a token
def initialize(type, arr, opts = {})
super(arr)
self.type = type
self.line_range = opts[:line]
self.source_range = opts[:char]
@fallback_line = opts[:listline]
@fallback_source = opts[:listchar]
@token = true if opts[:token]
@docstring = nil
end
# @return [Boolean] whether the node is equal to another by checking
# the list and type
# @private
def ==(other)
super && type == other.type
end
# @group Traversing a Node
# Searches through the node and all descendants and returns the
# first node with a type matching any of +node_types+, otherwise
# returns the original node (self).
#
# @example Returns the first method definition in a block of code
# ast = YARD.parse_string("if true; def x; end end").ast
# ast.jump(:def)
# # => s(:def, s(:ident, "x"), s(:params, nil, nil, nil, nil,
# # nil), s(s(:void_stmt, )))
# @example Returns first 'def' or 'class' statement
# ast = YARD.parse_string("class X; def y; end end")
# ast.jump(:def, :class).first
# # =>
# @example If the node types are not present in the AST
# ast = YARD.parse("def x; end")
# ast.jump(:def)
#
# @param [Array] node_types a set of node types to match
# @return [AstNode] the matching node, if one was found
# @return [self] if no node was found
def jump(*node_types)
traverse {|child| return(child) if node_types.include?(child.type) }
self
end
# @return [Array] the {AstNode} children inside the node
def children
@children ||= select {|e| AstNode === e }
end
# Traverses the object and yields each node (including descendants) in order.
#
# @yield each descendant node in order
# @yieldparam [AstNode] self, or a child/descendant node
# @return [void]
def traverse
nodes = [self]
nodes.each.with_index do |node, index|
yield node
nodes.insert index + 1, *node.children
end
end
# @group Node Meta Types
# @return [Boolean] whether the node is a token
def token?
@token
end
# @return [Boolean] whether the node is a reference (variable,
# constant name)
def ref?
false
end
# @return [Boolean] whether the node is a literal value
def literal?
false
end
# @return [Boolean] whether the node is a keyword
def kw?
false
end
# @return [Boolean] whether the node is a method call
def call?
false
end
# @return [Boolean] whether the node is a method definition
def def?
false
end
# @return [Boolean] whether the node is a if/elsif/else condition
def condition?
false
end
# @return [Boolean] whether the node is a loop
def loop?
false
end
# @return [Boolean] whether the node has a block
def block?
respond_to?(:block) || condition?
end
# @group Getting Line Information
# @return [Boolean] whether the node has a {#line_range} set
def has_line?
@line_range ? true : false
end
# @return [Fixnum] the starting line number of the node
def line
line_range && line_range.first
end
# @return [String] the first line of source represented by the node.
def first_line
full_source.split(/\r?\n/)[line - 1].strip
end
# @group Printing a Node
# @return [String] the first line of source the node represents
def show
"\t#{line}: #{first_line}"
end
# @return [nil] pretty prints the node
def pretty_print(q)
objs = dup + [:__last__]
objs.unshift(type) if type && type != :list
options = []
options << ['docstring', docstring] if @docstring
if @source_range || @line_range
options << ['line', line_range]
options << ['source', source_range]
end
objs.pop if options.empty?
q.group(3, 's(', ')') do
q.seplist(objs, nil, :each) do |v|
if v == :__last__
q.seplist(options, nil, :each) do |arr|
k, v2 = *arr
q.group(3) do
q.text k
q.group(3) do
q.text ': '
q.pp v2
end
end
end
else
q.pp v
end
end
end
end
# @return [String] inspects the object
def inspect
typeinfo = type && type != :list ? ':' + type.to_s + ', ' : ''
's(' + typeinfo + map(&:inspect).join(", ") + ')'
end
# @group Managing node state
# Resets node state in tree
def unfreeze
@children = nil
end
# @endgroup
private
# Resets line information
# @return [void]
def reset_line_info
if size == 0
self.line_range = @fallback_line
self.source_range = @fallback_source
elsif !children.empty?
f = children.first
l = children.last
self.line_range = Range.new(f.line_range.first, l.line_range.last)
self.source_range = Range.new(f.source_range.first, l.source_range.last)
elsif @fallback_line || @fallback_source
self.line_range = @fallback_line
self.source_range = @fallback_source
else
self.line_range = 0...0
self.source_range = 0...0
end
end
end
class ReferenceNode < AstNode
def ref?; true end
def path
Array.new flatten
end
def namespace
Array.new flatten[0...-1]
end
end
class LiteralNode < AstNode
def literal?; true end
end
class KeywordNode < AstNode
def kw?; true end
end
class ParameterNode < AstNode
def unnamed_required_params
self[0]
end
def unnamed_optional_params
return @unnamed_optional_params if defined?(@unnamed_optional_params)
params = self[1] || []
if self[-3] && self[-3][0] && self[-3][0].type == :unnamed_optional_arg
params += self[-3]
end
@unnamed_optional_params = params.empty? ? nil : params
end
def named_params
return @named_params if defined?(@named_params)
if YARD.ruby2? && self[-3] && self[-3][0] && self[-3][0].type == :named_arg
@named_params = self[-3]
else
@named_params = nil
end
end
def splat_param
self[2] ? self[2][0] : nil
end
def unnamed_end_params
self[3]
end
def double_splat_param
return nil unless YARD.ruby2?
self[-2] if self[-2].is_a?(AstNode) && self[-2].type == :ident
end
def block_param
self[-1] ? self[-1][0] : nil
end
end
class MethodCallNode < AstNode
def call?; true end
def namespace; first if index_adjust > 0 end
def method_name(name_only = false)
name = self[index_adjust]
if name == :call
nil
elsif name_only && Array === name
name.jump(:ident).first.to_sym
else
name
end
end
def parameters(include_block_param = true)
return [] if type == :vcall
params = self[1 + index_adjust]
return [] unless params
params = call_has_paren? ? params.first : params
return [] unless params
include_block_param ? params : params[0...-1]
end
def block_param; parameters.last end
def block
last.type == :do_block || last.type == :brace_block ? last : nil
end
private
def index_adjust
[:call, :command_call].include?(type) ? 2 : 0
end
def call_has_paren?
[:fcall, :call].include?(type)
end
end
class MethodDefinitionNode < AstNode
def kw?; true end
def def?; true end
def namespace; first if index_adjust > 0 end
def method_name(name_only = false)
name = self[index_adjust]
name_only ? name.jump(:ident).first.to_sym : name
end
def parameters(include_block_param = true)
params = self[1 + index_adjust]
params = params[0] if params.type == :paren
include_block_param ? params : params[0...-1]
end
alias block last
private
def index_adjust
type == :defs ? 2 : 0
end
end
class ConditionalNode < KeywordNode
def condition?; true end
def condition; first end
def then_block; self[1] end
def else_block
return unless self[2] && !cmod?
self[2].type == :elsif ? self[2] : self[2][0]
end
private
def cmod?; type =~ /_mod$/ end
end
class ClassNode < KeywordNode
def class_name; first end
def superclass; type == :sclass ? nil : self[1] end
def block; last end
end
class ModuleNode < KeywordNode
def module_name; first end
def block; last end
end
class LoopNode < KeywordNode
def loop?; true end
def condition; type == :for ? s(self[0], self[1]) : first end
def block; last end
end
# Represents a lone comment block in source
class CommentNode < AstNode
def docstring; first end
def docstring=(value) end
alias comments docstring
def source; "" end
def first_line; "" end
end
end
end
end
yard-0.9.7/lib/yard/i18n/ 0000755 0000041 0000041 00000000000 13035234564 015007 5 ustar www-data www-data yard-0.9.7/lib/yard/i18n/text.rb 0000644 0000041 0000041 00000012464 13035234564 016327 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module I18n
# Provides some convenient features for translating a text.
class Text
# Creates a text object that has translation related features for
# the input text.
#
# @param [#each_line] input a text to be translated.
# @option options [Boolean] :have_header (false) whether the
# input text has header or not.
def initialize(input, options = {})
@input = input
@options = options
end
# Extracts translation target messages from +@input+.
#
# @yield [:attribute, name, value, line_no] the block that
# recieves extracted an attribute in header. It may called many
# times.
# @yieldparam [String] name the name of extracted attribute.
# @yieldparam [String] value the value of extracted attribute.
# @yieldparam [Integer] line_no the defined line number of extracted
# attribute.
# @yield [:paragraph, text, start_line_no] the block that
# recieves extracted a paragraph in body. Paragraph is a text
# block separated by one or more empty lines. Empty line is a
# line that contains only zero or more whitespaces. It may
# called many times.
# @yieldparam [String] text the text of extracted paragraph.
# @yieldparam [Integer] start_line_no the start line number of
# extracted paragraph.
# @return [void]
def extract_messages
parse do |part|
case part[:type]
when :markup, :empty_line
# ignore
when :attribute
yield(:attribute, part[:name], part[:value], part[:line_no])
when :paragraph
yield(:paragraph, part[:paragraph], part[:line_no])
end
end
end
# Translates into +locale+.
#
# @param [Locale] locale the translation target locale.
# @return [String] translated text.
def translate(locale)
translated_text = String.new("")
parse do |part|
case part[:type]
when :markup
translated_text << part[:line]
when :attribute
prefix = "#{part[:prefix]}#{part[:name]}#{part[:infix]}"
value = locale.translate(part[:value])
suffix = part[:suffix]
translated_text << "#{prefix}#{value}#{suffix}"
when :paragraph
translated_text << locale.translate(part[:paragraph])
when :empty_line
translated_text << part[:line]
else
raise "should not reach here: unexpected type: #{type}"
end
end
translated_text
end
private
def parse(&block)
paragraph = String.new("")
paragraph_start_line = 0
line_no = 0
in_header = @options[:have_header]
@input.each_line do |line|
line_no += 1
if in_header
case line
when /^#!\S+\s*$/
if line_no == 1
emit_markup_event(line, line_no, &block)
else
in_header = false
end
when /^(\s*#\s*@)(\S+)(\s*)(.+?)(\s*)$/
emit_attribute_event(Regexp.last_match, line_no, &block)
else
in_header = false
if line.strip.empty?
emit_empty_line_event(line, line_no, &block)
next
end
end
next if in_header
end
case line
when /^\s*$/
if paragraph.empty?
emit_empty_line_event(line, line_no, &block)
else
paragraph << line
emit_paragraph_event(paragraph, paragraph_start_line, line_no,
&block)
paragraph = String.new("")
end
else
paragraph_start_line = line_no if paragraph.empty?
paragraph << line
end
end
unless paragraph.empty?
emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
end
end
def emit_markup_event(line, line_no)
part = {
:type => :markup,
:line => line,
:line_no => line_no
}
yield(part)
end
def emit_attribute_event(match_data, line_no)
part = {
:type => :attribute,
:prefix => match_data[1],
:name => match_data[2],
:infix => match_data[3],
:value => match_data[4],
:suffix => match_data[5],
:line_no => line_no
}
yield(part)
end
def emit_empty_line_event(line, line_no)
part = {
:type => :empty_line,
:line => line,
:line_no => line_no
}
yield(part)
end
def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
paragraph_part = {
:type => :paragraph,
:line_no => paragraph_start_line
}
match_data = /(\s*)\z/.match(paragraph)
if match_data
paragraph_part[:paragraph] = match_data.pre_match
yield(paragraph_part)
emit_empty_line_event(match_data[1], line_no, &block)
else
paragraph_part[:paragraph] = paragraph
yield(paragraph_part)
end
end
end
end
end
yard-0.9.7/lib/yard/i18n/message.rb 0000644 0000041 0000041 00000003260 13035234564 016761 0 ustar www-data www-data # frozen_string_literal: true
require "set"
module YARD
module I18n
# +Message+ is a translation target message. It has message ID as
# {#id} and some properties {#locations} and {#comments}.
#
# @since 0.8.1
class Message
# @return [String] the message ID of the trnslation target message.
attr_reader :id
# @return [Set] the set of locations. Location is an array of
# path and line number where the message is appeared.
attr_reader :locations
# @return [Set] the set of comments for the messages.
attr_reader :comments
# Creates a trasnlate target message for message ID +id+.
#
# @param [String] id the message ID of the translate target message.
def initialize(id)
@id = id
@locations = Set.new
@comments = Set.new
end
# Adds location information for the message.
#
# @param [String] path the path where the message appears.
# @param [Integer] line the line number where the message appears.
# @return [void]
def add_location(path, line)
@locations << [path, line]
end
# Adds a comment for the message.
#
# @param [String] comment the comment for the message to be added.
# @return [void]
def add_comment(comment)
@comments << comment unless comment.nil?
end
# @param [Message] other the +Message+ to be compared.
# @return [Boolean] checks whether this message is equal to another.
def ==(other)
other.is_a?(self.class) &&
@id == other.id &&
@locations == other.locations &&
@comments == other.comments
end
end
end
end
yard-0.9.7/lib/yard/i18n/pot_generator.rb 0000644 0000041 0000041 00000023057 13035234564 020213 0 ustar www-data www-data # frozen_string_literal: true
require "stringio"
module YARD
module I18n
# The +PotGenerator+ generates POT format string from
# {CodeObjects::Base} and {CodeObjects::ExtraFileObject}.
#
# == POT and PO
#
# POT is an acronym for "Portable Object Template". POT is a
# template file to create PO file. The extension for POT is
# ".pot". PO file is an acronym for "Portable Object". PO file has
# many parts of message ID (msgid) that is translation target
# message and message string (msgstr) that is translated message
# of message ID. If you want to tranlsate "Hello" in English into
# "Bonjour" in French, "Hello" is the msgid ID and "Bonjour" is
# msgstr. The extension for PO is ".po".
#
# == How to extract msgids
#
# The +PotGenerator+ has two parse methods:
#
# * {#parse_objects} for {CodeObjects::Base}
# * {#parse_files} for {CodeObjects::ExtraFileObject}
#
# {#parse_objects} extracts msgids from docstring and tags of
# {CodeObjects::Base} objects. The docstring of
# {CodeObjects::Base} object is parsed and a paragraph is
# extracted as a msgid. Tag name and tag text are extracted as
# msgids from a tag.
#
# {#parse_files} extracts msgids from
# {CodeObjects::ExtraFileObject} objects. The file content of
# {CodeObjects::ExtraFileObject} object is parsed and a paragraph
# is extracted as a msgid.
#
# == Usage
#
# To create a .pot file by +PotGenerator+, instantiate a
# +PotGenerator+ with a relative working directory path from a
# directory path that has created .pot file, parse
# {CodeObjects::Base} objects and {CodeObjects::ExtraFileObject}
# objects, generate a POT and write the generated POT to a .pot
# file. The relative working directory path is ".." when the
# working directory path is "." and the POT is wrote into
# "po/yard.pot".
#
# @example Generate a .pot file
# po_file_path = "po/yard.pot"
# po_file_directory_pathname = Pathname.new(po_file_path).directory)
# working_directory_pathname = Pathname.new(".")
# relative_base_path = working_directory_pathname.relative_path_from(po_file_directory_pathname).to_s
# # relative_base_path -> ".."
# generator = YARD::I18n::PotGenerator.new(relative_base_path)
# generator.parse_objects(objects)
# generator.parse_files(files)
# pot = generator.generate
# po_file_directory_pathname.mkpath
# File.open(po_file_path, "w") do |pot_file|
# pot_file.print(pot)
# end
# @see http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
# GNU gettext manual about details of PO file
class PotGenerator
# Extracted messages.
#
# @return [Messages]
# @since 0.8.1
attr_reader :messages
# Creates a POT generator that uses +relative_base_path+ to
# generate locations for a msgid. +relative_base_path+ is
# prepended to all locations.
#
# @param [String] relative_base_path a relative working
# directory path from a directory path that has created .pot
# file.
def initialize(relative_base_path)
@relative_base_path = relative_base_path
@extracted_objects = {}
@messages = Messages.new
end
# Parses {CodeObjects::Base} objects and stores extracted msgids
# into {#messages}
#
# @param [Array] objects a list of
# {CodeObjects::Base} to be parsed.
# @return [void]
def parse_objects(objects)
objects.each do |object|
extract_documents(object)
end
end
# Parses {CodeObjects::ExtraFileObject} objects and stores
# extracted msgids into {#messages}.
#
# @param [Array] files a list
# of {CodeObjects::ExtraFileObject} objects to be parsed.
# @return [void]
def parse_files(files)
files.each do |file|
extract_paragraphs(file)
end
end
# Generates POT from +@messages+.
#
# One PO file entry is generated from a +Message+ in
# +@messages+.
#
# Locations of the +Message+ are used to generate the reference
# line that is started with "#: ". +relative_base_path+ passed
# when the generater is created is prepended to each path in location.
#
# Comments of the +Message+ are used to generate the
# translater-comment line that is started with "# ".
#
# @return [String] POT format string
def generate
pot = String.new(header)
sorted_messages = @messages.sort_by do |message|
sorted_locations = message.locations.sort
sorted_locations.first || []
end
sorted_messages.each do |message|
generate_message(pot, message)
end
pot
end
private
def header
<<-EOH
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR , YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\\n"
"Report-Msgid-Bugs-To: \\n"
"POT-Creation-Date: #{generate_pot_creation_date_value}\\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
"Last-Translator: FULL NAME \\n"
"Language-Team: LANGUAGE \\n"
"Language: \\n"
"MIME-Version: 1.0\\n"
"Content-Type: text/plain; charset=UTF-8\\n"
"Content-Transfer-Encoding: 8bit\\n"
EOH
end
def current_time
@current_time ||= Time.now
end
def generate_pot_creation_date_value
current_time.strftime("%Y-%m-%d %H:%M%z")
end
def generate_message(pot, message)
message.comments.sort.each do |comment|
pot << "# #{comment}\n" unless comment.empty?
end
message.locations.sort.each do |path, line|
pot << "#: #{@relative_base_path}/#{path}:#{line}\n"
end
escaped_message_id = escape_message_id(message.id)
escaped_message_id = escaped_message_id.gsub(/\n/, "\\\\n\"\n\"")
pot << "msgid \"#{escaped_message_id}\"\n"
pot << "msgstr \"\"\n"
pot << "\n"
pot
end
def escape_message_id(message_id)
message_id.gsub(/(\\|")/) do
special_character = $1
"\\#{special_character}"
end
end
def register_message(id)
@messages.register(id)
end
def extract_documents(object)
return if @extracted_objects.key?(object)
@extracted_objects[object] = true
case object
when CodeObjects::NamespaceObject
object.children.each do |child|
extract_documents(child)
end
end
if object.group
message = register_message(object.group)
object.files.each do |path, line|
message.add_location(path, line)
end
message.add_comment(object.path) unless object.path.empty?
end
docstring = object.docstring
unless docstring.empty?
text = Text.new(StringIO.new(docstring))
text.extract_messages do |type, *args|
case type
when :paragraph
paragraph, line_no = *args
message = register_message(paragraph.rstrip)
object.files.each do |path, line|
message.add_location(path, (docstring.line || line) + line_no)
end
message.add_comment(object.path) unless object.path.empty?
else
raise "should not reach here: unexpected type: #{type}"
end
end
end
docstring.tags.each do |tag|
extract_tag_documents(tag)
end
end
def extract_tag_documents(tag)
extract_tag_name(tag)
extract_tag_text(tag)
extract_documents(tag) if Tags::OverloadTag === tag
end
def extract_tag_name(tag)
return if tag.name.nil?
return if tag.name.is_a?(String) && tag.name.empty?
key = "tag|#{tag.tag_name}|#{tag.name}"
message = register_message(key)
tag.object.files.each do |path, line|
message.add_location(path, line)
end
tag_label = String.new("@#{tag.tag_name}")
tag_label << " [#{tag.types.join(', ')}]" if tag.types
message.add_comment(tag_label)
end
def extract_tag_text(tag)
return if tag.text.nil?
return if tag.text.empty?
message = register_message(tag.text)
tag.object.files.each do |path, line|
message.add_location(path, line)
end
tag_label = String.new("@#{tag.tag_name}")
tag_label << " [#{tag.types.join(', ')}]" if tag.types
tag_label << " #{tag.name}" if tag.name
message.add_comment(tag_label)
end
def extract_paragraphs(file)
File.open(file.filename) do |input|
text = Text.new(input, :have_header => true)
text.extract_messages do |type, *args|
case type
when :attribute
name, value, line_no = *args
message = register_message(value)
message.add_location(file.filename, line_no)
message.add_comment(name)
when :paragraph
paragraph, line_no = *args
message = register_message(paragraph.rstrip)
message.add_location(file.filename, line_no)
else
raise "should not reach here: unexpected type: #{type}"
end
end
end
end
end
end
end
yard-0.9.7/lib/yard/i18n/messages.rb 0000644 0000041 0000041 00000003047 13035234564 017147 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module I18n
# Acts as a container for {Message} objects.
#
# @since 0.8.1
class Messages
include Enumerable
# Creates a new container.
def initialize
@messages = {}
end
# Enumerates each {Message} in the container.
#
# @yieldparam [Message] message the next message object in
# the enumeration.
# @return [void]
def each(&block)
@messages.each_value(&block)
end
# @param [String] id the message ID to perform a lookup on.
# @return [Message, nil] a registered message for the given +id+,
# or nil if no message for the ID is found.
def [](id)
@messages[id]
end
# Registers a {Message}, the mssage ID of which is +id+. If
# corresponding +Message+ is already registered, the previously
# registered object is returned.
#
# @param [String] id the ID of the message to be registered.
# @return [Message] the registered +Message+.
def register(id)
@messages[id] ||= Message.new(id)
end
# Checks if this messages list is equal to another messages list.
#
# @param [Messages] other the container to compare.
# @return [Boolean] whether +self+ and +other+ is equivalence or not.
def ==(other)
other.is_a?(self.class) &&
@messages == other.messages
end
protected
# @return [Hash{String=>Message}] the set of message objects
attr_reader :messages
end
end
end
yard-0.9.7/lib/yard/i18n/locale.rb 0000644 0000041 0000041 00000003460 13035234564 016576 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module I18n
# +Locale+ is a unit of translation. It has {#name} and a set of
# messages.
#
# @since 0.8.2
class Locale
class << self
# @return [String, nil] the default locale name.
# @since 0.8.4
attr_accessor :default
undef default
def default
@@default ||= nil
end
undef default=
def default=(locale)
@@default = locale
end
end
# @return [String] the name of the locale. It used IETF language
# tag format +[language[_territory][.codeset][@modifier]]+.
# @see http://tools.ietf.org/rfc/bcp/bcp47.txt
# BCP 47 - Tags for Identifying Languages
attr_reader :name
# Creates a locale for +name+ locale.
#
# @param [String] name the locale name.
def initialize(name)
@name = name
@messages = {}
end
# Loads translation messages from +locale_directory+/{#name}.po.
#
# @param [String] locale_directory the directory path that has
# {#name}.po.
# @return [Boolean] +true+ if PO file exists, +false+ otherwise.
def load(locale_directory)
return false if @name.nil?
po_file = File.join(locale_directory, "#{@name}.po")
return false unless File.exist?(po_file)
require "yard/i18n/po_parser"
return false unless POParser.available?
po_parser = POParser.new
@messages.merge!(po_parser.parse(po_file))
true
end
# @param [String] message the translation target message.
# @return [String] translated message. If tarnslation isn't
# registered, the +message+ is returned.
def translate(message)
@messages[message] || message
end
end
end
end
yard-0.9.7/lib/yard/i18n/po_parser.rb 0000644 0000041 0000041 00000003212 13035234564 017324 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module I18n
# +Locale+ is a wrapper for gettext's PO parsing feature. It hides
# gettext API difference from YARD.
#
# @since 0.8.8
class POParser
if RUBY_VERSION < "1.9"
begin
require "gettext/tools/poparser"
require "gettext/runtime/mofile"
@@gettext_version = 2
rescue LoadError
log.warn "Need gettext gem 2.x for i18n feature:\n" \
"\tgem install gettext -v 2.3.9"
end
else
begin
require "gettext/po_parser"
require "gettext/mo"
@@gettext_version = 3
rescue LoadError
begin
require "gettext/tools/poparser"
require "gettext/runtime/mofile"
@@gettext_version = 2
rescue LoadError
log.warn "Need gettext gem for i18n feature:\n" \
"\tgem install gettext"
end
end
end
class << self
# @return [Boolean] true if gettext is available, false otherwise.
def available?
!@@gettext_version.nil?
end
end
# Parses PO file.
#
# @param [String] file path of PO file to be parsed.
# @return [Hash] parsed messages.
def parse(file)
case @@gettext_version
when 2
parser = GetText::PoParser.new
data = GetText::MoFile.new
when 3
parser = GetText::POParser.new
data = GetText::MO.new
end
parser.report_warning = false
parser.parse_file(file, data)
data
end
end
end
end
yard-0.9.7/lib/yard/logging.rb 0000644 0000041 0000041 00000013430 13035234564 016204 0 ustar www-data www-data # frozen_string_literal: true
require 'logger'
require 'thread'
module YARD
# Handles console logging for info, warnings and errors.
# Uses the stdlib Logger class in Ruby for all the backend logic.
class Logger < ::Logger
# The list of characters displayed beside the progress bar to indicate
# "movement".
# @since 0.8.2
PROGRESS_INDICATORS = ["\u230C", "\u230D", "\u230E", "\u230F"]
# @return [IO] the IO object being logged to
# @since 0.8.2
def io; @logdev end
def io=(pipe) @logdev = pipe end
# @return [Boolean] whether backtraces should be shown (by default
# this is on).
def show_backtraces; @show_backtraces || level == DEBUG end
attr_writer :show_backtraces
# @return [Boolean] whether progress indicators should be shown when
# logging CLIs (by default this is off).
def show_progress
return false if YARD.ruby18? # threading is too ineffective for progress support
return false if YARD.windows? # windows has poor ANSI support
return false unless io.tty? # no TTY support on IO
return false unless level > INFO # no progress in verbose/debug modes
@show_progress
end
attr_writer :show_progress
# The logger instance
# @return [Logger] the logger instance
def self.instance(pipe = STDOUT)
@logger ||= new(pipe)
end
# Creates a new logger
def initialize(pipe, *args)
super(pipe, *args)
self.io = pipe
self.show_backtraces = true
self.show_progress = false
self.level = WARN
self.formatter = method(:format_log)
@progress_indicator = 0
@mutex = Mutex.new
@progress_msg = nil
end
# Changes the debug level to DEBUG if $DEBUG is set
# and writes a debugging message.
def debug(*args)
self.level = DEBUG if $DEBUG
super
end
# Captures the duration of a block of code for benchmark analysis. Also
# calls {#progress} on the message to display it to the user.
#
# @todo Implement capture storage for reporting of benchmarks
# @param [String] msg the message to display
# @param [Symbol, nil] nontty_log the level to log as if the output
# stream is not a TTY. Use +nil+ for no alternate logging.
# @yield a block of arbitrary code to benchmark
# @return [void]
def capture(msg, nontty_log = :debug)
progress(msg, nontty_log)
yield
ensure
clear_progress
end
# Displays a progress indicator for a given message. This progress report
# is only displayed on TTY displays, otherwise the message is passed to
# the +nontty_log+ level.
#
# @param [String] msg the message to log
# @param [Symbol, nil] nontty_log the level to log as if the output
# stream is not a TTY. Use +nil+ for no alternate logging.
# @return [void]
# @since 0.8.2
def progress(msg, nontty_log = :debug)
send(nontty_log, msg) if nontty_log
return unless show_progress
icon = ""
if defined?(::Encoding)
icon = PROGRESS_INDICATORS[@progress_indicator] + " "
end
@mutex.synchronize do
print("\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r")
@progress_msg = msg
@progress_indicator += 1
@progress_indicator %= PROGRESS_INDICATORS.size
end
Thread.new do
sleep(0.05)
progress(msg + ".", nil) if @progress_msg == msg
end
end
# Clears the progress indicator in the TTY display.
# @return [void]
# @since 0.8.2
def clear_progress
return unless show_progress
print_no_newline("\e[?25h\e[2K")
@progress_msg = nil
end
# Displays an unformatted line to the logger output stream, adding
# a newline.
# @param [String] msg the message to display
# @return [void]
# @since 0.8.2
def puts(msg = '')
print("#{msg}\n")
end
alias print_no_newline <<
private :print_no_newline
# Displays an unformatted line to the logger output stream.
# @param [String] msg the message to display
# @return [void]
# @since 0.8.2
def print(msg = '')
clear_line
print_no_newline(msg)
end
alias << print
# Prints the backtrace +exc+ to the logger as error data.
#
# @param [Array] exc the backtrace list
# @param [Symbol] level_meth the level to log backtrace at
# @return [void]
def backtrace(exc, level_meth = :error)
return unless show_backtraces
send(level_meth, "#{exc.class.class_name}: #{exc.message}")
send(level_meth, "Stack trace:" +
exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n")
end
# Warns that the Ruby environment does not support continuations. Applies
# to JRuby, Rubinius and MacRuby. This warning will only display once
# per Ruby process.
#
# @deprecated Continuations are no longer needed by YARD 0.8.0+.
# @return [void]
def warn_no_continuations
end
# Sets the logger level for the duration of the block
#
# @example
# log.enter_level(Logger::ERROR) do
# YARD.parse_string "def x; end"
# end
# @param [Fixnum] new_level the logger level for the duration of the block.
# values can be found in Ruby's Logger class.
# @yield the block with the logger temporarily set to +new_level+
def enter_level(new_level = level)
old_level = level
self.level = new_level
yield
ensure
self.level = old_level
end
private
# Override this internal Logger method to clear line
def add(*args)
clear_line
super(*args)
end
def clear_line
return unless @progress_msg
print_no_newline("\e[2K\r")
end
# Log format (from Logger implementation). Used by Logger internally
def format_log(sev, _time, _prog, msg)
"[#{sev.downcase}]: #{msg}\n"
end
end
end
yard-0.9.7/lib/yard/version.rb 0000644 0000041 0000041 00000000102 13035234564 016233 0 ustar www-data www-data # frozen_string_literal: true
module YARD
VERSION = '0.9.7'
end
yard-0.9.7/lib/yard/serializers/ 0000755 0000041 0000041 00000000000 13035234564 016564 5 ustar www-data www-data yard-0.9.7/lib/yard/serializers/process_serializer.rb 0000644 0000041 0000041 00000001321 13035234564 023015 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Serializers
# Serializes an object to a process (like less)
#
# @example Serializing to a pager (less)
# serializer = ProcessSerializer.new('less')
# serializer.serialize(object, "data!")
class ProcessSerializer < Base
# Creates a new ProcessSerializer for the shell command +cmd+
#
# @param [String] cmd the command that will accept data on stdin
def initialize(cmd)
@cmd = cmd
end
# Overrides serialize behaviour and writes data to standard input
# of the associated command
def serialize(_object, data)
IO.popen(@cmd, 'w') {|io| io.write(data) }
end
end
end
end
yard-0.9.7/lib/yard/serializers/yardoc_serializer.rb 0000644 0000041 0000041 00000010477 13035234564 022634 0 ustar www-data www-data # frozen_string_literal: true
module YARD
# Stubs marshal dumps and acts a delegate class for an object by path
#
# @private
class StubProxy
instance_methods.each {|m| undef_method(m) unless m.to_s =~ /^__|^object_id$/ }
def _dump(_depth) @path end
def self._load(str) new(str) end
def hash; @path.hash end
def initialize(path, transient = false)
@path = path
@transient = transient
end
def method_missing(meth, *args, &block)
return true if meth == :respond_to? && args.first == :_dump
@object = nil if @transient
@object ||= Registry.at(@path)
@object.send(meth, *args, &block)
rescue NoMethodError => e
e.backtrace.delete_if {|l| l[0, FILELEN] == __FILE__ }
raise
end
FILELEN = __FILE__.size
end
module Serializers
class YardocSerializer < FileSystemSerializer
def initialize(yfile)
super(:basepath => yfile, :extension => 'dat')
end
def objects_path; File.join(basepath, 'objects') end
# @deprecated The registry no longer tracks proxy types
def proxy_types_path; File.join(basepath, 'proxy_types') end
def checksums_path; File.join(basepath, 'checksums') end
def object_types_path; File.join(basepath, 'object_types') end
def complete_lock_path; File.join(basepath, 'complete') end
def processing_path; File.join(basepath, 'processing') end
def complete?
File.exist?(complete_lock_path) && !locked_for_writing?
end
# Creates a pessmistic transactional lock on the database for writing.
# Use with {YARD.parse} to ensure the database is not written multiple
# times.
#
# @see #locked_for_writing?
def lock_for_writing
File.open!(processing_path, 'w') {}
yield
ensure
File.unlink(processing_path) if File.exist?(processing_path)
end
# @return [Boolean] whether the database is currently locked for writing
def locked_for_writing?
File.exist?(processing_path)
end
def serialized_path(object)
path =
case object
when String, Symbol
object = object.to_s
if object =~ /#/
object += '_i'
elsif object =~ /\./
object += '_c'
end
object.split(/::|\.|#/).map do |p|
p.gsub(/[^\w\.-]/) do |x|
encoded = '_'
x.each_byte {|b| encoded << ("%X" % b) }
encoded
end
end.join('/') + '.' + extension
when YARD::CodeObjects::RootObject
'root.dat'
else
super(object)
end
File.join('objects', path)
end
def serialize(object)
if Hash === object
super(object[:root], dump(object)) if object[:root]
else
super(object, dump(object))
end
end
def deserialize(path, is_path = false)
path = File.join(basepath, serialized_path(path)) unless is_path
if File.file?(path)
log.debug "Deserializing #{path}..."
Marshal.load(File.read_binary(path))
else
log.debug "Could not find #{path}"
nil
end
end
private
def dump(object)
object = internal_dump(object, true) unless object.is_a?(Hash)
Marshal.dump(object)
end
def internal_dump(object, first_object = false)
if !first_object && object.is_a?(CodeObjects::Base) &&
!(Tags::OverloadTag === object)
return StubProxy.new(object.path)
end
if object.is_a?(Hash) || object.is_a?(Array) ||
object.is_a?(CodeObjects::Base) ||
!object.instance_variables.empty?
object = object.dup
end
object.instance_variables.each do |ivar|
ivar_obj = object.instance_variable_get(ivar)
ivar_obj_dump = internal_dump(ivar_obj)
object.instance_variable_set(ivar, ivar_obj_dump)
end
case object
when Hash
list = object.map do |k, v|
[k, v].map {|item| internal_dump(item) }
end
object.replace(Hash[list])
when Array
list = object.map {|item| internal_dump(item) }
object.replace(list)
end
object
end
end
end
end
yard-0.9.7/lib/yard/serializers/file_system_serializer.rb 0000644 0000041 0000041 00000010776 13035234564 023700 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Serializers
# Implements a serializer that reads from and writes to the filesystem.
class FileSystemSerializer < Base
# The base path to write data to.
# @return [String] a base path
attr_reader :basepath
def basepath=(value)
@basepath = options[:basepath] = value
end
# The extension of the filename (defaults to +html+)
#
# @return [String] the extension of the file. Empty string for no extension.
attr_reader :extension
def extension=(value)
@extension = options[:extension] = value
end
# Creates a new FileSystemSerializer with options
#
# @option opts [String] :basepath ('doc') the base path to write data to
# @option opts [String] :extension ('html') the extension of the serialized
# path filename. If this is set to the empty string, no extension is used.
def initialize(opts = {})
super
@name_map = nil
@basepath = (options[:basepath] || 'doc').to_s
@extension = (options.key?(:extension) ? options[:extension] : 'html').to_s
end
# Serializes object with data to its serialized path (prefixed by the +#basepath+).
#
# @return [String] the written data (for chaining)
def serialize(object, data)
path = File.join(basepath, serialized_path(object))
log.debug "Serializing to #{path}"
File.open!(path, "wb") {|f| f.write data }
end
# Implements the serialized path of a code object.
#
# @param [CodeObjects::Base, CodeObjects::ExtraFileObject, String] object
# the object to get a path for. The path of a string is the string itself.
# @return [String] if object is a String, returns
# object, otherwise the path on disk (without the basepath).
def serialized_path(object)
return object if object.is_a?(String)
if object.is_a?(CodeObjects::ExtraFileObject)
fspath = ['file.' + object.name + (extension.empty? ? '' : ".#{extension}")]
else
objname = object != YARD::Registry.root ? mapped_name(object) : "top-level-namespace"
objname += '_' + object.scope.to_s[0, 1] if object.is_a?(CodeObjects::MethodObject)
fspath = [objname + (extension.empty? ? '' : ".#{extension}")]
if object.namespace && object.namespace.path != ""
fspath.unshift(*object.namespace.path.split(CodeObjects::NSEP))
end
end
File.join(encode_path_components(*fspath))
end
# Checks the disk for an object and returns whether it was serialized.
#
# @param [CodeObjects::Base] object the object to check
# @return [Boolean] whether an object has been serialized to disk
def exists?(object)
File.exist?(File.join(basepath, serialized_path(object)))
end
private
# Builds a filename mapping from object paths to filesystem path names.
# Needed to handle case sensitive YARD objects mapped into a case
# insensitive filesystem. Uses with {#mapped_name} to determine the
# mapping name for a given object.
#
# @note In order to use filesystem name mapping, you must initialize
# the serializer object after preparing the {YARD::Registry}.
def build_filename_map
@name_map = {}
YARD::Registry.all.each do |object|
lpath = nil
if object.parent && object.parent.type != :root
lpath = object.parent.path + "::" + object.name.to_s.downcase
else
lpath = object.path.downcase
end
@name_map[lpath] ||= {}
size = @name_map[lpath].size
name = "#{object.name}#{size > 0 ? "_" * size : ""}"
@name_map[lpath][object.name] = name
end
end
# @return [String] the filesystem mapped name of a given object.
def mapped_name(object)
build_filename_map unless @name_map
map = @name_map[object.path.downcase]
map && map[object.name] ? map[object.name] : object.name.to_s
end
# Remove special chars from filenames.
# Windows disallows \ / : * ? " < > | but we will just remove any
# non alphanumeric (plus period, underscore and dash).
def encode_path_components(*components)
components.map! do |p|
p.gsub(/[^\w\.-]/) do |x|
encoded = String.new('_')
x.each_byte {|b| encoded << ("%X" % b) }
encoded
end
end
end
end
end
end
yard-0.9.7/lib/yard/serializers/base.rb 0000644 0000041 0000041 00000006152 13035234564 020027 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Serializers
# The abstract base serializer. Serializers allow templates to be
# rendered to various endpoints. For instance, a {FileSystemSerializer}
# would allow template contents to be written to the filesystem
#
# To implement a custom serializer, override the following methods:
# * {#serialize}
# * {#serialized_path}
#
# Optionally, a serializer can implement before and after filters:
# * {#before_serialize}
# * {#after_serialize}
#
# @abstract Override this class to implement a custom serializer.
class Base
# All serializer options are saved so they can be passed to other serializers.
#
# @return [SymbolHash] the serializer options
attr_reader :options
# @group Creating a New Serializer
# Creates a new serializer with options
#
# @param [Hash] opts the options to assign to {#options}
def initialize(opts = {})
@options = SymbolHash.new(false).update(opts)
end
# @group Serializing an Object
# Serializes an object.
#
# @abstract This method should implement the logic that serializes
# +data+ to the respective endpoint. This method should also call
# the before and after callbacks {#before_serialize} and {#after_serialize}
# @param [CodeObjects::Base, String] object the object to serialize the
# data for. The object can also be a string (for non-object serialization)
# @param [String] data the contents that should be serialized
def serialize(object, data) end
# The serialized path of an object
#
# @abstract This method should return the path of the object on the
# endpoint. For instance, for a file serializer, this should return
# the filename that represents the object on disk.
# @param [CodeObjects::Base] object the object to return a path for
# @return [String] the serialized path of an object
def serialized_path(object) end
# Returns whether an object has been serialized
#
# @abstract This method should return whether the endpoint already exists.
# For instance, a file system serializer would check if the file exists
# on disk. You will most likely use +#basepath+ and {#serialized_path} to
# get the endpoint's location.
# @param [CodeObjects::Base] object the object to check existence of
# @return [Boolean] whether the endpoint exists.
# @since 0.6.0
def exists?(object) # rubocop:disable Lint/UnusedMethodArgument
false
end
# @group Callbacks
# Called before serialization.
#
# @abstract Should run code before serialization. Should return false
# if serialization should not occur.
# @return [Boolean] whether or not serialization should occur
def before_serialize; end
# Called after serialization.
#
# @abstract Should run code after serialization.
# @param [String] data the data that was serialized.
# @return [void]
def after_serialize(data); end
end
end
end
yard-0.9.7/lib/yard/serializers/stdout_serializer.rb 0000644 0000041 0000041 00000002027 13035234564 022665 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module Serializers
# A serializer that writes data to standard output.
class StdoutSerializer < Base
# Creates a serializer to print text to stdout
#
# @param [Fixnum, nil] wrap if wrap is a number, wraps text to +wrap+
# columns, otherwise no wrapping is done.
def initialize(wrap = nil)
@wrap = wrap
end
# Overrides serialize behaviour to write data to standard output
def serialize(_object, data)
print(@wrap ? word_wrap(data, @wrap) : data)
end
private
# Wraps text to a specific column length
#
# @param [String] text the text to wrap
# @param [Fixnum] _length the column length to wrap to
# @return [String] the wrapped text
def word_wrap(text, _length = 80)
# See ruby-talk/10655 / Ernest Ellingson
text.gsub(/\t/, " ").gsub(/.{1,50}(?:\s|\Z)/) do
($& + 5.chr).gsub(/\n\005/, "\n").gsub(/\005/, "\n")
end
end
end
end
end
yard-0.9.7/lib/yard/globals.rb 0000644 0000041 0000041 00000001050 13035234564 016174 0 ustar www-data www-data # frozen_string_literal: true
# @group Global Convenience Methods
# Shortcut for creating a YARD::CodeObjects::Proxy via a path
#
# @see YARD::CodeObjects::Proxy
# @see YARD::Registry.resolve
def P(namespace, name = nil, type = nil) # rubocop:disable Style/MethodName
if name.nil?
name = namespace
namespace = nil
end
YARD::Registry.resolve(namespace, name, false, true, type)
end
# The global {YARD::Logger} instance
#
# @return [YARD::Logger] the global {YARD::Logger} instance
# @see YARD::Logger
def log
YARD::Logger.instance
end
yard-0.9.7/lib/yard/config.rb 0000644 0000041 0000041 00000022443 13035234564 016027 0 ustar www-data www-data # frozen_string_literal: true
module YARD
# This class maintains all system-wide configuration for YARD and handles
# the loading of plugins. To access options call {options}, and to load
# a plugin use {load_plugin}. All other public methods are used by YARD
# during load time.
#
# == User Configuration Files
#
# Persistent user configuration files can be stored in the file
# +~/.yard/config+, which is read when YARD first loads. The file should
# be formatted as YAML, and should contain a map of keys and values.
#
# Although you can specify any key-value mapping in the configuration file,
# YARD defines special keys specified in {DEFAULT_CONFIG_OPTIONS}.
#
# An example of a configuration file is listed below:
#
# !!!yaml
# load_plugins: true # Auto-load plugins when YARD starts
# ignored_plugins:
# - yard-broken
# - broken2 # yard- prefix not necessary
# autoload_plugins:
# - yard-rspec
#
# == Automatic Loading of Plugins
#
# YARD 0.6.2 will no longer automatically load all plugins by default. This
# option can be reset by setting 'load_plugins' to true in the configuration
# file. In addition, you can specify a set of specific plugins to load on
# load through the 'autoload_plugins' list setting. This setting is
# independent of the 'load_plugins' value and will always be processed.
#
# == Ignored Plugins File
#
# YARD 0.5 and below used a +~/.yard/ignored_plugins+ file to specify
# plugins to be ignored at load time. Ignored plugins in 0.6.2 and above
# should now be specified in the main configuration file, though YARD
# will support the +ignored_plugins+ file until 0.7.x.
#
# == Safe Mode
#
# YARD supports running in safe-mode. By doing this, it will avoid executing
# any user code such as require files or queries. Plugins will still be
# loaded with safe mode on, because plugins are properly namespaced with
# a 'yard-' prefix, must be installed as a gem, and therefore cannot be
# touched by the user. To specify safe mode, use the +safe_mode+ key.
#
# == Plugin Specific Configuration
#
# Additional settings can be defined within the configuration file
# specifically to provide configuration for a plugin. A plugin that utilizes
# the YARD configuration is strongly encouraged to utilize namespacing of
# their configuration content.
#
# !!!yaml
# load_plugins: true # Auto-load plugins when YARD starts
# ignored_plugins:
# - yard-broken
# - broken2 # yard- prefix not necessary
# autoload_plugins:
# - yard-rspec
# # Plugin Specific Configuration
# yard-sample-plugin:
# show-results-inline: true
#
# As the configuration is available system wide, it can be
# accessed within the plugin code.
#
#
# if YARD::Config.options['yard-sample-plugin'] and
# YARD::Config.options['yard-sample-plugin']['show-results-inline']
# # ... perform the action that places the results inline ...
# else
# # ... do the default behavior of not showing the results inline ...
# end
#
# When accessing the configuration, be aware that this file is user managed
# so configuration keys and values may not be present. Make no assumptions and
# instead ensure that you check for the existence of keys before proceeding to
# retrieve values.
#
# @since 0.6.2
# @see options
class Config
class << self
# The system-wide configuration options for YARD
# @return [SymbolHash] a map a key-value pair settings.
# @see DEFAULT_CONFIG_OPTIONS
attr_accessor :options
end
# The location where YARD stores user-specific settings
CONFIG_DIR = File.expand_path('~/.yard')
# The main configuration YAML file.
CONFIG_FILE = File.join(CONFIG_DIR, 'config')
# File listing all ignored plugins
# @deprecated Set `ignored_plugins` in the {CONFIG_FILE} instead.
IGNORED_PLUGINS = File.join(CONFIG_DIR, 'ignored_plugins')
# Default configuration options
DEFAULT_CONFIG_OPTIONS = {
:load_plugins => false, # Whether to load plugins automatically with YARD
:ignored_plugins => [], # A list of ignored plugins by name
:autoload_plugins => [], # A list of plugins to be automatically loaded
:safe_mode => false # Does not execute or eval any user-level code
}
# The prefix used for YARD plugins. Name your gem with this prefix
# to allow it to be used as a plugin.
YARD_PLUGIN_PREFIX = /^yard[-_]/
# Loads settings from {CONFIG_FILE}. This method is called by YARD at
# load time and should not be called by the user.
# @return [void]
def self.load
self.options = SymbolHash.new(false)
options.update(DEFAULT_CONFIG_OPTIONS)
options.update(read_config_file)
load_commandline_safemode
add_ignored_plugins_file
translate_plugin_names
load_plugins
rescue => e
log.error "Invalid configuration file, using default options."
log.backtrace(e)
options.update(DEFAULT_CONFIG_OPTIONS)
end
# Saves settings to {CONFIG_FILE}.
# @return [void]
def self.save
require 'yaml'
Dir.mkdir(CONFIG_DIR) unless File.directory?(CONFIG_DIR)
File.open(CONFIG_FILE, 'w') {|f| f.write(YAML.dump(options)) }
end
# Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except
# those listed in +~/.yard/ignored_plugins+. This is called immediately
# after YARD is loaded to allow plugin support.
#
# @return [Boolean] true if all plugins loaded successfully, false otherwise.
def self.load_plugins
load_gem_plugins &&
load_autoload_plugins &&
load_commandline_plugins ? true : false
end
# Loads an individual plugin by name. It is not necessary to include the
# +yard-+ plugin prefix here.
#
# @param [String] name the name of the plugin (with or without +yard-+ prefix)
# @return [Boolean] whether the plugin was successfully loaded
def self.load_plugin(name)
name = translate_plugin_name(name)
return false if options[:ignored_plugins].include?(name)
return false if name =~ /^yard-doc-/
log.debug "Loading plugin '#{name}'..."
require name
true
rescue LoadError => e
load_plugin_failed(name, e)
end
# Load gem plugins if :load_plugins is true
def self.load_gem_plugins
return true unless options[:load_plugins]
require 'rubygems'
result = true
YARD::GemIndex.find_all_by_name('').each do |gem|
begin
next true unless gem.name =~ YARD_PLUGIN_PREFIX
load_plugin(gem.name)
rescue Gem::LoadError => e
tmp = load_plugin_failed(gem.name, e)
result = tmp unless tmp
end
end
result
rescue LoadError
log.debug "RubyGems is not present, skipping plugin loading"
false
end
# Load plugins set in :autoload_plugins
def self.load_autoload_plugins
options[:autoload_plugins].each {|name| load_plugin(name) }
end
# Load plugins from {arguments}
def self.load_commandline_plugins
with_yardopts do
arguments.each_with_index do |arg, i|
next unless arg == '--plugin'
load_plugin(arguments[i + 1])
end
end
end
# Check for command-line safe_mode switch in {arguments}
def self.load_commandline_safemode
with_yardopts do
arguments.each_with_index do |arg, _i|
options[:safe_mode] = true if arg == '--safe'
end
end
end
# Print a warning if the plugin failed to load
# @return [false]
def self.load_plugin_failed(name, exception)
log.error "Error loading plugin '#{name}'"
log.backtrace(exception) if $DEBUG
false
end
# Legacy support for {IGNORED_PLUGINS}
def self.add_ignored_plugins_file
if File.file?(IGNORED_PLUGINS)
options[:ignored_plugins] += File.read(IGNORED_PLUGINS).split(/\s+/)
end
end
# Translates plugin names to add yard- prefix.
def self.translate_plugin_names
options[:ignored_plugins].map! {|name| translate_plugin_name(name) }
options[:autoload_plugins].map! {|name| translate_plugin_name(name) }
end
# Loads the YAML configuration file into memory
# @return [Hash] the contents of the YAML file from disk
# @see CONFIG_FILE
def self.read_config_file
if File.file?(CONFIG_FILE)
require 'yaml'
YAML.load_file(CONFIG_FILE)
else
{}
end
end
# Sanitizes and normalizes a plugin name to include the 'yard-' prefix.
# @param [String] name the plugin name
# @return [String] the sanitized and normalized plugin name.
def self.translate_plugin_name(name)
name = name.delete('/') # Security sanitization
name = "yard-" + name unless name =~ YARD_PLUGIN_PREFIX
name
end
# Temporarily loads .yardopts file into @yardopts
def self.with_yardopts
yfile = CLI::Yardoc::DEFAULT_YARDOPTS_FILE
@yardopts = File.file?(yfile) ? File.read_binary(yfile).shell_split : []
result = yield
@yardopts = nil
result
end
# @return [Array] arguments from commandline and yardopts file
def self.arguments
ARGV + @yardopts
end
end
Config.options = Config::DEFAULT_CONFIG_OPTIONS
end
yard-0.9.7/lib/yard/code_objects/ 0000755 0000041 0000041 00000000000 13035234564 016653 5 ustar www-data www-data yard-0.9.7/lib/yard/code_objects/constant_object.rb 0000644 0000041 0000041 00000000732 13035234564 022361 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
register_separator NSEP, :constant
# A +ConstantObject+ represents a Ruby constant (not a module or class).
# To access the constant's (source code) value, use {#value}.
class ConstantObject < Base
# The source code representing the constant's value
# @return [String] the value the constant is set to
attr_reader :value
def value=(value)
@value = format_source(value)
end
end
end
yard-0.9.7/lib/yard/code_objects/namespace_mapper.rb 0000644 0000041 0000041 00000006620 13035234564 022504 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module CodeObjects
# This module controls registration and accessing of namespace separators
# for {Registry} lookup.
#
# @since 0.9.1
module NamespaceMapper
# @!group Registering a Separator for a Namespace
# Registers a separator with an optional set of valid types that
# must follow the separator lexically.
#
# @param sep [String] the separator string for the namespace
# @param valid_types [Array] a list of object types that
# must follow the separator. If the list is empty, any type can
# follow the separator.
# @example Registering separators for a method object
# # Anything after a "#" denotes a method object
# register_separator "#", :method
# # Anything after a "." denotes a method object
# register_separator ".", :method
def register_separator(sep, *valid_types)
NamespaceMapper.invalidate
valid_types.each do |t|
NamespaceMapper.rev_map[t] ||= []
NamespaceMapper.rev_map[t] << sep
end
NamespaceMapper.map[sep] ||= []
NamespaceMapper.map[sep] += valid_types
end
# Clears the map of separators.
#
# @return [void]
def clear_separators
NamespaceMapper.invalidate
NamespaceMapper.map = {}
NamespaceMapper.rev_map = {}
end
# Gets or sets the default separator value to use when no
# separator for the namespace can be determined.
#
# @param value [String, nil] the default separator, or nil to return the
# value
# @example
# default_separator "::"
def default_separator(value = nil)
if value
NamespaceMapper.default_separator = Regexp.quote value
else
NamespaceMapper.default_separator
end
end
# @!group Separator and Type Lookup Helpers
# @return [Array] all of the registered separators
def separators
NamespaceMapper.map.keys
end
# @return [Regexp] the regexp match of all separators
def separators_match
NamespaceMapper.map_match
end
# @param sep [String] the separator to return types for
# @return [Array] a list of types registered to a separator
def types_for_separator(sep)
NamespaceMapper.map[sep]
end
# @param type [String] the type to return separators for
# @return [Array] a list of separators registered to a type
def separators_for_type(type)
NamespaceMapper.rev_map[type]
end
# Internal methods to act as a singleton registry
class << self
# @!visibility private
# @return [Hash] a mapping of types to separators
def map
@map ||= {}
end
# @return [Hash] a reverse mapping of separators to types
def rev_map
@rev_map ||= {}
end
# Invalidates all separators
# @return [void]
def invalidate
@map_match = nil
end
# @return [Regexp] the full list of separators as a regexp match
def map_match
@map_match ||= @map.keys.map {|k| Regexp.quote k }.join('|')
end
# @return [String] the default separator when no separator can begin
# determined.
attr_accessor :default_separator
end
end
end
end
yard-0.9.7/lib/yard/code_objects/root_object.rb 0000644 0000041 0000041 00000001010 13035234564 021501 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module CodeObjects
# Represents the root namespace object (the invisible Ruby module that
# holds all top level modules, class and other objects).
class RootObject < ModuleObject
def path; @path ||= "" end
def inspect; @inspect ||= "#" end
def root?; true end
def title; 'Top Level Namespace' end
def equal?(other)
other == :root ? true : super(other)
end
def hash; :root.hash end
end
end
end
yard-0.9.7/lib/yard/code_objects/class_object.rb 0000644 0000041 0000041 00000012023 13035234564 021631 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
register_separator NSEP, :class
# A ClassObject represents a Ruby class in source code. It is a {ModuleObject}
# with extra inheritance semantics through the superclass.
class ClassObject < NamespaceObject
# The {ClassObject} that this class object inherits from in Ruby source.
# @return [ClassObject] a class object that is the superclass of this one
attr_reader :superclass
# Creates a new class object in +namespace+ with +name+
#
# @see Base.new
def initialize(namespace, name, *args, &block)
super
if is_exception?
self.superclass ||= "::Exception" unless P(namespace, name) == P(:Exception)
else
case P(namespace, name).path
when "BasicObject"
nil
when "Object"
self.superclass ||= "::BasicObject"
else
self.superclass ||= "::Object"
end
end
end
# Whether or not the class is a Ruby Exception
#
# @return [Boolean] whether the object represents a Ruby exception
def is_exception?
inheritance_tree.reverse.any? {|o| BUILTIN_EXCEPTIONS_HASH.key? o.path }
end
# Returns the inheritance tree of the object including self.
#
# @param [Boolean] include_mods whether or not to include mixins in the
# inheritance tree.
# @return [Array] the list of code objects that make up
# the inheritance tree.
def inheritance_tree(include_mods = false)
list = (include_mods ? mixins(:instance, :class) : [])
if superclass.is_a?(Proxy) || superclass.respond_to?(:inheritance_tree)
list += [superclass] unless superclass == P(:Object) || superclass == P(:BasicObject)
end
[self] + list.map do |m|
next m if m == self
next m unless m.respond_to?(:inheritance_tree)
m.inheritance_tree(include_mods)
end.flatten.uniq
end
# Returns the list of methods matching the options hash. Returns
# all methods if hash is empty.
#
# @param [Hash] opts the options hash to match
# @option opts [Boolean] :inherited (true) whether inherited methods should be
# included in the list
# @option opts [Boolean] :included (true) whether mixed in methods should be
# included in the list
# @return [Array] the list of methods that matched
def meths(opts = {})
opts = SymbolHash[:inherited => true].update(opts)
list = super(opts)
list += inherited_meths(opts).reject do |o|
next(false) if opts[:all]
list.find {|o2| o2.name == o.name && o2.scope == o.scope }
end if opts[:inherited]
list
end
# Returns only the methods that were inherited.
#
# @return [Array] the list of inherited method objects
def inherited_meths(opts = {})
inheritance_tree[1..-1].inject([]) do |list, superclass|
if superclass.is_a?(Proxy)
list
else
list += superclass.meths(opts).reject do |o|
next(false) if opts[:all]
child(:name => o.name, :scope => o.scope) ||
list.find {|o2| o2.name == o.name && o2.scope == o.scope }
end
end
end
end
# Returns the list of constants matching the options hash.
#
# @param [Hash] opts the options hash to match
# @option opts [Boolean] :inherited (true) whether inherited constant should be
# included in the list
# @option opts [Boolean] :included (true) whether mixed in constant should be
# included in the list
# @return [Array] the list of constant that matched
def constants(opts = {})
opts = SymbolHash[:inherited => true].update(opts)
super(opts) + (opts[:inherited] ? inherited_constants : [])
end
# Returns only the constants that were inherited.
#
# @return [Array] the list of inherited constant objects
def inherited_constants
inheritance_tree[1..-1].inject([]) do |list, superclass|
if superclass.is_a?(Proxy)
list
else
list += superclass.constants.reject do |o|
child(:name => o.name) || list.find {|o2| o2.name == o.name }
end
end
end
end
# Sets the superclass of the object
#
# @param [Base, Proxy, String, Symbol, nil] object the superclass value
# @return [void]
def superclass=(object)
case object
when Base, Proxy, NilClass
@superclass = object
when String, Symbol
@superclass = Proxy.new(namespace, object)
else
raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol"
end
if name == @superclass.name && namespace != YARD::Registry.root && !object.is_a?(Base)
@superclass = Proxy.new(namespace.namespace, object)
end
if @superclass == self
msg = "superclass #{@superclass.inspect} cannot be the same as the declared class #{inspect}"
@superclass = P("::Object")
raise ArgumentError, msg
end
end
end
end
yard-0.9.7/lib/yard/code_objects/macro_object.rb 0000644 0000041 0000041 00000016524 13035234564 021637 0 ustar www-data www-data # frozen_string_literal: true
require 'ostruct'
module YARD
module CodeObjects
# A MacroObject represents a docstring defined through +@!macro NAME+ and can be
# reused by specifying the tag +@!macro NAME+. You can also provide the
# +attached+ type flag to the macro definition to have it attached to the
# specific DSL method so it will be implicitly reused.
#
# Macros are fully described in the {file:docs/Tags.md#macro Tags Overview}
# document.
#
# @example Creating a basic named macro
# # @!macro prop
# # @!method $1(${3-})
# # @return [$2] the value of the $0
# property :foo, String, :a, :b
#
# # @!macro prop
# property :bar, Numeric, :value
#
# @example Creating a macro that is attached to the method call
# # @!macro [attach] prop2
# # @!method $1(value)
# property :foo
#
# # Extra data added to docstring
# property :bar
class MacroObject < Base
MACRO_MATCH = /(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/
class << self
# Creates a new macro and fills in the relevant properties.
# @param [String] macro_name the name of the macro, must be unique.
# @param [String] data the data the macro should expand when re-used
# @param [CodeObjects::Base] method_object an object to attach this
# macro to. If supplied, {#attached?} will be true
# @return [MacroObject] the newly created object
def create(macro_name, data, method_object = nil)
obj = new(:root, macro_name)
obj.macro_data = data
obj.method_object = method_object
obj
end
# Finds a macro using +macro_name+
# @param [#to_s] macro_name the name of the macro
# @return [MacroObject] if a macro is found
# @return [nil] if there is no registered macro by that name
def find(macro_name)
Registry.at('.macro.' + macro_name.to_s)
end
# Parses a given docstring and determines if the macro is "new" or
# not. If the macro has $variable names or if it has a @!macro tag
# with the [new] or [attached] flag, it is considered new.
#
# If a new macro is found, the macro is created and registered. Otherwise
# the macro name is searched and returned. If a macro is not found,
# nil is returned.
#
# @param [#to_s] macro_name the name of the macro
# @param [CodeObjects::Base] method_object an optional method to attach
# the macro to. Only used if the macro is being created, otherwise
# this argument is ignored.
# @return [MacroObject] the newly created or existing macro, depending
# on whether the @!macro tag was a new tag or not.
# @return [nil] if the +data+ has no macro tag or if the macro is
# not new and no macro by the macro name is found.
def find_or_create(macro_name, data, method_object = nil)
find(name) || create(macro_name, data, method_object)
end
alias create_docstring find_or_create
# Expands +macro_data+ using the interpolation parameters.
#
# Interpolation rules:
# * $0, $1, $2, ... = the Nth parameter in +call_params+
# * $* = the full statement source (excluding block)
# * Also supports $!{N-M} ranges, as well as negative indexes on N or M
# * Use \$ to escape the variable name in a macro.
#
# @!macro [new] macro.expand
# @param [Array] call_params the method name and parameters
# to the method call. These arguments will fill \$0-N
# @param [String] full_source the full source line (excluding block)
# interpolated as \$*
# @param [String] block_source Currently unused. Will support
# interpolating the block data as a variable.
# @return [String] the expanded macro data
# @param [String] macro_data the macro data to expand (taken from {#macro_data})
def expand(macro_data, call_params = [], full_source = '', block_source = '') # rubocop:disable Lint/UnusedMethodArgument
macro_data = macro_data.all if macro_data.is_a?(Docstring)
macro_data.gsub(MACRO_MATCH) do
escape = $1
first = $2 || $5
last = $4
rng = $3 ? true : false
next $&[1..-1] if escape
if first == '*'
last ? $& : full_source
else
first_i = first.to_i
last_i = (last ? last.to_i : call_params.size)
last_i = first_i unless rng
params = call_params[first_i..last_i]
params ? params.join(", ") : ''
end
end
end
# Applies a macro on a docstring by creating any macro data inside of
# the docstring first. Equivalent to calling {find_or_create} and {apply_macro}
# on the new macro object.
#
# @param [Docstring] docstring the docstring to create a macro out of
# @!macro macro.expand
# @see find_or_create
def apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) # rubocop:disable Lint/UnusedMethodArgument
docstring = docstring.all if Docstring === docstring
parser = Docstring.parser
handler = OpenStruct.new
handler.call_params = call_params[1..-1]
handler.caller_method = call_params.first
handler.statement = OpenStruct.new(:source => full_source)
parser.parse(docstring, nil, handler).to_docstring.to_raw
end
# Applies a macro to a docstring, interpolating the macro's data on the
# docstring and appending any extra local docstring data that was in
# the original +docstring+ object.
#
# @param [MacroObject] macro the macro object
# @!macro macro.expand
def apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') # rubocop:disable Lint/UnusedMethodArgument
apply(docstring, call_params, full_source, block_source)
end
end
# @return [String] the macro data stored on the object
attr_accessor :macro_data
# @return [CodeObjects::Base] the method object that this macro is
# attached to.
attr_accessor :method_object
# @return [Boolean] whether this macro is attached to a method
def attached?; method_object ? true : false end
# Overrides {Base#path} so the macro path is ".macro.MACRONAME"
def path; '.macro.' + name.to_s end
# Overrides the separator to be '.'
def sep; '.' end
# Expands the macro using
# @param [Array] call_params a list of tokens that are passed
# to the method call
# @param [String] full_source the full method call (not including the block)
# @param [String] block_source the source passed in the block of the method
# call, if there is a block.
# @example Expanding a Macro
# macro.expand(%w(property foo bar), 'property :foo, :bar', '') #=>
# "...macro data interpolating this line of code..."
# @see expand
def expand(call_params = [], full_source = '', block_source = '')
self.class.expand(macro_data, call_params, full_source, block_source)
end
end
end
end
yard-0.9.7/lib/yard/code_objects/proxy.rb 0000644 0000041 0000041 00000016751 13035234564 020373 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module CodeObjects
# A special type of +NoMethodError+ when raised from a {Proxy}
class ProxyMethodError < NoMethodError; end
# @private
PROXY_MATCH = /(?:#{NSEPQ}|#{ISEPQ}|#{CSEPQ})([^#{Regexp.quote(
(NSEP + ISEP + CSEP).split('').uniq.join
)}]+)$/
# The Proxy class is a way to lazily resolve code objects in
# cases where the object may not yet exist. A proxy simply stores
# an unresolved path until a method is called on the object, at which
# point it does a lookup using {Registry.resolve}. If the object is
# not found, a warning is raised and {ProxyMethodError} might be raised.
#
# @example Creates a Proxy to the String class from a module
# # When the String class is parsed this method will
# # begin to act like the String ClassObject.
# Proxy.new(mymoduleobj, "String")
# @see Registry.resolve
# @see ProxyMethodError
class Proxy
def self.===(other) other.is_a?(self) end
attr_reader :namespace
alias parent namespace
# Creates a new Proxy
#
# @raise [ArgumentError] if namespace is not a NamespaceObject
# @return [Proxy] self
def initialize(namespace, name, type = nil)
namespace = Registry.root if !namespace || namespace == :root
if name =~ /^#{NSEPQ}/
namespace = Registry.root
name = name[2..-1]
end
if name =~ PROXY_MATCH
@orignamespace = namespace
@origname = name
@imethod = true if name.include? ISEP
namespace = Proxy.new(namespace, $`) unless $`.empty?
name = $1
else
@orignamespace = nil
@origname = nil
@imethod = nil
end
@name = name.to_sym
@namespace = namespace
@obj = nil
@imethod ||= nil
self.type = type
if @namespace.is_a?(ConstantObject)
@origname = nil # forget these for a constant
@orignamespace = nil
@namespace = Proxy.new(@namespace.namespace, @namespace.value)
end
unless @namespace.is_a?(NamespaceObject) || @namespace.is_a?(Proxy)
raise ArgumentError, "Invalid namespace object: #{namespace}"
end
# If the name begins with "::" (like "::String")
# this is definitely a root level object, so
# remove the namespace and attach it to the root
if @name =~ /^#{NSEPQ}/
@name.gsub!(/^#{NSEPQ}/, '')
@namespace = Registry.root
end
end
# (see Base#name)
def name(prefix = false)
prefix ? "#{@imethod && ISEP}#{@name}" : @name
end
# Returns a text representation of the Proxy
# @return [String] the object's #inspect method or P(OBJECTPATH)
def inspect
to_obj ? to_obj.inspect : "P(#{path})"
end
# If the proxy resolves to an object, returns its path, otherwise
# guesses at the correct path using the original namespace and name.
#
# @return [String] the assumed path of the proxy (or the real path
# of the resolved object)
def path
to_obj ? to_obj.path : proxy_path
end
alias to_s path
alias to_str path
alias title path
# @return [Boolean]
def is_a?(klass)
to_obj ? to_obj.is_a?(klass) : self.class <= klass
end
# @return [Boolean]
def ===(other)
to_obj ? to_obj === other : self.class <= other.class
end
# @return [Boolean]
def <=>(other)
if other.respond_to? :path
path <=> other.path
else
false
end
end
# @return [Boolean]
def equal?(other)
if other.respond_to? :path
path == other.path
else
false
end
end
alias == equal?
# @return [Integer] the object's hash value (for equality checking)
def hash; path.hash end
# Returns the class name of the object the proxy is mimicking, if
# resolved. Otherwise returns +Proxy+.
# @return [Class] the resolved object's class or +Proxy+
def class
to_obj ? to_obj.class : Proxy
end
# Returns the type of the proxy. If it cannot be resolved at the
# time of the call, it will either return the inferred proxy type
# (see {#type=}) or +:proxy+
# @return [Symbol] the Proxy's type
# @see #type=
def type
to_obj ? to_obj.type : @type || :proxy
end
# Allows a parser to infer the type of the proxy by its path.
# @param [#to_sym] type the proxy's inferred type
# @return [void]
def type=(type) @type = type ? type.to_sym : nil end
# @return [Boolean]
def instance_of?(klass)
self.class == klass
end
# @return [Boolean]
def kind_of?(klass)
self.class <= klass
end
# @return [Boolean]
def respond_to?(meth, include_private = false)
to_obj ? to_obj.respond_to?(meth, include_private) : super
end
# Dispatches the method to the resolved object.
#
# @raise [ProxyMethodError] if the proxy cannot find the real object
def method_missing(meth, *args, &block)
if to_obj
to_obj.__send__(meth, *args, &block)
else
log.warn "Load Order / Name Resolution Problem on #{path}:\n" \
"-\n" \
"Something is trying to call #{meth} on object #{path} before it has been recognized.\n" \
"This error usually means that you need to modify the order in which you parse files\n" \
"so that #{path} is parsed before methods or other objects attempt to access it.\n" \
"-\n" \
"YARD will recover from this error and continue to parse but you *may* have problems\n" \
"with your generated documentation. You should probably fix this.\n" \
"-\n"
begin
super
rescue NoMethodError
raise ProxyMethodError, "Proxy cannot call method ##{meth} on object '#{path}'"
end
end
end
# This class is never a root object
def root?; false end
private
# @note this method fixes a bug in 1.9.2: http://gist.github.com/437136
def to_ary; nil end
# Attempts to find the object that this unresolved object
# references by checking if any objects by this name are
# registered all the way up the namespace tree.
#
# @return [Base, nil] the registered code object or nil
def to_obj
return @obj if @obj
@obj = Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s, false, false, @type)
if @obj
if @origname && @origname.include?("::") && !@obj.path.include?(@origname)
# the object's path should include the original proxy namespace,
# otherwise it's (probably) not the right object.
@obj = nil
else
@namespace = @obj.namespace
@name = @obj.name
end
end
@obj
end
def proxy_path
if @namespace.root?
(@imethod ? ISEP : "") + name.to_s
elsif @origname
if @origname =~ CONSTANTSTART
@origname
else
[namespace.path, @origname].join
end
elsif name.to_s =~ CONSTANTSTART
name.to_s
else # class meth?
[namespace.path, name.to_s].join(CSEP)
end
end
end
end
end
yard-0.9.7/lib/yard/code_objects/module_object.rb 0000644 0000041 0000041 00000001272 13035234564 022015 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
register_separator NSEP, :module
# Represents a Ruby module.
class ModuleObject < NamespaceObject
# Returns the inheritance tree of mixins.
#
# @param [Boolean] include_mods if true, will include mixed in
# modules (which is likely what is wanted).
# @return [Array] a list of namespace objects
def inheritance_tree(include_mods = false)
return [self] unless include_mods
[self] + mixins(:instance, :class).map do |m|
next if m == self
next m unless m.respond_to?(:inheritance_tree)
m.inheritance_tree(true)
end.compact.flatten.uniq
end
end
end
yard-0.9.7/lib/yard/code_objects/extended_method_object.rb 0000644 0000041 0000041 00000001441 13035234564 023666 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
# Represents an instance method of a module that was mixed into the class
# scope of another namespace.
#
# @see MethodObject
class ExtendedMethodObject
instance_methods.each {|m| undef_method(m) unless m =~ /^__/ || m.to_sym == :object_id }
# @return [Symbol] always +:class+
def scope; :class end
# Sets up a delegate for {MethodObject} obj.
#
# @param [MethodObject] obj the instance method to treat as a mixed in
# class method on another namespace.
def initialize(obj) @del = obj end
# Sends all methods to the {MethodObject} assigned in {#initialize}
# @see #initialize
# @see MethodObject
def method_missing(sym, *args, &block) @del.__send__(sym, *args, &block) end
end
end
yard-0.9.7/lib/yard/code_objects/extra_file_object.rb 0000644 0000041 0000041 00000006667 13035234564 022667 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
# An ExtraFileObject represents an extra documentation file (README or other
# file). It is not strictly a CodeObject (does not inherit from `Base`) although
# it implements `path`, `name` and `type`, and therefore should be structurally
# compatible with most CodeObject interfaces.
class ExtraFileObject
attr_accessor :filename
attr_writer :attributes
attr_accessor :name
# @since 0.8.3
attr_reader :locale
# Creates a new extra file object.
# @param [String] filename the location on disk of the file
# @param [String] contents the file contents. If not set, the contents
# will be read from disk using the +filename+.
def initialize(filename, contents = nil)
self.filename = filename
self.name = File.basename(filename).gsub(/\.[^.]+$/, '')
self.attributes = SymbolHash.new(false)
@original_contents = contents
@parsed = false
@locale = nil
ensure_parsed
end
alias path name
def attributes
ensure_parsed
@attributes
end
def title
attributes[:title] || name
end
def contents
ensure_parsed
@contents
end
def contents=(contents)
@original_contents = contents
@parsed = false
end
# @param [String] locale the locale name to be translated.
# @return [void]
# @since 0.8.3
def locale=(locale)
@locale = locale
@parsed = false
end
def inspect
"#"
end
alias to_s inspect
def type; :extra_file end
def ==(other)
return false unless self.class === other
other.filename == filename
end
alias eql? ==
alias equal? ==
def hash; filename.hash end
private
def ensure_parsed
return if @parsed
@parsed = true
@contents = parse_contents(@original_contents || File.read(@filename))
end
# @param [String] data the file contents
def parse_contents(data)
retried = false
cut_index = 0
data = translate(data)
data = data.split("\n")
data.each_with_index do |line, index|
case line
when /^#!(\S+)\s*$/
if index == 0
attributes[:markup] = $1
else
cut_index = index
break
end
when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
attributes[$1] = $2
when /^\s*\s*$/
# Ignore HTML comments
else
cut_index = index
break
end
end
data = data[cut_index..-1] if cut_index > 0
contents = data.join("\n")
if contents.respond_to?(:force_encoding) && attributes[:encoding]
begin
contents.force_encoding(attributes[:encoding])
rescue ArgumentError
log.warn "Invalid encoding `#{attributes[:encoding]}' in #{filename}"
end
end
contents
rescue ArgumentError => e
if retried && e.message =~ /invalid byte sequence/
# This should never happen.
log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
return ''
end
data.force_encoding('binary') if data.respond_to?(:force_encoding)
retried = true
retry
end
def translate(data)
text = YARD::I18n::Text.new(data, :have_header => true)
text.translate(YARD::Registry.locale(locale))
end
end
end
yard-0.9.7/lib/yard/code_objects/class_variable_object.rb 0000644 0000041 0000041 00000000515 13035234564 023501 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
register_separator NSEP, :class_variable
# Represents a class variable inside a namespace. The path is expressed
# in the form "A::B::@@classvariable"
class ClassVariableObject < Base
# @return [String] the class variable's value
attr_accessor :value
end
end
yard-0.9.7/lib/yard/code_objects/method_object.rb 0000644 0000041 0000041 00000013763 13035234564 022020 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
register_separator CSEP, :method
register_separator ISEP, :method
# Represents a Ruby method in source
class MethodObject < Base
# The scope of the method (+:class+ or +:instance+)
#
# @return [Symbol] the scope
attr_reader :scope
# Whether the object is explicitly defined in source or whether it was
# inferred by a handler. For instance, attribute methods are generally
# inferred and therefore not explicitly defined in source.
#
# @return [Boolean] whether the object is explicitly defined in source.
attr_accessor :explicit
# Returns the list of parameters parsed out of the method signature
# with their default values.
#
# @return [Array] a list of parameter names followed
# by their default values (or nil)
attr_accessor :parameters
# Creates a new method object in +namespace+ with +name+ and an instance
# or class +scope+
#
# If scope is +:module+, this object is instantiated as a public
# method in +:class+ scope, but also creates a new (empty) method
# as a private +:instance+ method on the same class or module.
#
# @param [NamespaceObject] namespace the namespace
# @param [String, Symbol] name the method name
# @param [Symbol] scope +:instance+, +:class+, or +:module+
def initialize(namespace, name, scope = :instance, &block)
@module_function = false
@scope = nil
# handle module function
if scope == :module
other = self.class.new(namespace, name, &block)
other.visibility = :private
scope = :class
@module_function = true
end
@visibility = :public
self.scope = scope
self.parameters = []
super
end
# Changes the scope of an object from :instance or :class
# @param [Symbol] v the new scope
def scope=(v)
reregister = @scope ? true : false
# handle module function
if v == :module
other = self.class.new(namespace, name)
other.visibility = :private
@visibility = :public
@module_function = true
@path = nil
end
YARD::Registry.delete(self)
@path = nil
@scope = v.to_sym
@scope = :class if @scope == :module
YARD::Registry.register(self) if reregister
end
# @return whether or not the method is the #initialize constructor method
def constructor?
name == :initialize && scope == :instance && namespace.is_a?(ClassObject)
end
# @return [Boolean] whether or not this method was created as a module
# function
# @since 0.8.0
def module_function?
@module_function
end
# Returns the read/writer info for the attribute if it is one
# @return [SymbolHash] if there is information about the attribute
# @return [nil] if the method is not an attribute
# @since 0.5.3
def attr_info
return nil unless namespace.is_a?(NamespaceObject)
namespace.attributes[scope][name.to_s.gsub(/=$/, '')]
end
# @return [Boolean] whether the method is a writer attribute
# @since 0.5.3
def writer?
info = attr_info
info && info[:write] == self ? true : false
end
# @return [Boolean] whether the method is a reader attribute
# @since 0.5.3
def reader?
info = attr_info
info && info[:read] == self ? true : false
end
# Tests if the object is defined as an attribute in the namespace
# @return [Boolean] whether the object is an attribute
def is_attribute?
info = attr_info
if info
read_or_write = name.to_s =~ /=$/ ? :write : :read
info[read_or_write] ? true : false
else
false
end
end
# Tests if the object is defined as an alias of another method
# @return [Boolean] whether the object is an alias
def is_alias?
return false unless namespace.is_a?(NamespaceObject)
namespace.aliases.key? self
end
# Tests boolean {#explicit} value.
#
# @return [Boolean] whether the method is explicitly defined in source
def is_explicit?
explicit ? true : false
end
# @return [MethodObject] the object that this method overrides
# @return [nil] if it does not override a method
# @since 0.6.0
def overridden_method
return nil if namespace.is_a?(Proxy)
meths = namespace.meths(:all => true)
meths.find {|m| m.path != path && m.name == name && m.scope == scope }
end
# Returns all alias names of the object
# @return [Array] the alias names
def aliases
list = []
return list unless namespace.is_a?(NamespaceObject)
namespace.aliases.each do |o, aname|
list << o if aname == name && o.scope == scope
end
list
end
# Override path handling for instance methods in the root namespace
# (they should still have a separator as a prefix).
# @return [String] the path of a method
def path
@path ||= !namespace || namespace.path == "" ? sep + super : super
end
# Returns the name of the object.
#
# @example The name of an instance method (with prefix)
# an_instance_method.name(true) # => "#mymethod"
# @example The name of a class method (with prefix)
# a_class_method.name(true) # => "mymethod"
# @param [Boolean] prefix whether or not to show the prefix
# @return [String] returns {#sep} + +name+ for an instance method if
# prefix is true
# @return [Symbol] the name without {#sep} if prefix is set to false
def name(prefix = false)
prefix ? (sep == ISEP ? "#{sep}#{super}" : super.to_s) : super
end
# Override separator to differentiate between class and instance
# methods.
# @return [String] "#" for an instance method, "." for class
def sep
if scope == :class
namespace && namespace != YARD::Registry.root ? CSEP : NSEP
else
ISEP
end
end
protected
def copyable_attributes
super - %w(scope module_function)
end
end
end
yard-0.9.7/lib/yard/code_objects/base.rb 0000644 0000041 0000041 00000054257 13035234564 020127 0 ustar www-data www-data # frozen_string_literal: true
module YARD
module CodeObjects
# A list of code objects. This array acts like a set (no unique items)
# but also disallows any {Proxy} objects from being added.
class CodeObjectList < Array
# Creates a new object list associated with a namespace
#
# @param [NamespaceObject] owner the namespace the list should be associated with
# @return [CodeObjectList]
def initialize(owner = Registry.root)
@owner = owner
end
# Adds a new value to the list
#
# @param [Base] value a code object to add
# @return [CodeObjectList] self
def push(value)
value = Proxy.new(@owner, value) if value.is_a?(String) || value.is_a?(Symbol)
if value.is_a?(CodeObjects::Base) || value.is_a?(Proxy)
super(value) unless include?(value)
else
raise ArgumentError, "#{value.class} is not a valid CodeObject"
end
self
end
alias << push
end
extend NamespaceMapper
# Namespace separator
NSEP = '::'
# Regex-quoted namespace separator
NSEPQ = NSEP
# Instance method separator
ISEP = '#'
# Regex-quoted instance method separator
ISEPQ = ISEP
# Class method separator
CSEP = '.'
# Regex-quoted class method separator
CSEPQ = Regexp.quote CSEP
# Regular expression to match constant name
CONSTANTMATCH = /[A-Z]\w*/
# Regular expression to match the beginning of a constant
CONSTANTSTART = /^[A-Z]/
# Regular expression to match namespaces (const A or complex path A::B)
NAMESPACEMATCH = /(?:(?:#{NSEPQ}\s*)?#{CONSTANTMATCH})+/
# Regular expression to match a method name
METHODNAMEMATCH = %r{[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|![=~]?|<=>|[<>]=?|\*\*|[-/+%^&*~`|]|\[\]=?}
# Regular expression to match a fully qualified method def (self.foo, Class.foo).
METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|[a-z]\w*)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/
# All builtin Ruby exception classes for inheritance tree.
BUILTIN_EXCEPTIONS = ["ArgumentError", "ClosedQueueError", "EncodingError",
"EOFError", "Exception", "FiberError", "FloatDomainError", "IndexError",
"Interrupt", "IOError", "KeyError", "LoadError", "LocalJumpError",
"NameError", "NoMemoryError", "NoMethodError", "NotImplementedError",
"RangeError", "RegexpError", "RuntimeError", "ScriptError", "SecurityError",
"SignalException", "StandardError", "StopIteration", "SyntaxError",
"SystemCallError", "SystemExit", "SystemStackError", "ThreadError",
"TypeError", "UncaughtThrowError", "ZeroDivisionError"]
# All builtin Ruby classes for inheritance tree.
# @note MatchingData is a 1.8.x legacy class
BUILTIN_CLASSES = ["Array", "Bignum", "Binding", "Class", "Complex",
"ConditionVariable", "Data", "Dir", "Encoding", "Enumerator", "FalseClass",
"Fiber", "File", "Fixnum", "Float", "Hash", "IO", "Integer", "MatchData",
"Method", "Module", "NilClass", "Numeric", "Object", "Proc", "Queue",
"Random", "Range", "Rational", "Regexp", "RubyVM", "SizedQueue", "String",
"Struct", "Symbol", "Thread", "ThreadGroup", "Time", "TracePoint",
"TrueClass", "UnboundMethod"] + BUILTIN_EXCEPTIONS
# All builtin Ruby modules for mixin handling.
BUILTIN_MODULES = ["Comparable", "Enumerable", "Errno", "FileTest", "GC",
"Kernel", "Marshal", "Math", "ObjectSpace", "Precision", "Process", "Signal"]
# All builtin Ruby classes and modules.
BUILTIN_ALL = BUILTIN_CLASSES + BUILTIN_MODULES
# Hash of {BUILTIN_EXCEPTIONS} as keys and true as value (for O(1) lookups)
BUILTIN_EXCEPTIONS_HASH = BUILTIN_EXCEPTIONS.inject({}) {|h, n| h.update(n => true) }
# +Base+ is the superclass of all code objects recognized by YARD. A code
# object is any entity in the Ruby language (class, method, module). A
# DSL might subclass +Base+ to create a new custom object representing
# a new entity type.
#
# == Registry Integration
# Any created object associated with a namespace is immediately registered
# with the registry. This allows the Registry to act as an identity map
# to ensure that no object is represented by more than one Ruby object
# in memory. A unique {#path} is essential for this identity map to work
# correctly.
#
# == Custom Attributes
# Code objects allow arbitrary custom attributes to be set using the
# {#[]=} assignment method.
#
# == Namespaces
# There is a special type of object called a "namespace". These are subclasses
# of the {NamespaceObject} and represent Ruby entities that can have
# objects defined within them. Classically these are modules and classes,
# though a DSL might create a custom {NamespaceObject} to describe a
# specific set of objects.
#
# == Separators
# Custom classes with different separator tokens should define their own
# separators using the {NamespaceMapper.register_separator} method. The
# standard Ruby separators have already been defined ('::', '#', '.', etc).
#
# @abstract This class should not be used directly. Instead, create a
# subclass that implements {#path}, {#sep} or {#type}. You might also
# need to register custom separators if {#sep} uses alternate separator
# tokens.
# @see Registry
# @see #path
# @see #[]=
# @see NamespaceObject
# @see NamespaceMapper.register_separator
class Base
# The files the object was defined in. To add a file, use {#add_file}.
# @return [Array] a list of files
# @see #add_file
attr_reader :files
# The namespace the object is defined in. If the object is in the
# top level namespace, this is {Registry.root}
# @return [NamespaceObject] the namespace object
attr_reader :namespace
# The source code associated with the object
# @return [String, nil] source, if present, or nil
attr_reader :source
# Language of the source code associated with the object. Defaults to
# +:ruby+.
#
# @return [Symbol] the language type
attr_accessor :source_type
# The one line signature representing an object. For a method, this will
# be of the form "def meth(arguments...)". This is usually the first
# source line.
#
# @return [String] a line of source
attr_accessor :signature
# The non-localized documentation string associated with the object
# @return [Docstring] the documentation string
# @since 0.8.4
attr_reader :base_docstring
undef base_docstring
def base_docstring; @docstring end
# Marks whether or not the method is conditionally defined at runtime
# @return [Boolean] true if the method is conditionally defined at runtime
attr_accessor :dynamic
# @return [String] the group this object is associated with
# @since 0.6.0
attr_accessor :group
# Is the object defined conditionally at runtime?
# @see #dynamic
def dynamic?; @dynamic end
# @return [Symbol] the visibility of an object (:public, :private, :protected)
attr_accessor :visibility
undef visibility=
def visibility=(v) @visibility = v.to_sym end
class << self
# Allocates a new code object
# @return [Base]
# @see #initialize
def new(namespace, name, *args, &block)
raise ArgumentError, "invalid empty object name" if name.to_s.empty?
if namespace.is_a?(ConstantObject)
namespace = Proxy.new(namespace.namespace, namespace.value)
end
if name.to_s[0, 2] == NSEP
name = name.to_s[2..-1]
namespace = Registry.root
end
if name =~ /(?:#{NSEPQ})([^:]+)$/
return new(Proxy.new(namespace, $`), $1, *args, &block)
end
obj = super(namespace, name, *args)
existing_obj = Registry.at(obj.path)
obj = existing_obj if existing_obj && existing_obj.class == self
yield(obj) if block_given?
obj
end
# Compares the class with subclasses
#
# @param [Object] other the other object to compare classes with
# @return [Boolean] true if other is a subclass of self
def ===(other)
other.is_a?(self)
end
end
# Creates a new code object
#
# @example Create a method in the root namespace
# CodeObjects::Base.new(:root, '#method') # => #
# @example Create class Z inside namespace X::Y
# CodeObjects::Base.new(P("X::Y"), :Z) # or
# CodeObjects::Base.new(Registry.root, "X::Y")
# @param [NamespaceObject] namespace the namespace the object belongs in,
# {Registry.root} or :root should be provided if it is associated with
# the top level namespace.
# @param [Symbol, String] name the name (or complex path) of the object.
# @yield [self] a block to perform any extra initialization on the object
# @yieldparam [Base] self the newly initialized code object
# @return [Base] the newly created object
def initialize(namespace, name, *)
if namespace && namespace != :root &&
!namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
raise ArgumentError, "Invalid namespace object: #{namespace}"
end
@files = []
@current_file_has_comments = false
@name = name.to_sym
@source_type = :ruby
@visibility = :public
@tags = []
@docstrings = {}
@docstring = Docstring.new!('', [], self)
@namespace = nil
self.namespace = namespace
yield(self) if block_given?
end
# Copies all data in this object to another code object, except for
# uniquely identifying information (path, namespace, name, scope).
#
# @param [Base] other the object to copy data to
# @return [Base] the other object
# @since 0.8.0
def copy_to(other)
copyable_attributes.each do |ivar|
ivar = "@#{ivar}"
other.instance_variable_set(ivar, instance_variable_get(ivar))
end
other.docstring = @docstring.to_raw
other
end
# The name of the object
# @param [Boolean] prefix whether to show a prefix. Implement
# this in a subclass to define how the prefix is showed.
# @return [Symbol] if prefix is false, the symbolized name
# @return [String] if prefix is true, prefix + the name as a String.
# This must be implemented by the subclass.
def name(prefix = false)
prefix ? @name.to_s : (defined?(@name) && @name)
end
# Associates a file with a code object, optionally adding the line where it was defined.
# By convention, '' should be used to associate code that comes form standard input.
#
# @param [String] file the filename ('' for standard input)
# @param [Fixnum, nil] line the line number where the object lies in the file
# @param [Boolean] has_comments whether or not the definition has comments associated. This
# will allow {#file} to return the definition where the comments were made instead
# of any empty definitions that might have been parsed before (module namespaces for instance).
def add_file(file, line = nil, has_comments = false)
raise(ArgumentError, "file cannot be nil or empty") if file.nil? || file == ''
obj = [file.to_s, line]
return if files.include?(obj)
if has_comments && !@current_file_has_comments
@current_file_has_comments = true
@files.unshift(obj)
else
@files << obj # back of the line
end
end
# Returns the filename the object was first parsed at, taking
# definitions with docstrings first.
#
# @return [String] a filename
def file
@files.first ? @files.first[0] : nil
end
# Returns the line the object was first parsed at (or nil)
#
# @return [Fixnum] the line where the object was first defined.
# @return [nil] if there is no line associated with the object
def line
@files.first ? @files.first[1] : nil
end
# Tests if another object is equal to this, including a proxy
# @param [Base, Proxy] other if other is a {Proxy}, tests if
# the paths are equal
# @return [Boolean] whether or not the objects are considered the same
def equal?(other)
if other.is_a?(Base) || other.is_a?(Proxy)
path == other.path
else
super
end
end
alias == equal?
alias eql? equal?
# @return [Integer] the object's hash value (for equality checking)
def hash; path.hash end
# @return [nil] this object does not turn into an array
def to_ary; nil end
# Accesses a custom attribute on the object
# @param [#to_s] key the name of the custom attribute
# @return [Object, nil] the custom attribute or nil if not found.
# @see #[]=
def [](key)
if respond_to?(key)
send(key)
elsif instance_variable_defined?("@#{key}")
instance_variable_get("@#{key}")
end
end
# Sets a custom attribute on the object
# @param [#to_s] key the name of the custom attribute
# @param [Object] value the value to associate
# @return [void]
# @see #[]
def []=(key, value)
if respond_to?("#{key}=")
send("#{key}=", value)
else
instance_variable_set("@#{key}", value)
end
end
# @overload dynamic_attr_name
# @return the value of attribute named by the method attribute name
# @raise [NoMethodError] if no method or custom attribute exists by
# the attribute name
# @see #[]
# @overload dynamic_attr_name=(value)
# @param value a value to set
# @return +value+
# @see #[]=
def method_missing(meth, *args, &block)
if meth.to_s =~ /=$/
self[meth.to_s[0..-2]] = args.first
elsif instance_variable_get("@#{meth}")
self[meth]
else
super
end
end
# Attaches source code to a code object with an optional file location
#
# @param [#source, String] statement
# the +Parser::Statement+ holding the source code or the raw source
# as a +String+ for the definition of the code object only (not the block)
def source=(statement)
if statement.respond_to?(:source)
self.signature = statement.first_line
@source = format_source(statement.source.strip)
else
@source = format_source(statement.to_s)
end
end
# The documentation string associated with the object
#
# @param [String, I18n::Locale] locale (I18n::Locale.default)
# the locale of the documentation string.
# @return [Docstring] the documentation string
def docstring(locale = I18n::Locale.default)
if locale.nil?
@docstring.resolve_reference
return @docstring
end
if locale.is_a?(String)
locale_name = locale
locale = nil
else
locale_name = locale.name
end
@docstrings[locale_name] ||=
translate_docstring(locale || Registry.locale(locale_name))
end
# Attaches a docstring to a code object by parsing the comments attached to the statement
# and filling the {#tags} and {#docstring} methods with the parsed information.
#
# @param [String, Array, Docstring] comments
# the comments attached to the code object to be parsed
# into a docstring and meta tags.
def docstring=(comments)
@docstrings.clear
@docstring = Docstring === comments ?
comments : Docstring.new(comments, self)
end
# Default type is the lowercase class name without the "Object" suffix.
# Override this method to provide a custom object type
#
# @return [Symbol] the type of code object this represents
def type
self.class.name.split('::').last.gsub(/Object$/, '').downcase.to_sym
end
# Represents the unique path of the object. The default implementation
# joins the path of {#namespace} with {#name} via the value of {#sep}.
# Custom code objects should ensure that the path is unique to the code
# object by either overriding {#sep} or this method.
#
# @example The path of an instance method
# MethodObject.new(P("A::B"), :c).path # => "A::B#c"
# @return [String] the unique path of the object
# @see #sep
def path
@path ||= if parent && !parent.root?
[parent.path, name.to_s].join(sep)
else
name.to_s
end
end
alias to_s path
# @note
# Override this method if your object has a special title that does
# not match the {#path} attribute value. This title will be used
# when linking or displaying the object.
# @return [String] the display title for an object
# @see 0.8.4
def title
path
end
# @param [Base, String] other another code object (or object path)
# @return [String] the shortest relative path from this object to +other+
# @since 0.5.3
def relative_path(other)
other = Registry.at(other) if String === other && Registry.at(other)
same_parent = false
if other.respond_to?(:path)
same_parent = other.parent == parent
other = other.path
end
return other unless namespace
common = [path, other].join(" ").match(/^(\S*)\S*(?: \1\S*)*$/)[1]
common = path unless common =~ /(\.|::|#)$/
common = common.sub(/(\.|::|#)[^:#\.]*?$/, '') if same_parent
suffix = %w(. :).include?(common[-1, 1]) || other[common.size, 1] == '#' ?
'' : '(::|\.)'
result = other.sub(/^#{Regexp.quote common}#{suffix}/, '')
result.empty? ? other : result
end
# Renders the object using the {Templates::Engine templating system}.
#
# @example Formats a class in plaintext
# puts P('MyClass').format
# @example Formats a method in html with rdoc markup
# puts P('MyClass#meth').format(:format => :html, :markup => :rdoc)
# @param [Hash] options a set of options to pass to the template
# @option options [Symbol] :format (:text) :html, :text or another output format
# @option options [Symbol] :template (:default) a specific template to use
# @option options [Symbol] :markup (nil) the markup type (:rdoc, :markdown, :textile)
# @option options [Serializers::Base] :serializer (nil) see Serializers
# @return [String] the rendered template
# @see Templates::Engine#render
def format(options = {})
options = options.merge(:object => self)
options = options.merge(:type => type) unless options[:type]
Templates::Engine.render(options)
end
# Inspects the object, returning the type and path
# @return [String] a string describing the object
def inspect
"#"
end
# Sets the namespace the object is defined in.
#
# @param [NamespaceObject, :root, nil] obj the new namespace (:root
# for {Registry.root}). If obj is nil, the object is unregistered
# from the Registry.
def namespace=(obj)
if @namespace
@namespace.children.delete(self)
Registry.delete(self)
end
@namespace = (obj == :root ? Registry.root : obj)
if @namespace
reg_obj = Registry.at(path)
return if reg_obj && reg_obj.class == self.class
@namespace.children << self unless @namespace.is_a?(Proxy)
Registry.register(self)
end
end
alias parent namespace
alias parent= namespace=
# Gets a tag from the {#docstring}
# @see Docstring#tag
def tag(name); docstring.tag(name) end
# Gets a list of tags from the {#docstring}
# @see Docstring#tags
def tags(name = nil); docstring.tags(name) end
# Tests if the {#docstring} has a tag
# @see Docstring#has_tag?
def has_tag?(name); docstring.has_tag?(name) end
# Add tags to the {#docstring}
# @see Docstring#add_tag
# @since 0.8.4
def add_tag(*tags)
@docstrings.clear
@docstring.add_tag(*tags)
end
# @return whether or not this object is a RootObject
def root?; false end
# Override this method with a custom component separator. For instance,
# {MethodObject} implements sep as '#' or '.' (depending on if the
# method is instance or class respectively). {#path} depends on this
# value to generate the full path in the form: namespace.path + sep + name
#
# @return [String] the component that separates the namespace path
# and the name (default is {NSEP})
def sep; NSEP end
protected
# Override this method if your code object subclass does not allow
# copying of certain attributes.
#
# @return [Array] the list of instance variable names (without
# "@" prefix) that should be copied when {#copy_to} is called
# @see #copy_to
# @since 0.8.0
def copyable_attributes
vars = instance_variables.map {|ivar| ivar.to_s[1..-1] }
vars -= %w(docstring docstrings namespace name path)
vars
end
private
# Formats source code by removing leading indentation
#
# @param [String] source the source code to format
# @return [String] formatted source
def format_source(source)
source = source.chomp
last = source.split(/\r?\n/).last
indent = last ? last[/^([ \t]*)/, 1].length : 0
source.gsub(/^[ \t]{#{indent}}/, '')
end
def translate_docstring(locale)
@docstring.resolve_reference
return @docstring if locale.nil?
text = I18n::Text.new(@docstring)
localized_text = text.translate(locale)
docstring = Docstring.new(localized_text, self)
docstring.add_tag(*@docstring.tags)
docstring
end
end
end
end
yard-0.9.7/lib/yard/code_objects/namespace_object.rb 0000644 0000041 0000041 00000016355 13035234564 022474 0 ustar www-data www-data # frozen_string_literal: true
module YARD::CodeObjects
register_separator NSEP, :namespace
default_separator NSEP
# A "namespace" is any object that can store other objects within itself.
# The two main Ruby objects that can act as namespaces are modules
# ({ModuleObject}) and classes ({ClassObject}).
class NamespaceObject < Base
# @return [Array] a list of ordered group names inside the namespace
# @since 0.6.0
attr_accessor :groups
# The list of objects defined in this namespace
# @return [Array,
# :write => nil
# },
# :object => {
# :read => #,
# :write => #
# },
# ...
# }
# }
# @return [Hash] a list of methods
attr_reader :attributes
# A hash containing two keys, :class and :instance, each containing
# a hash of objects and their alias names.
# @return [Hash] a list of methods
attr_reader :aliases
# Class mixins
# @return [Array] a list of mixins
attr_reader :class_mixins
# Instance mixins
# @return [Array] a list of mixins
attr_reader :instance_mixins
# Creates a new namespace object inside +namespace+ with +name+.
# @see Base#initialize
def initialize(namespace, name, *args, &block)
@children = CodeObjectList.new(self)
@class_mixins = CodeObjectList.new(self)
@instance_mixins = CodeObjectList.new(self)
@attributes = SymbolHash[:class => SymbolHash.new, :instance => SymbolHash.new]
@aliases = {}
@groups = []
super
end
# Only the class attributes
# @return [Hash] a list of method names and their read/write objects
# @see #attributes
def class_attributes
attributes[:class]
end
# Only the instance attributes
# @return [Hash] a list of method names and their read/write objects
# @see #attributes
def instance_attributes
attributes[:instance]
end
# Looks for a child that matches the attributes specified by +opts+.
#
# @example Finds a child by name and scope
# namespace.child(:name => :to_s, :scope => :instance)
# # => #
# @return [Base, nil] the first matched child object, or nil
def child(opts = {})
if !opts.is_a?(Hash)
children.find {|o| o.name == opts.to_sym }
else
opts = SymbolHash[opts]
children.find do |obj|
opts.each do |meth, value|
break false unless value.is_a?(Array) ? value.include?(obj[meth]) : obj[meth] == value
end
end
end
end
# Returns all methods that match the attributes specified by +opts+. If
# no options are provided, returns all methods.
#
# @example Finds all private and protected class methods
# namespace.meths(:visibility => [:private, :protected], :scope => :class)
# # => [#, #]
# @option opts [Array, Symbol] :visibility ([:public, :private,
# :protected]) the visibility of the methods to list. Can be an array or
# single value.
# @option opts [Array, Symbol] :scope ([:class, :instance]) the
# scope of the methods to list. Can be an array or single value.
# @option opts [Boolean] :included (true) whether to include mixed in
# methods in the list.
# @return [Array] a list of method objects
def meths(opts = {})
opts = SymbolHash[
:visibility => [:public, :private, :protected],
:scope => [:class, :instance],
:included => true
].update(opts)
opts[:visibility] = [opts[:visibility]].flatten
opts[:scope] = [opts[:scope]].flatten
ourmeths = children.select do |o|
o.is_a?(MethodObject) &&
opts[:visibility].include?(o.visibility) &&
opts[:scope].include?(o.scope)
end
ourmeths + (opts[:included] ? included_meths(opts) : [])
end
# Returns methods included from any mixins that match the attributes
# specified by +opts+. If no options are specified, returns all included
# methods.
#
# @option opts [Array, Symbol] :visibility ([:public, :private,
# :protected]) the visibility of the methods to list. Can be an array or
# single value.
# @option opts [Array, Symbol] :scope ([:class, :instance]) the
# scope of the methods to list. Can be an array or single value.
# @option opts [Boolean] :included (true) whether to include mixed in
# methods in the list.
# @see #meths
def included_meths(opts = {})
opts = SymbolHash[:scope => [:instance, :class]].update(opts)
[opts[:scope]].flatten.map do |scope|
mixins(scope).inject([]) do |list, mixin|
next list if mixin.is_a?(Proxy)
arr = mixin.meths(opts.merge(:scope => :instance)).reject do |o|
next false if opts[:all]
child(:name => o.name, :scope => scope) || list.find {|o2| o2.name == o.name }
end
arr.map! {|o| ExtendedMethodObject.new(o) } if scope == :class
list + arr
end
end.flatten
end
# Returns all constants in the namespace
#
# @option opts [Boolean] :included (true) whether or not to include
# mixed in constants in list
# @return [Array] a list of constant objects
def constants(opts = {})
opts = SymbolHash[:included => true].update(opts)
consts = children.select {|o| o.is_a? ConstantObject }
consts + (opts[:included] ? included_constants : [])
end
# Returns constants included from any mixins
# @return [Array] a list of constant objects
def included_constants
instance_mixins.inject([]) do |list, mixin|
if mixin.respond_to? :constants
list += mixin.constants.reject do |o|
child(:name => o.name) || list.find {|o2| o2.name == o.name }
end
else
list
end
end
end
# Returns class variables defined in this namespace.
# @return [Array