Merge branch 'main' into 'main'

Draft: Created Tutorial page; TODOs pending.

See merge request jwestman/blueprint-compiler!66

blueprintcompiler/language/adw_breakpoint.py

@@ -81,8 +81,8 @@ class AdwBreakpointSetter(AstNode):
         return self.tokens["property"]
 
     @property
-    def value(self) -> Value:
-        return self.children[Value][0]
+    def value(self) -> T.Optional[Value]:
+        return self.children[Value][0] if len(self.children[Value]) > 0 else None
 
     @property
     def gir_class(self) -> T.Optional[GirType]:
@@ -106,7 +106,10 @@ class AdwBreakpointSetter(AstNode):
             return None
 
     @property
-    def document_symbol(self) -> DocumentSymbol:
+    def document_symbol(self) -> T.Optional[DocumentSymbol]:
+        if self.value is None:
+            return None
+
         return DocumentSymbol(
             f"{self.object_id}.{self.property_name}",
             SymbolKind.Property,

blueprintcompiler/outputs/xml/__init__.py

@@ -308,6 +308,9 @@ class XmlOutput(OutputFormat):
 
         elif isinstance(extension, AdwBreakpointSetters):
             for setter in extension.setters:
+                if setter.value is None:
+                    continue
+
                 attrs = {}
 
                 if isinstance(setter.value.child, Translated):

blueprintcompiler/outputs/xml/xml_emitter.py

@@ -73,6 +73,7 @@ class XmlEmitter:
         self._needs_newline = False
 
     def put_cdata(self, text: str):
+        text = text.replace("]]>", "]]]]><![CDATA[>")
         self.result += f"<![CDATA[{text}]]>"
         self._needs_newline = False
 

docs/tutorial.rst

@@ -0,0 +1,481 @@
+========
+Tutorial
+========
+
+.. margin at column 75
+
+Read this if you want to learn how to use Blueprint and never used
+the XML syntax that can be read by GtkBuilder.
+
+For compatibility with Blueprint IDE extensions, blueprint files
+should end with ``.blp``.
+
+
+Namespaces
+----------
+
+Blueprint needs the widget library to be imported. These include Gtk,
+Libadwaita, Shumate, etc. To import a namespace, write ``using`` followed
+by the library and version number.
+
+.. code-block::
+
+    using Gtk 4.0;
+    using Adw 1;
+
+The Gtk import is required in all blueprints and the minor version
+number must be 0.
+
+
+Comments
+--------
+
+Blueprint has inline or multi-line comments
+
+.. code-block::
+
+    // This is an inline comment
+    /* This is
+       a multiline
+       comment */
+
+Multi-line comments can't have inner multi-line comments. The compiler
+will interpret the inner comment's closing token as the outer comment's
+closing token. For example, the following will not compile:
+
+.. code-block::
+
+    // Bad comment below:
+    /* Outer comment 
+        /* Inner comment */
+    */
+
+
+Widgets
+-------
+
+Create widgets in the following format:
+
+.. code-block::
+
+    Namespace.WidgetClass {
+
+    }
+
+The Gtk namespace is implied for widgets, so you can just write the
+widget class
+
+.. code-block::
+
+    Box {
+    
+    }
+
+Other namespaces must be written explicitly.
+
+.. code-block::
+
+    Adw.Leaflet {
+
+    }
+
+Consult the widget library's documentation for a list of widgets.
+A good place to start is
+`the Gtk4 widget list <https://docs.gtk.org/gtk4/index.html>`_.
+
+Naming Widgets
+~~~~~~~~~~~~~~
+
+Widgets can be given a **name/ID** so that they can be referenced by your
+program or other widgets in the blueprint.
+
+.. code-block::
+
+    Namespace.WidgetClass widget_id {
+    
+    }
+
+Any time you want to use this widget as a property (more about that in the
+next section) or something else, write the widget's **ID** (e.g.
+``main_window``).
+
+
+Properties
+----------
+
+Every widget has properties defined by their GObject class.
+For example, the Libadwaita documentation lists the
+`properties of the Toast class <https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1.2/class.Toast.html#properties>`_.
+Write properties inside the curly brackets of a widget:
+
+.. code-block::
+
+    Namespace.WidgetClass {
+        property-name: value;
+    }
+
+Properties values are *all lowercase* (except strings) and must end with a
+semicolon (``;``).
+
+Property Types
+~~~~~~~~~~~~~~
+
+These are the **types** of values that can be used in properties:
+    - Booleans: ``true``, ``false``
+    - Numbers: e.g. ``1``, ``1.5``, ``-2``, ``-2.5``
+    - Strings (single- or double-quoted): e.g. ``"a string"``, ``'another string'``
+    - Enums
+    - Widgets
+
+Properties are **strongly typed**, so you can't use, for example, a string
+for the orientation property, which requires an ``Orientation`` enum
+vartiant as its value.
+
+Enum Properties
+~~~~~~~~~~~~~~~
+
+In the Gtk documentation, enum variants have long names and are
+capitalized. For example, these are the
+`Orientation <https://docs.gtk.org/gtk4/enum.Orientation.html>`_
+enum variants:
+
+    - GTK_ORIENTATION_HORIZONTAL
+    - GTK_ORIENTATION_VERTICAL
+
+In the blueprint, you would only write the *variant* part of the enum in
+*lowercase*, just like you would in the XML.
+
+.. code-block::
+
+    Box {
+        orientation: horizontal;
+    }
+
+Widget Properties
+~~~~~~~~~~~~~~~~~
+
+Some widgets take other widgets as properties. For example, the
+``Gtk.StackSidebar`` has a stack property which takes a ``Gtk.Stack`` widget.
+You can create a new widget for the value, or you can reference another
+widget by its **ID**.
+
+.. code-block::
+
+    StackSidebar {
+        stack: Stack { };
+    }
+
+OR
+
+.. code-block::
+
+    StackSidebar {
+        stack: my_stack;
+    }
+
+    Stack my_stack {
+
+    }
+
+Note the use of a semicolon at the end of the property in both cases.
+Inline widget properties are not exempt of this rule.
+
+
+Property Bindings
+-----------------
+
+If you want a widget's property to have the same value as another widget's
+property (without hard-coding the value), you could ``bind`` two widgets'
+properties of the same type. Bindings must reference a *source* widget by
+**ID**. As long as the two properties have the same type, you can bind
+properties of different names and of widgets with different widget classes.
+
+.. code-block::
+
+    Box my_box {
+        halign: fill; // Source
+    }
+
+    Button {
+        valign: bind my_box.halign; // Target
+    }
+
+Binding Flags
+~~~~~~~~~~~~~
+
+Modify the behavior of bindings with flags. Flags are written after the
+binding. The default behavior is that the *Target*'s value will be
+changed to the *Source*'s value when the binding is created and when the
+*Source* value changes.
+
+.. code-block::
+
+    Box my_box {
+        hexpand: true; // Source
+    }
+
+    Button {
+        vexpand: bind my_box.hexpand inverted bidirectional; // Target
+    }
+
+no-sync-create
+    Prevent setting the *Tartget* with the *Source*'s value,
+    updating the target value when the *Source* value changes, not when
+    the binding is first created. Useful when the *Target* property has
+    another initial value that is not the *Source* value.
+
+bidirectional
+    When either the *Source* or *Target* value is modified, the other's
+    value will be updated. For example, if the logic of the program
+    changes the Button's vexpand value to ``false``, then the Box's halign
+    value will also be updated to ``false``.
+
+inverted
+    If the property is a boolean, the value of the bind can be negated
+    with this flag. For example, if the Box's hexpand property is ``true``,
+    the Button's vexpand property will be ``false`` in the code above.
+
+
+Signals
+-------
+
+Gtk allows you to register signals in your program. This can be done by
+getting the object from the GtkBuilder and connecting a handler to the
+signal. Or register the handler with the application and reference it in
+the blueprint.
+
+Signals have an *event name*, a *handler* (aka callback), and optionally
+some *flags*. Each widget will have a set of defined signals. Consult the
+widget's documentation for a list of its signals.
+
+To register a handler with the application, consult the documentation for
+your language's bindings of Gtk.
+
+.. code-block::
+
+    WidgetClass {
+        event_name => handler_name() flags;
+    }
+
+.. TODO: add a list of flags and their descriptions
+
+By default, signals in the blueprint will pass the widget that the signal
+is for as an argument to the *handler*. However, you can specify the
+widget that is passed to the handler by referencing its **ID** inside the
+parenthesis.
+
+.. code-block::
+
+    Label my_label {
+        label: "Hide me"; 
+    }
+
+    Button {
+        clicked => hide_widget(my_label);
+    }
+
+
+Custom Widget Classes
+---------------------
+
+Some programs have custom widgets defined in their logic, so blueprint
+won't know that they exist. Writing widgets not defined in the GIR will
+result in an error. Prepend a custom widget with a period (``.``) to prevent the
+compiler from trying to validate the widget. This is essentially saying
+the widget has no *namespace*.
+
+To register a custom widget with the application consult the documentation
+for your language's bindings of Gtk.
+
+.. code-block::
+
+    .MyCustomWidget {
+
+    }
+
+
+Templates
+---------
+.. TODO
+
+
+CSS Style Classes
+-----------------
+
+.. TODO: Unsure if to group styles with widget-specific items
+
+Widgets can be given style classes that can be used with your CSS or
+`predefined styles <https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1.2/style-classes.html>`_
+in libraries like Libadwaita.
+
+.. code-block::
+
+    Button {
+        label: "Click me";
+        styles ["my-style", "pill"]
+    }
+
+Note the lack of a *colon* after "styles" and a *semicolon* at the end of
+the line. This syntax looks like the properties syntax, but it compiles to
+XML completely different from properties.
+
+Consult your language's bindings of Gtk to use a CSS file.
+
+Non-property Elements
+~~~~~~~~~~~~~~~~~~~~~
+
+Some widgets will have elements which are not properties, but they sort
+of act like properties. Most of the time they will be specific only to a
+certain widget. *Styles* is one of these elements, except that styles can
+be used for any widget. Similar to how every widget has styles,
+``Gtk.ComboBoxText`` has *items*:
+
+.. code-block::
+
+    Gtk.ComboBoxText {
+        items [
+            item1: "Item 1",
+            item2: _("Items can be translated"),
+            "The item ID is not required",
+        ]
+    }
+
+See :doc:`examples <examples#widget-specific-items>` for a list of more of these
+widget-specific items.
+
+
+Menus
+-----
+
+Menus are usually the widgets that are placed along the top-bar of a
+window, or pop up when you right-click some other widget. In Blueprint, a
+``menu`` is a ``Gio.MenuModel`` that can be shown by MenuButtons or other
+widgets.
+
+In Blueprint, a ``menu`` can have *items*, *sections*, and *submenus*.
+Like widgets, a ``menu`` can also be given an **ID**.
+The `Menu Model section of the Gtk.PopoverMenu documentation <https://docs.gtk.org/gtk4/class.PopoverMenu.html#menu-models>`_
+has complete details on the menu model.
+
+Here is an example of a menu:
+
+.. code-block::
+
+    menu my_menu {
+        section {
+            label: "File";
+            item {
+                label: "Open";
+                action: "win.open";
+                icon-name: "document-open-symbolic";
+            }
+            item {
+                label: "Save";
+                action: "win.save";
+                icon-name: "document-save-symbolic";
+            }
+            submenu {
+                label: "Save As";
+                icon-name: "document-save-as-symbolic";
+                item {
+                    label: "PDF";
+                    action: "win.save_as_pdf";
+                }
+            }
+        }
+    }
+
+There is a shorthand for *items*. Items require at least a label. The
+action and icon-name are optional.
+
+.. code-block::
+
+    menu {
+        item ( "Item 2" )
+        item ( "Item 2", "app.action", "icon-name" )
+    }
+
+A widget that uses a ``menu`` is ``Gtk.MenuButton``. It has the *menu-model*
+property, which takes a menu. Write the menu at the root of the blueprint
+(meaning not inside any widgets) and reference it by **ID**.
+
+.. code-block::
+
+    MenuButton {
+        menu-model: my_menu;
+    }
+
+
+Child Types
+-----------
+
+Child types describe how a child widget is placed on a parent widget. For
+example, HeaderBar widgets can have children placed either at the *start*
+or the *end* of the HeaderBar. Child widgets of HeaderBars can have the
+*start* or *end* types. Values for child types a widget can have are
+defined in the widget's documentation.
+
+Child types in blueprint are written between square brackets (``[`` ``]``) and before
+the child the type is for.
+
+The following blueprint code...
+
+.. code-block::
+
+    HeaderBar {
+        [start]
+        Button {
+            label: "Button";
+        }
+    }
+
+\... would look like this:
+
+.. code-block::
+
+    ---------------------------
+    | Button                  |
+    ---------------------------
+
+And the following blueprint code...
+
+.. code-block::
+
+    HeaderBar {
+        [end]
+        Button {
+            label: "Button";
+        }
+    }
+
+\... would look like this:
+
+.. code-block::
+
+    ---------------------------
+    |                  Button |
+    ---------------------------
+
+
+Translatable Strings
+--------------------
+
+Mark any string as translatable using this syntax: ``_("...")``.
+
+Two strings that are the same in English could be translated in different
+ways in other languages because of different *contexts*. Translatable
+strings with context look like this: ``C_("context", "...")``. An example
+where a context is needed is the word "have", which in Spanish could
+translate to "tener" or "haber".
+
+.. code-block::
+
+    Label {
+        label: C_("1st have", "have");
+    }
+
+    Label {
+        label: C_("2nd have", "have");
+    }
+
+See `translations <translations.html>`_ for more details.

tests/samples/list_factory_nested.blp

@@ -0,0 +1,17 @@
+using Gtk 4.0;
+
+Gtk.ListView {
+  factory: Gtk.BuilderListItemFactory list_item_factory {
+    template ListItem {
+      child: Gtk.ListView {
+        factory: Gtk.BuilderListItemFactory list_item_factory {
+          template ListItem {
+            child: Gtk.Label {
+              label: bind template.item as <$MyObject>.name;
+            };
+          }
+        };
+      };
+    }
+  };
+}

tests/samples/list_factory_nested.ui

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+DO NOT EDIT!
+This file was @generated by blueprint-compiler. Instead, edit the
+corresponding .blp file and regenerate this file with blueprint-compiler.
+-->
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <object class="GtkListView">
+    <property name="factory">
+      <object class="GtkBuilderListItemFactory" id="list_item_factory">
+        <property name="bytes"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <template class="GtkListItem">
+    <property name="child">
+      <object class="GtkListView">
+        <property name="factory">
+          <object class="GtkBuilderListItemFactory" id="list_item_factory">
+            <property name="bytes"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <template class="GtkListItem">
+    <property name="child">
+      <object class="GtkLabel">
+        <binding name="label">
+          <lookup name="name" type="MyObject">
+            <lookup name="item" type="GtkListItem">
+              <constant>GtkListItem</constant>
+            </lookup>
+          </lookup>
+        </binding>
+      </object>
+    </property>
+  </template>
+</interface>]]]]><![CDATA[></property>
+          </object>
+        </property>
+      </object>
+    </property>
+  </template>
+</interface>]]></property>
+      </object>
+    </property>
+  </object>
+</interface>

tests/samples/list_factory_nested_dec.blp

@@ -0,0 +1,18 @@
+using Gtk 4.0;
+
+ListView {
+  factory: BuilderListItemFactory list_item_factory {
+    template ListItem {
+      child: ListView {
+        factory: BuilderListItemFactory list_item_factory {
+          template ListItem {
+            child: Label {
+              label: bind template.item as <$MyObject>.name;
+            };
+          }
+        };
+      };
+    }
+  };
+}
+

tests/test_tokenizer.py

@@ -25,7 +25,7 @@ from blueprintcompiler.tokenizer import Token, TokenType, tokenize
 
 
 class TestTokenizer(unittest.TestCase):
-    def assert_tokenize(self, string: str, expect: [Token]):
+    def assert_tokenize(self, string: str, expect: list[Token]):
         try:
             tokens = tokenize(string)
             self.assertEqual(len(tokens), len(expect))