Instantly share code, notes, and snippets.

@jashkenas / Secret
Created Jan 5, 2013

What would you like to do?

The Scope class regulates lexical scoping within CoffeeScript. As you generate code, you create a tree of scopes in the same shape as the nested function bodies. Each scope knows about the variables declared within it, and has a reference to its parent enclosing scope. In this way, we know which variables are new and need to be declared with var, and which are shared with external scopes.

Import the helpers we plan to use.

{extend, last} = require './helpers'

exports.Scope = class Scope

The root is the top-level Scope object for a given file.

  @root: null

Initialize a scope with its parent, for lookups up the chain, as well as a reference to the Block node it belongs to, which is where it should declare its variables, and a reference to the function that it belongs to.

  constructor: (@parent, @expressions, @method) ->
    @variables = [{name: 'arguments', type: 'arguments'}]
    @positions = {}
    Scope.root = this unless @parent

Adds a new variable or overrides an existing one.

  add: (name, type, immediate) ->
    return @parent.add name, type, immediate if @shared and not immediate
    if @positions, name
      @variables[@positions[name]].type = type
      @positions[name] = @variables.push({name, type}) - 1

When super is called, we need to find the name of the current method we're in, so that we know how to invoke the same method of the parent class. This can get complicated if super is being called from an inner function. namedMethod will walk up the scope tree until it either finds the first function object that has a name filled in, or bottoms out.

  namedMethod: ->
    return @method if or !@parent

Look up a variable name in lexical scope, and declare it if it does not already exist.

  find: (name) ->
    return yes if @check name
    @add name, 'var'

Reserve a variable name as originating from a function parameter for this scope. No var required for internal references.

  parameter: (name) ->
    return if @shared and @parent.check name, yes
    @add name, 'param'

Just check to see if a variable has already been declared, without reserving, walks up to the root scope.

  check: (name) ->
    !!(@type(name) or @parent?.check(name))

Generate a temporary variable name at the given index.

  temporary: (name, index) ->
    if name.length > 1
      '_' + name + if index > 1 then index - 1 else ''
      '_' + (index + parseInt name, 36).toString(36).replace /\d/g, 'a'

Gets the type of a variable.

  type: (name) ->
    return v.type for v in @variables when is name

If we need to store an intermediate result, find an available name for a compiler-generated variable. _var, _var2, and so on...

  freeVariable: (name, reserve=true) ->
    index = 0
    index++ while @check((temp = @temporary name, index))
    @add temp, 'var', yes if reserve

Ensure that an assignment is made at the top of this scope (or at the top-level scope, if requested).

  assign: (name, value) ->
    @add name, {value, assigned: yes}, yes
    @hasAssignments = yes

Does this scope have any declared variables?

  hasDeclarations: ->

Return the list of variables first declared in this scope.

  declaredVariables: ->
    realVars = []
    tempVars = []
    for v in @variables when v.type is 'var'
      (if is '_' then tempVars else realVars).push
    realVars.sort().concat tempVars.sort()

Return the list of assignments that are supposed to be made at the top of this scope.

  assignedVariables: ->
    "#{} = #{v.type.value}" for v in @variables when v.type.assigned

This comment has been minimized.

gbraad commented Feb 26, 2013

Screenshot of the output when using an editor with syntax-highlighting:


This comment has been minimized.

hickford commented Feb 26, 2013

Brilliant! Original at - will look better when GitHub pulls github/linguist#408


This comment has been minimized.

hoodie commented Feb 27, 2013

This is great, especially for libs or little helpers.
Now github only needs to treat it the way it treats .md files by default. But then, why does'n it do the same to any file with comments.
Neat idea!


This comment has been minimized.

americos commented Mar 1, 2013

Cool, This looks pretty neat


This comment has been minimized.

jamiter commented Mar 1, 2013

Like it!

Now github only needs to treat it the way it treats .md files by default.

Is there any way we could speed up this process?


This comment has been minimized.

JogoShugh commented Mar 4, 2013

Very cool


This comment has been minimized.

czarcrab commented Mar 8, 2013

Absolutely love it

  • makes reviewing and writing code so painless
  • Sytax highlighting worked like a charm in sublime text
  • Got to remember the trick of adding a full stop at the end of comments, which is a really neat habit anyways to adopt, atleast till coffee-script connects to my temples and reads my mind

Now if I can just get docco to run on it.

czarcrab$ docco src/*.litcoffee
docco: skipped unknown type (src/checkers.litcoffee)

Which is a relatively easy fix using

".litcoffee" :
{"name" : "coffee-script", "symbol" : ""},

in languages.json, but this makes docco think that the file is all comments


This comment has been minimized.


jashkenas commented Mar 17, 2013

@czarcrab -- Docco supports it now (and is also now itself written in Literate CoffeeScript).


This comment has been minimized.

aprice2704 commented Apr 11, 2013

Really liking litcoffee so far!

OMG just tried docco. Fan-bloody-tastic. That is simply amazingly awesome. BY FAR the best looking code docs I have ever seen. Sooo cool, thanks Jeremy, you are a genius. Andy.


This comment has been minimized.

paulvi commented Apr 29, 2013


Now github only needs to treat it the way it treats .md files by default.

Is there any way we could speed up this process?

Just use double extension, as mention on Docco page

Nodeclipse (GitHub) is planning to add support for Coffee & LitCoffee


This comment has been minimized.

madfriend commented Jul 4, 2013

@gbraad What's the color scheme you were using?


This comment has been minimized.

tusharmath commented Aug 26, 2013

Literate Coffee script is just too good! But there were two problems that I faced -

  1. I am not able to add any non executable code to the markdown file. For example I tried to add some javascript code but failed as the interpreter got confused after seeing the backticks.
  2. Sometimes I don't want to show the coffee script code in the generated html even though I want it to be there in the file. Can that be done too? That would be a great feature!

This comment has been minimized.

pateketrueke commented Oct 7, 2013

This is how it looks on SublimeText and TextMate (?):

Monokai dark-theme


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment