md4c
1.0.0
MD4C는 "C에 대한 Markdown"을 나타냅니다. 이것이 바로이 프로젝트에 관한 것입니다.
요컨대, Markdown 은이 README.md 파일에 기록 된 Markup 언어입니다.
다음 자료는 익숙하지 않은 경우 더 자세히 설명 할 수 있습니다.
MD4C는 다음과 같은 기능을 갖춘 C의 Markdown Parser 구현입니다.
준수 : 일반적으로 MD4C는 최신 버전의 CommonMark 사양을 준수하는 것을 목표로합니다. 현재 우리는 CommonMark 0.31을 완전히 준수하고 있습니다.
확장 : MD4C는 일반적으로 요청되고 허용되는 확장을 지원합니다. 아래를 참조하십시오.
성능 : MD4C는 매우 빠릅니다.
소형 : MD4C 파서는 하나의 소스 파일과 하나의 헤더 파일로 구현됩니다. 표준 C 라이브러리 외에는 의존성이 없습니다.
임베딩 : MD4C 파서는 다른 프로젝트에서 재사용하기 쉽고 API는 매우 간단합니다. 실제로 하나의 기능 만 있습니다. md_parse() .
푸시 모델 : MD4C는 전체 문서를 구문 분석하고 응용 프로그램에서 제공 한 몇 가지 콜백 기능을 호출하여 모든 블록의 시작/종료, 모든 스팬의 시작/끝 및 텍스트 내용에 대해 알려줍니다.
이식성 : MD4C는 Windows 및 Posix 호환 OS에서 빌드 및 작동합니다. (플랫폼이 힙 메모리 관리를 포함하여 C 표준 라이브러리를 제공하는 한 대부분의 다른 플랫폼에서도 실행하는 것이 간단해야합니다.)
인코딩 : MD4C 기본적으로 입력 문서의 UTF-8 인코딩을 기대합니다. 그러나 ascii-only 컨트롤 문자 (즉, 모든 유니 코드 별 코드를 비활성화하기 위해) 또는 (Windows에서) UTF-16 (예 : 일반적으로 "유니 코드"라고하는 Windows)을 예상하기 위해 컴파일 할 수 있습니다. 아래의 자세한 내용을 참조하십시오.
허용 라이센스 : MD4C는 MIT 라이센스에 따라 제공됩니다.
Markdown 문서를 구문 분석 해야하는 경우 md4c.h 포함하고 MD4C 라이브러리 ( -lmd4c )에 대한 링크를 포함해야합니다. 또는 Parser가 단일 C 소스 파일에서만 구현되므로 Code Base에 직접 md4c.[hc] 추가하십시오.
제공된 기능은 md_parse() 입니다. Markdown 구문의 텍스트와 여러 콜백 함수에 대한 포인터를 제공하는 구조에 대한 포인터가 필요합니다.
md_parse() 입력을 처리하므로 콜백을 호출합니다 (마크 다운 블록 또는 스팬을 입력하거나 남겨 두는 경우 문서의 텍스트 내용을 출력 할 때) 응용 프로그램이 다른 형식으로 변환하거나 화면으로 렌더링 할 수 있습니다.
마크 다운을 HTML로 변환 해야하는 경우 md4c-html.h 포함하고 MD4C-HTML 라이브러리 ( -lmd4c-html )에 대한 링크; 또는 소스 md4c.[hc] , md4c-html.[hc] entity.[hc] 코드베이스에 추가하십시오.
마크 다운 입력을 변환하려면 md_html() 함수를 호출하십시오. 마크 다운 입력이 필요하고 제공된 콜백 함수를 호출합니다. 콜백에는 HTML 출력 덩어리가 공급됩니다. 일반적인 콜백 구현은 청크를 버퍼에 추가하거나 파일에 씁니다.
기본 동작은 CommonMark 사양에 의해 정의 된 Markdown 구문 만 인식하는 것입니다.
그러나 적절한 플래그를 사용하면 동작을 조정하여 일부 확장을 가능하게 할 수 있습니다.
플래그 MD_FLAG_COLLAPSEWHITESPACE 사용하면 사소한 공백이 단일 공간으로 무너집니다.
플래그 MD_FLAG_TABLES 사용하면 GitHub 스타일 테이블이 지원됩니다.
플래그 MD_FLAG_TASKLISTS 사용하면 GitHub 스타일 작업 목록이 지원됩니다.
플래그 MD_FLAG_STRIKETHROUGH 사용하면 스트라이크 스페이스가 활성화됩니다 (텍스트는 tilde marks, 예를 들어 ~foo bar~ ).
플래그 MD_FLAG_PERMISSIVEURLAUTOLINKS 허용 URL AUTOLINKS ( < 및 > 에 포함되지 않음)가 지원됩니다.
플래그 MD_FLAG_PERMISSIVEEMAILAUTOLINKS 사용하면 허용 전자 메일 자동 링크 ( < 및 > 에 포함되지 않음)가 지원됩니다.
플래그를 사용하여 MD_FLAG_PERMISSIVEWWWAUTOLINKS 허용 www AUTOLINKS (예 : www.example.com )가 지원됩니다. 그런 다음 MD4C는 http: scheme을 가정합니다.
플래그 MD_FLAG_LATEXMATHSPANS LATEX MATH SPANS ( $...$ ) 및 LATEX 디스플레이 수학 스팬 ( $$...$$ )이 지원됩니다. (HTML 렌더러는 사용자 정의 태그 <x-equation> 방정식>에서 구두를 출력한다는 점에 유의하십시오.)
플래그 MD_FLAG_WIKILINKS 사용하면 Wiki 스타일 링크 ( [[link label]] 및 [[target article|link label]] )가 지원됩니다. (HTML 렌더러는 사용자 지정 태그 <x-wikilink> 로 출력합니다.)
플래그 MD_FLAG_UNDERLINE 사용하면 밑줄 ( _ )은 일반적인 강조 또는 강조 대신 밑줄을 나타냅니다.
CommonMark의 특징은 다음 깃발로 비활성화 될 수 있습니다.
플래그 MD_FLAG_NOHTMLSPANS 또는 MD_FLAG_NOHTMLBLOCKS , 원시 인라인 HTML 또는 원시 HTML 블록이 각각 비활성화됩니다.
플래그 MD_FLAG_NOINDENTEDCODEBLOCKS 사용하면 압축 된 코드 블록이 비활성화됩니다.
CommonMark 사양은 모든 유니 코드 코드 포인트 시퀀스가 유효한 공통된 문서라고 선언합니다.
그러나 긴밀한 검사를 통해 유니 코드는 마크 다운 문서를 구문 분석 할 때 매우 구체적인 상황에서 어떤 역할을 수행합니다.
강조 및 강조 강조를 처리 할 때 단어 경계를 감지하려면 유니 코드 문자 (공백이든 구두점이든)의 일부 분류가 필요합니다.
링크 참조 레이블의 (Case-Insensitive) 일치하는 경우 해당 링크 참조 정의와 일치하는 경우 유니 코드 케이스 접이식이 사용됩니다.
HTML 엔티티 (예 : & ) 및 숫자 문자 참조 (예 # 또는 ಫ )를 유니 코드 등가물로 번역합니다.
그러나 MD4C는이 번역을 렌더러/응용 프로그램에 남겨 둡니다. 렌더러가 실제로 출력 인코딩과 이런 종류의 번역을 수행 해야하는지 여부를 실제로 알고 있어야합니다. (예를 들어, 렌더러가 HTML을 출력 할 때 엔티티가 번역되지 않은 상태로두고 작업을 웹 브라우저로 연기 할 수 있습니다.)
MD4C는 CommonMark 의이 속성에 의존하며 구현은 대량으로 인코딩하는 것입니다. 대부분의 MD4C 코드는 선택한 인코딩이 ASCII와 호환된다고 가정합니다. 즉, 128 미만의 코드 포인트는 ASCII와 동일한 숫자 값을 갖는다.
이해하지 못하는 모든 입력 MD4C는 단순히 문서 텍스트의 일부로 간주되어 렌더러의 콜백 함수로 전송되지 않았습니다.
MD4C를 이해해야하는 두 가지 상황 (단어 경계 감지 및 링크 참조 일치)은 유니 코드를 다음 전처리 매크로 (MD4C를 구축 할 때 지정된대로)에 의해 지정된대로 처리됩니다.
사전 처리기 MACRO MD4C_USE_UTF8 이 정의되면 MD4C는 Word 경계 감지 및 링크 레이블의 사례에 민감한 일치에 대해 UTF-8을 가정합니다.
이러한 매크로 중 어느 것도 명시 적으로 사용되지 않으면 이것은 기본 동작입니다.
Windows에서 전 처리기 MACRO MCRO MD4C_USE_UTF16 이 정의되면 MD4C는 char 대신 WCHAR 사용하고 해당 상황에서 UTF-16 인코딩을 가정합니다. (UTF-16은 Windows 개발자가 일반적으로 "유니 코드"라고 부르는 것과 Win32api가 일반적으로 작동하는 것입니다.)
이 매크로는 md4c.h 의 유형에도 영향을 미치기 때문에 MD4C를 구축 할 때와 md4c.h 포함 할 때 매크로를 정의해야합니다.
또한 파서 ( md4c.[hc] )에서만 지원됩니다. HTML 렌더러는이 기능을 지원하지 않으므로이 기능을 사용하려면 고유 한 사용자 정의 렌더러를 작성해야합니다.
사전 처리기 MACRO MD4C_USE_ASCII 가 정의되면 MD4C는 ASCII 입력 만 가정합니다.
이는 효과적으로 ASCII 비 공백 또는 구두점 문자가 그러한 것으로 인식되지 않을 것이며 링크 참조 매칭이 ASCII 문자 ( [a-zA-Z] )에 대해서만 대사하는 방식으로 작동한다는 것을 의미합니다.
파서의 API는 md4c.h 의 의견에 잘 기록되어 있습니다. 마찬가지로, 마크 다운 투 -HTML API는 헤더 md4c-html.h 에 설명되어있다.
좀 더 포괄적 인 문서를 제공하는 프로젝트 위키도 있습니다. 그러나 불완전하고 일부 세부 사항은 다소 구식 일 수 있습니다.
Q : MD4C는 다른 Markdown 파서와 어떻게 비교됩니까?
A : 다른 구현은 Markdown에서 HTML로 변환 할 수있는 인터페이스 뒤에 숨겨진 단일 얽힌 코드로 Markdown Parser와 HTML 생성기를 결합합니다. 다른 방식으로 입력을 처리하려면 종종 사용할 수 없습니다.
둘째, 대부분의 파서 (대부분은 아니지만 C/C ++ 언어의 범위 내에서)는 전체 마크 다운 문서의 추상 구문 트리 (AST) 표현을 구성합니다. 시간이 걸리고 메모리 발자국이 더 커집니다.
AST 건물은 필요한 한 완전히 괜찮습니다. 그렇지 않은 경우 MD4C를 사용하면 메모리 소비 측면에서 실질적으로 더 빠르고 배가 덜 될 가능성이 매우 높습니다.
마지막으로, 일부 마크 다운 파서는 순진한 방식으로 구현됩니다. 현명하게 제작 된 입력 패턴이 공급되면 2 차 (또는 더 나쁜) 파싱 시간을 나타낼 수 있습니다. MD4C가 여전히 두 번째 부분에서 구문 분석 할 수있는 것은 장시간 또는 몇 시간으로 변할 수 있습니다. 따라서, 그러한 순진한 파서가 신뢰할 수없는 소스로부터의 입력을 처리하는 데 사용될 때, 서비스 거부 공격의 가능성은 실질적인 위험이된다.
우리의 많은 노력은 어떤 종류의 미친 입력 MD4C 파서가 공급 되더라도 선형 구문 분석 시간을 제공하는 데 도움이되었습니다. (하위 선형 파싱 시간으로 이어지는 입력 패턴이 발생하면 주저하지 말고 버그로보고하십시오.)
Q : MD4C는 입력 유효성 검사를 수행합니까?
A : 아니요. 그리고 우리는 그것을 자랑스럽게 생각합니다. :-)
CommonMark 사양에 따르면 모든 유니 코드 문자 시퀀스는 유효한 마크 다운 문서라고합니다. (실제로, 이것은 항상 UTF-8 인코딩을 의미합니다.)
다시 말해, 사양에 따르면, 일부 마크 다운 구문 구성이 어떤 식 으로든 깨진 것인지 여부는 중요하지 않습니다. 그것이 깨지면, 그것은 인식되지 않으며, 파서는 그것을 구두 텍스트로보아야합니다.
MD4C는 이것을 한 단계 더 발전시킨다 : 그것은 기고 철학 (쓰레기, 쓰레기 아웃)에 따라 모든 바이트 시퀀스를 유효한 입력으로 본다. 즉, 잘못 형성된 UTF-8 바이트 시퀀스는 텍스트의 일부로 각 콜백으로 전파됩니다.
입력이 잘 형성된 UTF-8 문서인지 확인 해야하는 경우 직접 수행해야합니다. 이 작업을 수행하는 가장 쉬운 방법은 MD4C 파서에 전달하기 전에 전체 문서를 간단히 검증하는 것입니다.
MD4C는 MIT 라이센스로 덮여 있습니다. File LICENSE.md 참조하십시오.
다른 언어에 대한 포트 및 바인딩 :
CommonMark-D : MD4C ~ D 언어의 포트.
Markdown-Wasm : MD4C 포트에서 WebAssembly.
PYMD4C : MD4C에 대한 파이썬 바인딩
MD4C를 사용하는 소프트웨어 :
imgui_md : 친애하는 imgui를위한 Markdown 렌더러
Markdown Monolith 어셈블러 : 브라우저 기반 책을 구축하기위한 명령 줄 도구.
Qownnotes : Markdown Support 및 OwnCloud / NextCloud 통합을 갖춘 일반 텍스트 파일 메모장 및 Todo-List 관리자.
QT : 크로스 플랫폼 C ++ GUI 프레임 워크.
Textosaurus : QT 및 Scintilla를 기반으로 한 크로스 플랫폼 텍스트 편집기.
8 위 : 교차 플랫폼 연결 프로그래밍 언어.
