A slick config file format for humans.
Scuff is a language suite with a slick, efficient, flexible syntax, unique features and useful tools.
Its purpose is to represent structured data effectively. Scuff's greatest strengths are its syntactic simplicity and reliable flexibility. It comes with a Python API and a simple command line tool for moving data between JSON syntax, Python's and its own.
One excellent use for Scuff is to encode and parse configuration files.
Scuff implements its own custom lexer, recursive-descent parser and transpiler to read and process data. Though written in Python, the parser is immune from Python's recursion limit.
To install Scuff and its tools for Python from the Python Package Index, run the following in the command line:
$ python -m pip install scuff
Variables are assigned with a key and a value.
Key names must be valid identifiers, meaning they must contain no spaces or
symbols except underscore (_
).
Values can be assigned to variables with or without an equals sign (=
):
my_favorite_number = 42
my_favorite_color "Magenta"
is_but_a_flesh_wound yes
When left without a value, variables will evaluate to null
or None
:
set_to_null =
also_null
but_this_has_a_value 15
- Numbers
Numbers can be integers or floats:
1 1.2 -1_000 0.123 .123_4
- Booleans
The boolean values
True
andFalse
are given using these variants:True true yes False false no
They are case-insensitive, so
yes
andyES
both evaluate toTrue
.
- Strings
Single-line strings can be enclosed by single quotes (
'
), double quotes ("
) or backticks (`
), and multiline strings are enclosed by three of any one:foo "abc" bar 'def' baz '''Hi, did you know you're cute? '''
- Lists
Lists are enclosed by square brackets (
[]
). Elements inside lists are separated by spaces, commas or line breaks:groceries [ "bread", "milk" "eggs" "spam" ]
- Mappings
Mappings are groups of key-value pairs enclosed by curly braces (
{}
). Values may be any expression, even other mappings:me { name "Samantha" age 24 job "Developer" favorite_things { editor "Vim" languages ["Python", "Rust"] } }
Mappings may also take the form of dotted attribute lookups:
outer.middle.inner yes
evauates in Python to
{'outer': {'middle': {'inner': True}}}
- Comments
Single-line comments are made using the
#
symbol:option = "The parser reads this." # But this is a comment. #And so is this. option2 = "# But not this; It's inside a string." # The parser ignores everything between ``#`` and the end of the line. # ignore = "Comment out any lines of code you want to skip."
Once you install Scuff, you can then import scuff
as a Python module
and use its tools:
>>> import scuff
>>> scuff.to_json('menu {border.color "#aa22bb", font.color "#cdcdcd"}')
'{"menu": {"border": {"color": "#aa22bb"}, "font": {"color": "#cdcdcd"}}}'
>>> type(scuff.to_py('Documents/file.conf'))
<class 'dict'>
>>> scuff.to_py('a.b ["c", "d"]')
{'a': {'b': ['c', 'd']}}
>>> scuff.parse('hovercraft ["eel" "eel" "eel" "eel"]')
<ast.Module object at 0x74b59c109710>
>>> print(scuff.dump(_))
Module(
body=[
Assign(
targets=[
Name(id='hovercraft')],
value=List(
elts=[
Constant(value='eel'),
Constant(value='eel'),
Constant(value='eel'),
Constant(value='eel')]))])
Scuff also comes with a command line tool for converting between formats:
usage: scuff [-h] [-j] [-p] [-a] [--debug] [-v] source [source ...]
positional arguments:
source The file path(s) or literal Scuff to process.
options:
-h, --help show this help message and exit
-j, --to-json Convert `source` to JSON.
-p, --to-python Convert `source` to Python.
-a, --show-ast Parse `source` and show its equivalent AST.
--debug Use debug mode. (Not implemented)
-v, --version show program's version number and exit
Multiple files and strings may be converted in multiple ways at once:
$ python -m scuff --to-json ~/.config/mybar/mybar.conf 'foo {a{b [1,{c 3}]}}'
{"field_order": ["hostname", "uptime", "cpu_usage", "cpu_temp", "mem_usage", "disk_usage", "battery", "net_stats", "datetime"], "field_icons": {"uptime": ["Up ", "\uf2f2 "], "cpu_usage": ["CPU ", "\uf3fd "], "cpu_temp": ["", "\uf06d "], "mem_usage": ["MEM ", "\uf2db "], "disk_usage": ["/: ", "\uf233 "], "battery": ["BAT ", "\uf242 "], "net_stats": ["", "\uf1eb"]}}
{"foo": {"a": {"b": [1, {"c": 3}]}}}