This is an automated email from the ASF dual-hosted git repository. joshtynjala pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/royale-docs.git
commit 363639f3ea49c6ef993486d0dbb368980f4320bd Author: Josh Tynjala <joshtynj...@bowlerhat.dev> AuthorDate: Tue Sep 27 13:53:20 2022 -0700 Expand formatter and linter documentation, including asformat and aslint -config.xml files --- _data/toc.json | 6 +++++ formatter.md | 37 +++++++++++++++++++++++++----- formatter/asformat-config-file.md | 47 +++++++++++++++++++++++++++++++++++++++ formatter/formatter-options.md | 2 +- linter.md | 25 ++++++++++++++++----- linter/aslint-config-file.md | 47 +++++++++++++++++++++++++++++++++++++++ linter/linter-options.md | 2 +- 7 files changed, 152 insertions(+), 14 deletions(-) diff --git a/_data/toc.json b/_data/toc.json index dd9d34b..86c76c0 100644 --- a/_data/toc.json +++ b/_data/toc.json @@ -249,6 +249,9 @@ { "path": "formatter.md", "children": [ + { + "path": "formatter/asformat-config-file.md" + }, { "path": "formatter/formatter-options.md" } @@ -257,6 +260,9 @@ { "path": "linter.md", "children": [ + { + "path": "linter/aslint-config-file.md" + }, { "path": "linter/linter-options.md" } diff --git a/formatter.md b/formatter.md index 11ebeb4..305b1e4 100644 --- a/formatter.md +++ b/formatter.md @@ -30,14 +30,39 @@ Below are some pointers to help you get started with the Royale formatter in var ### Command line -The _bin_ directory of the Royale SDK should contain the **asformat** script that will launch the formatter. Use `asformat --help` to see the [list of available formatter options](formatter/formatter-options). +The _bin_ directory of the Royale SDK should contain the **asformat** script that will launch the formatter. Use `asformat --help` to see a [list of available formatter options](formatter/formatter-options). -### IDEs +To use the default formatting options, simply pass in the path to a _.as_ or _.mxml_ file as an argument. -Consult your IDE documentation for how to use the Royale formatter. +```sh +asformat src/com/example/MyClass.as +``` -## Formatter Options +The formatted file contents will be printed to the standard output only, and the original file will remain unmodified. To save the formatting changes, use the `--write-files` option (or its shorter `-w` alias). -The Royale formatter provides a number of command line options to customize its use. You can find the list of formatter options here: +```sh +asformat --write-files src/com/example/MyClass.as +``` -- [Formatter Options](formatter/formatter-options) +To format multiple files, pass in a directory path. The formatter will search this directory recursively for _.as_ and _.mxml_ files, and it will format every one that it finds. + +```sh +asformat --write-files src +``` + +To see which files were changed by the formatter, use the `--list-files` option (or its shorter `-l` alias). + +```sh +asformat --write-files --list-files src +``` + +### Editors and IDEs + +Consult your editor or IDE documentation to see whether it integrates the Royale formatter or not. Many development environments have the ability to run external command line programs, even if the Royale formatter is not directly integrated. + +## Formatter configuration + +The Royale formatter provides a number of command line options to customize its use. You can also save a list of the options for your project in a local configuration file that will be detected automatically. + +- [List of formatter options](formatter/formatter-options) +- [_asformat-config.xml_](formatter/asformat-config-file) diff --git a/formatter/asformat-config-file.md b/formatter/asformat-config-file.md new file mode 100644 index 0000000..eb6180c --- /dev/null +++ b/formatter/asformat-config-file.md @@ -0,0 +1,47 @@ +--- +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +layout: docpage +title: asformat-config.xml +description: Configure asformat with an external asformat-config.xml file +permalink: /formatter/asformat-config-file +--- + +# _asformat-config.xml_ + +Configure the Royale formatter for a specific project + +If the current working directory contains an _asformat-config.xml_ file, the [**asformat**](formatter/) tool will conveniently load this file automatically to configure its options. + +The root of this file is an `<asformat-config>` element. To specify a [formatter option](formatter/formatter-options), add it as a child element. + +```xml +<asformat-config> + <collapse-empty-blocks>true</collapse-empty-blocks> + <max-preserve-new-lines>3</max-preserve-new-lines> + <semicolons>ignore</semicolons> +</asformat-config> +``` + +For boolean option values, set the text inside the opening and closing tags to `true` or `false`. For numeric option values, use the digits 0-9. For string option values, enter the text as you would on the command line. + +## Disable _asformat-config.xml_ + +To disable loading the _asformat-config.xml_ file, use the `-skip-local-config-file` option. + +```sh +asformat --skip-local-config-file --write-files src/com/example/MyClass.as +``` \ No newline at end of file diff --git a/formatter/formatter-options.md b/formatter/formatter-options.md index fcd8293..118e96c 100644 --- a/formatter/formatter-options.md +++ b/formatter/formatter-options.md @@ -24,7 +24,7 @@ permalink: /formatter/formatter-options List of all available formatter options -This list may be generated by running `asformat -help advanced` in a terminal. +The [**asformat**](formatter/) tool has a number of useful configuration options. The list below is also available by running `asformat -help advanced` in a terminal. - `-collapse-empty-blocks` -- Determines if empty blocks containing no statements will be collapsed to a single line, or if the closing curly brace should still appear on a new line. - `-help` `[keyword]` `[...]` -- Displays formatter usage instructions. diff --git a/linter.md b/linter.md index bafe92f..26b60ff 100644 --- a/linter.md +++ b/linter.md @@ -30,14 +30,27 @@ Below are some pointers to help you get started with the Royale linter in variou ### Command line -The _bin_ directory of the Royale SDK should contain the **aslint** script that will launch the linter. Use `aslint --help` to see the [list of available linter options](linter/linter-options). +The _bin_ directory of the Royale SDK should contain the **aslint** script that will launch the linter. Use `aslint --help` to see a [list of available linter options](linter/linter-options). -### IDEs +To use the default linting options, simply pass in the path to a _.as_ or _.mxml_ file as an argument. -Consult your IDE documentation for how to use the Royale linter. +```sh +aslint src/com/example/MyClass.as +``` -## Linter Options +To lint multiple files, pass in a directory path. The linter will search this directory recursively for _.as_ and _.mxml_ files, and it will lint every one that it finds. -The Royale linter provides a number of command line options to customize its use. You can find the list of linter options here: +```sh +aslint src +``` -- [Linter Options](linter/linter-options) +### Editors and IDEs + +Consult your editor or IDE documentation to see whether it integrates the Royale linter or not. Many development environments have the ability to run external command line programs, even if the Royale linter is not directly integrated. + +## Linter configuration + +The Royale linter provides a number of command line options to customize its use. You can also save a list of the options for your project in a local configuration file that will be detected automatically. + +- [List of linter options](linter/linter-options) +- [_aslint-config.xml_](linter/aslint-config-file) diff --git a/linter/aslint-config-file.md b/linter/aslint-config-file.md new file mode 100644 index 0000000..fadb7cf --- /dev/null +++ b/linter/aslint-config-file.md @@ -0,0 +1,47 @@ +--- +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +layout: docpage +title: aslint-config.xml +description: Configure aslint with an external aslint-config.xml file +permalink: /linter/aslint-config-file +--- + +# _aslint-config.xml_ + +Configure the Royale linter for a specific project + +If the current working directory contains an _aslint-config.xml_ file, the [**aslint**](/linter/) tool will conveniently load this file automatically to configure its options. + +The root of this file is an `<aslint-config>` element. To specify a [linter option](linter/linter-options), add it as a child element. + +```xml +<aslint-config> + <max-params>5</max-params> + <no-dynamic-class>true</no-dynamic-class> + <line-comment-position>beside</line-comment-position> +</aslint-config> +``` + +For boolean option values, set the text inside the opening and closing tags to `true` or `false`. For numeric option values, use the digits 0-9. For string option values, enter the text as you would on the command line. + +## Disable _aslint-config.xml_ + +To disable loading the _aslint-config.xml_ file, use the `-skip-local-config-file` option. + +```sh +aslint --skip-local-config-file src/com/example/MyClass.as +``` \ No newline at end of file diff --git a/linter/linter-options.md b/linter/linter-options.md index d6f51a2..949367d 100644 --- a/linter/linter-options.md +++ b/linter/linter-options.md @@ -24,7 +24,7 @@ permalink: /linter/linter-options List of all available linter options -This list may be generated by running `aslint -help advanced` in a terminal. +The [**aslint**](linter/) tool has a number of useful configuration options. The list below is also available by running `aslint -help advanced` in a terminal. - `-class-name` -- Ensures that class names follow a certain pattern. - `-constant-name` -- Ensures that constant names follow a certain pattern.