모범 사례

이 페이지는 지금까지 발견한 구문 지침과 모범 사례를 수집하는 작업 문서입니다. 이 문서의 목표는 결국 정식 누셸 코드 스타일에 도달하는 것이지만, 현재로서는 아직 진행 중이며 변경될 수 있습니다. 토론과 기여를 환영합니다.

이러한 지침은 외부 저장소(우리 것이 아님)에서 사용할 필요는 없으며, 원하는 방식으로 변경할 수 있지만 일관성을 유지하고 규칙을 따르십시오.

모든 이스케이프 시퀀스는 지시가 없는 한 문자 그대로 해석되어서는 안 됩니다. 즉, \n과 같은 것을 리터럴 슬래시 다음에 n이 오는 것이 아니라 줄 바꿈 문자로 처리하십시오.

서식 지정

기본값

기본적으로 공백이나 탭이 허용되지 않는다고 가정하는 것이 좋지만, 다음 규칙은 허용되는 위치를 정의합니다.

기본

  • 파이프 | 기호, 명령, 하위 명령, 해당 옵션 및 인수 앞뒤에 공백 하나를 두는 것이 좋습니다.
  • 문자열의 일부가 아닌 한 여러 개의 연속된 공백을 넣지 않는 것이 좋습니다.
  • 목록 항목 사이에 쉼표를 생략하는 것이 좋습니다.

올바름:

'Hello, Nushell! This is a gradient.' | ansi gradient --fgstart '0x40c9ff' --fgend '0xe81cff'

잘못됨:

# - "|" 뒤에 너무 많은 공백: 1개 대신 2개
'Hello, Nushell! This is a gradient.' |  ansi gradient --fgstart '0x40c9ff' --fgend '0xe81cff'

한 줄 형식

한 줄 형식은 모든 명령을 한 줄에 작성하는 형식입니다.

다음과 같은 경우를 제외하고 이 형식을 기본으로 하는 것이 좋습니다.

  1. 스크립트를 작성하지 않는 경우
  2. 스크립트에서 목록 및 레코드의 경우 다음 중 하나에 해당하지 않는 한:
    1. 80자보다 긴 경우
    2. 중첩된 목록 또는 레코드를 포함하는 경우
  3. 긴 형식으로 서식을 지정해야 하는 항목을 포함하지 않는 80자 미만의 파이프라인의 경우

규칙:

  1. 매개변수:
    1. 블록 또는 클로저 매개변수 뒤에 쉼표 , 뒤에 공백 하나를 두는 것이 좋습니다.
    2. 블록 또는 클로저 매개변수 목록 끝을 나타내는 파이프 | 기호 뒤에 공백 하나를 두는 것이 좋습니다.
  2. 블록 및 클로저 본문:
    1. 명시적인 매개변수가 정의되지 않은 경우 여는 블록 또는 클로저 중괄호 { 뒤에 공백 하나를 두는 것이 좋습니다.
    2. 닫는 블록 또는 클로저 중괄호 } 앞에 공백 하나를 두는 것이 좋습니다.
  3. 레코드:
    1. 레코드 키 뒤에 : 뒤에 공백 하나를 두는 것이 좋습니다.
    2. 키 값 뒤에 쉼표 , 뒤에 공백 하나를 두는 것이 좋습니다.
  4. 목록:
    1. 목록 값 뒤에 쉼표 , 뒤에 공백 하나를 두는 것이 좋습니다.
  5. 주변 구문:
    1. 앞 기호가 동일하지 않은 경우 여는 대괄호 [, 중괄호 { 또는 괄호 ( 앞에 공백 하나를 두는 것이 좋습니다.
    2. 뒤 기호가 동일하지 않고 이 규칙을 적용하면 단일 괄호가 있는 줄이 생성되는 경우 닫는 대괄호 ], 중괄호 } 또는 괄호 ) 뒤에 공백 하나를 두는 것이 좋습니다.

올바름:

[[status]; [UP] [UP]] | all {|el| $el.status == UP }
[1 2 3 4] | reduce {|elt, acc| $elt + $acc }
[1 2 3 4] | reduce {|elt acc| $elt + $acc }
{x: 1, y: 2}
{x: 1 y: 2}
[1 2] | zip [3 4]
[]
(1 + 2) * 3

잘못됨:

# "|el|" 앞에 너무 많은 공백: 공백 허용 안 됨
[[status]; [UP] [UP]] | all { |el| $el.status == UP }

# "," 앞에 너무 많은 공백: 공백 허용 안 됨
[1 2 3 4] | reduce {|elt , acc| $elt + $acc }

# "x" 앞에 너무 많은 공백: 공백 허용 안 됨
{ x: 1, y: 2}

# "[3" 앞에 너무 많은 공백: 공백 하나 필요
[1 2] | zip  [3 4]

# "]" 앞에 너무 많은 공백: 공백 허용 안 됨
[ ]

# ")" 앞에 너무 많은 공백: 공백 허용 안 됨
(1 + 2 ) * 3

여러 줄 형식

여러 줄 형식은 모든 명령을 여러 줄에 작성하는 형식입니다. 한 줄 형식의 모든 규칙을 상속하고 약간 수정합니다.

다음과 같은 경우 이 형식을 기본으로 하는 것이 좋습니다.

  1. 스크립트를 작성하는 동안
  2. 스크립트에서 목록 및 레코드의 경우 다음 중 하나에 해당하는 동안:
    1. 80자보다 긴 경우
    2. 중첩된 목록 또는 레코드를 포함하는 경우
  3. 80자보다 긴 파이프라인의 경우

규칙:

  1. 일반:
    1. 후행 공백을 생략해야 합니다.
  2. 블록 및 클로저 본문:
    1. 각 본문 파이프라인을 별도의 줄에 두는 것이 좋습니다.
  3. 레코드:
    1. 각 레코드 키-값 쌍을 별도의 줄에 두는 것이 좋습니다.
  4. 목록:
    1. 각 목록 항목을 별도의 줄에 두는 것이 좋습니다.
  5. 주변 구문:
    1. 앞 기호가 동일하지 않고 이 규칙을 적용하면 단일 괄호가 있는 줄이 생성되는 경우 여는 대괄호 [, 중괄호 { 또는 괄호 ( 앞에 \n 하나를 두는 것이 좋습니다.
    2. 뒤 기호가 동일하지 않고 이 규칙을 적용하면 단일 괄호가 있는 줄이 생성되는 경우 닫는 대괄호 ], 중괄호 } 또는 괄호 ) 뒤에 \n 하나를 두는 것이 좋습니다.

올바름:

[[status]; [UP] [UP]] | all {|el|
    $el.status == UP
}

[1 2 3 4] | reduce {|elt, acc|
    $elt + $acc
}

{x: 1, y: 2}

[
  {name: "Teresa", age: 24},
  {name: "Thomas", age: 26}
]

let selectedProfile = (for it in ($credentials | transpose name credentials) {
    echo $it.name
})

잘못됨:

# "|el|" 앞에 너무 많은 공백: 공백 허용 안 됨(한 줄 형식과 같음)
[[status]; [UP] [UP]] | all { |el|
    # "}" 앞에 너무 적은 "\n": "\n" 하나 필요
    $el.status == UP}

# "2" 앞에 너무 많은 공백: 공백 하나 필요(한 줄 형식과 같음)
[1  2 3 4] | reduce {|elt, acc|
    $elt + $acc
}

{
   # "x" 앞에 너무 많은 "\n": 중첩된 목록이나 레코드가 없으므로 한 줄 형식 필요
   x: 1,
   y: 2
}

# "{" 앞에 너무 적은 "\n": 중첩된 레코드가 두 개 있으므로 여러 줄 형식 필요
[{name: "Teresa", age: 24},
  {name: "Thomas", age: 26}]

let selectedProfile = (
    # "foo" 앞에 너무 많은 "\n": "\n" 허용 안 됨
    for it in ($credentials | transpose name credentials) {
        echo $it.name
})

명명 규칙

약어 및 두문자어

잘 알려져 있거나 일반적으로 사용되지 않는 한 약어 및 두문자어보다 완전하고 간결한 단어를 사용하는 것이 좋습니다.

올바름:

query-user --id 123

$user.name | str downcase

잘못됨:

qry-usr --id 123

$user.name | string downcase

대소문자

명령

여러 단어로 된 명령 이름에는 케밥 케이스를 사용하는 것이 좋습니다.

올바름:

fetch-user --id 123

잘못됨:

fetch_user --id 123
fetchUser --id 123

참조: 명령 이름 지정.

하위 명령

하위 명령은 부모 명령 아래에 논리적으로 그룹화되고 공백으로 구분되는 명령입니다. 하위 명령 이름에는 케밥 케이스를 사용하는 것이 좋습니다.

올바름:

date now

date list-timezone

def "login basic-auth" [username: string password: string] {
    # ...
}

참조: 하위 명령 이름 지정.

플래그

플래그 이름에는 케밥 케이스를 사용하는 것이 좋습니다.

올바름:

def greet [name: string, --all-caps] {
    # ...
}

잘못됨:

def greet [name: string, --all_caps] {
    # ...
}

팁

플래그에 액세스하는 데 사용되는 이름은 결과 변수 이름에서 대시를 밑줄로 바꾸어 액세스합니다.

플래그를 참조하십시오.

변수 및 명령 매개변수

명령 매개변수를 포함한 변수 이름에는 스네이크 케이스를 사용하는 것이 좋습니다.

올바름:

let user_id = 123

def fetch-user [user_id: int] {
  # ...
}

잘못됨:

let user-id = 123
let userId = 123

def fetch-user [user-id: int] {
  # ...
}

환경 변수

환경 변수 이름에는 SCREAMING_SNAKE_CASE를 사용하는 것이 좋습니다.

올바름:

$env.ENVIRONMENT_CODE = "prod"

$env.APP_VERSION = "1.0.0"

잘못됨:

$env.ENVIRONMENT-CODE = "prod"

$env.app_version = "1.0.0"

사용자 지정 명령의 옵션 및 매개변수

  • 모든 위치 매개변수의 수를 2개 이하로 유지하고 나머지 입력에는 옵션을 사용하는 것이 좋습니다. mv와 같이 명령이 소스 및 대상 매개변수를 예상할 수 있다고 가정합니다. 소스 및 대상 파일 또는 디렉터리.
  • 여기에 나열된 규칙이나 기술적 제한으로 인해 사용할 수 없는 경우를 제외하고는 위치 매개변수를 사용하는 것이 좋습니다. 예를 들어, 여러 종류의 선택적 매개변수가 있지만(그러나 적어도 하나의 매개변수는 제공해야 함) 옵션을 사용합니다. 좋은 예는 전경 또는 배경 중 적어도 하나를 전달해야 하는 ansi gradient 명령입니다.
  • 긴 옵션과 짧은 옵션을 모두 제공하는 것이 좋습니다.

문서화

  • 내보낸 모든 엔터티(예: 사용자 지정 명령)와 해당 입력(예: 사용자 지정 명령 매개변수 및 옵션)에 대한 문서를 제공하는 것이 좋습니다.