diff options
author | Christian Hergert <chergert@redhat.com> | 2020-09-08 18:21:13 -0700 |
---|---|---|
committer | Christian Hergert <chergert@redhat.com> | 2020-09-21 15:32:49 -0700 |
commit | 76d5a1ff77ffc16f6eee0da57344b0266743957e (patch) | |
tree | 65c7dcb28f8bd9f64297ec4e0544df2beeafc6ef /docs | |
parent | adde4b14d435baf636236e80e8993265b47a2789 (diff) | |
download | gtksourceview-76d5a1ff77ffc16f6eee0da57344b0266743957e.tar.gz |
This is a straightforward port of Builder's snippet system to GtkSourceView.
A number of new objects are added as part of this commit to the
GtkSourceView ABI.
- GtkSourceSnippet provides an object representing a snippet to be inserted
into a textview. Snippets are associated with a textview rather than a
buffer because of incremental state that is necessary to interact with
widgetry and event controllers. Additionally, it doesn't make sense to have
this attached to the buffer when the view area could be different.
- GtkSourceSnippetChunk is a single chunk of a snippet. A snippet contains
zero or more chunks. A chunk can have a spec (which can be evaluated
using variables) or text set (such as after typing in the editor). Also, a
chunk can have a "focus-position" which allows the user to tab through the
chunks of the snippet.
- GtkSourceSnippetContext provides state which can be expanded as part of
the snippet. This is useful to expand variables set by the application or
filters to transform input text or other variables.
- gtksourceview-snippets.c contains integration bits to be hooked into
GtkSourceView. Keeping much of this outside of gtksourceview.c helps
to keep things mostly self-contained but also ensures that we don't keep
growing gtksourceview.c with complexity and size. Future additions to
gtksourceview.c should be done this way when it makes sense (such as
adding indenters).
- GtkSourceSnippetBundle is used for multiple purposes because it is handy
to do so without increasing the number of GObjects we need and because
it flows naturally. It is used to parse new snippet files as well as
merge multiple snippet files together. Furthermore, it serves as a
GListModel with a filtered set of snippets when queried by the
snippet manager. This type is private, however.
- A completion provider is provided so that applications can use snippets
provided by the snippet manager, however it still needs porting to the
new completion engine.
- Tabbing will expand the snippet based on the current word.
- The classic style scheme has been adjusted to give us access to a focus
position tag so that they are highlighted to the user. Style schemes
bundled with GtkSourceView will want to implement this in a future commit.
- Applications can insert snippets using gtk_source_view_push_snippet().
- Using the mouse or touch input to move to another chunk will cause it to
be focused (and selected). Moving between chunks manually will cause the
snippet to be released.
- A number of snippet variables are made available as seen in other snippet
engines, notable textmate and Visual Studio Code.
- You can toggle snippets on/off in test-widget using a checkbox. The
snippets from data/snippets/ are available based on the current
language.
- Documentation for the file format and snippet text format is provided
as part of the gtk-doc installation.
- A snippets.rng file is provided to validate snippet files
- Various style schemes have gotten "snippet-focus" styles that apply
to the focus positions of the snippet.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/reference/gtksourceview-5.0-sections.txt | 113 | ||||
-rw-r--r-- | docs/reference/gtksourceview-docs.xml.in | 10 | ||||
-rw-r--r-- | docs/reference/meson.build | 11 | ||||
-rw-r--r-- | docs/reference/snippet-reference.xml.in | 207 |
4 files changed, 341 insertions, 0 deletions
diff --git a/docs/reference/gtksourceview-5.0-sections.txt b/docs/reference/gtksourceview-5.0-sections.txt index 504cd009..bacb98da 100644 --- a/docs/reference/gtksourceview-5.0-sections.txt +++ b/docs/reference/gtksourceview-5.0-sections.txt @@ -207,6 +207,21 @@ gtk_source_completion_words_get_type </SECTION> <SECTION> +<FILE>completionsnippets</FILE> +GtkSourceCompletionSnippets +gtk_source_completion_snippets_new +<SUBSECTION Standard> +GTK_SOURCE_COMPLETION_SNIPPETS +GTK_SOURCE_COMPLETION_SNIPPETS_CLASS +GTK_SOURCE_COMPLETION_SNIPPETS_GET_CLASS +GTK_SOURCE_IS_COMPLETION_SNIPPETS +GTK_SOURCE_IS_COMPLETION_SNIPPETS_CLASS +GTK_SOURCE_TYPE_COMPLETION_SNIPPETS +GtkSourceCompletionSnippetsClass +gtk_source_completion_snippets_get_type +</SECTION> + +<SECTION> <FILE>encoding</FILE> GtkSourceEncoding <SUBSECTION> @@ -704,6 +719,101 @@ gtk_source_search_settings_get_type </SECTION> <SECTION> +<FILE>snippet</FILE> +GtkSourceSnippet +gtk_source_snippet_add_chunk +gtk_source_snippet_copy +gtk_source_snippet_get_context +gtk_source_snippet_get_description +gtk_source_snippet_get_focus_position +gtk_source_snippet_get_language_id +gtk_source_snippet_get_name +gtk_source_snippet_get_n_chunks +gtk_source_snippet_get_nth_chunk +gtk_source_snippet_get_trigger +gtk_source_snippet_new +gtk_source_snippet_set_description +gtk_source_snippet_set_language_id +gtk_source_snippet_set_name +gtk_source_snippet_set_trigger +<SUBSECTION Standard> +GTK_SOURCE_IS_SNIPPET +GTK_SOURCE_IS_SNIPPET_CLASS +GTK_SOURCE_SNIPPET +GTK_SOURCE_SNIPPET_CLASS +GTK_SOURCE_SNIPPET_GET_CLASS +GTK_SOURCE_TYPE_SNIPPET +GtkSourceSnippetClass +</SECTION> + +<SECTION> +<FILE>snippetchunk</FILE> +GtkSourceSnippetChunk +gtk_source_snippet_chunk_copy +gtk_source_snippet_chunk_get_context +gtk_source_snippet_chunk_get_focus_position +gtk_source_snippet_chunk_get_spec +gtk_source_snippet_chunk_get_text +gtk_source_snippet_chunk_get_text_set +gtk_source_snippet_chunk_new +gtk_source_snippet_chunk_set_context +gtk_source_snippet_chunk_set_focus_position +gtk_source_snippet_chunk_set_spec +gtk_source_snippet_chunk_set_text +gtk_source_snippet_chunk_set_text_set +<SUBSECTION Standard> +GTK_SOURCE_IS_SNIPPET_CHUNK +GTK_SOURCE_IS_SNIPPET_CHUNK_CLASS +GTK_SOURCE_SNIPPET_CHUNK +GTK_SOURCE_SNIPPET_CHUNK_CLASS +GTK_SOURCE_SNIPPET_CHUNK_GET_CLASS +GTK_SOURCE_TYPE_SNIPPET_CHUNK +GtkSourceSnippetChunkClass +</SECTION> + +<SECTION> +<FILE>snippetcontext</FILE> +GtkSourceSnippetContext +gtk_source_snippet_context_clear_variables +gtk_source_snippet_context_expand +gtk_source_snippet_context_get_variable +gtk_source_snippet_context_new +gtk_source_snippet_context_set_constant +gtk_source_snippet_context_set_line_prefix +gtk_source_snippet_context_set_tab_width +gtk_source_snippet_context_set_use_spaces +gtk_source_snippet_context_set_variable +<SUBSECTION Standard> +GTK_SOURCE_IS_SNIPPET_CONTEXT +GTK_SOURCE_IS_SNIPPET_CONTEXT_CLASS +GTK_SOURCE_SNIPPET_CONTEXT +GTK_SOURCE_SNIPPET_CONTEXT_CLASS +GTK_SOURCE_SNIPPET_CONTEXT_GET_CLASS +GTK_SOURCE_TYPE_SNIPPET_CONTEXT +GtkSourceSnippetContextClass +</SECTION> + +<SECTION> +<FILE>snippetmanager</FILE> +GtkSourceSnippetManager +gtk_source_snippet_manager_get_default +gtk_source_snippet_manager_get_search_path +gtk_source_snippet_manager_get_snippet +gtk_source_snippet_manager_list_groups +gtk_source_snippet_manager_list_matching +gtk_source_snippet_manager_set_search_path +<SUBSECTION Standard> +GTK_SOURCE_IS_SNIPPET_MANAGER +GTK_SOURCE_IS_SNIPPET_MANAGER_CLASS +GTK_SOURCE_SNIPPET_MANAGER +GTK_SOURCE_SNIPPET_MANAGER_CLASS +GTK_SOURCE_SNIPPET_MANAGER_GET_CLASS +GTK_SOURCE_TYPE_SNIPPET_MANAGER +GtkSourceSnippetManagerClass +</SUBSECTION> +</SECTION> + +<SECTION> <FILE>spacedrawer</FILE> GtkSourceSpaceDrawer GtkSourceSpaceTypeFlags @@ -924,6 +1034,9 @@ gtk_source_view_set_show_line_marks gtk_source_view_get_show_line_marks gtk_source_view_set_background_pattern gtk_source_view_get_background_pattern +gtk_source_view_get_enable_snippets +gtk_source_view_set_enable_snippets +gtk_source_view_push_snippet <SUBSECTION Standard> GtkSourceViewClass GTK_SOURCE_IS_VIEW diff --git a/docs/reference/gtksourceview-docs.xml.in b/docs/reference/gtksourceview-docs.xml.in index de572897..89e3bd49 100644 --- a/docs/reference/gtksourceview-docs.xml.in +++ b/docs/reference/gtksourceview-docs.xml.in @@ -50,6 +50,7 @@ <xi:include href="xml/completionitem.xml"/> <xi:include href="xml/completionproposal.xml"/> <xi:include href="xml/completionprovider.xml"/> + <xi:include href="xml/completionsnippets.xml"/> <xi:include href="xml/completionwords.xml"/> </chapter> @@ -83,6 +84,15 @@ <xi:include href="xml/searchsettings.xml"/> </chapter> + <chapter id="snippets"> + <title>Snippets</title> + <xi:include href="snippet-reference.xml"/> + <xi:include href="xml/snippet.xml"/> + <xi:include href="xml/snippetchunk.xml"/> + <xi:include href="xml/snippetcontext.xml"/> + <xi:include href="xml/snippetmanager.xml"/> + </chapter> + <chapter id="misc"> <title>Misc</title> <xi:include href="xml/map.xml"/> diff --git a/docs/reference/meson.build b/docs/reference/meson.build index 622a4de8..8fe0ecf3 100644 --- a/docs/reference/meson.build +++ b/docs/reference/meson.build @@ -16,6 +16,7 @@ reference_private_h = [ 'gtksourcecompletioncontext-private.h', 'gtksourcecompletioninfo-private.h', 'gtksourcecompletionmodel-private.h', + 'gtksourcecompletionsnippetsproposal-private.h', 'gtksourcecompletionwordsbuffer-private.h', 'gtksourcecompletionwordslibrary-private.h', 'gtksourcecompletionwordsproposal-private.h', @@ -35,6 +36,10 @@ reference_private_h = [ 'gtksourcepixbufhelper-private.h', 'gtksourceregex-private.h', 'gtksourcesearchcontext-private.h', + 'gtksourcesnippet-private.h', + 'gtksourcesnippetbundle-private.h', + 'gtksourcesnippetcontext-private.h', + 'gtksourcesnippetmanager-private.h', 'gtksourcestyle-private.h', 'gtksourcestylescheme-private.h', 'gtksourcestyleschememanager-private.h', @@ -65,6 +70,12 @@ lang_reference_xml = configure_file( configuration: config_h ) +snippet_reference_xml = configure_file( + input: 'snippet-reference.xml.in', + output: 'snippet-reference.xml', + configuration: config_h +) + style_reference_xml = configure_file( input: 'style-reference.xml.in', output: 'style-reference.xml', diff --git a/docs/reference/snippet-reference.xml.in b/docs/reference/snippet-reference.xml.in new file mode 100644 index 00000000..0d10c907 --- /dev/null +++ b/docs/reference/snippet-reference.xml.in @@ -0,0 +1,207 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> +]> +<refentry id="snippet-reference"> +<refmeta> +<refentrytitle>Snippet Definition Reference</refentrytitle> +</refmeta> + +<refnamediv> +<refname>Snippet Definition Reference</refname> +<refpurpose> +Reference to the GtkSourceView snippet definition file format +</refpurpose> +</refnamediv> + +<refsect1> +<title>Overview</title> +<para> +This is an overview of the Snippet Definition XML format, describing the +meaning and usage of every element and attribute. The formal definition is +stored in the RelaxNG schema file <filename>snippets.rng</filename> which +should be installed on your system in the directory +<filename>${PREFIX}/share/gtksourceview-@GSV_API_VERSION@/</filename> (where +<filename>${PREFIX}</filename> can be <filename>/usr/</filename> or +<filename>/usr/local/</filename> if you have installed from source). +</para> +</refsect1> + +<para> +The toplevel tag in a snippet file is <code><snippets></code>. +It has the following attributes: +<variablelist> +<varlistentry> +<term><code>_group</code></term> +<listitem><para> +The group for the snippet. This is purely used to group snippets together +in user-interfaces. +</para></listitem> +</varlistentry> +</variablelist> +</para> + +<para> +Within the snippets tag is one or more <code><snippets></code> elements. +It has the following attributes: +<variablelist> +<varlistentry> +<term><code>_name</code></term> +<listitem><para> +The name of the snippet. This may be displayed in the user interface such as +in a snippet editor or completion providers. An attempt will be made to translate +it by GtkSourceView. +</para></listitem> +</varlistentry> +<varlistentry> +<term><code>trigger</code></term> +<listitem><para> +The word trigger of the snippet. If the user types this word and hits Tab, +the snippet will be inserted. +</para></listitem> +</varlistentry> +<varlistentry> +<term><code>_description</code></term> +<listitem><para> +The description of the snippet. This may be displayed in the user interface +such as in a snippet editor or completion providers. An attempt will be made +to translate it by GtkSourceView. +</para></listitem> +</varlistentry> +</variablelist> +</para> + +<para> +Within the snippet tag is one or more <code><text></code> elements. +It has the following attributes: +<variablelist> +<varlistentry> +<term><code>languages</code></term> +<listitem><para> +A semicolon separated list of GtkSourceView language identifiers for which this +text should be used when inserting the snippet. Defining this on the +<code><text></code> tag allows a snippet to have multiple variants based +on the programming language. +</para></listitem> +</varlistentry> +<varlistentry> +<term><code>CDATA</code></term> +<listitem><para> +Within the <code><text></code> tag should be a single +<code><![CDATA[]]></code> tag containing the text for the snippet +between the []. You do not need to use CDATA if the text does not have any +embedded characters that will conflict with XML. +</para></listitem> +</varlistentry> +</variablelist> +</para> + +<refsect1> +<title>Snippet Text Format</title> +<para> +GtkSourceView's snippet text format is largely based upon other snippet +implementations that have gained popularity. Since there are so many, it likely +differs in some small ways from what you may have used previously. +</para> + +<refsect2> +<title>Focus Positions</title> +<para>Focus positions allow the user to move through chunks within the snippet +that are meant to be edited by the user. Each subsequent "Tab" by the user will +advance them to the next focus position until all have been exhausted.</para> +<para>To set a focus position in your snippet, use a dollar sign followed by +curly braces with the focus position number inside like <code>${1}</code> or +<code>${2}</code>. The user can also use Shift+Tab to move to a previous tab +stop.</para> +<para>The special <code>$0</code> tab stop is used to place the cursor after +all focus positions have been exhausted. If no focus position was provided, the +cursor will be placed there automatically.</para> +<para>You can also set a default value for a focus position by appending a colon +and the initial value such as <code>${2:default_value}</code>. You can even +reference other chunks such as <code>${3:$2_$1}</code> to join the contents of +<code>$2</code>, an underbar <code>_</code>, and <code>$1</code>.</para> +</refsect2> + +<refsect2> +<title>Variable Expansion</title> +<para>When a snippet is expanded into the #GtkSourceView, chunks may reference +a number of built-in or application provided variables. Applications may +add additional variables with either gtk_source_snippet_context_set_constant() +(for things that do not change) or gtk_source_snippet_context_set_variable() +for values that may change.</para> +<para>Snippet chunks can reference a variable anywhere by using a dollar sign +followed by the variable name such as <code>$variable</code>.</para> +<para>You can also reference another focus position's value by usin their focus +position number as the variable such as <code>$1</code>.</para> +<para>To post-process a variables value, enclose the variable in curly-brackets +and use the pipe operator to denote the post-processing function such as +<code>${$1|capitalize}</code>.</para> +</refsect2> + +<refsect2> +<title>Predefined Variables</title> +<para>A number of predefined variables are provided by GtkSourceView which can be extended by applications. +<variablelist> +<varlistentry><term><code>$CURRENT_YEAR</code></term><listitem><para>The current 4-digit year</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_YEAR_SHORT</code></term><listitem><para>The last 2 digits of the current year</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_MONTH</code></term><listitem><para>The current month as a number from 01-12</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_MONTH_NAME</code></term><listitem><para>The full month name such as "August" in the current locale</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_MONTH_NAME_SHORT</code></term><listitem><para>The short month name such as "Aug" in the current locale</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_DATE</code></term><listitem><para>The current day of the month from 1-31</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_DAY_NAME</code></term><listitem><para>The current day such as "Friday" in the current locale</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_DAY_NAME_SHORT</code></term><listitem><para>The current day using the shortened name such as "Fri" in the current locale</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_HOUR</code></term><listitem><para>The current hour in 24-hour format</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_MINUTE</code></term><listitem><para>The current minute within the hour</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_SECOND</code></term><listitem><para>The current second within the minute</para></listitem></varlistentry> +<varlistentry><term><code>$CURRENT_SECONDS_UNIX</code></term><listitem><para>The number of seconds since the UNIX epoch</para></listitem></varlistentry> +<varlistentry><term><code>$NAME_SHORT</code></term><listitem><para>The users login user name (See g_get_user_name())</para></listitem></varlistentry> +<varlistentry><term><code>$NAME</code></term><listitem><para>The users full name, if known (See g_get_full_name())</para></listitem></varlistentry> +<varlistentry><term><code>$TM_CURRENT_LINE</code></term><listitem><para>The contents of the current line</para></listitem></varlistentry> +<varlistentry><term><code>$TM_LINE_INDEX</code></term><listitem><para>The zero-index based line number</para></listitem></varlistentry> +<varlistentry><term><code>$TM_LINE_NUMBER</code></term><listitem><para>The one-index based line number</para></listitem></varlistentry> +</variablelist> +</para> +</refsect2> + +<refsect2> +<title>Post-Processing</title> +<para> +By appending a pipe to a variable within curly braces, you can post-process +the variable. A number of built-in functions are available for processing. +For example <code>${$1|stripsuffix|functify}</code>. + +<variablelist> +<varlistentry><term><code>lower</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>upper</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>captialize</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>uncapitalize</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>html</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>camelize</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>functify</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>namespace</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>class</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>instance</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>space</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>stripsuffix</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>slash_to_dots</code></term><listitem><para></para></listitem></varlistentry> +<varlistentry><term><code>descend_path</code></term><listitem><para></para></listitem></varlistentry> +</variablelist> +</para> +</refsect2> + +</refsect1> + + +<refsect1> +<title>Default snippets</title> +<para> +The GtkSourceView team prefers to just keep a small number of snippets +distributed with the library. To add a new snippet in GtkSourceView itself, +the snippet must be very popular, and ideally a GtkSourceView-based application +must use it by default. +</para> +</refsect1> + +</refentry> |