RakuAST::Doc::Declarator — 선언부 앞뒤의 문서화

RakuAST::Doc::Declarator — 선언부 앞뒤의 문서화 (Leading and trailing declarator documentation)

Raku 6.e부터는 소스 코드의 선언부에 붙는 문서(선행 #| 문서와 후행 #= 문서)를 AST 객체로 다룰 수 있어요. RakuAST::Doc::Declarator는 바로 그 문서 정보를 담는 객체예요. 이 타입이 어떤 정보를 들고 있고, 어떻게 다루는지 살펴볼게요.

출처: Raku Documentation — RakuAST::Doc::Declarator

본문

RakuAST::Doc::Declarator 클래스는 RakuAST::Doc::DeclaratorTarget 롤을 수행하는 객체의 선행·후행 문서를 담아요.

class RakuAST::Doc::Declarator { }

RakuAST 기능 지원은 언어 버전 6.e+에서 사용할 수 있고, Rakudo 컴파일러 2023.02 릴리스에서 추가됐어요. 그 이전 언어 버전에서는 다음처럼 명시해야 해요.

use experimental :rakuast;

객체 들여다보기 (Object introspection)

RakuAST::Doc::Declarator 객체는 대개 Raku 소스 코드에서 선행(#|)과 후행(#=) 문서가 붙은 객체를 파싱할 때 만들어져요. 그래서 대부분의 개발자는 만들어진 객체를 어떻게 들여다보는지만 알면 충분해요.

메서드 WHEREFORE

say "attached to a $declarator.WHEREFORE.^name() object";

이 객체가 선언부 문서를 담고 있는 대상 객체를 돌려줘요.

메서드 leading

.say for $declarator.leading;

선행 선언부 문서의 줄들을 돌려줘요. 객체가 Raku 소스 코드를 파싱해서 만들어졌다면, #|가 붙은 줄마다 하나씩 나와요.

메서드 trailing

.say for $declarator.trailing;

후행 선언부 문서의 줄들을 돌려줘요. 객체가 Raku 소스 코드를 파싱해서 만들어졌다면, #=가 붙은 줄마다 하나씩 나와요.

메서드 raku

# method .gist falls back to .raku
say $declarator;  # RakuAST::Doc::Declarator.new(...

RakuAST 호출로 객체를 만들 때 필요한 문자열을 돌려줘요.

객체 만들기 (Object creation)

RakuAST::Doc::Declarator 객체를 직접 만드는 일은 드물어요. 이 문서는 프로그램적으로 RakuAST::Doc::Declarator 객체를 직접 만들고 싶어 하는 소수의 사람들을 위한 내용이에요.

메서드 new

method new(
  Str:D :$WHEREFORE,  # the associated RakuAST object
        :@leading,    # leading lines of documentation
        :@trailing    # trailing lines of documentation
)

new 메서드는 새 RakuAST::Doc::Declarator 객체를 만들 때 호출해요. 이름 인자만 받아요.

# there is no syntax for creating just a ::Declarator object

my $declarator = RakuAST::Doc::Declarator.new(
  :WHEREFORE(RakuAST::VarDeclaration::Simple.new(...)),
  :leading("line 1 leading","line 2 leading"),
  :trailing("line 1 trailing","line 2 trailing")
);

선행·후행 문서에는 왼쪽 여백의 공백이 포함될 수 있다는 점을 참고해두세요.

:WHEREFORE

이 선언부가 문서를 담고 있는 RakuAST 객체예요.

:leading

선행 문서 문자열의 줄들을 담은 Positional이에요.

:trailing

후행 문서 문자열의 줄들을 담은 Positional이에요.

객체 수정 (Object modification)

메서드 set-WHEREFORE

$declarator.set-WHEREFORE($object);

RakuAST::Doc::Declarator 객체가 문서를 담게 될 대상 객체를 설정해요.

메서드 set-leading

$declarator.set-leading;  # reset
$declarator.set-leading("foo", "bar");

선행 문서를 설정해요. 인자를 지정하지 않으면 선행 문서가 없는 상태로 초기화해요.

메서드 add-leading

$declarator.add-leading("additional");

선행 문서에 줄을 하나 추가해요.

메서드 set-trailing

$declarator.set-trailing;  # reset
$declarator.set-trailing("foo", "bar");

후행 문서를 설정해요. 인자를 지정하지 않으면 후행 문서가 없는 상태로 초기화해요.

메서드 add-trailing

$declarator.add-trailing("additional");

후행 문서에 줄을 하나 추가해요.

RakuAST::Doc::Declarator — 선언부 앞뒤의 문서화