From 6130eb4d84ea408695f9f7fa8c5c18de537fa9c6 Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Sun, 27 Mar 2022 21:32:15 +0200 Subject: [PATCH] Generate documentation --- latest/cuerdas.core.html | 153 +++++++++++++++++++-------------------- latest/index.html | 2 +- latest/user-guide.html | 80 ++++++++++---------- 3 files changed, 116 insertions(+), 119 deletions(-) diff --git a/latest/cuerdas.core.html b/latest/cuerdas.core.html index 3a8be40..d0e7a94 100644 --- a/latest/cuerdas.core.html +++ b/latest/cuerdas.core.html @@ -1,91 +1,86 @@ -cuerdas.core documentation

Project

Topics

Namespaces

Public Vars

cuerdas.core

<<

macro

deprecated

(<< & strings)

A backward compatibility alias for istr macro.

-
view source

<<-

(<<- s)(<<- r s)

Unindent multiline text. Uses either a supplied regex or the shortest beginning-of-line to non-whitespace distance

-
view source

alnum?

(alnum? s)

Checks if a string contains only alphanumeric characters.

-
view source

alpha?

(alpha? s)

Checks if a string contains only alpha characters.

-
view source

blank?

(blank? s)

Checks if a string is empty or contains only whitespace.

-
view source

camel

(camel s)

Output will be: lowerUpperUpperNoSpaces accepts strings and keywords

-
view source

capital

(capital s)

Uppercases the first character of a string

-
view source

chars

(chars s)

Split a string in a seq of chars.

-
view source

clean

(clean s)

Trim and replace multiple spaces with a single space.

-
view source

collapse-whitespace

(collapse-whitespace s)

Converts all adjacent whitespace characters to a single space.

-
view source

css-selector

(css-selector s)

Output will be either: (js-selector “LeadingDash”) ;; => -leading-dash (js-selector “noLeadingDash”) ;; => no-leading-dash

+cuerdas.core documentation

Project

Topics

Namespaces

Public Vars

cuerdas.core

<<

macro

deprecated

(<< & strings)

A backward compatibility alias for istr macro.

+
view source

<<-

(<<- s)(<<- r s)

Unindent multiline text. Uses either a supplied regex or the shortest beginning-of-line to non-whitespace distance

+
view source

alnum?

(alnum? s)

Checks if a string contains only alphanumeric characters.

+
view source

alpha?

(alpha? s)

Checks if a string contains only alpha characters.

+
view source

blank?

(blank? s)

Checks if a string is empty or contains only whitespace.

+
view source

camel

(camel s)

Output will be: lowerUpperUpperNoSpaces accepts strings and keywords

+
view source

capital

(capital s)

Uppercases the first character of a string

+
view source

chars

(chars s)

Split a string in a seq of chars.

+
view source

clean

(clean s)

Trim and replace multiple spaces with a single space.

+
view source

collapse-whitespace

(collapse-whitespace s)

Converts all adjacent whitespace characters to a single space.

+
view source

concat

macro

(concat & params)

A macro variant of the clojure.core/str function that performs considerbaly faster string concatenation operation on CLJS (on JVM/CLJ it only applies basic simplification and then relies on the clojure.core/str).

+
view source

concat

macro

(concat & params)

A macro variant of the clojure.core/str function that performs considerbaly faster string concatenation operation on CLJS (on JVM/CLJ it only applies basic simplification and then relies on the clojure.core/str).

+
view source

css-selector

(css-selector s)

Output will be either: (js-selector “LeadingDash”) ;; => -leading-dash (js-selector “noLeadingDash”) ;; => no-leading-dash

accepts keywords and strings, with any standard delimiter

-
view source

digits?

(digits? s)

Checks if a string contains only digit characters.

-
view source

empty-or-nil?

(empty-or-nil? s)

Convenient helper for check emptines or if value is nil.

-
view source

empty?

(empty? s)

Checks if a string is empty.

-
view source

ends-with?

(ends-with? s suffix)

Check if the string ends with suffix.

-
view source

escape-html

(escape-html s)
view source

fmt

A shorter alias to format function.

-
view source

format

(format s & more)

Simple string interpolation.

-
view source

human

(human s)

Output will be: lower cased and space separated accepts strings and keywords

-
view source

includes?

(includes? s subs)

Determines whether a string contains a substring.

-
view source

index-of

(index-of s val)(index-of s val from)
view source

istr

macro

(istr & strings)

Accepts one or more strings; emits a str invocation that concatenates the string data and evaluated expressions contained within that argument. Evaluation is controlled using ~{} and ~() forms. The former is used for simple value replacement using clojure.core/str; the latter can be used to embed the results of arbitrary function invocation into the produced string.

+
view source

digits?

(digits? s)

Checks if a string contains only digit characters.

+
view source

empty-or-nil?

(empty-or-nil? s)

Convenient helper for check emptines or if value is nil.

+
view source

empty?

(empty? s)

Checks if a string is empty.

+
view source

ends-with?

(ends-with? s suffix)

Check if the string ends with suffix.

+
view source

escape-html

(escape-html s)
view source

ffmt

macro

(ffmt s & params)

Alternative (to istr) string formating macro, that performs simple string formating on the compile time (this means that the string should be known at compile time). Internally it uses the fast string concatenation mechanism implemented in the concat macro.

+

If you don’t need the peculiarities of the istr macro, this macro should be prefered.

+

It works with two basic forms: sequencial and indexed. Let seen an example:

+

(str/ffmt “url(%)” my-url) ; sequential (str/ffmt “url(%1)” my-url) ; indexed

+
view source

fmt

A shorter alias to format function.

+
view source

format

(format s & more)

Simple string interpolation.

+
view source

human

(human s)

Output will be: lower cased and space separated accepts strings and keywords

+
view source

includes?

(includes? s subs)

Determines whether a string contains a substring.

+
view source

index-of

(index-of s val)(index-of s val from)
view source

istr

macro

(istr & strings)

A string formating macro that works LIKE ES6 template literals but using clojure construcs and symbols for interpolation delimiters.

+

It accepts one or more strings; emits a concat invocation that concatenates the string data and evaluated expressions contained within that argument.

+

Evaluation is controlled using ~{} and ~() forms. The former is used for simple value replacement using clojure.core/str; the latter can be used to embed the results of arbitrary function invocation into the produced string.

Examples:

-
user=> (def v 30.5)
-#'user/v
-user=> (istr "This trial required ~{v}ml of solution.")
-"This trial required 30.5ml of solution."
-user=> (istr "There are ~(int v) days in November.")
-"There are 30 days in November."
-user=> (def m {:a [1 2 3]})
-#'user/m
-user=> (istr "The total for your order is $~(->> m :a (apply +)).")
-"The total for your order is $6."
-user=> (<< "Just split a long interpolated string up into ~(-> m :a (get 0)), "
-         "~(-> m :a (get 1)), or even ~(-> m :a (get 2)) separate strings "
-         "if you don't want a << expression to end up being e.g. ~(* 4 (int v)) "
-         "columns wide.")
-"Just split a long interpolated string up into 1, 2, or even 3 separate strings if you don't want a << expression to end up being e.g. 120 columns wide."
-
+

user=> (def v 30.5) user=> (istr “This trial required ~{v}ml of solution.”) “This trial required 30.5ml of solution.” user=> (istr “There are ~(int v) days in November.”) “There are 30 days in November.”

+

user=> (def m {:a 1 2 3}) user=> (istr “The total for your order is $~(->> m :a (apply +)).”) “The total for your order is $6.”

+

user=> (istr "Just split a long interpolated string up into ~(-> m :a (get 0)), " "~(-> m :a (get 1)), or even ~(-> m :a (get 2)) separate strings " "if you don’t want a << expression to end up being e.g. ~(* 4 (int v)) " “columns wide.”) “Just split a long interpolated string up into 1, 2, or even 3 separate strings if you don’t want a << expression to end up being e.g. 120 columns wide.”

Note that quotes surrounding string literals within ~() forms must be escaped.

-
view source

join

(join coll)(join separator coll)

Joins strings together with given separator.

-
view source

js-selector

(js-selector s)

Output will be either: (js-selector “-pascal-case-me”) ;; => PascalCaseMe (js-selector “camel-case-me”) ;; => camelCaseMe

+
view source

join

(join coll)(join separator coll)

Joins strings together with given separator.

+
view source

js-selector

(js-selector s)

Output will be either: (js-selector “-pascal-case-me”) ;; => PascalCaseMe (js-selector “camel-case-me”) ;; => camelCaseMe

accepts keywords and strings, with any standard delimiter

-
view source

kebab

(kebab s)

Output will be: lower-cased-and-separated-with-dashes accepts strings and keywords

-
view source

keyword

(keyword k)(keyword n k)

Safer version of clojure keyword, accepting a symbol for the namespace and kebab-casing the key

-
view source

last-index-of

(last-index-of s val)(last-index-of s val from)
view source

letters?

(letters? s)

Checks if string contains only letters. This function will use all the unicode range.

-
view source

lines

(lines s)

Return a list of the lines in the string.

-
view source

lower

(lower s)

Converts string to all lower-case.

+
view source

kebab

(kebab s)

Output will be: lower-cased-and-separated-with-dashes accepts strings and keywords

+
view source

keyword

(keyword k)(keyword n k)

Safer version of clojure keyword, accepting a symbol for the namespace and kebab-casing the key

+
view source

last-index-of

(last-index-of s val)(last-index-of s val from)
view source

letters?

(letters? s)

Checks if string contains only letters. This function will use all the unicode range.

+
view source

lines

(lines s)

Return a list of the lines in the string.

+
view source

lower

(lower s)

Converts string to all lower-case.

This function works in strictly locale independent way, if you want a localized version, just use locale-lower

-
view source

ltrim

(ltrim s)(ltrim s chs)

Removes whitespace or specified characters from left side of string.

-
view source

numeric?

(numeric? s)

Check if a string contains only numeric values.

-
view source

one-of?

(one-of? coll s)

Returns true if s can be found in coll.

-
view source

pad

(pad s)(pad s {:keys [length padding type], :or {length 0, padding " ", type :left}})

Pads the str with characters until the total string length is equal to the passed length parameter. By default, pads on the left with the space char.

-
view source

pascal

(pascal s)

Output will be: CapitalizedAndTouchingTheNext accepts strings and keywords

-
view source

phrase

(phrase s)

Output will be: Space separated with the first letter capitalized. accepts strings and keywords

-
view source

prune

(prune s num)(prune s num subs)

Truncates a string to a certain length and adds ‘…’ if necessary.

-
view source

quote

(quote s)(quote s qchar)

Quotes a string.

-
view source

repeat

(repeat s)(repeat s n)

Repeats string n times.

-
view source

replace

(replace s match replacement)

Replaces all instance of match with replacement in s.

+
view source

ltrim

(ltrim s)(ltrim s chs)

Removes whitespace or specified characters from left side of string.

+
view source

numeric?

(numeric? s)

Check if a string contains only numeric values.

+
view source

one-of?

(one-of? coll s)

Returns true if s can be found in coll.

+
view source

pad

(pad s)(pad s {:keys [length padding type], :or {length 0, padding " ", type :left}})

Pads the str with characters until the total string length is equal to the passed length parameter. By default, pads on the left with the space char.

+
view source

pascal

(pascal s)

Output will be: CapitalizedAndTouchingTheNext accepts strings and keywords

+
view source

phrase

(phrase s)

Output will be: Space separated with the first letter capitalized. accepts strings and keywords

+
view source

prune

(prune s num)(prune s num subs)

Truncates a string to a certain length and adds ‘…’ if necessary.

+
view source

quote

(quote s)(quote s qchar)

Quotes a string.

+
view source

repeat

(repeat s)(repeat s n)

Repeats string n times.

+
view source

replace

(replace s match replacement)

Replaces all instance of match with replacement in s.

The replacement is literal (i.e. none of its characters are treated specially) for all cases above except pattern / string.

In match is pattern instance, replacement can contain $1, $2, etc. will be substituted with string that matcher the corresponding parenthesized group in pattern.

If you wish your replacement string to be used literary, use (cuerdas.regexp/escape replacement).

Example: (replace “Almost Pig Latin” #“\b(\w)(\w+)\b” “$2$1ay”) ;; => “lmostAay igPay atinLay”

-
view source

replace-first

(replace-first s match replacement)

Replaces first instance of match with replacement in s.

-
view source

reverse

(reverse s)

Return string reversed.

-
view source

rtrim

(rtrim s)(rtrim s chs)

Removes whitespace or specified characters from right side of string.

-
view source

slice

(slice s begin)(slice s begin end)

Extracts a section of a string and returns a new string.

-
view source

slug

(slug s)

Transform text into a URL slug.

-
view source

snake

(snake s)

Output will be: lower_cased_and_underscore_separated accepts strings and keywords

-
view source

split

(split s)(split s sep)(split s sep num)

Splits a string on a separator a limited number of times. The separator can be a string, character or Pattern (clj) / RegExp (cljs) instance.

-
view source

starts-with?

(starts-with? s prefix)

Check if the string starts with prefix.

-
view source

strip-newlines

(strip-newlines s)

Takes a string and replaces newlines with a space. Multiple lines are replaced with a single space.

-
view source

strip-prefix

(strip-prefix s prefix)

Strip prefix in more efficient way.

-
view source

strip-suffix

(strip-suffix s suffix)

Strip suffix in more efficient way.

-
view source

strip-tags

(strip-tags s)(strip-tags s tags)(strip-tags s tags mapping)

Remove html tags from string.

-
view source

stylize

(stylize s every-fn join-with)(stylize s first-fn rest-fn join-with)
view source

substr-between

(substr-between s prefix suffix)

Find string that is nested in between two strings. Return first match

-
view source

surround

(surround s wrap)

Surround a string with another string or character.

-
view source

title

(title s)

Output will be: Each Word Capitalized And Separated With Spaces accepts strings and keywords

-
view source

to-bool

(to-bool s)

Returns true for 1/on/true/yes string values (case-insensitive), false otherwise.

-
view source

trim

(trim s)(trim s chs)

Removes whitespace or specified characters from both ends of string.

-
view source

unescape-html

(unescape-html s)

Converts entity characters to HTML equivalents.

-
view source

unlines

(unlines s)

Returns a new string joining a list of strings with a newline char (\n).

-
view source

unquote

(unquote s)(unquote s qchar)

Unquote a string.

-
view source

unsurround

(unsurround s surrounding)

Unsurround a string surrounded by another string or character.

-
view source

upper

(upper s)

Converts string to all upper-case.

+
view source

replace-first

(replace-first s match replacement)

Replaces first instance of match with replacement in s.

+
view source

reverse

(reverse s)

Return string reversed.

+
view source

rtrim

(rtrim s)(rtrim s chs)

Removes whitespace or specified characters from right side of string.

+
view source

slice

(slice s begin)(slice s begin end)

Extracts a section of a string and returns a new string.

+
view source

slug

(slug s)

Transform text into a URL slug.

+
view source

snake

(snake s)

Output will be: lower_cased_and_underscore_separated accepts strings and keywords

+
view source

split

(split s)(split s sep)(split s sep num)

Splits a string on a separator a limited number of times. The separator can be a string, character or Pattern (clj) / RegExp (cljs) instance.

+
view source

starts-with?

(starts-with? s prefix)

Check if the string starts with prefix.

+
view source

strip-newlines

(strip-newlines s)

Takes a string and replaces newlines with a space. Multiple lines are replaced with a single space.

+
view source

strip-prefix

(strip-prefix s prefix)

Strip prefix in more efficient way.

+
view source

strip-suffix

(strip-suffix s suffix)

Strip suffix in more efficient way.

+
view source

strip-tags

(strip-tags s)(strip-tags s tags)(strip-tags s tags mapping)

Remove html tags from string.

+
view source

stylize

(stylize s every-fn join-with)(stylize s first-fn rest-fn join-with)
view source

substr-between

(substr-between s prefix suffix)

Find string that is nested in between two strings. Return first match

+
view source

surround

(surround s wrap)

Surround a string with another string or character.

+
view source

title

(title s)

Output will be: Each Word Capitalized And Separated With Spaces accepts strings and keywords

+
view source

to-bool

(to-bool s)

Returns true for 1/on/true/yes string values (case-insensitive), false otherwise.

+
view source

trim

(trim s)(trim s chs)

Removes whitespace or specified characters from both ends of string.

+
view source

unescape-html

(unescape-html s)

Converts entity characters to HTML equivalents.

+
view source

unlines

(unlines s)

Returns a new string joining a list of strings with a newline char (\n).

+
view source

unquote

(unquote s)(unquote s qchar)

Unquote a string.

+
view source

unsurround

(unsurround s surrounding)

Unsurround a string surrounded by another string or character.

+
view source

upper

(upper s)

Converts string to all upper-case.

This function works in strictly locale independent way, if you want a localized version, just use locale-upper

-
view source

uslug

(uslug s)

Unicode friendly version of slug function.

-
view source

word?

(word? s)

Checks if a string contains only the word characters. This function will use all the unicode range.

-
view source

words

(words s)(words s re)

Returns a vector of the words in the string.

-
view source
\ No newline at end of file +
view source

uslug

(uslug s)

Unicode friendly version of slug function.

+
view source

word?

(word? s)

Checks if a string contains only the word characters. This function will use all the unicode range.

+
view source

words

(words s)(words s re)

Returns a vector of the words in the string.

+
view source
\ No newline at end of file diff --git a/latest/index.html b/latest/index.html index b820392..8d58a9e 100644 --- a/latest/index.html +++ b/latest/index.html @@ -1,4 +1,4 @@ -funcool/cuerdas

Project

Topics

Namespaces

funcool/cuerdas

Topics

Namespaces

cuerdas.core

Public variables and functions:

cuerdas.regexp

A regexp helpers and enhancements (mostly for cljs).

+funcool/cuerdas

Project

Topics

Namespaces

funcool/cuerdas

Topics

Namespaces

cuerdas.core

Public variables and functions:

cuerdas.regexp

A regexp helpers and enhancements (mostly for cljs).

Public variables and functions:

\ No newline at end of file diff --git a/latest/user-guide.html b/latest/user-guide.html index 73c7ed7..ee53d68 100644 --- a/latest/user-guide.html +++ b/latest/user-guide.html @@ -17,7 +17,7 @@

Introduction

Install

Add the following dependency to your project.clj file:

-
funcool/cuerdas {:mvn/version "RELEASE"}
+
funcool/cuerdas {:mvn/version "2022.03.27-397"}
 

 
Quick start

 
(ns my.namespace
@@ -55,8 +55,26 @@ 
<<-

 
 another line
 

+
concat

+
This is a macro variant of clojure.core/str function that performs string concatenation. It is considerably faster on CLJS and slightly faster on JVM.

+
On CLJS, it uses the + native operator to perform the concatenation that is more optimized than the [].join(...) for the vast majority of cases. On the JVM it only simplifies contiguos strings that are know to be string instances at compile time.

+
(str/concat "foo" 1 "bar")
+;; => "foo1bar"
+

+
There some benchmark result with huge number of items to concatenate:

+
;; => benchmarking: cljs.core/str
+;; --> WARM:  100000
+;; --> BENCH: 500000
+;; --> TOTAL: 197.82ms
+;; --> MEAN:  395.64ns
+;; => benchmarking: cuerdas.core/concat
+;; --> WARM:  100000
+;; --> BENCH: 500000
+;; --> TOTAL: 20.31ms
+;; --> MEAN:  40.63ns
+

 
istr

-
String interpolation macro. Enables easy string formating allowing symbol substitutions and simple expression evaluation. At the moment not compatible with self-host ClojureScript.

+
String interpolation macro. Enables easy string formating allowing symbol substitutions and simple expression evaluation. Very similar to the ES6 template strings. At the moment not compatible with self-host ClojureScript.

 
(def value 30)
 
 (str/istr "value = ~{value}")
@@ -70,6 +88,21 @@ 
istr

           "is ~{value}")
 ;; => "the value is 30"
 

+
This macro ends using the fast string concatenation thanks to concat macro.

+
ffmt

+
Another string formating, simplier alternative to the istr macro.

+
It works with two basic forms: sequencial and indexed. Let seen an example:

+
(str/ffmt \"url(%)\" my-url) ; sequential
+(str/ffmt \"url(%1)\" my-url) ; indexed
+

+
If you need the % character, just duplicate it:

+
(str/fmt "%1%%" 1)
+;; => "1%"
+
+(str/fmt "%%%" 1)
+;; => "%1"
+

+
This macro ends using the fast string concatenation thanks to concat macro.

 
alnum?

 
Checks if a string contains only alphanumeric characters.

 
(str/alnum? nil)
@@ -233,7 +266,7 @@ 
format

 
(str/format "hello $0" ["yen"])
 ;; => "hello yen"
 

-
You can use str/fmt as shorter alias to str/format function.

+
You can use str/fmt as shorter alias to str/format function.  This performs the formatting at runtime, so consider using the istr or ffmt macros if you can, because they will have much lower overhead.

 
human

 
Convert a string or keyword to a human friendly string (lower case and spaces).

 
(str/human "JustNiceForReading")
@@ -372,37 +405,6 @@ 
pad

 (str/pad "1" {:length 8 :padding "0" :type :both})
 ;; => "00001000"
 

-
parse-double

-
parse-double

-
Parses string into a double:

-
(str/parse-double "1.4")
-;; => 1.4
-
-(str/parse-double nil)
-;; => NaN
-

-
parse-int

-
Parses string into a integer:

-
(str/parse-int "1.4")
-;; => 1
-
-(str/parse-int nil)
-;; => NaN
-

-
parse-number

-
General purpose function for parse number like strings to number. It works with integers and floats.

-
(str/parse-number "1.4")
-;; => 1
-
-(str/parse-number "1.4")
-;; => 1.4
-
-(str/parse-number "1")
-;; => 1
-
-(str/parse-number "")
-;; => NaN
-

 
pascal

 
Convert a string or keyword into a PascalCasedString (aka, UpperCamelCase and ClassCase).

 
(str/pascal "my name is epeli")
@@ -720,11 +722,11 @@ 
words

 

 
Run tests

 
cuerdas has targeted some parts of implementation for Clojure and ClojureScript using Reader Conditionals.

-
.Run tests in the Clojure environment.

-
$ clj -A:dev ./tools.clj test
+
Run tests in the Clojure environment:

+
$ clojure -M:dev:test
 

-
.Run tests in the ClojureScript environment.

-
$ clj -A:dev ./tools.clj test-cljs
+
Run tests in the ClojureScript environment:

+
$ clojure -M:dev ./tools.clj test <once|watch>
 

 
How to Contribute?

 
cuerdas’ source is on https://github.com/funcool/cuerdasgithub.

@@ -732,7 +734,7 @@ 
How to Contribute?Pull requests are welcome!

 
License

 
cuerdas is licensed under BSD (2-Clause) license:

-
Copyright (c) 2015-2016 Andrey Antukh <niwi@niwi.nz>
+
Copyright (c) 2015-Now Andrey Antukh <niwi@niwi.nz>
 
 All rights reserved.