solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/doc/subproperties.rb

@@ -0,0 +1,71 @@
+require 'jsduck/util/singleton'
+require 'jsduck/logger'
+
+module JsDuck
+  module Doc
+
+    # Detects nested structure of subproperties.
+    class Subproperties
+      include Util::Singleton
+
+      # Given array of e.g. @param tags from Doc::Parser with names
+      # containing dots:
+      #
+      #     {:name => "foo"},
+      #     {:name => "foo.bar"},
+      #     {:name => "foo.baz"},
+      #     {:name => "zap"},
+      #
+      # Produces nested structure:
+      #
+      #     {:name => "foo", :properties => [
+      #         {:name => "bar"},
+      #         {:name => "baz"}]},
+      #     {:name => "zap"},
+      #
+      # Secondly it takes a position argument which is used for
+      # logging warnings when bogus subproperty syntax is encountered.
+      def nest(raw_items, pos)
+        # First item can't be namespaced, if it is ignore the rest.
+        if raw_items[0] && raw_items[0][:name] =~ /\./
+          warn(raw_items[0][:name], pos)
+          raw_items[0][:name].sub!(/\..*$/, '')
+          return [raw_items[0]]
+        end
+
+        # build name-index of all items
+        index = {}
+        raw_items.each {|it| index[it[:name]] = it }
+
+        # If item name has no dots, add it directly to items array.
+        # Otherwise look up the parent of item and add it as the
+        # property of that parent.
+        items = []
+        raw_items.each do |it|
+          if it[:name] =~ /^(.+)\.([^.]+)$/
+            it[:name] = $2
+            parent = index[$1]
+            if parent
+              parent[:properties] = [] unless parent[:properties]
+              parent[:properties] << it
+            else
+              warn("#{$1}.#{$2}", pos)
+            end
+          else
+            items << it
+          end
+        end
+
+        return items
+      end
+
+      def warn(name, pos)
+        parent = name.sub(/\.[^.]*$/, '')
+        msg = "Ignoring subproperty '#{name}' no parent found with name '#{parent}'."
+        Logger.warn(:subproperty, msg, pos)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/examples.rb

@@ -0,0 +1,63 @@
+require 'jsduck/util/json'
+require 'jsduck/util/null_object'
+require 'jsduck/grouped_asset'
+
+module JsDuck
+
+  # Reads in examples JSON file
+  class Examples < GroupedAsset
+    # Creates Examples object from filename.
+    def self.create(filename, opts)
+      if filename
+        Examples.new(filename, opts)
+      else
+        Util::NullObject.new(:to_array => [], :[] => nil)
+      end
+    end
+
+    # Parses examples config file
+    def initialize(filename, opts)
+      @groups = Util::Json.read(filename)
+      @opts = opts
+      fix_examples_data
+      build_map_by_name
+    end
+
+    # Prefix all relative URL-s in examples list with path given in --examples-base-url
+    #
+    # For backwards compatibility:
+    #
+    # - Create names for each example when not present
+    # - Create title from text
+    # - Create description from desc
+    #
+    def fix_examples_data
+      each_item do |ex|
+        ex["name"] = ex["url"] unless ex["name"]
+
+        unless ex["url"] =~ /^https?:\/\//
+          ex["url"] = @opts.examples_base_url + ex["url"]
+        end
+        unless ex["icon"] =~ /^https?:\/\//
+          ex["icon"] = @opts.examples_base_url + ex["icon"]
+        end
+
+        unless ex["title"]
+          ex["title"] = ex["text"]
+          ex.delete("text")
+        end
+        unless ex["description"]
+          ex["description"] = ex["desc"]
+          ex.delete("desc")
+        end
+      end
+    end
+
+    # Extracts example icon URL from example hash
+    def icon_url(example)
+      example["icon"]
+    end
+
+  end
+
+end

data/lib/jsduck/export_writer.rb

@@ -0,0 +1,63 @@
+require 'jsduck/util/stdout'
+require 'jsduck/exporter/full'
+require 'jsduck/exporter/examples'
+require 'jsduck/format/batch'
+require 'jsduck/class_writer'
+require 'jsduck/guide_writer'
+require 'jsduck/output_dir'
+require 'fileutils'
+
+module JsDuck
+
+  # Performs the export in one of the export formats.
+  class ExportWriter
+    def initialize(relations, assets, opts)
+      @relations = relations
+      @assets = assets
+      @opts = opts
+    end
+
+    def write
+      format_classes
+
+      clean_output_dir unless @opts.output == :stdout
+
+      export_classes
+      export_examples_in_guides if @opts.export == :examples
+
+      Util::Stdout.flush if @opts.output == :stdout
+    end
+
+    private
+
+    def export_classes
+      cw = ClassWriter.new(get_exporter, @relations, @opts)
+      cw.write(@opts.output, ".json")
+    end
+
+    def get_exporter
+      exporters = {
+        :full => Exporter::Full,
+        :examples => Exporter::Examples,
+      }
+      exporters[@opts.export]
+    end
+
+    def export_examples_in_guides
+      gw = GuideWriter.new(Exporter::Examples, @assets.guides, @opts)
+      gw.write(@opts.output, ".json")
+    end
+
+    # -- util routines --
+
+    def clean_output_dir
+      OutputDir.clean(@opts)
+    end
+
+    def format_classes
+      Format::Batch.format_all!(@relations, @assets, @opts)
+    end
+
+  end
+
+end

data/lib/jsduck/exporter/app.rb

@@ -0,0 +1,80 @@
+require 'jsduck/render/class'
+require 'jsduck/exporter/full'
+require 'jsduck/tag_registry'
+require 'jsduck/web/class_icons'
+
+module JsDuck
+  module Exporter
+
+    # Exports data for Docs app.
+    class App
+      def initialize(relations, opts)
+        @full_exporter = Exporter::Full.new(relations, opts)
+        @relations = relations
+        @renderer = Render::Class.new(opts)
+      end
+
+      # Returns compacted class data hash which contains an additional
+      # :html field with full HTML to show on class overview page.
+      def export(cls)
+        data = @full_exporter.export(cls)
+
+        data[:classIcon] = Web::ClassIcons.get(cls)
+        data[:superclasses] = cls.superclasses.collect {|c| c[:name] }
+        data[:subclasses] = @relations.subclasses(cls).collect {|c| c[:name] }.sort
+        data[:mixedInto] = @relations.mixed_into(cls).collect {|c| c[:name] }.sort
+        data[:alternateClassNames] = cls[:alternateClassNames].sort if cls[:alternateClassNames]
+
+        data[:mixins] = cls.deps(:mixins).collect {|c| c[:name] }.sort
+        data[:parentMixins] = cls.parent_deps(:mixins).collect {|c| c[:name] }.sort
+        data[:requires] = cls.deps(:requires).collect {|c| c[:name] }.sort
+        data[:uses] = cls.deps(:uses).collect {|c| c[:name] }.sort
+
+        data[:html] = @renderer.render(data)
+
+        return compact(data)
+      end
+
+      private
+
+      # removes extra data from export
+      def compact(cls)
+        cls.delete(:doc)
+        cls[:members] = cls[:members].map {|m| compact_member(m) }
+        cls[:files] = compact_files(cls[:files])
+        cls[:meta] = combine_meta(cls)
+        cls
+      end
+
+      def compact_member(m)
+        m_copy = {}
+        [:name, :tagname, :owner, :id].each do |key|
+          m_copy[key] = m[key]
+        end
+        m_copy[:meta] = combine_meta(m)
+        m_copy
+      end
+
+      # Add data for builtin tags with signatures to :meta field.
+      def combine_meta(m)
+        meta = {}
+        TagRegistry.signatures.each do |s|
+          name = s[:tagname]
+          meta[name] = m[name] if m[name]
+        end
+        meta
+      end
+
+      # Remove full path from filename for privacy considerations as the
+      # path can reveal information about the system where JSDuck was
+      # run.  The docs app doesn't need to have this information.
+      def compact_files(files)
+        files.map do |f|
+          {:filename => File.basename(f[:filename]), :href => f[:href]}
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/exporter/examples.rb

@@ -0,0 +1,58 @@
+require 'jsduck/inline_examples'
+
+module JsDuck
+  module Exporter
+
+    # Exporter for inline examples.
+    #
+    # It produces the following structure:
+    #
+    # {
+    #   :type => :class,  # can also be :guide
+    #   :name => "Panel",
+    #   :examples => [
+    #     {:code => "bla bla", :options => {}},
+    #     {:code => "bla bla", :options => {"raw" => true}},
+    #     ...
+    #   ]
+    # }
+    #
+    class Examples
+      def initialize(relations, opts)
+        # All params ignored, they're present to be compatible with
+        # other exporters.
+        @inline_examples = InlineExamples.new
+      end
+
+      # Returns hash of class name and inline examples
+      def export(cls)
+        examples = @inline_examples.extract(cls[:doc])
+        if examples.length > 0
+          {
+            :type => :class,
+            :name => cls[:name],
+            :examples => examples,
+          }
+        else
+          nil
+        end
+      end
+
+      # Returns hash of guide name and inline examples
+      def export_guide(guide)
+        examples = @inline_examples.extract(guide[:html] || "")
+        if examples.length > 0
+          {
+            :type => :guide,
+            :name => guide["name"],
+            :examples => examples,
+          }
+        else
+          nil
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/exporter/full.rb

@@ -0,0 +1,60 @@
+require 'jsduck/class'
+require 'jsduck/member_registry'
+require 'ostruct'
+
+module JsDuck
+  module Exporter
+
+    # Exporter for all the class docs.
+    class Full
+      def initialize(relations, opts=OpenStruct.new)
+        # parameters are just for compatibility with other exporters
+      end
+
+      # Returns a hash of class data, with :members field expanded
+      # into list of all members (including those inherited from
+      # parents and mixins).
+      def export(cls)
+        # Make copy of the internal data structure of a class
+        # so our modifications on it will be safe.
+        h = cls.internal_doc.clone
+
+        h[:members] = export_members(cls)
+
+        h
+      end
+
+      private
+
+      # Generates flat list of all members
+      def export_members(cls)
+        groups = []
+        MemberRegistry.names.each do |tagname|
+          groups << export_members_group(cls, {:tagname => tagname, :static => false})
+          groups << export_members_group(cls, {:tagname => tagname, :static => true})
+        end
+        groups.flatten
+      end
+
+      # Looks up members of given type, and sorts them so that
+      # constructor method is first
+      def export_members_group(cls, cfg)
+        ms = cls.find_members(cfg)
+        ms.sort! {|a,b| a[:name] <=> b[:name] }
+        cfg[:tagname] == :method ? constructor_first(ms) : ms
+      end
+
+      # If methods list contains constructor, move it into the beginning.
+      def constructor_first(ms)
+        constr = ms.find {|m| JsDuck::Class.constructor?(m) }
+        if constr
+          ms.delete(constr)
+          ms.unshift(constr)
+        end
+        ms
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/external_classes.rb

@@ -0,0 +1,362 @@
+module JsDuck
+
+  # Handles patterns of external classes.
+  #
+  # A pattern can be a simple classname or a one with a wildcard "*".
+  #
+  # Also one can use a special keyword "@browser" to include all
+  # common browser web API class names.
+  class ExternalClasses
+
+    def initialize(classnames = [])
+      @class_names = {}
+      @patterns = []
+      classnames.each {|name| add(name) }
+    end
+
+    # Adds a classname or pattern to list of external classes.
+    def add(name)
+      if name =~ /\*/
+        @patterns << make_pattern(name)
+      elsif name =~ /^@browser$/i
+        WEB_APIS.each do |cls|
+          @class_names[cls] = true
+        end
+      else
+        @class_names[name] = true
+      end
+    end
+
+    # True if the classname matches an external class pattern.
+    def is?(classname)
+      @class_names[classname] || @patterns.any? {|p| classname =~ p }
+    end
+
+    private
+
+    def make_pattern(pattern)
+      Regexp.new("^" + pattern.split(/\*/, -1).map {|s| Regexp.escape(s) }.join(".*") + "$")
+    end
+
+    # List taken from: https://developer.mozilla.org/en-US/docs/Web/API
+    # Excluding experimental, obsolete, deprecated and non-standardized APIs.
+    WEB_APIS = %w(
+      AbstractWorker
+      ArrayBuffer
+      ArrayBufferView
+      Attr
+
+      BatteryManager
+      Blob
+      BluetoothAdapter
+      BluetoothManager
+
+      CanvasGradient
+      CanvasImageSource
+      CanvasPattern
+      CanvasRenderingContext2D
+      CharacterData
+      CloseEvent
+      Comment
+      CompositionEvent
+      ContactManager
+      Coordinates
+      CSS
+      CSSConditionRule
+      CSSGroupingRule
+      CSSMediaRule
+      CSSPageRule
+      CSSRule
+      CSSRuleList
+      CSSStyleDeclaration
+      CSSStyleRule
+      CSSStyleSheet
+      CSSSupportsRule
+      CustomEvent
+
+      DataTransfer
+      DataView
+      DedicatedWorkerGlobalScope
+      Document
+      DocumentFragment
+      DocumentTouch
+      DocumentType
+      DOMError
+      DOMException
+      DOMHighResTimeStamp
+      DOMImplementation
+      DOMImplementationRegistry
+      DOMString
+      DOMStringList
+      DOMStringMap
+      DOMTimeStamp
+      DOMTokenList
+
+      Element
+      ErrorEvent
+      Event
+      EventListener
+      EventSource
+      EventTarget
+      Extensions
+
+      File
+      FileHandle
+      FileList
+      FileReader
+      FileReaderSync
+      FileRequest
+      Float32Array
+      Float64Array
+      FormData
+
+      Geolocation
+      GlobalEventHandlers
+
+      History
+      HTMLAnchorElement
+      HTMLAreaElement
+      HTMLAudioElement
+      HTMLBaseElement
+      HTMLBodyElement
+      HTMLBRElement
+      HTMLButtonElement
+      HTMLCanvasElement
+      HTMLCollection
+      HTMLDataElement
+      HTMLDataListElement
+      HTMLDivElement
+      HTMLDListElement
+      HTMLDocument
+      HTMLElement
+      HTMLEmbedElement
+      HTMLFieldSetElement
+      HTMLFormControlsCollection
+      HTMLFormElement
+      HTMLHeadElement
+      HTMLHeadingElement
+      HTMLHRElement
+      HTMLHtmlElement
+      HTMLIFrameElement
+      HTMLImageElement
+      HTMLInputElement
+      HTMLKeygenElement
+      HTMLLabelElement
+      HTMLLegendElement
+      HTMLLIElement
+      HTMLLinkElement
+      HTMLMapElement
+      HTMLMediaElement
+      HTMLMetaElement
+      HTMLMeterElement
+      HTMLModElement
+      HTMLObjectElement
+      HTMLOListElement
+      HTMLOptGroupElement
+      HTMLOptionElement
+      HTMLOptionsCollection
+      HTMLOutputElement
+      HTMLParagraphElement
+      HTMLParamElement
+      HTMLPreElement
+      HTMLProgressElement
+      HTMLQuoteElement
+      HTMLScriptElement
+      HTMLSelectElement
+      HTMLSourceElement
+      HTMLSpanElement
+      HTMLStyleElement
+      HTMLTableCaptionElement
+      HTMLTableCellElement
+      HTMLTableColElement
+      HTMLTableDataCellElement
+      HTMLTableElement
+      HTMLTableHeaderCellElement
+      HTMLTableRowElement
+      HTMLTableSectionElement
+      HTMLTextAreaElement
+      HTMLTimeElement
+      HTMLTitleElement
+      HTMLTrackElement
+      HTMLUListElement
+      HTMLUnknownElement
+      HTMLVideoElement
+
+      IDBCursor
+      IDBCursorSync
+      IDBCursorWithValue
+      IDBDatabase
+      IDBDatabaseSync
+      IDBEnvironment
+      IDBEnvironmentSync
+      IDBFactory
+      IDBFactorySync
+      IDBIndex
+      IDBIndexSync
+      IDBKeyRange
+      IDBObjectStore
+      IDBObjectStoreSync
+      IDBOpenDBRequest
+      IDBRequest
+      IDBTransaction
+      IDBTransactionSync
+      IDBVersionChangeEvent
+      IDBVersionChangeRequest
+      ImageData
+      Int16Array
+      Int32Array
+      Int8Array
+
+      KeyboardEvent
+
+      LinkStyle
+      Location
+      LockedFile
+
+      MessageEvent
+      MouseEvent
+
+      Navigator
+      NavigatorGeolocation
+      NavigatorID
+      NavigatorLanguage
+      NavigatorOnLine
+      Node
+      NodeFilter
+      NodeIterator
+      NodeList
+      Notification
+      NotifyAudioAvailableEvent
+
+      Performance
+      PerformanceNavigation
+      PerformanceTiming
+      PermissionSettings
+      Plugin
+      Position
+      PositionError
+      PositionOptions
+      ProcessingInstruction
+      ProgressEvent
+
+      Range
+      RTCPeerConnection
+
+      SharedWorker
+      StorageEvent
+      StyleSheet
+      StyleSheetList
+      SVGAElement
+      SVGAngle
+      SVGAnimateColorElement
+      SVGAnimatedAngle
+      SVGAnimatedBoolean
+      SVGAnimatedEnumeration
+      SVGAnimatedInteger
+      SVGAnimatedLength
+      SVGAnimatedLengthList
+      SVGAnimatedNumber
+      SVGAnimatedNumberList
+      SVGAnimatedPoints
+      SVGAnimatedPreserveAspectRatio
+      SVGAnimatedRect
+      SVGAnimatedString
+      SVGAnimatedTransformList
+      SVGAnimateElement
+      SVGAnimateMotionElement
+      SVGAnimateTransformElement
+      SVGAnimationElement
+      SVGCircleElement
+      SVGClipPathElement
+      SVGCursorElement
+      SVGDefsElement
+      SVGDescElement
+      SVGElement
+      SVGEllipseElement
+      SVGFilterElement
+      SVGFontElement
+      SVGFontFaceElement
+      SVGFontFaceFormatElement
+      SVGFontFaceNameElement
+      SVGFontFaceSrcElement
+      SVGFontFaceUriElement
+      SVGForeignObjectElement
+      SVGGElement
+      SVGGlyphElement
+      SVGGradientElement
+      SVGHKernElement
+      SVGImageElement
+      SVGLength
+      SVGLengthList
+      SVGLinearGradientElement
+      SVGLineElement
+      SVGMaskElement
+      SVGMatrix
+      SVGMissingGlyphElement
+      SVGMPathElement
+      SVGNumber
+      SVGNumberList
+      SVGPathElement
+      SVGPatternElement
+      SVGPoint
+      SVGPolygonElement
+      SVGPolylineElement
+      SVGPreserveAspectRatio
+      SVGRadialGradientElement
+      SVGRect
+      SVGRectElement
+      SVGScriptElement
+      SVGSetElement
+      SVGStopElement
+      SVGStringList
+      SVGStylable
+      SVGStyleElement
+      SVGSVGElement
+      SVGSwitchElement
+      SVGSymbolElement
+      SVGTests
+      SVGTextElement
+      SVGTextPositioningElement
+      SVGTitleElement
+      SVGTransform
+      SVGTransformable
+      SVGTransformList
+      SVGTRefElement
+      SVGTSpanElement
+      SVGUseElement
+      SVGViewElement
+      SVGVKernElement
+
+      TCPServerSocket
+      Text
+      TextMetrics
+      TimeRanges
+      Touch
+      TouchEvent
+      TouchList
+      Transferable
+      TreeWalker
+
+      UIEvent
+      Uint16Array
+      Uint32Array
+      Uint8Array
+      Uint8ClampedArray
+
+      ValidityState
+
+      WebGLRenderingContext
+      WebSocket
+      WheelEvent
+      Window
+      Worker
+      WorkerLocation
+      WorkerNavigator
+
+      XMLHttpRequest
+      XMLHttpRequestEventTarget
+    )
+
+  end
+
+end