brick 0.17.1 → 0.17.2

raw patch · 7 files changed

+125/−49 lines, 7 filesnew-component:exe:brick-readme-demoPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• CHANGELOG.md +11/−0
• README.md +66/−42
• brick.cabal +13/−1
• docs/guide.rst +4/−5
• programs/ReadmeDemo.hs +15/−0
• src/Brick/Widgets/Center.hs +10/−1
• src/Brick/Widgets/Edit.hs +6/−0

@@ -2,6 +2,17 @@ Brick changelog --------------- +0.17.2+------++Package changes:+ * Added programs/ReadmeDemo.hs and featured its output and code in the+   README to provide an early demonstration++Library changes:+ * centerAbout now right- and bottom-pads its operand to behave+   consistently with h/vCenter+ 0.17.1 ------ 

@@ -3,24 +3,63 @@  [![Build Status](https://travis-ci.org/jtdaugherty/brick.svg?branch=master)](https://travis-ci.org/jtdaugherty/brick) -`brick` is a terminal user interface programming-library written in Haskell, in the style of-[gloss](http://hackage.haskell.org/package/gloss). This means you write-a function that describes how your user interface should look, but the-library takes care of a lot of the book-keeping that so commonly goes-into writing such programs.+`brick` is a Haskell terminal user interface programming library in the+style of [gloss](http://hackage.haskell.org/package/gloss). This means+you write a function that describes how your user interface should look,+but the library takes care of a lot of the book-keeping that so commonly+goes into writing such programs.  `brick` exposes a declarative API. Unlike most GUI toolkits which require you to write a long and tedious sequence of "create a widget,-now bind an event handler", `brick` just requires you to describe-your interface -- even the bits that are stateful -- using a set of-declarative combinators. Then you provide a function to transform your-own application state when input (or other kinds of) events arrive.+now bind an event handler", `brick` just requires you to describe your+interface using a set of declarative combinators. Then you provide a+function to transform your application state when input or other kinds+of events arrive. -Under the hood, this library builds upon [vty](http://hackage.haskell.org/package/vty).+Under the hood, this library builds upon+[vty](http://hackage.haskell.org/package/vty), so some knowledge of Vty+will be helpful in using this library.  This library deprecates [vty-ui](https://github.com/jtdaugherty/vty-ui). +Example+-------++Here's an example interface that resizes automatically when the terminal+size changes (see `programs/ReadmeDemo.hs`):++```+withBorderStyle unicode $+borderWithLabel (str "Hello!") $+(center (str "Left") <+> vBorder <+> center (str "Right"))+```++Result:++```+┌─────────Hello!─────────┐+│           │            │+│           │            │+│   Left    │   Right    │+│           │            │+│           │            │+└────────────────────────┘+```++Getting Started+---------------++TLDR:++```+$ cabal sandbox init+$ cabal install -j -f demos+$ .cabal-sandbox/bin/brick-???-demo+```++To get started, see the [first few sections of the brick+user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst).+ Feature Overview ---------------- @@ -41,30 +80,9 @@   * All widgets can be arranged in predictable layouts so you don't have    to worry about terminal resizes.- * Most widgets can be made scrollable *for free*.  * Attribute management is flexible and can be customized at runtime on    a per-widget basis. -`brick` exports-[microlens](http://hackage.haskell.org/package/microlens) and non-lens-interfaces for most things, so you can get the power of lenses if-desired or use plain Haskell if you don't. If a `brick` library function-named `thing` has a lens version, the lens version is named `thingL`.--Getting Started------------------TLDR:--```-$ cabal sandbox init-$ cabal install -j -f demos-$ .cabal-sandbox/bin/brick-???-demo-```--To get started, see the [first few sections of the brick-user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst).- Brick-Users Discussion ---------------------- @@ -89,11 +107,18 @@ `brick` is young and may be missing some essential features. There are some places were I have deliberately chosen to worry about performance later for the sake of spending more time on the design (and to wait on-performance issues to arise first). `brick` exports an extension API-that makes it possible to make your own packages and widgets. If you-use that, you'll also be helping to test whether the exported interface-is usable and complete!+performance issues to arise first). `brick` is also something of an+experimental project of mine and some aspects of the design involve+trade-offs that are not entirely settled. In addition you can expect+this library to follow a principle of fearless improvement: new versions+will make (sometimes substantial) API changes if those changes really do+make the library better. I will place more importance on getting the API+right than on maintaining backwards compatibility. +`brick` exports an extension API that makes it possible to make your own+packages and widgets. If you use that, you'll also be helping to test+whether the exported interface is usable and complete!+ Reporting bugs -------------- @@ -101,8 +126,7 @@   - Include the versions of relevant software packages: your terminal    emulator, `brick`, `ghc`, and `vty` will be the most important-   ones. Even better, the output of `cabal freeze` would probably be-   helpful in making the problem reproducible.+   ones.   - Clearly describe the behavior you expected ... @@ -118,7 +142,7 @@  - If you want to take on big things, talk to me first; let's have a    design/vision discussion before you start coding. Create a GitHub    issue and we can use that as the place to hash things out.- - If you make changes, try to make them consistent with the syntactic-   conventions I've used in the codebase.- - Please provide Haddock and/or user guide documentation for any-   changes you make.+ - Please make changes consistent with the conventions I've used in the+   codebase.+ - Please adjust or provide Haddock and/or user guide documentation+   relevant to any changes you make.

@@ -1,5 +1,5 @@ name:                brick-version:             0.17.1+version:             0.17.2 synopsis:            A declarative terminal user interface library description:   Write terminal applications painlessly with 'brick'! You write an@@ -93,6 +93,18 @@                        text-zipper >= 0.7.1,                        template-haskell,                        deepseq >= 1.3 && < 1.5++executable brick-readme-demo+  if !flag(demos)+    Buildable: False+  hs-source-dirs:      programs+  ghc-options:         -threaded -Wall -fno-warn-unused-do-bind -O3+  default-language:    Haskell2010+  default-extensions:  CPP+  main-is:             ReadmeDemo.hs+  build-depends:       base,+                       brick,+                       text  executable brick-cache-demo   if !flag(demos)

@@ -1055,9 +1055,8 @@ specified viewport; scrolling a ``Vertical`` viewport horizontally is a no-op, for example. -Using ``viewportScroll`` and the ``myViewport`` example given above, we-can write an event handler that scrolls the "Hello, world!" viewport one-column to the right:+Using ``viewportScroll`` we can write an event handler that scrolls the+``Viewport1`` viewport one column to the right:  .. code:: haskell @@ -1086,8 +1085,8 @@    let w = viewport Viewport1 Horizontal $            (visible $ str "Hello," <+> (str " world!") -This example requests that the "``myViewport``" viewport be scrolled-so that "Hello," is visible. We could extend this example with a value+This example requests that the ``Viewport1`` viewport be scrolled so+that "Hello," is visible. We could extend this example with a value in the application state indicating which word in our string should be visible and then use that to change which string gets wrapped with ``visible``; this is the basis of cursor-based scrolling.

@@ -0,0 +1,15 @@+module Main where++import Brick+import Brick.Widgets.Center+import Brick.Widgets.Border+import Brick.Widgets.Border.Style++ui :: Widget ()+ui =+    withBorderStyle unicode $+    borderWithLabel (str "Hello!") $+    (center (str "Left") <+> vBorder <+> center (str "Right"))++main :: IO ()+main = simpleMain ui

@@ -156,4 +156,13 @@           off = Location ( centerW - l^.locationColumnL                          , centerH - l^.locationRowL                          )-      render $ translateBy off p+      result <- render $ translateBy off p++      -- Pad the result so it consumes available space+      let rightPaddingAmt = max 0 $ c^.availWidthL - imageWidth (result^.imageL)+          bottomPaddingAmt = max 0 $ c^.availHeightL - imageHeight (result^.imageL)+          rightPadding = charFill (c^.attrL) ' ' rightPaddingAmt (imageHeight $ result^.imageL)+          bottomPadding = charFill (c^.attrL) ' ' (imageWidth $ result^.imageL) bottomPaddingAmt+          paddedImg = horizCat [vertCat [result^.imageL, bottomPadding], rightPadding]++      return $ result & imageL .~ paddedImg

@@ -11,6 +11,12 @@ -- The editor's 'HandleEvent' instance handles a set of basic input -- events that should suffice for most purposes; see the source for a -- complete list.+--+-- Bear in mind that the editor provided by this module is intended to+-- provide basic input support for brick applications but it is not+-- intended to be a replacement for your favorite editor such as Vim or+-- Emacs. It is also not suitable for building sophisticated editors. If+-- you want to build your own editor, I suggest starting from scratch. module Brick.Widgets.Edit   ( Editor(editContents, editorName, editDrawContents)   -- * Constructing an editor