'''libxslt Tutorial'''

John Fleck

이것은 libxslt Tutorial 의 0.4 판이다.

 '''원본''': http://xmlsoft.org/XSLT/tutorial/libxslttutorial.html


Copyright (c) 2001 John Fleck

Permission is granted to copy, distribute and/or modify this document under the terms of the ''GNU Free Documentation License'', Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found [http://www.gnu.org/copyleft/fdl.html here].

'''목차'''
[[TableOfContents]]

'''요약'''
 libxslt 라이브러리를 이용한 XSLT 변환을 수행하여 XML 파일을 HTML 로 변환하는 간단한 응용프로그램을 작성하는 강좌.

== 소개 ==
확장 마크업 언어(XML: Extensible Markup Language)은 구조화된 데이터를 텍스트 형태로 교환하기 위한 World Wide Web Consortium 표준이다. 이것의 인기는 그 보편성에서 비롯한다. 어떤 컴퓨터든지 텍스트 파일을 읽을 수 있다. 적당한 도구로, 어떤 컴퓨터든지 다른 컴퓨터의 XML 파일을 읽을 수 있다.

이 도구들 가운데 가장 중요한 것의 하나로 확장 마크업 언어 변환(XSLT: Extensible Stylesheet Language Transformations)을 들 수 있다. XSLT 는 선언적인 언어로서 XML 파일을 스타일시트를 이용해 임의의 텍스트 출력으로 변환할 수 있게 해준다. libxslt 는 바로 이러한 변환을 수행 하는 함수를 제공한다.

libxslt 는 Daniel Veillard 가 그놈 프로젝트를 위해 작성한 자유 C 언어 라이브러리로 XSLT 변환을 하는 프로그램을 작성할 수 있도록 하기 위해 만들어졌다.

 '''주의''': libxslt 는 그놈 프로젝트의 후원 하에 작성되었으나, 어떤 그놈 라이브러리에도 의존하지 않는다. 이 강좌의 예제에도 사용하지 않았다.


이 강좌에서는 XML 파일을 읽어들여, 스타일시트를 적용하고 그 결과로 나온 출력을 저장하는 간단한 프로그램을 보기를 들어 설명한다. 이것은 당신이 만들고자 하는 프로그램은 아닐 것이다. xsltproc 이라는 libxslt 묶음에 포함된 프로그램이 똑같은 일을 하며 더 튼튼하고 완전한 기능을 구현하고 있다. 강좌를 위해 작성하는 프로그램은 xsltproc 을 벗겨내서 줄인 판으로 libxslt 의 기능을 보여주기 위해 고안되었다.

xsltproc 의 완전한 코드는 libxslt 배포본에 포함된 xsltproc.c 에 있다. 그것은 또한 [http://cvs.gnome.org/lxr/source/libxslt/libxslt/xsltproc.c 웹상]에서도 볼 수 있다.

참고문헌:
 * [http://www.w3.org/XML/ W3C XML page]
 * [http://www.w3.org/Style/XSL/ W3C XSL page]
 * [http://xmlsoft.org/XSLT/ libxslt]

== 기본 함수 ==
XML 파일을 변환하기 위해서는, 세 가지 함수를 수행해야 한다:
 1. 입력 파일을 구문 분석
 1. 스타일시트를 구문 분석
 1. 스타일시트 적용

=== 구문분석 준비하기 ===
입력 파일이나 스타일시트를 분석하기 전에, 엔티티를 다루기 위해 설정해야 하는 일련의 절차가 있다. 이 절차는 libxslt 고유의 것이 아니다. XML 파일을 구문분석하는 어던 libxml2 프로그램이든지 비슷한 절차를 거쳐야 할 것이다.

첫째, 일상적인 libxml 루틴을 호출해야 한다. xmlSubstituteEntitiesDefault 함수에, 정수값 1 을 넘겨서 libxml2 구문분석기에게 입력 파일을 구문분석 하는 동안 엔티티 지환을 하라고 알려줘야 한다. (0 을 넘기면 libxml2 에서 엔티티 치환이 일어나지 않는다.)

둘째, xmlLoadExtDtdDefaultValue 이 1의 값을 갖도록 해야 한다. 이것은 libxml 이 외부 엔티티 부분을 불러오도록 설정한다. 이것을 하지 않으면 입력 파일이 엔티티 일부를 외부에서 불러오도록 되어 있다면, 에러가 날 것이다.

=== 스타일시트 구문 분석 ===
스타일시트 구문 분석은 하나의 함수 호출로 이러우지며, 이 함수는 xmlChar 꼴의 인자를 하나 받는다:

{{{#!vim c
cur = xsltParseStylesheetFile((const xmlChar *)argv[i]);
}}}

여기서, 명령줄 인자로 넘겨받은 스타일시트 파일 이름을 to xmlChar 로 형변환했다. 함수가 돌려주는 값은 ''xsltStylesheetPtr'' 꼴로서 스타일시트 나무를 비롯한 스타일시트에 대한 정보를 가진 메모리상의 구조체이다. 그것을 직접 조작할 수도 있지만 이 보기에서는 그럴 필요가 없다.

=== 입력 파일 구문 분석 ===
입력 파일 구문 분석은 하나의 함수 호출로 이루어진다:

{{{#!vim c
doc = xmlParseFile(argv[i]);
}}}

함수가 돌려주는 값은 ''xmlDocPtr'' 라는 문서에 대한 정보를 담고 있는 메모리상의 구조체이다. 그것을 직접 조작할 수도 있지만 이 보기에서는 그럴 필요가 없다.

=== 스타일시트 적용하기 ===
이제 메모리에는 문서와 스타일시트를 나타내는 트리 정보가 저장되어 있고, xsltApplyStylesheet 함수를 사용해서 문서에 스타일시트를 적용한다:

{{{#!vim c
res = xsltApplyStylesheet(cur, doc, params);
}}}

이 함수는 앞의 두 함수 결과값인 ''xsltStylesheetPtr'' 와 ''xmlDocPtr'' 인자를 받는다, 세번쩨 인자 params 는 XSLT 보조 변수를 스타일시트에 넘기는 데 쓸 수 있는 `NULL`로 끝나는 이름/값 쌍의 상수 문자열 배열이다.

=== 결과 저장하기 ===
libxslt 는 결과 출력을 저장하기 위한 일련의 함수들을 포함한다. 이 보기에서는, ''xsltSaveResultToFile'' 이 쓰였으며, 결과를 `stdout` 에 저장한다:

{{{#!vim c
xsltSaveResultToFile(stdout, res, cur);
}}}

 '''주의''': libxml 에도 xmlSaveFile 과 같은 출력 함수가 있어 이럴 때 쓸 수 있다. 그러나 libxslt 저장 함수 중 하나를 쓰지 않을 경우 스타일시트에 있는 출력과 관계돤 정보들, 이를테면 어떤 인코딩을 쓸지 선언하는 것 등을 잃게 된다.

=== 보조변수 ===
XSLT 에서는 보조변수를 통해 추가적인 정보를 스타일시트에 넘길 수 있다. libxslt 는 XSLT 보조변수를 xsltApplyStylesheet에 넘긴 값들 중에 하나처럼 받는다.

강좌의 보기와 이 강좌 보기의 기반이 되는 xsltproc 에서는 넘기는 보조변수가 이름/값 쌍의 형태를 갖는다. 이 프로그램은 그것을 명령줄 인자로부터 수집하여 그것을 배열 params 에 삽입한 뒤 함수로 넘긴다. 배열의 마지막 원소는 NULL 값을 갖는다.

 '''주의''': 넘기는 인자가 노드가 아닌 문자열일 때, 반드시 escaped 야 한다. 이 강좌의 프로그램에서는, 다음과 같다: {{{tutorial]$ ./libxslt_tutorial --param rootid "'asect1'" stylesheet.xsl filename.xml}}}

=== 청소 ===
끝마친 뒤 libxslt 와 libxml 에서는 메모리 해제를 위한 함수를 제공한다.

{{{#!vim c
1: xsltFreeStylesheet(cur);
2: xmlFreeDoc(res);
3: xmlFreeDoc(doc);

4: xsltCleanupGlobals();
5: xmlCleanupParser();
}}}
 1. 스타일시트에 쓴 메모리 해제.
 1. 결과 문서에 쓴 메모리 해제.
 1. 원본 문서에 쓴 메모리 해제.
 1. libxslt 전역변수에 쓴 메모리 해제
 1. XML 구문분석기에 쓴 메모리 해제

== 코드 ==
libxslt_tutorial.c

{{{#!vim c
/*
 * libxslt_tutorial.c: demo program for the XSL Transformation 1.0 engine
 *
 * based on xsltproc.c, by Daniel.Veillard@imag.fr
 * by John Fleck 
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc.,  59 Temple Place - Suite 330, Cambridge, MA 02139, USA.
 *
 */ 

#include <string.h>
#include <libxml/xmlmemory.h>
#include <libxml/debugXML.h>

#include <libxml/HTMLtree.h>
#include <libxml/xmlIO.h>
#include <libxml/DOCBparser.h>
#include <libxml/xinclude.h>
#include <libxml/catalog.h>
#include <libxslt/xslt.h>

#include <libxslt/xsltInternals.h>
#include <libxslt/transform.h>
#include <libxslt/xsltutils.h>


extern int xmlLoadExtDtdDefaultValue;

static void usage(const char *name) {
    printf("Usage: %s [options] stylesheet file [file ...]\n", name);
    printf("      --param name value : pass a (parameter,value) pair\n");

}

int
main(int argc, char **argv) {
	int i;
	const char *params[16 + 1];
	int nbparams = 0;
	xsltStylesheetPtr cur = NULL;
	xmlDocPtr doc, res;

	if (argc <= 1) {
		usage(argv[0]);
		return(1);
	}
	

 for (i = 1; i < argc; i++) {
        if (argv[i][0] != '-')
            break;
	if ((!strcmp(argv[i], "-param")) ||
                   (!strcmp(argv[i], "--param"))) {
		i++;
		params[nbparams++] = argv[i++];
		params[nbparams++] = argv[i];
		if (nbparams >= 16) {
			fprintf(stderr, "too many params\n");
			return (1);
		}
        }  else {
            fprintf(stderr, "Unknown option %s\n", argv[i]);
            usage(argv[0]);
            return (1);
        }
    }

	params[nbparams] = NULL;
	xmlSubstituteEntitiesDefault(1);
	xmlLoadExtDtdDefaultValue = 1;
	cur = xsltParseStylesheetFile((const xmlChar *)argv[i]);
	i++;
	doc = xmlParseFile(argv[i]);
	res = xsltApplyStylesheet(cur, doc, params);
	xsltSaveResultToFile(stdout, res, cur);

	xsltFreeStylesheet(cur);
	xmlFreeDoc(res);
	xmlFreeDoc(doc);

        xsltCleanupGlobals();
        xmlCleanupParser();
	return(0);
}
}}}

== 작업일지 ==
 * 2005-03-08 [윤현호]: 위키문서로 변환 및 번역 안된 부분 번역
 * 2005-02-28 [wiki:kyagrd 안기영]: 최초 번역

----
CategoryDevelopment