From 5f548013febe23f3dd7cc06973caca221e329408 Mon Sep 17 00:00:00 2001 From: Joshua Peek Date: Tue, 24 May 2011 20:23:12 -0500 Subject: [PATCH] Document Language class --- lib/linguist/language.rb | 180 ++++++++++++++++++++++++++++++++++++--- lib/linguist/popular.yml | 10 ++- 2 files changed, 175 insertions(+), 15 deletions(-) diff --git a/lib/linguist/language.rb b/lib/linguist/language.rb index e89414e0..ca90c698 100644 --- a/lib/linguist/language.rb +++ b/lib/linguist/language.rb @@ -8,100 +8,258 @@ module Linguist @lexer_index = {} @extension_index = {} + # Internal: Create a new Language object + # + # attributes - A hash of attributes + # + # Returns a Language object def self.create(attributes = {}) language = new(attributes) + # All Language names should be unique. Warn if there is a duplicate. if @name_index.key?(language.name.downcase) warn "Duplicate language name: #{language.name}" end + # Case-insensitive language name index @name_index[language.name.downcase] = language + # Set langauge as the default for reverse lexer lookup if + # :default_lexer is set or the language is the same name as its + # lexer. if attributes[:default_lexer] || language.default_lexer? @lexer_index[language.lexer_name.downcase] = language end + # Case-insensitive lexer name index @lexer_index[language.lexer_name.downcase] ||= language language.extensions.each do |extension| + # All Language extensions should be unique. Warn if there is a + # duplicate. if @extension_index.key?(extension) warn "Duplicate extension: #{extension}" end + # Index the extension with a leading ".": ".rb" @extension_index[extension] = language + + # Index the extension without a leading ".": "rb" @extension_index[extension.sub(/^./, '')] = language end language end - def self.[](name) - find_by_name(name) || find_by_lexer(name) - end - + # Public: Look up Language by its proper name. + # + # name - The case-insensitive String name of the Language + # + # Examples + # + # Language.find_by_name('Ruby') + # # => # + # + # Returns the Language or nil if none was found. def self.find_by_name(name) @name_index[name.downcase] end + # Public: Look up Language by extension. + # + # extension - The extension String. May include leading "." + # + # Examples + # + # Language.find_by_extension('.rb') + # # => # + # + # Returns the Language or nil if none was found. def self.find_by_extension(extension) @extension_index[extension] end + # Deprecated: Look up Language by its lexer. + # + # The use of this method is discouraged since multiple languages + # may have the same lexer name. + # + # name - The case-insensitive String lexer of the Language + # + # Examples + # + # Language.find_by_lexer('cpp') + # # => # + # + # Returns the Language or Language['Text'] if none was found. def self.find_by_lexer(lexer) @lexer_index[lexer.downcase] || self['Text'] end + # Public: Look up Language by its name or lexer. + # + # name - The case-insensitive String name of the Language + # + # Examples + # + # Language['Ruby'] + # # => # + # + # Language['ruby'] + # # => # + # + # Returns the Language or nil if none was found. + def self.[](name) + find_by_name(name) || find_by_lexer(name) + end + + # Public: A List of popular languages + # + # Popular languages are sorted to the top of language chooser + # dropdowns. + # + # This list is configured in "popular.yml". + # + # Returns an Array of Lexers. def self.popular - @name_index.values.select(&:popular?).sort_by { |lang| lang.name.downcase } + @popular ||= @name_index.values.select(&:popular?).sort_by { |lang| lang.name.downcase } end + # Public: A List of non-popular languages + # + # Unpopular languages appear below popular ones in language + # chooser dropdowns. + # + # This list is created from all the languages not listed in "popular.yml". + # + # Returns an Array of Lexers. def self.unpopular - @name_index.values.select(&:unpopular?).sort_by { |lang| lang.name.downcase } + @unpopular ||= @name_index.values.select(&:unpopular?).sort_by { |lang| lang.name.downcase } end + # Internal: Initialize a new Language + # + # attributes - A hash of attributes def initialize(attributes = {}) - @name = attributes[:name] || raise(ArgumentError, "missing name") + # @name is required + @name = attributes[:name] || raise(ArgumentError, "missing name") + + # Use :lexer_name or fallback to `@name.downcase` @lexer_name = attributes[:lexer_name] || default_lexer_name - @lexer = Lexer.find_by_alias(@lexer_name) + + # Lookup Lexer object + @lexer = Lexer.find_by_alias(@lexer_name) + + # Set extensions or default to []. + # Consider using `@lexer.extensions` @extensions = attributes[:extensions] || [] - @popular = attributes[:popular] || false - @common = attributes[:common] || false + + # Set popular or common flags + @popular = attributes[:popular] || false + @common = attributes[:common] || false end - attr_reader :name, :lexer_name, :lexer, :extensions + # Public: Get proper name + # + # Examples + # + # # => "Ruby" + # # => "Python" + # # => "Perl" + # + # Returns the name String + attr_reader :name + # Deprecated: Get lexer name + # + # Examples + # + # # => "ruby" + # # => "python" + # # => "perl" + # + # Returns the name String + attr_reader :lexer_name + + # Public: Get Lexer + # + # Returns the Lexer + attr_reader :lexer + + # Public: Get extensions + # + # Examples + # + # # => ['.rb', '.rake', 'Rakefile', ...] + # + # Returns the extensions Array + attr_reader :extensions + + # Internal: Get default lexer name + # + # Returns the lexer name String def default_lexer_name name.downcase.gsub(/\s/, '-') end + # Internal: Is the language using the default lexer + # + # Returns true or false def default_lexer? lexer_name == default_lexer_name end + # Public: Get name for code search + # + # For historical reasons, code search uses a lower case form of + # the language name rather than the proper casing. + # + # Returns lexer String def search_term lexer_name end + # Public: Is it popular? + # + # Returns true or false def popular? @popular end + # Public: Is it not popular? + # + # Returns true or false def unpopular? !popular? end + # Public: Is it common? + # + # Returns true or false def common? @common end + # Public: Highlight syntax of text + # + # text - String of code to be highlighted + # + # Returns html String def colorize(text) lexer.colorize(text) end + # Public: Highlight syntax of text without the outer highlight div + # wrapper. + # + # text - String of code to be highlighted + # + # Returns html String def colorize_without_wrapper(text) lexer.colorize_without_wrapper(text) end + # Public: Return name as String representation def to_s name end diff --git a/lib/linguist/popular.yml b/lib/linguist/popular.yml index b6e10491..2e4277fd 100644 --- a/lib/linguist/popular.yml +++ b/lib/linguist/popular.yml @@ -1,25 +1,27 @@ +# Popular languages appear at the top of language dropdowns + - ActionScript - Bash - C -- Common Lisp - C# - C++ - CSS +- Common Lisp - Diff - Emacs Lisp - Erlang -- Haskell - HTML +- Haskell - Java - JavaScript - Lua - Objective-C -- Perl - PHP +- Perl - Python - Ruby +- SQL - Scala - Scheme -- SQL - TeX - XML