The gtk-tagged-streams Reference Manual

Table of Contents

The gtk-tagged-streams Reference Manual

This is the gtk-tagged-streams Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:39:40 2020 GMT+0.

1 Introduction

GTK-TAGGED-STREAMS

GTK-TAGGED-STREAMS is a minimalistic library that beefs up gtk-text-buffer with an output stream. Tagged runs of text can now be printed using a simple (with-tag ..) macro and your favorite Lisp printing function.

It further lets you open tagged texts as streams, for reasonably easy input.

You may be interested in this library if

• you need something better looking than a terminal;
• you need control of type and color in your output;

This library uses (and is an extension of) the ubiquitous cl-cffi-gtk.

Demo and Screenshot

...

(ql:quickload :gtk-tagged-streams)(in-package :gts)
(demo)

Mouse-clicks will create an input stream on the run of text underneath the click, and output it to your *standard-output*.

While the demo is open, you can output to the screen using something like (format *buffer* "hello") from the REPL. Or if you want to be fancy, try (with-tag *buffer* *tHead* (format *buffer* "~&Elephant~&"))

Quickstart

To use GTK-TAGGED-STREAMS, clone it into your Lisp directory, or use Quicklisp (soon).

Use gts:tb instead of gtk-text-buffer, and gts:tv instead of gtk-text-view.

The buffer is also a caret output stream; any output will be inserted at the caret.

For tagged output, wrap your outputting code like this:

(with-tag *buffer* tag (format *buffer* "hello"))

(without-tag *buffer* tag ...)

The latter removes the specified tag from output (a very useful feature!)

The tag can be any tag valid for this buffer. You may nest these as needed.

Other streams may be opened on the buffer. They are described below.

Generalized Positions

When opening streams, the initial position can be expressed in a variety of ways. For convenience, all streams on text-buffer are opened with a :position argument that may be one of:

• an integer offset (0 is start, -1 is end);
• an iterator;
• a mark;
• a string naming a mark;
• nil for the caret position.

OUT-STREAM

The built-in caret stream of a text-buffer always outputs at the current caret position, adjusting it after output. For truly random-position output, use MARK-OUT-STREAM. It maintains its own mark for tracking output position. Any number of these may be opened of a text-buffer; don't forget to close!

(make-instance 'out-stream :buffer buffer :position genpos)

IN-STREAM

This stream is a general-purpose input stream on the buffer

(make-instance 'in-stream :buffer buffer :position genpos)

TAG-IN-STREAM

This stream allows you to treat a single tagged run of text as an input stream.

(make-instance 'tag-in-stream :buffer buffer :tag tag :position genpos)

If the tag is not active at the position indicated by the :position parameter, an :eof condition will exist at the next read.

Once open, you may use :start or :end file-position to wind to the beginning or end of the run.

TAG-ONLY-IN-STREAM

This stream allows you to treat all runs of the tag as a stream. Any text not tagged will be skipped.

(make-instance 'tag-only-in-stream :buffer buffer :tag tag :position genpos)

Normal position semantics apply to file-position.

STATUS

Early working code.

Other stream classes will probably be added as needed. Please open an issue if you have a good idea for one.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 gtk-tagged-streams

Author

StackSmith <fpgasm@apple2.x10.mx>

License

BSD Simplified (2-clause)

Description

Text I/O using streams for GTK text buffers, including tags for styling.

Dependencies

• cl-cffi-gtk
• bordeaux-threads
• trivial-gray-streams

Source

gtk-tagged-streams.asd (file)

Components

• package.lisp (file)
• gtk-fixes/gtk.text-iter.lisp (file)
• utils.lisp (file)
• gtk-assets/generalized-position.lisp (file)
• gtk-assets/abstract-streams.lisp (file)
• gtk-assets/tb-output-mixin.lisp (file)
• gtk-assets/tb.lisp (file)
• gtk-assets/tag.lisp (file)
• gtk-assets/tag-in-stream.lisp (file)
• gtk-assets/tag-only-in-stream.lisp (file)
• gtk-assets/mark-out-stream.lisp (file)
• demo.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 gtk-tagged-streams.asd

Location

gtk-tagged-streams.asd

Systems

gtk-tagged-streams (system)

3.1.2 gtk-tagged-streams/package.lisp

Parent

gtk-tagged-streams (system)

Location

package.lisp

Packages

gtk-tagged-streams

3.1.3 gtk-tagged-streams/gtk-fixes/gtk.text-iter.lisp

Dependency

package.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-fixes/gtk.text-iter.lisp

3.1.4 gtk-tagged-streams/utils.lisp

Dependency

gtk-fixes/gtk.text-iter.lisp (file)

Parent

gtk-tagged-streams (system)

Location

utils.lisp

Internal Definitions

• abbrev-symbols (function)
• fsv (macro)
• gsafe (macro)
• hsv (function)
• idly (macro)
• increment-within-range (macro)
• make-synonym (function)
• mvb (macro)
• mvs (macro)
• prognil (macro)
• progt (macro)
• string-ell-out (function)

3.1.5 gtk-tagged-streams/gtk-assets/generalized-position.lisp

Dependency

utils.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/generalized-position.lisp

Internal Definitions

new-iter-at-position (function)

3.1.6 gtk-tagged-streams/gtk-assets/abstract-streams.lisp

Dependency

gtk-assets/generalized-position.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/abstract-streams.lisp

Internal Definitions

• bs-close (function)
• bs-init (function)
• bs-position (function)
• bs-set-position (function)
• buffer (method)
• (setf buffer) (method)
• buffer-stream (class)
• buffer-tag-stream (class)
• iter (method)
• (setf iter) (method)
• mark (method)
• (setf mark) (method)
• tag (method)
• (setf tag) (method)

3.1.7 gtk-tagged-streams/gtk-assets/tb-output-mixin.lisp

Dependency

gtk-assets/abstract-streams.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/tb-output-mixin.lisp

Internal Definitions

• charbuf (method)
• (setf charbuf) (method)
• tb-output-mixin (class)

3.1.8 gtk-tagged-streams/gtk-assets/tb.lisp

Dependency

gtk-assets/tb-output-mixin.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/tb.lisp

Exported Definitions

• tb (class)
• with-tag (macro)

Internal Definitions

• iter0 (method)
• (setf iter0) (method)
• iter1 (method)
• (setf iter1) (method)
• mcursor (method)
• (setf mcursor) (method)
• tb-apply-tag (function)
• tb-cursor-backwards (function)
• tb-cursor-iter (function)
• tb-iters-to-offsets (function)
• tb-remove-tag (function)
• without-tag (macro)

3.1.9 gtk-tagged-streams/gtk-assets/tag.lisp

Dependency

gtk-assets/tb.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/tag.lisp

Internal Definitions

tag (class)

3.1.10 gtk-tagged-streams/gtk-assets/tag-in-stream.lisp

Dependency

gtk-assets/tag.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/tag-in-stream.lisp

Internal Definitions

tag-in-stream (class)

3.1.11 gtk-tagged-streams/gtk-assets/tag-only-in-stream.lisp

Dependency

gtk-assets/tag-in-stream.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/tag-only-in-stream.lisp

Internal Definitions

• tag-only-in-stream (class)
• tois-prep-iter (function)

3.1.12 gtk-tagged-streams/gtk-assets/mark-out-stream.lisp

Dependency

gtk-assets/tag-only-in-stream.lisp (file)

Parent

gtk-tagged-streams (system)

Location

gtk-assets/mark-out-stream.lisp

Internal Definitions

• charbuf (method)
• (setf charbuf) (method)
• mark-out-stream (class)

3.1.13 gtk-tagged-streams/demo.lisp

Dependency

gtk-assets/mark-out-stream.lisp (file)

Parent

gtk-tagged-streams (system)

Location

demo.lisp

Exported Definitions

demo (function)

Internal Definitions

• *buffer* (special variable)
• *thead* (special variable)
• *tlink* (special variable)
• *view* (special variable)
• populate (function)

4 Packages

Packages are listed by definition order.

4.1 gtk-tagged-streams

Source

package.lisp (file)

Nickname

gts

Use List

• common-lisp
• cffi
• cairo
• pango
• gio
• glib
• gobject
• gdk-pixbuf
• gdk
• gtk

Exported Definitions

• demo (function)
• tb (class)
• with-tag (macro)

Internal Definitions

• *buffer* (special variable)
• *thead* (special variable)
• *tlink* (special variable)
• *view* (special variable)
• abbrev-symbols (function)
• bs-close (function)
• bs-init (function)
• bs-position (function)
• bs-set-position (function)
• buffer (generic function)
• buffer (method)
• (setf buffer) (method)
• (setf buffer) (generic function)
• buffer-stream (class)
• buffer-tag-stream (class)
• charbuf (generic function)
• charbuf (method)
• (setf charbuf) (method)
• charbuf (method)
• (setf charbuf) (method)
• (setf charbuf) (generic function)
• fsv (macro)
• gsafe (macro)
• hsv (function)
• idly (macro)
• increment-within-range (macro)
• iter (generic function)
• iter (method)
• (setf iter) (method)
• (setf iter) (generic function)
• iter0 (generic function)
• iter0 (method)
• (setf iter0) (method)
• (setf iter0) (generic function)
• iter1 (generic function)
• iter1 (method)
• (setf iter1) (method)
• (setf iter1) (generic function)
• make-synonym (function)
• mark (generic function)
• mark (method)
• (setf mark) (method)
• (setf mark) (generic function)
• mark-out-stream (class)
• mcursor (generic function)
• mcursor (method)
• (setf mcursor) (method)
• (setf mcursor) (generic function)
• mvb (macro)
• mvs (macro)
• new-iter-at-position (function)
• populate (function)
• prognil (macro)
• progt (macro)
• string-ell-out (function)
• tag (generic function)
• tag (method)
• (setf tag) (method)
• (setf tag) (generic function)
• tag (class)
• tag-in-stream (class)
• tag-only-in-stream (class)
• tb-apply-tag (function)
• tb-cursor-backwards (function)
• tb-cursor-iter (function)
• tb-iters-to-offsets (function)
• tb-output-mixin (class)
• tb-remove-tag (function)
• tois-prep-iter (function)
• without-tag (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: with-tag TB TAG &rest BODY

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

5.1.2 Functions

Function: demo ()

Package

gtk-tagged-streams

Source

demo.lisp (file)

5.1.3 Classes

Class: tb ()

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

Direct superclasses

• tb-output-mixin (class)
• gtk-text-buffer (class)

Direct methods

• initialize-instance (method)
• mcursor (method)
• mcursor (method)
• iter1 (method)
• iter1 (method)
• iter0 (method)
• iter0 (method)

Direct slots

Slot: iter0

Readers

iter0 (generic function)

Writers

(setf iter0) (generic function)

Slot: iter1

Readers

iter1 (generic function)

Writers

(setf iter1) (generic function)

Slot: mcursor

Readers

mcursor (generic function)

Writers

(setf mcursor) (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *buffer*

Package

gtk-tagged-streams

Source

demo.lisp (file)

Special Variable: *thead*

Package

gtk-tagged-streams

Source

demo.lisp (file)

Special Variable: *tlink*

Package

gtk-tagged-streams

Source

demo.lisp (file)

Special Variable: *view*

Package

gtk-tagged-streams

Source

demo.lisp (file)

5.2.2 Macros

Macro: fsv &rest REST

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: gsafe &rest BODY

execute body safely inside gtk main thread

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: idly &rest REST

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: increment-within-range ITEM &key BY MIN MAX

increment (or decrement if ’by’ is negative) item if the result is within range (inclusive min). Return result or nil if no increment took place.

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: mvb &body REST

synonym for multiple-value-bind

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: mvs &rest REST

synonym for multiple-value-setq

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: prognil &body BODY

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: progt &body BODY

Package

gtk-tagged-streams

Source

utils.lisp (file)

Macro: without-tag TB TAG &rest BODY

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

5.2.3 Functions

Function: abbrev-symbols PACKAGE OLD-PREFIX NEW-PREFIX

Create synonyms starting with ’new-prefix’ for function symbols starting with ’old-prefix’ in :package. Remember to capitalize

Package

gtk-tagged-streams

Source

utils.lisp (file)

Function: bs-close STREAM

Package

gtk-tagged-streams

Source

gtk-assets/abstract-streams.lisp (file)

Function: bs-init STREAM POSITION

Package

gtk-tagged-streams

Source

gtk-assets/abstract-streams.lisp (file)

Function: bs-position STREAM

Package

gtk-tagged-streams

Source

gtk-assets/abstract-streams.lisp (file)

Function: bs-set-position STREAM NEWVAL

Package

gtk-tagged-streams

Source

gtk-assets/abstract-streams.lisp (file)

Function: hsv H S V

convert hsv color to a gdk-rgba

Package

gtk-tagged-streams

Source

utils.lisp (file)

Function: make-synonym OLD NEWNAME &key PACKAGE OVERWRITE

make a synonym for old symbol using newname, optionally in a different package. Functions only.

Package

gtk-tagged-streams

Source

utils.lisp (file)

Function: new-iter-at-position BUFFER POSITION

create an iter at generalized position

Package

gtk-tagged-streams

Source

gtk-assets/generalized-position.lisp (file)

Function: populate BUFFER THEAD TBODY TLINK TBOLDLINK

Package

gtk-tagged-streams

Source

demo.lisp (file)

Function: string-ell-out STRING LIMIT STREAM

stream out a string; if it is longer than limit, ellipsize.

Package

gtk-tagged-streams

Source

utils.lisp (file)

Function: tb-apply-tag TB TAG START END

Apply a tag at start/end offsets; return T

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

Function: tb-cursor-backwards TB &key COUNT

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

Function: tb-cursor-iter TB

set iter0 to cursor

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

Function: tb-iters-to-offsets TB START END

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

Function: tb-remove-tag TB TAG START END

Remove a tag at start/end offsets; return T

Package

gtk-tagged-streams

Source

gtk-assets/tb.lisp (file)

Function: tois-prep-iter STREAM

if the iter is not in a tag, advance; return nil if eof

Package

gtk-tagged-streams

Source

gtk-assets/tag-only-in-stream.lisp (file)

5.2.4 Generic functions

Generic Function: buffer OBJECT

Generic Function: (setf buffer) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: buffer (BUFFER-STREAM buffer-stream)

automatically generated reader method

Source

gtk-assets/abstract-streams.lisp (file)

Method: (setf buffer) NEW-VALUE (BUFFER-STREAM buffer-stream)

automatically generated writer method

Source

gtk-assets/abstract-streams.lisp (file)

Generic Function: charbuf OBJECT

Generic Function: (setf charbuf) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: charbuf (MARK-OUT-STREAM mark-out-stream)

automatically generated reader method

Source

gtk-assets/mark-out-stream.lisp (file)

Method: (setf charbuf) NEW-VALUE (MARK-OUT-STREAM mark-out-stream)

automatically generated writer method

Source

gtk-assets/mark-out-stream.lisp (file)

Method: charbuf (TB-OUTPUT-MIXIN tb-output-mixin)

automatically generated reader method

Source

gtk-assets/tb-output-mixin.lisp (file)

Method: (setf charbuf) NEW-VALUE (TB-OUTPUT-MIXIN tb-output-mixin)

automatically generated writer method

Source

gtk-assets/tb-output-mixin.lisp (file)

Generic Function: iter OBJECT

Generic Function: (setf iter) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: iter (BUFFER-STREAM buffer-stream)

automatically generated reader method

Source

gtk-assets/abstract-streams.lisp (file)

Method: (setf iter) NEW-VALUE (BUFFER-STREAM buffer-stream)

automatically generated writer method

Source

gtk-assets/abstract-streams.lisp (file)

Generic Function: iter0 OBJECT

Generic Function: (setf iter0) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: iter0 (TB tb)

automatically generated reader method

Source

gtk-assets/tb.lisp (file)

Method: (setf iter0) NEW-VALUE (TB tb)

automatically generated writer method

Source

gtk-assets/tb.lisp (file)

Generic Function: iter1 OBJECT

Generic Function: (setf iter1) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: iter1 (TB tb)

automatically generated reader method

Source

gtk-assets/tb.lisp (file)

Method: (setf iter1) NEW-VALUE (TB tb)

automatically generated writer method

Source

gtk-assets/tb.lisp (file)

Generic Function: mark OBJECT

Generic Function: (setf mark) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: mark (BUFFER-STREAM buffer-stream)

automatically generated reader method

Source

gtk-assets/abstract-streams.lisp (file)

Method: (setf mark) NEW-VALUE (BUFFER-STREAM buffer-stream)

automatically generated writer method

Source

gtk-assets/abstract-streams.lisp (file)

Generic Function: mcursor OBJECT

Generic Function: (setf mcursor) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: mcursor (TB tb)

automatically generated reader method

Source

gtk-assets/tb.lisp (file)

Method: (setf mcursor) NEW-VALUE (TB tb)

automatically generated writer method

Source

gtk-assets/tb.lisp (file)

Generic Function: tag OBJECT

Generic Function: (setf tag) NEW-VALUE OBJECT

Package

gtk-tagged-streams

Methods

Method: tag (BUFFER-TAG-STREAM buffer-tag-stream)

automatically generated reader method

Source

gtk-assets/abstract-streams.lisp (file)

Method: (setf tag) NEW-VALUE (BUFFER-TAG-STREAM buffer-tag-stream)

automatically generated writer method

Source

gtk-assets/abstract-streams.lisp (file)

5.2.5 Classes

Class: buffer-stream ()

Package

gtk-tagged-streams

Source

gtk-assets/abstract-streams.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• buffer-tag-stream (class)
• mark-out-stream (class)

Direct methods

• stream-file-position (method)
• stream-file-position (method)
• initialize-instance (method)
• close (method)
• mark (method)
• mark (method)
• iter (method)
• iter (method)
• buffer (method)
• buffer (method)

Direct slots

Slot: buffer

Initargs

:buffer

Readers

buffer (generic function)

Writers

(setf buffer) (generic function)

Slot: iter

Readers

iter (generic function)

Writers

(setf iter) (generic function)

Slot: mark

Readers

mark (generic function)

Writers

(setf mark) (generic function)

Class: buffer-tag-stream ()

Package

gtk-tagged-streams

Source

gtk-assets/abstract-streams.lisp (file)

Direct superclasses

buffer-stream (class)

Direct subclasses

• tag-in-stream (class)
• tag-only-in-stream (class)

Direct methods

• initialize-instance (method)
• tag (method)
• tag (method)

Direct slots

Slot: tag

Initargs

:tag

Readers

tag (generic function)

Writers

(setf tag) (generic function)

Class: mark-out-stream ()

Package

gtk-tagged-streams

Source

gtk-assets/mark-out-stream.lisp (file)

Direct superclasses

• fundamental-character-output-stream (class)
• buffer-stream (class)

Direct methods

• stream-line-column (method)
• stream-start-line-p (method)
• stream-write-string (method)
• stream-write-char (method)
• charbuf (method)
• charbuf (method)

Direct slots

Slot: charbuf

Initform

"a"

Readers

charbuf (generic function)

Writers

(setf charbuf) (generic function)

Class: tag ()

Package

gtk-tagged-streams

Source

gtk-assets/tag.lisp (file)

Direct superclasses

gtk-text-tag (class)

Direct methods

initialize-instance (method)

Class: tag-in-stream ()

Package

gtk-tagged-streams

Source

gtk-assets/tag-in-stream.lisp (file)

Direct superclasses

• fundamental-character-input-stream (class)
• buffer-tag-stream (class)

Direct methods

• stream-file-position (method)
• stream-read-char (method)

Class: tag-only-in-stream ()

Package

gtk-tagged-streams

Source

gtk-assets/tag-only-in-stream.lisp (file)

Direct superclasses

• fundamental-character-input-stream (class)
• buffer-tag-stream (class)

Direct methods

• stream-unread-char (method)
• stream-peek-char (method)
• stream-read-char (method)

Class: tb-output-mixin ()

Package

gtk-tagged-streams

Source

gtk-assets/tb-output-mixin.lisp (file)

Direct superclasses

fundamental-character-output-stream (class)

Direct subclasses

tb (class)

Direct methods

• stream-file-position (method)
• stream-file-position (method)
• stream-line-column (method)
• stream-start-line-p (method)
• stream-write-string (method)
• stream-write-char (method)
• charbuf (method)
• charbuf (method)

Direct slots

Slot: charbuf

Initform

" "

Readers

charbuf (generic function)

Writers

(setf charbuf) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types