مستند سازی در ارلنگ

مستندسازی از آن قسمت‌هایی است که اغلب مغفول می‌ماند. ارزش مستندسازی شاید ماه ها پس از اتمام پروژه معلوم شود بخصوص وقتی که خود برنامه‌نویس از فهم کد خودش عاجز می‌ماند. کد نویسی تنها زمانی ارزشمند خواهد بود که کد ما برای برنامه نویسان دیگر، از هم تیمی‌هایمان گرفته تا مشتری های نرم افزای، قابل فهم باشد. ساده‌ترین راه برای مستند سازی استفاده از کامنت است. در ارلنگ برای نوشتن کامنت از علامت % استفاده می‌شود. کامنت‌ها در حقیقت عباراتی هستند که توسط کامپایل بنوعی نادیده گرفته می‌شوند و صرفا برای قابل فهم کردن کد نوشته می‌شوند. علامت % تمام خط جلوی خود را تبدیل به کامنت می‌کند و بنابراین اگر نیاز به نوشتن در چند خط دارید باید در ابتدا هر خط از این علامت استفاده کنید. برای نمونه کد زیر در نظر بگیرید، در این کد با استفاده از کامنت توضیحی در مورد یک تابع نوشته شده است.

-module(mydouble).
-export([double/1]).
%This function doubles its input
double(X) -> X * 2.

 

اگر بخواهیم برای یک ماژول توضیح مفصلی بنویسم و مثلا اطلاعاتی شامل نسخه، تاریخ و نام نویسنده آن را، به آن بیافزاییم و سپس خروجی را در فرمت اچ تی ام ال ببینیم کافی است از تابع edoc در استفاده کنیم. البته قبل از آن باید کامنت‌های لازم را در فایل بنویسیم که سعی کردم در کد زیر این کار را انجام دهم.

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Functions calculating triple 
%%@reference from <a href="http://erlang.blog.ir">کتابارلنگ</a>,
%% 2016
%%@copyright 2016 by Mahdi Hosseini Moghaddam
%%@version 0.1

-module(mytriple).
-export([triple/1]).
-import(mydouble,[double/1]).

%%% This function multiplies a number by 3
triple(X) -> X + double(X).

برای ایجاد مستند برای فایل فوق از فرمان زیر استفاده می‌کنیم:

17> edoc:files(["mytriple.erl"], [{dir, "doc"}]).

خروجی در یک پوشه جدید ساخته می‌شود. فایل index.html را با مرورگر خود باز کنید، روی نام تابع mytriple کلیک کنید،تصویری مشابه تصویر زیر خواهید دید:

حتما توجه شما به علامت @ در کامنتها جلب شده است. این علامت در حقیقت توضیحی است به برنامه مستندساز ارلنگ که اطلاعات ذکر شده مربوط به چه قسمتی است. اگر خواستید توضیحی برای تابع خود بنویسید که در مستند نهایی ایجاد شده بیاید کافی است از @doc استفاده کنید. علت خالی بودن توضیح تابع triple در شکل بالا عدم استفاده ما از @doc است. کافیست آن را پس از % اضافه کنیم و دوباره فرمان قبل را اجرا کنیم.

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Functions calculating triple 
%%@reference from <a href="http://erlang.blog.ir">کتاب ارلنگ</a>,
%% 2016
%%@copyright 2016 by Mahdi Hosseini Moghaddam
%%@version 0.1
-module(mytriple).
-export([triple/1]).
-import(mydouble,[double/1]).

%@doc This function multiplies a number by 3
triple(X) -> X + double(X).

تا اینجا مستند ما کامل است اما یک نکته وجود دارد، بدلیل آنکه نوع داده ها در ارلنگ بصورت پویاست به این معنی که شما نیازی ندارید نوع متغیر را در هنگام مقدار دهی مشخص کنید اطلاعات در مورد تابع triple هنوز گنگ است. برنامه‌نویسی که مستند فوق را می‌خواند نخواهد دانست که تابع ما ورودی خود را بصورت عددی می‌گیرد یا انواع دیگر. برای این منظور باید از spec- کد استفاده کرد که خیلی شبیه تعریف مجدد تابع است با این تفاوت که انواع داده‌ای را که انتظار داریم دریافت کنیم را مشخص می‌کنیم. تابع ما عدد حسابی یا اعشاری را دریافت می‌کند و خروجی آن نیز عدد حسابی یا اعشاری خواهد بود. کد زیر تغییر یافته تابع ماست. تولید مستند جدید برمبنای آن برعهده شما باشد.

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Functions calculating triple 
%%@reference from <a href="http://erlang.blog.ir">کتاب ارلنگ</a>,
%% 2016
%%@copyright 2016 by Mahdi Hosseini Moghaddam
%%@version 0.1
-module(mytriple).
-export([triple/1]).
-import(mydouble,[double/1]).

%@doc This function multiplies a number by 3
-spec(triple(number()) -> number()).
triple(X) -> X + double(X).

شما می توانید برای همه برنامه خود مستند بسازید برای اینکار از فرمان زیر استفاده کنید و خروجی را مشاهده کنید. 

15> edoc:files(["mytriple.erl", mydouble.erl"]). 

مثال‌هایی در ارلنگ - مثال چهاردهم Tax calculator

در این مثال قرار است کارکردن با عبارات شرطی نظیر if تست شود هرچند در ارلنگ در بسیاری از موارد می‌توان از آن صرفنظر کرد و با خود توابع و تطابق الگو به این کارکرد رسید. برای این مثال قرار است مبلغ و اسم ایالت پرسیده شود چنانچه نام ایالت WI بود 5.5% درصد مالیات محاسبه شده و مقدار کل برگردد و در غیر اینصورت همان مبلغ اصلی برگشت داده شود. برای چاپ خروجی از if استفاده کردم اما برای محاسبه با استفاده از تطابق الگو تمایز ایجاد کردم.  در این مثال برای نخستین بار سعی در مستند سازی کد کردم که در پست مربوطه  به آن توضیح مفصل خواهم داد.

%%@author Mahdi Hosseini Moghaddam <[e-mail]>
%%@doc Exercise 14 from "Exercises for programmers" Book
%%@reference from <a href="http://erlang.blog.ir">مثال هایی در ارلنگ</a>,
%% 2016
%%@copyright 2018 by Mahdi Hosseini Moghaddam
%%@version 0.1
-module(ex14).
-export([main/0]).
-define(WITAX, 0.055).
%@doc This is my main function, It handles the exceptions and runs the program
main() ->
	try run()
	catch
		error:_Error -> io:format(
			"Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.
%@doc This fucntion print out the result, it first calls readData function then calc_Tax to calculate the result
run() ->
	{A, State} = readData(),
	{At, Taxed} = calc_Tax(A, State),
	if
		State =="WI" ->
		io:fwrite("The subtotal is $~w~n The tax is $~w~n the total is ~.2f~n"
					,[A,Taxed,At]);
		true ->
			io:fwrite("The total is $~w~n",[At])
	end.
%@doc This function calculates the tax
calc_Tax(A,"WI") -> 
	{A * (1+?WITAX),A * ?WITAX};
calc_Tax(A,_) ->
	{A,0}.
	
%@doc This function reads the user input the returns the result, it checks for invalid input like negative numbers
readData() ->
	{ok,[A]} = io:fread(
		"What is the order amount? ","~d"),
	State = string:strip(io:get_line("What's the state? "),right,$\n),
	if
		A =< 0  -> 
			throw(negativeNumber);
		true -> ok
	end,
	{A, State}.

چند توصیه در مورد نحوه کد زنی در ارلنگ - شماره یک

موارد زیر را از کتاب برنامه نویسی ارلنگ نوشته چزارینی استخراج کرده بودم که بنظرم خیلی مفید هستند. 

1-    ماژول ها پایه های برنامه شما هستند، زمانی که ماژولی را می‌سازید سعی کنید تا جای ممکن توابع کمتری را با استفاده از export عمومی کنید. با این کار پیچیدگی کد خود را کنترل می‌کنید.

2-    ماژول های بهم وابسته نباید یک دایره بسازند، به این صورت که ماژول A به B وابسته باشد، B به C  و C به A.

3-    در یک ماژول توابع مربوط بهم را در کنار یکدیگر بنویسید.

4-    سعی نکنید کدی بنویسید که برای هر ورودی که در آینده ممکن است واردش شود راهی برای بازخورد داشته باشد. سعی نکنید بی نقص باشید. این کار خواندن کد شما را سخت می‌کند. سعی کنید تنها ورودی ها مهم را پشتیبانی کنید و بگذارید مشکلات ایجاد شده توسط ورودی ها را تابع صدا زننده اولیه حل کند.

5-    از کامنت کردن کد‌های قدیمی خودداری کنید، آنها را حذف کنید و در جای دیگری ذخیره کنید. مثلا در یک نسخه پایین تر از کد.

6-    تا جای ممکن از توپل بجای لیست استفاده کنید. سایز توپل در سیستم 32 بیتی 8 بایت بیشتر از مجموع طول اعضای داخل آن است در حالی که لیست ها به ازاء هر عضو 4 بایت فضا اشغال می‌کنند.

7-    توجه داشته باشید که اتم ها توسط آشغال جمع کن سیستم حذف نمی‌شوند و ابدی هستند.

8-    اگر نیاز دارید پیام بزرگی به تعداد زیادی پروسس بفرستید ابتدا آن را به باینری تبدیل کنید. باینری های بزرگتر از 64 بایت با استفاده از نشانگر(Pointer) ارسال می‌شوند.

9-    حتما کد رو مستند کنید.

10- حتما از سیستم نوع (Type system) اختیاری ارلنگ استفاده کنید و با استفاده از Dyalizer قبل از کامپایل کردن صحت کد خود را بررسی کنید

مثال‌هایی در ارلنگ - مثال سیزدهم Determining Compound Interest

این مثال عینا شبیه مثال قبل است با این تفاوت که فرمول محاسبه مبلغ نهایی تفاوت دارد.

A = P (1 + nr )^nt

در این مثال با توجه به اینکه تنها به دو رقم اعشار در جواب نیاز دارم از .2f استفاده کردم که در تابع io:format مشهود است. 

-module(ex13).
-export([main/0]).
-compile([debug_info]).

main() ->
	try run()
	catch
		error:_Error -> io:format(
			"Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.

run() ->
	{P,R,T,N} = readItems(),
	A = calc_Investment({P,R,T,N}),
	io:fwrite(
		"$~w invested at ~w% for ~w years compounded ~w times per year is $~.2f",
		[P,R,T,N,A]).

calc_Investment({P,R,T,N}) -> 
	P*(math:pow(1+R/(N*100),N*T)).
	
readItems() ->
	{ok,[P]} = io:fread(
		"Enter the principal: ","~d"),
	{R,_} = string:to_float(string:strip(
			io:get_line("Enter the rate of interest: "), right, $\n)),
	{ok,[T]} = io:fread(
		"Enter the number of years: ","~d"),
	{ok,[N]} = io:fread(
		"What is the number of times the interest is compounded per year? ","~d"),
	if
		P =< 0 orelse R =< 0 orelse T =< 0 orelse N =< 0 -> 
			throw(negativeNumber);
		true -> ok
	end,
	{P,R,T,N}.

مثال‌های در ارلنگ - شماره دوازدهم Computing Simple Interest

این مثال محاسبه سود است. برای مثال اگر شما 1500 دلار داشته باشید و سالانه 4.3% سود بگیرید بعد از 4 سال پول شما از طریق فرمول زیر به 1758 خواهد رسید.

A = P(1 + rt)

که در آن r همان نرخ سود و t تعداد سال است و P هم همان پول اولیه شماست. در نوشتن این کد به مشکلی برخوردم و آنهم خواندن نوع اعشاری بود که در کد نحوه آن قابل مشاهده است. نکته دیگر استفاده از دیباگر ارلنگ بود. برای این کار باید debug_info را به نحوه زیر به کد اضافه کنید. کار با دیباگر ارلنگ را در زیر کد توضیح خواهد داد.

-module(ex12).
-export([main/0]).
-compile([debug_info]).

main() ->
	try run()
	catch
		error:_Error -> io:format(
			"Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.

run() ->
	{P,I,Y} = readItems(),
	Total = calc_Investment({P,I,Y}),
	io:fwrite(
		"After ~w years at ~w%, the investment will be worth $~w.",
		[Y,I,Total]).

calc_Investment({P,I,Y}) -> 
	P*(1+(I*Y/100)).
	
readItems() ->
	{ok,[P]} = io:fread(
		"Enter the principal: ","~d"),
	%{ok,[I]} = io:fread(
	%	"Enter the rate of interest: ","~f"),
	{I,_} = string:to_float(string:strip(
			io:get_line("Enter the rate of interest: "), right, $\n)),
	{ok,[Y]} = io:fread(
		"Enter the number of years: ","~d"),
	if
		P =< 0 orelse I =< 0 orelse Y =< 0 -> 
			throw(negativeNumber);
		true -> ok
	end,
	{P,I,Y}.

خوب همانطور که مشخص است ابتدا debug_info  را به کد اضافه می‌کنیم. کد را به صورت معمول کامپایل کرده و سپس دیباگر را اجرا می‌کنیم. دیباگر یک محیط گرافیکی دارد که باید ماژول خود را از قسمت Module انتخاب کنیم و سپس تابع اصلی را انتخاب کنیم. می‌توانیم خیلی ساده روی هر خط کد break بگذاریم و خط به خط پیش رویم. کامند ها را بترتیب زیر اجرا می‌کنیم:

163> c(ex12,debug_info).
{ok,ex12}
164> debugger:start().
{ok,<0.552.0>}

مثال‌هایی در ارلنگ - شماره دهم Self-Checkout

در این مثال قیمت سه آیتم از کاربر از ورودی بهمراه تعداد هر کدام را دریافت می‌کنیم و قیمت نهایی را با در نظر گرفتن 5.5% مالیات محاسبه می‌کنیم که بسیار ساده است. در این مثال قسمت دریافت اطلاعات، چاپ خروجی و محاسبات را از هم جدا کردم و ضمنا تابع محابسه بصورت بازگشتی تعریف شده است.

-module(ex10).
-export([main/0]).
-define(TAX, 0.55).

main() ->
	try run()
	catch
		error:_Error -> io:format(
			"Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.

run() ->
	L = readItems(),
	[Sub,Taxed,Total] = calc_tax(L),
	io:fwrite(
		"Subtotal: $~w~nTax: $~w~nTotal: $~w~n",
		[Sub,Taxed,Total]).

calc_tax(L) -> calc_tax(L,0).
calc_tax([],Total) ->
	[Total, Total*?TAX,(1+?TAX)*Total];
calc_tax([{P,Q}|T],Total) ->
	calc_tax(T,Total+(P*Q)).
	
readItems() ->
	{ok,[P1]} = io:fread(
		"Enter the price of item 1: ","~d"),
	{ok,[Q1]} = io:fread(
		"Enter the quantity of item 1: ","~d"),
	{ok,[P2]} = io:fread(
		"Enter the price of item 2: ","~d"),
	{ok,[Q2]} = io:fread(
		"Enter the quantity of item 2: ","~d"),
	{ok,[P3]} = io:fread(
		"Enter the price of item 3: ","~d"),
	{ok,[Q3]} = io:fread(
		"Enter the quantity of item 3: ","~d"),
	if
		P1 =< 0 orelse Q1 =< 0 orelse P2 =< 0 orelse Q2 =< 0 orelse
		P3 =< 0 orelse Q3 =< 0 -> throw(negativeNumber);
		true -> ok
	end,
	[{P1,Q1},{P2,Q2},{P3,Q3}].

مثال‌هایی در ارلنگ - شماره نهم Paint calculator

این مثال ساده در حقیقت سعی دارد شما را با عملگرهای div و rem آشنا کند که اولی تقسیم صحیح و دومی باقیمانده است. در این مثال شما باید برنامه‌ئی بنویسید که طول و عرض یک دیوار را دریافت کند( با در نظر گرفتن این نکته که برای رنگ کردن هر 350 فوت مربع یه گالون رنگ نیاز است و همچنین امکان خرید قسمتی از یک گالون نیست و باید یک گالون کامل بخریم) و بشما اعلام کند چه تعداد گالون نیاز دارید. برای مثال اگر مساحت دیوار 351 فوت مربع باشد شما به دو گالون رنگ نیاز دارید.

-module(ex9).
-export([main/0]).
-define(GALLON, 350).

main() ->
	try run()
	catch
		error:_Error -> io:format(
			"Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.

run() ->
	{Length, Width} = readDimension(),
	D = calc_gallon(Length,Width),
	io:fwrite(
		"You will need to purchase ~w gallons of paint 
		to cover ~w square feet.~n",
		[D,Length*Width]).

calc_gallon(Length, Width) ->
	D = Length * Width,
	if
		D div ?GALLON == D / ?GALLON -> D div ?GALLON;
		true -> (D div ?GALLON) + 1
	end.
	
readDimension() ->
	{ok,[First]} = io:fread(
		"What is the length of the wall in feet? ","~d"),
	{ok,[Second]} = io:fread(
		"What is the width of the wall in feet? ","~d"),
	if
		First =< 0 orelse Second =< 0 -> throw(negativeNumber);
		true -> ok
	end,
	{First,Second}.

مثال‌هایی در ارلنگ - شماره هشتم Pizza Party

برنامه‌ای بنویسد که با دریافت تعداد نفرات یک مهمانی و همچنین تعداد پیتزای موجود و البته تعداد تکه‌های هر پیتزا محاسبه کند که بهر نفر چند تکه می‌رسد. قطعات قابل ریز شدن نیستند و بنابرین سهم هر نفر عدد صحیح خواهد بود و طبیعتا در برخی موارد تعدادی  پیتزا باقی خواهد ماند. بنابراین برنامه سهم نفر و تعداد باقی مانده را خواهد نوشت. برای مثال ورودی های زیر خروجی نوشته شده را خواهد داد:

Input:

How many people? 4

How many pizzas do you have? 5

How many slices each pizza have? 7

Output:

4 People with 5 pizzas which have 7 slices per each

Each Person will have 8 slices

there are 3 leftover

کد این برنامه بشرح زیر خواهد بود:

 

-module(ex8).
-export([main/0]).

main() ->
	try run()
	catch
		error:_Error -> io:format("Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.

run() ->
	{Poeple, Pizzas, Slices} = readServing(),
	io:fwrite("~w People with ~w pizzas which have ~w slices per each~n",
		[Poeple,Pizzas,Slices]),
	io:fwrite("Each Person will have ~w slices~n there are ~w leftover~n",
		[(Pizzas*Slices) div Poeple, (Pizzas*Slices) rem Poeple]).

	
readServing() ->
	{ok,[Poeple]} = io:fread(
		"How many people? ","~d"),
	{ok,[Pizzas]} = io:fread(
		"How many pizzas do you have? ","~d"),
	{ok,[Slices]} = io:fread(
		"How many slices each pizza have? ","~d"),
	if
		Poeple =< 0 orelse Pizzas =< 0 orelse Slices =< 0 -> throw(negativeNumber);
		true -> ok
	end,
	{Poeple,Pizzas,Slices}.

مثال‌هایی در ارلنگ - مثال هفتم Area of a Rectangular Room

مثال بعدی محاسبه مساحت یک مستطیل است. واحد دریافتی از کاربر فوت هست و خروجی باید مساحت به فوت مربع و متر مربع باشد. برای تبدیل فوت مربع به متر مربع باید آن را در عدد ثابت 0.09290304 ضرب کنیم. این عدد را بصورت ماکرو در ابتدای برنامه تعریف کردم. برای استفاده از ماکرو در ارلنگ نام آن را که صرفا بخاطر یک قرارداد بصورت حروف بزرگ نوشته می‌شود را با ؟ فراخوانی می‌کنیم، کد زیر برنامه مورد نظر است:

-module(ex7).
-export([main/0]).
-define(CONRATE,0.09290304).

main() ->
	try run()
	catch
		error:_Error -> io:format("Please Enter only Numeric type~n");
		throw:negativeNumber -> io:format(
			"Please Enter only non-zero positive number~n")
	end.

run() ->
	{Length, Width} = readDimension(),
	D = calc_area(Length,Width),
	io:fwrite("You entered dimensions of ~w feet by ~w feet.~n",
		[Length,Width]),
	io:fwrite("The area is~n ~w square feet~n ~w square meters~n",
		[D, D * ?CONRATE]).

calc_area(Length, Width) ->
	Length * Width.
	
readDimension() ->
	{ok,[First]} = io:fread(
		"What is the length of the room in feet? ","~d"),
	{ok,[Second]} = io:fread(
		"What is the width of the room in feet? ","~d"),
	if
		First =< 0 orelse Second =< 0 -> throw(negativeNumber);
		true -> ok
	end,
	{First,Second}.

مثال‌هایی در ارلنگ - شماره شش Retirement Calculator

این مثال بسیار شبیه مثال قبلی است. دو عدد از ورودی در یافت می‌شود. اولی سن شماست و دومی سنی که دوست دارید بازنشسته شوید. سپس قرار است بشما بگوید که چند سال تا بازنشستگی دارید ( که خیلی ساده با کسر کردن سن کنونی از سن مورد نظر برای بازنشستگی بدست می‌آید) و چه سالی بازنشسته خواهید شد. این قسمت کمی چالشی است زیرا شما نیاز دارید با توابع خاصی سال کنونی را از سیستم استخراج کنید. تابع مورد نظر local_time است که در ماژول سیستمی calendar موجود است.  از آنجایی که ما تنها به سال کنونی نیاز داریم باقی را نادیده می گیریم. خروجی این تابع بصورت زیر است:

{{Year, Month, Day}, {Hour, Minute, Second}}
کد برنامه به شرح زیر است: 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

-module(ex6). -export([main/0]). main() -> try run() catch error:_Error -> io:format("Please Enter only Numeric type~n"); throw:negativeNumber -> io:format("Please Enter only positive number~n"); throw:outOfBound -> io:format("You are already retired~n") end. run() -> {Cur,Retire} = readInteger(), {{Year,_,_},_} = calendar:local_time(), io:fwrite("you have ~w years before retirement~n",[Retire - Cur]), io:fwrite("It's ~w so you be retired in ~w ~n",[Year,Year+(Retire - Cur)]). readInteger() -> {ok,[First]} = io:fread("What's you current age? ","~d"), {ok,[Second]} = io:fread("At what age would you like to retire? ","~d"), if First < 0 orelse Second < 0 -> throw(negativeNumber); First > Second -> throw(outOfBound); true -> ok end, {First,Second}.

خط 14 ما تنها مقدار سال را به متغیر Year انتقال می‌دهیم و باقی را دور می‌ریزیم. ضمنا سیستم برای مواقعی که سن مورد نظر برای بازنشستگی کمتر از سن کنونی شماس خطا خواهد داد.