[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  final class DivinerAtom {
   4  
   5    const TYPE_FILE      = 'file';
   6    const TYPE_ARTICLE   = 'article';
   7    const TYPE_METHOD    = 'method';
   8    const TYPE_CLASS     = 'class';
   9    const TYPE_FUNCTION  = 'function';
  10    const TYPE_INTERFACE = 'interface';
  11  
  12    private $type;
  13    private $name;
  14    private $file;
  15    private $line;
  16    private $hash;
  17    private $contentRaw;
  18    private $length;
  19    private $language;
  20    private $docblockRaw;
  21    private $docblockText;
  22    private $docblockMeta;
  23    private $warnings = array();
  24    private $parent;
  25    private $parentHash;
  26    private $children = array();
  27    private $childHashes = array();
  28    private $context;
  29    private $extends = array();
  30    private $links = array();
  31    private $book;
  32    private $properties = array();
  33  
  34    /**
  35     * Returns a sorting key which imposes an unambiguous, stable order on atoms.
  36     */
  37    public function getSortKey() {
  38      return implode(
  39        "\0",
  40        array(
  41          $this->getBook(),
  42          $this->getType(),
  43          $this->getContext(),
  44          $this->getName(),
  45          $this->getFile(),
  46          sprintf('%08', $this->getLine()),
  47        ));
  48    }
  49  
  50    public function setBook($book) {
  51      $this->book = $book;
  52      return $this;
  53    }
  54  
  55    public function getBook() {
  56      return $this->book;
  57    }
  58  
  59    public function setContext($context) {
  60      $this->context = $context;
  61      return $this;
  62    }
  63  
  64    public function getContext() {
  65      return $this->context;
  66    }
  67  
  68    public static function getAtomSerializationVersion() {
  69      return 2;
  70    }
  71  
  72    public function addWarning($warning) {
  73      $this->warnings[] = $warning;
  74      return $this;
  75    }
  76  
  77    public function getWarnings() {
  78      return $this->warnings;
  79    }
  80  
  81    public function setDocblockRaw($docblock_raw) {
  82      $this->docblockRaw = $docblock_raw;
  83  
  84      $parser = new PhutilDocblockParser();
  85      list($text, $meta) = $parser->parse($docblock_raw);
  86      $this->docblockText = $text;
  87      $this->docblockMeta = $meta;
  88  
  89      return $this;
  90    }
  91  
  92    public function getDocblockRaw() {
  93      return $this->docblockRaw;
  94    }
  95  
  96    public function getDocblockText() {
  97      if ($this->docblockText === null) {
  98        throw new Exception('Call setDocblockRaw() before getDocblockText()!');
  99      }
 100      return $this->docblockText;
 101    }
 102  
 103    public function getDocblockMeta() {
 104      if ($this->docblockMeta === null) {
 105        throw new Exception('Call setDocblockRaw() before getDocblockMeta()!');
 106      }
 107      return $this->docblockMeta;
 108    }
 109  
 110    public function getDocblockMetaValue($key, $default = null) {
 111      $meta = $this->getDocblockMeta();
 112      return idx($meta, $key, $default);
 113    }
 114  
 115    public function setDocblockMetaValue($key, $value) {
 116      $meta = $this->getDocblockMeta();
 117      $meta[$key] = $value;
 118      $this->docblockMeta = $meta;
 119      return $this;
 120    }
 121  
 122    public function setType($type) {
 123      $this->type = $type;
 124      return $this;
 125    }
 126  
 127    public function getType() {
 128      return $this->type;
 129    }
 130  
 131    public function setName($name) {
 132      $this->name = $name;
 133      return $this;
 134    }
 135  
 136    public function getName() {
 137      return $this->name;
 138    }
 139  
 140    public function setFile($file) {
 141      $this->file = $file;
 142      return $this;
 143    }
 144  
 145    public function getFile() {
 146      return $this->file;
 147    }
 148  
 149    public function setLine($line) {
 150      $this->line = $line;
 151      return $this;
 152    }
 153  
 154    public function getLine() {
 155      return $this->line;
 156    }
 157  
 158    public function setContentRaw($content_raw) {
 159      $this->contentRaw = $content_raw;
 160      return $this;
 161    }
 162  
 163    public function getContentRaw() {
 164      return $this->contentRaw;
 165    }
 166  
 167    public function setHash($hash) {
 168      $this->hash = $hash;
 169      return $this;
 170    }
 171  
 172    public function addLink(DivinerAtomRef $ref) {
 173      $this->links[] = $ref;
 174      return $this;
 175    }
 176  
 177    public function addExtends(DivinerAtomRef $ref) {
 178      $this->extends[] = $ref;
 179      return $this;
 180    }
 181  
 182    public function getLinkDictionaries() {
 183      return mpull($this->links, 'toDictionary');
 184    }
 185  
 186    public function getExtendsDictionaries() {
 187      return mpull($this->extends, 'toDictionary');
 188    }
 189  
 190    public function getExtends() {
 191      return $this->extends;
 192    }
 193  
 194    public function getHash() {
 195      if ($this->hash) {
 196        return $this->hash;
 197      }
 198  
 199      $parts = array(
 200        $this->getBook(),
 201        $this->getType(),
 202        $this->getName(),
 203        $this->getFile(),
 204        $this->getLine(),
 205        $this->getLength(),
 206        $this->getLanguage(),
 207        $this->getContentRaw(),
 208        $this->getDocblockRaw(),
 209        $this->getProperties(),
 210        $this->getChildHashes(),
 211        mpull($this->extends, 'toHash'),
 212        mpull($this->links, 'toHash'),
 213      );
 214  
 215      $this->hash = md5(serialize($parts)).'N';
 216      return $this->hash;
 217    }
 218  
 219    public function setLength($length) {
 220      $this->length = $length;
 221      return $this;
 222    }
 223  
 224    public function getLength() {
 225      return $this->length;
 226    }
 227  
 228    public function setLanguage($language) {
 229      $this->language = $language;
 230      return $this;
 231    }
 232  
 233    public function getLanguage() {
 234      return $this->language;
 235    }
 236  
 237    public function addChildHash($child_hash) {
 238      $this->childHashes[] = $child_hash;
 239      return $this;
 240    }
 241  
 242    public function getChildHashes() {
 243      if (!$this->childHashes && $this->children) {
 244        $this->childHashes = mpull($this->children, 'getHash');
 245      }
 246      return $this->childHashes;
 247    }
 248  
 249    public function setParentHash($parent_hash) {
 250      if ($this->parentHash) {
 251        throw new Exception('Atom already has a parent!');
 252      }
 253      $this->parentHash = $parent_hash;
 254      return $this;
 255    }
 256  
 257    public function hasParent() {
 258      return $this->parent || $this->parentHash;
 259    }
 260  
 261    public function setParent(DivinerAtom $atom) {
 262      if ($this->parentHash) {
 263        throw new Exception('Parent hash has already been computed!');
 264      }
 265      $this->parent = $atom;
 266      return $this;
 267    }
 268  
 269    public function getParentHash() {
 270      if ($this->parent && !$this->parentHash) {
 271        $this->parentHash = $this->parent->getHash();
 272      }
 273      return $this->parentHash;
 274    }
 275  
 276    public function addChild(DivinerAtom $atom) {
 277      if ($this->childHashes) {
 278        throw new Exception('Child hashes have already been computed!');
 279      }
 280  
 281      $atom->setParent($this);
 282      $this->children[] = $atom;
 283      return $this;
 284    }
 285  
 286    public function getURI() {
 287      $parts = array();
 288      $parts[] = phutil_escape_uri_path_component($this->getType());
 289      if ($this->getContext()) {
 290        $parts[] = phutil_escape_uri_path_component($this->getContext());
 291      }
 292      $parts[] = phutil_escape_uri_path_component($this->getName());
 293      $parts[] = null;
 294      return implode('/', $parts);
 295    }
 296  
 297  
 298    public function toDictionary() {
 299      // NOTE: If you change this format, bump the format version in
 300      // getAtomSerializationVersion().
 301  
 302      return array(
 303        'book'        => $this->getBook(),
 304        'type'        => $this->getType(),
 305        'name'        => $this->getName(),
 306        'file'        => $this->getFile(),
 307        'line'        => $this->getLine(),
 308        'hash'        => $this->getHash(),
 309        'uri'         => $this->getURI(),
 310        'length'      => $this->getLength(),
 311        'context'     => $this->getContext(),
 312        'language'    => $this->getLanguage(),
 313        'docblockRaw' => $this->getDocblockRaw(),
 314        'warnings'    => $this->getWarnings(),
 315        'parentHash'  => $this->getParentHash(),
 316        'childHashes' => $this->getChildHashes(),
 317        'extends'     => $this->getExtendsDictionaries(),
 318        'links'       => $this->getLinkDictionaries(),
 319        'ref'         => $this->getRef()->toDictionary(),
 320        'properties'  => $this->getProperties(),
 321      );
 322    }
 323  
 324    public function getRef() {
 325      $title = null;
 326      if ($this->docblockMeta) {
 327        $title = $this->getDocblockMetaValue('title');
 328      }
 329  
 330      return id(new DivinerAtomRef())
 331        ->setBook($this->getBook())
 332        ->setContext($this->getContext())
 333        ->setType($this->getType())
 334        ->setName($this->getName())
 335        ->setTitle($title)
 336        ->setGroup($this->getProperty('group'));
 337    }
 338  
 339    public static function newFromDictionary(array $dictionary) {
 340      $atom = id(new DivinerAtom())
 341        ->setBook(idx($dictionary, 'book'))
 342        ->setType(idx($dictionary, 'type'))
 343        ->setName(idx($dictionary, 'name'))
 344        ->setFile(idx($dictionary, 'file'))
 345        ->setLine(idx($dictionary, 'line'))
 346        ->setHash(idx($dictionary, 'hash'))
 347        ->setLength(idx($dictionary, 'length'))
 348        ->setContext(idx($dictionary, 'context'))
 349        ->setLanguage(idx($dictionary, 'language'))
 350        ->setParentHash(idx($dictionary, 'parentHash'))
 351        ->setDocblockRaw(idx($dictionary, 'docblockRaw'))
 352        ->setProperties(idx($dictionary, 'properties'));
 353  
 354      foreach (idx($dictionary, 'warnings', array()) as $warning) {
 355        $atom->addWarning($warning);
 356      }
 357  
 358      foreach (idx($dictionary, 'childHashes', array()) as $child) {
 359        $atom->addChildHash($child);
 360      }
 361  
 362      foreach (idx($dictionary, 'extends', array()) as $extends) {
 363        $atom->addExtends(DivinerAtomRef::newFromDictionary($extends));
 364      }
 365  
 366      return $atom;
 367    }
 368  
 369    public function getProperty($key, $default = null) {
 370      return idx($this->properties, $key, $default);
 371    }
 372  
 373    public function setProperty($key, $value) {
 374      $this->properties[$key] = $value;
 375    }
 376  
 377    public function getProperties() {
 378      return $this->properties;
 379    }
 380  
 381    public function setProperties(array $properties) {
 382      $this->properties = $properties;
 383      return $this;
 384    }
 385  
 386    public static function getThisAtomIsNotDocumentedString($type) {
 387      switch ($type) {
 388        case self::TYPE_FILE:
 389          return pht('This file is not documented.');
 390        case self::TYPE_FUNCTION:
 391          return pht('This function is not documented.');
 392        case self::TYPE_CLASS:
 393          return pht('This class is not documented.');
 394        case self::TYPE_ARTICLE:
 395          return pht('This article is not documented.');
 396        case self::TYPE_METHOD:
 397          return pht('This method is not documented.');
 398        case self::TYPE_INTERFACE:
 399          return pht('This interface is not documented.');
 400        default:
 401          phlog("Need translation for '{$type}'.");
 402          return pht('This %s is not documented.', $type);
 403      }
 404    }
 405  
 406    public static function getAllTypes() {
 407      return array(
 408        self::TYPE_FILE,
 409        self::TYPE_FUNCTION,
 410        self::TYPE_CLASS,
 411        self::TYPE_ARTICLE,
 412        self::TYPE_METHOD,
 413        self::TYPE_INTERFACE,
 414      );
 415    }
 416  
 417    public static function getAtomTypeNameString($type) {
 418      switch ($type) {
 419        case self::TYPE_FILE:
 420          return pht('File');
 421        case self::TYPE_FUNCTION:
 422          return pht('Function');
 423        case self::TYPE_CLASS:
 424          return pht('Class');
 425        case self::TYPE_ARTICLE:
 426          return pht('Article');
 427        case self::TYPE_METHOD:
 428          return pht('Method');
 429        case self::TYPE_INTERFACE:
 430          return pht('Interface');
 431        default:
 432          phlog("Need translation for '{$type}'.");
 433          return ucwords($type);
 434      }
 435    }
 436  
 437  }