Implements YASGuide style

README.md

@@ -33,104 +33,9 @@ julia> format_file("foo.jl")
 julia> format_text(str)
 ```
 
-[Use With Github Actions](https://github.com/julia-actions/julia-format)
-
-## Usage
-
-`JuliaFormatter` exports `format_text`, `format_file` and `format`:
-
-```julia
-format_text(
-    text::AbstractString;
-    indent = 4,
-    margin = 92,
-    always_for_in = false,
-    whitespace_typedefs::Bool = false,
-    whitespace_ops_in_indices::Bool = false,
-    remove_extra_newlines::Bool = false,
-    style::AbstractStyle = DefaultStyle(),
-)
-
-format_file(
-    file::AbstractString;
-    overwrite = true,
-    verbose = false,
-    indent = 4,
-    margin = 92,
-    always_for_in = false,
-    whitespace_typedefs::Bool = false,
-    whitespace_ops_in_indices::Bool = false,
-    remove_extra_newlines::Bool = false,
-    style::AbstractStyle = DefaultStyle(),
-)
-
-format(
-    paths...;
-    overwrite = true,
-    verbose = false,
-    indent = 4,
-    margin = 92,
-    always_for_in = false,
-    whitespace_typedefs::Bool = false,
-    whitespace_ops_in_indices::Bool = false,
-    remove_extra_newlines::Bool = false,
-    style::AbstractStyle = DefaultStyle(),
-)
-```
-
-The `text` argument to `format_text` is a string containing the code to be formatted;
-the formatted code is retuned as a new string.
-The `file` argument to `format_file` is the path of a file to be formatted.
-The `format` function is either called with a single string or a collection of strings,
-in both cases representing filesystem paths. If the path is to a `.jl` file, it formats it;
-if it's a directory, it recurses into it, looking for `.jl` files to format.
-
-### File Options
-
-If `overwrite` is `true`, the file will be reformatted in place, overwriting
-the existing file; if it is `false`, the formatted version of `foo.jl` will
-be written to `foo_fmt.jl` instead.
-
-If `verbose` is `true` details related to formatting the file will be printed
-to `stdout`.
-
-### Formatting Options
-
-`indent` - the number of spaces used for an indentation.
-
-`margin` - the maximum length of a line. Code exceeding this margin will be formatted
-across multiple lines.
-
-If `always_for_in` is true `=` is always replaced with `in` if part of a
-`for` loop condition.  For example, `for i = 1:10` will be transformed
-to `for i in 1:10`.
-
-If `whitespace_typedefs` is true, whitespace is added for type definitions.
-Make this `true` if you prefer `Union{A <: B, C}` to `Union{A<:B,C}`.
+Check out the docs for further description of the formatter and its options.
 
-If `whitespace_ops_in_indices` is true, whitespace is added for binary operations in indices.
-Make this `true` if you prefer `arr[a + b]` to `arr[a+b]`.
-Additionally, if there's a colon `:` involved, parenthesis will be added to the LHS and RHS.
-
-Example: `arr[(i1 + i2):(i3 + i4)]` instead of `arr[i1+i2:i3+i4]`.
-
-If `remove_extra_newlines` is true superflous newlines will be removed. For example:
-
-```julia
-a = 1
-
-
-
-b = 2
-```
-
-is rewritten as
-
-```julia
-a = 1
-
-b = 2
-```
+[Use With Github Actions](https://github.com/julia-actions/julia-format)
 
 ### Editor Plugins
 

docs/src/index.md

@@ -36,71 +36,81 @@ format_text(
     text::AbstractString;
     indent = 4,
     margin = 92,
+    style::AbstractStyle = DefaultStyle(),
     always_for_in = false,
     whitespace_typedefs::Bool = false,
     whitespace_ops_in_indices::Bool = false,
     remove_extra_newlines::Bool = false,
-    style::AbstractStyle = DefaultStyle(),
+    import_to_using::Bool = false,
+    pipe_to_function_call::Bool = false,
+    short_to_long_function_def::Bool = false,
+    always_use_return::Bool = false,
 )
 
 format_file(
     file::AbstractString;
     overwrite = true,
     verbose = false,
-    indent = 4,
-    margin = 92,
-    always_for_in = false,
-    whitespace_typedefs::Bool = false,
-    whitespace_ops_in_indices::Bool = false,
-    remove_extra_newlines::Bool = false,
-    style::AbstractStyle = DefaultStyle(),
+    format_options...,
 )
 
 format(
     paths...;
-    overwrite = true,
-    verbose = false,
-    indent = 4,
-    margin = 92,
-    always_for_in = false,
-    whitespace_typedefs::Bool = false,
-    whitespace_ops_in_indices::Bool = false,
-    remove_extra_newlines::Bool = false,
-    style::AbstractStyle = DefaultStyle(),
+    options...,
 )
 ```
 
 The `text` argument to `format_text` is a string containing the code to be formatted; the formatted code is retuned as a new string. The `file` argument to `format_file` is the path of a file to be formatted. The `format` function is either called with a singe string to format if it is a `.jl` file or to recuse into looking for `.jl` files if it is a directory. It can also be called with a collection of such paths to iterate over.
 
+`format` calls `format_file` which in turn calls `format_text`.
+
 ### File Options
 
-If `overwrite` is `true` the file will be reformatted in place, overwriting
-the existing file; if it is `false`, the formatted version of `foo.jl` will
-be written to `foo_fmt.jl` instead.
+#### `overwrite`
+
+The file will be reformatted in place, overwriting the existing file.
+If it is `false`, the formatted version of `foo.jl` will be written to
+`foo_fmt.jl` instead.
 
-If `verbose` is `true` details related to formatting the file will be printed
-to `stdout`.
+#### `verbose`
+
+Details related to formatting the file will be printed to `stdout`.
 
 ### Formatting Options
 
-`indent` - the number of spaces used for an indentation.
+Formats a Julia source passed in as a string, returning the formatted
+code as another string.
+
+#### `indent`
+
+The number of spaces used for an indentation.
+
+#### `margin`
 
-`margin` - the maximum length of a line. Code exceeding this margin will be formatted
-across multiple lines.
+The maximum length of a line. Code exceeding this margin will
+be formatted across multiple lines.
 
-If `always_for_in` is true `=` is always replaced with `in` if part of a
-`for` loop condition.  For example, `for i = 1:10` will be transformed
-to `for i in 1:10`.
+#### `always_for_in`
 
-If `whitespace_typedefs` is true, whitespace is added for type definitions.
-Make this `true` if you prefer `Union{A <: B, C}` to `Union{A<:B,C}`.
+If true `=` is always replaced with `in` if part of a `for` loop condition.
+For example, `for i = 1:10` will be transformed to `for i in 1:10`.
+
+#### `whitespace_typedefs`
+
+If true, whitespace is added for type definitions.  Make this `true`
+if you prefer `Union{A <: B, C}` to `Union{A<:B,C}`.
+
+#### `whitespace_ops_in_indices`
+
+If true, whitespace is added for binary operations in indices. Make this
+`true` if you prefer `arr[a + b]` to `arr[a+b]`. Additionally, if there's
+a colon `:` involved, parenthesis will be added to the LHS and RHS.
 
-If `whitespace_ops_in_indices` is true, whitespace is added for binary operations
-in indices. Make this `true` if you prefer `arr[a + b]` to `arr[a+b]`. Additionally,
-if there's a colon `:` involved, parenthesis will be added to the LHS and RHS.
 Example: `arr[(i1 + i2):(i3 + i4)]` instead of `arr[i1+i2:i3+i4]`.
 
-If `remove_extra_newlines` is true superflous newlines will be removed. For example:
+#### `remove_extra_newlines`
+
+If true superflous newlines will be removed. For example:
 
 ```julia
 a = 1
@@ -117,3 +127,67 @@ a = 1
 
 b = 2
 ```
+
+#### `import_to_using`
+
+If true `import` expressions are rewritten to `using` expressions
+in the following cases:
+
+```julia
+import A
+
+import A, B, C
+```
+
+is rewritten to:
+
+```julia
+using A: A
+
+using A: A
+using B: B
+using C: C
+```
+
+#### `pipe_to_function_call`
+
+If true `f |> x` is rewritten to `f(x)`.
+
+#### `short_to_long_function_def`
+
+Transforms a _short_ function definition
+
+```julia
+f(arg1, arg2) = body
+```
+
+to a _long_ function definition
+
+```julia
+function f(arg2, arg2)
+    body
+end
+```
+
+#### `always_use_return`
+
+If true `return` will be prepended to the last expression where
+applicable in function definitions, macro definitions, and do blocks.
+
+Example:
+
+```julia
+function foo()
+    expr1
+    expr2
+end
+```
+
+to
+
+```julia
+function foo()
+    expr1
+    return expr2
+end
+```

docs/src/transforms.md

@@ -80,3 +80,28 @@ foo(x::T) where {T} = ...
 ```
 
 See [this issue](https://github.com/domluna/JuliaFormatter.jl/issues/53) for more details.
+
+## Annotate unannotated type fields with `Any`
+
+```julia
+struct Foo
+    field
+end
+
+->
+
+struct Foo
+    field::Any
+end
+```
+
+## Move `@` in macro calls to the final identifier
+
+
+```julia
+@Module.macro
+
+->
+
+Module.@macro
+```

docs/src/yas_style.md

@@ -0,0 +1,71 @@
+# YAS Style
+
+Formatting style based on [YASGuide](https://github.com/jrevels/YASGuide) and https://github.com/domluna/JuliaFormatter.jl/issues/198.
+
+Recommended options for confirming with the above guide are:
+
+- `always_for_in` = true
+- `whitespace_ops_in_indices` = true
+- `whitespace_typedefs` = false
+- `remove_extra_newlines` = true
+- `import_to_using` = true
+- `pipe_to_function_call` = true
+- `short_to_long_function_def` = true
+- `always_use_return` = true
+
+## Usage
+
+```julia
+format("file.jl", style=YASStyle(), ...)
+```
+
+## Differences from `DefaultStyle`
+
+There are three main differences between `YASStyle` and `DefaultStyle`. They are based
+on alignment and line break behaviors.
+
+1. Arguments are aligned to just after the start of the *opener* `[, {, (, etc`.
+
+```julia
+function_call(arg1,
+              arg2)
+```
+
+2. As you can see from the above the *closer* sticks to the final argument.
+
+3. Nesting (line breaks) only occur when the margin of the next argument exceeds
+the maximim limit.
+
+```julia
+function_call(arg1, arg2,
+              arg3)
+```
+
+`arg3` exceeded the margin limit and so it was placed on the following line.
+
+
+### Nesting `=`
+
+Unlike `DefaultStyle`, assignment operations `=` are not nested. That
+is, the following
+
+```julia
+my_function(arg1, arg2) = arg1 * arg2
+```
+
+Is not nested to
+
+
+```julia
+my_function(arg1, arg2) =
+    arg1 * arg2
+```
+
+It is highly recommended setting `short_to_long_function_def` to `true`. This option
+transforms the above to a long function definition if it exceeds the maximum margin.
+
+```julia
+function my_function(arg1, arg2)
+    arg1 * arg2
+end
+```