Linguist Unknown

This repository is used as a Web Browser extension for the website GitHub.com in order to detect and highlight unknown, lost or new programming languages. Oh! And you are as well able to overwrite syntax highlighting of known languages such as C, Javascript and many others!

See CONTRIBUTING.md before creating a pull request.

• Why
• Download
• Highlighting a new language
• Examples
• Check if Linguist Unknown works
  • Check if your yaml is valid
• Documentation
  • Multiple Languages
  • extensions
  • default
    • color
  • identifier
    • color
  • number
    • color
  • string
    • color
  • comment
    • color
    • single_line
    • begin_multiline
    • end_multiline
  • group
    • color
    • keywords
    • operators
    • regexes
    • multiline
• Contributing
• License

Why should you download it?

There are numerous cool languages out there whose syntaxes are not being highlighted on GitHub. That happens because the Linguist Project targets only the main existent programming languages.

Because of that, most of the time it is frustrating to see a new-or-unknown-language source code. Linguist Unknown is a project that helps new, lost or unknown languages to be visualized on GitHub. It helps you to do what you already do on your favorite Text Editor.

We believe that all languages should be highlighted on GitHub; just the way it should always be. :) There is an ocean of programming languages out there and by downloading Linguist Unknown you're making every drop of this ocean count!

How can I download and use it?

Two Simple Steps:

• Install the Google Chrome Plugin or the Firefox Plugin (still in TODO, accepting pull requests).
• Make sure it is active.

How to highlight my language(s)?

1. Download and install Linguist Unknown.
2. Add a file named .linguist.yml into the root of your GitHub repository to tell Linguist Unknown your language(s) grammar(s).
3. Write your grammar(s) rules. The example below tells Linguist Unknown that you have a programming language called Foo whose extensions are .foo and .bar. It also tells that Foo's single linge comment is defined by //, whereas its multiline comments are defined by /* and */. Last but not least, it defines the color of your tokens i.e. identifier.color, number.color. It also helps you to define the color groups of your grammar's keywords, operators and customizable regexes

Foo:
  extensions:
    - ".foo"
    - ".bar"

  default:
    color: "#808A9F"

  identifier:
    color: "#333333"

  number:
    color: "#FF6600"

  string:
    color: "#333300"

  comment:
    color: "#CCF5AC"
    single_line: "//"
    begin_multiline: "/*"
    end_multiline: "*/"

  group:
    - color: "#72EEBB"
      operators:
        - "==="
        - ">="
      keywords:
        - "int"
        - "float"
      regexes:
        - regex: "&(amp;)\/[^\/]*\/([\\S]?)*"
          modifier: ""

    - color: "#FF00FF"
      keywords:
        - "if"
        - "else"
        - "switch"
        - "let"

    - color: "#000000"
      multiline:
        - begin: "\"\"\""
          end:   "\"\"\""

4. Test it. Go to https://github.com/your/repository/path/to/file.foo or https://github.com/your/repository/path/to/file.bar and check if is highlighted! Simple as that!

// Obs.: Make sure you refresh your browser's cached data.

Examples

Brain Language

Brain:
  extensions:
    - ".br"
    - ".brain"

  default:
    color: "#969896"

  group:
    - color: "#a71d5d"
      operators:
        - ">"
        - "<"
        - "^"
        - "&lt;"
        - "&gt;"

    - color: "#333333"
      operators:
        - "["
        - "]"
        - "{"
        - "}"
        - "?"
        - ":"
        - ";"
        - "!"

    - color: "#0086b3"
      operators:
        - "+"
        - "-"
        - "*"
        - "/"
        - "%"
        - "_"

    - color: "#795da3"
      operators:
        - "."
        - ","
        - "$"
        - "#"

Output

Test

Test:
  extensions:
    - ".test"

  default:
    color: "#FF8272"

  identifier:
    color: "#FF99FF"

  number:
    color: "#FF6600"

  string:
    color: "#333300"
  
  comment:
    color: "#969896"
    single_line: "//"
    begin_multiline: "/*"
    end_multiline: "*/"

  group:
    - color: "#72EEBB"
      keywords:
        - "for"
        - "while"
      regexes:
        - regex: "&(amp;)\/[^\/]*\/([\\S]?)*"
          modifier: ""

    - color: "#FF00FF"
      keywords:
        - "if"
        - "else"
        - "switch"
        - "let"

Output

How do I know if it works?

After downloading and installing it, visit one (or all) of the cool languages we have gathered in this repository:

Language	GitHub (or info) Repository	URL to test	Test file written by
AdvPL	AdvPL repo	./examples/AdvPL/JSONTest.prw	haskellcamargo
Brain	Brain repo	./examples/Brain/human_jump.brain	luizperes
Brainfuck	Brainfuck (Wikipedia)	./examples/Brainfuck/hellbox.bf	Robert de Bath
BrazukaScript	BrazukaScript repo	./examples/BrazukaScript/wesley_safadao.bra	luizperes
C	C (Wikipedia)	./examples/C/io.c	luizperes
Capybara	Capybara repo	./examples/Capybara/helloworld.capy	haskellcamargo
Headache	Headache repo	./examples/Headache/func.ha	LucasMW
Monga	Monga repo	./examples/Monga/bf.monga	LucasMW
Moon	Moon repo	./examples/Moon/examples.moon	MaiaVictor
Quack	Quack repo	./examples/Quack/fn_stmt.qk	luizperes
Siren	Siren repo	./examples/Siren/100-doors.siren	robotlolita
Test	--	./examples/Test/test.test	luizperes

If they're highlighted, you're good to go!

How do I know my YAML is valid?

Please read the documentation and check if your YAML is valid here

Documentation

Multiple languages in same repo

It's simple, in your .linguist.yml:

Foo:
  extensions:
    - ".foo"
  # ... other rules

Bar:
  extensions:
    - ".bar"
  # ... other rules

extensions

List of extensions for your language.

extensions:
  - ".ext1"
  - ".ext2"

default

The default configurations for your language.

default.color

All tokens with undefined color will have this color. If this color is not defined, it will use GitHub's default color: #24292e.

default:
  color: "#F00BAF"

identifier

The rules for identifiers in your language. // Obs.: Right now we only have the property color, but we may add other properties later such as custom identifiers.

identifier.color

The color for your language's identifiers. If this color is undefined, it will user the property default.color instead.

identifier:
  color: "#F00BAF"

number

The rules for numbers in your language. // Obs.: Right now we only have the property color, but we may add other properties later such as custom numbers.

number.color

The color for your language's numbers. If this color is undefined, it will user the property default.color instead.

number:
  color: "#F00BAF"

string

The rules for strings in your language. // Obs.: Right now we only have the property color, but we may add other properties later such as custom strings.

string.color

The color for your language's strings. If this color is undefined, it will user the property default.color instead.

string:
  color: "#F00BAF"

comment

Group of lexemes related to your comment tokens.

comment.color

The color for your language's comments. If this color is undefined, it will user the property default.color instead.

comment:
  color: "#F00BAF"
  ...

single_line

The lexeme for your single line comments, such as //, # and others

comment:
  single_line: "//"
  # ... other rules

begin_multiline

The lexeme for the begin of your multiline comments, such as /*, { and others

comment:
  begin_multiline: "/*"
  # ... other rules

end_multiline

The lexeme for the end of your multiline comments, such as */, } and others

comment:
  end_multiline: "*/"

group

Represents a list of color rules for your keywords, operators and others. Example

group:
  - color: "#F00BAF"
    keywords:
      - "if"
      - "while"
      - "for"
  - color: "#333333"
    keywords:
      - "int"
      - "float"
    operators:
      - "==="
      - "!=="
      - "=="
    multiline:
      - begin: "<begin>"
      - end:   "</end>"
  - color: "FF0000"
    regexes:
      - regex: "&(amp;)\/[^\/]*\/([\\S]?)*"
        modifier: ""
      - regex: "^#(?:[0-9a-fA-F]{3}){1,2}"
        modifier: "i"

group.color

Defines the color group for your keywords, operators and others (such as regexes). If undefined, it will user the property default.color instead.

group:
  - color: "#F00BAF"

  # ... other rules

group.keywords

Defines a list of keywords for a color group.

group:
  - color: "#F00BAF"
    keywords:
      - "if"
      - "else"

  # ... other rules

group.operators

Defines a list of operators for color group.

group:
  - color: "#F00BAF"
    operators:
      - "=="
      - "!="
      - ">"

  # ... other rules

group.regexes

Defines a list of regexes for a color group. The regexes properties can be used as a property that may identify custom lexemes not included by Linguist Unknown. For example, imagine that #FFFFFF is a valid lexeme in your language, to highlight it with red color, you would most likely do:

group:
  - color: "#FF0000"
    regexes:
      - regex: "^#(?:[0-9a-fA-F]{3}){1,2}"
        modifiers: ""

  # ... other rules

group.multiline

Defines a list of multiline lexemes for a color group. It is very useful when you have a lexeme that takes multiple lines (not intended to be used for comments).

group:
  - color: "#FF00FF"
    multiline:
      - begin: "<table>"
        end:   "</table>"

   # ... other rules

Contributing

Feel free to send your pull requests. Read our CONTRIBUTING.md file :)

LICENSE

This project extends GNU GPL v. 3, so be aware of that, regarding copying, modifying and (re)destributing.