No OneTemporary
Actions

Size

41 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/applications/diviner/controller/DivinerAtomController.php b/src/applications/diviner/controller/DivinerAtomController.php
	index 10ebcccb3e..a332b63fab 100644
	--- a/src/applications/diviner/controller/DivinerAtomController.php
	+++ b/src/applications/diviner/controller/DivinerAtomController.php
	@@ -1,679 +1,695 @@
	<?php

	final class DivinerAtomController extends DivinerController {

	private $bookName;
	private $atomType;
	private $atomName;
	private $atomContext;
	private $atomIndex;

	public function shouldAllowPublic() {
	return true;
	}

	public function willProcessRequest(array $data) {
	$this->bookName = $data['book'];
	$this->atomType = $data['type'];
	$this->atomName = $data['name'];
	$this->atomContext = nonempty(idx($data, 'context'), null);
	$this->atomIndex = nonempty(idx($data, 'index'), null);
	}

	public function processRequest() {
	$request = $this->getRequest();
	$viewer = $request->getUser();

	require_celerity_resource('diviner-shared-css');

	$book = id(new DivinerBookQuery())
	->setViewer($viewer)
	->withNames(array($this->bookName))
	->executeOne();

	if (!$book) {
	return new Aphront404Response();
	}

	- // TODO: This query won't load ghosts, because they'll fail `needAtoms()`.
	- // Instead, we might want to load ghosts and render a message like
	- // "this thing existed in an older version, but no longer does", especially
	- // if we add content like comments.
	-
	$symbol = id(new DivinerAtomQuery())
	->setViewer($viewer)
	->withBookPHIDs(array($book->getPHID()))
	->withTypes(array($this->atomType))
	->withNames(array($this->atomName))
	->withContexts(array($this->atomContext))
	->withIndexes(array($this->atomIndex))
	- ->withGhosts(false)
	->withIsDocumentable(true)
	->needAtoms(true)
	->needExtends(true)
	->needChildren(true)
	->executeOne();

	if (!$symbol) {
	return new Aphront404Response();
	}

	$atom = $symbol->getAtom();
	$crumbs = $this->buildApplicationCrumbs();
	$crumbs->setBorder(true);

	$crumbs->addTextCrumb(
	$book->getShortTitle(),
	'/book/'.$book->getName().'/');

	- $atom_short_title = $atom->getDocblockMetaValue(
	- 'short',
	- $symbol->getTitle());
	+ $atom_short_title = $atom
	+ ? $atom->getDocblockMetaValue('short', $symbol->getTitle())
	+ : $symbol->getTitle();

	$crumbs->addTextCrumb($atom_short_title);

	$header = id(new PHUIHeaderView())
	->setHeader($this->renderFullSignature($symbol))
	->addTag(
	id(new PHUITagView())
	->setType(PHUITagView::TYPE_STATE)
	->setBackgroundColor(PHUITagView::COLOR_BLUE)
	- ->setName(DivinerAtom::getAtomTypeNameString($atom->getType())));
	+ ->setName(DivinerAtom::getAtomTypeNameString(
	+ $atom ? $atom->getType() : $symbol->getType())));

	$properties = id(new PHUIPropertyListView());

	- $group = $atom->getProperty('group');
	+ $group = $atom ? $atom->getProperty('group') : $symbol->getGroupName();
	if ($group) {
	$group_name = $book->getGroupName($group);
	} else {
	$group_name = null;
	}

	- $this->buildDefined($properties, $symbol);
	- $this->buildExtendsAndImplements($properties, $symbol);
	+ $document = id(new PHUIDocumentView())
	+ ->setBook($book->getTitle(), $group_name)
	+ ->setHeader($header)
	+ ->addClass('diviner-view')
	+ ->setFontKit(PHUIDocumentView::FONT_SOURCE_SANS)
	+ ->appendChild($properties);
	+
	+ if ($atom) {
	+ $this->buildDefined($properties, $symbol);
	+ $this->buildExtendsAndImplements($properties, $symbol);
	+
	+ $warnings = $atom->getWarnings();
	+ if ($warnings) {
	+ $warnings = id(new PHUIInfoView())
	+ ->setErrors($warnings)
	+ ->setTitle(pht('Documentation Warnings'))
	+ ->setSeverity(PHUIInfoView::SEVERITY_WARNING);
	+ }

	- $warnings = $atom->getWarnings();
	- if ($warnings) {
	- $warnings = id(new PHUIInfoView())
	- ->setErrors($warnings)
	- ->setTitle(pht('Documentation Warnings'))
	- ->setSeverity(PHUIInfoView::SEVERITY_WARNING);
	+ $document->appendChild($warnings);
	}

	$methods = $this->composeMethods($symbol);

	$field = 'default';
	$engine = id(new PhabricatorMarkupEngine())
	->setViewer($viewer)
	->addObject($symbol, $field);
	foreach ($methods as $method) {
	foreach ($method['atoms'] as $matom) {
	$engine->addObject($matom, $field);
	}
	}
	$engine->process();

	- $content = $this->renderDocumentationText($symbol, $engine);
	+ if ($atom) {
	+ $content = $this->renderDocumentationText($symbol, $engine);
	+ $document->appendChild($content);
	+ }

	$toc = $engine->getEngineMetadata(
	$symbol,
	$field,
	PhutilRemarkupHeaderBlockRule::KEY_HEADER_TOC,
	array());

	- $document = id(new PHUIDocumentView())
	- ->setBook($book->getTitle(), $group_name)
	- ->setHeader($header)
	- ->addClass('diviner-view')
	- ->setFontKit(PHUIDocumentView::FONT_SOURCE_SANS)
	- ->appendChild($properties)
	- ->appendChild($warnings)
	- ->appendChild($content);
	+ if (!$atom) {
	+ $document->appendChild(
	+ id(new PHUIInfoView())
	+ ->setSeverity(PHUIInfoView::SEVERITY_NOTICE)
	+ ->appendChild(
	+ pht(
	+ 'This atom no longer exists.')));
	+ }

	- $document->appendChild($this->buildParametersAndReturn(array($symbol)));
	+ if ($atom) {
	+ $document->appendChild($this->buildParametersAndReturn(array($symbol)));
	+ }

	if ($methods) {
	$tasks = $this->composeTasks($symbol);

	if ($tasks) {
	$methods_by_task = igroup($methods, 'task');

	// Add phantom tasks for methods which have a "@task" name that isn't
	// documented anywhere, or methods that have no "@task" name.
	foreach ($methods_by_task as $task => $ignored) {
	if (empty($tasks[$task])) {
	$tasks[$task] = array(
	'name' => $task,
	'title' => $task ? $task : pht('Other Methods'),
	'defined' => $symbol,
	);
	}
	}

	$section = id(new DivinerSectionView())
	->setHeader(pht('Tasks'));

	foreach ($tasks as $spec) {
	$section->addContent(
	id(new PHUIHeaderView())
	->setNoBackground(true)
	->setHeader($spec['title']));

	$task_methods = idx($methods_by_task, $spec['name'], array());
	$inner_box = id(new PHUIBoxView())
	->addPadding(PHUI::PADDING_LARGE_LEFT)
	->addPadding(PHUI::PADDING_LARGE_RIGHT)
	->addPadding(PHUI::PADDING_LARGE_BOTTOM);

	$box_content = array();
	if ($task_methods) {
	$list_items = array();
	foreach ($task_methods as $task_method) {
	$atom = last($task_method['atoms']);

	$item = $this->renderFullSignature($atom, true);

	if (strlen($atom->getSummary())) {
	$item = array(
	$item,
	" \xE2\x80\x94 ",
	$atom->getSummary(),
	);
	}

	$list_items[] = phutil_tag('li', array(), $item);
	}

	$box_content[] = phutil_tag(
	'ul',
	array(
	'class' => 'diviner-list',
	),
	$list_items);
	} else {
	$no_methods = pht('No methods for this task.');
	$box_content = phutil_tag('em', array(), $no_methods);
	}

	$inner_box->appendChild($box_content);
	$section->addContent($inner_box);
	}
	$document->appendChild($section);
	}

	$section = id(new DivinerSectionView())
	- ->setHeader(pht('Methods'));
	+ ->setHeader(pht('Methods'));

	foreach ($methods as $spec) {
	$matom = last($spec['atoms']);
	$method_header = id(new PHUIHeaderView())
	->setNoBackground(true);

	$inherited = $spec['inherited'];
	if ($inherited) {
	$method_header->addTag(
	id(new PHUITagView())
	->setType(PHUITagView::TYPE_STATE)
	->setBackgroundColor(PHUITagView::COLOR_GREY)
	->setName(pht('Inherited')));
	}

	$method_header->setHeader($this->renderFullSignature($matom));

	$section->addContent(
	array(
	$method_header,
	$this->renderMethodDocumentationText($symbol, $spec, $engine),
	$this->buildParametersAndReturn($spec['atoms']),
	));
	}
	$document->appendChild($section);
	}

	if ($toc) {
	$side = new PHUIListView();
	$side->addMenuItem(
	id(new PHUIListItemView())
	->setName(pht('Contents'))
	->setType(PHUIListItemView::TYPE_LABEL));
	foreach ($toc as $key => $entry) {
	$side->addMenuItem(
	id(new PHUIListItemView())
	->setName($entry[1])
	->setHref('#'.$key));
	}

	$document->setSideNav($side, PHUIDocumentView::NAV_TOP);
	}

	return $this->buildApplicationPage(
	array(
	$crumbs,
	$document,
	),
	array(
	'title' => $symbol->getTitle(),
	));
	}

	private function buildExtendsAndImplements(
	PHUIPropertyListView $view,
	DivinerLiveSymbol $symbol) {

	$lineage = $this->getExtendsLineage($symbol);
	if ($lineage) {
	$tags = array();
	foreach ($lineage as $item) {
	$tags[] = $this->renderAtomTag($item);
	}

	$caret = phutil_tag('span', array('class' => 'caret-right msl msr'));
	$tags = phutil_implode_html($caret, $tags);
	$view->addProperty(pht('Extends'), $tags);
	}

	$implements = $this->getImplementsLineage($symbol);
	if ($implements) {
	$items = array();
	foreach ($implements as $spec) {
	$via = $spec['via'];
	$iface = $spec['interface'];
	if ($via == $symbol) {
	$items[] = $this->renderAtomTag($iface);
	} else {
	$items[] = array(
	$this->renderAtomTag($iface),
	" \xE2\x97\x80 ",
	$this->renderAtomTag($via),
	);
	}
	}

	$view->addProperty(
	pht('Implements'),
	phutil_implode_html(phutil_tag('br'), $items));
	}

	}

	private function renderAtomTag(DivinerLiveSymbol $symbol) {
	return id(new PHUITagView())
	->setType(PHUITagView::TYPE_OBJECT)
	->setName($symbol->getName())
	->setHref($symbol->getURI());
	}

	private function getExtendsLineage(DivinerLiveSymbol $symbol) {
	foreach ($symbol->getExtends() as $extends) {
	if ($extends->getType() == 'class') {
	$lineage = $this->getExtendsLineage($extends);
	$lineage[] = $extends;
	return $lineage;
	}
	}
	return array();
	}

	private function getImplementsLineage(DivinerLiveSymbol $symbol) {
	$implements = array();

	// Do these first so we get interfaces ordered from most to least specific.
	foreach ($symbol->getExtends() as $extends) {
	if ($extends->getType() == 'interface') {
	$implements[$extends->getName()] = array(
	'interface' => $extends,
	'via' => $symbol,
	);
	}
	}

	// Now do parent interfaces.
	foreach ($symbol->getExtends() as $extends) {
	if ($extends->getType() == 'class') {
	$implements += $this->getImplementsLineage($extends);
	}
	}

	return $implements;
	}

	private function buildDefined(
	PHUIPropertyListView $view,
	DivinerLiveSymbol $symbol) {

	$atom = $symbol->getAtom();
	$defined = $atom->getFile().':'.$atom->getLine();

	$link = $symbol->getBook()->getConfig('uri.source');
	if ($link) {
	$link = strtr(
	$link,
	array(
	'%%' => '%',
	'%f' => phutil_escape_uri($atom->getFile()),
	'%l' => phutil_escape_uri($atom->getLine()),
	));
	$defined = phutil_tag(
	'a',
	array(
	'href' => $link,
	'target' => '_blank',
	),
	$defined);
	}

	$view->addProperty(pht('Defined'), $defined);
	}

	private function composeMethods(DivinerLiveSymbol $symbol) {
	$methods = $this->findMethods($symbol);
	if (!$methods) {
	return $methods;
	}

	foreach ($methods as $name => $method) {
	// Check for "@task" on each parent, to find the most recently declared
	// "@task".
	$task = null;
	foreach ($method['atoms'] as $key => $method_symbol) {
	$atom = $method_symbol->getAtom();
	if ($atom->getDocblockMetaValue('task')) {
	$task = $atom->getDocblockMetaValue('task');
	}
	}
	$methods[$name]['task'] = $task;

	// Set 'inherited' if this atom has no implementation of the method.
	if (last($method['implementations']) !== $symbol) {
	$methods[$name]['inherited'] = true;
	} else {
	$methods[$name]['inherited'] = false;
	}
	}

	return $methods;
	}

	private function findMethods(DivinerLiveSymbol $symbol) {
	$child_specs = array();
	foreach ($symbol->getExtends() as $extends) {
	if ($extends->getType() == DivinerAtom::TYPE_CLASS) {
	$child_specs = $this->findMethods($extends);
	}
	}

	foreach ($symbol->getChildren() as $child) {
	if ($child->getType() == DivinerAtom::TYPE_METHOD) {
	$name = $child->getName();
	if (isset($child_specs[$name])) {
	$child_specs[$name]['atoms'][] = $child;
	$child_specs[$name]['implementations'][] = $symbol;
	} else {
	$child_specs[$name] = array(
	'atoms' => array($child),
	'defined' => $symbol,
	'implementations' => array($symbol),
	);
	}
	}
	}

	return $child_specs;
	}

	private function composeTasks(DivinerLiveSymbol $symbol) {
	$extends_task_specs = array();
	foreach ($symbol->getExtends() as $extends) {
	$extends_task_specs += $this->composeTasks($extends);
	}

	$task_specs = array();

	$tasks = $symbol->getAtom()->getDocblockMetaValue('task');
	if (strlen($tasks)) {
	$tasks = phutil_split_lines($tasks, $retain_endings = false);

	foreach ($tasks as $task) {
	list($name, $title) = explode(' ', $task, 2);
	$name = trim($name);
	$title = trim($title);

	$task_specs[$name] = array(
	'name' => $name,
	'title' => $title,
	'defined' => $symbol,
	);
	}
	}

	$specs = $task_specs + $extends_task_specs;

	// Reorder "@tasks" in original declaration order. Basically, we want to
	// use the documentation of the closest subclass, but put tasks which
	// were declared by parents first.
	$keys = array_keys($extends_task_specs);
	$specs = array_select_keys($specs, $keys) + $specs;

	return $specs;
	}

	private function renderFullSignature(
	DivinerLiveSymbol $symbol,
	$is_link = false) {
	switch ($symbol->getType()) {
	case DivinerAtom::TYPE_CLASS:
	case DivinerAtom::TYPE_INTERFACE:
	case DivinerAtom::TYPE_METHOD:
	case DivinerAtom::TYPE_FUNCTION:
	break;
	default:
	return $symbol->getTitle();
	}

	$atom = $symbol->getAtom();

	$out = array();
	- if ($atom->getProperty('final')) {
	- $out[] = 'final';
	- }

	- if ($atom->getProperty('abstract')) {
	- $out[] = 'abstract';
	- }
	+ if ($atom) {
	+ if ($atom->getProperty('final')) {
	+ $out[] = 'final';
	+ }

	- if ($atom->getProperty('access')) {
	- $out[] = $atom->getProperty('access');
	- }
	+ if ($atom->getProperty('abstract')) {
	+ $out[] = 'abstract';
	+ }
	+
	+ if ($atom->getProperty('access')) {
	+ $out[] = $atom->getProperty('access');
	+ }

	- if ($atom->getProperty('static')) {
	- $out[] = 'static';
	+ if ($atom->getProperty('static')) {
	+ $out[] = 'static';
	+ }
	}

	switch ($symbol->getType()) {
	case DivinerAtom::TYPE_CLASS:
	case DivinerAtom::TYPE_INTERFACE:
	$out[] = $symbol->getType();
	break;
	case DivinerAtom::TYPE_FUNCTION:
	switch ($atom->getLanguage()) {
	case 'php':
	$out[] = $symbol->getType();
	break;
	}
	break;
	case DivinerAtom::TYPE_METHOD:
	switch ($atom->getLanguage()) {
	case 'php':
	$out[] = DivinerAtom::TYPE_FUNCTION;
	break;
	}
	break;
	}

	$anchor = null;
	switch ($symbol->getType()) {
	case DivinerAtom::TYPE_METHOD:
	$anchor = $symbol->getType().'/'.$symbol->getName();
	break;
	default:
	break;
	}

	$out[] = phutil_tag(
	$anchor ? 'a' : 'span',
	array(
	'class' => 'diviner-atom-signature-name',
	'href' => $anchor ? '#'.$anchor : null,
	'name' => $is_link ? null : $anchor,
	),
	$symbol->getName());

	$out = phutil_implode_html(' ', $out);

	- $parameters = $atom->getProperty('parameters');
	- if ($parameters !== null) {
	- $pout = array();
	- foreach ($parameters as $parameter) {
	- $pout[] = idx($parameter, 'name', '...');
	+ if ($atom) {
	+ $parameters = $atom->getProperty('parameters');
	+ if ($parameters !== null) {
	+ $pout = array();
	+ foreach ($parameters as $parameter) {
	+ $pout[] = idx($parameter, 'name', '...');
	+ }
	+ $out = array($out, '('.implode(', ', $pout).')');
	}
	- $out = array($out, '('.implode(', ', $pout).')');
	}

	return phutil_tag(
	'span',
	array(
	'class' => 'diviner-atom-signature',
	),
	$out);
	}

	private function buildParametersAndReturn(array $symbols) {
	assert_instances_of($symbols, 'DivinerLiveSymbol');

	$symbols = array_reverse($symbols);
	$out = array();

	$collected_parameters = null;
	foreach ($symbols as $symbol) {
	$parameters = $symbol->getAtom()->getProperty('parameters');
	if ($parameters !== null) {
	if ($collected_parameters === null) {
	$collected_parameters = array();
	}
	foreach ($parameters as $key => $parameter) {
	if (isset($collected_parameters[$key])) {
	$collected_parameters[$key] += $parameter;
	} else {
	$collected_parameters[$key] = $parameter;
	}
	}
	}
	}

	if (nonempty($parameters)) {
	$out[] = id(new DivinerParameterTableView())
	->setHeader(pht('Parameters'))
	->setParameters($parameters);
	}

	$collected_return = null;
	foreach ($symbols as $symbol) {
	$return = $symbol->getAtom()->getProperty('return');
	if ($return) {
	if ($collected_return) {
	$collected_return += $return;
	} else {
	$collected_return = $return;
	}
	}
	}

	if (nonempty($return)) {
	$out[] = id(new DivinerReturnTableView())
	->setHeader(pht('Return'))
	->setReturn($collected_return);
	}

	return $out;
	}

	private function renderDocumentationText(
	DivinerLiveSymbol $symbol,
	PhabricatorMarkupEngine $engine) {

	$field = 'default';
	$content = $engine->getOutput($symbol, $field);

	if (strlen(trim($symbol->getMarkupText($field)))) {
	$content = phutil_tag(
	'div',
	array(
	'class' => 'phabricator-remarkup',
	),
	$content);
	} else {
	$atom = $symbol->getAtom();
	$content = phutil_tag(
	'div',
	array(
	'class' => 'diviner-message-not-documented',
	),
	DivinerAtom::getThisAtomIsNotDocumentedString($atom->getType()));
	}

	return $content;
	}

	private function renderMethodDocumentationText(
	DivinerLiveSymbol $parent,
	array $spec,
	PhabricatorMarkupEngine $engine) {

	$symbols = array_values($spec['atoms']);
	$implementations = array_values($spec['implementations']);

	$field = 'default';

	$out = array();
	foreach ($symbols as $key => $symbol) {
	$impl = $implementations[$key];
	if ($impl !== $parent) {
	if (!strlen(trim($symbol->getMarkupText($field)))) {
	continue;
	}
	}

	$doc = $this->renderDocumentationText($symbol, $engine);

	if (($impl !== $parent) \|\| $out) {
	$where = id(new PHUIBoxView())
	->addPadding(PHUI::PADDING_MEDIUM_LEFT)
	->addPadding(PHUI::PADDING_MEDIUM_RIGHT)
	->addClass('diviner-method-implementation-header')
	->appendChild($impl->getName());
	$doc = array($where, $doc);

	if ($impl !== $parent) {
	$doc = phutil_tag(
	'div',
	array(
	'class' => 'diviner-method-implementation-inherited',
	),
	$doc);
	}
	}

	$out[] = $doc;
	}

	// If we only have inherited implementations but none have documentation,
	// render the last one here so we get the "this thing has no documentation"
	// element.
	if (!$out) {
	$out[] = $this->renderDocumentationText($symbol, $engine);
	}

	return $out;
	}

	}
	diff --git a/src/applications/diviner/query/DivinerAtomQuery.php b/src/applications/diviner/query/DivinerAtomQuery.php
	index 4af0f1b1fa..e01df2022d 100644
	--- a/src/applications/diviner/query/DivinerAtomQuery.php
	+++ b/src/applications/diviner/query/DivinerAtomQuery.php
	@@ -1,446 +1,465 @@
	<?php

	final class DivinerAtomQuery extends PhabricatorCursorPagedPolicyAwareQuery {

	private $ids;
	private $phids;
	private $bookPHIDs;
	private $names;
	private $types;
	private $contexts;
	private $indexes;
	private $isDocumentable;
	private $isGhost;
	private $nodeHashes;
	private $titles;
	private $nameContains;

	private $needAtoms;
	private $needExtends;
	private $needChildren;

	public function withIDs(array $ids) {
	$this->ids = $ids;
	return $this;
	}

	public function withPHIDs(array $phids) {
	$this->phids = $phids;
	return $this;
	}

	public function withBookPHIDs(array $phids) {
	$this->bookPHIDs = $phids;
	return $this;
	}

	public function withTypes(array $types) {
	$this->types = $types;
	return $this;
	}

	public function withNames(array $names) {
	$this->names = $names;
	return $this;
	}

	public function withContexts(array $contexts) {
	$this->contexts = $contexts;
	return $this;
	}

	public function withIndexes(array $indexes) {
	$this->indexes = $indexes;
	return $this;
	}

	public function withNodeHashes(array $hashes) {
	$this->nodeHashes = $hashes;
	return $this;
	}

	public function withTitles($titles) {
	$this->titles = $titles;
	return $this;
	}

	public function withNameContains($text) {
	$this->nameContains = $text;
	return $this;
	}

	public function needAtoms($need) {
	$this->needAtoms = $need;
	return $this;
	}

	public function needChildren($need) {
	$this->needChildren = $need;
	return $this;
	}


	/**
	* Include or exclude "ghosts", which are symbols which used to exist but do
	* not exist currently (for example, a function which existed in an older
	* version of the codebase but was deleted).
	*
	* These symbols had PHIDs assigned to them, and may have other sorts of
	* metadata that we don't want to lose (like comments or flags), so we don't
	* delete them outright. They might also come back in the future: the change
	* which deleted the symbol might be reverted, or the documentation might
	* have been generated incorrectly by accident. In these cases, we can
	* restore the original data.
	*
	* @param bool
	* @return this
	*/
	public function withGhosts($ghosts) {
	$this->isGhost = $ghosts;
	return $this;
	}

	public function needExtends($need) {
	$this->needExtends = $need;
	return $this;
	}

	public function withIsDocumentable($documentable) {
	$this->isDocumentable = $documentable;
	return $this;
	}

	protected function loadPage() {
	$table = new DivinerLiveSymbol();
	$conn_r = $table->establishConnection('r');

	$data = queryfx_all(
	$conn_r,
	'SELECT * FROM %T %Q %Q %Q',
	$table->getTableName(),
	$this->buildWhereClause($conn_r),
	$this->buildOrderClause($conn_r),
	$this->buildLimitClause($conn_r));

	return $table->loadAllFromArray($data);
	}

	protected function willFilterPage(array $atoms) {
	$books = array_unique(mpull($atoms, 'getBookPHID'));

	$books = id(new DivinerBookQuery())
	->setViewer($this->getViewer())
	->withPHIDs($books)
	->execute();
	$books = mpull($books, null, 'getPHID');

	foreach ($atoms as $key => $atom) {
	$book = idx($books, $atom->getBookPHID());
	if (!$book) {
	unset($atoms[$key]);
	continue;
	}
	$atom->attachBook($book);
	}

	if ($this->needAtoms) {
	$atom_data = id(new DivinerLiveAtom())->loadAllWhere(
	'symbolPHID IN (%Ls)',
	mpull($atoms, 'getPHID'));
	$atom_data = mpull($atom_data, null, 'getSymbolPHID');

	foreach ($atoms as $key => $atom) {
	$data = idx($atom_data, $atom->getPHID());
	- if (!$data) {
	- unset($atoms[$key]);
	- continue;
	- }
	$atom->attachAtom($data);
	}
	}

	// Load all of the symbols this symbol extends, recursively. Commonly,
	// this means all the ancestor classes and interfaces it extends and
	// implements.

	if ($this->needExtends) {

	// First, load all the matching symbols by name. This does 99% of the
	// work in most cases, assuming things are named at all reasonably.

	$names = array();
	foreach ($atoms as $atom) {
	+ if (!$atom->getAtom()) {
	+ continue;
	+ }
	+
	foreach ($atom->getAtom()->getExtends() as $xref) {
	$names[] = $xref->getName();
	}
	}

	if ($names) {
	$xatoms = id(new DivinerAtomQuery())
	->setViewer($this->getViewer())
	->withNames($names)
	->needExtends(true)
	->needAtoms(true)
	->needChildren($this->needChildren)
	->execute();
	$xatoms = mgroup($xatoms, 'getName', 'getType', 'getBookPHID');
	} else {
	$xatoms = array();
	}

	foreach ($atoms as $atom) {
	- $alang = $atom->getAtom()->getLanguage();
	+ $atom_lang = null;
	+ $atom_extends = array();
	+
	+ if ($atom->getAtom()) {
	+ $atom_lang = $atom->getAtom()->getLanguage();
	+ $atom_extends = $atom->getAtom()->getExtends();
	+ }
	+
	$extends = array();
	- foreach ($atom->getAtom()->getExtends() as $xref) {

	+ foreach ($atom_extends as $xref) {
	// If there are no symbols of the matching name and type, we can't
	// resolve this.
	if (empty($xatoms[$xref->getName()][$xref->getType()])) {
	continue;
	}

	// If we found matches in the same documentation book, prefer them
	// over other matches. Otherwise, look at all the the matches.
	$matches = $xatoms[$xref->getName()][$xref->getType()];
	if (isset($matches[$atom->getBookPHID()])) {
	$maybe = $matches[$atom->getBookPHID()];
	} else {
	$maybe = array_mergev($matches);
	}

	if (!$maybe) {
	continue;
	}

	// Filter out matches in a different language, since, e.g., PHP
	// classes can not implement JS classes.
	$same_lang = array();
	foreach ($maybe as $xatom) {
	- if ($xatom->getAtom()->getLanguage() == $alang) {
	+ if ($xatom->getAtom()->getLanguage() == $atom_lang) {
	$same_lang[] = $xatom;
	}
	}

	if (!$same_lang) {
	continue;
	}

	// If we have duplicates remaining, just pick the first one. There's
	// nothing more we can do to figure out which is the real one.
	$extends[] = head($same_lang);
	}

	$atom->attachExtends($extends);
	}
	}

	if ($this->needChildren) {
	$child_hashes = $this->getAllChildHashes($atoms, $this->needExtends);

	if ($child_hashes) {
	$children = id(new DivinerAtomQuery())
	->setViewer($this->getViewer())
	->withNodeHashes($child_hashes)
	->needAtoms($this->needAtoms)
	->execute();

	$children = mpull($children, null, 'getNodeHash');
	} else {
	$children = array();
	}

	$this->attachAllChildren($atoms, $children, $this->needExtends);
	}

	return $atoms;
	}

	protected function buildWhereClause(AphrontDatabaseConnection $conn_r) {
	$where = array();

	if ($this->ids) {
	$where[] = qsprintf(
	$conn_r,
	'id IN (%Ld)',
	$this->ids);
	}

	if ($this->phids) {
	$where[] = qsprintf(
	$conn_r,
	'phid IN (%Ls)',
	$this->phids);
	}

	if ($this->bookPHIDs) {
	$where[] = qsprintf(
	$conn_r,
	'bookPHID IN (%Ls)',
	$this->bookPHIDs);
	}

	if ($this->types) {
	$where[] = qsprintf(
	$conn_r,
	'type IN (%Ls)',
	$this->types);
	}

	if ($this->names) {
	$where[] = qsprintf(
	$conn_r,
	'name IN (%Ls)',
	$this->names);
	}

	if ($this->titles) {
	$hashes = array();
	foreach ($this->titles as $title) {
	$slug = DivinerAtomRef::normalizeTitleString($title);
	$hash = PhabricatorHash::digestForIndex($slug);
	$hashes[] = $hash;
	}

	$where[] = qsprintf(
	$conn_r,
	'titleSlugHash in (%Ls)',
	$hashes);
	}

	if ($this->contexts) {
	$with_null = false;
	$contexts = $this->contexts;
	foreach ($contexts as $key => $value) {
	if ($value === null) {
	unset($contexts[$key]);
	$with_null = true;
	continue;
	}
	}

	if ($contexts && $with_null) {
	$where[] = qsprintf(
	$conn_r,
	'context IN (%Ls) OR context IS NULL',
	$contexts);
	} else if ($contexts) {
	$where[] = qsprintf(
	$conn_r,
	'context IN (%Ls)',
	$contexts);
	} else if ($with_null) {
	$where[] = qsprintf(
	$conn_r,
	'context IS NULL');
	}
	}

	if ($this->indexes) {
	$where[] = qsprintf(
	$conn_r,
	'atomIndex IN (%Ld)',
	$this->indexes);
	}

	if ($this->isDocumentable !== null) {
	$where[] = qsprintf(
	$conn_r,
	'isDocumentable = %d',
	(int)$this->isDocumentable);
	}

	if ($this->isGhost !== null) {
	if ($this->isGhost) {
	$where[] = qsprintf($conn_r, 'graphHash IS NULL');
	} else {
	$where[] = qsprintf($conn_r, 'graphHash IS NOT NULL');
	}
	}

	if ($this->nodeHashes) {
	$where[] = qsprintf(
	$conn_r,
	'nodeHash IN (%Ls)',
	$this->nodeHashes);
	}

	if ($this->nameContains) {
	// NOTE: This CONVERT() call makes queries case-insensitive, since the
	// column has binary collation. Eventually, this should move into
	// fulltext.

	$where[] = qsprintf(
	$conn_r,
	'CONVERT(name USING utf8) LIKE %~',
	$this->nameContains);
	}

	$where[] = $this->buildPagingClause($conn_r);

	return $this->formatWhereClause($where);
	}


	/**
	* Walk a list of atoms and collect all the node hashes of the atoms'
	* children. When recursing, also walk up the tree and collect children of
	* atoms they extend.
	*
	* @param list<DivinerLiveSymbol> List of symbols to collect child hashes of.
	* @param bool True to collect children of extended atoms,
	* as well.
	* @return map<string, string> Hashes of atoms' children.
	*/
	private function getAllChildHashes(array $symbols, $recurse_up) {
	assert_instances_of($symbols, 'DivinerLiveSymbol');

	$hashes = array();
	foreach ($symbols as $symbol) {
	- foreach ($symbol->getAtom()->getChildHashes() as $hash) {
	+ $child_hashes = array();
	+
	+ if ($symbol->getAtom()) {
	+ $child_hashes = $symbol->getAtom()->getChildHashes();
	+ }
	+
	+ foreach ($child_hashes as $hash) {
	$hashes[$hash] = $hash;
	}
	if ($recurse_up) {
	$hashes += $this->getAllChildHashes($symbol->getExtends(), true);
	}
	}

	return $hashes;
	}


	/**
	* Attach child atoms to existing atoms. In recursive mode, also attach child
	* atoms to atoms that these atoms extend.
	*
	* @param list<DivinerLiveSymbol> List of symbols to attach children to.
	* @param map<string, DivinerLiveSymbol> Map of symbols, keyed by node hash.
	* @param bool True to attach children to extended atoms, as well.
	* @return void
	*/
	private function attachAllChildren(
	array $symbols,
	array $children,
	$recurse_up) {

	assert_instances_of($symbols, 'DivinerLiveSymbol');
	assert_instances_of($children, 'DivinerLiveSymbol');

	foreach ($symbols as $symbol) {
	+ $child_hashes = array();
	$symbol_children = array();
	- foreach ($symbol->getAtom()->getChildHashes() as $hash) {
	+
	+ if ($symbol->getAtom()) {
	+ $child_hashes = $symbol->getAtom()->getChildHashes();
	+ }
	+
	+ foreach ($child_hashes as $hash) {
	if (isset($children[$hash])) {
	$symbol_children[] = $children[$hash];
	}
	}
	$symbol->attachChildren($symbol_children);
	if ($recurse_up) {
	$this->attachAllChildren($symbol->getExtends(), $children, true);
	}
	}
	}

	public function getQueryApplicationClass() {
	return 'PhabricatorDivinerApplication';
	}

	}
	diff --git a/src/applications/diviner/storage/DivinerLiveSymbol.php b/src/applications/diviner/storage/DivinerLiveSymbol.php
	index ba35eed255..dc53b24f08 100644
	--- a/src/applications/diviner/storage/DivinerLiveSymbol.php
	+++ b/src/applications/diviner/storage/DivinerLiveSymbol.php
	@@ -1,266 +1,274 @@
	<?php

	final class DivinerLiveSymbol extends DivinerDAO
	implements
	PhabricatorPolicyInterface,
	PhabricatorMarkupInterface,
	PhabricatorDestructibleInterface {

	protected $bookPHID;
	protected $context;
	protected $type;
	protected $name;
	protected $atomIndex;
	protected $graphHash;
	protected $identityHash;
	protected $nodeHash;

	protected $title;
	protected $titleSlugHash;
	protected $groupName;
	protected $summary;
	protected $isDocumentable = 0;

	private $book = self::ATTACHABLE;
	private $atom = self::ATTACHABLE;
	private $extends = self::ATTACHABLE;
	private $children = self::ATTACHABLE;

	protected function getConfiguration() {
	return array(
	self::CONFIG_AUX_PHID => true,
	self::CONFIG_TIMESTAMPS => false,
	self::CONFIG_COLUMN_SCHEMA => array(
	'context' => 'text255?',
	'type' => 'text32',
	'name' => 'text255',
	'atomIndex' => 'uint32',
	'identityHash' => 'bytes12',
	'graphHash' => 'text64?',
	'title' => 'text?',
	'titleSlugHash' => 'bytes12?',
	'groupName' => 'text255?',
	'summary' => 'text?',
	'isDocumentable' => 'bool',
	'nodeHash' => 'text64?',
	),
	self::CONFIG_KEY_SCHEMA => array(
	'key_phid' => null,
	'identityHash' => array(
	'columns' => array('identityHash'),
	'unique' => true,
	),
	'phid' => array(
	'columns' => array('phid'),
	'unique' => true,
	),
	'graphHash' => array(
	'columns' => array('graphHash'),
	'unique' => true,
	),
	'nodeHash' => array(
	'columns' => array('nodeHash'),
	'unique' => true,
	),
	'bookPHID' => array(
	'columns' => array(
	'bookPHID',
	'type',
	'name(64)',
	'context(64)',
	'atomIndex',
	),
	),
	'name' => array(
	'columns' => array('name(64)'),
	),
	'key_slug' => array(
	'columns' => array('titleSlugHash'),
	),
	),
	) + parent::getConfiguration();
	}

	public function generatePHID() {
	return PhabricatorPHID::generateNewPHID(DivinerAtomPHIDType::TYPECONST);
	}

	public function getBook() {
	return $this->assertAttached($this->book);
	}

	public function attachBook(DivinerLiveBook $book) {
	$this->book = $book;
	return $this;
	}

	public function getAtom() {
	return $this->assertAttached($this->atom);
	}

	- public function attachAtom(DivinerLiveAtom $atom) {
	- $this->atom = DivinerAtom::newFromDictionary($atom->getAtomData());
	+ public function attachAtom(DivinerLiveAtom $atom = null) {
	+ if ($atom === null) {
	+ $this->atom = null;
	+ } else {
	+ $this->atom = DivinerAtom::newFromDictionary($atom->getAtomData());
	+ }
	return $this;
	}

	public function getURI() {
	$parts = array(
	'book',
	$this->getBook()->getName(),
	$this->getType(),
	);

	if ($this->getContext()) {
	$parts[] = $this->getContext();
	}

	$parts[] = $this->getName();

	if ($this->getAtomIndex()) {
	$parts[] = $this->getAtomIndex();
	}

	return '/'.implode('/', $parts).'/';
	}

	public function getSortKey() {
	// Sort articles before other types of content. Then, sort atoms in a
	// case-insensitive way.
	return sprintf(
	'%c:%s',
	($this->getType() == DivinerAtom::TYPE_ARTICLE ? '0' : '1'),
	phutil_utf8_strtolower($this->getTitle()));
	}

	public function save() {

	// NOTE: The identity hash is just a sanity check because the unique tuple
	// on this table is way way too long to fit into a normal UNIQUE KEY. We
	// don't use it directly, but its existence prevents duplicate records.

	if (!$this->identityHash) {
	$this->identityHash = PhabricatorHash::digestForIndex(
	serialize(
	array(
	'bookPHID' => $this->getBookPHID(),
	'context' => $this->getContext(),
	'type' => $this->getType(),
	'name' => $this->getName(),
	'index' => $this->getAtomIndex(),
	)));
	}

	return parent::save();
	}

	public function getTitle() {
	$title = parent::getTitle();
	if (!strlen($title)) {
	$title = $this->getName();
	}
	return $title;
	}

	public function setTitle($value) {
	$this->writeField('title', $value);
	if (strlen($value)) {
	$slug = DivinerAtomRef::normalizeTitleString($value);
	$hash = PhabricatorHash::digestForIndex($slug);
	$this->titleSlugHash = $hash;
	} else {
	$this->titleSlugHash = null;
	}
	return $this;
	}

	public function attachExtends(array $extends) {
	assert_instances_of($extends, __CLASS__);
	$this->extends = $extends;
	return $this;
	}

	public function getExtends() {
	return $this->assertAttached($this->extends);
	}

	public function attachChildren(array $children) {
	assert_instances_of($children, __CLASS__);
	$this->children = $children;
	return $this;
	}

	public function getChildren() {
	return $this->assertAttached($this->children);
	}


	/* -( PhabricatorPolicyInterface )----------------------------------------- */

	public function getCapabilities() {
	return $this->getBook()->getCapabilities();
	}


	public function getPolicy($capability) {
	return $this->getBook()->getPolicy($capability);
	}


	public function hasAutomaticCapability($capability, PhabricatorUser $viewer) {
	return $this->getBook()->hasAutomaticCapability($capability, $viewer);
	}

	public function describeAutomaticCapability($capability) {
	return pht('Atoms inherit the policies of the books they are part of.');
	}


	/* -( Markup Interface )--------------------------------------------------- */


	public function getMarkupFieldKey($field) {
	return $this->getPHID().':'.$field.':'.$this->getGraphHash();
	}


	public function newMarkupEngine($field) {
	return PhabricatorMarkupEngine::getEngine('diviner');
	}


	public function getMarkupText($field) {
	+ if (!$this->getAtom()) {
	+ return;
	+ }
	+
	return $this->getAtom()->getDocblockText();
	}


	public function didMarkupText(
	$field,
	$output,
	PhutilMarkupEngine $engine) {
	return $output;
	}


	public function shouldUseMarkupCache($field) {
	return true;
	}

	/* -( PhabricatorDestructibleInterface )----------------------------------- */

	public function destroyObjectPermanently(
	PhabricatorDestructionEngine $engine) {

	$this->openTransaction();
	$conn_w = $this->establishConnection('w');

	queryfx(
	$conn_w,
	'DELETE FROM %T WHERE symbolPHID = %s',
	id(new DivinerLiveAtom())->getTableName(),
	$this->getPHID());

	$this->delete();
	$this->saveTransaction();
	}

	}

File Metadata

Mime Type: text/x-diff
Expires: Mon, Dec 1, 8:31 AM (1 d, 12 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 430307
Default Alt Text: (41 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions