Provide a "reference-with-full-name" syntax for Remarkup

Summary:
Provide a {T123} syntax which pulls in the entire name of an object, not just a
link to it. A major use for this is organizing projects using wiki pages. Since
handle links show object status now, this lets you organize stuff in an ad-hoc
way and get a reasonable overview of it. We can make handles richer in the
future, too.

The performance on this isn't perfect (it adds some potential single gets) but I
think it's okay for now and I don't want to make remarkup engine even more
complex until the preprocess/postprocess stuff has had a chance to settle and
I'm more confident it works.

In Differential and Maniphest we'll also incorrectly cache the object
state/name, but that'll fix itself once I move the cache code to use
preprocess/postprocess correctly.

Test Plan:
  - See https://secure.phabricator.com/file/view/PHID-FILE-5f9ca32407bec20899b9/
for an example.
  - Generated and looked over the documentation.

Reviewed By: jungejason
Reviewers: jungejason, tuomaspelkonen, aran, hunterbridges
CC: skrul, aran, jungejason, epriestley
Differential Revision: 784

src/__phutil_library_map__.php

@@ -485,11 +485,14 @@ phutil_register_library_map(array(
     'PhabricatorRedirectController' => 'applications/base/controller/redirect',
     'PhabricatorRefreshCSRFController' => 'applications/auth/controller/refresh',
     'PhabricatorRemarkupRuleDifferential' => 'infrastructure/markup/remarkup/markuprule/differential',
+    'PhabricatorRemarkupRuleDifferentialHandle' => 'infrastructure/markup/remarkup/markuprule/handle/differential',
     'PhabricatorRemarkupRuleDiffusion' => 'infrastructure/markup/remarkup/markuprule/diffusion',
     'PhabricatorRemarkupRuleEmbedFile' => 'infrastructure/markup/remarkup/markuprule/embedobject',
     'PhabricatorRemarkupRuleImageMacro' => 'infrastructure/markup/remarkup/markuprule/imagemacro',
     'PhabricatorRemarkupRuleManiphest' => 'infrastructure/markup/remarkup/markuprule/maniphest',
+    'PhabricatorRemarkupRuleManiphestHandle' => 'infrastructure/markup/remarkup/markuprule/handle/maniphest',
     'PhabricatorRemarkupRuleMention' => 'infrastructure/markup/remarkup/markuprule/mention',
+    'PhabricatorRemarkupRuleObjectHandle' => 'infrastructure/markup/remarkup/markuprule/handle',
     'PhabricatorRemarkupRuleObjectName' => 'infrastructure/markup/remarkup/markuprule/objectname',
     'PhabricatorRemarkupRulePaste' => 'infrastructure/markup/remarkup/markuprule/paste',
     'PhabricatorRemarkupRulePhriction' => 'infrastructure/markup/remarkup/markuprule/phriction',
@@ -1028,11 +1031,14 @@ phutil_register_library_map(array(
     'PhabricatorRedirectController' => 'PhabricatorController',
     'PhabricatorRefreshCSRFController' => 'PhabricatorAuthController',
     'PhabricatorRemarkupRuleDifferential' => 'PhabricatorRemarkupRuleObjectName',
+    'PhabricatorRemarkupRuleDifferentialHandle' => 'PhabricatorRemarkupRuleObjectHandle',
     'PhabricatorRemarkupRuleDiffusion' => 'PhutilRemarkupRule',
     'PhabricatorRemarkupRuleEmbedFile' => 'PhutilRemarkupRule',
     'PhabricatorRemarkupRuleImageMacro' => 'PhutilRemarkupRule',
     'PhabricatorRemarkupRuleManiphest' => 'PhabricatorRemarkupRuleObjectName',
+    'PhabricatorRemarkupRuleManiphestHandle' => 'PhabricatorRemarkupRuleObjectHandle',
     'PhabricatorRemarkupRuleMention' => 'PhutilRemarkupRule',
+    'PhabricatorRemarkupRuleObjectHandle' => 'PhutilRemarkupRule',
     'PhabricatorRemarkupRuleObjectName' => 'PhutilRemarkupRule',
     'PhabricatorRemarkupRulePaste' => 'PhabricatorRemarkupRuleObjectName',
     'PhabricatorRemarkupRulePhriction' => 'PhutilRemarkupRule',

src/applications/markup/engine/PhabricatorMarkupEngine.php

@@ -100,7 +100,11 @@ class PhabricatorMarkupEngine {
 
     $rules[] = new PhutilRemarkupRuleHyperlink();
 
+    $rules[] = new PhabricatorRemarkupRuleDifferentialHandle();
+    $rules[] = new PhabricatorRemarkupRuleManiphestHandle();
+
     $rules[] = new PhabricatorRemarkupRuleEmbedFile();
+
     $rules[] = new PhabricatorRemarkupRuleDifferential();
     $rules[] = new PhabricatorRemarkupRuleDiffusion();
     $rules[] = new PhabricatorRemarkupRuleManiphest();

src/applications/markup/engine/__init__.php

@@ -10,6 +10,8 @@ phutil_require_module('phabricator', 'infrastructure/env');
 phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/differential');
 phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/diffusion');
 phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/embedobject');
+phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/handle/differential');
+phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/handle/maniphest');
 phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/imagemacro');
 phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/maniphest');
 phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/mention');

src/docs/userguide/remarkup.diviner

@@ -11,6 +11,23 @@ other lightweight markup langauges like Markdown and Wiki markup.
 
 This document describes how to format text using Remarkup.
 
+= Quick Reference =
+
+All the syntax is explained in more detail below, but this is a quick guide to
+formatting text in Remarkup:
+
+  **bold** //italic// ##monospaced##
+  = Large Header=
+  == Smaller Header ==
+  > Quoted Text
+  D123 T123 rX123   # Link to Objects
+  {D123} {T123}     # Link to Objects (Full Name)
+  {F123}            # Embed Images
+  [[wiki page]]     # Link to Phriction
+  @username         # Mention a user
+  Indent two spaces for code.
+  Indent two spaces with "-" for lists.
+
 = Basic Styling =
 
 Format **basic text styles** like this:
@@ -103,6 +120,14 @@ You can also link directly to a comment in Maniphest and Differential:
 
   T123#4        # Link to comment #4 of T123
 
+You can also generate full-name references to some objects by using braces:
+
+  {D123}        # Link to Differential revision D123 with the full name
+  {T123}        # Link to Maniphest task T123 with the full name
+
+These references will also show when an object changes state (for instance, a
+task is closed or a revision is committed).
+
 = Quoting Text =
 
 To quote text, preface it with an ">":
@@ -113,6 +138,15 @@ This appears like this:
 
 > This is quoted text.
 
+= Embedding Images =
+
+You can embed an image by using braces to refer to it:
+
+  {F92}         # Embed the image file F92
+
+In most interfaces, you can drag-and-drop an image from your computer into the
+text area to upload and reference it.
+
 = Embedding Media =
 
 If you set configuration flags, you can embed media directly in text:

src/infrastructure/markup/remarkup/markuprule/handle/PhabricatorRemarkupRuleObjectHandle.php

@@ -0,0 +1,82 @@
+<?php
+
+/*
+ * Copyright 2011 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @group markup
+ */
+abstract class PhabricatorRemarkupRuleObjectHandle
+  extends PhutilRemarkupRule {
+
+  const KEY_RULE_HANDLE = 'rule.handle';
+
+  abstract protected function getObjectNamePrefix();
+  abstract protected function loadObjectPHID($id);
+
+  public function apply($text) {
+    $prefix = $this->getObjectNamePrefix();
+    return preg_replace_callback(
+      "@\B{{$prefix}(\d+)}\B@",
+      array($this, 'markupObjectHandle'),
+      $text);
+  }
+
+  private function markupObjectHandle($matches) {
+    // TODO: These are single gets but should be okay for now, they're behind
+    // the cache.
+    $phid = $this->loadObjectPHID($matches[1]);
+    if (!$phid) {
+      return $matches[0];
+    }
+
+    $engine = $this->getEngine();
+    $token = $engine->storeText('');
+
+    $metadata_key = self::KEY_RULE_HANDLE;
+    $metadata = $engine->getTextMetadata($metadata_key, array());
+    if (empty($metadata[$phid])) {
+      $metadata[$phid] = array();
+    }
+    $metadata[$phid][] = $token;
+    $engine->setTextMetadata($metadata_key, $metadata);
+
+    return $token;
+  }
+
+  public function didMarkupText() {
+    $engine = $this->getEngine();
+
+    $metadata_key = self::KEY_RULE_HANDLE;
+    $metadata = $engine->getTextMetadata($metadata_key, array());
+    if (empty($metadata)) {
+      return;
+    }
+
+    $handles = id(new PhabricatorObjectHandleData(array_keys($metadata)))
+      ->loadHandles();
+
+    foreach ($metadata as $phid => $tokens) {
+      $link = $handles[$phid]->renderLink();
+      foreach ($tokens as $token) {
+        $engine->overwriteStoredText($token, $link);
+      }
+    }
+
+    $engine->setTextMetadata($metadata_key, array());
+  }
+
+}

src/infrastructure/markup/remarkup/markuprule/handle/__init__.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * This file is automatically generated. Lint this module to rebuild it.
+ * @generated
+ */
+
+
+
+phutil_require_module('phabricator', 'applications/phid/handle/data');
+
+phutil_require_module('phutil', 'markup/engine/remarkup/markuprule/base');
+phutil_require_module('phutil', 'utils');
+
+
+phutil_require_source('PhabricatorRemarkupRuleObjectHandle.php');

src/infrastructure/markup/remarkup/markuprule/handle/differential/PhabricatorRemarkupRuleDifferentialHandle.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * Copyright 2011 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @group markup
+ */
+final class PhabricatorRemarkupRuleDifferentialHandle
+  extends PhabricatorRemarkupRuleObjectHandle {
+
+  protected function getObjectNamePrefix() {
+    return 'D';
+  }
+
+  protected function loadObjectPHID($id) {
+    $revision = id(new DifferentialRevision())->load($id);
+    if ($revision) {
+      return $revision->getPHID();
+    }
+    return null;
+  }
+
+}

src/infrastructure/markup/remarkup/markuprule/handle/differential/__init__.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * This file is automatically generated. Lint this module to rebuild it.
+ * @generated
+ */
+
+
+
+phutil_require_module('phabricator', 'applications/differential/storage/revision');
+phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/handle');
+
+phutil_require_module('phutil', 'utils');
+
+
+phutil_require_source('PhabricatorRemarkupRuleDifferentialHandle.php');

src/infrastructure/markup/remarkup/markuprule/handle/maniphest/PhabricatorRemarkupRuleManiphestHandle.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * Copyright 2011 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @group markup
+ */
+final class PhabricatorRemarkupRuleManiphestHandle
+  extends PhabricatorRemarkupRuleObjectHandle {
+
+  protected function getObjectNamePrefix() {
+    return 'T';
+  }
+
+  protected function loadObjectPHID($id) {
+    $task = id(new ManiphestTask())->load($id);
+    if ($task) {
+      return $task->getPHID();
+    }
+    return null;
+  }
+
+}

src/infrastructure/markup/remarkup/markuprule/handle/maniphest/__init__.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * This file is automatically generated. Lint this module to rebuild it.
+ * @generated
+ */
+
+
+
+phutil_require_module('phabricator', 'applications/maniphest/storage/task');
+phutil_require_module('phabricator', 'infrastructure/markup/remarkup/markuprule/handle');
+
+phutil_require_module('phutil', 'utils');
+
+
+phutil_require_source('PhabricatorRemarkupRuleManiphestHandle.php');