Merge pull request #1 from invenia/cv/first-revision

Implementation of MultilineStrings package

Author: omus

.travis.yml

@@ -28,7 +28,7 @@ jobs:
           Pkg.develop(PackageSpec(path=pwd()))
           Pkg.instantiate()
           using Documenter: doctest
-          using BlockScalars
-          doctest(BlockScalars)
+          using MultilineStrings
+          doctest(MultilineStrings)
           include("docs/make.jl")'
       after_success: skip

Project.toml

@@ -1,4 +1,4 @@
-name = "BlockScalars"
+name = "MultilineStrings"
 uuid = "1e8d2bf6-9821-4900-9a2f-4d87552df2bd"
 authors = ["Invenia Technical Computing Corporation"]
 version = "0.1.0"
@@ -8,6 +8,7 @@ julia = "1"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 [targets]
-test = ["Test"]
+test = ["Test", "YAML"]

README.md

@@ -1,7 +1,56 @@
-# BlockScalars
+# MultilineStrings
 
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://invenia.github.io/BlockScalars.jl/stable)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://invenia.github.io/BlockScalars.jl/dev)
-[![Build Status](https://travis-ci.com/invenia/BlockScalars.jl.svg?branch=master)](https://travis-ci.com/invenia/BlockScalars.jl)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://invenia.github.io/MultilineStrings.jl/stable)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://invenia.github.io/MultilineStrings.jl/dev)
+[![Build Status](https://travis-ci.com/invenia/MultilineStrings.jl.svg?branch=master)](https://travis-ci.com/invenia/MultilineStrings.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+
+Tooling for manipulating multiline strings.
+
+## Features
+
+The package features a multiline string literal (`@m_str`), inspired from [YAML's block scalars](https://yaml-multiline.info/), which provide options for manipulating multiline string literals via a style and chomp indicator:
+
+- Style indicator:
+    - `f` replace newlines with spaces (folded)
+    - `l` keep newlines (literal)
+- Chomp indicator:
+    - `s` no newlines at the end (strip)
+    - `c` single newline at the end (clip)
+    - `k` keep all newlines from the end (keep)
+
+The indicators are provided after the ending quote of the string (e.g. `m"hello\nworld!"fc`).
+If no indicators are provided the default behaviour is folded/strip.
+
+## Example
+
+When writing a long string literal you may want to break the string up over multiple lines in the code, to make it easier to read, but have the string be printed as a single line.
+Specifically, when writing an long error message you may want to break up the string over multiple lines:
+
+```julia
+"An unexpected error has occurred which really shouldn't have happened but somehow did. Please check that the inputs to this function doesn't contain magic that may interfere with with the non-magical computation occurring on this device."
+```
+
+Alternatively written over multiple lines:
+
+```julia
+"An unexpected error has occurred which really shouldn't " *
+"have happened but somehow did. Please check that the inputs " *
+"to this function doesn't contain magic that may interfere with " *
+"with the non-magical computation occurring on this device."
+```
+
+Writing strings this way can be cumbersome as you need to remember to add spaces between each line.
+The MultilineStrings package provides an alternative way of writing this using the multiline string macro:
+
+```julia
+m"""
+An unexpected error has occurred which really shouldn't
+have happened but somehow did. Please check that the inputs
+to this function doesn't contain magic that may interfere with
+with the non-magical computation occurring on this device.
+"""
+```
+
+Take note that a Julia [triple-quoted string literal](https://docs.julialang.org/en/v1/manual/strings/#Triple-Quoted-String-Literals) will leave most newlines in place.

docs/Manifest.toml

@@ -3,7 +3,7 @@
 [[Base64]]
 uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 
-[[BlockScalars]]
+[[MultilineStrings]]
 path = ".."
 uuid = "1e8d2bf6-9821-4900-9a2f-4d87552df2bd"
 version = "0.1.0"

docs/Project.toml

@@ -1,3 +1,3 @@
 [deps]
-BlockScalars = "1e8d2bf6-9821-4900-9a2f-4d87552df2bd"
+MultilineStrings = "1e8d2bf6-9821-4900-9a2f-4d87552df2bd"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -1,14 +1,14 @@
-using BlockScalars
+using MultilineStrings
 using Documenter
 
 makedocs(;
-    modules=[BlockScalars],
+    modules=[MultilineStrings],
     authors="Invenia Technical Computing Corporation",
-    repo="https://github.com/invenia/BlockScalars.jl/blob/{commit}{path}#L{line}",
-    sitename="BlockScalars.jl",
+    repo="https://github.com/invenia/MultilineStrings.jl/blob/{commit}{path}#L{line}",
+    sitename="MultilineStrings.jl",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://invenia.github.io/BlockScalars.jl",
+        canonical="https://invenia.github.io/MultilineStrings.jl",
         assets=String[],
     ),
     pages=[
@@ -19,5 +19,5 @@ makedocs(;
 )
 
 deploydocs(;
-    repo="github.com/invenia/BlockScalars.jl",
+    repo="github.com/invenia/MultilineStrings.jl",
 )

docs/src/index.md

@@ -1,12 +1,12 @@
 ```@meta
-CurrentModule = BlockScalars
+CurrentModule = MultilineStrings
 ```
 
-# BlockScalars
+# MultilineStrings
 
 ```@index
 ```
 
 ```@autodocs
-Modules = [BlockScalars]
+Modules = [MultilineStrings]
 ```