TODO accretion for pyScss

TODO.md

BUGS

• null is not supported -- it's treated as trueish

• interactive mode is broken and untested

• @keyframes is collapsed like it were a nested rule

• content: ''; becomes content: ; (pull #51, breaks stuff)

• unclear if full border-radius syntax (a b c d / e f g h) is handled correctly

  • ruby sass uses a heuristic: it doesn't perform division if both operands are literal numbers

• docstring-like comments at the start of the file are lost -- these are often license/copyright so might be nice to preserve

• debug-info doesn't appear in compressed mode; possibly doesn't make sense to use both together, though ruby sass allows it

• hsl/hsla is preserved but shouldn't be (pull #89, breaks stuff)

• exceptions in functions (and many other places) are swallowed -- see "strict mode" below

• something is wrong with linear-gradient; this:

    background: -webkit-linear-gradient(white, white 25px, rgba(255, 255, 255, 0) 50px);
    background:         linear-gradient(white, white 25px, rgba(255, 255, 255, 0) 50px);
  

  produces:

    background: -webkit-linear-gradient(#ffffff, #ffffff 25px, rgba(255, 255, 255, 0));
    background: linear-gradient(#ffffff 0px, #ffffff 25px, rgba(255, 255, 255, 0) 25px);
  

REFACTORING

• Scss() arguments are wired too much into the command-line tool syntax; scss.tool should be translating to normal constructor arguments

  • deprecate the global configuration and make the constructor take arguments
    • kill scss_opts!
      • search_paths is a start

• rename Scss to Compiler

• strict mode

  • die when an @import is missing
    • btw, will "foo" find foo.scss?
  • in DEBUG mode, unparseable expressions cause an (unhelpful) syntax error, but sometimes this is legit e.g. expression. turn into python warnings? something?
    • for that matter, should most logged messages be python warnings?
  • show compilation errors/warnings at the top of the including page, like ruby sass?

• lots more tests

  • import the sass test suite, somehow?
  • direly need tests for the compass stuff
  • need to port the disabled doctests that test unimplemented features
  • tests for stuff i added
    • function registry
    • function uncaching
    • new Scss arguments

• function registry sucks

  • poorly documented
  • existing functions still don't use it
  • no way to "compose" function registries -- always copies
  • should really be a property of the compiler instead of this weird dangling thing, but that makes it hard to reuse, since the compiler also remembers state of things it has seen. perhaps a compiler-options object...?
  • would be much more powerful if functions had access to the current state -- vars, options, etc.
  • compass, css, and sass functions ought to be separated into their own modules

• README is no longer correct

  • suggests monkeypatching the scss module, which no longer entirely works, oops
  • need real documentation anyway :)

• style warts

  • if not name: return
  • and/or ternary
  • very compact vertically
  • very short var names, especially in scanner
  • string building could be stringio? won't work as long as it needs to look at previous char
  • lots of typechecking; should have a more robust type system and fix types early. don't make everything worry about fallback

• parsing woes

  • generated grammar should live elsewhere
    • did i edit it to make func_registry work...? may have to update source grammar too
  • how viable is it to put more state in a single object instead of passing a dozen variables?
  • rules should be objects, not lists with constant keys
  • cut down use of regexen
  • inline compression options instead of postprocessing

• type system

  • everything should be typed; there should never be literal python strings mucking about in the expression evaluator
    • even $foo could be parsed as a Variable type
  • type classes accept too many variations of types in the constructor; presumably the caller knows what type it has, so let it use an appropriate classmethod
    • constructor for wrapping a python value, classmethods for conversions?
  • is the __hash__ method necessary? unsure where these are used in dicts/sets
  • StringValue is heavily overloaded; sometimes is a real string that can be quoted, sometimes is !important, sometimes is a CSS keyword that must not be quoted
  • no URL type. granted, ruby sass doesn't have one either, but it seems like the logical interpretation of url()

• make compiler thread-safe?? is that even possible? can we test that?

• create a consolidated Calculator class that can evaluate an expression independently and owns a function registry

• underscores and hyphens are supposed to be interchangeable, but this doesn't work if e.g. a @function name or FunctionRegistry name has underscores. need to check that this is covered everywhere? including var names, injected vars?

  • looks like kwargs explicitly use underscores for the sake of python kwargs
  • it would be nice to just, like, extend dict and have this conversion happen in the right places automatically

• break out magic-@import, make a pluggable import system

• fix this scss_files thing; would be nice to inject permanent files from the outside without having them overwritten. also, self.foo vs self._foo

• "3.0px" in compressed mode produces "0" due to a nasty regex. could stand a better fix for this. also, need a test, but don't know how to test compressed mode