next version - new syntax, AST, etc

.vscode/settings.json

@@ -1,15 +1,15 @@
 {
     "cSpell.words": [
         "Cbox",
+        "clrall",
+        "clrmask",
         "MOSFET",
+        "nanofarads",
         "NFET",
         "PFET",
         "polylinegon",
         "rendec",
         "schemascii",
         "tspan"
-    ],
-    "python.linting.pylintEnabled": false,
-    "python.linting.flake8Enabled": false,
-    "python.linting.enabled": true
+    ]
 }

Makefile

@@ -0,0 +1,8 @@
+.PHONY: docs must_specify
+
+must_specify:
+	@echo "there is no default makefile rule"
+	@exit 1
+
+docs:
+	python3 scripts/docs.py

README.md

@@ -1,128 +1,5 @@
 # Schemascii
 
-[![GitHub issues](https://img.shields.io/github/issues/dragoncoder047/schemascii)](https://github.com/dragoncoder047/schemascii/issues)
-![GitHub commit activity](https://img.shields.io/github/commit-activity/w/dragoncoder047/schemascii)
-![GitHub last commit](https://img.shields.io/github/last-commit/dragoncoder047/schemascii)
-![GitHub repo file count](https://img.shields.io/github/directory-file-count/dragoncoder047/schemascii)
-![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
-
-A command-line tool and library for converting ASCII-art diagrams into beautiful SVG circuit schematics.
-
-Turn this:
-
-```none
-*--BAT1+--*-------*---*
-|         |       |   |
-|         R1    .~~~. |
-|         |     :   :-*
-|         *-----:   :---+C2--*--D2+--*----------J1
-|         |     :U1 :        |       |
-|        R2     :555:        |       |
-|         |   *-:   :-*      |       |
-|         C1  | :   : |      +       C3
-|         |   *-:   : C4     D1      +
-|         *---* .~~~. |      |       |
-|         |       |   |      |       |
-*---------*-------*---*------*-------*----------J2
-
-BAT1:5
-R1:10k
-R2:100k
-C1:10000p
-C2:10u
-C3:100u
-C4:10p
-D1:1N4001
-D2:1N4001
-U1:NE555,7,6,2,1,5,3,4,8
-J1:-5V
-J2:GND
-```
-
-Into this:
-
-![image](test_data/test_charge_pump.png)
-
-And with a little CSS, this:
-
-![image](test_data/test_charge_pump_css.png)
-
-Works with Python 3.10+. It uses the new `match` feature in a few places. If you need to run Schemascii on an older version of Python, feel free to fork it and send me a pull request.
-
-## Installation
-
-Not published to PyPI yet, so you have two options:
-
-1. Install using pip's VCS support:
-  ```bash
-  pip install git+https://github.com/dragoncoder047/schemascii
-  ```
-2. Install from source:
-  ```bash
-  git clone https://github.com/dragoncoder047/schemascii
-  cd schemascii
-  pip install .
-  ```
-
-You can also add `git+https://github.com/dragoncoder047/schemascii` to your `requirements.txt` if you have one.
-
-## Command line usage
-
-```usage
-usage: schemascii [-h] [-V] [-o OUT_FILE] [--padding PADDING] [--scale SCALE] [--stroke_width STROKE_WIDTH] [--stroke STROKE]
-                  [--label {L,V,VL}] [--nolabels]
-                  in_file
-
-Render ASCII-art schematics into SVG.
-
-positional arguments:
-  in_file               File to process.
-
-options:
-  -h, --help            show this help message and exit
-  -V, --version         show program's version number and exit
-  -o OUT_FILE, --out OUT_FILE
-                        Output SVG file. (default input file plus .svg)
-  --padding PADDING     Amount of padding to add on the edges.
-  --scale SCALE         Scale at which to enlarge the entire diagram by.
-  --stroke_width STROKE_WIDTH
-                        Width of the lines
-  --stroke STROKE       Color of the lines.
-  --label {L,V,VL}      Component label style (L=include label, V=include value, VL=both)
-  --nolabels            Turns off labels on all components, except for part numbers on ICs.
-```
-
-## Python usage
-
-```python
-import schemascii
-
-# Render a file
-svg = schemascii.render("my_circuit.txt")
-
-# Render a string
-text = ... # this is the text of your file
-svg = schemascii.render("<string>", text)
-
-# Provide options
-svg = schemascii.render("my_circuit.txt",
-    padding=10,
-    scale=15,
-    stroke_width=2,
-    stroke="black",
-    label="LV",
-    nolabels=False)
-# these are the defaults
-```
-
-## Contributing Tips
-
-Make sure you have an *editable* install, so you can edit and still be able to use the `schemascii` command to test it:
-
-```bash
-pip uninstall schemascii
-cd path/to/your/schemascii/checkout
-pip install -e .
-```
+## This is the NEXT branch which contains unstable breaking changes. Don't install this branch if you want Schemascii to work.
 
 <!-- https://realpython.com/pypi-publish-python-package/ -->

algorithm.md

@@ -1,5 +1,7 @@
 # Schemascii algorithm
 
+(THIS DOCUMENT IS HORRIBLY OUT-OF-DATE, I NEED TO RE-WRITE THE UPDATED ALGORITHM...)
+
 Everything is based on a `Grid` that contains all the data for the document. This `Grid` can be masked to show something else instead of the original, and restored to the original.
 
 The algorithm first starts by finding all the "large component" boxes in the grid. After that, it finds all the "small component" reference designators. Then it picks out the BOM notes so component values, etc. can be included.

designators.md

@@ -2,7 +2,7 @@
 
 (copied from <https://en.wikipedia.org/wiki/Reference_designator> and edited lightly)
 
-This is a list of all components that Schemascii *might* support. For a complete list of all supported components, (generated from the implementation file), please see [supported-components.md](./supported-components.md). If a component you want is not supported, have a look at [#3](https://github.com/dragoncoder047/schemascii/issues/3) or fork and implement it yourself.
+This is a list of all components that Schemascii *might* support. For a complete list of all supported components, (generated from the implementation file), please see [options.md][options]. If a component you want is not supported, post a request on [issue #3][todo_components] or fork and implement it yourself.
 
 | Designator | Component type |
 |:--:|:--|
@@ -73,3 +73,6 @@ This is a list of all components that Schemascii *might* support. For a complete
 | VT | Voltage transformer |
 | W | Wire |
 | X, XTAL, Y | Crystal oscillator, ceramic resonator |
+
+[options]: options.md
+[todo_components]: https://github.com/dragoncoder047/schemascii/issues/3

format.md

@@ -15,56 +15,122 @@ Crossed:         Joined:       Corner:     Crossed:      Crossed:    Dangling en
     |               |                         |             |
 ```
 
-## Components
-
-### Small components
+### Wire Tags
 
-Small components are notated with their reference designator: one or more uppercase letters followed by an ID, which can either be a number, or a period followed by some text.
+Wire tags look like `<name=` or `=name>` and are attached to specific wires. All wires tagged with the same `name` belong to the same net. Currently this only affects rendering.
 
-They are always written horizontally even if the terminals are on the top and bottom.
+## Components
 
-IDs are allowed to be duplicated and result in the same component values.
+Components are notated with their reference designator: one or more uppercase letters followed by an ID (a nonnegative integer) optionally followed by a suffix (which can be composed of uppercase letters and underscores)
 
-Components can be padded on either side with `#`'s to make them bigger.
+* They are always written horizontally even if the terminals are on the top and bottom.
+* IDs are allowed to be duplicated and result in the same component values.
+* Components can be padded (horizontally and vertically) `#`'s to make them bigger and control the shape (for components that support shapes).
 
 Examples:
 
 * `C33`
 * `Q1001`
-* `L.Coil`
+* `L5`
 * `F3#`
-* `D7#####`
-* `U1#####`
-* `####R.Heater####`
+* `####D7#####`
+* `R333A`
+* ```txt
+      # ######
+       # ########
+    ----# #########
+        # #U1G1#####----
+    ----# #########
+       # ########
+      # ######
+  ```
 
-Components are able to accept "flags", which are other punctuation characters and lowercase letters touching them.
+Components' terminals are annotated with "flags", which are other punctuation characters and lowercase letters touching them.
 
-* Polarized components (caps, diodes, etc.) accept a `+` to indicate the polarity,
-* Transistors use lowercase letters to indicate collector/emitter/base (for BJTs) or source/gate/drain (for FETs).
+* Polarized components (caps, diodes, etc.) use a `+` for one terminal to indicate the polarity,
+* Transistors use 3 lowercase letters to indicate collector/emitter/base (for bipolar transistors) or source/gate/drain (for field-effect transistors).
 
-### Big components
+## Annotations
 
-* Big components are indicated with a box made of `~` (top and bottom), `:` (sides), and `.` (corners).
-* The inside of the box can contain anything you want, but it must include exactly one reference designator as to what component it is.
+### Text Annotations
 
-## Reference designators
+You can include arbitrary text in the diagram by `[enclosing it in brackets like this]`.
 
-To include component values, pin numbers, etc, somewhere in the drawing but not touching any wires or other components, you can write component values - these are formatted as the reference designator (same as in circuit) followed by a `:` and the value parameter (which stops at the first whitespace). *I usually put these in a "BOM section" below the circuit itself but you could also put them right next to the component.*
+### Line Annotations
 
-For simple components, this is usually just a value rating, but *without* the units (only the Metric prefix). For more specific components (mostly semiconductor devices) this is usually the part number and/or some string to determine how to draw the component.
+To outline certain areas with lines (that are not wires), you can draw lines with colons/tildes (for straight lines), and periods/single quotes (for corners) like so:
 
-Examples:
+```txt
+   .~~~~~~~~~~.
+   :  .~~~    :
+   :  :       :
+   :  :       :
+   :  :    .~~'~~~~.
+   :  '~~~~'       :
+   '~~~~~~~~~~~~~~~'
+```
+
+Lines are allowed to cross wires. They are crossed the same way that wires cross each other.
+
+## Data
+
+Every drawing is required to have a "data section" appended after it. The data section contains mappings of values to tell Schemascii how to render each component (e.g. how thick to make the lines, what the components' values are, etc.)
+
+The data section is separated from the actual circuit by a line containing `---` and nothing else. This is REQUIRED and Schemascii will complain if it doesn't find any line containing `---` and nothing else, even if there is no data after it.
+
+Here is some example data:
+
+```txt
+* {
+    %% these are global config options
+    color = black
+    width = 2; padding = 20;
+    format = symbol
+    mystring = "hello\nworld"
+}
+
+R* %% matches any resistor
+{tolerance = .05; wattage = 0.25}
+
+VR1 {
+    resistance = 0 - 10k; %% ranges on variable components
+    %% trailing comments are allowed
+}
+```
+
+In each RULE, the SELECTOR defines what components and/or drawing objects match; for the ones that match, the MAPPING (which is stored as a Python `dict`) is or'ed into the computed properties. Rules on the bottom take precedence (there is no such thing as specificity like there is in CSS).
+
+Selectors can match multiple scopes by using glob matching. Schemascii currently uses [`fnmatch`][fnmatch] to determine matching selectors but I'll probably change that.
+
+See [options.md][options] for what options are available in which scopes.
+
+Here is a rough grammar (space ignored):
+
+```ebnf
+DATA = RULE (eol+ RULE)* ;
+RULE = SELECTOR eol* MAPPING ;
+SELECTOR = symbol ;
+MAPPING = "{" ((NAME "=" VALUE)? eol)* "}" ;
+NAME = string | symbol ;
+VALUE = (number | string | symbol)* ;
+number = /(?:\d*\.)?\d+(?:[Ee][+-]?\d+)?/ ;
+string = /"(?:\\"|[^"])+"|\s+/ ;
+symbol = <any sequence of printing characters that isn't another kind of token>
+eol = ";" | comment? "\n"+ ;
+comment = "%%" <everything until newline> ;
+```
+
+### Metric values
 
-* `C33:2.2u` -- "2.2 &micro;F"
-* `Q1001:pnp:TIP102` -- "pnp", "npn", "pfet", or "nfet" to determine what kind of transistor, plus the part number; printed verbatim
-* `L51:0.33` -- this is rewritten to "330 mH" so that it has no decimal point.
-* `F3:1500m` -- rewritten: "1.5 A"
-* `D7:1N4001` -- again, part number
-* `U1:SN74LS08N,14,1,2,7,3` -- some components let you label pins with whatever you want (in this case just numbers). They start at the top-leftmost and follow **counterclockwise** to follow with the pin-numbering of most IC's.
-* `R2:10,5` -- this is formatted as "10 &ohm; 5 W". The second value is the rating; for resistors, this is a wattage, for most else, this is a maximum voltage.
+For many small components, the value of the component is just a number and some unit -- e.g. for resistors it's ohms (&ohm;). Schemascii includes built-in Metric normalization and units, so if the "value" is a Metric number it will be re-written to be as short as possible while still observing the conventions of typical component values. If the unit symbol is not included, it will be added.
 
-## Inline configuration values
+* `value = 0.33m` on an inductor --> "330 &micro;H" (integer values are preferred).
+* `value = 0.33` on a resistor --> "0.33 &ohm;" (no Metric multiplier is preferred).
+* `value = 1500mA` on a fuse --> "1.5 A" (using decimal point is shorter)
+* `value = 2.2 nF` on a capacitor --> "2200 pF" (capacitances aren't typically given in nanofarads)
+* `value = 10; power = 5` --> "10 &ohm; 5 W". Many components have "secondary" optional values; the name will be given in the [options][].
 
-**New in 0.2.0!**
+Also, if the value is not even a number -- such as `L1 {value = "detector coil"}`, the Metric-normalization code will not activate, and the value written will be used verbatim -- "L1 detector coil".
 
-You can specify configuration values for rendering the components inline in the document by writing `!name=value!` in your document. See the help output of the Schemascii CLI for the different options (in the README) or look at the config options at the top of [`configs.py`](https://github.com/dragoncoder047/schemascii/blob/main/schemascii/configs.py). The most common options I use are `scale` and `padding`.
+[fnmatch]: https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch
+[options]: options.md